@fabrika/proxy-core 0.0.1

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "@fabrika/proxy-core",
+	"version": "0.0.1",
+	"type": "module",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/proxy-core"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/__tests__/**"
+	],
+	"exports": {
+		".": {
+			"bun": "./src/index.ts",
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@fabrika/auth-core": "^0.0.1",
+		"@fabrika/proxy-contract": "^0.0.1",
+		"jose": "^5.9.0"
+	}
+}

package/src/authorize.ts

@@ -0,0 +1,406 @@
+/**
+ * The proxy authorization core ([ADR-0007](../../../docs/decisions/0007-proxy-based-auth-enforcement.md)).
+ *
+ * Same four steps, same order, same fail-closed posture:
+ *   1. match the request path against the app's ordered gate rules;
+ *   2. resolve the credential the matched rule requires (cookie session, `px_` key, passthrough JWT);
+ *   3. exchange it with IAM once, cache the result, and thereafter verify LOCALLY against the JWKS;
+ *   4. deny unless a rule was satisfied.
+ *
+ * A human miss becomes a bounce to IAM's `/auth/login`, in whichever shape the caller can act on: a
+ * 302 for a document navigation, a 401 carrying the same URL in a JSON body for everything else (see
+ * `isDocumentNavigation`). Caddy returns a non-2xx auth response — status, headers and body — to the
+ * client verbatim, so both reach the caller and neither reaches the app. A request with no session
+ * cookie needs no IAM call.
+ *
+ * NOTHING here returns an allow on an unexpected condition. Every `catch` maps to a deny.
+ */
+
+import { API_KEY_PREFIX, AUTH_CODE_PARAM, AUTH_HANDOFF_STATE_PARAM, SESSION_COOKIE, TOKEN_REFRESH_SKEW_SECONDS } from '@fabrika/auth-core'
+import type { ProxyApp } from '@fabrika/proxy-contract'
+import { cacheKey, type TokenCache } from './cache'
+import { LOGIN_REDIRECT_PARAM } from './constants'
+import { applicableGates, type CompiledGate, readCookie, readServiceCredential } from './gates'
+import { createHandoffAttempt, type HandoffAttempt, handoffCookieName, setHandoffParams } from './handoff'
+import { type IamGateway, IamUnavailableError } from './iam'
+import { TokenVerifier } from './verifier'
+
+/** Every way a request can be refused. Coarse on purpose — these are logged, not returned to clients. */
+export type DenyReason =
+	/** No gate rule matched the path. The fail-closed default. */
+	| 'no_rule'
+	/** Every matching rule was a `service` rule and no credential was presented. */
+	| 'no_credential'
+	/** A `px_` key or passthrough JWT was presented and is not valid. */
+	| 'invalid_key'
+	| 'no_session'
+	| 'invalid_session'
+	| 'unknown_principal'
+	| 'disabled'
+	/** The `Host` maps to no app in the manifest. */
+	| 'no_app'
+	/** The forwarded-request headers are missing or malformed — we cannot know what was asked for. */
+	| 'bad_forward'
+	/** IAM could not be consulted, or its keys could not be fetched. We do not know; we refuse. */
+	| 'iam_unavailable'
+	/** Anything that escaped. Always a deny. */
+	| 'internal_error'
+
+export type Decision =
+	| {
+		outcome: 'allow'
+		gate: 'public' | 'service' | 'human'
+		/** The verified token to inject upstream. `null` on a `public` gate — no credential, no token. */
+		token: string | null
+		/** Principal id (or credential id) for the log line. Never a secret. */
+		subject: string | null
+	}
+	| { outcome: 'deny'; status: 401 | 403 | 503; reason: DenyReason; clearHandoffState?: string }
+	/**
+	 * A human hit a `human` gate without a usable session. `location` is where they must go to sign
+	 * in; `status` is only how they are TOLD — 302 for a document navigation, 401 for anything else,
+	 * whose body carries the same URL. See `isDocumentNavigation` for why the two differ.
+	 */
+	| { outcome: 'login'; status: 302 | 401; location: string; reason: DenyReason; handoff: HandoffAttempt }
+	/**
+	 * A handoff code was redeemed (ADR-0021). The only outcome that writes the long-lived app
+	 * session: `session` is host-only on this app's host, and `location` is where IAM said the browser
+	 * was going — read from the code server-side, never from the request.
+	 */
+	| { outcome: 'handoff'; status: 302; location: string; session: string; expiresAt: number; handoffState: string }
+
+/** The original request, reconstructed from what `forward_auth` forwarded. */
+export interface ForwardedRequest {
+	/** Original method. Informational — gates are path-only — but logged. */
+	method: string
+	/** Original absolute URL. Its `pathname` drives gate matching; the whole URL is the login return. */
+	url: URL
+	/** The original request's headers, forwarded verbatim by Caddy. */
+	headers: Headers
+	requestId: string
+}
+
+/** An app plus its precompiled gates, built once at startup. */
+export interface ResolvedApp {
+	app: ProxyApp
+	gates: CompiledGate[]
+}
+
+export interface AuthorizerOptions {
+	iam: IamGateway
+	/** IAM's origin — verifies the token `iss` and is the base for the `/auth/login` bounce. */
+	issuer: string
+	/** `null` disables caching entirely. Decisions are identical either way; only the IAM call count changes. */
+	cache?: TokenCache | null
+	/** Unix seconds. Injectable for tests. */
+	now?: () => number
+}
+
+/**
+ * The browser's own description of what issued the request. Read from the FORWARDED headers like
+ * everything else a decision depends on — verified against caddy 2.10.2, whose `forward_auth`
+ * subrequest carries the original `Sec-Fetch-*` verbatim.
+ */
+const FETCH_MODE_HEADER = 'Sec-Fetch-Mode'
+
+/** Why a `human` attempt failed — mirrors `mintToken`'s reasons. */
+type SessionFailureReason = 'no_session' | 'invalid_session' | 'unknown_principal' | 'disabled'
+
+/**
+ * The outcome of resolving the human behind a request. Three arms, not two: "there is no usable
+ * session" bounces the browser to login, but "we could not check" must NOT — an unreachable IAM would
+ * otherwise look like an expired session and put the user in a login loop instead of showing an
+ * incident.
+ */
+type SessionAttempt =
+	| { ok: true; token: string; subject: string }
+	| { ok: false; status: 'miss'; reason: SessionFailureReason }
+	| { ok: false; status: 'unavailable' }
+
+export class Authorizer {
+	private readonly verifier: TokenVerifier
+	private readonly cache: TokenCache | null
+	private readonly now: () => number
+
+	constructor(private readonly options: AuthorizerOptions) {
+		this.now = options.now ?? (() => Math.floor(Date.now() / 1000))
+		this.cache = options.cache ?? null
+		this.verifier = new TokenVerifier(() => options.iam.getJwks(), options.issuer, this.now)
+	}
+
+	/**
+	 * Decide one request. NEVER throws and NEVER returns an allow it did not derive from a verified
+	 * token — the outer `catch` is the last line of the fail-closed guarantee.
+	 */
+	async authorize(resolved: ResolvedApp, request: ForwardedRequest): Promise<Decision> {
+		try {
+			return await this.decide(resolved, request)
+		} catch (err) {
+			if (err instanceof IamUnavailableError) {
+				return { outcome: 'deny', status: 503, reason: 'iam_unavailable' }
+			}
+			return { outcome: 'deny', status: 403, reason: 'internal_error' }
+		}
+	}
+
+	private async decide(resolved: ResolvedApp, request: ForwardedRequest): Promise<Decision> {
+		const matching = applicableGates(resolved.gates, request.url.pathname)
+		if (matching.length === 0) {
+			// Fail closed — the app has no public route of its own, so an unmatched path is denied.
+			return { outcome: 'deny', status: 403, reason: 'no_rule' }
+		}
+
+		// Remembers a human rule's miss (with its precise reason) so the browser is bounced to login
+		// only after every matching rule has been exhausted.
+		let humanMiss: SessionFailureReason | null = null
+		// The human behind a request is resolved AT MOST ONCE. Two matching human rules cannot reach
+		// different verdicts, so a second resolution would only buy a second `mintToken`.
+		let session: SessionAttempt | null = null
+
+		for (const { rule } of matching) {
+			if (rule.kind === 'public') {
+				return { outcome: 'allow', gate: 'public', token: null, subject: null }
+			}
+			if (rule.kind === 'service') {
+				const raw = readServiceCredential(request.headers, request.url, rule.credential)
+				if (raw === null) {
+					continue // absent → fall through to the next matching rule
+				}
+				return await this.authorizeBearer(resolved.app, raw, request.requestId) // present → terminal
+			}
+			session ??= await this.authorizeSession(resolved.app, request)
+			if (session.ok) {
+				return { outcome: 'allow', gate: 'human', token: session.token, subject: session.subject }
+			}
+			if (session.status === 'unavailable') {
+				return { outcome: 'deny', status: 503, reason: 'iam_unavailable' }
+			}
+			if (session.reason !== 'no_session') {
+				return await this.loginDecision(resolved.app, request, session.reason)
+			}
+			humanMiss = session.reason
+		}
+
+		if (humanMiss !== null) {
+			return await this.loginDecision(resolved.app, request, humanMiss)
+		}
+		// Every matching rule was a `service` rule with no credential present.
+		return { outcome: 'deny', status: 401, reason: 'no_credential' }
+	}
+
+	/**
+	 * A `service`-rule bearer. A `px_` opaque key is exchanged via `mintFromKey` (cached, so the hot
+	 * path is a local verify); anything else is treated as an already-signed passthrough token and
+	 * verified locally with no IAM call. A present-but-invalid credential fails closed — no fall-through.
+	 */
+	private async authorizeBearer(app: ProxyApp, bearer: string, requestId: string): Promise<Decision> {
+		if (!bearer.startsWith(API_KEY_PREFIX)) {
+			const verified = await this.verifier.verify(bearer, app.id)
+			if (!verified.ok) {
+				return verified.reason === 'unavailable'
+					? { outcome: 'deny', status: 503, reason: 'iam_unavailable' }
+					: { outcome: 'deny', status: 401, reason: 'invalid_key' }
+			}
+			return { outcome: 'allow', gate: 'service', token: bearer, subject: verified.claims.sub }
+		}
+
+		const key = cacheKey(app.id, 'key', bearer)
+		const cached = this.cache?.get(key)
+		if (cached !== undefined && cached.expiresAt - this.now() > TOKEN_REFRESH_SKEW_SECONDS) {
+			const verified = await this.verifier.verify(cached.token, app.id)
+			if (verified.ok) {
+				return { outcome: 'allow', gate: 'service', token: cached.token, subject: verified.claims.sub }
+			}
+			if (verified.reason === 'unavailable') {
+				// Nothing is wrong with the entry — we simply cannot check it. Keep it; a re-mint could
+				// not be verified either, so it would only add an IAM call to the same 503.
+				return { outcome: 'deny', status: 503, reason: 'iam_unavailable' }
+			}
+			// A cached entry that PROVED bad (rotated key, revoked issuer) is dropped, and we fall
+			// through to a fresh mint rather than trusting it.
+			this.cache?.delete(key)
+		}
+
+		const minted = await this.callIam('mintFromKey', () => this.options.iam.mintFromKey({ app: app.id, key: bearer, requestId }))
+		if (!minted.ok) {
+			return { outcome: 'deny', status: minted.reason === 'invalid_key' ? 401 : 403, reason: minted.reason }
+		}
+		const verified = await this.verifier.verify(minted.token, app.id)
+		if (!verified.ok) {
+			// We just minted it, so a verification miss is a config/clock/key problem — not a client
+			// error. Either way: deny.
+			return verified.reason === 'unavailable'
+				? { outcome: 'deny', status: 503, reason: 'iam_unavailable' }
+				: { outcome: 'deny', status: 401, reason: 'invalid_key' }
+		}
+		this.cache?.set(key, { token: minted.token, expiresAt: minted.expiresAt })
+		return { outcome: 'allow', gate: 'service', token: minted.token, subject: verified.claims.sub }
+	}
+
+	/**
+	 * Resolve a human. Two tiers, cheapest first:
+	 *   1. a cached token minted earlier from the SAME session — no IAM call;
+	 *   2. exchange the `px_session` SSO cookie via `mintToken`.
+	 *
+	 * Every tier additionally requires `ptype: 'user'`: a `human` gate asserts that a resolved USER
+	 * principal exists. Without the check a broken IAM could turn a service token into a human allow.
+	 */
+	private async authorizeSession(app: ProxyApp, request: ForwardedRequest): Promise<SessionAttempt> {
+		const cookieHeader = request.headers.get('Cookie')
+		const now = this.now()
+
+		const session = readCookie(cookieHeader, SESSION_COOKIE)
+		if (session === null) {
+			// DIVERGENCE from the SDK, which calls `mintToken({ session: null })` and lets IAM answer
+			// `no_session`. The proxy sits in front of EVERY request to every app, so an anonymous
+			// flood would otherwise become an IAM flood. The answer is knowable locally; take it.
+			return { ok: false, status: 'miss', reason: 'no_session' }
+		}
+
+		const key = cacheKey(app.id, 'session', session)
+		const cached = this.cache?.get(key)
+		if (cached !== undefined && cached.expiresAt - now > TOKEN_REFRESH_SKEW_SECONDS) {
+			const verified = await this.verifier.verify(cached.token, app.id)
+			if (verified.ok && verified.claims.ptype === 'user') {
+				return { ok: true, token: cached.token, subject: verified.claims.sub }
+			}
+			if (!verified.ok && verified.reason === 'unavailable') {
+				// Nothing is wrong with the entry — we simply cannot check it. Keep it and say so.
+				return { ok: false, status: 'unavailable' }
+			}
+			// Only a token that PROVED bad is dropped (rotated key, revoked issuer, wrong principal).
+			this.cache?.delete(key)
+		}
+
+		const minted = await this.callIam('mintToken', () => this.options.iam.mintToken({ app: app.id, session, requestId: request.requestId }))
+		if (!minted.ok) {
+			return { ok: false, status: 'miss', reason: minted.reason }
+		}
+		const verified = await this.verifier.verify(minted.token, app.id)
+		if (!verified.ok) {
+			// We just minted it, so this is a config/clock/key problem, not a bad session — and if the
+			// key set is unreachable it is an incident, not a reason to bounce the browser to login.
+			return verified.reason === 'unavailable' ? { ok: false, status: 'unavailable' } : { ok: false, status: 'miss', reason: 'invalid_session' }
+		}
+		if (verified.claims.ptype !== 'user') {
+			// `mintToken` always signs `type: 'user'`; anything else means IAM is not what we think.
+			return { ok: false, status: 'miss', reason: 'invalid_session' }
+		}
+		this.cache?.set(key, { token: minted.token, expiresAt: minted.expiresAt })
+		return { ok: true, token: minted.token, subject: verified.claims.sub }
+	}
+
+	/**
+	 * Every IAM call goes through here, so ANY failure — a rejected fetch, a Workers RPC error, a
+	 * gateway that does not honour the `IamUnavailableError` contract — becomes the same deny. The
+	 * gateway is an injected interface; the fail-closed guarantee must not depend on its manners.
+	 */
+	private async callIam<T>(operation: string, call: () => Promise<T>): Promise<T> {
+		try {
+			return await call()
+		} catch (err) {
+			// Never inspect or re-wrap the cause: it can stringify a request URL or a body.
+			throw err instanceof IamUnavailableError ? err : new IamUnavailableError(operation)
+		}
+	}
+
+	/**
+	 * Redeem a handoff code (ADR-0021). Called for the reserved callback path only, BEFORE gate
+	 * matching — the callback is how a browser becomes able to satisfy a gate, so it cannot be behind
+	 * one.
+	 *
+	 * A failed redemption is an ordinary deny with no cookie. It is deliberately not a fresh bounce to
+	 * IAM: a code that will not redeem twice would turn a retry into a loop.
+	 */
+	async authorizeCallback(resolved: ResolvedApp, request: ForwardedRequest): Promise<Decision> {
+		const state = request.url.searchParams.get(AUTH_HANDOFF_STATE_PARAM)
+		if (handoffCookieName(state) === null || state === null) {
+			return { outcome: 'deny', status: 403, reason: 'no_credential' }
+		}
+		try {
+			return await this.redeem(resolved, request, state)
+		} catch (err) {
+			if (err instanceof IamUnavailableError) {
+				return { outcome: 'deny', status: 503, reason: 'iam_unavailable', clearHandoffState: state }
+			}
+			return { outcome: 'deny', status: 403, reason: 'internal_error', clearHandoffState: state }
+		}
+	}
+
+	private async redeem(resolved: ResolvedApp, request: ForwardedRequest, state: string): Promise<Decision> {
+		const code = request.url.searchParams.get(AUTH_CODE_PARAM)
+		if (code === null || code === '') {
+			return { outcome: 'deny', status: 403, reason: 'no_credential', clearHandoffState: state }
+		}
+		const cookieName = handoffCookieName(state)
+		const verifier = cookieName === null ? null : readCookie(request.headers.get('Cookie'), cookieName)
+		if (verifier === null) {
+			return { outcome: 'deny', status: 403, reason: 'invalid_session', clearHandoffState: state }
+		}
+		// Through `callIam` like every other IAM call, so an unreachable service is a 503 whatever kind
+		// of error the injected gateway happened to throw. `authorize`'s outer catch maps the rest.
+		const result = await this.callIam(
+			'exchangeAuthCode',
+			() => this.options.iam.exchangeAuthCode({ app: resolved.app.id, code, verifier, requestId: request.requestId }),
+		)
+		if (!result.ok) {
+			return { outcome: 'deny', status: 403, reason: 'invalid_session', clearHandoffState: state }
+		}
+		return { outcome: 'handoff', status: 302, location: result.returnUrl, session: result.session, expiresAt: result.expiresAt, handoffState: state }
+	}
+
+	private async loginDecision(app: ProxyApp, request: ForwardedRequest, reason: SessionFailureReason): Promise<Decision> {
+		const handoff = await createHandoffAttempt()
+		return {
+			outcome: 'login',
+			status: isDocumentNavigation(request.headers) ? 302 : 401,
+			location: this.loginUrl(app, request.url, handoff),
+			reason,
+			handoff,
+		}
+	}
+
+	/**
+	 * Where to send the browser to log in, returning to the originally requested URL afterwards.
+	 *
+	 * The scheme comes from the MANIFEST, not from the forwarded request: behind a TLS-terminating
+	 * balancer the proxy is reached over plain HTTP and `X-Forwarded-Proto` says so, which would send
+	 * the browser back to an `http://` URL for an origin only served over `https://`.
+	 */
+	private loginUrl(app: ProxyApp, url: URL, handoff: HandoffAttempt): string {
+		const target = new URL(url)
+		target.protocol = `${app.scheme}:`
+		// `readProxyEnv` already reduces the issuer to an origin; this covers a composition root that
+		// does not go through it (the Cloudflare Worker reads its env directly).
+		const issuer = this.options.issuer.replace(/\/+$/, '')
+		const login = new URL('/auth/login', issuer)
+		login.searchParams.set('app', app.id)
+		login.searchParams.set(LOGIN_REDIRECT_PARAM, target.toString())
+		setHandoffParams(login, handoff)
+		return login.toString()
+	}
+}
+
+/**
+ * Is this a top-level document navigation — the one caller a 302 actually helps?
+ *
+ * A redirect is not a neutral way to say "sign in". A cross-origin bounce to IAM is something a
+ * page's `fetch` cannot follow, so the console sees an opaque network failure instead of a sign-in;
+ * and a 302 destroys the request it answers, turning an in-flight POST into a bodyless GET — the same
+ * argument ADR-0021 makes for handing over a session rather than a bare token.
+ *
+ * **`Sec-Fetch-Mode` is the signal, not `Accept`.** It is written by the browser and not by the page:
+ * `Sec-` is a forbidden header PREFIX, so `fetch`/XHR cannot set it, and only a document or frame
+ * navigation carries `navigate` — `fetch()` and XHR emit `cors` / `same-origin` / `no-cors`. `Accept:
+ * text/html` (what the deleted SDK's `wantsHtml` used) is an ordinary header: any XHR may send it and
+ * a navigation may omit it, so it would let the CALLER pick the answer shape instead of describing
+ * what the caller is.
+ *
+ * **Absent → 302**, the answer this proxy has always given. A client old enough to omit the header is
+ * overwhelmingly a browser navigating, and a JSON body is unusable to one; a non-browser client that
+ * sends no `Sec-Fetch-Mode` is no worse off than before this distinction existed.
+ */
+function isDocumentNavigation(headers: Headers): boolean {
+	const mode = headers.get(FETCH_MODE_HEADER)
+	return mode === null || mode === '' || mode === 'navigate'
+}

package/src/constants.ts

@@ -0,0 +1,48 @@
+/**
+ * The wire names the proxy and its Caddy config agree on. Both sides are generated from this file
+ * (`caddy.ts` reads the same constants the service does), so a rename cannot desynchronise them.
+ */
+
+export { CLIENT_ADDRESS_HEADER, PROXY_TOKEN_HEADER, UNTRUSTED_FORWARD_HEADERS } from '@fabrika/auth-core'
+
+// ── What Caddy's `forward_auth` sends us ───────────────────────────────────────
+//
+// `forward_auth` rewrites the subrequest to `GET <uri>`, so the ORIGINAL method and URI arrive only
+// in these headers. `reverse_proxy` adds the other three X-Forwarded-* itself. Everything the gate
+// decision depends on comes from here — never from the `/verify` request's own method/path.
+
+export const FORWARDED_METHOD_HEADER = 'X-Forwarded-Method'
+export const FORWARDED_URI_HEADER = 'X-Forwarded-Uri'
+export const FORWARDED_HOST_HEADER = 'X-Forwarded-Host'
+export const FORWARDED_PROTO_HEADER = 'X-Forwarded-Proto'
+
+/** Correlation id, when the edge supplies one; otherwise the proxy generates a UUIDv7. */
+export const REQUEST_ID_HEADER = 'X-Request-Id'
+
+/** The auth service's decision endpoint (Caddy's `uri` subdirective). */
+export const DEFAULT_VERIFY_PATH = '/verify'
+/** Liveness endpoint on the auth service itself — never routed publicly. */
+export const DEFAULT_HEALTH_PATH = '/healthz'
+/**
+ * Query parameter the generated Caddy route pins the app id with. Explicit beats host-sniffing: the
+ * route already knows which app it fronts, so the auth service never has to infer it.
+ */
+export const APP_QUERY_PARAM = 'app'
+
+/**
+ * Query parameter IAM's `/auth/login` takes the return URL in (ADR-0021). The proxy writes it on the
+ * login bounce and redacts it out of the access log, where it would re-emit — percent-encoded — a
+ * credential that was just stripped from the logged URI.
+ */
+export const LOGIN_REDIRECT_PARAM = 'redirect'
+
+/** How long a fetched JWKS is reused before a refetch (a kid rotation also forces one on demand). */
+export const JWKS_TTL_SECONDS = 600
+/**
+ * Minimum gap between two unknown-`kid` refetches. Bounds how often a token nobody can verify may
+ * cost an IAM round trip — the token is denied either way, and a real rotation is picked up within it.
+ */
+export const JWKS_REFETCH_COOLDOWN_SECONDS = 30
+
+/** Default IAM request timeout. A hung IAM must deny, not hang every request behind it. */
+export const DEFAULT_IAM_TIMEOUT_MS = 5_000

package/src/gates.ts

@@ -0,0 +1,65 @@
+/**
+ * Credential extraction for the gate evaluator relocated out of the app's process
+ * ([ADR-0007](../../../docs/decisions/0007-proxy-based-auth-enforcement.md)).
+ *
+ * The semantics are `AppGates`', verbatim (see `@fabrika/auth-core`'s `types.ts`):
+ *   - array order IS the precedence;
+ *   - a matching rule whose credential is ABSENT falls through to the next matching rule;
+ *   - a matching rule whose credential is PRESENT is terminal (valid → allow, invalid → deny);
+ *   - a request matching NO rule is denied.
+ *
+ * The canonical matcher and its ordered compiled representation live in `@fabrika/auth-core` so the
+ * gate declaration and its evaluator cannot drift. Credential extraction remains proxy-owned.
+ */
+
+import type { CredentialLocation } from '@fabrika/auth-core'
+
+export { applicableGates, compileGates } from '@fabrika/auth-core'
+export type { CompiledGate } from '@fabrika/auth-core'
+
+// ── Credential extraction ──────────────────────────────────────────────────────
+
+/** The raw `service`-rule credential: the declared location, else `Authorization: Bearer`. Null if absent. */
+export function readServiceCredential(headers: Headers, url: URL, location: CredentialLocation | undefined): string | null {
+	if (location !== undefined) {
+		const raw = extractCredential(headers, url, location)
+		return raw === null || raw === '' ? null : raw
+	}
+	return readBearer(headers.get('Authorization'))
+}
+
+/** Pull the raw credential from a declared location. A header value may be bare or `Bearer <token>`. */
+function extractCredential(headers: Headers, url: URL, source: CredentialLocation): string | null {
+	if (source.in === 'header') {
+		const value = headers.get(source.name)
+		return value === null ? null : (readBearer(value) ?? value.trim())
+	}
+	if (source.in === 'query') {
+		return url.searchParams.get(source.name)
+	}
+	return readCookie(headers.get('Cookie'), source.name)
+}
+
+/** Read the token out of an `Authorization: Bearer <token>` header. Null when absent/non-bearer. */
+export function readBearer(header: string | null): string | null {
+	if (header === null) {
+		return null
+	}
+	const match = /^Bearer\s+(.+)$/i.exec(header.trim())
+	return match ? (match[1]?.trim() ?? null) : null
+}
+
+/** Read a single cookie value out of a raw `Cookie` header. Null when absent or malformed. */
+export function readCookie(header: string | null, name: string): string | null {
+	if (!header) {
+		return null
+	}
+	for (const part of header.split(';')) {
+		const eq = part.indexOf('=')
+		if (eq !== -1 && part.slice(0, eq).trim() === name) {
+			const value = part.slice(eq + 1).trim()
+			return value === '' ? null : value
+		}
+	}
+	return null
+}

package/src/handoff.ts

@@ -0,0 +1,61 @@
+import { AUTH_HANDOFF_CHALLENGE_PARAM, AUTH_HANDOFF_STATE_PARAM, FABRIKA_COOKIE_PREFIX, HANDOFF_COOKIE_PREFIX } from '@fabrika/auth-core'
+
+const HANDOFF_VALUE_PATTERN = /^[A-Za-z0-9_-]{16,128}$/
+
+export interface HandoffAttempt {
+	state: string
+	verifier: string
+	challenge: string
+}
+
+/** Create the browser-held verifier and the public values IAM carries through the login. */
+export async function createHandoffAttempt(): Promise<HandoffAttempt> {
+	const state = randomToken(16)
+	const verifier = randomToken(32)
+	return { state, verifier, challenge: await handoffChallenge(verifier) }
+}
+
+/** S256, matching PKCE: the verifier never rides in a URL or reaches IAM through the browser. */
+export async function handoffChallenge(verifier: string): Promise<string> {
+	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+	return base64url(new Uint8Array(digest))
+}
+
+/** Return the dynamic `__Host-` cookie name for a validated public state. */
+export function handoffCookieName(state: string | null): string | null {
+	return state !== null && HANDOFF_VALUE_PATTERN.test(state) ? `${HANDOFF_COOKIE_PREFIX}${state}` : null
+}
+
+/** Add the public handoff coordinates to IAM's login URL. */
+export function setHandoffParams(url: URL, attempt: HandoffAttempt): void {
+	url.searchParams.set(AUTH_HANDOFF_STATE_PARAM, attempt.state)
+	url.searchParams.set(AUTH_HANDOFF_CHALLENGE_PARAM, attempt.challenge)
+}
+
+/** Keep application cookies, but never expose a Fabrika bearer credential to the upstream app. */
+export function stripFabrikaCookies(headers: Headers): void {
+	const raw = headers.get('Cookie')
+	if (raw === null) return
+	const kept = raw.split(';').map((part) => part.trim()).filter((part) => {
+		const separator = part.indexOf('=')
+		const name = separator === -1 ? part : part.slice(0, separator).trim()
+		return !name.startsWith(FABRIKA_COOKIE_PREFIX)
+	})
+	if (kept.length === 0) {
+		headers.delete('Cookie')
+	} else {
+		headers.set('Cookie', kept.join('; '))
+	}
+}
+
+function randomToken(bytes: number): string {
+	const value = new Uint8Array(bytes)
+	crypto.getRandomValues(value)
+	return base64url(value)
+}
+
+function base64url(bytes: Uint8Array): string {
+	let binary = ''
+	for (const byte of bytes) binary += String.fromCharCode(byte)
+	return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '')
+}