@fabrika/proxy-core 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/proxy-core",
-	"version": "0.3.2",
+	"version": "0.4.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -24,6 +24,11 @@
 			"bun": "./src/manifest.ts",
 			"types": "./src/manifest.ts",
 			"default": "./src/manifest.ts"
+		},
+		"./headers": {
+			"bun": "./src/headers.ts",
+			"types": "./src/headers.ts",
+			"default": "./src/headers.ts"
 		}
 	},
 	"scripts": {
@@ -32,9 +37,9 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "^0.3.2",
-		"@fabrika/jwks": "^0.3.2",
+		"@fabrika/auth-core": "^0.4.0",
+		"@fabrika/jwks": "^0.4.0",
 		"jose": "^5.9.0",
-		"@fabrika/platform": "^0.3.2"
+		"@fabrika/platform": "^0.4.0"
 	}
 }

package/src/authorize.ts

@@ -1,11 +1,12 @@
 /**
  * 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 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.
+ * Every entry — a contract application or an installation service — is protected by its endpoint table, in one pass
+ * over ONE selected endpoint: `planEndpoint` → a `px_` key whose caller kind the endpoint admits, or else the session
+ * when `human` may call → the requirement (`satisfies`) → admission → the delegation grant. There is no fall-through
+ * to another endpoint. On an installation row that admits `oauth`, a bearer that is not a `px_` key is an OAuth
+ * resource token, verified locally. A key or a session is exchanged with IAM once, cached, and thereafter verified
+ * LOCALLY against the JWKS.
  *
  * 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
@@ -16,31 +17,66 @@
  * 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 AccessTokenClaims,
+	API_KEY_PREFIX,
+	AUTH_CODE_PARAM,
+	AUTH_HANDOFF_STATE_PARAM,
+	callerAdmittedAt,
+	callerOf,
+	type CompiledEndpointTable,
+	formatEndpointHeader,
+	planEndpoint,
+	satisfies,
+	SESSION_COOKIE,
+	TOKEN_REFRESH_SKEW_SECONDS,
+	type TokenCaller,
+} from '@fabrika/auth-core'
 import { cacheKey, type TokenCache } from './cache'
 import { LOGIN_REDIRECT_PARAM } from './constants'
-import { applicableGates, type CompiledGate, readCookie, readServiceCredential } from './gates'
+import { readBearer, readCookie } from './credentials'
 import { createHandoffAttempt, type HandoffAttempt, handoffCookieName, setHandoffParams } from './handoff'
-import { type IamGateway, IamUnavailableError } from './iam'
-import type { ProxyApp } from './manifest'
+import { type DelegationIssuer, type IamGateway, IamUnavailableError } from './iam'
+import { type ManifestEndpointRow, type OAuthBearerChallenge, type OAuthProtectedResource, oauthResourceOfRow, 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. */
 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. */
+	/** The endpoint admits no person, and no credential was presented. */
 	| 'no_credential'
-	/** A service credential was presented and is not a valid `px_` key. */
+	/** A bearer was presented and is not a valid `px_` key. */
 	| 'invalid_key'
+	/** An `oauth` row's bearer is malformed, unverifiable, or minted for another resource or app. */
+	| 'invalid_token'
+	/** An `oauth` row's bearer verified but lacks a required scope. */
+	| 'insufficient_scope'
 	| 'no_session'
 	| 'invalid_session'
 	| 'unknown_principal'
 	| 'disabled'
+	/** IAM refused to sign a token above its size bound: the principal holds more than fits in a header. */
+	| 'token_too_large'
+	/** The entry's table has no endpoint for the method and path. The fail-closed default; no fall-through. */
+	| 'no_endpoint'
+	/**
+	 * The credential's caller kind is not one of the endpoint's callers, is no caller kind at all (a job or a webhook
+	 * key), or is a connector caller off an export path.
+	 */
+	| 'caller_kind'
+	/** The token does not satisfy the endpoint's requirement. */
+	| 'insufficient_permission'
+	/** A session request that is not a `GET` did not come from the app's own origin. */
+	| 'cross_site'
+	/** The request's `Content-Type` is not one the endpoint admits. */
+	| 'content_type'
+	/** IAM refused the delegation grant a membership or scope-creating endpoint needs. */
+	| 'delegation_refused'
 	/** 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'
+	/** The forwarded path is not canonical (`isCanonicalPath`); refused before any endpoint is planned. */
+	| 'non_canonical_path'
 	/** 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. */
@@ -49,15 +85,25 @@ export type DenyReason =
 export type Decision =
 	| {
 		outcome: 'allow'
-		gate: 'public' | 'service' | 'human'
-		/** The verified token to inject upstream. `null` on a `public` gate — no credential, no token. */
+		/** The verified token to inject upstream. `null` on an anonymous endpoint — no credential, no token. */
 		token: string | null
 		/** Principal id (or credential id) for the log line. Never a secret. */
 		subject: string | null
+		/** `<id>@<digest>` of the selected endpoint, for `X-Fabrika-Endpoint`. */
+		endpoint: string
+		/** The single-use delegation grant for `X-Fabrika-Delegation`, when the endpoint spends one. */
+		delegation: string | null
+	}
+	| {
+		outcome: 'deny'
+		status: 400 | 401 | 403 | 503
+		reason: DenyReason
+		clearHandoffState?: string
+		/** Set on an `oauth` row's 401/403: rendered as the RFC 6750 `WWW-Authenticate` challenge. */
+		challenge?: OAuthBearerChallenge
 	}
-	| { 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
+	 * A human reached an endpoint `human` may call 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.
 	 */
@@ -71,19 +117,21 @@ export type Decision =
 
 /** The original request, reconstructed from what `forward_auth` forwarded. */
 export interface ForwardedRequest {
-	/** Original method. Informational — gates are path-only — but logged. */
+	/** Original method; the endpoint table selects by it. */
 	method: string
-	/** Original absolute URL. Its `pathname` drives gate matching; the whole URL is the login return. */
+	/** Original absolute URL; the whole URL is the login return. */
 	url: URL
+	/** The forwarded path exactly as the upstream receives it, already checked by `isCanonicalPath`. */
+	rawPath: string
 	/** The original request's headers, forwarded verbatim by Caddy. */
 	headers: Headers
 	requestId: string
 }
 
-/** An app plus its precompiled gates, built once at startup. */
+/** An entry plus its precompiled endpoint table, built once at startup. */
 export interface ResolvedApp {
-	app: ProxyApp
-	gates: CompiledGate[]
+	readonly app: ProxyApp
+	readonly table: CompiledEndpointTable<ManifestEndpointRow>
 }
 
 export interface AuthorizerOptions {
@@ -94,6 +142,11 @@ export interface AuthorizerOptions {
 	cache?: TokenCache | null
 	/** Unix seconds. Injectable for tests. */
 	now?: () => number
+	/**
+	 * Issues the single-use grant a membership or scope-creating endpoint spends at IAM. Unset, such a request is
+	 * forwarded without one and IAM refuses the membership operation unless the framework obtained a grant itself.
+	 */
+	delegations?: DelegationIssuer | null
 }
 
 /**
@@ -103,9 +156,31 @@ export interface AuthorizerOptions {
  */
 const FETCH_MODE_HEADER = 'Sec-Fetch-Mode'
 
-/** Why a `human` attempt failed — mirrors `mintToken`'s reasons. */
+/** Fetch metadata the browser writes and page script cannot: `same-origin` only for a request from this origin. */
+const FETCH_SITE_HEADER = 'Sec-Fetch-Site'
+
+/** Why a session attempt failed — mirrors `mintToken`'s reasons. */
 type SessionFailureReason = 'no_session' | 'invalid_session' | 'unknown_principal' | 'disabled'
 
+type Denial = Extract<Decision, { outcome: 'deny' }>
+
+/** A `px_` key exchanged and verified, or the denial that ends the request. */
+type KeyAttempt = { ok: true; token: string; claims: AccessTokenClaims } | { ok: false; denial: Denial }
+
+/** An OAuth resource token verified for a resource and its scopes, or the challenge that ends the request. */
+type OAuthAttempt = { ok: true; token: string; claims: AccessTokenClaims } | { ok: false; denial: Denial }
+
+/** The resource a row that admits `oauth` is bound to, and the scopes the row requires. */
+interface OAuthBinding {
+	readonly resource: OAuthProtectedResource
+	readonly scopes: readonly string[]
+}
+
+/** Who is behind a request to a credentialed endpoint, or the decision that ends it (a denial or the login bounce). */
+type EndpointCaller =
+	| { ok: true; token: string; claims: AccessTokenClaims; session: boolean }
+	| { ok: false; decision: Extract<Decision, { outcome: 'deny' | 'login' }> }
+
 /**
  * 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
@@ -113,8 +188,9 @@ type SessionFailureReason = 'no_session' | 'invalid_session' | 'unknown_principa
  * incident.
  */
 type SessionAttempt =
-	| { ok: true; token: string; subject: string }
+	| { ok: true; token: string; claims: AccessTokenClaims }
 	| { ok: false; status: 'miss'; reason: SessionFailureReason }
+	| { ok: false; status: 'refused'; reason: 'token_too_large' }
 	| { ok: false; status: 'unavailable' }
 
 export class Authorizer {
@@ -134,7 +210,7 @@ export class Authorizer {
 	 */
 	async authorize(resolved: ResolvedApp, request: ForwardedRequest): Promise<Decision> {
 		try {
-			return await this.decide(resolved, request)
+			return await this.decideEndpoint(resolved.app, resolved.table, request)
 		} catch (err) {
 			if (err instanceof IamUnavailableError) {
 				return { outcome: 'deny', status: 503, reason: 'iam_unavailable' }
@@ -143,59 +219,154 @@ export class Authorizer {
 		}
 	}
 
-	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' }
+	/**
+	 * One pass over the endpoint `planEndpoint` selects (ADR-0022 rule 3). An anonymous kind reads no credential and
+	 * mints no token. A credentialed one takes a `px_` key when one is presented — terminal, whatever its verdict —
+	 * an OAuth resource token on a row that admits `oauth`, and the session only when `human` may call; then the
+	 * requirement, then admission.
+	 */
+	private async decideEndpoint(
+		app: ProxyApp,
+		table: CompiledEndpointTable<ManifestEndpointRow>,
+		request: ForwardedRequest,
+	): Promise<Decision> {
+		const plan = planEndpoint(table, request.method, request.rawPath)
+		if (plan.outcome === 'non-canonical') {
+			return { outcome: 'deny', status: 400, reason: 'non_canonical_path' }
 		}
+		if (plan.outcome === 'no-endpoint') {
+			return { outcome: 'deny', status: 403, reason: 'no_endpoint' }
+		}
+		const row = plan.endpoint
+		const endpoint = formatEndpointHeader(row.id, row.digest)
+		if (row.requirement === null) {
+			return admitBody(row, request.headers) ?? { outcome: 'allow', token: null, subject: null, endpoint, delegation: null }
+		}
+		const oauth = oauthBindingOf(app, row)
+		if (oauth === 'unregistered') {
+			// The manifest parser refuses an `oauth` row without its resource; reaching this is a composition bug.
+			return { outcome: 'deny', status: 403, reason: 'internal_error' }
+		}
+		const callers: readonly TokenCaller[] = row.callers
+		const caller = await this.endpointCaller(app, oauth, callers, request)
+		if (!caller.ok) {
+			return caller.decision
+		}
+		const kind = callerOf(caller.claims)
+		if (kind === null || !callers.includes(kind) || !callerAdmittedAt(kind, row.path)) {
+			return withBearerChallenge({ outcome: 'deny', status: 403, reason: 'caller_kind' }, oauth)
+		}
+		if (!satisfies(row.requirement, caller.claims.perms)) {
+			return { outcome: 'deny', status: 403, reason: 'insufficient_permission' }
+		}
+		if (caller.session && request.method !== 'GET' && request.headers.get(FETCH_SITE_HEADER) !== 'same-origin') {
+			return { outcome: 'deny', status: 403, reason: 'cross_site' }
+		}
+		const refused = admitBody(row, request.headers)
+		if (refused !== null) {
+			return refused
+		}
+		const delegation = row.delegation === null ? null : await this.obtainDelegation(app, row.id, caller.token, request.requestId)
+		if (delegation !== null && !delegation.ok) {
+			return delegation.denial
+		}
+		return {
+			outcome: 'allow',
+			token: caller.token,
+			subject: caller.claims.sub,
+			endpoint,
+			delegation: delegation?.grant ?? null,
+		}
+	}
 
-		// 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)
+	/**
+	 * A `px_` key wherever the request carries an `Authorization` header, and on a row that admits `oauth` any other
+	 * credential there as an OAuth resource token; otherwise the session, if `human` may call.
+	 */
+	private async endpointCaller(
+		app: ProxyApp,
+		oauth: OAuthBinding | null,
+		callers: readonly TokenCaller[],
+		request: ForwardedRequest,
+	): Promise<EndpointCaller> {
+		const authorization = request.headers.get('Authorization')
+		if (authorization !== null && authorization.trim() !== '') {
+			const bearer = readBearer(authorization)
+			if (oauth !== null && (bearer === null || !bearer.startsWith(API_KEY_PREFIX))) {
+				const verified = await this.verifyOAuthBearer(app, oauth, bearer)
+				return verified.ok ? { ok: true, token: verified.token, claims: verified.claims, session: false } : { ok: false, decision: verified.denial }
 			}
-			humanMiss = session.reason
+			const key = bearer === null ? { ok: false, denial: invalidKey() } satisfies KeyAttempt : await this.exchangeKey(app, bearer, request.requestId)
+			return key.ok
+				? { ok: true, token: key.token, claims: key.claims, session: false }
+				: { ok: false, decision: withBearerChallenge(key.denial, oauth) }
+		}
+		if (!callers.includes('human')) {
+			// No session reaches an endpoint a person may not call, so there is nothing to sign in to.
+			const denial: Denial = { outcome: 'deny', status: 401, reason: 'no_credential' }
+			return { ok: false, decision: oauth === null ? denial : { ...denial, challenge: { resource_metadata: oauth.resource.resourceMetadata } } }
+		}
+		const session = await this.authorizeSession(app, request)
+		if (session.ok) {
+			return { ok: true, token: session.token, claims: session.claims, session: true }
 		}
+		if (session.status === 'unavailable') {
+			return { ok: false, decision: { outcome: 'deny', status: 503, reason: 'iam_unavailable' } }
+		}
+		if (session.status === 'refused') {
+			return { ok: false, decision: { outcome: 'deny', status: 403, reason: session.reason } }
+		}
+		return { ok: false, decision: await this.loginDecision(app, request, session.reason) }
+	}
 
-		if (humanMiss !== null) {
-			return await this.loginDecision(resolved.app, request, humanMiss)
+	/** A fresh grant for every request, never cached: IAM spends it once, for this request id. */
+	private async obtainDelegation(
+		app: ProxyApp,
+		endpoint: string,
+		token: string,
+		requestId: string,
+	): Promise<{ ok: true; grant: string | null } | { ok: false; denial: Denial }> {
+		const issuer = this.options.delegations
+		if (issuer === undefined || issuer === null) {
+			return { ok: true, grant: null }
 		}
-		// Every matching rule was a `service` rule with no credential present.
-		return { outcome: 'deny', status: 401, reason: 'no_credential' }
+		const result = await this.callIam('requestDelegation', () => issuer.requestDelegation({ app: app.id, credential: token, requestId, endpoint }))
+		return result.ok && result.grant !== ''
+			? { ok: true, grant: result.grant }
+			: { ok: false, denial: { outcome: 'deny', status: 403, reason: 'delegation_refused' } }
 	}
 
 	/**
-	 * 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.
+	 * An OAuth resource token for one registered resource of this app, carrying every scope required. Verified
+	 * locally — no IAM call, no cache. RFC 6750 §3.1: a request without a bearer (none, or another scheme) gets a
+	 * challenge with no error code.
 	 */
-	private async authorizeBearer(app: ProxyApp, bearer: string, requestId: string): Promise<Decision> {
+	private async verifyOAuthBearer(app: ProxyApp, binding: OAuthBinding, bearer: string | null): Promise<OAuthAttempt> {
+		const challenge: OAuthBearerChallenge = { resource_metadata: binding.resource.resourceMetadata }
+		if (bearer === null) {
+			return { ok: false, denial: { outcome: 'deny', status: 401, reason: 'no_credential', challenge } }
+		}
+		const verified = await this.verifier.verify(bearer, { kind: 'resource', app: app.id, resource: binding.resource.resource })
+		if (!verified.ok) {
+			return verified.reason === 'unavailable'
+				? { ok: false, denial: { outcome: 'deny', status: 503, reason: 'iam_unavailable' } }
+				: { ok: false, denial: { outcome: 'deny', status: 401, reason: 'invalid_token', challenge: { ...challenge, error: 'invalid_token' } } }
+		}
+		const granted = verified.claims.oauth?.scopes ?? []
+		if (!binding.scopes.every((scope) => granted.includes(scope))) {
+			const scope = binding.scopes.join(' ')
+			return {
+				ok: false,
+				denial: { outcome: 'deny', status: 403, reason: 'insufficient_scope', challenge: { ...challenge, error: 'insufficient_scope', scope } },
+			}
+		}
+		return { ok: true, token: bearer, claims: verified.claims }
+	}
+
+	/** Exchange a `px_` key for a verified token, through the cache. A non-`px_` bearer is refused with no IAM call. */
+	private async exchangeKey(app: ProxyApp, bearer: string, requestId: string): Promise<KeyAttempt> {
 		if (!bearer.startsWith(API_KEY_PREFIX)) {
-			return { outcome: 'deny', status: 401, reason: 'invalid_key' }
+			return { ok: false, denial: invalidKey() }
 		}
 
 		const key = cacheKey(app.id, 'key', bearer)
@@ -203,12 +374,12 @@ export class Authorizer {
 		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 }
+				return { ok: true, token: cached.token, claims: verified.claims }
 			}
 			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' }
+				return { ok: false, denial: { 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.
@@ -217,18 +388,16 @@ export class Authorizer {
 
 		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 }
+			return { ok: false, denial: { 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' }
+			return { ok: false, denial: verified.reason === 'unavailable' ? { outcome: 'deny', status: 503, reason: 'iam_unavailable' } : invalidKey() }
 		}
 		this.cache?.set(key, { token: minted.token, expiresAt: minted.expiresAt })
-		return { outcome: 'allow', gate: 'service', token: minted.token, subject: verified.claims.sub }
+		return { ok: true, token: minted.token, claims: verified.claims }
 	}
 
 	/**
@@ -236,8 +405,8 @@ export class Authorizer {
 	 *   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.
+	 * Every tier additionally requires `ptype: 'user'`: a session 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')
@@ -256,7 +425,7 @@ export class Authorizer {
 		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 }
+				return { ok: true, token: cached.token, claims: verified.claims }
 			}
 			if (!verified.ok && verified.reason === 'unavailable') {
 				// Nothing is wrong with the entry — we simply cannot check it. Keep it and say so.
@@ -268,7 +437,9 @@ export class Authorizer {
 
 		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 }
+			return minted.reason === 'token_too_large'
+				? { ok: false, status: 'refused', reason: minted.reason }
+				: { ok: false, status: 'miss', reason: minted.reason }
 		}
 		const verified = await this.verifier.verify(minted.token, app.id)
 		if (!verified.ok) {
@@ -281,7 +452,7 @@ export class Authorizer {
 			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 }
+		return { ok: true, token: minted.token, claims: verified.claims }
 	}
 
 	/**
@@ -299,9 +470,8 @@ export class Authorizer {
 	}
 
 	/**
-	 * 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.
+	 * Redeem a handoff code (ADR-0022). Called for the reserved callback path only, BEFORE the endpoint
+	 * is planned — the callback is how a browser obtains a session, so it cannot be behind an endpoint.
 	 *
 	 * 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.
@@ -343,7 +513,11 @@ export class Authorizer {
 		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> {
+	private async loginDecision(
+		app: ProxyApp,
+		request: ForwardedRequest,
+		reason: SessionFailureReason,
+	): Promise<Extract<Decision, { outcome: 'login' }>> {
 		const handoff = await createHandoffAttempt()
 		return {
 			outcome: 'login',
@@ -375,6 +549,44 @@ export class Authorizer {
 	}
 }
 
+function invalidKey(): Denial {
+	return { outcome: 'deny', status: 401, reason: 'invalid_key' }
+}
+
+/**
+ * The resource and scopes of a row that admits `oauth`, `null` for any other row, and `unregistered` when the entry
+ * has no resource on the row's path.
+ */
+function oauthBindingOf(app: ProxyApp, row: ManifestEndpointRow): OAuthBinding | null | 'unregistered' {
+	const required = 'oauth' in row ? row.oauth : null
+	if (required === null) {
+		return null
+	}
+	const resource = 'installation' in app ? oauthResourceOfRow(app, row) : null
+	return resource === null ? 'unregistered' : { resource, scopes: required.scopes }
+}
+
+/**
+ * A refused `px_` key on a row that admits `oauth` still tells an OAuth client where the resource's metadata is
+ * (RFC 6750 §3): a 401 as `invalid_token`, a 403 with no error code. Status and reason stay those of the key.
+ */
+function withBearerChallenge(denial: Denial, oauth: OAuthBinding | null): Denial {
+	if (oauth === null || (denial.status !== 401 && denial.status !== 403)) {
+		return denial
+	}
+	const challenge: OAuthBearerChallenge = { resource_metadata: oauth.resource.resourceMetadata }
+	return { ...denial, challenge: denial.status === 401 ? { ...challenge, error: 'invalid_token' } : challenge }
+}
+
+/** An endpoint that admits a body admits only its declared media types (ADR-0022 rule 3, admission). */
+function admitBody(row: ManifestEndpointRow, headers: Headers): Denial | null {
+	if (row.admission === null) {
+		return null
+	}
+	const type = headers.get('Content-Type')?.split(';')[0]?.trim().toLowerCase() ?? ''
+	return row.admission.contentTypes.includes(type) ? null : { outcome: 'deny', status: 400, reason: 'content_type' }
+}
+
 /**
  * Is this a top-level document navigation — the one caller a 302 actually helps?
  *

package/src/constants.ts

@@ -3,12 +3,12 @@
  * (`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'
+export { CLIENT_ADDRESS_HEADER, DELEGATION_HEADER, ENDPOINT_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
+// in these headers. `reverse_proxy` adds the other three X-Forwarded-* itself. Everything the
 // decision depends on comes from here — never from the `/verify` request's own method/path.
 
 export const FORWARDED_METHOD_HEADER = 'X-Forwarded-Method'

package/src/credentials.ts

@@ -0,0 +1,25 @@
+// Reading a `px_` credential off a request: the bearer header and the session cookie.
+
+/** 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
+}