@fabrika/proxy-core 0.3.3 → 0.4.1

package/src/service.ts

@@ -21,7 +21,17 @@
  *      back on a 2xx, so the edge is the only thing that mints either.
  */
 
-import { AUTH_CALLBACK_PATH, HANDOFF_COOKIE_TTL_SECONDS, SESSION_COOKIE } from '@fabrika/auth-core'
+import {
+	AUTH_CALLBACK_PATH,
+	compileEndpointTable,
+	DELEGATION_HEADER,
+	ENDPOINT_HEADER,
+	HANDOFF_COOKIE_TTL_SECONDS,
+	isCanonicalPath,
+	planEndpoint,
+	SESSION_COOKIE,
+	splitRequestTarget,
+} 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'
@@ -36,11 +46,20 @@ import {
 	PROXY_TOKEN_HEADER,
 	REQUEST_ID_HEADER,
 } from './constants'
-import { compileGates } from './gates'
 import { type HandoffAttempt, handoffCookieName } from './handoff'
-import type { IamGateway } from './iam'
+import {
+	appFileTreatment,
+	appHeaderPolicy,
+	applyFileTreatment,
+	applyHeaderPolicy,
+	BASE_HEADER_POLICY,
+	type HeaderPolicy,
+	transportPolicy,
+} from './headers'
+import type { DelegationIssuer, IamGateway } from './iam'
 import { type LogFields, type ProxyLogger, redactPath, silentLogger } from './log'
-import type { ProxyManifest } from './manifest'
+import { formatOAuthBearerChallenge, isApplicationEntry, type ManifestEndpointRow, type ProxyApp, type ProxyManifest } from './manifest'
+import { findOAuthMetadata, OAUTH_METADATA_VERIFY_PATH, oauthMetadataResponse } from './oauth'
 
 export interface VerifyServiceConfig {
 	manifest: ProxyManifest
@@ -54,6 +73,8 @@ export interface VerifyServiceConfig {
 	healthPath?: string
 	/** Unix seconds. Injectable for tests. */
 	now?: () => number
+	/** Issues delegation grants for membership and scope-creating endpoints; see `AuthorizerOptions.delegations`. */
+	delegations?: DelegationIssuer | null
 }
 
 export type VerifyService = (request: Request) => Promise<Response>
@@ -62,8 +83,8 @@ export type VerifyService = (request: Request) => Promise<Response>
 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.
+ * Build the `/verify` service. Endpoint tables are compiled once here, not per request — the planner is
+ * on the hot path of every request to every app.
  */
 export function createVerifyService(config: VerifyServiceConfig): VerifyService {
 	const logger = config.logger ?? silentLogger
@@ -71,9 +92,11 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 
 	const byId = new Map<string, ResolvedApp>()
 	const byHost = new Map<string, ResolvedApp>()
+	const policies = new Map<string, HeaderPolicy>()
 	for (const app of config.manifest.apps) {
-		const resolved: ResolvedApp = { app, gates: compileGates(app.gates) }
+		const resolved = resolveApp(app)
 		byId.set(app.id, resolved)
+		policies.set(app.id, isApplicationEntry(app) ? appHeaderPolicy(app) : BASE_HEADER_POLICY)
 		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)
@@ -87,6 +110,9 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 	if (config.now !== undefined) {
 		authorizerOptions.now = config.now
 	}
+	if (config.delegations !== undefined) {
+		authorizerOptions.delegations = config.delegations
+	}
 	const authorizer = new Authorizer(authorizerOptions)
 
 	return async (request: Request): Promise<Response> => {
@@ -99,30 +125,36 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 			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 (url.pathname !== DEFAULT_VERIFY_PATH && url.pathname !== OAUTH_METADATA_VERIFY_PATH) {
+				return withPolicy(textResponse(404, 'not found'), BASE_HEADER_POLICY)
 			}
 			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')
+				return withPolicy(textResponse(405, 'method not allowed'), BASE_HEADER_POLICY)
 			}
 
-			const forwarded = readForwardedRequest(request, requestId)
-			if (forwarded === null) {
-				return denied(logger, { requestId }, { outcome: 'deny', status: 403, reason: 'bad_forward' })
+			const read = readForwardedRequest(request, requestId)
+			if (!read.ok) {
+				const status = read.reason === 'non_canonical_path' ? 400 : 403
+				return withPolicy(denied(logger, { requestId }, { outcome: 'deny', status, reason: read.reason }), earlyPolicy(request, url))
 			}
+			const forwarded = read.request
 
 			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',
-				})
+				const fields = { requestId, host: forwarded.url.host, path: redactPath(forwarded.url.pathname) }
+				return withPolicy(denied(logger, fields, { outcome: 'deny', status: 403, reason: 'no_app' }), BASE_HEADER_POLICY)
+			}
+
+			if (url.pathname === OAUTH_METADATA_VERIFY_PATH) {
+				const metadata = findOAuthMetadata(resolved.app, forwarded.url)
+				return metadata === null
+					? withPolicy(textResponse(404, 'not found'), policies.get(resolved.app.id) ?? BASE_HEADER_POLICY)
+					: oauthMetadataResponse(metadata, forwarded.method)
 			}
 
-			// 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
+			// The handoff callback is checked BEFORE the endpoint table: it is how a browser obtains a
+			// session, so it cannot itself be behind an endpoint. Because Caddy returns a non-2xx auth
 			// response verbatim, answering 302 + Set-Cookie here reaches the client and never the app.
 			const isCallback = forwarded.url.pathname === AUTH_CALLBACK_PATH
 			const decision = isCallback
@@ -136,25 +168,68 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 				path: redactPath(forwarded.url.pathname),
 			}
 			if (decision.outcome === 'allow') {
-				logger.info('allow', { ...fields, gate: decision.gate, subject: decision.subject })
+				logger.info('allow', { ...fields, subject: decision.subject, endpoint: decision.endpoint })
 				const headers = new Headers({ 'cache-control': 'no-store', [REQUEST_ID_HEADER]: requestId })
 				if (decision.token !== null) {
 					headers.set(PROXY_TOKEN_HEADER, decision.token)
 				}
+				if (decision.endpoint !== null) {
+					headers.set(ENDPOINT_HEADER, decision.endpoint)
+				}
+				if (decision.delegation !== null) {
+					headers.set(DELEGATION_HEADER, decision.delegation)
+				}
 				return new Response(null, { status: 204, headers })
 			}
-			if (decision.outcome === 'handoff') {
-				logger.info('handoff', fields)
-				return handoffResponse(decision)
-			}
-			return denied(logger, fields, decision, isCallback)
+			const answer = decision.outcome === 'handoff' ? handoff(logger, fields, decision) : denied(logger, fields, decision, isCallback)
+			return isDownload(resolved, forwarded)
+				? withFileTreatment(answer, appFileTreatment(resolved.app))
+				: withPolicy(answer, policies.get(resolved.app.id) ?? BASE_HEADER_POLICY)
 		} 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')
+			return withPolicy(textResponse(403, 'forbidden'), earlyPolicy(request, null))
 		}
 	}
+
+	/**
+	 * A refusal before the request is read: the base policy, plus the transport header of the application host it
+	 * names, when the forwarded host (and the pinned app) resolves to one. Nothing of the host decides anything else.
+	 */
+	function earlyPolicy(request: Request, verifyUrl: URL | null): HeaderPolicy {
+		try {
+			const host = request.headers.get(FORWARDED_HOST_HEADER) ?? request.headers.get('Host') ?? ''
+			const resolved = selectApp(verifyUrl ?? new URL(request.url), host, byId, byHost)
+			return resolved === null || !isApplicationEntry(resolved.app)
+				? BASE_HEADER_POLICY
+				: [...BASE_HEADER_POLICY, ...transportPolicy(resolved.app.scheme)]
+		} catch {
+			return BASE_HEADER_POLICY
+		}
+	}
+}
+
+function handoff(logger: ProxyLogger, fields: LogFields, decision: Extract<Decision, { outcome: 'handoff' }>): Response {
+	logger.info('handoff', fields)
+	return handoffResponse(decision)
+}
+
+/** An answer the proxy writes reaches the client as-is, so it carries the policy the application's own answers do. */
+function withPolicy(response: Response, policy: HeaderPolicy): Response {
+	applyHeaderPolicy(response.headers, policy)
+	return response
+}
+
+function withFileTreatment(response: Response, treatment: HeaderPolicy): Response {
+	applyFileTreatment(response.headers, treatment)
+	return response
+}
+
+/** Whether the request selects a download endpoint, whose every answer gets the file treatment instead of the policy. */
+function isDownload(resolved: ResolvedApp, forwarded: ForwardedRequest): boolean {
+	const plan = planEndpoint(resolved.table, forwarded.method, forwarded.rawPath)
+	return plan.outcome === 'endpoint' && plan.endpoint.kind === 'download'
 }
 
 /**
@@ -198,12 +273,13 @@ function denied(
 			: loginRequired(decision.location, decision.handoff)
 	}
 	logger.warn('deny', { ...fields, reason, status: decision.status })
-	const response = isCallback
-		? callbackFailure(decision.status)
-		: textResponse(decision.status, decision.status === 401 ? 'unauthorized' : decision.status === 503 ? 'unavailable' : 'forbidden')
+	const response = isCallback ? callbackFailure(decision.status) : textResponse(decision.status, DENY_TEXT[decision.status])
 	if (decision.clearHandoffState !== undefined) {
 		response.headers.append('set-cookie', clearHandoffCookie(decision.clearHandoffState))
 	}
+	if (decision.challenge !== undefined) {
+		response.headers.set('WWW-Authenticate', formatOAuthBearerChallenge(decision.challenge))
+	}
 	return response
 }
 
@@ -300,46 +376,57 @@ function secureCookie(name: string, value: string, maxAge: number): string {
 	return [`${name}=${value}`, 'Path=/', `Max-Age=${maxAge}`, 'HttpOnly', 'SameSite=Lax', 'Secure'].join('; ')
 }
 
+const DENY_TEXT: Record<Extract<Decision, { outcome: 'deny' }>['status'], string> = {
+	400: 'bad request',
+	401: 'unauthorized',
+	403: 'forbidden',
+	503: 'unavailable',
+}
+
 function textResponse(status: number, body: string): Response {
 	return new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
 }
 
+type ForwardedRead = { ok: true; request: ForwardedRequest } | { ok: false; reason: 'bad_forward' | 'non_canonical_path' }
+
 /**
- * Rebuild the original request from the forwarded headers. Returns null — a DENY — whenever the
+ * Rebuild the original request from the forwarded headers. Refuses — 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.
+ * that authorizes the wrong thing. That includes a missing method: there is no default to guess.
+ *
+ * The path is checked RAW, before any URL is built: assigning a pathname resolves `..` and `%2e%2e`, so
+ * `/a/../admin` would otherwise be matched as `/admin` while the upstream receives the original.
  *
  * 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
+ * URL, silently changing the host — which would both select the wrong app and turn the login bounce
  * into an open redirect.
  */
-function readForwardedRequest(request: Request, requestId: string): ForwardedRequest | null {
+function readForwardedRequest(request: Request, requestId: string): ForwardedRead {
 	const uri = request.headers.get(FORWARDED_URI_HEADER)
-	if (uri === null || !uri.startsWith('/')) {
-		return null
+	const method = request.headers.get(FORWARDED_METHOD_HEADER)
+	if (uri === null || !uri.startsWith('/') || method === null || method === '') {
+		return { ok: false, reason: 'bad_forward' }
+	}
+	const target = splitRequestTarget(uri)
+	if (!isCanonicalPath(target.pathname)) {
+		return { ok: false, reason: 'non_canonical_path' }
 	}
 	const host = request.headers.get(FORWARDED_HOST_HEADER) ?? request.headers.get('Host')
 	if (host === null || !HOST_PATTERN.test(host)) {
-		return null
+		return { ok: false, reason: 'bad_forward' }
 	}
 	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)
+	url.pathname = target.pathname
+	url.search = target.search
 	if (url.host.toLowerCase() !== host.toLowerCase()) {
 		// Defensive: the assignment above must not have been able to move the host.
-		return null
+		return { ok: false, reason: 'bad_forward' }
 	}
 
-	return {
-		method: request.headers.get(FORWARDED_METHOD_HEADER) ?? 'GET',
-		url,
-		headers: request.headers,
-		requestId,
-	}
+	return { ok: true, request: { method, url, rawPath: target.pathname, headers: request.headers, requestId } }
 }
 
 /**
@@ -366,6 +453,11 @@ function selectApp(verifyUrl: URL, host: string, byId: Map<string, ResolvedApp>,
 	return byHost.get(hostname) ?? null
 }
 
+/** The compiled table an app is protected by. The manifest parser already refused an ambiguous table. */
+function resolveApp(app: ProxyApp): ResolvedApp {
+	return { app, table: compileEndpointTable<ManifestEndpointRow>(app) }
+}
+
 /** 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

@@ -8,7 +8,7 @@
  * not per verifier.
  */
 
-import type { Jwks } from '@fabrika/auth-core'
+import type { Jwks, TokenAudienceProfile } from '@fabrika/auth-core'
 import { TokenVerifier as JwksVerifier, type VerifyResult } from '@fabrika/jwks'
 import { JWKS_REFETCH_COOLDOWN_SECONDS, JWKS_TTL_SECONDS } from './constants'
 
@@ -28,11 +28,11 @@ export class TokenVerifier {
 	}
 
 	/**
-	 * Verify `token` for `audience`. An unknown `kid` forces one JWKS refetch (a key rotated in), then a
+	 * Verify `token` for `audience` (a bare string is an app id). An unknown `kid` forces 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`.
 	 */
-	verify(token: string, audience: string): Promise<VerifyResult> {
+	verify(token: string, audience: string | TokenAudienceProfile): Promise<VerifyResult> {
 		return this.inner.verify(token, audience)
 	}
 }

package/src/gates.ts

@@ -1,65 +0,0 @@
-/**
- * Credential extraction for the gate evaluator relocated out of the app's process
- * ([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;
- *   - 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
-}