dorfteich/docs/architecture/security.md

# 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: <APP_BASE_URL>`.
- 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:<issuer>"`, `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.
- **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
  `<APP_BASE_URL>/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/<id>/<version>/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 <image> -o image.tar && docker run … anchore/syft:<pinned>
scan docker-archive:/image.tar -o cyclonedx-json` respectively
  `scan dir:<workspace> -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).