@fabrika/proxy-core 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/proxy-core",
-	"version": "0.6.0",
+	"version": "0.8.0",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -37,9 +37,9 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "0.6.0",
-		"@fabrika/jwks": "0.6.0",
+		"@fabrika/auth-core": "0.8.0",
+		"@fabrika/jwks": "0.8.0",
 		"jose": "^5.9.0",
-		"@fabrika/platform": "0.6.0"
+		"@fabrika/platform": "0.8.0"
 	}
 }

package/src/authorize.ts

@@ -27,6 +27,7 @@ import {
 	callerOf,
 	type CompiledEndpointTable,
 	FORM_MULTIPART_TYPE,
+	FORM_URLENCODED_TYPE,
 	formatEndpointHeader,
 	planEndpoint,
 	satisfies,
@@ -36,7 +37,7 @@ import {
 } from '@fabrika/auth-core'
 import { cacheKey, type TokenCache } from './cache'
 import { LOGIN_REDIRECT_PARAM } from './constants'
-import { readBearer, readCookie } from './credentials'
+import { carriesPlatformKey, readBearer, readCookie } from './credentials'
 import { createHandoffAttempt, type HandoffAttempt, handoffCookieName, setHandoffParams } from './handoff'
 import { type DelegationIssuer, type IamGateway, IamUnavailableError } from './iam'
 import {
@@ -109,6 +110,11 @@ export type Decision =
 		delegation: string | null
 		/** The `Access-Control-Allow-Origin` the answer carries: the request's admitted origin, `*`, or none. */
 		crossOrigin: string | null
+		/**
+		 * Whether the request's own `Authorization` reaches the application: on a webhook row that forwards it, unless it
+		 * carries a platform key. Every other anonymous request loses it (ADR-0022 rule 3).
+		 */
+		forwardsAuthorization: boolean
 	}
 	| {
 		outcome: 'deny'
@@ -306,7 +312,15 @@ export class Authorizer {
 		const endpoint = formatEndpointHeader(row.id, row.digest)
 		if (row.requirement === null) {
 			return admitBody(row, request.headers) ?? admitFormOrigin(app, row, request, crossOrigin)
-				?? { outcome: 'allow', token: null, subject: null, endpoint, delegation: null, crossOrigin }
+				?? {
+					outcome: 'allow',
+					token: null,
+					subject: null,
+					endpoint,
+					delegation: null,
+					crossOrigin,
+					forwardsAuthorization: forwardsAuthorization(row, request),
+				}
 		}
 		const oauth = oauthBindingOf(app, row)
 		if (oauth === 'unregistered') {
@@ -344,6 +358,7 @@ export class Authorizer {
 			endpoint,
 			delegation: delegation?.grant ?? null,
 			crossOrigin,
+			forwardsAuthorization: false,
 		}
 	}
 
@@ -661,27 +676,41 @@ function withBearerChallenge(denial: Denial, oauth: OAuthBinding | null): Denial
 	return { ...denial, challenge: denial.status === 401 ? { ...challenge, error: 'invalid_token' } : challenge }
 }
 
+/** The media types a browser sends from any page without a CORS preflight, which therefore carry no origin check of their own. */
+const PREFLIGHTLESS_TYPES: readonly string[] = [FORM_MULTIPART_TYPE, FORM_URLENCODED_TYPE]
+
 /**
- * A multipart form admits a browser's request only from the application's own origin or one the row admits (ADR-0022
- * "Cross-origin endpoints"). A page on any origin sends `multipart/form-data` without a preflight, so the proxy refuses
- * at the request what it refuses at the preflight of a JSON form. A request without `Origin` is no browser's
- * cross-origin request.
+ * An anonymous body a browser sends without a preflight is admitted only from the application's own origin or one the
+ * row admits (ADR-0022 "Cross-origin endpoints", the browser admission matrix): a multipart form, and a public
+ * procedure's multipart or urlencoded body. The proxy refuses at the request what it refuses at the preflight of a JSON
+ * body. A request without `Origin` is no browser's cross-origin request; `Origin: null` names no origin and is refused.
  */
 function admitFormOrigin(app: ProxyApp, row: ManifestEndpointRow, request: ForwardedRequest, crossOrigin: string | null): Denial | null {
 	const origin = request.headers.get(ORIGIN_HEADER)
-	if (row.kind !== 'form' || origin === null || crossOrigin !== null || !(row.admission?.contentTypes.includes(FORM_MULTIPART_TYPE) ?? false)) {
+	if (origin === null || crossOrigin !== null || !preflightless(row, request.headers)) {
 		return null
 	}
 	return origin === `${app.scheme}://${request.url.host}` ? null : { outcome: 'deny', status: 403, reason: 'cross_origin' }
 }
 
+/** A form that takes files (whatever this request sends), or a public procedure's request of a preflightless type. */
+function preflightless(row: ManifestEndpointRow, headers: Headers): boolean {
+	if (row.kind === 'form') {
+		return row.admission?.contentTypes.includes(FORM_MULTIPART_TYPE) ?? false
+	}
+	return row.kind === 'public' && PREFLIGHTLESS_TYPES.includes(mediaTypeOf(headers))
+}
+
+function mediaTypeOf(headers: Headers): string {
+	return headers.get('Content-Type')?.split(';')[0]?.trim().toLowerCase() ?? ''
+}
+
 /** 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' }
+	return row.admission.contentTypes.includes(mediaTypeOf(headers)) ? null : { outcome: 'deny', status: 400, reason: 'content_type' }
 }
 
 /**
@@ -707,3 +736,12 @@ function isDocumentNavigation(headers: Headers): boolean {
 	const mode = headers.get(FETCH_MODE_HEADER)
 	return mode === null || mode === '' || mode === 'navigate'
 }
+
+/**
+ * The `Authorization` of an anonymous request is the application's only on a row that forwards it, and never when it
+ * carries a platform key. The proxy reads no credential from it either way: no key lookup, no session.
+ */
+function forwardsAuthorization(row: ManifestEndpointRow, request: ForwardedRequest): boolean {
+	const authorization = request.headers.get('Authorization')
+	return 'authorization' in row && row.authorization === 'forward' && authorization !== null && !carriesPlatformKey(authorization, API_KEY_PREFIX)
+}

package/src/constants.ts

@@ -27,6 +27,13 @@ export const DEFAULT_VERIFY_PATH = '/verify'
  */
 export const PREFLIGHT_HEADER = 'X-Fabrika-Preflight'
 
+/**
+ * Set on the auth service's 2xx when the request's own `Authorization` goes on to the application: an anonymous webhook
+ * row that forwards it. Every composition deletes `Authorization` from an anonymous request without it, and passes the
+ * marker on to no one.
+ */
+export const FORWARD_AUTHORIZATION_HEADER = 'X-Fabrika-Forward-Authorization'
+
 /** Liveness endpoint on the auth service itself — never routed publicly. */
 export const DEFAULT_HEALTH_PATH = '/healthz'
 /**

package/src/credentials.ts

@@ -9,6 +9,27 @@ export function readBearer(header: string | null): string | null {
 	return match ? (match[1]?.trim() ?? null) : null
 }
 
+/**
+ * Whether an `Authorization` value carries a platform key anywhere: the header itself, or the user or password of Basic
+ * credentials. Such a value is never forwarded to an application, whatever its row says: a key sent to a webhook URL
+ * by mistake must not reach application code.
+ */
+export function carriesPlatformKey(header: string, keyPrefix: string): boolean {
+	if (header.includes(keyPrefix)) {
+		return true
+	}
+	const basic = /^Basic\s+([A-Za-z0-9+/=]+)$/i.exec(header.trim())
+	if (basic?.[1] === undefined) {
+		return false
+	}
+	try {
+		return atob(basic[1]).includes(keyPrefix)
+	} catch {
+		// Not base64: the application refuses it as a verifier would, and it holds no readable key.
+		return false
+	}
+}
+
 /** 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) {

package/src/headers.ts

@@ -2,7 +2,7 @@
 // "Response headers"). The proxy sets them on every answer, its own denials included; the framework sets the same
 // definition in-process. Exported as `@fabrika/proxy-core/headers`, which imports nothing at runtime.
 
-import type { CspExtensions } from '@fabrika/auth-core'
+import type { CspExtensions, EndpointCache } from '@fabrika/auth-core'
 
 /** Every powerful feature off. ADR-0022 lists the same names; change both together. */
 export const PERMISSIONS_POLICY_FEATURES: readonly string[] = [
@@ -54,8 +54,17 @@ export interface CspOrigins {
 	readonly frameSrc: readonly string[]
 	readonly styleSrc: readonly string[]
 	readonly fontSrc: readonly string[]
+	/**
+	 * `worker-src 'self' blob:` is emitted only when it holds `blob:`, its one source (a challenge widget that starts its
+	 * workers from `Blob` URLs); without it workers fall back to `script-src`. Absent from every manifest without it, so a
+	 * proxy that does not know the directive still parses those.
+	 */
+	readonly workerSrc?: readonly string[]
 }
 
+/** The one source a contract's `workerSrc` holds: a worker the page's own script built from a `Blob`. */
+export const WORKER_BLOB_SOURCE = 'blob:'
+
 const HOSTNAME = /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
 
 /**
@@ -93,6 +102,7 @@ export function cspOrigins(csp: CspExtensions): CspOrigins {
 		frameSrc: (csp.frameSrc ?? []).map((source) => source.origin),
 		styleSrc: (csp.styleSrc ?? []).map((source) => source.origin),
 		fontSrc: (csp.fontSrc ?? []).map((source) => source.origin),
+		...(csp.workerSrc === undefined ? {} : { workerSrc: csp.workerSrc.map((source) => source.origin) }),
 	}
 }
 
@@ -116,6 +126,7 @@ export function headerPolicy(origins: CspOrigins, operationsOrigin: string | nul
 		`frame-ancestors ${frameAncestors.join(' ')}`,
 		// Without it frames fall back to `default-src 'self'`; a declared origin only extends that, so `'self'` stays.
 		...(origins.frameSrc.length === 0 ? [] : [`frame-src ${["'self'", ...origins.frameSrc].join(' ')}`]),
+		...(origins.workerSrc?.includes(WORKER_BLOB_SOURCE) === true ? [`worker-src 'self' ${WORKER_BLOB_SOURCE}`] : []),
 	]
 	return Object.freeze([
 		['Content-Security-Policy', directives.join('; ')],
@@ -257,6 +268,21 @@ export function applyFileTreatment(headers: Headers, treatment: HeaderPolicy = F
 	headers.set('Content-Disposition', `${fileDisposition(headers.get('Content-Type'))}${parameters}`)
 }
 
+/**
+ * A cacheable row's successful answer (`http.cache`): its `Cache-Control` replaces the `no-store` of the policy or the
+ * file treatment. Every other answer, an error or a redirect included, keeps `no-store`.
+ */
+export function applyAnswerCache(headers: Headers, row: { readonly cache?: EndpointCache }, status: number): void {
+	if (row.cache !== undefined && status === 200) {
+		headers.set('Cache-Control', cacheControlOf(row.cache))
+	}
+}
+
+/** The `Cache-Control` of a cacheable row's successful answer: `immutable` is reused for a year. */
+export function cacheControlOf(cache: EndpointCache): string {
+	return cache === 'immutable' ? 'public, max-age=31536000, immutable' : `public, max-age=${cache.maxAgeSeconds}`
+}
+
 /** A copy of `response` whose headers `apply` rewrote; status and body are unchanged. */
 export function withResponseHeaders(response: Response, apply: (headers: Headers) => void): Response {
 	const headers = new Headers(response.headers)

package/src/index.ts

@@ -22,6 +22,7 @@ export {
 	DEFAULT_VERIFY_PATH,
 	DELEGATION_HEADER,
 	ENDPOINT_HEADER,
+	FORWARD_AUTHORIZATION_HEADER,
 	FORWARDED_HOST_HEADER,
 	FORWARDED_METHOD_HEADER,
 	FORWARDED_PROTO_HEADER,
@@ -33,7 +34,7 @@ export {
 	REQUEST_ID_HEADER,
 	UNTRUSTED_FORWARD_HEADERS,
 } from './constants'
-export { readBearer, readCookie } from './credentials'
+export { carriesPlatformKey, readBearer, readCookie } from './credentials'
 export { stripFabrikaCookies } from './handoff'
 export { HttpIamGateway, IamUnavailableError } from './iam'
 export type { DelegationIssuer, DelegationRequest, HttpIamGatewayOptions, IamGateway } from './iam'

package/src/manifest.ts

@@ -12,14 +12,16 @@ import {
 	endpointDelegation,
 	type EndpointRow,
 	EndpointTableError,
+	FILE_RESPONSE_KINDS,
 	type InstallationEndpointRow,
 	type InstallationEndpointTable,
 	isDigest,
+	MAX_CACHE_AGE_SECONDS,
 	parseAppEnvironmentId,
 	requirementDigest,
 } from '@fabrika/auth-core'
 import { z } from 'zod'
-import { type CspOrigins, cspOrigins, isCrossOrigin, isPolicyOrigin, MAX_CROSS_ORIGINS, MAX_CSP_ORIGINS } from './headers'
+import { type CspOrigins, cspOrigins, isCrossOrigin, isPolicyOrigin, MAX_CROSS_ORIGINS, MAX_CSP_ORIGINS, WORKER_BLOB_SOURCE } from './headers'
 import { type OAuthProtectedResource, oauthProtectedResourceSchema, oauthScopesSchema } from './oauth-resource'
 
 export * from './oauth-resource'
@@ -92,9 +94,15 @@ interface ProxyEndpointExtras {
 
 /** An endpoint row as the proxy applies it: the rules without the schemas, plus the digest and the delegation. */
 export type ProxyEndpointRow =
-	| (Pick<CredentialedEndpoint, 'id' | 'kind' | 'method' | 'path' | 'callers' | 'requirement' | 'admission' | 'crossOrigin'> & ProxyEndpointExtras)
 	| (
-		& Pick<Extract<EndpointRow, { requirement: null }>, 'id' | 'kind' | 'method' | 'path' | 'callers' | 'requirement' | 'admission' | 'crossOrigin'>
+		& Pick<CredentialedEndpoint, 'id' | 'kind' | 'method' | 'path' | 'callers' | 'requirement' | 'admission' | 'crossOrigin' | 'response'>
+		& ProxyEndpointExtras
+	)
+	| (
+		& Pick<
+			Extract<EndpointRow, { requirement: null }>,
+			'id' | 'kind' | 'method' | 'path' | 'callers' | 'requirement' | 'admission' | 'crossOrigin' | 'response' | 'cache' | 'authorization'
+		>
 		& {
 			digest: string
 			delegation: null
@@ -156,9 +164,19 @@ const accessFormSchema = z.discriminatedUnion('form', [
 	z.object({ form: z.literal('creates'), dimension: nameSchema }).strict(),
 	z.object({ form: z.literal('app') }).strict(),
 ])
+const capabilityFormSchema = z.discriminatedUnion('form', [
+	z.object({ form: z.literal('over'), dimension: nameSchema }).strict(),
+	z.object({ form: z.literal('in'), dimension: nameSchema, from: nameSchema }).strict(),
+	z.object({ form: z.literal('on'), dimension: nameSchema, from: nameSchema }).strict(),
+])
+const capabilitySchema = z.object({ action: nameSchema, access: capabilityFormSchema }).strict()
 const requirementSchema = z.discriminatedUnion('kind', [
 	z.object({ kind: z.literal('member') }).strict(),
 	z.object({ kind: z.literal('action'), action: nameSchema, access: accessFormSchema }).strict(),
+	z.object({
+		kind: z.literal('capabilities'),
+		capabilities: z.record(nameSchema, capabilitySchema).refine((capabilities) => Object.keys(capabilities).length >= 2, 'at least two capabilities'),
+	}).strict(),
 ])
 const admissionSchema = z.object({
 	contentTypes: z.array(nameSchema).nonempty(),
@@ -180,14 +198,18 @@ export const proxyEndpointRowSchema = z.union([
 		requirement: requirementSchema,
 		delegation: z.enum(['members', 'creates']).nullable(),
 		crossOrigin: z.literal('environment').optional(),
+		response: z.literal('file').optional(),
 	}).strict(),
 	z.object({
 		...endpointRuleFields,
-		kind: z.enum(['health', 'form', 'webhook', 'link-spa']),
+		kind: z.enum(['health', 'form', 'webhook', 'link-spa', 'public']),
 		callers: z.tuple([]),
 		requirement: z.null(),
 		delegation: z.null(),
 		crossOrigin: z.enum(['environment', 'any']).optional(),
+		response: z.literal('file').optional(),
+		cache: z.union([z.literal('immutable'), z.object({ maxAgeSeconds: z.number().int().min(1).max(MAX_CACHE_AGE_SECONDS) }).strict()]).optional(),
+		authorization: z.literal('forward').optional(),
 	}).strict(),
 	// A public SPA is a fixed static row: it serves GET only and admits no body.
 	z.object({
@@ -202,6 +224,15 @@ export const proxyEndpointRowSchema = z.union([
 ]).refine(
 	(row) => crossOriginAllowed(row.kind, 'crossOrigin' in row ? row.crossOrigin : undefined),
 	'this endpoint kind cannot be called cross-origin',
+).refine(
+	(row) => !('response' in row) || row.response === undefined || FILE_RESPONSE_KINDS.includes(row.kind),
+	'only a procedure answers a stored file',
+).refine(
+	(row) => !('cache' in row) || row.cache === undefined || (row.kind === 'public' && row.method === 'GET'),
+	'only a public GET query caches its answer',
+).refine(
+	(row) => !('authorization' in row) || row.authorization === undefined || row.kind === 'webhook',
+	"only a webhook forwards the request's Authorization",
 ).refine(
 	(row) => row.digest === requirementDigest(row),
 	'endpoint digest does not match its rules',
@@ -211,7 +242,7 @@ export const proxyEndpointRowSchema = z.union([
 	unknown
 >
 
-/** Only an RPC procedure and a form open to another origin, and only a form to any origin (ADR-0022). */
+/** Only an RPC procedure, a public procedure and a form open to another origin, and only the anonymous two to any (ADR-0022). */
 function crossOriginAllowed(kind: ProxyEndpointRow['kind'], form: CrossOriginForm | undefined): boolean {
 	return form === undefined || (CROSS_ORIGIN_KINDS.includes(kind) && (form !== 'any' || ANY_ORIGIN_KINDS.includes(kind)))
 }
@@ -236,6 +267,8 @@ const cspOriginsSchema = z.object({
 	frameSrc: cspDirectiveSchema.default([]),
 	styleSrc: cspDirectiveSchema.default([]),
 	fontSrc: cspDirectiveSchema.default([]),
+	// Only a challenge widget's workers need it, and its one source is `blob:`; absent everywhere else.
+	workerSrc: z.tuple([z.literal(WORKER_BLOB_SOURCE)]).optional(),
 }).strict() satisfies z.ZodType<CspOrigins, z.ZodTypeDef, unknown>
 
 // Strict: a key the proxy does not read (`gates`, or an installation entry's field) is refused, never ignored.
@@ -339,8 +372,10 @@ export const proxyAppSchema = z.union([contractProxyAppSchema, installationProxy
 /**
  * The manifest form of a compiled contract: every endpoint's rules with their digest and delegation, the reserved
  * prefixes, the contract digest and the named CSP origins. Producers call this; they never assemble rows by hand.
+ * `digest` is the one the application's own release computes; Control passes it for an artifact it upcast from an
+ * older release's (ADR-0062).
  */
-export function contractProxyTable(artifact: ContractArtifact): ContractProxyTable {
+export function contractProxyTable(artifact: ContractArtifact, digest: string = contractDigest(artifact)): ContractProxyTable {
 	return {
 		endpoints: artifact.endpoints.map((row): ProxyEndpointRow => {
 			const rules = {
@@ -349,9 +384,12 @@ export function contractProxyTable(artifact: ContractArtifact): ContractProxyTab
 				path: row.path,
 				admission: row.admission,
 				...(row.crossOrigin === undefined ? {} : { crossOrigin: row.crossOrigin }),
+				...(row.response === undefined ? {} : { response: row.response }),
 			}
 			if (row.requirement === null) {
-				const anonymous = { ...rules, kind: row.kind, callers: row.callers, requirement: null, delegation: null }
+				const cache = row.cache === undefined ? {} : { cache: row.cache }
+				const authorization = row.authorization === undefined ? {} : { authorization: row.authorization }
+				const anonymous = { ...rules, ...cache, ...authorization, kind: row.kind, callers: row.callers, requirement: null, delegation: null }
 				return { ...anonymous, digest: requirementDigest(anonymous) }
 			}
 			const credentialed = {
@@ -364,7 +402,7 @@ export function contractProxyTable(artifact: ContractArtifact): ContractProxyTab
 			return { ...credentialed, digest: requirementDigest(credentialed) }
 		}),
 		reservedPrefixes: [...artifact.reservedPrefixes],
-		snapshot: contractDigest(artifact),
+		snapshot: digest,
 		csp: cspOrigins(artifact.csp),
 	}
 }

package/src/service.ts

@@ -22,6 +22,7 @@
  */
 
 import {
+	answersFile,
 	AUTH_CALLBACK_PATH,
 	compileEndpointTable,
 	DELEGATION_HEADER,
@@ -39,6 +40,7 @@ import {
 	APP_QUERY_PARAM,
 	DEFAULT_HEALTH_PATH,
 	DEFAULT_VERIFY_PATH,
+	FORWARD_AUTHORIZATION_HEADER,
 	FORWARDED_HOST_HEADER,
 	FORWARDED_METHOD_HEADER,
 	FORWARDED_PROTO_HEADER,
@@ -183,6 +185,9 @@ export function createVerifyService(config: VerifyServiceConfig): VerifyService
 				if (decision.delegation !== null) {
 					headers.set(DELEGATION_HEADER, decision.delegation)
 				}
+				if (decision.forwardsAuthorization) {
+					headers.set(FORWARD_AUTHORIZATION_HEADER, '1')
+				}
 				// The composition writes it onto the application's answer, after the policy deleted the application's own.
 				if (decision.crossOrigin !== null) {
 					applyCrossOriginHeaders(headers, crossOriginHeaders(decision.crossOrigin))
@@ -244,10 +249,13 @@ function withFileTreatment(response: Response, treatment: HeaderPolicy): Respons
 	return response
 }
 
-/** Whether the request selects a download endpoint, whose every answer gets the file treatment instead of the policy. */
+/**
+ * Whether the request selects a download endpoint or a procedure that answers a stored file, 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'
+	return plan.outcome === 'endpoint' && answersFile(plan.endpoint)
 }
 
 /**