@fabrika/proxy-core 0.0.1

package/src/service.ts

@@ -0,0 +1,312 @@
+/**
+ * The `forward_auth` endpoint — a fetch-style `Request → Response` service, written the way
+ * `@fabrika/iam` is so the same code runs on Bun, Node and Workers.
+ *
+ * Caddy's contract (verified against `modules/caddyhttp/reverseproxy/forwardauth/caddyfile.go`):
+ *   - the subrequest is rewritten to `GET /verify` with the ORIGINAL headers, plus
+ *     `X-Forwarded-Method` / `X-Forwarded-Uri`, plus reverse_proxy's `X-Forwarded-{For,Proto,Host}`;
+ *   - a **2xx** response lets the request continue, and each `copy_headers` field is copied onto the
+ *     UPSTREAM request — but ONLY when non-empty (Caddy guards each copy with a `not vars ""` matcher);
+ *   - **any other status** is returned to the client verbatim — status, headers AND body, verified
+ *     against caddy 2.10.2 — so both a 302 to `/auth/login` and a 401 carrying a JSON login envelope
+ *     reach the caller and neither reaches the app.
+ *
+ * The two consequences that shape this file:
+ *   1. the request being authorized is described ENTIRELY by the forwarded headers. Never look at
+ *      this request's own method or path — a missing `X-Forwarded-Uri` must deny, not fall back;
+ *   2. because an empty copy header is a no-op rather than a delete, the generated Caddy config
+ *      strips the token header AND the request id from the inbound request BEFORE `forward_auth`
+ *      runs. Otherwise a client could present its own token header on a `public` path and have it
+ *      reach the app, or choose the correlation id that lands in IAM's audit trail. Both are handed
+ *      back on a 2xx, so the edge is the only thing that mints either.
+ */
+
+import { AUTH_CALLBACK_PATH, HANDOFF_COOKIE_TTL_SECONDS, SESSION_COOKIE, uuidv7 } from '@fabrika/auth-core'
+import type { ProxyManifest } from '@fabrika/proxy-contract'
+import { Authorizer, type AuthorizerOptions, type Decision, type DenyReason, type ForwardedRequest, type ResolvedApp } from './authorize'
+import type { TokenCache } from './cache'
+import {
+	APP_QUERY_PARAM,
+	DEFAULT_HEALTH_PATH,
+	DEFAULT_VERIFY_PATH,
+	FORWARDED_HOST_HEADER,
+	FORWARDED_METHOD_HEADER,
+	FORWARDED_PROTO_HEADER,
+	FORWARDED_URI_HEADER,
+	PROXY_TOKEN_HEADER,
+	REQUEST_ID_HEADER,
+} from './constants'
+import { compileGates } from './gates'
+import { type HandoffAttempt, handoffCookieName } from './handoff'
+import type { IamGateway } from './iam'
+import { type LogFields, type ProxyLogger, redactPath, silentLogger } from './log'
+
+export interface VerifyServiceConfig {
+	manifest: ProxyManifest
+	iam: IamGateway
+	/** IAM's origin — token `iss` and the base of the login bounce. */
+	issuer: string
+	/** `null`/omitted disables the token cache. Same decisions, more IAM calls. */
+	cache?: TokenCache | null
+	logger?: ProxyLogger
+	/** Liveness probe path on the auth service's own port. Default `/healthz`. */
+	healthPath?: string
+	/** Unix seconds. Injectable for tests. */
+	now?: () => number
+}
+
+export type VerifyService = (request: Request) => Promise<Response>
+
+/** A hostname we are willing to build a URL from. Anything else is a malformed forward → deny. */
+const HOST_PATTERN = /^[a-z0-9.\-[\]]+(:\d{1,5})?$/i
+
+/**
+ * Build the `/verify` service. Gates are compiled once here, not per request — the matcher is on the
+ * hot path of every request to every app.
+ */
+export function createVerifyService(config: VerifyServiceConfig): VerifyService {
+	const logger = config.logger ?? silentLogger
+	const healthPath = config.healthPath ?? DEFAULT_HEALTH_PATH
+
+	const byId = new Map<string, ResolvedApp>()
+	const byHost = new Map<string, ResolvedApp>()
+	for (const app of config.manifest.apps) {
+		const resolved: ResolvedApp = { app, gates: compileGates(app.gates) }
+		byId.set(app.id, resolved)
+		for (const host of app.hosts) {
+			// Normalized exactly as a forwarded host is, so the two sides cannot disagree about a port.
+			byHost.set(normalizeHost(host), resolved)
+		}
+	}
+
+	const authorizerOptions: AuthorizerOptions = { iam: config.iam, issuer: config.issuer }
+	if (config.cache !== undefined) {
+		authorizerOptions.cache = config.cache
+	}
+	if (config.now !== undefined) {
+		authorizerOptions.now = config.now
+	}
+	const authorizer = new Authorizer(authorizerOptions)
+
+	return async (request: Request): Promise<Response> => {
+		// Only the edge may supply this: it is written to IAM's `auth_log` and `audit_events`, and the
+		// generated Caddy route (and the Cloudflare Worker) delete a client-supplied one before we run.
+		const suppliedRequestId = request.headers.get(REQUEST_ID_HEADER)
+		const requestId = suppliedRequestId === null || suppliedRequestId === '' ? uuidv7() : suppliedRequestId
+		try {
+			const url = new URL(request.url)
+			if (url.pathname === healthPath) {
+				return new Response('ok', { status: 200, headers: { 'cache-control': 'no-store' } })
+			}
+			if (url.pathname !== DEFAULT_VERIFY_PATH) {
+				return textResponse(404, 'not found')
+			}
+			if (request.method !== 'GET' && request.method !== 'HEAD') {
+				// `forward_auth` always rewrites to GET; anything else did not come from our config.
+				return textResponse(405, 'method not allowed')
+			}
+
+			const forwarded = readForwardedRequest(request, requestId)
+			if (forwarded === null) {
+				return denied(logger, { requestId }, { outcome: 'deny', status: 403, reason: 'bad_forward' })
+			}
+
+			const resolved = selectApp(url, forwarded.url.host, byId, byHost)
+			if (resolved === null) {
+				return denied(logger, { requestId, host: forwarded.url.host, path: redactPath(forwarded.url.pathname) }, {
+					outcome: 'deny',
+					status: 403,
+					reason: 'no_app',
+				})
+			}
+
+			// The handoff callback is checked BEFORE the gates: it is how a browser becomes able to
+			// satisfy one, so it cannot itself be behind one. Because Caddy returns a non-2xx auth
+			// response verbatim, answering 302 + Set-Cookie here reaches the client and never the app.
+			const decision = forwarded.url.pathname === AUTH_CALLBACK_PATH
+				? await authorizer.authorizeCallback(resolved, forwarded)
+				: await authorizer.authorize(resolved, forwarded)
+			const fields: LogFields = {
+				requestId,
+				app: resolved.app.id,
+				host: forwarded.url.host,
+				method: forwarded.method,
+				path: redactPath(forwarded.url.pathname),
+			}
+			if (decision.outcome === 'allow') {
+				logger.info('allow', { ...fields, gate: decision.gate, subject: decision.subject })
+				const headers = new Headers({ 'cache-control': 'no-store', [REQUEST_ID_HEADER]: requestId })
+				if (decision.token !== null) {
+					headers.set(PROXY_TOKEN_HEADER, decision.token)
+				}
+				return new Response(null, { status: 204, headers })
+			}
+			if (decision.outcome === 'handoff') {
+				logger.info('handoff', fields)
+				return handoffResponse(decision)
+			}
+			return denied(logger, fields, decision)
+		} catch {
+			// The last line of the fail-closed guarantee. No `err` is inspected or logged: a caught
+			// error can stringify a URL, a header or a body, any of which may carry a credential.
+			logger.error('verify failed', { requestId })
+			return textResponse(403, 'forbidden')
+		}
+	}
+}
+
+/**
+ * Render a redeemed handoff: set the app session on THIS host and send the browser where IAM said.
+ *
+ * This is the ONE place the proxy writes the long-lived app session. It separately writes a
+ * short-lived handoff verifier when starting login, then clears that verifier here.
+ *
+ * Every attribute is fixed by `SESSION_COOKIE`'s `__Host-` prefix: `Secure`, `Path=/`, and no
+ * `Domain`. The absent `Domain` is the substance — the session belongs to this app's host and no
+ * sibling can read it — and the prefix is the browser-enforced restatement, which additionally stops a
+ * sibling under a shared registrable domain from planting a second cookie of this name. `Secure` is
+ * unconditional rather than following the manifest's scheme: the prefix requires it, so a conditional
+ * could only produce a cookie the browser discards. It stays correct behind a terminating balancer
+ * (the socket is plain HTTP, the browser spoke HTTPS) and on `*.localhost`, which browsers treat as
+ * potentially trustworthy.
+ */
+function handoffResponse(decision: Extract<Decision, { outcome: 'handoff' }>): Response {
+	const maxAge = Math.max(0, decision.expiresAt - Math.floor(Date.now() / 1000))
+	const headers = new Headers({ location: decision.location, 'cache-control': 'no-store' })
+	headers.append('set-cookie', secureCookie(SESSION_COOKIE, decision.session, maxAge))
+	headers.append('set-cookie', clearHandoffCookie(decision.handoffState))
+	return new Response(null, {
+		status: 302,
+		headers,
+	})
+}
+
+/** Emit the log line for a refusal and render its response. The reason is logged, never returned. */
+function denied(logger: ProxyLogger, fields: LogFields, decision: Extract<Decision, { outcome: 'deny' | 'login' }>): Response {
+	const reason: DenyReason = decision.reason
+	if (decision.outcome === 'login') {
+		logger.info('login', { ...fields, reason, status: decision.status })
+		return decision.status === 302
+			? loginRedirect(decision.location, decision.handoff)
+			: loginRequired(decision.location, decision.handoff)
+	}
+	logger.warn('deny', { ...fields, reason, status: decision.status })
+	const response = textResponse(decision.status, decision.status === 401 ? 'unauthorized' : decision.status === 503 ? 'unavailable' : 'forbidden')
+	if (decision.clearHandoffState !== undefined) {
+		response.headers.append('set-cookie', clearHandoffCookie(decision.clearHandoffState))
+	}
+	return response
+}
+
+/** The bounce a document navigation gets: the browser follows it and comes back signed in. */
+function loginRedirect(location: string, handoff: HandoffAttempt): Response {
+	return new Response(null, {
+		status: 302,
+		headers: { location, 'cache-control': 'no-store', 'set-cookie': handoffCookie(handoff) },
+	})
+}
+
+/**
+ * The answer everything else gets — an XHR, a `fetch`, the console's own RPC POST. The envelope is
+ * the one `@fabrika/app`'s browser client already parses (`bounceOnAuth` acts on a 401 whose
+ * `error.type` is `auth` and which carries a `loginUrl`), so an expired console session becomes a
+ * sign-in rather than a redirect `fetch` cannot follow.
+ *
+ * The message is a fixed string: the deny REASON stays coarse and stays in the log. The login URL
+ * now rides in a body as well as in `Location`, which adds no way for a credential to reach a log —
+ * Caddy logs request URIs and response headers, never bodies, and the access log already redacts
+ * `?redirect=` out of both.
+ */
+function loginRequired(loginUrl: string, handoff: HandoffAttempt): Response {
+	return new Response(JSON.stringify({ error: { type: 'auth', message: 'Authentication required', loginUrl } }), {
+		status: 401,
+		headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'set-cookie': handoffCookie(handoff) },
+	})
+}
+
+function handoffCookie(handoff: HandoffAttempt): string {
+	const name = handoffCookieName(handoff.state)
+	if (name === null) throw new Error('generated invalid handoff state')
+	return secureCookie(name, handoff.verifier, HANDOFF_COOKIE_TTL_SECONDS)
+}
+
+function clearHandoffCookie(state: string): string {
+	const name = handoffCookieName(state)
+	if (name === null) throw new Error('invalid handoff state')
+	return secureCookie(name, '', 0)
+}
+
+function secureCookie(name: string, value: string, maxAge: number): string {
+	return [`${name}=${value}`, 'Path=/', `Max-Age=${maxAge}`, 'HttpOnly', 'SameSite=Lax', 'Secure'].join('; ')
+}
+
+function textResponse(status: number, body: string): Response {
+	return new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
+}
+
+/**
+ * Rebuild the original request from the forwarded headers. Returns null — a DENY — whenever the
+ * description is incomplete or suspicious, because a proxy that guesses what was asked for is a proxy
+ * that authorizes the wrong thing.
+ *
+ * The URL is assembled by assignment rather than by `new URL(uri, base)`: a request line of
+ * `GET //evil.example/x` is a legal path, and relative resolution would read it as a protocol-relative
+ * URL, silently changing the host — which would both mis-match the gates and turn the login bounce
+ * into an open redirect.
+ */
+function readForwardedRequest(request: Request, requestId: string): ForwardedRequest | null {
+	const uri = request.headers.get(FORWARDED_URI_HEADER)
+	if (uri === null || !uri.startsWith('/')) {
+		return null
+	}
+	const host = request.headers.get(FORWARDED_HOST_HEADER) ?? request.headers.get('Host')
+	if (host === null || !HOST_PATTERN.test(host)) {
+		return null
+	}
+	const proto = request.headers.get(FORWARDED_PROTO_HEADER) === 'http' ? 'http' : 'https'
+
+	const query = uri.indexOf('?')
+	const url = new URL(`${proto}://${host}`)
+	url.pathname = query === -1 ? uri : uri.slice(0, query)
+	url.search = query === -1 ? '' : uri.slice(query)
+	if (url.host.toLowerCase() !== host.toLowerCase()) {
+		// Defensive: the assignment above must not have been able to move the host.
+		return null
+	}
+
+	return {
+		method: request.headers.get(FORWARDED_METHOD_HEADER) ?? 'GET',
+		url,
+		headers: request.headers,
+		requestId,
+	}
+}
+
+/**
+ * Which app is this? The generated Caddy route pins `?app=<id>`, because the route already knows.
+ * Host lookup is the fallback for hand-written configs. Neither resolving is a deny — there is no
+ * "default app".
+ *
+ * A PINNED app is still cross-checked against the forwarded host. `X-Forwarded-Host` is
+ * client-controllable once `trusted_proxies` is set (ADR-0010), and the pin is what stops it choosing
+ * the app — but the same header then builds the login bounce and the handoff callback, so a request
+ * pinned to app A claiming app B's host would send the browser somewhere the manifest never declared.
+ * The authoritative host list is right here; use it.
+ */
+function selectApp(verifyUrl: URL, host: string, byId: Map<string, ResolvedApp>, byHost: Map<string, ResolvedApp>): ResolvedApp | null {
+	const hostname = normalizeHost(host)
+	const pinned = verifyUrl.searchParams.get(APP_QUERY_PARAM)
+	if (pinned !== null) {
+		const resolved = byId.get(pinned)
+		if (resolved === undefined || !resolved.app.hosts.some((declared) => normalizeHost(declared) === hostname)) {
+			return null
+		}
+		return resolved
+	}
+	return byHost.get(hostname) ?? null
+}
+
+/** Lower-case, port stripped — the one normalization every host comparison in this file uses. */
+function normalizeHost(host: string): string {
+	return host.toLowerCase().replace(/:\d+$/, '')
+}

package/src/verifier.ts

@@ -0,0 +1,105 @@
+/**
+ * Local token verification — the warm path. Fetch the JWKS once, then verify every token with no
+ * network call on the warm path.
+ *
+ * `verify` returns a three-state result, because "this token is bad" and "we could not check" are
+ * different denials: the first is the caller's fault (401/403), the second is ours (503). Both deny.
+ */
+
+import { type AccessTokenClaims, type Jwks, parseAccessClaims } from '@fabrika/auth-core'
+import { createLocalJWKSet, errors as joseErrors, jwtVerify } from 'jose'
+import { JWKS_REFETCH_COOLDOWN_SECONDS, JWKS_TTL_SECONDS } from './constants'
+import { IamUnavailableError } from './iam'
+
+export type VerifyResult =
+	| { ok: true; claims: AccessTokenClaims }
+	/** Signature, issuer, audience, expiry or claim-shape failure — the token is not trustworthy. */
+	| { ok: false; reason: 'invalid' }
+	/** The key set could not be obtained, so nothing can be verified. Deny, but say why. */
+	| { ok: false; reason: 'unavailable' }
+
+/** Sentinel distinguishing "no signing key matched (kid rotation)" from a real verification failure. */
+const NO_KEY = Symbol('no-matching-key')
+
+export class TokenVerifier {
+	private cached: { verifier: ReturnType<typeof createLocalJWKSet>; expiresAt: number } | null = null
+	/** When the last unknown-`kid` refetch was attempted. Null until one has been. */
+	private lastForcedAt: number | null = null
+
+	constructor(
+		private readonly getJwks: () => Promise<Jwks>,
+		private readonly issuer: string,
+		private readonly now: () => number,
+		private readonly ttlSeconds: number = JWKS_TTL_SECONDS,
+		private readonly refetchCooldownSeconds: number = JWKS_REFETCH_COOLDOWN_SECONDS,
+	) {}
+
+	/**
+	 * Verify `token` for `audience` and narrow it to access claims. An unknown `kid` triggers one JWKS
+	 * refetch (a key rotated in), then a retry — but at most once per cooldown, because otherwise any
+	 * caller can turn every request into an IAM round trip just by inventing a `kid`.
+	 */
+	async verify(token: string, audience: string): Promise<VerifyResult> {
+		let payload: unknown
+		try {
+			payload = await this.verifyWith(token, audience, false)
+			if (payload === NO_KEY && this.mayForceRefetch()) {
+				payload = await this.verifyWith(token, audience, true)
+			}
+		} catch (err) {
+			if (err instanceof IamUnavailableError) {
+				return { ok: false, reason: 'unavailable' }
+			}
+			throw err
+		}
+		if (payload === NO_KEY || payload === null) {
+			return { ok: false, reason: 'invalid' }
+		}
+		const claims = parseAccessClaims(payload)
+		return claims === null ? { ok: false, reason: 'invalid' } : { ok: true, claims }
+	}
+
+	/**
+	 * May an unknown `kid` force a refetch right now? A rotation is rare and the token is denied either
+	 * way, so rate-limiting this costs a few seconds of rotation lag and removes an amplification
+	 * primitive: without it, N requests with N invented kids are N IAM fetches.
+	 */
+	private mayForceRefetch(): boolean {
+		const now = this.now()
+		if (this.lastForcedAt !== null && now - this.lastForcedAt < this.refetchCooldownSeconds) {
+			return false
+		}
+		this.lastForcedAt = now
+		return true
+	}
+
+	/** Returns the payload, `null` on a genuine verification failure, or `NO_KEY` on a kid miss. */
+	private async verifyWith(token: string, audience: string, force: boolean): Promise<unknown> {
+		const jwks = await this.jwks(force)
+		try {
+			const { payload } = await jwtVerify(token, jwks, { issuer: this.issuer, audience })
+			return payload
+		} catch (err) {
+			return err instanceof joseErrors.JWKSNoMatchingKey ? NO_KEY : null
+		}
+	}
+
+	private async jwks(force: boolean): Promise<ReturnType<typeof createLocalJWKSet>> {
+		const now = this.now()
+		if (!force && this.cached !== null && this.cached.expiresAt > now) {
+			return this.cached.verifier
+		}
+		let keys: Jwks
+		try {
+			keys = await this.getJwks()
+		} catch {
+			// Any JWKS failure is an IAM outage as far as we are concerned. Note that we do NOT fall
+			// back to a stale verifier here: the previous key set may have been rotated out precisely
+			// because it was compromised.
+			throw new IamUnavailableError('getJwks')
+		}
+		const verifier = createLocalJWKSet(keys)
+		this.cached = { verifier, expiresAt: now + this.ttlSeconds }
+		return verifier
+	}
+}