create-ailk 0.23.0 → 0.25.1

package/templates/apps/api/src/middleware/auth.ts

@@ -1,864 +0,0 @@
-/**
- * Dual-mode authentication preHandler for apps/api (#587).
- *
- * Decorates `request.userId` on authenticated requests, or returns 401.
- * Two modes, evaluated in order:
- *
- *   1. Cookie path — Better Auth session cookie present and valid.
- *      Looked up directly against the `Session` table (the row Better Auth's
- *      database adapter creates on sign-in). Cookie wins when both modes are
- *      present (locked by brief decision OQ-D / spec §3 "Both present").
- *      Non-GET requests with a cookie are required to carry an Origin header
- *      that is exactly one of the configured trusted origins (#7395) — the
- *      lightweight CSRF mechanism agreed in OQ-D. Bearer-authenticated callers
- *      skip the origin check (non-browser flow).
- *
- *   2. Bearer path — Authorization: Bearer <token>. The token is sha256-hashed
- *      and matched against `ApiToken.token` (stored as hash). Revoked / expired
- *      tokens fail closed; lastUsedAt is bumped on a successful hit.
- *
- *   3. Agent path (#3591) — a bearer starting `ailk_agt_` is an agent's key
- *      (`lib/agent-store.ts`). Its digest must match an enabled `Agent` whose
- *      key-holder still holds a membership; anything else is the same 401.
- *      The request acts as the agent's person (`request.userId`) and carries
- *      `request.agent` — never `request.sessionTenant`, which stays the
- *      cookie-only signal. An agent reaches ONLY routes a tenant guard tagged
- *      (`config.tenantGuarded`, set by both guards' `onRoute` hook) and is 403
- *      everywhere else; inside them the guard clamps its role. Each agent is
- *      limited to 60 requests a minute, at most 10 of them writes (any
- *      method but GET and HEAD).
- *
- *   4. Hub-credential path (#7894) — a bearer starting `ailk_hst_` is a
- *      credential a spoke holds for a person the hub signed in on its behalf
- *      (`lib/hub-sign-in-store.ts`). It is admitted only beside the SAME
- *      spoke's key (`x-ailk-spoke-key`), only while its grant is unrevoked and
- *      unexpired, its client enabled and its person's email verified, and only
- *      on `HUB_SESSION_ROUTES` — an exact list of METHOD + registered URL
- *      pairs — the credential's own `me`, the member routes and the
- *      account-agreements pair, 26 in all (#8220, #8515, #8765); any other
- *      route is 404 (never 403, so the account area's `read()` loads
- *      "nothing for this caller"). It acts as its person
- *      (`request.userId`) and carries `request.hubSession` — never
- *      `request.sessionTenant` — and its request logger names the spoke
- *      (`spokeId`). Each person is limited, at each spoke, to 60 requests and
- *      10 writes a minute and 30 writes an hour — a fixed hour window from
- *      the bucket's first admitted write (#8220 D2, SEC-8169-4): the bucket is
- *      keyed on the VERIFIED spoke and person, never a header, and charged
- *      only after every check above passes, so a refused credential or an
- *      off-list route never gets one. The write limits refuse only writes,
- *      and a request the budget refuses is not counted.
- *
- * Every authenticated request carries `request.actor` — the person, or the
- * agent and the person it acts for — and its request/reply loggers are
- * rebound to name it, so Fastify's "request completed" line says who acted.
- * No log line carries a credential.
- *
- * Decision matrix (per spec §3):
- *   - Cookie valid                    → cookie path wins. Bearer ignored.
- *   - Cookie absent, bearer valid     → bearer path; CSRF skipped.
- *   - Both modes invalid              → 401 unauthorized.
- *   - Cookie expired + bearer valid   → 401 (no silent fallback).
- *   - Cookie absent, bearer malformed → 401 (no silent fallback).
- *   - DATABASE_URL unset              → 503 database_not_configured (#6482).
- *
- * Public routes (health, content, leads, webhooks, openapi) are NOT registered
- * with this preHandler — server.ts narrows scope via a sub-plugin.
- */
-import { createHash } from "node:crypto";
-
-import { getClock } from "@working-theory/common";
-import type { Id } from "@working-theory/ids";
-import type {
-  FastifyPluginCallback,
-  FastifyReply,
-  FastifyRequest,
-} from "fastify";
-
-import {
-  AGENT_KEY_PREFIX,
-  findAgentByKeyHash,
-  hashAgentKey,
-  touchAgentLastActive,
-  type AgentGrant,
-} from "../lib/agent-store.js";
-import {
-  findAuthorizationByCredentialHash,
-  HUB_SESSION_PREFIX,
-} from "../lib/hub-sign-in-store.js";
-import { prisma } from "../lib/prisma.js";
-import { findSpokeByKeyHash, hashSpokeKey } from "../lib/spoke-store.js";
-
-/**
- * Better Auth's default cookie names. Both are tried in order so a deployment
- * running over HTTP locally and HTTPS in production reads the same code path.
- */
-const COOKIE_NAMES = [
-  "better-auth.session_token",
-  "__Secure-better-auth.session_token",
-] as const;
-
-const UNAUTHORIZED = { error: "unauthorized" } as const;
-const DATABASE_NOT_CONFIGURED = { error: "database_not_configured" } as const;
-const NOT_FOUND = {
-  ok: false,
-  error: { code: "not_found", message: "Not found" },
-} as const;
-const SPOKE_KEY_HEADER = "x-ailk-spoke-key";
-const FORBIDDEN = {
-  ok: false,
-  error: { code: "forbidden", message: "Forbidden" },
-} as const;
-/**
- * How stale `Agent.lastActiveAt` may be before an admitted request writes it
- * again: the column is "active within the last minute", not a request log,
- * so a busy agent costs one UPDATE a minute rather than one per request.
- */
-const AGENT_ACTIVITY_WRITE_INTERVAL_MS = 60_000;
-
-const RATE_LIMITED = {
-  ok: false,
-  error: { code: "rate_limited", message: "Too many requests" },
-} as const;
-
-declare module "fastify" {
-  interface FastifyRequest {
-    userId?: Id<"user">;
-    sessionTenant?: SessionTenant;
-    /** Set ONLY on the agent path (#3591 D4). */
-    agent?: AgentGrant;
-    /** Who made the request — set on every authenticated request (#3591 D9). */
-    actor?: RequestActor;
-    /**
-     * Set ONLY on the hub-credential path (#7894 D6): the spoke the credential
-     * and the request's spoke key both name, and that spoke's workspace.
-     */
-    hubSession?: HubSession;
-  }
-  interface FastifyContextConfig {
-    /**
-     * Set by both tenant guards' `onRoute` hook on every route registered
-     * after them in their scope (#3591 D6). An agent is refused on any route
-     * without it.
-     */
-    tenantGuarded?: boolean;
-  }
-}
-
-/** The spoke a hub-issued credential was admitted for (#7894 D6). */
-export type HubSession = {
-  spokeId: Id<"spoke">;
-  workspaceId: Id<"workspace">;
-};
-
-/**
- * The only routes a hub-issued credential reaches (#7894 D6, #8220 D1): an
- * EXACT list of method + registered URL, never a prefix and never computed,
- * so a route added later joins only by a reviewed edit of this list
- * (SEC-7894-3). Six groups, in this order: the credential's own `me` and
- * #7877's three member reads; #8169's eight member reads; #8170's six member
- * writes (roadmap §7.2 row order); #8438's member consents read and write;
- * #8765's account-agreements read and write; #8515's onboarding read and
- * write — 26 in all.
- * `GET /v1/consent/platform` is not admitted — it is the Admin owner's own
- * consent to Working Theory, on the hub's cookie session. Nor is the
- * anonymous `GET /v1/consent/sign-up` (#8765 D2): it takes no credential. The member profile write IS admitted — it
- * is the person's own account, which roadmap D9 saves through it. Not
- * admitted, deliberately: `GET /v1/waitlist-signups/me`,
- * `GET /v1/flow-checkouts/me`, `GET /v1/subscription/me` and
- * `POST /v1/subscription/portal-session` (they answer for the HUB's site and
- * the person's platform billing, SEC-7894-1, -2), the token routes and the
- * hub's own-account `/v1/user/*` routes, `PATCH /v1/user/profile` among them.
- */
-export const HUB_SESSION_ROUTES: readonly string[] = Object.freeze([
-  "GET /v1/hub-sign-in/me",
-  "GET /v1/member/pieces",
-  "GET /v1/member/messages",
-  "GET /v1/member/messages/:id/file",
-  "GET /v1/member/purchases",
-  "GET /v1/member/appointments",
-  "GET /v1/member/artifacts",
-  "GET /v1/member/artifacts/:pieceId/versions/:version/file",
-  "GET /v1/member/meeting-types",
-  "GET /v1/member/availability",
-  "GET /v1/member/request-form",
-  "GET /v1/member/billing",
-  "POST /v1/member/artifacts/:pieceId/review",
-  "POST /v1/member/bookings",
-  "POST /v1/member/requests",
-  "POST /v1/member/messages",
-  "PATCH /v1/member/profile",
-  "GET /v1/member/profile/contact",
-  "PATCH /v1/member/profile/contact",
-  "POST /v1/member/deletion-request",
-  // #8438 D6 — the member's own consents. `GET /v1/consent/platform` is NOT
-  // admitted: those are the Admin owner's, on the hub's own cookie session.
-  "GET /v1/member/consents",
-  "POST /v1/member/consents",
-  // #8765 D5 — the caller's account-level sign-up agreements, so a spoke's
-  // account layout reads and accepts the one grant every site shares.
-  "GET /v1/consent/account",
-  "POST /v1/consent/account",
-  // #8515 D13 — the client's onboarding read and write.
-  "GET /v1/member/onboarding",
-  "POST /v1/member/onboarding",
-]);
-
-/**
- * Who made a request (#3591 D9). A cookie session and a personal `ApiToken`
- * act as their person; an agent acts on behalf of its responsible person.
- */
-export type RequestActor =
-  | { type: "user"; userId: Id<"user"> }
-  | { type: "agent"; agentId: Id<"agent">; onBehalfOfUserId: Id<"user"> };
-
-/**
- * Active tenant context carried by a cookie session (multi-tenant module).
- * Set ONLY on the cookie path — a personal `ApiToken` carries no workspace
- * binding, and an agent carries its own (`request.agent`, #3591), so neither
- * ever sets this. Code that needs a cookie session (the billing portal, the
- * workspace switch) can rely on its presence. `sessionRowId` is the Session
- * PK, used by the workspace-switch service to update the active tenant
- * server-side.
- */
-export type SessionTenant = {
-  sessionRowId: Id<"session">;
-  activeOrganizationId: Id<"organization"> | null;
-  activeWorkspaceId: Id<"workspace"> | null;
-};
-
-/**
- * Hash an opaque bearer-token string the same way `tokens.ts` does at create
- * time. Centralised here so the lookup contract stays identical.
- */
-function hashBearer(token: string): string {
-  return createHash("sha256").update(token).digest("hex");
-}
-
-/**
- * Parse the request's Cookie header for the first Better Auth session-token
- * variant present. Returns the cookie value (decoded) or undefined.
- *
- * Cookie parsing intentionally avoids decoding `+` as space — session tokens
- * are URL-safe and don't contain `+`. Use decodeURIComponent only on the value
- * to handle the rare case Better Auth percent-encodes the token.
- */
-function readSessionCookie(request: FastifyRequest): string | undefined {
-  const raw = request.headers.cookie;
-  if (!raw) return undefined;
-  for (const part of raw.split(";")) {
-    const eq = part.indexOf("=");
-    if (eq < 0) continue;
-    const name = part.slice(0, eq).trim();
-    if (!COOKIE_NAMES.includes(name as (typeof COOKIE_NAMES)[number])) continue;
-    const value = part.slice(eq + 1).trim();
-    if (!value) continue;
-    try {
-      // Better Auth signs the cookie as <token>.<signature>; the dual-mode
-      // preHandler only needs the token portion to look up the Session row.
-      // Strip the signature if present.
-      const decoded = decodeURIComponent(value);
-      const dot = decoded.indexOf(".");
-      return dot > 0 ? decoded.slice(0, dot) : decoded;
-    } catch {
-      return undefined;
-    }
-  }
-  return undefined;
-}
-
-function readBearer(request: FastifyRequest): string | undefined {
-  const auth = request.headers.authorization;
-  if (!auth) return undefined;
-  const match = /^Bearer\s+(\S+)$/i.exec(auth);
-  return match ? match[1] : undefined;
-}
-
-/**
- * CSRF check for cookie-authenticated mutating requests (#7395).
- * Returns true if the request is safe (GET/HEAD/OPTIONS) or the Origin header
- * is exactly one of the trusted origins. False otherwise — including for any
- * write when the list is empty, in every environment.
- */
-function isOriginAllowed(
-  request: FastifyRequest,
-  trustedOrigins: readonly string[],
-): boolean {
-  const method = request.method.toUpperCase();
-  if (method === "GET" || method === "HEAD" || method === "OPTIONS")
-    return true;
-  const origin = request.headers.origin;
-  if (!origin) return false;
-  return trustedOrigins.includes(origin);
-}
-
-type SessionRow = {
-  id: string;
-  userId: string;
-  expiresAt: Date;
-  activeOrganizationId: string | null;
-  activeWorkspaceId: string | null;
-};
-
-async function resolveCookieSession(
-  cookieToken: string,
-): Promise<SessionRow | undefined> {
-  const row = await prisma.session.findUnique({
-    where: { token: cookieToken },
-    select: {
-      id: true,
-      userId: true,
-      expiresAt: true,
-      activeOrganizationId: true,
-      activeWorkspaceId: true,
-    },
-  });
-  if (!row) return undefined;
-  return row;
-}
-
-type BearerRow = {
-  userId: string;
-  expiresAt: Date | null;
-  revokedAt: Date | null;
-  id: string;
-};
-
-async function resolveBearerToken(
-  bearer: string,
-): Promise<BearerRow | undefined> {
-  const hash = hashBearer(bearer);
-  const row = await prisma.apiToken.findUnique({
-    where: { token: hash },
-    select: { id: true, userId: true, expiresAt: true, revokedAt: true },
-  });
-  return row ?? undefined;
-}
-
-/**
- * Decorate `request.actor` and rebind the request and reply loggers to name
- * it (#3591 D9). Fastify writes its "request completed" line through
- * `reply.log`, so that line carries the actor too.
- */
-function bindActor(
-  request: FastifyRequest,
-  reply: FastifyReply,
-  actor: RequestActor,
-): void {
-  request.actor = actor;
-  request.log = request.log.child(
-    actor.type === "agent"
-      ? {
-          actorType: "agent",
-          agentId: actor.agentId,
-          onBehalfOfUserId: actor.onBehalfOfUserId,
-        }
-      : { actorType: "user" },
-  );
-  reply.log = request.log;
-}
-
-// ── The per-caller limits (#3591 D4 step 5, SEC-3591-04/-14; #8220 D2) ──────
-//
-// In the handler, not `onRequest`: the shared limiter runs before any
-// identity exists, and a bucket must only ever be keyed on a VERIFIED id, so
-// an invented key or credential never gets one. The shape of
-// `routes/subscription/portal.ts`'s per-user budget. An agent and a person
-// never share a map.
-
-const AGENT_WINDOW_MS = 60_000;
-const AGENT_REQUESTS_PER_WINDOW = 60;
-const AGENT_WRITES_PER_WINDOW = 10;
-/** Cap on distinct buckets — the oldest is evicted at capacity (DEF-011's shape). */
-const MAX_AGENT_BUCKETS = 5_000;
-
-const HUB_SESSION_WINDOW_MS = 60_000;
-const HUB_SESSION_REQUESTS_PER_WINDOW = 60;
-const HUB_SESSION_WRITES_PER_WINDOW = 10;
-const HUB_SESSION_WRITE_HOUR_MS = 3_600_000;
-const HUB_SESSION_WRITES_PER_HOUR = 30;
-const MAX_HUB_SESSION_BUCKETS = 5_000;
-
-type CallerBucket = {
-  windowStartMs: number;
-  requests: number;
-  writes: number;
-  /** The hourly write window — set by the bucket's first admitted write. */
-  hourStartMs: number | null;
-  hourWrites: number;
-};
-
-type CallerLimits = {
-  windowMs: number;
-  maxBuckets: number;
-  requests: number;
-  writes: number;
-  /** An hourly write ceiling — the hub-credential path's alone. */
-  writesPerHour?: { limit: number; windowMs: number };
-  /** When true, the write limits refuse only writes; a read meets only `requests`. */
-  refuseOnlyWrites: boolean;
-  /** When true, a refused request still counts toward every limit. */
-  countRefused: boolean;
-};
-
-const AGENT_LIMITS: CallerLimits = {
-  windowMs: AGENT_WINDOW_MS,
-  maxBuckets: MAX_AGENT_BUCKETS,
-  requests: AGENT_REQUESTS_PER_WINDOW,
-  writes: AGENT_WRITES_PER_WINDOW,
-  refuseOnlyWrites: false,
-  countRefused: true,
-};
-
-const HUB_SESSION_LIMITS: CallerLimits = {
-  windowMs: HUB_SESSION_WINDOW_MS,
-  maxBuckets: MAX_HUB_SESSION_BUCKETS,
-  requests: HUB_SESSION_REQUESTS_PER_WINDOW,
-  writes: HUB_SESSION_WRITES_PER_WINDOW,
-  writesPerHour: {
-    limit: HUB_SESSION_WRITES_PER_HOUR,
-    windowMs: HUB_SESSION_WRITE_HOUR_MS,
-  },
-  refuseOnlyWrites: true,
-  countRefused: false,
-};
-
-const agentBuckets = new Map<string, CallerBucket>();
-const hubSessionBuckets = new Map<string, CallerBucket>();
-
-/** Test-only reset. Not intended for production use. */
-export function __resetAgentRateBuckets(): void {
-  agentBuckets.clear();
-}
-
-/** Test-only reset. Not intended for production use. */
-export function __resetHubSessionRateBuckets(): void {
-  hubSessionBuckets.clear();
-}
-
-function isWrite(method: string): boolean {
-  const m = method.toUpperCase();
-  return m !== "GET" && m !== "HEAD";
-}
-
-/** A bucket no window still holds — the eviction pass may drop it. */
-function isStale(
-  bucket: CallerBucket,
-  now: number,
-  limits: CallerLimits,
-): boolean {
-  if (now - bucket.windowStartMs < limits.windowMs) return false;
-  return (
-    bucket.hourStartMs === null ||
-    limits.writesPerHour === undefined ||
-    now - bucket.hourStartMs >= limits.writesPerHour.windowMs
-  );
-}
-
-/**
- * Charge one request to `key`'s bucket. `undefined` when admitted; the
- * seconds to wait — to the end of the latest window that refused, at least
- * 1 — when over budget.
- */
-function chargeCallerBucket(
-  buckets: Map<string, CallerBucket>,
-  key: string,
-  method: string,
-  now: number,
-  limits: CallerLimits,
-): number | undefined {
-  let bucket = buckets.get(key);
-  if (!bucket || now - bucket.windowStartMs >= limits.windowMs) {
-    if (!bucket && buckets.size >= limits.maxBuckets) {
-      for (const [k, b] of buckets) {
-        if (isStale(b, now, limits)) buckets.delete(k);
-      }
-      if (buckets.size >= limits.maxBuckets) {
-        const oldest = buckets.keys().next().value;
-        if (oldest !== undefined) buckets.delete(oldest);
-      }
-    }
-    // Re-insert, so Map order stays oldest-window-first for the eviction
-    // above. A new minute keeps the hour's start and count.
-    buckets.delete(key);
-    bucket = {
-      windowStartMs: now,
-      requests: 0,
-      writes: 0,
-      hourStartMs: bucket?.hourStartMs ?? null,
-      hourWrites: bucket?.hourWrites ?? 0,
-    };
-    buckets.set(key, bucket);
-  }
-  const hour = limits.writesPerHour;
-  if (
-    hour !== undefined &&
-    bucket.hourStartMs !== null &&
-    now - bucket.hourStartMs >= hour.windowMs
-  ) {
-    bucket.hourStartMs = null;
-    bucket.hourWrites = 0;
-  }
-
-  const write = isWrite(method);
-  const requests = bucket.requests + 1;
-  const writes = bucket.writes + (write ? 1 : 0);
-  const hourWrites = bucket.hourWrites + (write ? 1 : 0);
-  const minuteEnd = bucket.windowStartMs + limits.windowMs;
-  const refusedUntil: number[] = [];
-  if (requests > limits.requests) refusedUntil.push(minuteEnd);
-  if (write || !limits.refuseOnlyWrites) {
-    if (writes > limits.writes) refusedUntil.push(minuteEnd);
-    if (write && hour !== undefined && hourWrites > hour.limit) {
-      refusedUntil.push((bucket.hourStartMs ?? now) + hour.windowMs);
-    }
-  }
-
-  const refused = refusedUntil.length > 0;
-  if (!refused || limits.countRefused) {
-    bucket.requests = requests;
-    bucket.writes = writes;
-    if (write && hour !== undefined) {
-      bucket.hourWrites = hourWrites;
-      bucket.hourStartMs ??= now;
-    }
-  }
-  if (!refused) return undefined;
-  return Math.max(1, Math.ceil((Math.max(...refusedUntil) - now) / 1_000));
-}
-
-/**
- * The agent path (#3591 D4, D6). The key is never logged and never echoed:
- * every refusal is a fixed body.
- */
-async function authenticateAgent(
-  request: FastifyRequest,
-  reply: FastifyReply,
-  key: string,
-  now: number,
-): Promise<void> {
-  const row = await findAgentByKeyHash(hashAgentKey(key)).catch(() => null);
-  // Unknown, switched off, or its key-holder has left the organization (the
-  // FK set the column null) — one body for each, so none is an oracle.
-  if (!row || !row.enabled || !row.keyIssuedToMembershipId) {
-    reply.code(401).send(UNAUTHORIZED);
-    return;
-  }
-
-  // Brand assertion at the Prisma read edge (ADR-0031 rule 5): the agents
-  // table's format CHECKs guarantee these columns hold well-formed ids.
-  const agentId = row.id as Id<"agent">;
-  const personId = row.responsible.userId as Id<"user">;
-  request.userId = personId;
-  request.agent = {
-    agentId,
-    workspaceId: row.workspaceId as Id<"workspace">,
-    organizationId: row.organizationId as Id<"organization">,
-    responsibleMembershipId: row.responsible.id as Id<"membership">,
-    permissionLevel: row.permissionLevel,
-    // #7864 D3 — the one place a missing value becomes none; the tenant
-    // guards keep only the grants its person's role also holds.
-    grants: row.grants ?? [],
-  };
-  bindActor(request, reply, {
-    type: "agent",
-    agentId,
-    onBehalfOfUserId: personId,
-  });
-
-  const retryAfter = chargeCallerBucket(
-    agentBuckets,
-    agentId,
-    request.method,
-    now,
-    AGENT_LIMITS,
-  );
-  if (retryAfter !== undefined) {
-    reply.code(429).header("Retry-After", String(retryAfter)).send(RATE_LIMITED);
-    return;
-  }
-
-  // D6 — an agent reaches only routes a tenant guard runs on. Every other
-  // route in the auth scope (tokens, user data, `/me` reads, the leads union,
-  // the workspace switcher), and any route added outside a tenant scope
-  // later, is closed to it by default.
-  if (request.routeOptions.config?.tenantGuarded !== true) {
-    reply.code(403).send(FORBIDDEN);
-    return;
-  }
-
-  // Best-effort, as the token path bumps lastUsedAt: a failure never 401s.
-  // Only an admitted request writes, and only when the stamp is a minute old.
-  if (
-    !row.lastActiveAt ||
-    now - row.lastActiveAt.getTime() >= AGENT_ACTIVITY_WRITE_INTERVAL_MS
-  ) {
-    touchAgentLastActive(agentId, new Date(now)).catch(() => undefined);
-  }
-}
-
-/**
- * The hub-credential path (#7894 D6). The credential is never logged and
- * never echoed: every refusal is a fixed body. (1)-(3) failing is the one 401;
- * (4), the route not being on `HUB_SESSION_ROUTES`, is 404 with no handler run;
- * (5), the person over budget at this spoke (#8220 D2), is 429 with no
- * handler run.
- */
-async function authenticateHubSession(
-  request: FastifyRequest,
-  reply: FastifyReply,
-  credential: string,
-  now: number,
-): Promise<void> {
-  // (1) The spoke key resolves to an unrevoked spoke.
-  const rawKey = request.headers[SPOKE_KEY_HEADER];
-  const spokeKey = typeof rawKey === "string" ? rawKey.trim() : "";
-  const spoke = spokeKey
-    ? await findSpokeByKeyHash(hashSpokeKey(spokeKey)).catch(() => null)
-    : null;
-  if (!spoke || spoke.revokedAt) {
-    reply.code(401).send(UNAUTHORIZED);
-    return;
-  }
-
-  // (2) The credential's grant is live, and its client IS this spoke's.
-  // (3) Its person's email is verified (read in the same query).
-  const grant = await findAuthorizationByCredentialHash(
-    hashBearer(credential),
-  ).catch(() => null);
-  if (
-    !grant ||
-    grant.revokedAt ||
-    grant.expiresAt.getTime() <= now ||
-    !grant.client.enabled ||
-    grant.client.clientId !== spoke.id ||
-    grant.user.emailVerified !== true
-  ) {
-    reply.code(401).send(UNAUTHORIZED);
-    return;
-  }
-
-  // (4) Method and registered URL are on the list.
-  const route = `${request.method.toUpperCase()} ${request.routeOptions.url ?? ""}`;
-  if (!HUB_SESSION_ROUTES.includes(route)) {
-    reply.code(404).send(NOT_FOUND);
-    return;
-  }
-
-  // Brand assertion at the Prisma read edge (ADR-0031 rule 5), as above.
-  request.userId = grant.userId as Id<"user">;
-  request.hubSession = {
-    spokeId: spoke.id as Id<"spoke">,
-    workspaceId: spoke.workspaceId as Id<"workspace">,
-  };
-  bindActor(request, reply, { type: "user", userId: request.userId });
-  // #8220 D10 — every line the request logger writes after admission names
-  // the spoke that acted: its id, never its key or the credential. (Lines a
-  // helper writes through the module-level `logger` carry no request binding.)
-  request.log = request.log.child({ spokeId: spoke.id });
-  reply.log = request.log;
-
-  // (5) The verified (spoke, person) is within its budget.
-  const retryAfter = chargeCallerBucket(
-    hubSessionBuckets,
-    `${spoke.id}:${grant.userId}`,
-    request.method,
-    now,
-    HUB_SESSION_LIMITS,
-  );
-  if (retryAfter !== undefined) {
-    reply.code(429).header("Retry-After", String(retryAfter)).send(RATE_LIMITED);
-    return;
-  }
-}
-
-export type AuthPreHandlerOptions = {
-  /**
-   * The browser origins a cookie-authenticated write may come from — exact
-   * matches only. server.ts passes `config.TRUSTED_ORIGINS` (#7395).
-   */
-  trustedOrigins: readonly string[];
-};
-
-/**
- * The result of `resolveOptionalCookieUser` — a signed-in user, or the reason
- * there is none (#6866 D2).
- */
-export type OptionalCookieUser =
-  | { kind: "user"; userId: Id<"user"> }
-  | {
-      kind: "none";
-      reason:
-        | "no_cookie"
-        | "no_database"
-        | "unknown_session"
-        | "expired"
-        | "cross_origin"
-        | "lookup_failed";
-    };
-
-/**
- * Non-rejecting cookie resolver for routes that stay open to anonymous callers
- * but act on a signed-in user when there is one (#6866 D2 — the checkout
- * route's buyer stamp).
- *
- * Applies the cookie path's own rules — the same private cookie reader,
- * Session lookup, expiry comparison and trusted-origin check as
- * `makeAuthPreHandler` — so the two paths cannot drift. Reads the COOKIE only:
- * a bearer `ApiToken` never identifies a user here. Never writes a reply and
- * never throws; every failure is a `none` with its reason. The cookie is
- * checked first, so an anonymous call on a database-less boot is `no_cookie`.
- */
-export async function resolveOptionalCookieUser(
-  request: FastifyRequest,
-  opts: AuthPreHandlerOptions,
-): Promise<OptionalCookieUser> {
-  const cookieToken = readSessionCookie(request);
-  if (!cookieToken) return { kind: "none", reason: "no_cookie" };
-  if (!process.env.DATABASE_URL) return { kind: "none", reason: "no_database" };
-
-  let session: SessionRow | undefined;
-  try {
-    session = await resolveCookieSession(cookieToken);
-  } catch {
-    return { kind: "none", reason: "lookup_failed" };
-  }
-  if (!session) return { kind: "none", reason: "unknown_session" };
-  if (session.expiresAt.getTime() <= getClock().now()) {
-    return { kind: "none", reason: "expired" };
-  }
-  if (!isOriginAllowed(request, opts.trustedOrigins)) {
-    return { kind: "none", reason: "cross_origin" };
-  }
-  // Brand assertion at the Prisma read edge (ADR-0031 rule 5), as above.
-  return { kind: "user", userId: session.userId as Id<"user"> };
-}
-
-/**
- * The person a member read answers for (#7877 D5): the hub's own cookie
- * session or a hub-issued credential (#7894 D6) — never a personal ApiToken,
- * never an agent. `null` → the route answers 401 with `UNAUTHORIZED`.
- *
- * This is the ONE place the member reads (`services/member-area.ts`) learn
- * who is calling: a later credential kind joins them by an edit of this
- * function and nothing in `routes/member/`. An agent never gets here — the
- * member routes are not tenant-guarded, so this preHandler answers it 403.
- */
-export function memberCaller(request: FastifyRequest): Id<"user"> | null {
-  if (request.userId === undefined) return null;
-  if (request.sessionTenant !== undefined || request.hubSession !== undefined) {
-    return request.userId;
-  }
-  return null;
-}
-
-/**
- * Fastify preHandler implementing the dual-mode contract.
- *
- * Exported standalone so route-test suites can register it directly without
- * spinning up the full server module.
- */
-export function makeAuthPreHandler(opts: AuthPreHandlerOptions) {
-  const { trustedOrigins } = opts;
-  return async function authPreHandler(
-    request: FastifyRequest,
-    reply: FastifyReply,
-  ): Promise<void> {
-    // A database-less dev boot (#6482). First, and read per request: after
-    // the lookups below, their `.catch` would already have answered 401.
-    if (!process.env.DATABASE_URL) {
-      reply.code(503).send(DATABASE_NOT_CONFIGURED);
-      return;
-    }
-
-    const now = getClock().now();
-    const cookieToken = readSessionCookie(request);
-
-    if (cookieToken) {
-      const session = await resolveCookieSession(cookieToken).catch(
-        () => undefined,
-      );
-      if (session && session.expiresAt.getTime() > now) {
-        if (!isOriginAllowed(request, trustedOrigins)) {
-          reply.code(401).send(UNAUTHORIZED);
-          return;
-        }
-        // Brand assertion at the Prisma read edge (ADR-0031 rule 5): the DB
-        // CHECK constraints guarantee these columns hold well-formed
-        // prefixed ids, so the compile-time brand is asserted once here.
-        request.userId = session.userId as Id<"user">;
-        request.sessionTenant = {
-          sessionRowId: session.id as Id<"session">,
-          activeOrganizationId: session.activeOrganizationId as Id<"organization"> | null,
-          activeWorkspaceId: session.activeWorkspaceId as Id<"workspace"> | null,
-        };
-        bindActor(request, reply, { type: "user", userId: request.userId });
-        return;
-      }
-      // Cookie present but invalid / expired → 401 (no silent bearer fallback).
-      reply.code(401).send(UNAUTHORIZED);
-      return;
-    }
-
-    const bearer = readBearer(request);
-    if (bearer?.startsWith(HUB_SESSION_PREFIX)) {
-      await authenticateHubSession(request, reply, bearer, now);
-      return;
-    }
-    if (bearer?.startsWith(AGENT_KEY_PREFIX)) {
-      await authenticateAgent(request, reply, bearer, now);
-      return;
-    }
-    if (bearer) {
-      const row = await resolveBearerToken(bearer).catch(() => undefined);
-      if (!row) {
-        reply.code(401).send(UNAUTHORIZED);
-        return;
-      }
-      if (row.revokedAt) {
-        reply.code(401).send(UNAUTHORIZED);
-        return;
-      }
-      if (row.expiresAt && row.expiresAt.getTime() <= now) {
-        reply.code(401).send(UNAUTHORIZED);
-        return;
-      }
-      request.userId = row.userId as Id<"user">;
-      // A personal token acts as its person, as before (#3591 D9).
-      bindActor(request, reply, { type: "user", userId: request.userId });
-      // Best-effort: bump lastUsedAt. Failure here MUST NOT 401 — the caller
-      // is already authenticated. Swallow the error and continue.
-      prisma.apiToken
-        .update({ where: { id: row.id }, data: { lastUsedAt: new Date(now) } })
-        .catch(() => undefined);
-      return;
-    }
-
-    // Neither present.
-    reply.code(401).send(UNAUTHORIZED);
-  };
-}
-
-/**
- * Plugin form — exposes the preHandler via Fastify's `addHook`. The
- * encapsulation override (Symbol.for("skip-override")) lets the hook
- * propagate to sibling routes registered in the SAME parent scope after the
- * plugin — matching the rate-limit.ts pattern. Without it, the hook would
- * only fire for routes registered INSIDE the plugin, which is not the calling
- * convention (server.ts registers the plugin first, then sibling routes).
- */
-export const authPreHandlerPlugin: FastifyPluginCallback<
-  AuthPreHandlerOptions
-> = (fastify, opts, done) => {
-  const handler = makeAuthPreHandler(opts);
-  fastify.decorateRequest("userId", undefined);
-  fastify.decorateRequest("sessionTenant", undefined);
-  fastify.decorateRequest("agent", undefined);
-  fastify.decorateRequest("actor", undefined);
-  fastify.decorateRequest("hubSession", undefined);
-  fastify.addHook("preHandler", handler);
-  done();
-};
-
-(authPreHandlerPlugin as FastifyPluginCallback & { [key: symbol]: boolean })[
-  Symbol.for("skip-override")
-] = true;