@fabrika/proxy-core 0.0.1

package/src/iam.ts

@@ -0,0 +1,257 @@
+/**
+ * The proxy's view of the IAM service: the three cold-path calls it needs, and nothing else.
+ *
+ * `IamGateway` is a STRUCTURAL SUBSET of `IamRpc`, so on Cloudflare the thin Worker passes its
+ * `env.IAM` service binding straight in with no adapter. On Zerops there is no binding, so
+ * `HttpIamGateway` speaks HTTP to the global IAM service — the public hop ADR-0007 calls cold-path
+ * only: everything after the first exchange is a local JWKS verification against the cached token.
+ *
+ * FAIL-CLOSED CONTRACT: an unreachable, slow or incoherent IAM raises `IamUnavailableError`. A
+ * *decided* negative (`{ ok: false, reason }`) is returned normally. The caller must map the former
+ * to a deny too — the distinction only chooses the status, never the outcome.
+ */
+
+import type {
+	ExchangeAuthCodeInput,
+	ExchangeAuthCodeResult,
+	Jwks,
+	MintFromKeyInput,
+	MintFromKeyResult,
+	MintTokenInput,
+	MintTokenResult,
+	PublicJwk,
+} from '@fabrika/auth-core'
+import { DEFAULT_IAM_TIMEOUT_MS } from './constants'
+import { numberField, prop, stringField } from './json'
+
+/**
+ * What the proxy needs of IAM. IAM's entrypoints satisfy it structurally — the CF binding drops
+ * straight in with no adapter. Three of the four calls are `IamRpc`; `exchangeAuthCode` is
+ * deliberately NOT (`IamHandoffRpc`, ADR-0021), because only the proxy may turn a handoff code into
+ * a session and `IamRpc` is held by every SDK consumer.
+ */
+export interface IamGateway {
+	mintToken(input: MintTokenInput): Promise<MintTokenResult>
+	mintFromKey(input: MintFromKeyInput): Promise<MintFromKeyResult>
+	exchangeAuthCode(input: ExchangeAuthCodeInput): Promise<ExchangeAuthCodeResult>
+	getJwks(): Promise<Jwks>
+}
+
+/**
+ * IAM could not be consulted — network failure, timeout, non-200, or a body we cannot read. Distinct
+ * from a decided denial: we do not know the answer, so the request is denied with 503 rather than
+ * being told it is unauthorized.
+ *
+ * Carries NO cause and no response body: an error object from `fetch` can carry a URL, and a body
+ * can carry a token.
+ */
+export class IamUnavailableError extends Error {
+	constructor(readonly operation: string) {
+		super(`iam unavailable: ${operation}`)
+		this.name = 'IamUnavailableError'
+	}
+}
+
+export interface HttpIamGatewayOptions {
+	/** The IAM service origin, e.g. `https://iam.example.com` (trailing slash tolerated). */
+	origin: string
+	/** Per-call timeout. A hung IAM must deny, not hang every request behind the proxy. */
+	timeoutMs?: number
+	/** Optional `Authorization: Bearer` the proxy authenticates ITSELF to IAM with. */
+	key?: string
+	/** Injectable for tests; defaults to the global `fetch`. */
+	fetch?: FetchLike
+}
+
+/**
+ * Just the call shape the gateway uses. Narrower than `typeof fetch` on purpose: the global carries
+ * runtime-specific extras (Bun's `preconnect`) that a test double has no business implementing.
+ */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>
+
+/**
+ * HTTP transport for `IamGateway` — the Zerops path, where there is no service binding.
+ *
+ * This file and `packages/iam/src/rpc-http.ts` are two halves of one contract; neither may move
+ * without the other in the SAME commit. A mismatch fails closed (any non-200 becomes
+ * `IamUnavailableError` → a 503 deny) but is very hard to read from the outside.
+ *
+ *   POST {origin}/auth/mint/session   {app, session, requestId} -> MintTokenResult
+ *   POST {origin}/auth/mint/key       {app, key, requestId}     -> MintFromKeyResult
+ *   POST {origin}/auth/mint/exchange  {app, code, requestId}    -> ExchangeAuthCodeResult   (ADR-0021)
+ *   GET  {origin}/.well-known/jwks.json                         -> Jwks                     (public)
+ *
+ * The three POST endpoints are the `/auth/mint/*` PROXY surface, gated by IAM's `proxyKey` — the
+ * least-privilege split ADR-0007 requires, kept apart from the management `/rpc/*` surface. They
+ * answer **200 on any decided outcome, including a denial**: `{ ok: false, reason }` is "IAM answered:
+ * no", a non-200 is "IAM could not be consulted". Both deny; only the second is an incident.
+ *
+ * Credentials always ride in the POST body, never in a URL — a URL ends up in access logs and error
+ * strings; a body does not.
+ */
+export class HttpIamGateway implements IamGateway {
+	private readonly origin: string
+	private readonly timeoutMs: number
+	private readonly key: string | undefined
+	private readonly fetchImpl: FetchLike
+
+	constructor(options: HttpIamGatewayOptions) {
+		this.origin = options.origin.replace(/\/+$/, '')
+		this.timeoutMs = options.timeoutMs ?? DEFAULT_IAM_TIMEOUT_MS
+		this.key = options.key
+		this.fetchImpl = options.fetch ?? globalThis.fetch
+	}
+
+	async mintToken(input: MintTokenInput): Promise<MintTokenResult> {
+		const parsed = parseMintResult(await this.post('/auth/mint/session', input, 'mintToken'))
+		if (parsed === null) {
+			throw new IamUnavailableError('mintToken')
+		}
+		if (parsed.ok) {
+			return parsed
+		}
+		return { ok: false, reason: reasonOf(parsed.reason, ['no_session', 'invalid_session', 'unknown_principal', 'disabled'], 'invalid_session') }
+	}
+
+	async mintFromKey(input: MintFromKeyInput): Promise<MintFromKeyResult> {
+		const parsed = parseMintResult(await this.post('/auth/mint/key', input, 'mintFromKey'))
+		if (parsed === null) {
+			throw new IamUnavailableError('mintFromKey')
+		}
+		if (parsed.ok) {
+			return parsed
+		}
+		return { ok: false, reason: reasonOf(parsed.reason, ['invalid_key', 'unknown_principal', 'disabled'], 'invalid_key') }
+	}
+
+	async exchangeAuthCode(input: ExchangeAuthCodeInput): Promise<ExchangeAuthCodeResult> {
+		const body = await this.post('/auth/mint/exchange', input, 'exchangeAuthCode')
+		const ok = prop(body, 'ok')
+		if (ok === true) {
+			const session = stringField(body, 'session')
+			const returnUrl = stringField(body, 'returnUrl')
+			const expiresAt = numberField(body, 'expiresAt')
+			if (session === undefined || session === '' || returnUrl === undefined || returnUrl === '' || expiresAt === undefined) {
+				throw new IamUnavailableError('exchangeAuthCode')
+			}
+			return { ok: true, session, returnUrl, expiresAt }
+		}
+		if (ok !== false) {
+			throw new IamUnavailableError('exchangeAuthCode')
+		}
+		const reason = stringField(body, 'reason')
+		if (reason === undefined) {
+			throw new IamUnavailableError('exchangeAuthCode')
+		}
+		return {
+			ok: false,
+			reason: reasonOf(reason, ['invalid_code', 'expired_code', 'wrong_app', 'invalid_verifier', 'unknown_principal', 'disabled'], 'invalid_code'),
+		}
+	}
+
+	async getJwks(): Promise<Jwks> {
+		const response = await this.send('/.well-known/jwks.json', undefined, 'getJwks')
+		const body: unknown = await response.json().catch(() => null)
+		const jwks = parseJwks(body)
+		if (jwks === null) {
+			throw new IamUnavailableError('getJwks')
+		}
+		return jwks
+	}
+
+	private async post(path: string, payload: unknown, operation: string): Promise<unknown> {
+		const response = await this.send(path, JSON.stringify(payload), operation)
+		return response.json().catch(() => null)
+	}
+
+	private async send(path: string, body: string | undefined, operation: string): Promise<Response> {
+		const headers = new Headers({ accept: 'application/json' })
+		if (body !== undefined) {
+			headers.set('content-type', 'application/json')
+		}
+		if (this.key !== undefined) {
+			headers.set('authorization', `Bearer ${this.key}`)
+		}
+		let response: Response
+		try {
+			response = await this.fetchImpl(`${this.origin}${path}`, {
+				method: body === undefined ? 'GET' : 'POST',
+				headers,
+				body,
+				signal: AbortSignal.timeout(this.timeoutMs),
+			})
+		} catch {
+			// Deliberately swallow the cause: a fetch error stringifies the request URL and, on some
+			// runtimes, request detail. We only ever surface the operation name.
+			throw new IamUnavailableError(operation)
+		}
+		if (!response.ok) {
+			throw new IamUnavailableError(operation)
+		}
+		return response
+	}
+}
+
+/** The shared `{ok:true,token,expiresAt} | {ok:false,reason}` wire shape, read structurally. */
+type ParsedMint = { ok: true; token: string; expiresAt: number } | { ok: false; reason: string }
+
+function parseMintResult(body: unknown): ParsedMint | null {
+	const ok = prop(body, 'ok')
+	if (ok === true) {
+		const token = stringField(body, 'token')
+		const expiresAt = numberField(body, 'expiresAt')
+		if (token === undefined || token === '' || expiresAt === undefined) {
+			return null
+		}
+		return { ok: true, token, expiresAt }
+	}
+	if (ok === false) {
+		const reason = stringField(body, 'reason')
+		return reason === undefined ? null : { ok: false, reason }
+	}
+	return null
+}
+
+/**
+ * Narrow a wire `reason` string to the declared union without a cast. An unrecognised reason degrades
+ * to the given fallback, which is always a DENY reason — an IAM that starts speaking a dialect we do
+ * not know must not be able to talk us into an allow.
+ */
+function reasonOf<T extends string>(value: string, allowed: readonly T[], fallback: T): T {
+	for (const candidate of allowed) {
+		if (candidate === value) {
+			return candidate
+		}
+	}
+	return fallback
+}
+
+/**
+ * Read a key set, rejecting one we cannot fully represent. `PublicJwk` carries only the EC members,
+ * so a key of any other type would be copied into a shape missing the material that verifies it — a
+ * silently short key set, which reads as "this token is invalid" (a client problem) instead of "we
+ * could not check" (an incident). IAM signs ES256 only, so anything else means we are not reading the
+ * key set we think we are: refuse the whole fetch and let the caller raise `IamUnavailableError`.
+ */
+function parseJwks(body: unknown): Jwks | null {
+	const rawKeys = prop(body, 'keys')
+	if (!Array.isArray(rawKeys)) {
+		return null
+	}
+	const keys: PublicJwk[] = []
+	for (const raw of rawKeys) {
+		const kty = stringField(raw, 'kty')
+		if (kty !== 'EC') {
+			return null
+		}
+		const key: PublicJwk = { kty }
+		for (const field of ['crv', 'x', 'y', 'kid', 'alg', 'use'] as const) {
+			const value = stringField(raw, field)
+			if (value !== undefined) {
+				key[field] = value
+			}
+		}
+		keys.push(key)
+	}
+	return { keys }
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+// @fabrika/proxy-core — the auth enforcement decision, as a library.
+//
+// ADR-0022 makes the proxy the ONLY enforcement point, and there are two of them: a Bun service
+// answering Caddy's `forward_auth` subrequest on Zerops, and the Cloudflare proxy Worker calling the
+// same code in-process. This package is what they share — take a forwarded request, decide, and mint
+// or refuse. It is runtime-neutral by construction: no Caddy, no filesystem, no process.
+//
+// The deployment that fronts it on Zerops — the Caddy configuration and the compiled binary — is
+// `@fabrika/proxy`, which is private because it is an artifact rather than an API. The manifest wire
+// contract and its strict parser are `@fabrika/proxy-contract`; the gate matcher and the token claims
+// are `@fabrika/auth-core`.
+
+export { Authorizer } from './authorize'
+export type { AuthorizerOptions, Decision, DenyReason, ForwardedRequest, ResolvedApp } from './authorize'
+export { cacheKey, MemoryTokenCache } from './cache'
+export type { CachedToken, TokenCache } from './cache'
+export {
+	APP_QUERY_PARAM,
+	CLIENT_ADDRESS_HEADER,
+	DEFAULT_HEALTH_PATH,
+	DEFAULT_IAM_TIMEOUT_MS,
+	DEFAULT_VERIFY_PATH,
+	FORWARDED_HOST_HEADER,
+	FORWARDED_METHOD_HEADER,
+	FORWARDED_PROTO_HEADER,
+	FORWARDED_URI_HEADER,
+	JWKS_TTL_SECONDS,
+	LOGIN_REDIRECT_PARAM,
+	PROXY_TOKEN_HEADER,
+	REQUEST_ID_HEADER,
+	UNTRUSTED_FORWARD_HEADERS,
+} from './constants'
+export { applicableGates, compileGates, readBearer, readCookie, readServiceCredential } from './gates'
+export type { CompiledGate } from './gates'
+export { stripFabrikaCookies } from './handoff'
+export { HttpIamGateway, IamUnavailableError } from './iam'
+export type { HttpIamGatewayOptions, IamGateway } from './iam'
+export { consoleLogger, redactPath, redactUrl, silentLogger } from './log'
+export type { LogFields, LogValue, ProxyLogger } from './log'
+export { createVerifyService } from './service'
+export type { VerifyService, VerifyServiceConfig } from './service'
+export { TokenVerifier } from './verifier'
+export type { VerifyResult } from './verifier'

package/src/json.ts

@@ -0,0 +1,44 @@
+/**
+ * Tiny structural readers for untrusted JSON (the deployed manifest, an IAM HTTP response body).
+ * They let the parsers narrow without `as` casts: read a field, check its runtime type, proceed.
+ * Mirrors `@fabrika/auth-core`'s internal `json.ts`, which is not exported from its entry point.
+ */
+
+/** Read a property off an unknown value (undefined when absent / not an object). */
+export function prop(value: unknown, key: string): unknown {
+	if (typeof value !== 'object' || value === null) {
+		return undefined
+	}
+	return Object.hasOwn(value, key) ? Reflect.get(value, key) : undefined
+}
+
+export function stringField(value: unknown, key: string): string | undefined {
+	const v = prop(value, key)
+	return typeof v === 'string' ? v : undefined
+}
+
+export function numberField(value: unknown, key: string): number | undefined {
+	const v = prop(value, key)
+	return typeof v === 'number' && Number.isFinite(v) ? v : undefined
+}
+
+export function booleanField(value: unknown, key: string): boolean | undefined {
+	const v = prop(value, key)
+	return typeof v === 'boolean' ? v : undefined
+}
+
+/** An array of strings, or undefined when the field is absent or any element is not a string. */
+export function stringArrayField(value: unknown, key: string): string[] | undefined {
+	const v = prop(value, key)
+	if (!Array.isArray(v)) {
+		return undefined
+	}
+	const out: string[] = []
+	for (const item of v) {
+		if (typeof item !== 'string') {
+			return undefined
+		}
+		out.push(item)
+	}
+	return out
+}

package/src/log.ts

@@ -0,0 +1,58 @@
+/**
+ * Logging, constrained so that secret material cannot reach it.
+ *
+ * The rule is structural rather than aspirational: a log field is a `string | number | boolean |
+ * null`, call sites pass only decision metadata, and the two values that CAN carry a credential —
+ * a request path (share-link tokens ride in the path) and a URL — go through `redactPath` /
+ * `redactUrl` first. Nothing in this package ever passes a header, a cookie, a token or a caught
+ * error object to a logger.
+ */
+
+import { API_KEY_PREFIX } from '@fabrika/auth-core'
+
+export type LogValue = string | number | boolean | null
+export type LogFields = Record<string, LogValue>
+
+export interface ProxyLogger {
+	info(message: string, fields?: LogFields): void
+	warn(message: string, fields?: LogFields): void
+	error(message: string, fields?: LogFields): void
+}
+
+/** Emits one JSON object per line — what Zerops' log collector expects. */
+export const consoleLogger: ProxyLogger = {
+	info: (message, fields) => console.info(line('info', message, fields)),
+	warn: (message, fields) => console.warn(line('warn', message, fields)),
+	error: (message, fields) => console.error(line('error', message, fields)),
+}
+
+/** A logger that discards everything — the default, so a library consumer opts IN to output. */
+export const silentLogger: ProxyLogger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+}
+
+function line(level: string, message: string, fields: LogFields | undefined): string {
+	return JSON.stringify({ level, message, ...fields })
+}
+
+/**
+ * Make a path safe to log. Two hazards, both real:
+ *   - a query string can carry a declared `query` credential (`?pxt=<token>`) — dropped entirely;
+ *   - a path SEGMENT can be a share-link `px_` credential — replaced with `px_***`.
+ * Anything else is preserved, because an unloggable path is an undebuggable proxy.
+ */
+export function redactPath(pathname: string): string {
+	const query = pathname.indexOf('?')
+	const path = query === -1 ? pathname : pathname.slice(0, query)
+	return path
+		.split('/')
+		.map((segment) => (segment.startsWith(API_KEY_PREFIX) ? `${API_KEY_PREFIX}***` : segment))
+		.join('/')
+}
+
+/** Origin + redacted path. Never the query string. */
+export function redactUrl(url: URL): string {
+	return `${url.origin}${redactPath(url.pathname)}`
+}