security(server): make an issued session token withdrawable

[dcondrey]

A session was an HMAC-signed bearer token with a 30-day expiry and no server-side state, so nothing could end one early. /logout deleted a cookie in the browser that asked and did nothing to a token already copied out of it. #43 and #44 made that concrete rather than theoretical: the CRM audit log can now show an admin exactly which operator session read the contact table, and there was no lever to pull.

users.session_epoch is the lever. Every token carries the epoch it was signed at, a session resolves only while the two still match, and incrementing the column ends every outstanding session for that person at once. A counter rather than a timestamp, because two revocations in the same millisecond are two revocations and a clock that steps backwards must not resurrect a session. The increment is done in SQL rather than read-then-write, so two racing revocations both land instead of the second overwriting the first with the same value — which would report success while leaving alive the sessions it was called to kill.

sessionUser() is now the only way to resolve a session, and both halves live inside it. A signature check not followed by an epoch check silently restores the old unrevocable token, at whichever route forgot, which is the failure nobody notices. verifySession stays pure and exported for exactly what it is — proof the token was issued here and has not expired, never proof the session is live — the same split consent.ts draws between verifyConsentRecord and findActiveConsent. Verified by grep over src/: verifySession has exactly one caller.

It costs no extra round trips, which is the reason this design was picked over a session table. sessionUser returns the row it read, so /api/auth/me spends the one query it always did; and siteRole is now a single joined statement instead of two sequential reads, which pays for the epoch read on every RBAC path. The join also expresses "an unowned site grants nobody anything" directly — a NULL team_id matches no membership row — so that case no longer needs its own branch, and admin.test.ts already pinned it.

Two consequences an operator will actually meet, both deliberate. A token carrying no epoch claim is rejected rather than read as epoch 0: it cannot be compared against a revocation, and an unverifiable revocation state has to mean revoked, so everyone signs in once after this deploys. And deleting a user now ends their sessions, since an account that does not exist holds none — a test that asserted the opposite was rewritten rather than worked around, because it pinned the behaviour this replaces.

POST /api/auth/logout-everywhere is the self-service control, all-or-nothing by design: with no session table there is no device list to revoke from, and the honest control is the one that ends everything. POST /api/users/:id/revoke-sessions is the same call applied to someone else, behind ADMIN_TOKEN — that is the lever the audit log points at, since the only person who could otherwise act on a suspicious entry was the operator named in it. It stays a deployment-operator action rather than a team-admin one because team admins have no user-management surface at all today, and a route reaching across to another person's sessions would be the first of its kind, arriving without any of the structure that should come with it.

/audit-file on the auth kernel found one unrelated defect worth fixing and it is in this branch. upsertUserByEmail wrote its three bootstrap rows as separate statements, so a failure between them left a user with no team, permanently — every later login takes the existing branch and returns without ever looking for a membership, so nothing repairs it while the users table still looks healthy. Now one batch(), which for D1 is one transaction, matching what deleteCompany already does for the same reason. Eight other candidates were refuted against the corpus and are listed in the audit rather than filed: the siteRole join returning an arbitrary row (memberships is keyed on (team_id, user_id)), the dropped null-team guard (already covered by admin.test.ts:95), a timing oracle on the epoch (a counter is not a secret), and CSRF on the new POST (sameSite: Lax means a cross-site POST carries no cookie).

What the risk is not: no change to ingest, to the API-key path, or to any analytics table. The migration adds one column with a default, so existing rows read as epoch 0 and existing users are simply asked to sign in again. verifySession is unchanged as a cryptographic check — the new rejection is a missing claim, not a stricter signature.

Every new assertion was mutation-checked against a committed baseline: the epoch comparison removed, the epoch claim check removed, the increment made a no-op, requireAdmin dropped from the new route, and the membership insert dropped from the bootstrap batch — each time confirming exactly its covering tests fail, then restored.

pnpm lint, pnpm typecheck, pnpm test green: 1625 tests across 176 files, up from 1615.