@vibesdotdev/auth 0.0.0-stage → 1.0.0-rc.3

package/dist/server/jwt-session-handle.js

@@ -0,0 +1,1184 @@
+import { getVibesClient, tryGetVibesClient } from '@vibesdotdev/kernel/client';
+import { delegatedActorVerificationOptionsSchema, orgClaimSchema, delegatedActorVerificationSchema } from "../schemas/session-verification.js";
+export { delegatedActorClaimsSchema, delegatedActorVerificationSchema, delegatedActorVerificationSchema as DelegatedActorVerificationSchema } from "../schemas/session-verification.js";
+export { SessionJwtVerificationSchema } from "./session-verifier.js";
+import * as z from 'zod/v4';
+import { errors, createLocalJWKSet, jwtVerify } from 'jose';
+import { getLogger } from '@vibesdotdev/logging';
+import { CapabilityError, readPluginConfig, valueFreeFailure } from '@vibesdotdev/kernel';
+import { attempt, attemptSync, failureLabel, rethrowFailure } from "../features/utils/attempt.js";
+import { VIBES_LOCAL_AUTH_ORIGIN } from "../config/local-auth-origin.js";
+import { ApiKeyValidationResponseSchema } from "../schemas/api/api-keys.js";
+import { authenticatedAgentPrincipalSchema } from "../schemas/agents.js";
+import { readJsonOrNull } from "../client/read-json-or-null.js";
+import { SessionBlacklistReaderSchema, sessionIdRevocationKey, sessionRevocationKeys } from "./session-revocation.js";
+import { AuthServiceBindingSchema } from "./auth-service-binding.js";
+import { decodeJWTUnsafe } from "../jwt/index.js";
+import { SESSION_VERIFIER_KIND, SESSION_VERIFIER_ID, SessionJwtVerificationSchema } from "./session-verifier.js";
+import { isLocalAuthOrigin, resolveJwksOrigin, resolveLocalAuthOrigin } from "../jwt/local-jwks-origin.js";
+/**
+ * A single organization membership as carried by the shared .vibes.dev JWT
+ * `orgs` claim. Sourced from auth-web's `definePayload` (the ONE seam) and
+ * surfaced on `event.locals.user.orgs` by {@link applyJwtPayload}. Kept to
+ * `id` + `role` to keep the token small; `getRepositoryPermission` and other
+ * authorization checks read this off locals rather than re-querying account-web.
+ */
+const orgEntrySchema = orgClaimSchema;
+const orgListSchema = z.array(z.unknown());
+/**
+ * Coerce the JWT `orgs` claim into a validated `OrgClaim[]`. Tolerates a
+ * missing / malformed claim (old tokens predating the claim) by defaulting to
+ * `[]`. Only well-formed `{ id: string, role: string }` entries survive.
+ */
+function normalizeOrgClaims(raw) {
+    const list = orgListSchema.safeParse(raw);
+    if (!list.success)
+        return [];
+    const orgs = [];
+    for (const entry of list.data) {
+        const org = orgEntrySchema.safeParse(entry);
+        if (!org.success)
+            continue;
+        const claim = { id: org.data.id, role: org.data.role };
+        if (org.data.slug !== undefined && org.data.slug.length > 0)
+            claim.slug = org.data.slug;
+        orgs.push(claim);
+    }
+    return orgs;
+}
+/** What the session handle puts on `event.locals`, and what `authRequestPrincipal` reads back. */
+const sessionLocalsSchema = z.looseObject({
+    user: z
+        .looseObject({
+        id: z.string().optional().catch(undefined),
+        orgId: z.string().optional().catch(undefined),
+        roles: z.array(z.unknown()).optional().catch(undefined),
+        orgs: z.unknown().optional(),
+        staff: z.unknown().optional(),
+        isSuperuser: z.unknown().optional(),
+        agentPrincipal: z.unknown().optional()
+    })
+        .nullish()
+        .catch(undefined),
+    session: z.looseObject({ id: z.string().optional().catch(undefined) }).nullish().catch(undefined),
+    sessionToken: z.string().optional().catch(undefined)
+});
+const REFRESH_SESSION_COOKIE_NAMES = new Set([
+    'vibes.session',
+    'better-auth.session_token',
+    '__Secure-better-auth.session_token',
+    '__Host-better-auth.session_token'
+]);
+const JWT_COOKIE_NAME = 'vibes.jwt';
+const JWT_MAX_AGE_SECONDS = 15 * 60;
+// 30s default. Local SvelteKit dev under bun is slow on cold/warm requests
+// (Vite module runner re-evaluation, plugin chain); 5s consistently aborted
+// the JWT refresh fetch in dev even though the request itself succeeded.
+// Override with VIBES_AUTH_SESSION_REFRESH_TIMEOUT_MS when you need a
+// stricter budget (e.g. prod where the auth-web call is sub-100ms).
+const DEFAULT_SESSION_REFRESH_TIMEOUT_MS = 30_000;
+// Bound the server-to-server API-key validation fetch. auth-web's
+// `/api/api-keys/validate` has intermittently hung to Cloudflare's 30s
+// wall-clock limit (a public-URL loopback pathology); with NO timeout that hang
+// propagates up through EVERY consumer's sessionHandle on any request carrying
+// an opaque/API-key Bearer — e.g. it stalled the private-repo billing quota
+// check (an internal-service call) for minutes. 10s is far above the healthy
+// sub-100ms validate yet well under the 30s wall-clock kill, so a degraded
+// auth-web fails the request FAST (caller catches → user-less, non-fatal)
+// instead of hanging. Override with VIBES_AUTH_API_KEY_VALIDATE_TIMEOUT_MS.
+const DEFAULT_API_KEY_VALIDATE_TIMEOUT_MS = 10_000;
+// Bound the JWKS refill fetch, for exactly the reason the api-key validate call
+// is bounded. Consumers that DON'T declare the `AUTH_SERVICE` binding (git-web,
+// registry-web call `createJwtSessionHandle` with the default binding name and
+// declare no such binding in their wrangler.jsonc) fall through to global fetch
+// against the PUBLIC issuer origin — the loopback documented below as hanging to
+// Cloudflare's 30s wall clock. Unbounded, that hang owns the whole request, and
+// the forwarded `Authorization: Bearer <jwt>` path has no refresh-cookie fallback
+// to rescue it. 10s (not jose's old 5s ceiling, which a cold public auth-web blew
+// routinely) is far above a healthy sub-100ms JWKS read yet well under the wall
+// clock, so a degraded issuer fails the verify FAST (caller degrades to user-less)
+// instead of hanging. Override with VIBES_AUTH_JWKS_FETCH_TIMEOUT_MS.
+const DEFAULT_JWKS_FETCH_TIMEOUT_MS = 10_000;
+/** The request's runtime, set by `createSvelteKitRuntime`'s `prepareHandle`. */
+function requireRequestRuntime(locals) {
+    const runtime = locals.runtime;
+    if (!runtime) {
+        throw new CapabilityError('The session handle ran before the runtime prepared this request.', 'INTERNAL', {
+            reason: 'environment-not-prepared',
+            recoveryHint: 'Sequence createSvelteKitRuntime(...).prepareHandle before the session handle.'
+        });
+    }
+    return runtime;
+}
+/** A blacklist that is not bound is a deployment fault, not a failed login: it is never swallowed into "no session". */
+function rethrowIfBlacklistUnavailable(failure) {
+    const reason = valueFreeFailure(failure).reason;
+    if (reason === 'session-blacklist-unavailable' || reason === 'session-verifier-unavailable')
+        rethrowFailure(failure);
+}
+/**
+ * The auth origin this handle verifies against and calls: an http(s) URL with
+ * no user, password or fragment. Anything else is a configuration fault, so it
+ * is refused before a request is made to it.
+ */
+function assertAuthOrigin(authOrigin) {
+    const url = URL.parse(authOrigin);
+    if (url === null || (url.protocol !== 'https:' && url.protocol !== 'http:') || url.username !== '' || url.password !== '' || url.hash !== '') {
+        throw new CapabilityError('The auth origin is not an http(s) URL.', 'INVALID_INPUT', {
+            reason: 'auth-origin-invalid',
+            retryable: false
+        });
+    }
+    return authOrigin;
+}
+const SessionHandleKnobsSchema = z.object({
+    sessionRefreshTimeoutMs: z.number().positive().default(DEFAULT_SESSION_REFRESH_TIMEOUT_MS),
+    apiKeyValidateTimeoutMs: z.number().positive().default(DEFAULT_API_KEY_VALIDATE_TIMEOUT_MS),
+    jwksFetchTimeoutMs: z.number().positive().default(DEFAULT_JWKS_FETCH_TIMEOUT_MS)
+}).strict();
+const AuthHostSettingsSchema = z.object({ sessionHandle: SessionHandleKnobsSchema.prefault({}) }).passthrough();
+/** Declared auth plugin settings; host environment aliases are not configuration. */
+async function readSessionHandleKnobs(runtime) {
+    const config = await readPluginConfig(runtime, 'auth', AuthHostSettingsSchema);
+    return config?.sessionHandle ?? SessionHandleKnobsSchema.parse({});
+}
+/**
+ * Bound a promise even when the underlying I/O ignores AbortSignal.
+ * Cloudflare service-binding / public-edge fetches have been observed to
+ * swallow abort; without this race the incoming request holds the socket
+ * until the isolate wall clock (~30s).
+ */
+function withTimeout(runtime, promise, ms, message) {
+    let disarm;
+    const timeout = new Promise((_, reject) => {
+        disarm = runtime.lifecycle.timeout(() => reject(new Error(message)), ms);
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (disarm !== undefined)
+            disarm();
+    });
+}
+// ─── JWKS resolution (Cloudflare-native) ─────────────────────────────────────
+// Verification keys come from the auth issuer's JWKS. We deliberately do NOT use
+// jose's `createRemoteJWKSet`: it fetches over the network with a hard 5s ceiling
+// whose timeout error is literally "request timed out", and against a cold
+// auth-web reached over the PUBLIC url that ceiling was blown routinely — every
+// consumer app then failed verification and 401'd ("Authentication required").
+//
+// Instead the keys are managed as a three-tier cache, each tier decoupling
+// verification further from auth-web being warm:
+//   1. per-isolate memo (a local JWKS resolver — zero per-request network),
+//   2. the Cloudflare Cache API (survives isolate churn within a colo),
+//   3. a refill fetched through the AUTH_SERVICE service binding (Worker→Worker
+//      RPC — no public-edge loopback), never the consumer's arbitrary auth-RPC
+//      fetcher; single-flighted per origin and bounded by a generous timeout
+//      (`jwksFetchTimeoutMs`, from the caller) so an unanswering issuer fails fast instead of
+//      hanging the request — consumers that declare no AUTH_SERVICE binding run
+//      this leg over the public origin, exactly the loopback described above.
+// Freshness is charged against when the keys were pulled FROM THE ISSUER, not
+// when a tier happened to read them, so a partly-aged Cache entry cannot be
+// re-extended to a full fresh TTL (that would double the window in which a
+// revoked key still verifies).
+// A brand-new signing `kid` (key rotation the cached set predates) is handled
+// eagerly by a cooldown-guarded forced refresh, not by waiting out the TTL.
+function getRuntimeSessionState(runtime, expected) {
+    const state = tryGetVibesClient('auth', runtime)?.sessionVerificationState;
+    if (!state?.active || runtime.disposed || (expected && state !== expected)) {
+        throw new CapabilityError('Session verification owner is unavailable.', 'UNAVAILABLE', {
+            reason: 'session-verification-unavailable'
+        });
+    }
+    return state;
+}
+// JWKS rotate rarely; an hour sits well within better-auth's key-overlap window
+// and bounds how long a rotated-out key can linger in a warm cache.
+const JWKS_TTL_MS = 60 * 60 * 1000;
+// Floor between forced refreshes so a flood of unknown-`kid` (e.g. forged or
+// stale) tokens cannot hammer the issuer — mirrors jose's `cooldownDuration`.
+const JWKS_FORCE_REFRESH_COOLDOWN_MS = 30 * 1000;
+// How long a Cache entry of UNKNOWN age may be memoized. Such an entry is a
+// legacy body written before this module started stamping its pull time (they
+// wash out within one max-age window). We can't date it, so we don't pretend to:
+// it is trusted only briefly and then re-checked. The Cache API's own max-age
+// eviction already bounds the entry itself at JWKS_TTL_MS, so worst-case key
+// acceptance stays TTL + this floor — NOT the 2x TTL that memoizing an aged hit
+// for a full fresh TTL would produce.
+const JWKS_UNKNOWN_AGE_MEMO_MS = 60 * 1000;
+/**
+ * Clear the JWKS cache. Test-only: tests that generate fresh key pairs need
+ * to bust the per-origin cache between cases, otherwise the first test's
+ * JWKS persists and subsequent verifies fail with "signature verification
+ * failed". Production code never needs this.
+ */
+export function _resetJwksCache(runtime) {
+    const state = tryGetVibesClient('auth', runtime)?.sessionVerificationState;
+    state?.jwksByOrigin.clear();
+    state?.jwksForceRefreshAtMs.clear();
+    state?.jwksRefillInFlight.clear();
+}
+/** The declared service binding's fetcher on the request's runtime, if the host binds one. */
+function serviceBindingFetcherFrom(runtime, bindingName) {
+    if (!bindingName)
+        return undefined;
+    const binding = runtime.getBinding(bindingName, AuthServiceBindingSchema);
+    return binding ? binding.fetch.bind(binding) : undefined;
+}
+/**
+ * Service-binding fetch MUST NOT be pointed at the public issuer origin.
+ * `AUTH_SERVICE.fetch('https://auth.vibes.dev/api/auth/jwks')` has been
+ * observed to take the public-edge loopback (Worker → auth.vibes.dev →
+ * same colo) and hold the isolate without yielding, so AbortSignal and
+ * Promise.race timeouts never fire and the incoming socket dies at ~30s.
+ * The binding already selects the issuer worker; the host is only a
+ * pathname carrier.
+ */
+const ISSUER_BINDING_ORIGIN = 'https://issuer-binding.internal';
+function issuerBindingUrl(pathname) {
+    return new URL(pathname, ISSUER_BINDING_ORIGIN).toString();
+}
+function resolveFetcher(option, serviceBindingFetcher) {
+    if (option === null) {
+        return globalThis.fetch.bind(globalThis);
+    }
+    if (option !== undefined) {
+        if (option instanceof Function && option.length === 0) {
+            // Looks like a getter `() => fetcher | undefined`. The `fetch`
+            // shape has `length === 2` so this disambiguates safely.
+            // SAFETY: a zero-arity function is the getter form of the option; the fetch shape takes (input, init).
+            const got = option();
+            if (got)
+                return got;
+        }
+        else {
+            // SAFETY: any other function is the fetcher itself (the getter form was handled above).
+            return option;
+        }
+    }
+    return serviceBindingFetcher ?? globalThis.fetch.bind(globalThis);
+}
+export function createJwtSessionHandle(options) {
+    const serviceBindingName = options.serviceBindingName === undefined ? 'AUTH_SERVICE' : options.serviceBindingName;
+    const sessionHandle = async ({ event, resolve }) => {
+        const authOrigin = assertAuthOrigin(options.authOrigin instanceof Function ? await options.authOrigin(event) : options.authOrigin);
+        // SAFETY: `App.Locals` is an interface the host app augments; this handle owns the session fields on it (`SessionLocals`).
+        const locals = event.locals;
+        // Knobs and bindings come from the runtime prepareHandle bound to this
+        // request, never the ambient default (rc01 R2).
+        const runtime = requireRequestRuntime(locals);
+        const logger = getLogger(`${options.clientName || 'app'}.session`, runtime);
+        const knobs = await readSessionHandleKnobs(runtime);
+        const bindingNameForOrigin = isLocalAuthOrigin(authOrigin) ? null : serviceBindingName;
+        const serviceBindingFetcher = serviceBindingFetcherFrom(runtime, bindingNameForOrigin);
+        const fetcher = resolveFetcher(options.fetcher, serviceBindingFetcher);
+        // JWKS refill comes from the issuer worker via the AUTH_SERVICE binding
+        // (Worker→Worker RPC — no public-edge loopback). Crucially NOT the caller's
+        // `options.fetcher`: that override targets session/API-key endpoints and may
+        // point elsewhere, whereas verification keys must come from the issuer. The
+        // binding is guaranteed to be the issuer (wrangler `AUTH_SERVICE → vibes-auth`)
+        // and `iss` is checked independently, so this is correct as well as fast.
+        // Unbound (local dev / tests) it falls back to the public origin via `fetch`.
+        const jwksBindingFetcher = serviceBindingFetcher;
+        const jwksFetcher = jwksBindingFetcher ?? globalThis.fetch.bind(globalThis);
+        const jwksViaServiceBinding = Boolean(jwksBindingFetcher);
+        const jwtCookie = event.cookies.get(JWT_COOKIE_NAME);
+        if (jwtCookie) {
+            const verified = await attempt(() => verifyAuthJwt(jwtCookie, authOrigin, jwksFetcher, {
+                viaServiceBinding: jwksViaServiceBinding,
+                jwksFetchTimeoutMs: knobs.jwksFetchTimeoutMs,
+                runtime
+            }));
+            if (verified.ok) {
+                applyJwtPayload(locals, verified.value);
+                locals.sessionToken = jwtCookie;
+                return resolve(event);
+            }
+            rethrowIfBlacklistUnavailable(verified.failure);
+            logger.warn('[sessionHandle] Better Auth JWT verification failed', {
+                failure: failureLabel(verified.failure)
+            });
+        }
+        // Cross-app service calls (e.g. ai-web → platform-web/api/storage/upload)
+        // can't rely on browser-set cookies — Worker fetch doesn't carry the
+        // user's cookie jar. They forward the user's verified JWT as
+        // `Authorization: Bearer <jwt>` instead. Same JWKS verify path; the
+        // principal is still the requesting user, no service token involved.
+        const bearer = extractBearerToken(event.request.headers.get('authorization'));
+        if (bearer) {
+            if (bearer.split('.').length === 3) {
+                const verified = await attempt(() => verifyAuthJwt(bearer, authOrigin, jwksFetcher, {
+                    viaServiceBinding: jwksViaServiceBinding,
+                    jwksFetchTimeoutMs: knobs.jwksFetchTimeoutMs,
+                    runtime
+                }));
+                if (verified.ok) {
+                    applyJwtPayload(locals, verified.value);
+                    locals.sessionToken = bearer;
+                    return resolve(event);
+                }
+                rethrowIfBlacklistUnavailable(verified.failure);
+                logger.warn('[sessionHandle] Bearer JWT verification failed', {
+                    failure: failureLabel(verified.failure)
+                });
+            }
+            else {
+                // CLI / programmatic callers present a durable vibes API key, not a
+                // JWT. Validate against auth-web's existing server-to-server route
+                // (the MCP pattern) and populate the principal from the owner.
+                // Human-key results and misses are cached briefly by key hash.
+                // Agent principals are revalidated on every request so revocation,
+                // expiry, and quota changes take effect at Auth immediately.
+                const validated = await attempt(() => verifyApiKeyBearer(runtime, bearer, authOrigin, fetcher, {
+                    viaServiceBinding: Boolean(serviceBindingFetcher),
+                    timeoutMs: knobs.apiKeyValidateTimeoutMs
+                }));
+                if (!validated.ok) {
+                    logger.warn('[sessionHandle] API-key validation failed', {
+                        failure: failureLabel(validated.failure)
+                    });
+                }
+                const payload = validated.ok ? validated.value : null;
+                if (payload) {
+                    applyJwtPayload(locals, payload);
+                    // An opaque vibes API key, not a JWT — but every consumer's
+                    // sessionHandle validates it through the same bearer path, so it
+                    // re-presents correctly on a server-to-server hop.
+                    locals.sessionToken = bearer;
+                    return resolve(event);
+                }
+            }
+        }
+        if (hasRefreshSessionCookie(event.request.headers)) {
+            const refreshAttempt = await attempt(() => refreshJwtFromAuthSession({
+                authOrigin,
+                clientName: options.clientName,
+                requestHeaders: event.request.headers,
+                requestUrl: event.url,
+                setCookie: event.cookies.set,
+                fetcher,
+                jwksFetcher,
+                viaServiceBinding: jwksViaServiceBinding,
+                timeoutMs: knobs.sessionRefreshTimeoutMs,
+                jwksFetchTimeoutMs: knobs.jwksFetchTimeoutMs,
+                runtime
+            }));
+            if (!refreshAttempt.ok) {
+                rethrowIfBlacklistUnavailable(refreshAttempt.failure);
+                logger.warn('[sessionHandle] Better Auth JWT refresh failed', {
+                    failure: failureLabel(refreshAttempt.failure)
+                });
+            }
+            const refreshed = refreshAttempt.ok ? refreshAttempt.value : null;
+            if (refreshed) {
+                // Best-effort — a no-op wherever request headers are immutable (workerd).
+                // `locals.sessionToken` is the reliable channel; see its docs.
+                upsertRequestCookie(runtime, event.request.headers, JWT_COOKIE_NAME, refreshed.token);
+                applyJwtPayload(locals, refreshed.payload);
+                locals.sessionToken = refreshed.token;
+                return resolve(event);
+            }
+        }
+        locals.user = null;
+        locals.session = null;
+        locals.sessionToken = null;
+        return resolve(event);
+    };
+    return sessionHandle;
+}
+/**
+ * The request principal extractor for `createSvelteKitRuntime({ principal })`.
+ *
+ * Runs in `invocationHandle`, after {@link createJwtSessionHandle}, and reads
+ * only what that handle verified: the user from `locals.user` and the JWT from
+ * `locals.sessionToken`, which is the credential in force after a refresh. It
+ * never reads the `vibes.jwt` cookie, which can be the expired token the
+ * request arrived with (d48 revision). No verified user, or no token, is
+ * `{ kind: 'anonymous' }`.
+ */
+export function authRequestPrincipal(event) {
+    const parsed = sessionLocalsSchema.safeParse(event.locals);
+    if (!parsed.success)
+        return { kind: 'anonymous' };
+    const { user, session, sessionToken: jwt } = parsed.data;
+    const userId = user?.id !== undefined && user.id.length > 0 ? user.id : null;
+    if (!user || !userId || jwt === undefined || jwt.length === 0)
+        return { kind: 'anonymous' };
+    const principal = { kind: 'user', userId, jwt };
+    // Verified facts (A18): projected only from what `applyJwtPayload` verified onto
+    // `locals.user`. An absent fact is omitted, never `false` / `[]`.
+    if (user.orgId !== undefined && user.orgId.length > 0)
+        principal.orgId = user.orgId;
+    const roles = (user.roles ?? []).flatMap((role) => {
+        const name = z.string().safeParse(role);
+        return name.success ? [name.data] : [];
+    });
+    if (roles.length > 0)
+        principal.roles = roles;
+    const orgs = normalizeOrgClaims(user.orgs);
+    if (orgs.length > 0)
+        principal.orgs = orgs;
+    if (user.staff === true)
+        principal.staff = true;
+    if (user.isSuperuser === true)
+        principal.isSuperuser = true;
+    const agentPrincipal = authenticatedAgentPrincipalSchema.safeParse(user.agentPrincipal);
+    if (agentPrincipal.success)
+        principal.agentPrincipal = agentPrincipal.data;
+    if (session?.id !== undefined && session.id.length > 0)
+        principal.sessionId = session.id;
+    return principal;
+}
+/**
+ * Create a same-origin route that binds an already verified bearer JWT as the
+ * host-only session cookie used by {@link createJwtSessionHandle}.
+ *
+ * The session handle must run before this route. It verifies the bearer against
+ * Auth's JWKS and populates `locals.user`; this handler refuses to write a
+ * cookie unless that verification succeeded. When the old cookie authenticated
+ * a renewal request, an explicit authOrigin lets it verify the new bearer too.
+ */
+export function createJwtSessionBindingHandler(options) {
+    return async (event) => {
+        const { request, cookies, locals, url } = event;
+        const origin = request.headers.get('origin');
+        if (origin !== null && origin !== url.origin)
+            return Response.json({ bound: false }, { status: 403 });
+        const bearer = extractBearerToken(request.headers.get('authorization'));
+        const verified = sessionLocalsSchema.safeParse(locals).data;
+        if (!bearer || bearer.split('.').length !== 3) {
+            return Response.json({ bound: false }, { status: 401 });
+        }
+        if (verified?.sessionToken === bearer && verified.user) {
+            const principal = authRequestPrincipal({ locals: verified });
+            if (principal.kind !== 'user')
+                return Response.json({ bound: false }, { status: 401 });
+            await options?.admit?.(event, principal);
+            setSessionJwtCookie(cookies, url, bearer);
+            return Response.json({ bound: true });
+        }
+        if (!options)
+            return Response.json({ bound: false }, { status: 401 });
+        const bound = await bindVerifiedSessionJwt(event, bearer, options);
+        return Response.json({ bound }, { status: bound ? 200 : 401 });
+    };
+}
+function setSessionJwtCookie(cookies, url, bearer) {
+    cookies.set(JWT_COOKIE_NAME, bearer, {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: url.protocol === 'https:',
+        path: '/',
+        maxAge: JWT_MAX_AGE_SECONDS
+    });
+}
+/**
+ * Verify a bearer against Auth, apply host admission, and write it as the
+ * host-only HttpOnly session cookie. Returns false when the bearer does not
+ * verify as a user session; admission refusals propagate from `admit`.
+ */
+export async function bindVerifiedSessionJwt(event, bearer, options) {
+    if (bearer.split('.').length !== 3)
+        return false;
+    const authOrigin = options.authOrigin instanceof Function ? await options.authOrigin(event) : options.authOrigin;
+    const verdict = await verifySessionJwtResult({ token: bearer, authOrigin, runtime: requireRequestRuntime(event.locals) });
+    if (verdict.status !== 'verified')
+        return false;
+    const bindingLocals = { sessionToken: bearer };
+    applyJwtPayload(bindingLocals, verdict.payload);
+    const principal = authRequestPrincipal({ locals: bindingLocals });
+    if (principal.kind !== 'user')
+        return false;
+    await options.admit?.(event, principal);
+    setSessionJwtCookie(event.cookies, event.url, bearer);
+    return true;
+}
+/** The Cache API store is usable when it answers the two calls this module makes. */
+const cacheStoreSchema = z.custom((value) => value instanceof Object &&
+    'match' in value &&
+    value.match instanceof Function &&
+    'put' in value &&
+    value.put instanceof Function);
+const cacheHostSchema = z.object({
+    caches: z.object({ default: cacheStoreSchema }).optional()
+});
+/** The Cloudflare Cache API (`caches.default`), or null off-Workers (local dev, tests). */
+function getCacheStore() {
+    const host = cacheHostSchema.safeParse(globalThis);
+    return host.success ? host.data.caches?.default ?? null : null;
+}
+/** Stable Cache-API key for an issuer's JWKS. Host is only a namespace; the entry
+ *  is keyed by this URL string. */
+function jwksCacheRequest(jwksOrigin) {
+    // Never key the Cache API on the public issuer URL. A put at
+    // `https://auth.vibes.dev/api/auth/jwks` pollutes that origin's HTTP cache
+    // with this module's envelope (`{cachedAtMs,jwks}`), so a public GET no
+    // longer returns a standard JWKS `{keys:[...]}`.
+    const key = new URL('https://jwks-cache.internal/api/auth/jwks');
+    key.searchParams.set('origin', jwksOrigin);
+    return new Request(key.toString(), { method: 'GET' });
+}
+/**
+ * When was this cache hit actually written? The Cache API does not rewrite an
+ * entry on a hit, so `Age` (seconds the entry has been cached) / `Date` are the
+ * only header-borne signals. Entries this module writes carry the timestamp in
+ * the body instead; these headers cover entries written by an older deploy.
+ */
+function readCacheEntryFetchedAtMs(hit) {
+    const ageHeader = hit.headers.get('age');
+    if (ageHeader !== null && ageHeader.trim().length > 0) {
+        const ageSeconds = Number(ageHeader);
+        if (Number.isFinite(ageSeconds) && ageSeconds >= 0)
+            return Date.now() - ageSeconds * 1000;
+    }
+    const dateHeader = hit.headers.get('date');
+    if (dateHeader) {
+        const parsed = Date.parse(dateHeader);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return null;
+}
+/** A JWKS body: a `keys` list. The keys themselves are parsed by `jose` when the set is built. */
+const jsonWebKeySetSchema = z.looseObject({
+    keys: z.array(z.looseObject({ kty: z.string().optional(), kid: z.string().optional() }))
+});
+/** What the Cache API holds: the envelope this module writes, or a bare key set an older deploy wrote. */
+const cachedJwksBodySchema = z.union([
+    z.looseObject({
+        jwks: jsonWebKeySetSchema,
+        cachedAtMs: z.number().optional().catch(undefined)
+    }),
+    jsonWebKeySetSchema.transform((jwks) => ({ jwks, cachedAtMs: undefined }))
+]);
+async function readJwksFromCache(runtime, jwksOrigin) {
+    const store = getCacheStore();
+    if (!store)
+        return null;
+    // Declared-optional cache read: a miss (or an unreadable entry) refetches from the issuer.
+    const read = await attempt(async () => {
+        const hit = await store.match(jwksCacheRequest(jwksOrigin));
+        if (!hit)
+            return null;
+        const headerFetchedAtMs = readCacheEntryFetchedAtMs(hit);
+        // Envelope written by this module — the write time travels WITH the keys, so
+        // freshness never depends on an edge header we don't control. A bare key set
+        // (an older deploy) is only as fresh as its headers say, possibly not at all.
+        const body = cachedJwksBodySchema.safeParse(await hit.json());
+        if (!body.success)
+            return null;
+        return { jwks: body.data.jwks, fetchedAtMs: body.data.cachedAtMs ?? headerFetchedAtMs };
+    });
+    if (read.ok)
+        return read.value;
+    getLogger('auth.jwt-session', runtime).debug('JWKS cache read failed; treating as a miss', { failure: failureLabel(read.failure) });
+    return null;
+}
+async function writeJwksToCache(runtime, jwksOrigin, jwks, fetchedAtMs) {
+    const store = getCacheStore();
+    if (!store)
+        return;
+    // Declared-optional cache write: a failure just means the next isolate refetches.
+    const written = await attempt(() => store.put(jwksCacheRequest(jwksOrigin), 
+    // The envelope carries the issuer-pull time so a later reader can charge
+    // the entry's own age against the TTL. An older deploy reading this body
+    // finds no `keys` and simply refills — it never mistakes it for keys.
+    new Response(JSON.stringify({ cachedAtMs: fetchedAtMs, jwks }), {
+        headers: {
+            'content-type': 'application/json',
+            // Cache API evicts past max-age → bounds staleness without a manual sweep.
+            'cache-control': `max-age=${Math.floor(JWKS_TTL_MS / 1000)}`
+        }
+    })));
+    if (!written.ok)
+        getLogger('auth.jwt-session', runtime).debug('JWKS cache write failed', { failure: failureLabel(written.failure) });
+}
+/** A fetched JWKS body: `{ keys }` or `{ jwks: { keys } }`, with at least one key. */
+const issuerJwksBodySchema = z.union([
+    jsonWebKeySetSchema,
+    z.looseObject({ jwks: jsonWebKeySetSchema }).transform((body) => body.jwks)
+]);
+function asJsonWebKeySet(body) {
+    const parsed = issuerJwksBodySchema.safeParse(body);
+    return parsed.success && parsed.data.keys.length > 0 ? parsed.data : null;
+}
+async function fetchJwksFromIssuer(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs) {
+    // Bounded two ways: AbortSignal (cooperative fetchers) AND Promise.race
+    // (CF Fetcher / public-edge loopback, which ignore abort and otherwise
+    // own the incoming socket until the ~30s isolate wall clock).
+    const jwksUrl = viaServiceBinding
+        ? issuerBindingUrl('/api/auth/jwks')
+        : new URL('/api/auth/jwks', jwksOrigin).toString();
+    try {
+        return await withTimeout(runtime, (async () => {
+            const controller = new AbortController();
+            const disarm = runtime.lifecycle.timeout(() => controller.abort(), timeoutMs);
+            try {
+                const res = await fetcher(jwksUrl, {
+                    // Refills establish verification trust and are already amortized by the
+                    // package-owned memo. Revalidate the issuer instead of accepting a
+                    // long-lived shared-edge entry written by another Worker cache.
+                    headers: { accept: 'application/json', 'cache-control': 'no-cache' },
+                    signal: controller.signal
+                });
+                if (!res.ok)
+                    throw new Error(`JWKS fetch failed: ${res.status}`);
+                const jwks = asJsonWebKeySet(await res.json());
+                if (!jwks)
+                    throw new Error('JWKS fetch returned no keys');
+                return jwks;
+            }
+            finally {
+                disarm();
+            }
+        })(), timeoutMs, `JWKS fetch timed out after ${timeoutMs}ms`);
+    }
+    catch (error) {
+        if (error instanceof CapabilityError)
+            throw error;
+        throw new CapabilityError('JWKS verification dependency is unavailable.', 'UNAVAILABLE', {
+            reason: 'jwks-unavailable'
+        });
+    }
+}
+/**
+ * Memoize a key set in this isolate. `fetchedAtMs` is when the set was pulled
+ * FROM THE ISSUER — not when we happened to read it — so the TTL measures key
+ * age, not memo age. Passing `Date.now()` for a Cache hit would re-extend an
+ * already-old entry to a full fresh TTL, doubling how long a revoked key keeps
+ * verifying (a 59-minute-old hit memoized for another 60).
+ */
+function memoizeJwks(runtime, jwksOrigin, jwks, fetchedAtMs, expected) {
+    return memoizeJwksUntil(runtime, jwksOrigin, jwks, fetchedAtMs + JWKS_TTL_MS, expected);
+}
+function memoizeJwksUntil(runtime, jwksOrigin, jwks, expiresAtMs, expected) {
+    const state = getRuntimeSessionState(runtime, expected);
+    const entry = { resolver: createLocalJWKSet(jwks), expiresAtMs };
+    state.jwksByOrigin.set(jwksOrigin, entry);
+    return entry;
+}
+/** Pull fresh keys from the issuer, cache them, memoize them. Concurrent callers
+ *  in one isolate share ONE in-flight pull rather than stampeding the issuer. */
+function refillJwksEntry(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs) {
+    const state = getRuntimeSessionState(runtime);
+    const existing = state.jwksRefillInFlight.get(jwksOrigin);
+    if (existing)
+        return existing;
+    const inFlight = (async () => {
+        // Stamped BEFORE the fetch: if the pull is slow the keys are treated as
+        // slightly older than they are, never younger.
+        const fetchedAtMs = Date.now();
+        const fetched = await fetchJwksFromIssuer(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs);
+        getRuntimeSessionState(runtime, state);
+        await writeJwksToCache(runtime, jwksOrigin, fetched, fetchedAtMs);
+        return memoizeJwks(runtime, jwksOrigin, fetched, fetchedAtMs, state);
+    })();
+    state.jwksRefillInFlight.set(jwksOrigin, inFlight);
+    const clear = () => {
+        if (state.jwksRefillInFlight.get(jwksOrigin) === inFlight)
+            state.jwksRefillInFlight.delete(jwksOrigin);
+    };
+    // `attempt` settles instead of rejecting: the derived promise must not re-throw a
+    // rejected refill as an unhandled rejection. Real callers still see the
+    // rejection on `inFlight` itself.
+    void attempt(() => inFlight).then(clear);
+    return inFlight;
+}
+/** Resolve a verification key set: isolate memo → Cache API → issuer binding fetch. */
+async function getJwksEntry(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs) {
+    const state = getRuntimeSessionState(runtime);
+    const memo = state.jwksByOrigin.get(jwksOrigin);
+    if (memo && memo.expiresAtMs > Date.now())
+        return memo;
+    const cached = await readJwksFromCache(runtime, jwksOrigin);
+    if (cached) {
+        // A hit is only as fresh as the entry itself — the Cache API does not
+        // rewrite an entry when it is read.
+        if (cached.fetchedAtMs !== null) {
+            if (cached.fetchedAtMs + JWKS_TTL_MS > Date.now()) {
+                return memoizeJwks(runtime, jwksOrigin, cached.jwks, cached.fetchedAtMs, state);
+            }
+            // Known-age and already past the TTL: refill rather than serve it.
+        }
+        else {
+            // Age unknown (a legacy pre-envelope entry). Still serve it — a warm
+            // cache entry is what decouples every consumer from a cold auth-web —
+            // but hold it only briefly instead of inventing a fresh full TTL.
+            return memoizeJwksUntil(runtime, jwksOrigin, cached.jwks, Date.now() + JWKS_UNKNOWN_AGE_MEMO_MS, state);
+        }
+    }
+    return refillJwksEntry(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs);
+}
+/** Force a fresh issuer pull (bypassing memo + Cache), cooldown-guarded so a burst
+ *  of unknown-`kid` tokens can't hammer the issuer. Returns null when on cooldown. */
+async function refreshJwksEntry(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs) {
+    const state = getRuntimeSessionState(runtime);
+    const last = state.jwksForceRefreshAtMs.get(jwksOrigin) ?? 0;
+    if (Date.now() - last < JWKS_FORCE_REFRESH_COOLDOWN_MS)
+        return null;
+    state.jwksForceRefreshAtMs.set(jwksOrigin, Date.now());
+    return refillJwksEntry(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs);
+}
+/** jose signals a `kid` absent from the current key set — the tell for a rotation
+ *  the cached JWKS predates (as opposed to a bad signature, which must NOT refetch). */
+function isNoMatchingKeyError(failure) {
+    return (valueFreeFailure(failure).code === 'ERR_JWKS_NO_MATCHING_KEY' ||
+        (failure instanceof Error && failure.name === 'JWKSNoMatchingKey'));
+}
+/** Normalize both token and session-ID storage failures at the verification owner. */
+async function readRevocation(blacklist, key) {
+    try {
+        return await blacklist.get(key);
+    }
+    catch (cause) {
+        throw new CapabilityError('Session revocation storage is unavailable.', 'UNAVAILABLE', {
+            cause,
+            reason: 'session-blacklist-unavailable'
+        });
+    }
+}
+/** Reject a verified JWT whose `sessionId` claim was revoked by admin session termination. */
+async function assertSessionIdNotRevoked(blacklist, payload) {
+    const sessionId = z.string().min(1).safeParse(payload.sessionId);
+    if (!sessionId.success)
+        return;
+    if (await readRevocation(blacklist, sessionIdRevocationKey(sessionId.data))) {
+        throw new CapabilityError('Session has been revoked.', 'AUTH_REQUIRED', {
+            reason: 'session-revoked'
+        });
+    }
+}
+async function verifyAuthJwt(token, authOrigin, fetcher, options) {
+    const verifier = await options.runtime.query(SESSION_VERIFIER_KIND).withId(SESSION_VERIFIER_ID).resolve();
+    return verifier.verify({ token, authOrigin, fetcher, jwksFetchTimeoutMs: options.jwksFetchTimeoutMs, viaServiceBinding: options.viaServiceBinding });
+}
+export async function verifyBoundAuthJwt(token, authOrigin, fetcher, options) {
+    const runtime = options.runtime;
+    await getVibesClient('auth', runtime);
+    getRuntimeSessionState(runtime);
+    const blacklist = runtime.getBinding('SESSION_BLACKLIST', SessionBlacklistReaderSchema);
+    if (!blacklist) {
+        throw new CapabilityError('Session blacklist KV namespace (SESSION_BLACKLIST) is not bound.', 'UNAVAILABLE', { reason: 'session-blacklist-unavailable' });
+    }
+    for (const key of await sessionRevocationKeys(token)) {
+        if (await readRevocation(blacklist, key)) {
+            throw new CapabilityError('Session token has been revoked.', 'AUTH_REQUIRED', { reason: 'session-revoked' });
+        }
+    }
+    const jwksOrigin = resolveJwksOrigin(authOrigin);
+    const viaServiceBinding = options.viaServiceBinding === true;
+    const timeoutMs = options.jwksFetchTimeoutMs;
+    const issuer = isLocalAuthOrigin(authOrigin)
+        ? [
+            ...new Set([
+                authOrigin,
+                resolveLocalAuthOrigin(authOrigin),
+                VIBES_LOCAL_AUTH_ORIGIN
+            ])
+        ]
+        : authOrigin;
+    // Local auth has two equivalent ingress names: the canonical auth.vibes.local
+    // origin and the direct PM port. Depending on which path minted the JWT, either
+    // may appear in `iss`; the signing key and audience are still verified normally.
+    // Production remains a single exact issuer.
+    const verifyOpts = { issuer, audience: 'vibes-apps' };
+    const verifyWith = async (resolver) => {
+        const { payload } = await jwtVerify(token, resolver, verifyOpts);
+        await assertSessionIdNotRevoked(blacklist, payload);
+        getRuntimeSessionState(runtime);
+        return payload;
+    };
+    const entry = await getJwksEntry(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs);
+    const first = await attempt(() => verifyWith(entry.resolver));
+    if (first.ok)
+        return first.value;
+    if (!isNoMatchingKeyError(first.failure))
+        return rethrowFailure(first.failure);
+    // Unknown `kid`: the issuer likely rotated keys since we cached. Pull fresh
+    // once (cooldown-guarded) and retry; on cooldown, surface the original miss.
+    const refreshed = await refreshJwksEntry(runtime, jwksOrigin, fetcher, viaServiceBinding, timeoutMs);
+    if (!refreshed)
+        return rethrowFailure(first.failure);
+    return verifyWith(refreshed.resolver);
+}
+/** The actor fields an org/tenant gate needs. Deliberately a SUBSET of the session user —
+ *  a delegated call proves who the end user is, not that they hold a live session here. */
+// The public projection and result types are inferred from Auth's owning schemas.
+/**
+ * Verify a JWT that a TRUSTED internal service forwarded on an end user's behalf, and return
+ * only the claims a tenant gate reads.
+ *
+ * Why this exists. A service-to-service call (chat-web → ai-web's agent run/stream, the
+ * agent-execution tool) carries no session cookie, so `locals.user` is null and every
+ * org-scope check downstream sees a null actor. Two bad options follow from that: deny every
+ * org-scoped agent over the delegated path, or skip the tenant check for delegated callers —
+ * which reopens the IDOR the per-agent org gate exists to close, because the delegating
+ * surface applies no org gate of its own and the agent id is caller-controlled.
+ *
+ * The third option is this one: the delegating service already forwards the ACTOR'S OWN JWT
+ * (strip-protected, so staged or model-authored metadata cannot forge it), and that JWT
+ * carries the same `orgs` / `staff` claims `locals.user` is built from. Verifying it here
+ * gives the delegated path the SAME evidence the session path has, from the same issuer,
+ * through the same JWKS — rather than a second, weaker notion of "who is acting".
+ *
+ * Verification is the full session-handle path (issuer + `vibes-apps` audience + JWKS with
+ * kid-rotation retry); this is not a decode. Credential refusals return a typed invalid
+ * result. Revocation/JWKS dependency failures reject, preserving CapabilityError.
+ * The compatible nullable entrypoint below projects every unsuccessful result to null.
+ */
+export async function verifyDelegatedActorClaimsResult(input) {
+    const options = delegatedActorVerificationOptionsSchema.parse(input);
+    const token = options.token?.trim();
+    if (!token)
+        return { status: 'invalid', reason: 'missing' };
+    const runtime = options.runtime;
+    const authOrigin = assertAuthOrigin(options.authOrigin);
+    const serviceBindingFetcher = options.serviceBindingFetcher ??
+        serviceBindingFetcherFrom(runtime, isLocalAuthOrigin(authOrigin) ? null : 'AUTH_SERVICE');
+    const viaServiceBinding = Boolean(options.fetcher === undefined && serviceBindingFetcher);
+    const verified = await attempt(async () => {
+        const knobs = await readSessionHandleKnobs(runtime);
+        return verifyAuthJwt(token, authOrigin, resolveFetcher(options.fetcher, serviceBindingFetcher), {
+            viaServiceBinding,
+            jwksFetchTimeoutMs: options.jwksFetchTimeoutMs ?? knobs.jwksFetchTimeoutMs,
+            runtime
+        });
+    });
+    if (!verified.ok) {
+        const failure = verified.failure;
+        if (failure instanceof CapabilityError && failure.code === 'AUTH_REQUIRED' && failure.reason === 'session-revoked') {
+            return { status: 'invalid', reason: 'revoked' };
+        }
+        if (failure instanceof errors.JWTExpired ||
+            failure instanceof errors.JWTClaimValidationFailed ||
+            failure instanceof errors.JWTInvalid ||
+            failure instanceof errors.JWSInvalid ||
+            failure instanceof errors.JWSSignatureVerificationFailed ||
+            failure instanceof errors.JWKSNoMatchingKey ||
+            failure instanceof errors.JOSEAlgNotAllowed) {
+            const reason = failure instanceof errors.JWTExpired ? 'expired'
+                : failure instanceof errors.JWTClaimValidationFailed ? 'scope' : 'invalid';
+            return { status: 'invalid', reason };
+        }
+        return rethrowFailure(failure);
+    }
+    const payload = verified.value;
+    const userId = z.string().min(1).safeParse(payload.sub);
+    if (!userId.success)
+        return { status: 'invalid', reason: 'invalid' };
+    return delegatedActorVerificationSchema.parse({
+        status: 'verified',
+        claims: {
+            userId: userId.data,
+            orgs: normalizeOrgClaims(payload.orgs),
+            staff: payload.staff === true,
+            isSuperuser: payload.isSuperuser === true
+        }
+    });
+}
+/** Issuer endpoint projection. Decode only the exact token the full verifier just accepted. */
+export async function verifySessionJwtResult(input) {
+    const options = delegatedActorVerificationOptionsSchema.parse(input);
+    const token = options.token?.trim();
+    if (!token)
+        return { status: 'invalid', reason: 'missing' };
+    const verdict = await verifyDelegatedActorClaimsResult({ ...options, token });
+    if (verdict.status === 'invalid')
+        return verdict;
+    return SessionJwtVerificationSchema.parse({ status: 'verified', payload: decodeJWTUnsafe(token) });
+}
+/** Compatibility projection: every unsuccessful verification remains nullable. */
+export async function verifyDelegatedActorClaims(options) {
+    const verified = await attempt(() => verifyDelegatedActorClaimsResult(options));
+    if (!verified.ok) {
+        // Invalid issuer configuration has always been a caller error, not a nullable credential refusal.
+        if (verified.failure instanceof CapabilityError &&
+            verified.failure.code === 'INVALID_INPUT' &&
+            verified.failure.reason === 'auth-origin-invalid')
+            return rethrowFailure(verified.failure);
+        return null;
+    }
+    return verified.value.status === 'verified' ? verified.value.claims : null;
+}
+const API_KEY_CACHE_TTL_MS = 5 * 60 * 1000;
+const API_KEY_CACHE_MAX = 1000;
+/** Test-only cache reset for falsifiers that exercise repeated opaque bearers. */
+export function _resetApiKeyCache(runtime) {
+    tryGetVibesClient('auth', runtime)?.sessionVerificationState.apiKeyCache.clear();
+}
+async function sha256Hex(value) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Validate a vibes API key against auth-web's server-to-server
+ * `/api/api-keys/validate` route and shape the owner as a minimal JWT-like
+ * payload (`sub` + scopes; no org claims — those require a real JWT).
+ * Human-key and negative results are cached. Agent principals are deliberately
+ * never cached: Auth remains authoritative for every use of a revocable,
+ * expiring machine credential.
+ */
+async function verifyApiKeyBearer(runtime, key, authOrigin, fetcher, options) {
+    await getVibesClient('auth', runtime);
+    const cacheKey = await sha256Hex(key);
+    const state = getRuntimeSessionState(runtime);
+    const hit = state.apiKeyCache.get(cacheKey);
+    if (hit && hit.expiresAtMs > Date.now())
+        return hit.payload;
+    const doFetch = fetcher ?? globalThis.fetch;
+    // Bounded two ways (AbortSignal + Promise.race): a hung auth-web, or a
+    // CF Fetcher that ignores abort, must not stall the caller's request.
+    // On timeout the fetch rejects and the caller's rejection handler
+    // degrades to user-less — non-fatal; routes that require a principal
+    // still enforce via their own guards.
+    const validateTimeoutMs = options.timeoutMs;
+    const controller = new AbortController();
+    const disarm = runtime.lifecycle.timeout(() => controller.abort(), validateTimeoutMs);
+    let res;
+    try {
+        const validateUrl = options.viaServiceBinding
+            ? issuerBindingUrl('/api/api-keys/validate')
+            : `${authOrigin.replace(/\/$/, '')}/api/api-keys/validate`;
+        res = await withTimeout(runtime, doFetch(validateUrl, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ key }),
+            signal: controller.signal
+        }), validateTimeoutMs, `API-key validate timed out after ${validateTimeoutMs}ms`);
+    }
+    finally {
+        disarm();
+    }
+    let payload = null;
+    if (res.ok) {
+        const body = ApiKeyValidationResponseSchema.safeParse(await readJsonOrNull(res));
+        if (body.success && body.data.valid) {
+            payload = {
+                sub: body.data.userId,
+                scopes: body.data.scopes,
+                authMethod: 'api-key'
+            };
+            if (body.data.principal?.kind === 'agent') {
+                payload.agentPrincipal = authenticatedAgentPrincipalSchema.parse(body.data.principal);
+                payload.roles = ['agent'];
+            }
+        }
+    }
+    getRuntimeSessionState(runtime, state);
+    if (payload?.agentPrincipal === undefined) {
+        if (state.apiKeyCache.size >= API_KEY_CACHE_MAX) {
+            // Evict the OLDEST entry (Map preserves insertion order) rather than wiping
+            // the whole cache. A full .clear() at the cap invalidated every still-valid
+            // cached key at once, causing a thundering herd of re-validations against
+            // auth-web the instant the cache filled.
+            const oldest = state.apiKeyCache.keys().next().value;
+            if (oldest !== undefined)
+                state.apiKeyCache.delete(oldest);
+        }
+        state.apiKeyCache.set(cacheKey, { expiresAtMs: Date.now() + API_KEY_CACHE_TTL_MS, payload });
+    }
+    return payload;
+}
+/** The claims `applyJwtPayload` reads; a claim of another type is absent (old tokens predate several of them). */
+const sessionClaimsSchema = z.looseObject({
+    email: z.string().optional().catch(undefined),
+    name: z.string().optional().catch(undefined),
+    slug: z.string().optional().catch(undefined),
+    org: z.string().optional().catch(undefined),
+    sessionId: z.string().optional().catch(undefined)
+});
+function applyJwtPayload(locals, payload) {
+    const agentPrincipal = authenticatedAgentPrincipalSchema.safeParse(payload.agentPrincipal);
+    const claims = sessionClaimsSchema.parse(payload);
+    const user = {
+        id: payload.sub,
+        email: claims.email ?? '',
+        // Display name from auth-web's `definePayload`. Old JWTs predating the
+        // claim fall through to undefined until the next sign-in / 15m refresh.
+        name: claims.name,
+        // User handle (slug) from `definePayload`. Consumers (forge user-repo
+        // namespace → `git.vibes.dev/~<slug>/<repo>`) read it off locals. Absent
+        // on tokens predating the claim → undefined (provider falls back to id).
+        slug: claims.slug !== undefined && claims.slug.length > 0 ? claims.slug : undefined,
+        orgId: claims.org,
+        // Org-membership claim — set exclusively by auth-web's `definePayload`
+        // (the single seam). Consumer apps (e.g. git-web's
+        // `getRepositoryPermission`) read this off `event.locals.user.orgs`
+        // instead of querying account-web per request. Defaults to `[]` for
+        // tokens issued before the claim existed.
+        orgs: normalizeOrgClaims(payload.orgs),
+        roles: Array.isArray(payload.roles) ? payload.roles : undefined,
+        // Admin-gate booleans — auth-web's JWT `definePayload` sets these from
+        // the `staff` / `is_superuser` columns. `requireAdminScope` reads them
+        // directly off `event.locals.user`. Old JWTs that predate the claim
+        // fall through to `false`, so users issued tokens before the auth-web
+        // deploy lose admin access until their next sign-in or 15m refresh.
+        staff: payload.staff === true,
+        isSuperuser: payload.isSuperuser === true
+    };
+    locals.user = agentPrincipal.success ? { ...user, agentPrincipal: agentPrincipal.data } : user;
+    locals.session = {
+        id: claims.sessionId,
+        validUntil: payload.exp
+    };
+}
+function extractBearerToken(header) {
+    if (!header)
+        return null;
+    // RFC 6750 Bearer auth: `Authorization: Bearer <token>`. Allow any
+    // whitespace between scheme and token; tolerate leading/trailing space
+    // on the token itself. Match scheme case-insensitively per the RFC.
+    const match = header.match(/^\s*Bearer\s+(.+?)\s*$/i);
+    if (!match)
+        return null;
+    const token = match[1].trim();
+    return token.length > 0 ? token : null;
+}
+function hasRefreshSessionCookie(headers) {
+    const cookieHeader = headers.get('cookie');
+    if (!cookieHeader)
+        return false;
+    for (const part of cookieHeader.split(';')) {
+        const name = part.trim().split('=', 1)[0];
+        if (REFRESH_SESSION_COOKIE_NAMES.has(name))
+            return true;
+    }
+    return false;
+}
+function upsertRequestCookie(runtime, headers, name, value) {
+    const cookieHeader = headers.get('cookie') ?? '';
+    const parts = cookieHeader
+        .split(';')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0 && part.split('=', 1)[0] !== name);
+    parts.push(`${name}=${value}`);
+    // Best-effort: some runtimes expose immutable request headers. The response cookie
+    // still refreshes the browser; this mutation only helps same-request
+    // server-to-server calls forward the fresh JWT.
+    const written = attemptSync(() => headers.set('cookie', parts.join('; ')));
+    if (!written.ok)
+        getLogger('auth.jwt-session', runtime).debug('Request headers are immutable here; the refreshed cookie was not set on them', { failure: failureLabel(written.failure) });
+}
+// A cross-subdomain FIRST request carries no host-scoped `vibes.jwt` yet, so it
+// ALWAYS lands in this refresh path — and the JWT mint depends on a session read
+// against a possibly-cold D1. That read races: observed in prod as GET
+// auth.vibes.dev/api/auth/token → 401 → 401 → 200 within ~120ms (the session row
+// resolves on a warm retry). A single-attempt refresh turned that transient into
+// `locals.user = null` → the user's FIRST action ("send a message") 401'd
+// "Authentication required", then a manual re-send worked. Retry the session read a
+// few times on a transient (non-ok / network) failure so the first request
+// resolves cleanly. A clean `{ authenticated: false }` (genuine no-session) is NOT
+// retried. See docs/audits + reference_auth_cold_start_hang_waituntil.
+const SESSION_REFRESH_MAX_ATTEMPTS = 3;
+const SESSION_REFRESH_RETRY_BACKOFF_MS = 120;
+/** HTTP statuses from /api/session that plausibly reflect a cold-start/session race, not a real deny. */
+const RETRYABLE_SESSION_REFRESH_STATUSES = new Set([401, 408, 425, 429, 500, 502, 503, 504]);
+/** What `/api/session` answers: whether there is a session, and its JWT when the mint succeeded. */
+const sessionRefreshBodySchema = z.looseObject({
+    authenticated: z.boolean().optional().catch(undefined),
+    jwt: z.string().optional().catch(undefined)
+});
+/** One `/api/session` attempt: a refreshed token, no session, or a transient answer worth retrying. */
+async function refreshOnce(input, url, attemptNumber, logger) {
+    const controller = new AbortController();
+    const disarm = input.runtime.lifecycle.timeout(() => controller.abort(), input.timeoutMs);
+    try {
+        const response = await input.fetcher(url, {
+            headers: {
+                accept: 'application/json',
+                cookie: input.requestHeaders.get('cookie') ?? ''
+            },
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            // Only a transient status warrants a retry; anything else is a real refusal.
+            if (attemptNumber < SESSION_REFRESH_MAX_ATTEMPTS &&
+                RETRYABLE_SESSION_REFRESH_STATUSES.has(response.status)) {
+                logger.warn('[sessionHandle] session refresh transient non-ok; retrying', {
+                    status: response.status,
+                    attempt: attemptNumber
+                });
+                return { kind: 'retry' };
+            }
+            return { kind: 'none' };
+        }
+        const body = sessionRefreshBodySchema.safeParse(await response.json());
+        // A clean authenticated:false is a genuine no-session — never retry it.
+        // (auth-web returns 200 {authenticated:false} for both a real logout AND a
+        // swallowed transient session read, so we can't distinguish here — the source
+        // fix in getAuthSessionState retries the null-with-cookie read instead.)
+        if (!body.success || body.data.authenticated !== true)
+            return { kind: 'none' };
+        // authenticated:true but NO jwt = the token MINT transiently failed
+        // (auth-web getToken swallows its own mint error into null), NOT a real no-session. The user
+        // IS logged in; retry to obtain their token rather than nulling them → 401.
+        const jwt = body.data.jwt;
+        if (jwt === undefined || jwt.length === 0) {
+            if (attemptNumber < SESSION_REFRESH_MAX_ATTEMPTS) {
+                logger.warn('[sessionHandle] session authenticated but token mint empty; retrying', {
+                    attempt: attemptNumber
+                });
+                return { kind: 'retry' };
+            }
+            return { kind: 'none' };
+        }
+        const payload = await verifyAuthJwt(jwt, input.authOrigin, input.jwksFetcher, {
+            viaServiceBinding: input.viaServiceBinding === true,
+            jwksFetchTimeoutMs: input.jwksFetchTimeoutMs,
+            runtime: input.runtime
+        });
+        const cookieDomain = resolveCookieDomain(input.authOrigin);
+        const cookie = {
+            httpOnly: true,
+            sameSite: input.requestUrl.protocol === 'https:' ? 'none' : 'lax',
+            secure: input.requestUrl.protocol === 'https:',
+            path: '/',
+            maxAge: JWT_MAX_AGE_SECONDS
+        };
+        if (cookieDomain)
+            cookie.domain = cookieDomain;
+        input.setCookie(JWT_COOKIE_NAME, jwt, cookie);
+        return { kind: 'refreshed', value: { token: jwt, payload } };
+    }
+    finally {
+        disarm();
+    }
+}
+async function refreshJwtFromAuthSession(input) {
+    const url = new URL('/api/session', resolveLocalAuthOrigin(input.authOrigin));
+    if (input.clientName)
+        url.searchParams.set('client', input.clientName);
+    const logger = getLogger(`${input.clientName || 'app'}.session`, input.runtime);
+    for (let attemptNumber = 1; attemptNumber <= SESSION_REFRESH_MAX_ATTEMPTS; attemptNumber += 1) {
+        const step = await attempt(() => refreshOnce(input, url, attemptNumber, logger));
+        if (step.ok) {
+            if (step.value.kind === 'refreshed')
+                return step.value.value;
+            if (step.value.kind === 'none')
+                return null;
+        }
+        else {
+            rethrowIfBlacklistUnavailable(step.failure);
+            // Network / abort (cold-start timeout) — retry unless this was the last attempt.
+            if (attemptNumber >= SESSION_REFRESH_MAX_ATTEMPTS)
+                return rethrowFailure(step.failure);
+            logger.warn('[sessionHandle] session refresh threw; retrying', {
+                failure: failureLabel(step.failure),
+                attempt: attemptNumber
+            });
+        }
+        await input.runtime.lifecycle.delay(SESSION_REFRESH_RETRY_BACKOFF_MS * attemptNumber);
+    }
+    return null;
+}
+function resolveCookieDomain(authOrigin) {
+    const hostname = new URL(authOrigin).hostname;
+    if (hostname === 'localhost' ||
+        /^\d{1,3}(?:\.\d{1,3}){3}$/.test(hostname) ||
+        hostname.includes(':')) {
+        return undefined;
+    }
+    const parts = hostname.split('.').filter(Boolean);
+    if (parts.length < 2)
+        return undefined;
+    return `.${parts.slice(-2).join('.')}`;
+}
+//# sourceMappingURL=jwt-session-handle.js.map