@fabrika/proxy-core 0.3.2 → 0.4.0

package/src/headers.ts

@@ -0,0 +1,210 @@
+// The one response header policy of a contract application and the file treatment of its downloads (ADR-0022,
+// "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'
+
+/** Every powerful feature off. ADR-0022 lists the same names; change both together. */
+export const PERMISSIONS_POLICY_FEATURES: readonly string[] = [
+	'accelerometer',
+	'ambient-light-sensor',
+	'autoplay',
+	'bluetooth',
+	'browsing-topics',
+	'camera',
+	'clipboard-read',
+	'display-capture',
+	'encrypted-media',
+	'fullscreen',
+	'gamepad',
+	'geolocation',
+	'gyroscope',
+	'hid',
+	'identity-credentials-get',
+	'idle-detection',
+	'local-fonts',
+	'magnetometer',
+	'microphone',
+	'midi',
+	'otp-credentials',
+	'payment',
+	'picture-in-picture',
+	'publickey-credentials-create',
+	'publickey-credentials-get',
+	'screen-wake-lock',
+	'serial',
+	'storage-access',
+	'usb',
+	'web-share',
+	'window-management',
+	'xr-spatial-tracking',
+]
+
+const PERMISSIONS_POLICY = PERMISSIONS_POLICY_FEATURES.map((feature) => `${feature}=()`).join(', ')
+
+export type HeaderPolicy = readonly (readonly [name: string, value: string])[]
+
+/** The named origins a contract adds to seven CSP directives: exact `https://` origins, never patterns. */
+export interface CspOrigins {
+	readonly connectSrc: readonly string[]
+	readonly imgSrc: readonly string[]
+	readonly frameAncestors: readonly string[]
+	readonly scriptSrc: readonly string[]
+	/** `frame-src 'self' <origins>` is emitted only when it names an origin; without it frames fall back to `default-src 'self'`. */
+	readonly frameSrc: readonly string[]
+	readonly styleSrc: readonly string[]
+	readonly fontSrc: readonly string[]
+}
+
+const HOSTNAME = /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
+
+/**
+ * An exact origin with a literal hostname: no path, no credentials and no wildcard (`new URL` accepts `*` in a
+ * hostname), so it means one site and is safe inside a header value. CSP origins are `https:` only.
+ */
+export function isPolicyOrigin(value: string, protocols: readonly string[] = ['https:']): boolean {
+	try {
+		const url = new URL(value)
+		return protocols.includes(url.protocol) && url.origin === value && HOSTNAME.test(url.hostname)
+	} catch {
+		return false
+	}
+}
+
+/** The most named origins one directive may carry: the contract build and the manifest parser refuse more. */
+export const MAX_CSP_ORIGINS = 16
+
+export const NO_CSP_ORIGINS: CspOrigins = Object.freeze({
+	connectSrc: [],
+	imgSrc: [],
+	frameAncestors: [],
+	scriptSrc: [],
+	frameSrc: [],
+	styleSrc: [],
+	fontSrc: [],
+})
+
+export function cspOrigins(csp: CspExtensions): CspOrigins {
+	return {
+		connectSrc: csp.connectSrc.map((source) => source.origin),
+		imgSrc: csp.imgSrc.map((source) => source.origin),
+		frameAncestors: csp.frameAncestors.map((source) => source.origin),
+		scriptSrc: (csp.scriptSrc ?? []).map((source) => source.origin),
+		frameSrc: (csp.frameSrc ?? []).map((source) => source.origin),
+		styleSrc: (csp.styleSrc ?? []).map((source) => source.origin),
+		fontSrc: (csp.fontSrc ?? []).map((source) => source.origin),
+	}
+}
+
+/**
+ * The policy for one application: the fixed CSP, extended by the contract's named origins and by the Operations
+ * ingest origin the browser reports errors to.
+ */
+export function headerPolicy(origins: CspOrigins, operationsOrigin: string | null): HeaderPolicy {
+	const connect = ["'self'", ...(operationsOrigin === null ? [] : [operationsOrigin]), ...origins.connectSrc]
+	const frameAncestors = origins.frameAncestors.length === 0 ? ["'none'"] : origins.frameAncestors
+	const directives = [
+		"default-src 'self'",
+		`script-src ${["'self'", ...origins.scriptSrc].join(' ')}`,
+		`style-src ${["'self'", "'unsafe-inline'", ...origins.styleSrc].join(' ')}`,
+		`img-src ${["'self'", 'data:', 'blob:', ...origins.imgSrc].join(' ')}`,
+		`font-src ${["'self'", 'data:', ...origins.fontSrc].join(' ')}`,
+		`connect-src ${connect.join(' ')}`,
+		"form-action 'self'",
+		"object-src 'none'",
+		"base-uri 'none'",
+		`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(' ')}`]),
+	]
+	return Object.freeze([
+		['Content-Security-Policy', directives.join('; ')],
+		['X-Content-Type-Options', 'nosniff'],
+		['Cache-Control', 'no-store'],
+		['Referrer-Policy', 'no-referrer'],
+		['Cross-Origin-Opener-Policy', 'same-origin'],
+		['Permissions-Policy', PERMISSIONS_POLICY],
+	])
+}
+
+/** The browser-facing scheme of a manifest entry's hosts; behind a TLS-terminating balancer no header can supply it. */
+export type PublicScheme = 'http' | 'https'
+
+/** One year. No `includeSubDomains` and no `preload`: applications share parent domains. */
+export const STRICT_TRANSPORT_SECURITY = 'max-age=31536000'
+
+/**
+ * What every answer of an application host carries for its transport: HSTS on an `https` host, nothing on `http` (the
+ * local stack). Only the proxy knows the scheme, from the manifest, so the framework's in-process policy has none.
+ */
+export function transportPolicy(scheme: PublicScheme): HeaderPolicy {
+	return scheme === 'https' ? [['Strict-Transport-Security', STRICT_TRANSPORT_SECURITY]] : []
+}
+
+/**
+ * The transport headers the policy owns: an `https` entry's policy sets them, and every other answer loses the
+ * application's own, so an `http` host never pins a browser to a scheme it does not serve.
+ */
+export const TRANSPORT_HEADERS: readonly string[] = ['Strict-Transport-Security']
+
+/** The policy of a contract application's manifest entry, its transport header included. */
+export function appHeaderPolicy(app: { readonly csp: CspOrigins; readonly operationsOrigin?: string; readonly scheme: PublicScheme }): HeaderPolicy {
+	return Object.freeze([...headerPolicy(app.csp, app.operationsOrigin ?? null), ...transportPolicy(app.scheme)])
+}
+
+/** The policy of an answer that belongs to no contract application: no named origin, no ingest. */
+export const BASE_HEADER_POLICY: HeaderPolicy = headerPolicy(NO_CSP_ORIGINS, null)
+
+/** Raster formats a browser only ever renders as an image; every other download, SVG and HTML included, is an attachment. */
+export const INLINE_FILE_TYPES: readonly string[] = ['image/png', 'image/jpeg', 'image/gif', 'image/webp']
+
+/** What every answer of a download endpoint carries in place of the policy, its errors included. */
+export const FILE_TREATMENT: HeaderPolicy = Object.freeze([
+	['X-Content-Type-Options', 'nosniff'],
+	['Content-Security-Policy', "sandbox; default-src 'none'"],
+	// A revoked user must not read a cached copy.
+	['Cache-Control', 'private, no-store'],
+])
+
+/** The file treatment of a manifest entry's downloads, its transport header included. */
+export function appFileTreatment(app: { readonly scheme: PublicScheme }): HeaderPolicy {
+	return Object.freeze([...FILE_TREATMENT, ...transportPolicy(app.scheme)])
+}
+
+/**
+ * Headers an application may not send at all: each names a reporting endpoint the policy never approved, and a
+ * report-only CSP reports there whatever the enforced one says (`document-uri`, `blocked-uri`).
+ */
+export const REMOVED_RESPONSE_HEADERS: readonly string[] = ['Content-Security-Policy-Report-Only', 'Report-To', 'Reporting-Endpoints', 'NEL']
+
+/** `null` and anything but one allowlisted value is an attachment; `Headers` joins repeated fields with `, `, so two never match. */
+export function fileDisposition(contentType: string | null): 'inline' | 'attachment' {
+	return contentType !== null && INLINE_FILE_TYPES.includes(contentType) ? 'inline' : 'attachment'
+}
+
+/** Whatever the handler or an asset server set for these names is replaced; the removed and transport headers are dropped first. */
+export function applyHeaderPolicy(headers: Headers, policy: HeaderPolicy): void {
+	for (const name of [...REMOVED_RESPONSE_HEADERS, ...TRANSPORT_HEADERS]) {
+		headers.delete(name)
+	}
+	for (const [name, value] of policy) {
+		headers.set(name, value)
+	}
+}
+
+/**
+ * The file treatment over headers a download already carries: the disposition type follows the `Content-Type`
+ * exactly, and the parameters after it (the file name) are kept. The proxy passes `appFileTreatment` of its entry.
+ */
+export function applyFileTreatment(headers: Headers, treatment: HeaderPolicy = FILE_TREATMENT): void {
+	applyHeaderPolicy(headers, treatment)
+	const parameters = headers.get('Content-Disposition')?.replace(/^[^;]*/, '') ?? ''
+	headers.set('Content-Disposition', `${fileDisposition(headers.get('Content-Type'))}${parameters}`)
+}
+
+/** 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)
+	apply(headers)
+	return new Response(response.body, { status: response.status, statusText: response.statusText, headers })
+}

package/src/iam.ts

@@ -29,6 +29,10 @@ const mintResultSchema = z.discriminatedUnion('ok', [
 	z.object({ ok: z.literal(true), token: z.string().min(1), expiresAt: z.number().finite() }),
 	denialSchema,
 ])
+const delegationResultSchema = z.discriminatedUnion('ok', [
+	z.object({ ok: z.literal(true), grant: 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,
@@ -47,6 +51,22 @@ export interface IamGateway {
 	getJwks(): Promise<Jwks>
 }
 
+/**
+ * Issues the single-use delegation grant a membership or scope-creating endpoint spends (ADR-0022 rule 6). A
+ * structural subset of IAM's membership RPC, so its binding drops in like `IamGateway`'s does. `credential` is the
+ * token the proxy just minted for this request; the grant is bound to `endpoint` and `requestId`.
+ */
+export interface DelegationIssuer {
+	requestDelegation(input: DelegationRequest): Promise<{ ok: true; grant: string; expiresAt: number } | { ok: false; reason: string }>
+}
+
+export interface DelegationRequest {
+	app: string
+	credential: string
+	requestId: string
+	endpoint: string
+}
+
 /**
  * IAM could not be consulted — network failure, timeout, non-200, or a body we cannot read. Distinct
  * from a decided denial: we do not know the answer, so the request is denied with 503 rather than
@@ -89,9 +109,10 @@ 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-0022)
+ *   POST {origin}/auth/mint/delegation {app, credential, requestId, endpoint} -> a grant or a denial (rule 6)
  *   GET  {origin}/.well-known/jwks.json                         -> Jwks                     (public)
  *
- * The three POST endpoints are the `/auth/mint/*` PROXY surface, gated by IAM's `proxyKey` — the
+ * The four POST endpoints are the `/auth/mint/*` PROXY surface, authenticated by IAM's `proxyKey` — the
  * 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.
@@ -99,7 +120,7 @@ export type FetchLike = (input: string, init: RequestInit) => Promise<Response>
  * Credentials always ride in the POST body, never in a URL — a URL ends up in access logs and error
  * strings; a body does not.
  */
-export class HttpIamGateway implements IamGateway {
+export class HttpIamGateway implements IamGateway, DelegationIssuer {
 	private readonly origin: string
 	private readonly timeoutMs: number
 	private readonly key: string | undefined
@@ -121,7 +142,10 @@ export class HttpIamGateway implements IamGateway {
 		if (parsed.ok) {
 			return parsed
 		}
-		return { ok: false, reason: reasonOf(parsed.reason, ['no_session', 'invalid_session', 'unknown_principal', 'disabled'], 'invalid_session') }
+		return {
+			ok: false,
+			reason: reasonOf(parsed.reason, ['no_session', 'invalid_session', 'unknown_principal', 'disabled', 'token_too_large'], 'invalid_session'),
+		}
 	}
 
 	async mintFromKey(input: MintFromKeyInput): Promise<MintFromKeyResult> {
@@ -133,7 +157,7 @@ export class HttpIamGateway implements IamGateway {
 		if (parsed.ok) {
 			return parsed
 		}
-		return { ok: false, reason: reasonOf(parsed.reason, ['invalid_key', 'unknown_principal', 'disabled'], 'invalid_key') }
+		return { ok: false, reason: reasonOf(parsed.reason, ['invalid_key', 'unknown_principal', 'disabled', 'token_too_large'], 'invalid_key') }
 	}
 
 	async exchangeAuthCode(input: ExchangeAuthCodeInput): Promise<ExchangeAuthCodeResult> {
@@ -152,6 +176,14 @@ export class HttpIamGateway implements IamGateway {
 		}
 	}
 
+	async requestDelegation(input: DelegationRequest): Promise<{ ok: true; grant: string; expiresAt: number } | { ok: false; reason: string }> {
+		const result = delegationResultSchema.safeParse(await this.post('/auth/mint/delegation', input, 'requestDelegation'))
+		if (!result.success) {
+			throw new IamUnavailableError('requestDelegation')
+		}
+		return result.data.ok ? result.data : { ok: false, reason: result.data.reason }
+	}
+
 	async getJwks(): Promise<Jwks> {
 		const response = await this.send('/.well-known/jwks.json', undefined, 'getJwks')
 		const body: unknown = await response.json().catch(() => null)

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 the `./manifest` subpath; the gate matcher and the token claims
+// contract and its strict parser are the `./manifest` subpath; the endpoint planner and the token claims
 // are `@fabrika/auth-core`.
 
 export { Authorizer } from './authorize'
@@ -20,6 +20,8 @@ export {
 	DEFAULT_HEALTH_PATH,
 	DEFAULT_IAM_TIMEOUT_MS,
 	DEFAULT_VERIFY_PATH,
+	DELEGATION_HEADER,
+	ENDPOINT_HEADER,
 	FORWARDED_HOST_HEADER,
 	FORWARDED_METHOD_HEADER,
 	FORWARDED_PROTO_HEADER,
@@ -30,13 +32,13 @@ export {
 	REQUEST_ID_HEADER,
 	UNTRUSTED_FORWARD_HEADERS,
 } from './constants'
-export { applicableGates, compileGates, readBearer, readCookie, readServiceCredential } from './gates'
-export type { CompiledGate } from './gates'
+export { readBearer, readCookie } from './credentials'
 export { stripFabrikaCookies } from './handoff'
 export { HttpIamGateway, IamUnavailableError } from './iam'
-export type { HttpIamGatewayOptions, IamGateway } from './iam'
+export type { DelegationIssuer, DelegationRequest, HttpIamGatewayOptions, IamGateway } from './iam'
 export { consoleLogger, redactPath, redactUrl, silentLogger } from './log'
 export type { LogFields, LogValue, ProxyLogger } from './log'
+export { findOAuthMetadata, OAUTH_METADATA_VERIFY_PATH, oauthMetadataResponse } from './oauth'
 export { createVerifyService } from './service'
 export type { VerifyService, VerifyServiceConfig } from './service'
 export { TokenVerifier } from './verifier'