@sigrun/sigrun 0.0.0-stage → 0.1.1

package/dist/serve.js

@@ -0,0 +1,164 @@
+/**
+ * The serve boot (Task 5): the deploy entry's composition, factored out of
+ * `src/index.ts` so the CLI's `run` command can reuse it (boot
+ * harness+server, get the bound port, shut down on demand) while
+ * `src/index.ts` — and therefore `npm start` and the cluster container
+ * command — keeps the exact same deployed behavior by calling
+ * {@link serve} once with signal handlers attached. Every behavior the
+ * deploy-entry test pins (the bootstrap, the listening line, the
+ * SIGTERM/SIGINT shutdown, the fail-loud boot) lives here.
+ *
+ * `loadConfig(process.env)` → settings bootstrap → `openHarness` →
+ * `createServer` → listen.
+ *
+ * The settings bootstrap (ruling 5 / spec §6.6): on first boot the
+ * store writes ONLY what the environment set (the env-sourced `server`
+ * fields plus `extensions`/`defaultModel` when env supplied them —
+ * defaults are never persisted), and the FINAL config re-resolves env
+ * over the (possibly just-written) file (`loadConfig(env, file)`) — env
+ * always wins, the file fills only what env leaves unset.
+ * `SIGRUN_CONFIG_DIR` stays env-only (it locates the file itself).
+ *
+ * Fail-loud is the contract (the task brief): any boot error rejects the
+ * boot promise; callers print it and exit 1 — a wedged deploy must crash,
+ * never serve a broken process.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { envServerSection, loadConfig } from "./config.js";
+import { openHarness } from "./harness/boot.js";
+import { packagesDirOf, syncPackages } from "./harness/packages.js";
+import { defaultSettingsDir, SettingsStore } from "./harness/settings.js";
+import { createServer } from "./server/index.js";
+/**
+ * Boot the harness + server composition and listen on
+ * `options.host ?? "0.0.0.0"` + `<port>` (the default is the container's
+ * address — loopback-only would be unreachable behind the Service;
+ * `loadConfig` refuses port 0, so a real port is always bound).
+ * The CLI's `run` additionally launches the TUI against the loopback URL
+ * on {@link BootedServer.port}.
+ */
+export async function serve(env, options) {
+    // 1. Env-only resolution (the pre-file behavior — fail-loud on a bad
+    //    env value before anything is written). A file-only `defaultModel`
+    //    must NOT fail here: the file has not been read yet, and step 3
+    //    re-resolves with it. The env-only `envConfig` result feeds ONLY the
+    //    bootstrap's `defaultModel` write, which is used only when env
+    //    actually supplied the model — so skip the env-only resolution
+    //    entirely when no env model is set (a file-only model otherwise
+    //    throws here, before `settings.json` is ever read).
+    const envHasModel = env.SIGRUN_DEFAULT_MODEL?.trim() !== undefined ||
+        env.SIGRUN_MODEL?.trim() !== undefined;
+    const envConfig = envHasModel ? loadConfig(env) : undefined;
+    // 2. First-boot bootstrap (ruling 5 / spec §6.6): absent settings file
+    //    → write ONLY what the environment explicitly set — the env-sourced
+    //    `server` fields (`envServerSection`) plus `extensions` and
+    //    `defaultModel` when env supplied them. Defaults are NEVER
+    //    persisted, so later releases' default changes reach existing
+    //    installs (the file records intent, not reality); a `server`
+    //    section with zero entries is omitted entirely. A present file is
+    //    never touched.
+    const envModel = env.SIGRUN_DEFAULT_MODEL?.trim() || env.SIGRUN_MODEL?.trim() || undefined;
+    const settingsStore = new SettingsStore({ dir: defaultSettingsDir() });
+    settingsStore.bootstrap(envServerSection(env), {
+        extensions: env.SIGRUN_EXTENSIONS?.trim() === undefined
+            ? undefined
+            : envConfig.extensions,
+        defaultModel: envModel === undefined
+            ? undefined
+            : `${envConfig.models.provider}/${envConfig.models.modelId}`,
+    });
+    // 3. Final resolution: env over the file over code defaults. The file
+    //    re-read picks up whatever bootstrap wrote (or what was already
+    //    there) — env still wins every field it sets.
+    const config = loadConfig(env, settingsStore.read());
+    // Boot-time package install (the pi-style packages dir): the settings
+    // file's top-level `packages` array is the INSTALL intent — install the
+    // declared specifiers into `<config-dir>/packages` and prune the
+    // undeclared BEFORE any extension loads. Fail-loud: an uninstallable
+    // declaration fails the boot here, naming the specifier. Steady state
+    // (the dir already matches) costs one manifest read, no subprocess.
+    const settingsFile = settingsStore.read();
+    const packagesDir = packagesDirOf(defaultSettingsDir());
+    const extensionResolutions = await syncPackages(settingsFile.extensions ?? [], packagesDir);
+    // The workspace directory must exist before any files endpoint or tool
+    // call touches it. The deploy manifest mounts a volume at /data; the
+    // workspace is /data/workspace. Without this, the first files request
+    // 404s forever (the directory was never created).
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(config.workspace.path, { recursive: true });
+    const opened = await openHarness(config, { extensionEntries: extensionResolutions });
+    // The contributed-bundle registry (build-and-webui Task 6): boot folded
+    // the loader's extension contributions into the name-keyed registry;
+    // the server's serve-time NAME-selector resolution reads it here.
+    const app = await createServer(opened, config, opened.webuiBundles, {
+        listenHost: options?.host ?? "0.0.0.0",
+        env,
+    });
+    const host = options?.host ?? "0.0.0.0";
+    await app.listen({ port: config.port, host });
+    // Machine-greppable: the deploy-entry test waits for this line, and an
+    // operator reading pod logs sees the bound port without guessing.
+    console.log(`sigrun listening on http://${host}:${config.port}`);
+    const shutdown = async () => {
+        const failures = [];
+        try {
+            await app.close();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await opened.eventBus.shutdownSequence(BACKGROUND_CONTEXT);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            // The interval refresh scheduler (provider plugins Task 5) stops
+            // BEFORE the harness closes. The T4 boot refresh promise is raced
+            // against a bounded join: a wedged catalog fetch must not hold the
+            // ordered shutdown (and the SSE test harness's `app.close`) — the
+            // refresh contract already treats abandon as a retained-catalog
+            // warn, never a boot failure.
+            opened.stopProviderRefresh();
+            let joined = false;
+            const join = opened.bootRefresh
+                .then(() => {
+                joined = true;
+            })
+                .catch(() => { });
+            const BOOT_REFRESH_JOIN_MS = 2_000;
+            await Promise.race([
+                join,
+                new Promise((resolve) => {
+                    const timer = setTimeout(resolve, BOOT_REFRESH_JOIN_MS);
+                    timer.unref?.();
+                }),
+            ]);
+            if (!joined) {
+                console.warn(`sigrun: boot refresh still in flight after ${BOOT_REFRESH_JOIN_MS}ms at shutdown — abandoning the join`);
+            }
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await opened.harness.close(BACKGROUND_CONTEXT);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, "sigrun shutdown failed");
+        }
+    };
+    let stopping;
+    return {
+        port: config.port,
+        shutdown,
+        shutdownOnce: () => {
+            stopping ??= shutdown();
+            return stopping;
+        },
+    };
+}

package/dist/server/auth/claim-lock.js

@@ -0,0 +1,28 @@
+/**
+ * The claim mutex (core hardening W1 Task 4, spec §5.8): ONE in-process
+ * promise chain shared by the onboarding claim route and invite
+ * redemption. Claims and redeems are serialized end-to-end — the
+ * directory's `isClaimed()` read happens INSIDE the lock, and the
+ * directory write itself is atomic (Task 2's stores) — so of two
+ * concurrent correct claims exactly one lands the first admin and the
+ * rest observe `already_claimed`.
+ *
+ * In-process by design: the directory's MutationQueue already serializes
+ * single-store writes across processes; this mutex closes the
+ * read-decide-write WINDOW (check unclaimed → add) that would otherwise
+ * let two same-process claims both pass the check.
+ */
+/** The one module-level chain; every critical section rides its tail. */
+let chain = Promise.resolve();
+/**
+ * Run `section` under the claim mutex: it starts only after the previous
+ * section settles (either way — a failed claim must not wedge the
+ * chain), and the next waiter sees this section's tail. The returned
+ * promise carries `section`'s own settlement (success or rejection) to
+ * its caller.
+ */
+export function withClaimLock(section) {
+    const run = chain.then(section, section);
+    chain = run.then(() => undefined, () => undefined);
+    return run;
+}

package/dist/server/auth/ip.js

@@ -0,0 +1,51 @@
+/**
+ * CIDR allowlist membership for peer addresses (W1 Task 3): the proxy
+ * method's trusted-proxies check. `net.BlockList` is the engine;
+ * v4-mapped v6 spellings (`::ffff:10.42.3.4`) are folded to the v4
+ * address first — a dual-stack socket reports v4 peers mapped, and the
+ * allowlist spells v4 ranges.
+ */
+import { BlockList, isIP } from "node:net";
+/**
+ * Whether `address` (a socket remote address) falls in any of `cidrs`
+ * (CIDR ranges or bare IPs). Malformed entries never match; an
+ * undefined/unparseable address never matches.
+ */
+export function ipAllowed(address, cidrs) {
+    if (address === undefined)
+        return false;
+    let candidate = address.trim();
+    if (candidate.startsWith("::ffff:") && isIP(candidate.slice(7)) === 4) {
+        candidate = candidate.slice(7);
+    }
+    const family = isIP(candidate);
+    if (family === 0)
+        return false;
+    const list = new BlockList();
+    for (const entry of cidrs) {
+        const trimmed = entry.trim();
+        if (trimmed === "")
+            continue;
+        const slash = trimmed.indexOf("/");
+        try {
+            if (slash === -1) {
+                const entryFamily = isIP(trimmed);
+                if (entryFamily === 0)
+                    continue;
+                list.addAddress(trimmed, entryFamily === 6 ? "ipv6" : "ipv4");
+            }
+            else {
+                const base = trimmed.slice(0, slash);
+                const prefix = Number(trimmed.slice(slash + 1));
+                const entryFamily = isIP(base);
+                if (entryFamily === 0 || !Number.isInteger(prefix))
+                    continue;
+                list.addSubnet(base, prefix, entryFamily === 6 ? "ipv6" : "ipv4");
+            }
+        }
+        catch {
+            // A malformed entry matches nothing (never trust everyone).
+        }
+    }
+    return list.check(candidate, family === 6 ? "ipv6" : "ipv4");
+}

package/dist/server/auth/login-limiter.js

@@ -0,0 +1,52 @@
+/**
+ * The login rate limiter (W1 Task 3, spec §5.4): per-source-IP failure
+ * buckets over {@link Set} keys. Ten consecutive failures within the
+ * window lock the source for the lockout period; a successful login
+ * clears the bucket. Time is injectable for fake-timer tests.
+ */
+export const LOGIN_LIMIT_MAX_FAILURES = 10;
+export const LOGIN_LIMIT_WINDOW_MS = 10 * 60_000;
+export const LOGIN_LOCKOUT_MS = 10 * 60_000;
+/**
+ * The system clock, captured at module load: vitest's `useFakeTimers`
+ * replaces the global `Date`, and the login route's limiter must keep
+ * wall-clock semantics when a test fakes timers to skip the 1 000 ms
+ * failure delay (the limiter windows are minutes — no test waits them
+ * out; they simply never advance within one test).
+ */
+const systemNow = Date.now;
+export class LoginLimiter {
+    now;
+    buckets = new Map();
+    constructor(now = systemNow) {
+        this.now = now;
+    }
+    /**
+     * Whether a login attempt from `key` (the source IP) may proceed.
+     * False while locked; the locked reply never reveals the state of the
+     * token (checked BEFORE the credential and the wait, per the brief).
+     */
+    allowed(key) {
+        const bucket = this.buckets.get(key);
+        return bucket === undefined || bucket.lockedUntil <= this.now();
+    }
+    /** Record a failed attempt; the 10th inside the window locks the key. */
+    recordFailure(key) {
+        const now = this.now();
+        const bucket = this.buckets.get(key) ?? { failures: [], lockedUntil: 0 };
+        while (bucket.failures.length > 0 &&
+            now - bucket.failures[0] >= LOGIN_LIMIT_WINDOW_MS) {
+            bucket.failures.shift();
+        }
+        bucket.failures.push(now);
+        if (bucket.failures.length >= LOGIN_LIMIT_MAX_FAILURES) {
+            bucket.lockedUntil = now + LOGIN_LOCKOUT_MS;
+            bucket.failures.length = 0;
+        }
+        this.buckets.set(key, bucket);
+    }
+    /** A success clears the bucket — the lock punishes guessing, not use. */
+    recordSuccess(key) {
+        this.buckets.delete(key);
+    }
+}

package/dist/server/auth/loopback.js

@@ -0,0 +1,47 @@
+/**
+ * The loopback test shared by the auth surface (core-hardening W1).
+ *
+ * Two consumers with one notion of "local": `effectiveMethods` (the
+ * defaults ruling — `[]` methods on a loopback bind, `["token"]`
+ * otherwise) and Task 3's pipeline Host check (a loopback bind only
+ * accepts loopback `Host` values). The set is `127.0.0.0/8`, `::1`,
+ * and `localhost` (spec §5.2) — deliberately NOT `::` or link-local:
+ * binding those exposes the server beyond this machine.
+ */
+import { BlockList, isIP } from "node:net";
+const v4Loopback = new BlockList();
+v4Loopback.addSubnet("127.0.0.0", 8);
+const v6Loopback = new BlockList();
+// The family hints are required: BlockList's auto-detection does not
+// accept `::1` at add time and does not match it at check time (Node 26
+// behavior, verified — the plan's Review Focus 1 assumes explicit
+// normalization/family handling around BlockList, which is this).
+v6Loopback.addAddress("::1", "ipv6");
+/**
+ * Whether `host` is a loopback bind address: any `127.x.x.x`, `::1`
+ * (including its expanded, bracketed, and v4-mapped spellings), or the
+ * `localhost` name (case-insensitive). Everything else — the container
+ * default `0.0.0.0`, `::`, LAN addresses, other hostnames — is not.
+ */
+export function isLoopbackHost(host) {
+    let candidate = host.trim().toLowerCase();
+    // The URL-hostname form brackets IPv6 literals.
+    if (candidate.startsWith("[") && candidate.endsWith("]")) {
+        candidate = candidate.slice(1, -1);
+    }
+    if (candidate === "localhost")
+        return true;
+    // A v4-mapped v6 address binds the v4 address it maps to (Node
+    // accepts `::ffff:127.0.0.1` as a bind address; BlockList does not
+    // fold the mapping itself).
+    if (candidate.startsWith("::ffff:") &&
+        isIP(candidate.slice(7)) === 4) {
+        candidate = candidate.slice(7);
+    }
+    const family = isIP(candidate);
+    if (family === 4)
+        return v4Loopback.check(candidate);
+    if (family === 6)
+        return v6Loopback.check(candidate, "ipv6");
+    return false;
+}

package/dist/server/auth/pipeline.js

@@ -0,0 +1,330 @@
+/**
+ * The §5 request pipeline (core hardening W1 Task 3, spec §5.2/§5.3):
+ * ONE onRequest hook, registered before every route, that resolves the
+ * caller into `request.principal`. The stages, in order:
+ *
+ *  1. **Host/Origin checks.** On a loopback listen host, the `Host`
+ *     hostname (port stripped) must be loopback or in
+ *     `auth.allowedHosts`, else 421 (DNS-rebinding defense); a
+ *     non-loopback bind checks only when `allowedHosts` is set. A
+ *     non-GET/HEAD request with an `Origin` must match the effective
+ *     host (`X-Forwarded-Host` from a trusted proxy peer, else `Host`)
+ *     or `auth.allowedOrigins`, else 403 `origin_mismatch`.
+ *  2. **Public paths.** Decided from the MATCHED ROUTE PATTERN
+ *     (`request.routeOptions.url`), never the raw URL (Fastify decodes
+ *     before routing — `/%761/...` routes to `/v1/...`): `/healthz`,
+ *     `/readyz`, `/metrics` when `config.metricsPublic`,
+ *     `/v1/onboarding` (+ subpaths), `POST /v1/auth/login`,
+ *     `POST /v1/auth/logout`, and the browser surface — a GET/HEAD that
+ *     matched the static wildcard (`/*`) or no route at all (the
+ *     not-found handler serves the SPA for non-/v1 paths).
+ *  3. **Env service token.** A `Bearer` equal (constant-time) to
+ *     `SIGRUN_API_TOKEN` resolves the service principal and skips the
+ *     setup gate.
+ *  4. **Unclaimed gate.** `!users.isClaimed()` → 403 `setup_required`
+ *     (onboarding is the only usable surface until the first claim).
+ *  4b. **Extension-route public skip** (W5 Task 2, spec §9.2). A request
+ *     ROUTED to a mounted `/v1/ext/<slug>/<path>` route whose
+ *     contribution declared `auth: "public"` skips stage 5 — webhooks
+ *     and OAuth callbacks verify their own caller. Stages 1-4 still
+ *     applied (an unclaimed server answers a public route 403
+ *     `setup_required`, spec §5.8); the request carries no principal.
+ *  5. **Methods, in `ctx.methods` order.** `proxy`: trusted peer CIDR +
+ *     (when configured) the shared-secret header (deleted from the
+ *     request before handlers run) + a non-empty user header; a
+ *     directory miss auto-provisions (`source:"proxy"`, admin:false)
+ *     unless `autoProvision:false` → 403 `user_not_provisioned`.
+ *     `token`: Bearer or the `sigrun_session` cookie → `tokens.verify`;
+ *     the token's user must exist in the directory, else 401.
+ *  6. **Empty list** (the naive workstation path): the trimmed
+ *     `X-Sigrun-User` header verbatim, `admin: true`, method `"none"`.
+ */
+import { timingSafeEqual } from "node:crypto";
+import { ipAllowed } from "./ip.js";
+import { isLoopbackHost } from "./loopback.js";
+/** One header read: Fastify headers may be string | string[]; first wins. */
+function headerOf(request, name) {
+    const value = request.headers[name.toLowerCase()];
+    const single = Array.isArray(value) ? value[0] : value;
+    return single?.trim() || undefined;
+}
+/** Constant-time string equality (credentials never compare with `===`). */
+function timingSafeStringEqual(a, b) {
+    const left = Buffer.from(a, "utf8");
+    const right = Buffer.from(b, "utf8");
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+/** The request's Bearer credential, if the Authorization header carries one. */
+function bearerOf(request) {
+    const value = headerOf(request, "authorization");
+    if (value === undefined)
+        return undefined;
+    const match = /^Bearer\s+(.+)$/i.exec(value);
+    return match?.[1]?.trim() || undefined;
+}
+/** The `sigrun_session` cookie value (naive parse; the cookie is ours). */
+function sessionCookieOf(request) {
+    const raw = headerOf(request, "cookie");
+    if (raw === undefined)
+        return undefined;
+    for (const pair of raw.split(";")) {
+        const eq = pair.indexOf("=");
+        if (eq === -1)
+            continue;
+        if (pair.slice(0, eq).trim() === "sigrun_session") {
+            return pair.slice(eq + 1).trim() || undefined;
+        }
+    }
+    return undefined;
+}
+/** The Host hostname with any port stripped (`[::1]:3000` → `[::1]`). */
+function hostNameOf(host) {
+    if (host.startsWith("[")) {
+        const close = host.indexOf("]");
+        return close === -1 ? host : host.slice(0, close + 1);
+    }
+    const colon = host.indexOf(":");
+    return colon === -1 ? host : host.slice(0, colon);
+}
+/** Stage 1a: the Host check. Returns the rejection status, or undefined. */
+function checkHost(request, ctx) {
+    const host = headerOf(request, "host");
+    if (host === undefined)
+        return 421;
+    const allowed = ctx.config.auth.allowedHosts ?? [];
+    if (allowed.some((entry) => entry.toLowerCase() === host.toLowerCase())) {
+        return undefined;
+    }
+    const name = hostNameOf(host);
+    if (allowed.some((entry) => entry.toLowerCase() === name.toLowerCase())) {
+        return undefined;
+    }
+    if (!isLoopbackHost(ctx.listenHost)) {
+        // A non-loopback bind checks only when the allowlist exists.
+        return allowed.length === 0 ? undefined : 421;
+    }
+    return isLoopbackHost(name) ? undefined : 421;
+}
+/** Stage 1b: the Origin check (non-GET/HEAD only). Returns true when rejected. */
+function checkOrigin(request, ctx) {
+    if (request.method === "GET" || request.method === "HEAD")
+        return false;
+    const origin = headerOf(request, "origin");
+    if (origin === undefined)
+        return false;
+    for (const allowed of ctx.config.auth.allowedOrigins ?? []) {
+        if (allowed.toLowerCase() === origin.toLowerCase())
+            return false;
+    }
+    // The effective host the browser claims to be serving: X-Forwarded-Host
+    // from a trusted peer (a forward-auth proxy fronts us), else Host.
+    const trusted = ipAllowed(request.socket.remoteAddress, ctx.config.auth.proxy.trustedProxies);
+    const forwarded = trusted ? headerOf(request, "x-forwarded-host") : undefined;
+    const host = headerOf(request, "host");
+    const expectedHosts = new Set();
+    for (const candidate of [forwarded, host]) {
+        if (candidate === undefined)
+            continue;
+        expectedHosts.add(candidate.toLowerCase());
+        expectedHosts.add(hostNameOf(candidate).toLowerCase());
+    }
+    let originHost;
+    try {
+        originHost = new URL(origin).host.toLowerCase();
+    }
+    catch {
+        return true; // an unparseable Origin never matches
+    }
+    return !expectedHosts.has(originHost);
+}
+/**
+ * Stage 2: whether the request answers without a principal.
+ *
+ * Computed from the MATCHED ROUTE PATTERN (`request.routeOptions.url`,
+ * e.g. `/v1/settings`, `/v1/conversations/:id`, `/*`), never the raw
+ * URL: Fastify decodes the path BEFORE routing, so `GET /%761/settings`
+ * (`%76` = `v`) routes to `/v1/settings` while the raw URL fails a
+ * `/v1/` prefix check — the encoded-path auth bypass. A GET is public
+ * only when it matched the static plugin's wildcard (`/*`) or matched
+ * nothing (the not-found handler serves the SPA for non-/v1 paths).
+ */
+function isPublicPath(request, ctx) {
+    const pattern = request.routeOptions.url;
+    if (pattern === "/healthz" || pattern === "/readyz")
+        return true;
+    if (pattern === "/metrics" && ctx.config.metricsPublic)
+        return true;
+    if (pattern === "/v1/auth/login" && request.method === "POST")
+        return true;
+    if (pattern === "/v1/auth/logout" && request.method === "POST")
+        return true;
+    if (pattern === "/v1/onboarding" || pattern?.startsWith("/v1/onboarding/")) {
+        return true;
+    }
+    // The browser surface: GET/HEAD that matched the static wildcard or
+    // no route at all (the not-found handler serves the SPA). Anything
+    // that matched a real API route — under ANY spelling of its path — is
+    // not public.
+    if (request.method === "GET" || request.method === "HEAD") {
+        if (pattern === "/*" || pattern === undefined)
+            return true;
+    }
+    return false;
+}
+/**
+ * Stage 5a (proxy): resolve the forward-auth headers, or reply with the
+ * rejection. The secret header is DELETED from the request before any
+ * handler (or test hook) can observe it.
+ */
+async function resolveProxy(request, ctx) {
+    const { proxy, adminGroups } = ctx.config.auth;
+    if (!ipAllowed(request.socket.remoteAddress, proxy.trustedProxies)) {
+        return { status: 401 };
+    }
+    if (proxy.secret !== undefined && proxy.secretHeader !== undefined) {
+        const name = proxy.secretHeader.toLowerCase();
+        const presented = headerOf(request, name);
+        delete request.headers[name];
+        if (presented === undefined || !timingSafeStringEqual(presented, proxy.secret)) {
+            return { status: 401 };
+        }
+    }
+    const user = headerOf(request, proxy.userHeader);
+    if (user === undefined)
+        return { status: 401 };
+    const groups = headerOf(request, proxy.groupsHeader)
+        ?.split(",")
+        .map((group) => group.trim())
+        .filter((group) => group !== "") ?? [];
+    const { users } = ctx.opened.identity;
+    // The invalid-username case (a proxy header that can't be a directory
+    // user) is a loud 403, not a 500: the proxy vouched for an identity
+    // this server can never represent.
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(user)) {
+        return { status: 403, error: "invalid_username" };
+    }
+    const existing = users.get(user);
+    if (existing === undefined && !proxy.autoProvision) {
+        return { status: 403, error: "user_not_provisioned" };
+    }
+    const record = existing ??
+        (await users.add({
+            user,
+            ...(headerOf(request, proxy.nameHeader) === undefined
+                ? {}
+                : { name: headerOf(request, proxy.nameHeader) }),
+            ...(headerOf(request, proxy.emailHeader) === undefined
+                ? {}
+                : { email: headerOf(request, proxy.emailHeader) }),
+            admin: false,
+            source: "proxy",
+        }));
+    const groupAdmin = groups.some((group) => adminGroups.includes(group));
+    return {
+        user: record.user,
+        ...(record.name === undefined ? {} : { name: record.name }),
+        ...(record.email === undefined ? {} : { email: record.email }),
+        admin: record.admin || groupAdmin,
+        service: false,
+        method: "proxy",
+    };
+}
+/** Stage 5b (token): verify a presented credential against the token store. */
+function resolveToken(request, ctx) {
+    const presented = bearerOf(request) ?? sessionCookieOf(request);
+    if (presented === undefined)
+        return { status: 401 };
+    const record = ctx.opened.identity.tokens.verify(presented);
+    if (record === undefined)
+        return { status: 401 };
+    const user = ctx.opened.identity.users.get(record.user);
+    // A token for a removed user is dead weight — the user must exist.
+    if (user === undefined)
+        return { status: 401 };
+    return {
+        user: user.user,
+        ...(user.name === undefined ? {} : { name: user.name }),
+        ...(user.email === undefined ? {} : { email: user.email }),
+        admin: user.admin,
+        service: false,
+        method: "token",
+    };
+}
+/** The ONE request hook. Stages 1→5 in brief order; a stage replies or falls through. */
+export function registerAuthPipeline(app, ctx) {
+    app.addHook("onRequest", async (request, reply) => {
+        // Stage 1: Host + Origin.
+        const hostStatus = checkHost(request, ctx);
+        if (hostStatus !== undefined) {
+            return await reply.code(hostStatus).send({ error: "host_not_allowed" });
+        }
+        if (checkOrigin(request, ctx)) {
+            return await reply.code(403).send({ error: "origin_mismatch" });
+        }
+        // Stage 2: the public surface (resolved but never blocked).
+        if (isPublicPath(request, ctx))
+            return;
+        // Stage 3: the env service token (constant-time; skips stage 4).
+        const service = ctx.config.auth.serviceToken;
+        const bearer = bearerOf(request);
+        if (service !== undefined &&
+            bearer !== undefined &&
+            timingSafeStringEqual(bearer, service.token)) {
+            request.principal = {
+                user: service.user,
+                admin: true,
+                service: true,
+                method: "token",
+            };
+            return;
+        }
+        // Stage 4: the setup gate (the brief's "never 401 before 403").
+        if (!ctx.opened.identity.users.isClaimed()) {
+            return await reply.code(403).send({ error: "setup_required" });
+        }
+        // Stage 4b: the extension-route public skip (W5 Task 2, spec §9.2).
+        // The request is already ROUTED — Fastify resolved it to a route
+        // before lifecycle hooks run — so `routeOptions.config.extAuth` is
+        // the mounted route's declared auth, exactly (and `routeOptions.url`
+        // is the MATCHED PATTERN, immune to encoded-path spellings). A
+        // `public` route (a webhook, an OAuth callback) skips stage 5; its
+        // handler sees no principal and verifies its own caller. Everything
+        // else (`user`/`admin`, core routes, unrouted paths) falls through to
+        // the normal authentication stages.
+        if (request.routeOptions.url?.startsWith("/v1/ext/") &&
+            request.routeOptions.config.extAuth === "public") {
+            return;
+        }
+        // Stage 5/6: the configured methods, in order; the empty list is
+        // the naive loopback path.
+        if (ctx.methods.length === 0) {
+            request.principal = {
+                user: headerOf(request, "x-sigrun-user"),
+                admin: true,
+                service: false,
+                method: "none",
+            };
+            return;
+        }
+        for (const method of ctx.methods) {
+            const resolved = method === "proxy"
+                ? await resolveProxy(request, ctx)
+                : resolveToken(request, ctx);
+            if ("user" in resolved && resolved.user !== undefined) {
+                request.principal = resolved;
+                return;
+            }
+            // A configured-deny (403 user_not_provisioned) is terminal: the
+            // proxy VOUCHED for a user the directory refuses — trying weaker
+            // methods would widen, not narrow, the failure surface.
+            if (!("user" in resolved) && resolved.status === 403) {
+                return await reply
+                    .code(403)
+                    .send({ error: resolved.error ?? "forbidden" });
+            }
+        }
+        return await reply.code(401).send({ error: "unauthenticated" });
+    });
+}