# Security concept Threat-driven summary; detailed mechanics live in the referenced ADRs. ## Assets & main threats Wiki content (possibly confidential per pond/label), user credentials and e-mail addresses, instance availability. Threat actors: anonymous internet (public instance with self-signup), malicious registered users, malicious or sloppy plugin authors, compromised dependencies. ## Authentication & session security (ADR 0007) - Argon2id password hashing; opaque server-side sessions in HttpOnly, Secure, SameSite=Lax cookies; CSRF protected by SameSite + origin checks on mutating requests (double-submit token for the file-download edge cases). - The origin check **fails closed** (issue #189): a cookie-carrying mutation without `Origin` and `Referer` (or with an unparsable one) is rejected with `403 csrf_origin_mismatch`. Non-browser clients authenticate with a PAT/bearer token and no cookie, which never reaches the check — the exception is structural, not a header loophole; a request that does carry the session cookie is always checked. Scripted cookie clients must send `Origin: `. - Session bounds are configurable (issue #190): an absolute lifetime (`SESSION_ABSOLUTE_HOURS`, default 7 days, never extended by activity — also the cookie `maxAge`) and an idle timeout (`SESSION_IDLE_HOURS`, default 3 days), both enforced server-side, the idle bound against `lastSeenAt`. - E-mail verification (double opt-in) before an account can create content; password reset via single-use hashed tokens; both rate-limited. - Rate limiting (DB-backed) on login, signup, reset, and API; lockout backoff on repeated failed logins per account+IP. - Feed tokens (issue #149) authenticate feed URLs via `?token=` — feed readers cannot send headers, which is why the credential lives in the URL at all. Moving it into a path segment was rejected (issue #191): a path lands in the same proxy and request logs as a query string. Instead: the instance switch `feeds.enabled` hides the whole feed surface with 404 semantics (the VS-NfD reference configuration turns feeds off), tokens are stored hashed, and the api's request log masks `?token=` values (`common/mask-token-param.ts`), so no code path logs the credential. - Self-registration can be disabled instance-wide; personal-pond quotas (editors/readers/ponds/storage) bound the blast radius of spam accounts. ## External authentication (OIDC, issue #214, ADR 0021) - **Authorization Code + PKCE**, discovery-configured, ID tokens validated against the IdP's JWKS with an explicit `RS256`/`ES256` allowlist — built on `jose` (the vetted library from #188) plus `fetch`, so no new dependency enters the supply chain for a security base function. Nothing is IdP-specific; Keycloak is the reference IdP. - **Deploy-level configuration** (who authenticates users is a platform decision, not a Site-Admin setting): `OIDC_ISSUER`, `OIDC_CLIENT_ID`, optional `OIDC_CLIENT_SECRET` (public client uses PKCE alone), `OIDC_SCOPES` (default `openid profile email`), `OIDC_PROVIDER_LABEL` (login-button text). Enabled iff issuer + client id are set; the login page discovers this via `GET /auth/methods`. - **State, nonce and the PKCE verifier** travel in a signed, HttpOnly, SameSite=Lax cookie (10 min TTL) whose key is HKDF-derived for the dedicated `oidc-state` purpose (ADR 0020) — the callback binds the IdP's `state` and the ID token's `nonce` to exactly that browser. - **Identities**: `provider = "oidc:"`, `subject` from the token. First login creates the account just-in-time (ACTIVE, mail verified — refused if the IdP does not supply a verified address). An existing local account with the same address is NEVER adopted silently (that is an account-takeover path): the login is refused with `oidc_link_required`, and the owner links explicitly via `GET /auth/oidc/link` from a logged-in session (audited as `auth.identity_linked`). - **One session mechanism**: OIDC produces the same server-side session as the password login (#190 bounds apply). IdP-initiated single logout is deliberately NOT implemented: sessions are short-bounded, and the claim-mapping revocation path (#217) plus the account-disable flag cover the leaver case — recorded in ADR 0021. - **The hard local-auth switch (issue #216)**: `AUTH_LOCAL_ENABLED=false` closes every local credential flow with 404 — login, signup, e-mail verification, resend, password forgot/reset/change — enforced centrally in the auth guard via a route marker with an enumeration fence. Deploy-level on purpose (a compromised Site Admin cannot flip it back). Sessions, logout and PAT/feed-token issuance for externally authenticated users keep working; stored password hashes remain (documented, ADR 0021). Bootstrap: complete setup before flipping. - **Trusted-proxy / mTLS path (issue #215)** — for perimeters that authenticate before the application. **The trust boundary, precisely:** the identity header (`AUTH_PROXY_HEADER`) is honoured if and only if the request's **TCP peer address** — never a forwarded header — is on `AUTH_PROXY_TRUSTED_PEERS`. Off unless both are set; nothing about the header is ever guessed. A request carrying the header from any other peer is rejected outright (403) and audited (`auth.proxy_rejected`) — that is a spoof attempt, not a misconfiguration. A session cookie riding alongside the header never escalates beyond the header identity; with the feature off the header is inert. Mapping is explicit (`AUTH_PROXY_MAP`: the value is the local username or e-mail; no just-in-time creation — the header carries no verified address). The mTLS variant (`AUTH_PROXY_MODE=mtls-dn`) expects the TLS terminator to forward the client-certificate subject DN in the same header and maps the configured attribute (`AUTH_PROXY_DN_ATTRIBUTE`, default CN). Everything upstream of the trusted peers — TLS termination, certificate validation, header hygiene (the proxy MUST strip the header from incoming traffic) — is the operator's platform responsibility. - **Keycloak verification procedure** (repeatable): run `docker run --name keycloak-local -p 8089:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0 start-dev`; via `kcadm.sh`: create realm `dorfteich`, a public client `dorfteich-web` with redirect URI `/api/v1/auth/oidc/callback`, and a user with password + verified mail. Start the api with the OIDC variables pointing at `http://localhost:8089/realms/dorfteich`, then drive `GET /auth/oidc/login` → Keycloak form login → callback with a cookie jar (curl suffices) and confirm `GET /auth/me` returns the just-in-time account. Last verified 2026-07-31 against Keycloak 26.0. ## Authorization - Single resolution algorithm (`permissions.md`) in `packages/shared`, enforced in API guards and at collab token issuance — never in the client. - Default-closed: no grant → no access. Public access is always an explicit grant. - Admin actions are audit-logged (`operations.md`). ## Content & upload security - Editor content is structured (ProseMirror schema) — no raw HTML from users. The HTML render endpoint escapes everything outside the schema; link protocols allowlisted (`https`, `http`, `mailto`). - Uploads (ADR 0011): MIME/extension allowlist, size limits, magic-byte checks, SVG sanitization or rejection, `Content-Disposition: attachment` for non-image types, no user content served same-origin as executable (`X-Content-Type-Options: nosniff`; uploads path never serves `text/html`). - App CSP (strict): `default-src 'self'`; `font-src 'self'` (ADR 0016); no third-party origins at all — the GDPR posture is "zero external requests". - **Attachment integrity (issue #199)**: every upload stores the SHA-256 of its bytes, computed from the in-memory buffer as it is written (never by re-reading disk). Every download re-hashes the stored object BEFORE the first byte leaves and fails closed on mismatch with `attachment_integrity_failure` (HTTP 500); the mismatch is recorded in the audit trail (`file.integrity_failed`). §52 VSA leaves detecting manipulation of the application's own payloads to the application — only it knows what the file should be. Operator response to a verification failure: treat the object as tampered/corrupt, restore the affected file from backup (restore runbook), then re-download to confirm; the audit entry carries both hashes for the report. Pre-existing rows are hashed by the nightly backfill (part of the orphan-file-sweep job) and served unverified only until it reaches them; unreadable files are logged and retried, never silently skipped. - The full-text index holds **no trashed content** (issue #195): trashing a page or pond clears the affected `search_vector`s, restore rebuilds them, `reindexAll` converges to the same invariant, and a one-off migration backfilled pre-existing trash. The query-side `deleted_at IS NULL` joins stay in place as the second, independent layer — a future query path that forgets them still finds no trashed vectors. (The plaintext cache row itself remains until purge; the index is the concern here because it is queryable.) ## Security response headers & CORS (issue #197) Every api response carries this header set, stamped by a hand-rolled 15-line middleware (`apps/api/src/common/security-headers.middleware.ts`) rather than `helmet` — the set is small enough to own, each value is a deliberate decision, and the api gains no transitive dependency. It is wired through the AppModule's `MiddlewareConsumer`, so the e2e harness boots the exact production middleware. | Header | Value | Why | | --------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Strict-Transport-Security` | `max-age=31536000` | One year, **no** `includeSubDomains` — the api cannot speak for sibling subdomains it does not control. Browsers ignore HSTS over plain http, so it is sent unconditionally. | | `X-Content-Type-Options` | `nosniff` | No MIME sniffing, anywhere (the uploads path relies on this too, see above). | | `Referrer-Policy` | `no-referrer` | Page paths are permission-scoped knowledge; leak them to no destination. | | `X-Frame-Options` | `SAMEORIGIN` | Deliberately **not** `DENY`: the plugin sandbox (ADR 0008) embeds `/api/v1/plugins///frame` same-origin, and the frame's CSP has no `frame-ancestors` — this header governs its framing. | | `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=(), usb=()` | Powerful browser features denied outright; nothing in the app uses them. | **CORS** is a stated decision, not an implicit default: no foreign origin is granted anything. The middleware echoes `Access-Control-Allow-Origin` (plus `Allow-Credentials: true`) only for the `APP_BASE_URL` origin itself — where browsers never consult CORS anyway, since the SPA calls the api same-origin (the dev server proxies `/api`). The echo documents the stance rather than enabling a caller; consequently there is no preflight handling (same-origin requests never preflight), and every response carries `Vary: Origin` for cache correctness. Cross-origin API access is cookie-less by design anyway (PAT/Bearer, see Public API), and non-browser clients are unaffected by CORS. Regression fence: `apps/api/src/common/security-headers.e2e.test.ts` (header set, foreign origin gets no ACAO) and the frame assertion in `plugins.e2e.db.test.ts`. TLS termination itself is the reverse proxy's job (out of scope, below). ## Plugin sandboxing (ADR 0008, operational) - Code plugins: opaque-origin iframes, no network (`connect-src 'none'`), capability-scoped postMessage API executed with the **viewer's** permissions server-side; declared capabilities surfaced to the Site Admin at install time. - Style plugins: CSS sanitized (no `@import`/external `url()`), scoped class names. - Install surface restricted to Site Admins; packages size-limited and schema-validated; the `plugins/` directory watcher only trusts the volume (host-level access implies game over anyway). ## Collaboration layer - WebSocket connect requires a short-lived (≤ 60 s) single-purpose JWT bound to user + page + mode; write revocation closes sessions via LISTEN/NOTIFY (`realtime-collaboration.md`). - Update size and document size ceilings prevent resource-exhaustion via crafted CRDT updates. ## Secrets & configuration - Secrets (DB password, token root key, SMTP credentials) live only in the stage `.env` (mode 600, never in git) and container env — not in the database (`instance_settings` stores non-secret config; the SMTP password entered in the setup wizard is written to the env-backed secret store, not to a DB row). - Token key hierarchy (ADR 0020, issue #188): `COLLAB_TOKEN_SECRET` is a ROOT key. Each token purpose uses its own HKDF-SHA-256 subkey (`deriveTokenKey` in `packages/shared/src/token-crypto.ts`): `collab` for the collaboration JWTs (signed and verified by `jose`, HS256 as an explicit allowlist), `unsubscribe` for the digest unsubscribe links. No code path signs with the root key directly, so a compromise of one purpose's tokens is not transferable to the other. - Dual-verify window: unsubscribe links minted before the key separation live in already-sent mail (90-day TTL). Verification accepts the legacy derivation (root key + purpose prefix) until **2026-11-01** (`LEGACY_VERIFY_UNTIL` in `apps/api/src/notifications/unsubscribe-token.ts`), after which the legacy path goes dead automatically. New tokens are only ever signed with the subkey. - Key rotation: rotating the root key rotates every derived subkey at once (desired: one secret to rotate) via env change plus rolling restart; procedure documented in `operations.md` runbooks. - Dependencies: lockfile-pinned; monthly update batch; images pinned to digests in Prod. ## Supply chain artefacts (issue #202) - **SBOMs**: every release run (`release.yml`) generates CycloneDX 1.6 SBOMs with a pinned `anchore/syft` container — one per released image (scanned from the freshly built image tar, OS packages included) and one for the pnpm workspace (scanned from `pnpm-lock.yaml`) — and attaches them as build artefacts named `supply-chain-vX.Y.Z` on the release's action run. Provenance: the workflow file records the exact syft version; regenerate any of them with `docker save -o image.tar && docker run … anchore/syft: scan docker-archive:/image.tar -o cyclonedx-json` respectively `scan dir: -o cyclonedx-json` at the release tag. - **License policy**: `scripts/check-licenses.mjs` holds the documented allowlist (permissive licenses, plus MPL-2.0 and CC-BY-4.0 with recorded reasoning, plus a per-package exception table for wrong upstream metadata). CI runs the gate on every pull request; the release run additionally stores the full `pnpm licenses` report next to the SBOMs. A dependency outside the allowlist fails the build — extending the policy is a reviewed change to that script, never a build fix. ## Logging - Application logs are pino JSON on stdout; `authorization` and `cookie` headers are redacted, request bodies are never logged, and feed-token query values are masked (issue #191). Log forwarding and retention are the container runtime's job (SIEM division of labour — the application side of that contract is the stable event catalogue, issue #201). - **Audit event catalogue** (issue #201): the versioned contract SIEM rules are written against — every emittable event id with trigger, severity, actor/target semantics and fields — lives in `docs/architecture/audit-events.md`. The action set is a typed union in code (an uncatalogued id cannot be emitted), audit stdout lines carry the catalogue `severity`, and a CI fence (`audit-catalogue.test.ts`) fails when document and code drift. Forwarding path: container stdout → the operator's collector; deliberately no application-side syslog client. - The persistent audit trail (`audit_log`, issue #86) records auth and admin events — who changed access or configuration, not who edited what; content activity stays log-only by design. - Audit retention (issue #196): entries are kept for `audit.retentionDays` (instance setting, default 365) and pruned by the daily `audit-retention` job; each pruning run is itself recorded as `audit.pruned` with count and cutoff, so a gap in the trail is always explainable. The read-access trail (#222–#225) is deliberately not covered by this period — it gets its own. - **Read-access trail** (issue #222, ADR 0023): reads of pages with `classification = vs_nfd` land as `read_events` rows — only classified pages, which is what keeps the purpose limitation defensible (variant A). Master switch `readTrail.enabled`, **default off** (#225): off means no event is written anywhere, including stdout, and the api announces the switch position once per boot so an eventless trail is never ambiguous. The written purpose limitation lives in `docs/vs-nfd/60-sicherheitsdokumentation.md` §7. The instrumented channels, and the emission point of each: - `page_view` — authenticated SPA state fetch (`GET /pages/:id`, the by-slug variant), the rendered read view (`/read/...`), the public JSON content route, the plugin-API content route, and an expanded embed of a classified page inside another page's rendering. - `no_js_shell` — the server-rendered `/public/:pond/:page` document. - `public_api` — `GET /api/public/v1/.../pages/:slug` and the MCP `read_page` tool (same emission point); the write echo of the public API's create/update counts as a read of the returned page. - `attachment` — `GET /media/:fileId` when the attachment's effective classification (#212 semantics) is `vs_nfd`. - `export` — per-page markdown download, one event per classified page in a pond ZIP or the account data export, and the queued `.docx`/`.odt`/`.pdf` export (recorded at enqueue — the user's action; the worker's conversion is machinery, not a second read). - `collab_join` — collab-token issuance, the api-side proxy for the collab WS join: the collab server has no permission context, and the 60 s token TTL yields per-minute granularity for live sessions. Each event carries timestamp, actor (or the documented `anon` marker), session key (`session:`/`token:`/`job:`/`anon`), page, pond, channel and the classification at read time (a later reclassification never rewrites history). **Failure is not silent**: a failed trail write aborts the read with a 500 — the deliberate contrast to the audit trail's swallow-and-log, because a lost event is a gap in evidence (ADR 0023). Deliberately NOT instrumented (recorded residual): content _fragments_ — search-result snippets, task-overview rows, backlink titles — and the Atom feeds (disabled in the VS-NfD reference configuration, #227). Digest mails carry titles only (the #231 residue). ## Privacy (GDPR) - No external requests from the browser (fonts self-hosted, no CDNs, no analytics by default). - Instance-configurable legal pages (imprint, privacy policy) are a core feature; dorfteich.online uses the operator's standard texts. - Data minimization: username, e-mail, password hash, locale — nothing else required. Account deletion: personal pond and authored ponds follow the trash/purge path; authorship on shared content is pseudonymized ("deleted user"). A data-export endpoint (own profile + own ponds as Markdown/ZIP) supports access/portability requests. - IP addresses appear only in rate-limit counters (short TTL) and reverse proxy logs (host-level rotation) — documented in the privacy-policy template. - Sent mail is not kept forever (issue #234): SENT and permanently FAILED `mail_outbox` rows are deleted after `mail.outboxRetentionDays` (default 30) by a daily job. This bounds the copy of content-adjacent data — digest bodies name page titles and actors. That digest mails carry page titles at all is a recorded, accepted residue (issue #231): there is no per-page classification marking yet to key a suppression on (that lands with ADR 0022 / M32, revisit there), and a VS-NfD reference configuration (#227) can leave SMTP unconfigured entirely. ## Out of scope (v1, explicit) - No end-to-end encryption of page content (server sees plaintext — needed for search, export, rendering). - No plugin marketplace/signing — installation is a deliberate Site Admin act of trust in the reviewed package. - No SSO in MVP (OIDC-ready per ADR 0007).