Skip to content
Security model

Security model

What each check is for. The behaviour below is what those files do. Rule statements live in docs/human/engineering/engineering-rules.md (SE-4, SE-6, SE-7).

Fail closed

A check that cannot decide denies.

CheckWhereWhat a failure does
Route policyinterfaces/web/src/lib/server/route-table.tsA route folder with no policy.ts has no row, and the gate answers 500 internal.error without running it. tests/integration/web/gate.test.ts checks every route folder has one.
Form-only bodiesinterfaces/web/src/hooks.server.tsA POST whose type is not application/x-www-form-urlencoded or multipart/form-data is 415. A body with no declared length, or one over the route’s maxBody, is 413. Any method other than GET, HEAD and POST, or a POST to a route with no maxBody, is 405.
Session readinfrastructure/session/store.tsA database error throws service.unavailable (503). The read does not return an anonymous session, and the cookie stays.
Rate limitshared/http/limits/rateLimit.tsconsume on a thrown error returns a deny and calls onError.
Deadlineinterfaces/web/src/hooks.server.ts withDeadlinePast the route’s deadlineMs (or REQUEST_DEADLINE_MS) the answer is 503 http.deadline. A late result is logged, never sent.
Bootstrapdeployment/postgres/init/00-bootstrap.shA missing or empty password file exits before any SQL.
Error pagesinterfaces/web/src/hooks.server.ts handleError, caughtResponseOnly a catalog code is sent, never an error’s message or cause. Anything not in the catalog as public is 500 internal.error.

The request gate

interfaces/web/server.ts is adapter-node’s custom server. It runs for every response, files and SvelteKit’s own refusals included: the host check, the security headers from shared/http, and the one log line. interfaces/web/src/hooks.server.ts then runs, in order: the route’s policy, test routes (404 unless TEST_ROUTES), the body checks, the client address and its limit, then, under the route’s deadline, the session, the member’s limit and the route, and last the group’s CSP. ADR 0054 and ADR 0056 are the record.

Each route folder holds a policy.ts beside its +page or +server file (definePolicy in interfaces/web/src/lib/server/policy.ts). It names the CSP group (app, public or static), the rate-limit policy, an optional write policy for POST, the session mode, maxBody and an optional deadline. The generated Endpoints page lists every route’s policy.

Sessions

The browser cookie is host-only. The database stores a hash.

PieceWhereWhat it is for
Cookieinterfaces/web/src/lib/server/session.tsName __Host-sid. Attributes are Path=/; Secure; HttpOnly; SameSite=Lax and Max-Age. Two cookies of that name are ignored. An unknown, malformed or expired cookie is cleared.
Storeinfrastructure/session/store.ts32 random bytes in the cookie; app.session.id_hash is their sha256. Expiry uses the database clock. A session lasts only while app.oauth_session has a row for the DID.
App gateinterfaces/web/src/lib/server/app-gate.tsopenApp: onboarding, then a confirmed email. The decisions are domains/identity’s; this file turns them into 303 redirects (/welcome, /welcome/terms, /welcome/blocked, /verify-email). A grant revoked at the PDS drops the cookie and sends the browser to sign-in.
Domain attributescripts/guards/cookie-domain.tsA Domain attribute on a cookie fails CI. The guard has no allow.

A policy’s session is one of four modes, or absent:

ModeSigned outSigned in
required303 to /login?next=<page>the member’s limit, then the app gate
writesGET and HEAD pass; a POST goes to sign-inthe member’s limit, then the app gate (any method)
onboarding303 to sign-inthe member’s limit, no app gate (welcome and verify-email are where the gate sends people)
optionalpassesthe session is read, never gated; the page is private and varies on Cookie
absentno session is read, except on an app pagethe same

The page sign-in returns to is the route’s own id when it has no parameter, or the policy’s fixed returnTo. A session route with a parameter and no returnTo is refused. It is never taken from the request.

CSRF

Every method the server accepts other than GET and HEAD is POST. SvelteKit’s own Origin check refuses a cross-site form post before the hook runs (kit 3.2.0 src/runtime/server/respond.js). It covers only the form types, so the hook refuses every other body type with 415, which puts every POST under that check. tests/integration/web/csrf-coverage.test.ts checks, on the built server, that every route that can write refuses a cross-site post and a post with no Origin, whatever the body type. The OAuth callback is the one GET that changes state; its state and nonce protect it.

Rate limits

Two layers, both in memory. In socket mode the edge’s per-client zones are the per-client layer (ADR 0042).

The process layer is a token bucket per policy (shared/http/limits/rateLimit.ts). Keys are an HMAC of the IP rate key or the DID under a salt that is not written. interfaces/web/src/lib/server/limits.ts defines the web table; a route names one of its keys, and a name that is not in it fails the endpoint check. compose.ts passes policiesFor(config.TRUSTED_PROXY_MODE):

TRUSTED_PROXY_MODETable
headerThe full policies table
socketEvery scope: "ip" entry is dropped. login gains the site-wide sign-in ceiling. Per-DID entries stay

deployment/compose.dev.yaml, deployment/compose.dev.source.yaml and deployment/compose.local.yaml set socket on web. /health is the one probe route: no host check and no rate limit, so the container probe always reaches it.

The edge layer is deployment/edge/snippets/ratelimit.caddy: caddy-ratelimit, sliding window, keyed by client address, no distributed block and no storage (ADR 0018). Dev and dev-source mount deployment/edge/dev/app.caddy, which imports app-ratelimit. Local mounts deployment/edge/local/app.caddy, which imports pds-ratelimit, as the PDS sites do.

The edge’s sign-in zone (app_signin) counts POST /login and POST /join only, per client address. Web reaches our PDS through the edge from one address, so web’s own PDS calls carry X-Unset-Web-Key, built from the pds_web_key secret. A request with exactly that value skips the per-address global and oauth_token zones and counts in web_global and web_oauth_token, one bucket keyed web. Every other PDS zone (session, identity, sign-in, reset, upload, sync, firehose and the rest) still counts web by address, and a missing or wrong key counts as any other client. The key is compared, never logged, and deployment/edge/snippets/upstream.caddy drops it before the PDS. Whoever holds a leaked key skips the per-address global and oauth_token zones and shares web’s one bucket until the key is replaced. ADR 0071 (Proposed) is the record; the numbers are on Limits.

PDS fonts

The app’s Content-Security-Policy is set per page group in interfaces/web/src/lib/server/csp.ts. On the PDS host, deployment/edge/snippets/pds-fonts.caddy serves .woff2 files from /_unset/fonts/ and answers every other /_unset/ path with 404, inside the route and before the upstream. When the response Content-Type starts with text/html, it appends font-src https://{$PDS_HOST}/_unset/fonts/ to a Content-Security-Policy the response already carries. deployment/edge/adapted-rules.ts (fontProblems, strayProblems), on the config caddy adapt prints, rejects a wider font route, a file server outside it, a response matcher outside it, and any other change to a Content-Security-Policy. The lines are on edge. ADR 0027 is the PDS frontend record.

Logging allowlist

shared/log/logger.ts writes one JSON line per call. The event must be in EVENTS; any other name is logged as log.unknown_event. The fields a line may carry are the ALLOWED set: code, route, method, status, ms, reqId, count, bytes, key, reason, phase, kind, job, attempt, version, sqlstate, island. route must be a template. reason, phase, job, kind, key and island must match a fixed word shape. Other strings pass through shared/log/scrub.ts, which replaces control characters and redacts JWTs, Bearer/Basic credentials, email addresses, DIDs, multibase keys, IP addresses and long token-shaped runs. This is SE-7.