@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/dist/api/jwt.js

@@ -0,0 +1,199 @@
+import * as jose from "jose";
+import { parseTenantId } from "../engine/types/index.js";
+import { InternalError } from "../errors/index.js";
+function normalizeKeyring(secretOrKeyring) {
+    if (typeof secretOrKeyring === "string") {
+        const key = new TextEncoder().encode(secretOrKeyring);
+        return { verifyKeys: new Map(), signKid: undefined, signKey: key };
+    }
+    const verifyKeys = new Map();
+    for (const [kid, secret] of Object.entries(secretOrKeyring.keys)) {
+        verifyKeys.set(kid, new TextEncoder().encode(secret));
+    }
+    const signKey = verifyKeys.get(secretOrKeyring.signKid);
+    if (!signKey) {
+        throw new Error(`createJwtHelper: signKid "${secretOrKeyring.signKid}" is not present in the keyring`);
+    }
+    return { verifyKeys, signKid: secretOrKeyring.signKid, signKey };
+}
+// Tokens carry `kid` in the protected header when signed from a keyring — pick the
+// matching verify-key directly. Tokens without `kid` (single-secret form, or in-flight
+// tokens signed before a rotation) fall back to trying every verify-key.
+async function verifyWithKeyring(token, keyring, issuer) {
+    const { kid } = jose.decodeProtectedHeader(token);
+    if (typeof kid === "string" && keyring.verifyKeys.size > 0) {
+        const key = keyring.verifyKeys.get(kid);
+        if (!key) {
+            throw new Error(`JWT verification failed: unknown kid "${kid}"`);
+        }
+        return jose.jwtVerify(token, key, { issuer });
+    }
+    // ponytail: tries every key in the ring (O(keys) per legacy-token verify) — fine for a
+    // rotation window of a handful of keys, revisit if the keyring ever grows large.
+    const candidates = keyring.verifyKeys.size > 0 ? [...keyring.verifyKeys.values()] : [keyring.signKey];
+    let lastError;
+    for (const key of candidates) {
+        try {
+            return await jose.jwtVerify(token, key, { issuer });
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error("JWT verification failed: no matching key");
+}
+const DEFAULT_JWT_TTL_SECONDS = 24 * 60 * 60;
+export function createJwtHelper(secretOrKeyring, issuer = "kumiko", ttlSeconds = DEFAULT_JWT_TTL_SECONDS) {
+    const keyring = normalizeKeyring(secretOrKeyring);
+    return {
+        async sign(user) {
+            // A resolved member principal (origin set) carries no `sid` and must
+            // never be minted into a session — only interactive sign-in may sign.
+            if (user.origin !== undefined) {
+                throw new InternalError({
+                    message: `jwt.sign: refusing to sign a SessionUser with origin "${user.origin}" — only interactively-authenticated sessions may be minted.`,
+                });
+            }
+            const body = {
+                tenantId: user.tenantId,
+                roles: [...user.roles],
+            };
+            if (user.timezone)
+                body.timezone = user.timezone;
+            if (user.locale)
+                body.locale = user.locale;
+            if (user.claims)
+                body.claims = { ...user.claims };
+            const header = keyring.signKid
+                ? { alg: "HS256", kid: keyring.signKid }
+                : { alg: "HS256" };
+            // iat/exp share one `now` — jose's setIssuedAt()/setExpirationTime(Date)
+            // each read the clock separately, letting `exp - iat` drift by a
+            // second and making TTL-precision tests flaky.
+            const nowSec = Math.floor(Date.now() / 1000);
+            const builder = new jose.SignJWT(body)
+                .setProtectedHeader(header)
+                .setSubject(String(user.id))
+                .setIssuer(issuer)
+                .setIssuedAt(nowSec)
+                .setExpirationTime(nowSec + ttlSeconds);
+            if (user.sid)
+                builder.setJti(user.sid);
+            return builder.sign(keyring.signKey);
+        },
+        async verify(token) {
+            const { payload } = await verifyWithKeyring(token, keyring, issuer);
+            // defence-in-depth: valid sig ≠ well-formed claims; malformed payload → throw → 401
+            const tenantId = parseTenantId(payload["tenantId"]);
+            if (tenantId === null) {
+                throw new Error("JWT payload validation failed: tenantId claim is missing or malformed");
+            }
+            const rawRoles = payload["roles"];
+            if (!Array.isArray(rawRoles)) {
+                throw new Error("JWT payload validation failed: roles claim must be an array");
+            }
+            const roles = [];
+            for (const role of rawRoles) {
+                if (typeof role !== "string") {
+                    throw new Error("JWT payload validation failed: roles must contain only strings");
+                }
+                roles.push(role);
+            }
+            if (typeof payload.sub !== "string" || payload.sub === "") {
+                throw new Error("JWT payload validation failed: sub claim is missing or malformed");
+            }
+            const result = {
+                sub: payload.sub,
+                tenantId,
+                roles,
+            };
+            if (typeof payload["timezone"] === "string") {
+                result.timezone = payload["timezone"];
+            }
+            if (typeof payload["locale"] === "string") {
+                result.locale = payload["locale"];
+            }
+            const claims = payload["claims"];
+            if (claims && typeof claims === "object") {
+                result.claims = claims;
+            }
+            if (typeof payload.jti === "string") {
+                result.jti = payload.jti;
+            }
+            if (typeof payload.exp === "number") {
+                result.exp = payload.exp;
+            }
+            return result;
+        },
+        ttlSeconds,
+    };
+}
+const JWT_KEY_VAR_PATTERN = /^JWT_SECRET_V(\d+)$/;
+const JWT_CURRENT_VERSION_VAR = "JWT_SECRET_CURRENT_VERSION";
+// Mirrors authEmailPasswordEnvSchema's JWT_SECRET.min(32) — HS256 minimum.
+// JWT_SECRET_V<n> bypasses that zod schema entirely (it only validates the
+// plain JWT_SECRET name), so this loader is the only gate for the rotation path.
+const MIN_JWT_SECRET_LENGTH = 32;
+function assertMinLength(name, value) {
+    if (value.length < MIN_JWT_SECRET_LENGTH) {
+        throw new Error(`[jwt] ${name} must be ≥${MIN_JWT_SECRET_LENGTH} chars (HS256 minimum)`);
+    }
+}
+// Env-loader for createJwtHelper's secret-or-keyring param, analog to
+// secrets' loadKeyring: JWT_SECRET_V<n> (+ JWT_SECRET_CURRENT_VERSION picking
+// the active signKid) for rotation, falling back to plain JWT_SECRET when no
+// JWT_SECRET_V<n> is set — so a non-rotating deployment needs no new env vars.
+export function loadJwtSecretOrKeyring(env) {
+    const keys = {};
+    for (const [name, value] of Object.entries(env)) {
+        const match = name.match(JWT_KEY_VAR_PATTERN);
+        if (!match)
+            continue;
+        if (!value) {
+            throw new Error(`[jwt] ${name} is set but empty — an empty versioned secret is almost certainly a ` +
+                "deploy mistake, not an intentional skip. Unset the var entirely if it's unused.");
+        }
+        assertMinLength(name, value);
+        // biome-ignore lint/style/noNonNullAssertion: regex group 1 always present
+        keys[`v${match[1]}`] = value;
+    }
+    // skip: no JWT_SECRET_V<n> found — single-secret fallback.
+    if (Object.keys(keys).length === 0) {
+        const secret = env["JWT_SECRET"];
+        if (!secret) {
+            throw new Error("[jwt] JWT_SECRET not set — set JWT_SECRET for a single key, or " +
+                "JWT_SECRET_V1 (+ JWT_SECRET_CURRENT_VERSION=1) for a rotatable keyring.");
+        }
+        assertMinLength("JWT_SECRET", secret);
+        return secret;
+    }
+    const currentRaw = env[JWT_CURRENT_VERSION_VAR];
+    if (!currentRaw) {
+        throw new Error(`[jwt] ${JWT_CURRENT_VERSION_VAR} not set — explicit current-version required ` +
+            "so adding a new JWT_SECRET_V<n> doesn't auto-promote it to the sign key.");
+    }
+    const signKid = `v${currentRaw}`;
+    if (!keys[signKid]) {
+        throw new Error(`[jwt] ${JWT_CURRENT_VERSION_VAR}="${currentRaw}" not present in the keyring ` +
+            `(have versions: ${Object.keys(keys).sort().join(", ")}). ` +
+            `Check JWT_SECRET_V${currentRaw} is set.`);
+    }
+    // Carry the pre-rotation plain JWT_SECRET into the ring as a verify-only
+    // legacy key: sessions signed before JWT_SECRET_V<n> was first set have no
+    // `kid`, so verifyWithKeyring's no-kid fallback tries every key in `keys` —
+    // if the plain secret isn't one of them, every in-flight session breaks the
+    // moment rotation is adopted, exactly the mass-invalidation this keyring
+    // exists to avoid. Never becomes signKid — only JWT_SECRET_V<n> can sign.
+    // Retirement: has no automatic expiry — verifies unbounded as long as
+    // JWT_SECRET stays set. Operators must explicitly unset JWT_SECRET once
+    // max token TTL (`ttlSeconds`) has elapsed since cutover to actually
+    // retire a rotated-out secret (see run-prod-app.ts boot warning).
+    const legacySecret = env["JWT_SECRET"];
+    if (legacySecret) {
+        assertMinLength("JWT_SECRET", legacySecret);
+        keys["legacy"] = legacySecret;
+    }
+    return { keys, signKid };
+}

package/dist/api/observability-middleware.d.ts

@@ -0,0 +1,8 @@
+import type { Context, Next } from "hono";
+import { type Meter, type SensitiveFilterConfig, type Tracer } from "../observability/index.js";
+export type ObservabilityMiddlewareOptions = {
+    readonly tracer: Tracer;
+    readonly meter: Meter;
+    readonly sensitiveConfig: SensitiveFilterConfig;
+};
+export declare function observabilityMiddleware(opts: ObservabilityMiddlewareOptions): (c: Context, next: Next) => Promise<void>;

package/dist/api/observability-middleware.js

@@ -0,0 +1,68 @@
+import { emitHttpRequest, observabilityContext, redactQueryString, } from "../observability/index.js";
+import { getUser } from "./auth-middleware.js";
+import { requestContext } from "./request-context.js";
+export function observabilityMiddleware(opts) {
+    const { tracer, meter, sensitiveConfig } = opts;
+    return async (c, next) => {
+        const method = c.req.method;
+        const path = c.req.path;
+        const target = redactQueryString(c.req.url.replace(/^https?:\/\/[^/]+/, ""), sensitiveConfig);
+        // Start the root span for this request. kind=server marks it as an
+        // incoming server-side span in OTel terms.
+        const span = tracer.startSpan("http.request", {
+            kind: "server",
+            attributes: {
+                "http.method": method,
+                "http.route": path,
+                "http.target": target,
+            },
+        });
+        const reqCtx = requestContext.get();
+        if (reqCtx?.requestId) {
+            span.setAttribute("kumiko.request_id", reqCtx.requestId);
+        }
+        const startTime = performance.now();
+        try {
+            await observabilityContext.run({ activeSpan: span }, () => next());
+            // Auth middleware runs inside `next()` and sets the user on the
+            // Hono context if the token was valid. Enrich the span after the
+            // fact so public paths (health, login) don't emit empty user attrs.
+            try {
+                const user = getUser(c);
+                if (user) {
+                    span.setAttribute("kumiko.user_id", user.id);
+                    span.setAttribute("kumiko.tenant_id", user.tenantId);
+                }
+            }
+            catch {
+                // getUser throws if called before auth ran — public paths, fine.
+            }
+            span.setAttribute("http.status_code", c.res.status);
+            if (c.res.status >= 500) {
+                span.setStatus("error", `HTTP ${c.res.status}`);
+            }
+            else {
+                span.setStatus("ok");
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                span.recordException(error);
+                span.setStatus("error", error.message);
+            }
+            else {
+                span.setStatus("error", String(error));
+            }
+            span.setAttribute("http.status_code", 500);
+            throw error;
+        }
+        finally {
+            const durationSec = (performance.now() - startTime) / 1000;
+            // c.res may be undefined on very early throws (before any route handler);
+            // fall back to 500 for the metric so the counter is always incremented.
+            const status = c.res?.status ?? 500;
+            emitHttpRequest(meter, { route: path, method, status }, durationSec);
+            span.end();
+        }
+    };
+}

package/dist/api/origin-middleware.d.ts

@@ -0,0 +1,12 @@
+import type { Context, Next } from "hono";
+export declare function normalizeOrigin(value: string): string;
+export declare function isOriginAllowed(origin: string, normalizedAllowlist: ReadonlySet<string>): boolean;
+export declare function isForeignCookieOrigin(c: Context, allowlist: ReadonlySet<string>): boolean;
+export declare function rejectOrigin(c: Context): Response;
+export declare function isWebSocketOriginAllowed(c: Context, normalizedAllowlist: ReadonlySet<string> | undefined): boolean;
+export declare function originMiddleware(allowedOrigins: readonly string[]): (c: Context, next: Next) => Promise<void | Response>;
+export declare function assertOriginGuardConfig(auth: {
+    cookieDomain?: string;
+    allowedOrigins?: readonly string[];
+    unsafeSkipOriginCheck?: boolean;
+} | undefined): void;

package/dist/api/origin-middleware.js

@@ -0,0 +1,120 @@
+import { STATE_CHANGING_METHODS } from "./api-constants.js";
+import { getAuthTransport } from "./auth-middleware.js";
+// Canonical comparable form for an Origin / allowlist entry: lowercased, no
+// trailing slash. Origin headers are scheme+host(+port) without a path, but
+// config entries are hand-written and may carry a stray slash or mixed case.
+export function normalizeOrigin(value) {
+    return value.trim().toLowerCase().replace(/\/+$/, "");
+}
+// Exact-match against a pre-normalized allowlist. No wildcards by design:
+// `*.example.eu` would re-admit the tenant subdomains this guard exists to
+// shut out.
+export function isOriginAllowed(origin, normalizedAllowlist) {
+    return normalizedAllowlist.has(normalizeOrigin(origin));
+}
+// True when a state-changing request carries an Origin (or Sec-Fetch-Site)
+// signal that marks it as coming from outside the allowlist.
+export function isForeignCookieOrigin(c, allowlist) {
+    if (!STATE_CHANGING_METHODS.has(c.req.method))
+        return false;
+    const origin = c.req.header("origin");
+    if (origin !== undefined)
+        return !isOriginAllowed(origin, allowlist);
+    // No Origin header — older browsers, and some same-origin POSTs in Safari.
+    // Fall back to the Fetch-Metadata Sec-Fetch-Site signal: only an explicit
+    // cross-site marker counts as foreign here (it's a relation, not an origin,
+    // so it can't be matched against the allowlist).
+    return c.req.header("sec-fetch-site") === "cross-site";
+}
+export function rejectOrigin(c) {
+    return c.json({
+        error: {
+            code: "origin_not_allowed",
+            httpStatus: 403,
+            message: "request origin is not allowed",
+            i18nKey: "auth.errors.originNotAllowed",
+        },
+    }, 403);
+}
+// WebSocket upgrades are GETs, so originMiddleware/csrfMiddleware never see
+// them — yet a cookie-authenticated upgrade from a foreign page is a
+// cross-site WebSocket hijack. Bearer transports can't be set by a browser
+// WebSocket and need no check.
+export function isWebSocketOriginAllowed(c, normalizedAllowlist) {
+    if (getAuthTransport(c) !== "cookie")
+        return true;
+    const origin = c.req.header("origin");
+    if (origin === undefined || origin === "null")
+        return false;
+    let originHost;
+    try {
+        originHost = new URL(origin).host.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    // With an allowlist there is deliberately no same-host fallback: wide
+    // cookieDomain setups are exactly where a sibling subdomain is the attacker.
+    if (normalizedAllowlist !== undefined && normalizedAllowlist.size > 0) {
+        return isOriginAllowed(origin, normalizedAllowlist);
+    }
+    const requestHost = c.req.header("host")?.toLowerCase();
+    return requestHost !== undefined && originHost === requestHost;
+}
+// Server-side Origin-allowlist guard — an additional CSRF-hardening layer on
+// top of the double-submit token (csrf-middleware) for deployments that widen
+// the auth cookie across subdomains via AuthRoutesConfig.cookieDomain. A wide
+// cookie means an XSS on ANY subdomain (e.g. a tenant status page) can read
+// the JS-readable kumiko_csrf cookie and forge an authenticated state-changing
+// request. Pinning the request Origin to the apex + admin host (never tenant
+// subdomains) closes that vector even for "simple requests" (text/plain or
+// form-encoded) that skip the CORS preflight and reach the server.
+//
+// Runs AFTER authMiddleware (reads the authTransport flag) with the same scope
+// as the CSRF guard: only cookie-authenticated, state-changing requests.
+// Bearer-auth requests skip — browsers cannot set Authorization cross-origin,
+// and native clients send no/foreign Origin, so guarding them would be a
+// false-positive with no CSRF vector to defend.
+export function originMiddleware(allowedOrigins) {
+    const allowlist = new Set(allowedOrigins.map(normalizeOrigin));
+    return async (c, next) => {
+        const transport = getAuthTransport(c);
+        if (transport !== "cookie")
+            return next();
+        // Everything else (same-site, same-origin, none, absent) falls through to
+        // the CSRF token. Note: the CSRF token alone does NOT stop a same-site
+        // subdomain XSS — it can read the wide cookie — but that attack uses
+        // fetch/XHR, which always sends an Origin header and is already rejected
+        // by the allowlist branch inside isForeignCookieOrigin. The residual is
+        // only the no-Origin-yet-Sec-Fetch-Site combo, which no current browser
+        // emits for state-changing requests.
+        if (isForeignCookieOrigin(c, allowlist))
+            return rejectOrigin(c);
+        return next();
+    };
+}
+// Fail-closed boot check: a wide cookieDomain shares the JS-readable
+// kumiko_csrf cookie across every subdomain, so a subdomain XSS can read it and
+// defeat the double-submit CSRF check. Without an Origin allowlist there is no
+// server-side barrier left — refuse to boot in that configuration unless the
+// operator opts out explicitly. Called once from buildServer.
+export function assertOriginGuardConfig(auth) {
+    const widensCookieAcrossSubdomains = Boolean(auth?.cookieDomain);
+    const hasAllowlist = (auth?.allowedOrigins?.length ?? 0) > 0;
+    const optedOut = auth?.unsafeSkipOriginCheck === true;
+    // Contradictory config: the opt-out asks to skip the Origin guard, but a
+    // non-empty allowlist still registers it in buildServer — the flag would be
+    // silently ignored. Force the operator to pick one rather than guess.
+    if (optedOut && hasAllowlist) {
+        throw new Error("[kumiko:boot] auth.unsafeSkipOriginCheck: true disables the Origin guard, but " +
+            "auth.allowedOrigins is also set — the allowlist would still be enforced, ignoring " +
+            "the opt-out. Remove one: keep allowedOrigins to enforce the guard, or drop it to skip.");
+    }
+    if (widensCookieAcrossSubdomains && !hasAllowlist && !optedOut) {
+        throw new Error("[kumiko:boot] auth.cookieDomain widens the session cookie across subdomains, but " +
+            "auth.allowedOrigins is empty — the JS-readable kumiko_csrf cookie would be reachable " +
+            "from every subdomain (e.g. tenant pages) with no server-side Origin check, defeating " +
+            "CSRF protection. Set auth.allowedOrigins to the apex + admin host, or set " +
+            "auth.unsafeSkipOriginCheck: true to accept the risk explicitly.");
+    }
+}

package/dist/api/pat-route-guard.d.ts

@@ -0,0 +1,2 @@
+import type { MiddlewareHandler } from "hono";
+export declare function patRouteGuard(): MiddlewareHandler;

package/dist/api/pat-route-guard.js

@@ -0,0 +1,43 @@
+import { AccessDeniedError } from "../errors/index.js";
+import { Routes } from "./api-constants.js";
+import { getUser } from "./auth-middleware.js";
+// Personal Access Tokens are minted for headless dispatcher access only.
+// Every other /api/* surface (SSE, files, auth/*, feature httpRoutes,
+// entry:"user" extraRoutes) must stay off-limits to a PAT regardless of its
+// granted scopes — those routes never call assertPatAllowed, so without this
+// guard a PAT with any scope (even an empty one) authenticates everywhere a
+// cookie/JWT session would.
+const PAT_ALLOWED_API_PATHS = new Set([
+    `/api${Routes.write}`,
+    `/api${Routes.batch}`,
+    `/api${Routes.query}`,
+    `/api${Routes.command}`,
+    `/api${Routes.stream}`,
+]);
+function isDispatcherPath(path) {
+    return PAT_ALLOWED_API_PATHS.has(path);
+}
+// Must run after an auth guard has resolved getUser(c) — same wiring point
+// as buildPatRateLimitGuard. Cookie/JWT users (user.pat undefined) pass
+// through untouched.
+export function patRouteGuard() {
+    return async (c, next) => {
+        const user = getUser(c);
+        if (user?.pat && !isDispatcherPath(c.req.path)) {
+            const denied = new AccessDeniedError({
+                message: "personal access tokens are only valid for the dispatcher API (write, batch, query, command, stream)",
+                details: { reason: "pat_dispatcher_routes_only" },
+            });
+            return c.json({
+                error: {
+                    code: denied.code,
+                    httpStatus: denied.httpStatus,
+                    message: denied.message,
+                    i18nKey: denied.i18nKey,
+                    details: denied.details,
+                },
+            }, 403);
+        }
+        return next();
+    };
+}

package/dist/api/pat-scope.d.ts

@@ -0,0 +1,2 @@
+export declare function qnMatches(pattern: string, type: string): boolean;
+export declare function patAllows(allowedQns: readonly string[], type: string): boolean;

package/dist/api/pat-scope.js

@@ -0,0 +1,13 @@
+// QN scope-matching for Personal Access Tokens. A token's granted scopes
+// expand (in the PAT feature's resolver) to QN globs like "credit:write:*" or
+// "credit:query:credit:list". A glob ending in "*" matches any dispatch type
+// sharing the prefix; otherwise it is an exact match. Fail-closed: an empty
+// allow-list matches nothing, so a PAT with no scopes can call nothing.
+export function qnMatches(pattern, type) {
+    if (pattern.endsWith("*"))
+        return type.startsWith(pattern.slice(0, -1));
+    return pattern === type;
+}
+export function patAllows(allowedQns, type) {
+    return allowedQns.some((pattern) => qnMatches(pattern, type));
+}

package/dist/api/pii-leak-guard.d.ts

@@ -0,0 +1,2 @@
+import type { MiddlewareHandler } from "hono";
+export declare function piiCiphertextResponseGuard(): MiddlewareHandler;

package/dist/api/pii-leak-guard.js

@@ -0,0 +1,40 @@
+import { PII_CIPHERTEXT_PREFIX } from "../crypto/index.js";
+const isProductionEnv = () => process.env["NODE_ENV"] === "production";
+// Version-agnostic: catches both the current PII_CIPHERTEXT_PREFIX and any
+// older/decrypt-only format version still present in unmigrated rows.
+const CIPHERTEXT_MARKER = "kumiko-pii:v";
+const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^"\s<>\\]*/g;
+// A PII subject ciphertext never belongs in an API response — its presence
+// means a raw DB read (fetchOne/selectMany) leaked to the surface. Dev/test
+// fail loud (500) so a forgotten decrypt turns the first integration test
+// red; prod redacts + logs instead of shipping the blob. Scans unconditionally:
+// legacy ciphertext rows can outlive a subject KMS that later became
+// unconfigured, and the marker check itself needs no KMS access to run.
+export function piiCiphertextResponseGuard() {
+    return async (c, next) => {
+        await next();
+        const contentType = c.res.headers.get("content-type") ?? "";
+        // skip: only JSON bodies carry handler data — streams/zips stay untouched
+        if (!contentType.includes("application/json"))
+            return;
+        const text = await c.res.clone().text();
+        // skip: clean response — the common case
+        if (!text.includes(CIPHERTEXT_MARKER))
+            return;
+        const detail = `[api] JSON response for ${c.req.method} ${c.req.path} contains a PII ciphertext ` +
+            `("${PII_CIPHERTEXT_PREFIX}…") — a raw DB read leaked to the API surface. ` +
+            `Decrypt before returning (decryptStoredPii / executor read path).`;
+        if (!isProductionEnv()) {
+            c.res = Response.json({ error: { code: "pii_ciphertext_leak", httpStatus: 500, message: detail } }, { status: 500 });
+            // skip: response replaced with the loud 500 above — nothing left to do
+            return;
+        }
+        console.error(detail);
+        const headers = new Headers(c.res.headers);
+        headers.delete("content-length");
+        c.res = new Response(text.replace(CIPHERTEXT_RE, "[pii-redacted]"), {
+            status: c.res.status,
+            headers,
+        });
+    };
+}

package/dist/api/post-auth-landing.d.ts

@@ -0,0 +1,14 @@
+export type PostAuthLandingFlow = "login" | "signup" | "invite";
+export type PostAuthLandingArgs = {
+    readonly flow: PostAuthLandingFlow;
+    readonly roles: readonly string[];
+    readonly tenantId: string;
+    readonly tenantKey?: string;
+    readonly handover?: {
+        readonly entityType: string;
+        readonly id: string;
+    };
+};
+export type PostAuthLandingResolver = (args: PostAuthLandingArgs) => string | undefined;
+export declare function isSafeLandingPath(candidate: unknown): candidate is string;
+export declare function resolvePostAuthLandingPath(resolver: PostAuthLandingResolver | undefined, args: PostAuthLandingArgs): string | undefined;

package/dist/api/post-auth-landing.js

@@ -0,0 +1,92 @@
+// Server-computed post-auth redirect target. AuthRoutesConfig.postAuthLanding
+// lets an app decide, in ONE place, where a user lands after login/signup/
+// invite — instead of every frontend screen re-deriving it from roles/
+// tenantId via loggedInHref. The result travels in the JSON response
+// (`landingPath`) and is validated here before it ever reaches the wire: an
+// app-supplied resolver is untrusted input from the framework's perspective,
+// and a bad value would otherwise become a same-response open redirect.
+import { createFallbackLogger } from "../logging/index.js";
+function hasControlOrDelCharacter(candidate) {
+    for (let i = 0; i < candidate.length; i++) {
+        const code = candidate.charCodeAt(i);
+        if (code <= 0x1f || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+// Root-relative-only allowlist, stricter than the framework's existing
+// billing isRootRelativePath: rejects protocol-relative ("//host") and
+// backslash-based ("/\host") paths a browser would still resolve to a
+// different origin, and control chars/whitespace a URL parser silently
+// strips (so "/\t/evil.com" would otherwise normalize to "//evil.com" past
+// the leading-slash check). The new URL(...) parse is a backstop for
+// anything the explicit checks above missed.
+export function isSafeLandingPath(candidate) {
+    if (typeof candidate !== "string" || candidate.length === 0)
+        return false;
+    if (!candidate.startsWith("/"))
+        return false;
+    const second = candidate[1];
+    if (second === "/" || second === "\\")
+        return false;
+    if (candidate.includes("\\"))
+        return false;
+    if (hasControlOrDelCharacter(candidate))
+        return false;
+    if (/\s/.test(candidate))
+        return false;
+    try {
+        const parsed = new URL(candidate, "https://landing.invalid");
+        if (parsed.origin !== "https://landing.invalid")
+            return false;
+        // "/.//evil.com" clears every check above (no leading "//", no
+        // backslash) but normalizes to pathname "//evil.com" — still same-
+        // origin on first navigation, but protocol-relative if a caller ever
+        // re-resolves the bare pathname as a fresh href.
+        return !parsed.pathname.startsWith("//");
+    }
+    catch {
+        return false;
+    }
+}
+function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "then" in value &&
+        typeof value.then === "function");
+}
+const landingLog = createFallbackLogger("auth");
+export function resolvePostAuthLandingPath(resolver, args) {
+    if (!resolver)
+        return undefined;
+    let candidate;
+    try {
+        candidate = resolver(args);
+    }
+    catch (error) {
+        // Consumer error messages can carry PII or secrets; log only the error class.
+        landingLog.warn("postAuthLanding threw — landingPath omitted", {
+            flow: args.flow,
+            errorName: error instanceof Error ? error.name : typeof error,
+        });
+        return undefined;
+    }
+    if (isThenable(candidate)) {
+        // A JS consumer (or a cast) can bypass the sync signature; an unobserved
+        // rejection would terminate the Bun process on every login.
+        Promise.resolve(candidate).catch(() => undefined);
+        landingLog.warn("postAuthLanding async resolver not supported — landingPath omitted", {
+            flow: args.flow,
+        });
+        return undefined;
+    }
+    if (candidate === undefined)
+        return undefined;
+    if (!isSafeLandingPath(candidate)) {
+        landingLog.warn("postAuthLanding returned an unsafe path — landingPath omitted", {
+            flow: args.flow,
+        });
+        return undefined;
+    }
+    return candidate;
+}

package/dist/api/readiness.d.ts

@@ -0,0 +1,23 @@
+import type { Redis } from "ioredis";
+import type { DbConnection } from "../db/connection.js";
+export type ReadinessCheck = {
+    readonly name: string;
+    readonly run: () => Promise<void>;
+};
+export type ReadinessCheckResult = {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly latencyMs: number;
+    readonly error?: string;
+};
+export type ReadinessResult = {
+    readonly ok: boolean;
+    readonly checks: readonly ReadinessCheckResult[];
+};
+export type ReadinessProbeOptions = {
+    readonly timeoutMs?: number;
+};
+export declare function createReadinessProbe(checks: readonly ReadinessCheck[], opts?: ReadinessProbeOptions): () => Promise<ReadinessResult>;
+export declare function dbPingCheck(db: DbConnection): ReadinessCheck;
+export declare function redisPingCheck(redis: Redis): ReadinessCheck;
+export declare function dispatcherLagCheck(db: DbConnection, consumerNames: readonly string[], maxLagEvents: bigint): ReadinessCheck;