@fabrika/proxy-core 0.2.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/proxy-core",
-	"version": "0.2.0",
+	"version": "0.3.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -19,6 +19,11 @@
 			"bun": "./src/index.ts",
 			"types": "./src/index.ts",
 			"default": "./src/index.ts"
+		},
+		"./manifest": {
+			"bun": "./src/manifest.ts",
+			"types": "./src/manifest.ts",
+			"default": "./src/manifest.ts"
 		}
 	},
 	"scripts": {
@@ -26,9 +31,10 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/auth-core": "^0.2.0",
-		"@fabrika/jwks": "^0.2.0",
-		"@fabrika/proxy-contract": "^0.2.0",
-		"jose": "^5.9.0"
+		"zod": "^3.25.76",
+		"@fabrika/auth-core": "^0.3.2",
+		"@fabrika/jwks": "^0.3.2",
+		"jose": "^5.9.0",
+		"@fabrika/platform": "^0.3.2"
 	}
 }

package/src/authorize.ts

@@ -1,9 +1,9 @@
 /**
- * The proxy authorization core ([ADR-0007](../../../docs/decisions/0007-proxy-based-auth-enforcement.md)).
+ * The proxy authorization core ([ADR-0022](../../../docs/decisions/0022-the-proxy-is-the-only-enforcement-point.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);
+ *   2. resolve the credential the matched rule requires (cookie session or `px_` key);
  *   3. exchange it with IAM once, cache the result, and thereafter verify LOCALLY against the JWKS;
  *   4. deny unless a rule was satisfied.
  *
@@ -17,12 +17,12 @@
  */
 
 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 type { ProxyApp } from './manifest'
 import { TokenVerifier } from './verifier'
 
 /** Every way a request can be refused. Coarse on purpose — these are logged, not returned to clients. */
@@ -31,7 +31,7 @@ export type DenyReason =
 	| '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. */
+	/** A service credential was presented and is not a valid `px_` key. */
 	| 'invalid_key'
 	| 'no_session'
 	| 'invalid_session'
@@ -63,7 +63,7 @@ export type Decision =
 	 */
 	| { 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
+	 * A handoff code was redeemed (ADR-0022). 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.
 	 */
@@ -189,19 +189,13 @@ export class Authorizer {
 	}
 
 	/**
-	 * 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.
+	 * A `service`-rule bearer. Only a `px_` opaque key satisfies it: it is exchanged via `mintFromKey`
+	 * (cached, so the hot path is a local verify). Anything else is refused 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 }
+			return { outcome: 'deny', status: 401, reason: 'invalid_key' }
 		}
 
 		const key = cacheKey(app.id, 'key', bearer)
@@ -305,7 +299,7 @@ export class Authorizer {
 	}
 
 	/**
-	 * Redeem a handoff code (ADR-0021). Called for the reserved callback path only, BEFORE gate
+	 * Redeem a handoff code (ADR-0022). 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.
 	 *
@@ -387,7 +381,7 @@ export class Authorizer {
  * 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.
+ * argument ADR-0022 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

package/src/constants.ts

@@ -30,7 +30,7 @@ export const DEFAULT_HEALTH_PATH = '/healthz'
 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
+ * Query parameter IAM's `/auth/login` takes the return URL in (ADR-0022). 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.
  */

package/src/gates.ts

@@ -1,6 +1,6 @@
 /**
  * Credential extraction for the gate evaluator relocated out of the app's process
- * ([ADR-0007](../../../docs/decisions/0007-proxy-based-auth-enforcement.md)).
+ * ([ADR-0022](../../../docs/decisions/0022-the-proxy-is-the-only-enforcement-point.md)).
  *
  * The semantics are `AppGates`', verbatim (see `@fabrika/auth-core`'s `types.ts`):
  *   - array order IS the precedence;

package/src/iam.ts

@@ -3,7 +3,7 @@
  *
  * `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
+ * `HttpIamGateway` speaks HTTP to the global IAM service — the public hop ADR-0022 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
@@ -19,15 +19,25 @@ import type {
 	MintFromKeyResult,
 	MintTokenInput,
 	MintTokenResult,
-	PublicJwk,
 } from '@fabrika/auth-core'
+import { parseJwks } from '@fabrika/jwks'
+import { z } from 'zod'
 import { DEFAULT_IAM_TIMEOUT_MS } from './constants'
-import { numberField, prop, stringField } from './json'
+
+const denialSchema = z.object({ ok: z.literal(false), reason: z.string() })
+const mintResultSchema = z.discriminatedUnion('ok', [
+	z.object({ ok: z.literal(true), token: z.string().min(1), expiresAt: z.number().finite() }),
+	denialSchema,
+])
+const exchangeResultSchema = z.discriminatedUnion('ok', [
+	z.object({ ok: z.literal(true), session: z.string().min(1), returnUrl: z.string().min(1), expiresAt: z.number().finite() }),
+	denialSchema,
+])
 
 /**
  * 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
+ * deliberately NOT (`IamHandoffRpc`, ADR-0022), because only the proxy may turn a handoff code into
  * a session and `IamRpc` is held by every SDK consumer.
  */
 export interface IamGateway {
@@ -78,11 +88,11 @@ export type FetchLike = (input: string, init: RequestInit) => Promise<Response>
  *
  *   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)
+ *   POST {origin}/auth/mint/exchange  {app, code, requestId}    -> ExchangeAuthCodeResult   (ADR-0022)
  *   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
+ * least-privilege split ADR-0022 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.
  *
@@ -103,10 +113,11 @@ export class HttpIamGateway implements IamGateway {
 	}
 
 	async mintToken(input: MintTokenInput): Promise<MintTokenResult> {
-		const parsed = parseMintResult(await this.post('/auth/mint/session', input, 'mintToken'))
-		if (parsed === null) {
+		const result = mintResultSchema.safeParse(await this.post('/auth/mint/session', input, 'mintToken'))
+		if (!result.success) {
 			throw new IamUnavailableError('mintToken')
 		}
+		const parsed = result.data
 		if (parsed.ok) {
 			return parsed
 		}
@@ -114,10 +125,11 @@ export class HttpIamGateway implements IamGateway {
 	}
 
 	async mintFromKey(input: MintFromKeyInput): Promise<MintFromKeyResult> {
-		const parsed = parseMintResult(await this.post('/auth/mint/key', input, 'mintFromKey'))
-		if (parsed === null) {
+		const result = mintResultSchema.safeParse(await this.post('/auth/mint/key', input, 'mintFromKey'))
+		if (!result.success) {
 			throw new IamUnavailableError('mintFromKey')
 		}
+		const parsed = result.data
 		if (parsed.ok) {
 			return parsed
 		}
@@ -125,27 +137,18 @@ export class HttpIamGateway implements IamGateway {
 	}
 
 	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) {
+		const result = exchangeResultSchema.safeParse(await this.post('/auth/mint/exchange', input, 'exchangeAuthCode'))
+		if (!result.success) {
 			throw new IamUnavailableError('exchangeAuthCode')
 		}
+		if (result.data.ok) return result.data
 		return {
 			ok: false,
-			reason: reasonOf(reason, ['invalid_code', 'expired_code', 'wrong_app', 'invalid_verifier', 'unknown_principal', 'disabled'], 'invalid_code'),
+			reason: reasonOf(
+				result.data.reason,
+				['invalid_code', 'expired_code', 'wrong_app', 'invalid_verifier', 'unknown_principal', 'disabled'],
+				'invalid_code',
+			),
 		}
 	}
 
@@ -192,26 +195,6 @@ export class HttpIamGateway implements IamGateway {
 	}
 }
 
-/** 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
@@ -225,33 +208,3 @@ function reasonOf<T extends string>(value: string, allowed: readonly T[], fallba
 	}
 	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

@@ -7,7 +7,7 @@
 //
 // 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
+// contract and its strict parser are the `./manifest` subpath; the gate matcher and the token claims
 // are `@fabrika/auth-core`.
 
 export { Authorizer } from './authorize'

package/src/manifest.ts

@@ -0,0 +1,97 @@
+import type { AppGates, CredentialLocation, GateRule } from '@fabrika/auth-core'
+import { z } from 'zod'
+
+export const FABRIKA_PROXY_MANIFEST_JSON = 'FABRIKA_PROXY_MANIFEST_JSON'
+
+export interface ProxyApp {
+	/** The IAM app id, used as the minted token audience. */
+	id: string
+	/** Literal hostnames, lower-cased on parse; never patterns or host:port pairs. */
+	hosts: string[]
+	/** Private upstream dial address, for example `app:3000`. */
+	upstream: string
+	/** Ordered rules; evaluated only by auth-core in the proxy. */
+	gates: AppGates
+	/** Browser-facing scheme used for login and handoff URLs, defaulting to https. */
+	scheme: 'http' | 'https'
+}
+
+export interface ProxyManifest {
+	apps: ProxyApp[]
+}
+
+const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
+
+/** Literal LDH hostnames only: Caddy reads wildcard labels and placeholders as routing patterns. */
+export function isProxyHost(host: string): boolean {
+	return host.length > 0 && host.length <= 253 && host.split('.').every((label) => label.length <= 63 && HOST_LABEL.test(label))
+}
+
+export const proxyCredentialLocationSchema = z.object({
+	in: z.enum(['header', 'query', 'cookie']),
+	name: z.string().min(1),
+}) satisfies z.ZodType<CredentialLocation, z.ZodTypeDef, unknown>
+
+const gatePathSchema = z.string().startsWith('/')
+/** A gate rule's fields before normalization; a producer adds its own refinements on top. */
+export const proxyGateRuleFieldsSchema = z.discriminatedUnion('kind', [
+	z.object({ path: gatePathSchema, kind: z.literal('public') }),
+	z.object({ path: gatePathSchema, kind: z.literal('human') }),
+	z.object({ path: gatePathSchema, kind: z.literal('service'), credential: proxyCredentialLocationSchema.nullish() }),
+])
+
+/** Drop an absent service credential, so a rule without one carries no `credential` key at all. */
+export const normalizeGateRule = (rule: z.infer<typeof proxyGateRuleFieldsSchema>): GateRule => {
+	if (rule.kind !== 'service') return rule
+	return { path: rule.path, kind: rule.kind, ...(rule.credential == null ? {} : { credential: rule.credential }) }
+}
+
+export const proxyGateRuleSchema = proxyGateRuleFieldsSchema.transform(normalizeGateRule) satisfies z.ZodType<GateRule, z.ZodTypeDef, unknown>
+
+export const proxyAppGatesSchema = z.object({
+	rules: z.array(proxyGateRuleSchema),
+}) satisfies z.ZodType<AppGates, z.ZodTypeDef, unknown>
+
+export const proxyAppSchema = z.object({
+	id: z.string().min(1),
+	hosts: z.array(z.string().toLowerCase().refine(isProxyHost)).min(1),
+	upstream: z.string().min(1),
+	gates: proxyAppGatesSchema,
+	scheme: z.preprocess((value) => typeof value === 'string' ? value : undefined, z.enum(['http', 'https']).default('https')),
+}) satisfies z.ZodType<ProxyApp, z.ZodTypeDef, unknown>
+
+/** The first host two apps (or one app twice) claim, or null. A host belongs to exactly one app. */
+export function findDuplicateProxyHost(apps: readonly Pick<ProxyApp, 'hosts'>[]): string | null {
+	const hosts = new Set<string>()
+	for (const host of apps.flatMap((app) => app.hosts)) {
+		if (hosts.has(host)) return host
+		hosts.add(host)
+	}
+	return null
+}
+
+export const proxyManifestSchema = z.object({
+	apps: z.array(proxyAppSchema),
+}).superRefine(({ apps }, ctx) => {
+	if (new Set(apps.map((app) => app.id)).size !== apps.length) ctx.addIssue({ code: 'custom', message: 'duplicate proxy app id' })
+	if (findDuplicateProxyHost(apps) !== null) ctx.addIssue({ code: 'custom', message: 'duplicate proxy host' })
+}) satisfies z.ZodType<ProxyManifest, z.ZodTypeDef, unknown>
+
+export function parseProxyManifest(value: unknown): ProxyManifest | null {
+	const result = proxyManifestSchema.safeParse(value)
+	return result.success ? result.data : null
+}
+
+export function parseProxyManifestJson(value: string): ProxyManifest | null {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(value)
+	} catch {
+		return null
+	}
+	return parseProxyManifest(parsed)
+}
+
+export function encodeProxyManifestJson(manifest: ProxyManifest): string {
+	return JSON.stringify(manifest)
+}

package/src/service.ts

@@ -21,8 +21,8 @@
  *      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 { AUTH_CALLBACK_PATH, HANDOFF_COOKIE_TTL_SECONDS, SESSION_COOKIE } from '@fabrika/auth-core'
+import { uuidv7 } from '@fabrika/platform'
 import { Authorizer, type AuthorizerOptions, type Decision, type DenyReason, type ForwardedRequest, type ResolvedApp } from './authorize'
 import type { TokenCache } from './cache'
 import {
@@ -40,6 +40,7 @@ import { compileGates } from './gates'
 import { type HandoffAttempt, handoffCookieName } from './handoff'
 import type { IamGateway } from './iam'
 import { type LogFields, type ProxyLogger, redactPath, silentLogger } from './log'
+import type { ProxyManifest } from './manifest'
 
 export interface VerifyServiceConfig {
 	manifest: ProxyManifest
@@ -347,7 +348,7 @@ function readForwardedRequest(request: Request, requestId: string): ForwardedReq
  * "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
+ * client-controllable once `trusted_proxies` is set (ADR-0022), 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.

package/src/json.ts

@@ -1,44 +0,0 @@
-/**
- * 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
-}