@fabrika/proxy-core 0.8.2 → 0.9.0-cloudflare.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/proxy-core",
-	"version": "0.8.2",
+	"version": "0.9.0-cloudflare.1",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,22 +12,33 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./manifest": {
 			"bun": "./src/manifest.ts",
-			"types": "./src/manifest.ts",
+			"types": "./types/src/manifest.d.ts",
 			"default": "./src/manifest.ts"
 		},
+		"./brand": {
+			"bun": "./src/brand.ts",
+			"types": "./types/src/brand.d.ts",
+			"default": "./src/brand.ts"
+		},
+		"./page-style": {
+			"bun": "./src/page-style.ts",
+			"types": "./types/src/page-style.d.ts",
+			"default": "./src/page-style.ts"
+		},
 		"./headers": {
 			"bun": "./src/headers.ts",
-			"types": "./src/headers.ts",
+			"types": "./types/src/headers.d.ts",
 			"default": "./src/headers.ts"
 		}
 	},
@@ -37,9 +48,9 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/auth-core": "0.8.2",
-		"@fabrika/jwks": "0.8.2",
+		"@fabrika/auth-core": "0.9.0-cloudflare.1",
+		"@fabrika/jwks": "0.9.0-cloudflare.1",
 		"jose": "^5.9.0",
-		"@fabrika/platform": "0.8.2"
+		"@fabrika/platform": "0.9.0-cloudflare.1"
 	}
 }

package/src/authorize.ts

@@ -36,9 +36,9 @@ import {
 	type TokenCaller,
 } from '@fabrika/auth-core'
 import { cacheKey, type TokenCache } from './cache'
-import { LOGIN_REDIRECT_PARAM } from './constants'
+import { LOGIN_REDIRECT_PARAM, SIGNOUT_RELEASE_PATH } from './constants'
 import { carriesPlatformKey, readBearer, readCookie } from './credentials'
-import { createHandoffAttempt, type HandoffAttempt, handoffCookieName, setHandoffParams } from './handoff'
+import { createHandoffAttempt, type HandoffAttempt, handoffCookieName, setHandoffParams, unmatchedVerifier } from './handoff'
 import { type DelegationIssuer, type IamGateway, IamUnavailableError } from './iam'
 import {
 	isApplicationEntry,
@@ -48,6 +48,7 @@ import {
 	oauthResourceOfRow,
 	type ProxyApp,
 } from './manifest'
+import { FETCH_MODE_HEADER } from './pages'
 import { TokenVerifier } from './verifier'
 
 /** Every way a request can be refused. Coarse on purpose — these are logged, not returned to clients. */
@@ -75,8 +76,10 @@ export type DenyReason =
 	| '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. */
+	/** A session request that is not a `GET`, or a sign-out, did not come from the app's own origin. */
 	| 'cross_site'
+	/** A sign-out's return is absent or not a path on the app's own origin. */
+	| 'bad_redirect'
 	/** The request's `Content-Type` is not one the endpoint admits. */
 	| 'content_type'
 	/**
@@ -111,8 +114,8 @@ export type Decision =
 		/** 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).
+		 * Whether the request's own `Authorization` reaches the application: on the ops row, and 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
 	}
@@ -143,6 +146,11 @@ export type Decision =
 	 * was going — read from the code server-side, never from the request.
 	 */
 	| { outcome: 'handoff'; status: 302; location: string; session: string; expiresAt: number; handoffState: string }
+	/**
+	 * A same-origin sign-out (ADR-0067 §5): the app session cookie is cleared and the browser goes to IAM's release,
+	 * which returns it to `location`'s own redirect on this app's origin.
+	 */
+	| { outcome: 'signout'; status: 302; location: string }
 
 /** The original request, reconstructed from what `forward_auth` forwarded. */
 export interface ForwardedRequest {
@@ -178,13 +186,6 @@ export interface AuthorizerOptions {
 	delegations?: DelegationIssuer | null
 }
 
-/**
- * The browser's own description of what issued the request. Read from the FORWARDED headers like
- * everything else a decision depends on — verified against caddy 2.10.2, whose `forward_auth`
- * subrequest carries the original `Sec-Fetch-*` verbatim.
- */
-const FETCH_MODE_HEADER = 'Sec-Fetch-Mode'
-
 /** 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'
 
@@ -583,21 +584,56 @@ export class Authorizer {
 		}
 		const cookieName = handoffCookieName(state)
 		const verifier = cookieName === null ? null : readCookie(request.headers.get('Cookie'), cookieName)
+		// Through `callIam` like every other IAM call, so an unreachable service is a 503 whatever kind
+		// of error the injected gateway happened to throw. `authorize`'s outer catch maps the rest.
+		const redeem = (presented: string) =>
+			this.callIam(
+				'exchangeAuthCode',
+				() => this.options.iam.exchangeAuthCode({ app: resolved.app.id, code, verifier: presented, requestId: request.requestId }),
+			)
 		if (verifier === null) {
+			// This browser did not start the sign-in the code belongs to. The code is spent, so whoever started it cannot
+			// redeem it from the address this browser shows (ADR-0067 §3).
+			await redeem(unmatchedVerifier())
 			return { outcome: 'deny', status: 403, reason: 'invalid_session', clearHandoffState: state }
 		}
-		// Through `callIam` like every other IAM call, so an unreachable service is a 503 whatever kind
-		// of error the injected gateway happened to throw. `authorize`'s outer catch maps the rest.
-		const result = await this.callIam(
-			'exchangeAuthCode',
-			() => this.options.iam.exchangeAuthCode({ app: resolved.app.id, code, verifier, requestId: request.requestId }),
-		)
+		const result = await redeem(verifier)
 		if (!result.ok) {
 			return { outcome: 'deny', status: 403, reason: 'invalid_session', clearHandoffState: state }
 		}
 		return { outcome: 'handoff', status: 302, location: result.returnUrl, session: result.session, expiresAt: result.expiresAt, handoffState: state }
 	}
 
+	/**
+	 * Sign the browser out of this host (ADR-0067 §5). Called for the reserved sign-out path only, BEFORE the endpoint
+	 * is planned, for any entry and any session. It drops this session's cached token, so the next request re-mints
+	 * from IAM, which has revoked the session by then or still holds it; the cookie itself is cleared by the response.
+	 *
+	 * Admission is `Sec-Fetch-Site: same-origin`, absent included: the request changes state, and another page must not
+	 * sign a person out, as for a session request that is not a `GET` (ADR-0022 rule 3, step 6).
+	 */
+	signOut(resolved: ResolvedApp, request: ForwardedRequest): Decision {
+		if (request.method !== 'GET') {
+			return { outcome: 'deny', status: 403, reason: 'no_endpoint' }
+		}
+		if (request.headers.get(FETCH_SITE_HEADER) !== 'same-origin') {
+			return { outcome: 'deny', status: 403, reason: 'cross_site' }
+		}
+		const app = resolved.app
+		const target = sameOriginTarget(new URL(`${app.scheme}://${request.url.host}`).origin, request.url.searchParams.get(LOGIN_REDIRECT_PARAM))
+		if (target === null) {
+			return { outcome: 'deny', status: 400, reason: 'bad_redirect' }
+		}
+		const session = readCookie(request.headers.get('Cookie'), SESSION_COOKIE)
+		if (session !== null) {
+			this.cache?.delete(cacheKey(app.id, 'session', session))
+		}
+		const release = new URL(SIGNOUT_RELEASE_PATH, this.options.issuer.replace(/\/+$/, ''))
+		release.searchParams.set('app', app.id)
+		release.searchParams.set(LOGIN_REDIRECT_PARAM, target)
+		return { outcome: 'signout', status: 302, location: release.toString() }
+	}
+
 	private async loginDecision(
 		app: ProxyApp,
 		request: ForwardedRequest,
@@ -647,6 +683,23 @@ function admittedOrigin(app: ProxyApp, row: ManifestEndpointRow, origin: string)
 	return form === 'environment' && isApplicationEntry(app) && (app.crossOrigins ?? []).includes(origin) ? origin : null
 }
 
+/**
+ * The absolute URL of `path` on `origin`, or `null` when `path` is not a path on that origin. A leading `//` or any
+ * `\` would make the browser read a host from it, and a control character or a space is never part of a return path.
+ */
+function sameOriginTarget(origin: string, path: string | null): string | null {
+	if (path === null || !path.startsWith('/') || path.startsWith('//') || path.includes('\\') || [...path].some(isControlOrSpace)) {
+		return null
+	}
+	const target = new URL(path, origin)
+	return target.origin === origin ? target.toString() : null
+}
+
+function isControlOrSpace(character: string): boolean {
+	const code = character.charCodeAt(0)
+	return code <= 0x20 || code === 0x7f
+}
+
 function invalidKey(): Denial {
 	return { outcome: 'deny', status: 401, reason: 'invalid_key' }
 }
@@ -738,10 +791,13 @@ function isDocumentNavigation(headers: Headers): boolean {
 }
 
 /**
- * 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.
+ * The `Authorization` of an anonymous request goes on only on a `protocol` row, whose receiver authenticates the caller
+ * itself (ADR-0069: the ops key reaches framework code only), and on a webhook row that forwards it, never with 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)
+	if (authorization === null) return false
+	if (row.kind === 'protocol') return true
+	return 'authorization' in row && row.authorization === 'forward' && !carriesPlatformKey(authorization, API_KEY_PREFIX)
 }

package/src/brand.ts

@@ -0,0 +1,121 @@
+/**
+ * The client's brand on fabrika's own pages (ADR-0066). An installation serves one client, so its logo is one setting
+ * of the installation: IAM keeps it, the console's Settings writes it, and the proxy manifest carries it to the pages the
+ * proxy answers with on every application host. A page shows it where it would otherwise draw the fabrika mark.
+ *
+ * A logo is an image a page embeds as a `data:` URI in an `<img>`, never markup: an SVG in an image runs no script, and
+ * a page that carries it loads nothing. Every consumer checks it here, the IAM write, the manifest parser and the
+ * console's own pre-check, so a logo that one of them admits passes the others. This module imports zod and nothing
+ * else, so the browser can use it.
+ */
+
+import { z } from 'zod'
+
+export const BRAND_IMAGE_TYPES = ['image/png', 'image/webp', 'image/svg+xml'] as const
+
+export type BrandImageType = (typeof BRAND_IMAGE_TYPES)[number]
+
+/** The most one image may weigh, decoded. A page carries it in every copy Caddy serves, so it stays a logo's size. */
+export const MAX_BRAND_IMAGE_BYTES = 32 * 1024
+
+/** One image of the brand: its type and its bytes as canonical base64. */
+export interface BrandImage {
+	readonly type: BrandImageType
+	readonly base64: string
+}
+
+/** The logo for a light page, and the one for a dark page when the light one would not read there. */
+export interface InstallationBrand {
+	readonly light: BrandImage
+	readonly dark?: BrandImage
+}
+
+export type BrandImageProblem = 'type' | 'encoding' | 'size' | 'content'
+
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+const MAX_BASE64_LENGTH = Math.ceil(MAX_BRAND_IMAGE_BYTES / 3) * 4
+
+/** Why an image cannot be the brand, or null. The type must be one of three and must be what the bytes are. */
+export function brandImageProblem(image: { readonly type: string; readonly base64: string }): BrandImageProblem | null {
+	if (!isBrandImageType(image.type)) return 'type'
+	if (image.base64.length === 0 || !BASE64.test(image.base64)) return 'encoding'
+	if (image.base64.length > MAX_BASE64_LENGTH) return 'size'
+	const bytes = decode(image.base64)
+	// Base64 with stray bits in its last character decodes to the same bytes; only the canonical spelling is one image.
+	if (bytes === null || brandImageBase64(bytes) !== image.base64) return 'encoding'
+	if (bytes.length > MAX_BRAND_IMAGE_BYTES) return 'size'
+	return sniff(bytes) === image.type ? null : 'content'
+}
+
+export function isBrandImageType(value: string): value is BrandImageType {
+	return BRAND_IMAGE_TYPES.some((type) => type === value)
+}
+
+export const brandImageSchema = z.object({
+	type: z.enum(BRAND_IMAGE_TYPES),
+	base64: z.string(),
+}).strict().superRefine((image, ctx) => {
+	const problem = brandImageProblem(image)
+	if (problem !== null) ctx.addIssue({ code: 'custom', message: `not a brand image: ${problem}` })
+}) satisfies z.ZodType<BrandImage, z.ZodTypeDef, unknown>
+
+export const installationBrandSchema = z.object({
+	light: brandImageSchema,
+	dark: brandImageSchema.optional(),
+}).strict() satisfies z.ZodType<InstallationBrand, z.ZodTypeDef, unknown>
+
+/** The image as the `src` of an `<img>`. Base64 holds no `{`, so a Caddy `static_response` body keeps it as it is. */
+export function brandImageDataUri(image: BrandImage): string {
+	return `data:${image.type};base64,${image.base64}`
+}
+
+/** What the bytes are, read from their start, never from what the uploader called them. */
+function sniff(bytes: Uint8Array): BrandImageType | null {
+	if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png'
+	if (startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) && startsWith(bytes.subarray(8), [0x57, 0x45, 0x42, 0x50])) return 'image/webp'
+	return isSvg(bytes) ? 'image/svg+xml' : null
+}
+
+/**
+ * UTF-8 text whose first element is `<svg`, after an optional byte order mark, an XML declaration, comments and a
+ * doctype. An image of type SVG renders inert in an `<img>`, so this only has to stop another kind of file posing as one.
+ */
+function isSvg(bytes: Uint8Array): boolean {
+	let text: string
+	try {
+		text = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+	} catch {
+		return false
+	}
+	let rest = text.replace(/^/, '')
+	for (;;) {
+		const trimmed = rest.replace(/^\s+/, '')
+		const prologue = /^(?:<\?xml[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE\s+svg[^>]*>)/i.exec(trimmed)
+		if (prologue === null) return /^<svg[\s>]/.test(trimmed)
+		rest = trimmed.slice(prologue[0].length)
+	}
+}
+
+function startsWith(bytes: Uint8Array, prefix: readonly number[]): boolean {
+	return bytes.length >= prefix.length && prefix.every((byte, index) => bytes[index] === byte)
+}
+
+function decode(base64: string): Uint8Array | null {
+	try {
+		const binary = atob(base64)
+		const bytes = new Uint8Array(binary.length)
+		for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index)
+		return bytes
+	} catch {
+		return null
+	}
+}
+
+/** Canonical base64 of `bytes`, the spelling the check requires. Chunked, so a large file stays within `fromCharCode`'s arguments. */
+export function brandImageBase64(bytes: Uint8Array): string {
+	let binary = ''
+	for (let start = 0; start < bytes.length; start += 0x8000) {
+		binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000))
+	}
+	return btoa(binary)
+}

package/src/constants.ts

@@ -49,6 +49,15 @@ export const APP_QUERY_PARAM = 'app'
  */
 export const LOGIN_REDIRECT_PARAM = 'redirect'
 
+/**
+ * Reserved on every app host beside the handoff callback, and answered before endpoint selection: it clears the app
+ * session and sends the browser to IAM's release (ADR-0067 §5). It takes the return path in `LOGIN_REDIRECT_PARAM`.
+ */
+export const AUTH_SIGNOUT_PATH = '/__fabrika/auth/signout'
+
+/** IAM's path that revokes the browser's terminal sessions and returns it to the application (ADR-0067 §5). */
+export const SIGNOUT_RELEASE_PATH = '/auth/terminals/release'
+
 /** The JWKS cache TTL and the unknown-`kid` refetch cooldown, owned by the verifier both planes share. */
 export { JWKS_REFETCH_COOLDOWN_SECONDS, JWKS_TTL_SECONDS } from '@fabrika/jwks'
 

package/src/handoff.ts

@@ -15,6 +15,14 @@ export async function createHandoffAttempt(): Promise<HandoffAttempt> {
 	return { state, verifier, challenge: await handoffChallenge(verifier) }
 }
 
+/**
+ * A verifier made for no challenge. IAM consumes a code before it compares the verifier, so redeeming a code with this
+ * one only spends the code.
+ */
+export function unmatchedVerifier(): string {
+	return randomToken(32)
+}
+
 /** S256, matching PKCE: the verifier never rides in a URL or reaches IAM through the browser. */
 export async function handoffChallenge(verifier: string): Promise<string> {
 	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))

package/src/index.ts

@@ -16,6 +16,7 @@ export { cacheKey, MemoryTokenCache } from './cache'
 export type { CachedToken, TokenCache } from './cache'
 export {
 	APP_QUERY_PARAM,
+	AUTH_SIGNOUT_PATH,
 	CLIENT_ADDRESS_HEADER,
 	DEFAULT_HEALTH_PATH,
 	DEFAULT_IAM_TIMEOUT_MS,
@@ -32,6 +33,7 @@ export {
 	PREFLIGHT_HEADER,
 	PROXY_TOKEN_HEADER,
 	REQUEST_ID_HEADER,
+	SIGNOUT_RELEASE_PATH,
 	UNTRUSTED_FORWARD_HEADERS,
 } from './constants'
 export { carriesPlatformKey, readBearer, readCookie } from './credentials'
@@ -41,6 +43,8 @@ export type { DelegationIssuer, DelegationRequest, HttpIamGatewayOptions, IamGat
 export { consoleLogger, redactPath, redactUrl, silentLogger } from './log'
 export type { LogFields, LogValue, ProxyLogger } from './log'
 export { findOAuthMetadata, OAUTH_METADATA_VERIFY_PATH, oauthMetadataResponse } from './oauth'
+export { errorAnswer, errorPage, FETCH_MODE_HEADER, isPageNavigation, PAGE_CONTENT_TYPE, pageResponse, renderPage } from './pages'
+export type { ErrorPageStatus, PageAction, PageContent } from './pages'
 export { createVerifyService } from './service'
 export type { VerifyService, VerifyServiceConfig } from './service'
 export { TokenVerifier } from './verifier'

package/src/manifest.ts

@@ -1,6 +1,7 @@
 import {
 	ANY_ORIGIN_KINDS,
 	APP_ENVIRONMENT_SEPARATOR,
+	type BodyAdmission,
 	type Caller,
 	compileEndpointTable,
 	type ContractArtifact,
@@ -17,10 +18,16 @@ import {
 	type InstallationEndpointTable,
 	isDigest,
 	MAX_CACHE_AGE_SECONDS,
+	OPS_CONTENT_TYPE,
+	OPS_METHOD,
+	OPS_PREFIX,
+	OPS_ROW_ID,
+	OPS_ROW_PATH,
 	parseAppEnvironmentId,
 	requirementDigest,
 } from '@fabrika/auth-core'
 import { z } from 'zod'
+import { type InstallationBrand, installationBrandSchema } from './brand'
 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'
 
@@ -93,8 +100,8 @@ interface ProxyEndpointExtras {
 	delegation: EndpointDelegation | null
 }
 
-/** An endpoint row as the proxy applies it: the rules without the schemas, plus the digest and the delegation. */
-export type ProxyEndpointRow =
+/** A row a contract declares, as the proxy applies it: the rules without the schemas, plus the digest and the delegation. */
+export type DeclaredProxyEndpointRow =
 	| (
 		& Pick<CredentialedEndpoint, 'id' | 'kind' | 'method' | 'path' | 'callers' | 'requirement' | 'admission' | 'crossOrigin' | 'response'>
 		& ProxyEndpointExtras
@@ -110,6 +117,42 @@ export type ProxyEndpointRow =
 		}
 	)
 
+/** An endpoint row of an application table: a declared row, or the ops row that only platform composition adds. */
+export type ProxyEndpointRow = DeclaredProxyEndpointRow | OpsProxyEndpointRow
+
+/**
+ * The canonical ops row (ADR-0069): Control's channel to an environment's object, which platform composition adds to an
+ * application's table for a framework release that serves it. The parser admits only `opsProxyRow()`, field for field.
+ */
+export interface OpsProxyEndpointRow {
+	id: string
+	kind: 'protocol'
+	method: typeof OPS_METHOD
+	path: string
+	callers: []
+	requirement: null
+	admission: BodyAdmission
+	delegation: null
+	digest: string
+}
+
+/** The ops row's body limit: every ops request is a small JSON object. */
+export const OPS_ROW_MAX_BYTES = 64 * 1024
+
+/** The ops row, digested like every row; the provider composes it and the framework checks `X-Fabrika-Endpoint` against it. */
+export function opsProxyRow(): OpsProxyEndpointRow {
+	const rules = {
+		kind: 'protocol',
+		method: OPS_METHOD,
+		path: OPS_ROW_PATH,
+		callers: [],
+		requirement: null,
+		admission: { contentTypes: [OPS_CONTENT_TYPE], maxBytes: OPS_ROW_MAX_BYTES },
+		delegation: null,
+	} satisfies Omit<OpsProxyEndpointRow, 'id' | 'digest'>
+	return { id: OPS_ROW_ID, ...rules, digest: requirementDigest({ ...rules, oauth: null }) }
+}
+
 /** An installation row as the proxy applies it: the row with its digest and no delegation. */
 export type InstallationProxyEndpointRow = InstallationEndpointRow & { digest: string; delegation: null }
 
@@ -118,6 +161,11 @@ export type ManifestEndpointRow = ProxyEndpointRow | InstallationProxyEndpointRo
 
 export interface ProxyManifest {
 	apps: ProxyApp[]
+	/**
+	 * The installation's client logo for the pages the proxy answers with (ADR-0066). Absent, a page draws the fabrika
+	 * mark. A producer sends it only to a proxy whose source parses it: an older parser refuses the key.
+	 */
+	brand?: InstallationBrand
 }
 
 const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/
@@ -190,7 +238,10 @@ const endpointRuleFields = {
 	admission: admissionSchema.nullable(),
 	digest: z.string().refine(isDigest),
 }
-/** One row of a contract app's endpoint table; it refuses a digest that does not describe the row's rules. */
+/**
+ * One row a contract declares, of a contract app's endpoint table; it refuses a digest that does not describe the row's
+ * rules. It never admits the ops row, which only `contractProxyAppSchema` reads.
+ */
 export const proxyEndpointRowSchema = z.union([
 	z.object({
 		...endpointRuleFields,
@@ -238,13 +289,28 @@ export const proxyEndpointRowSchema = z.union([
 	(row) => row.digest === requirementDigest(row),
 	'endpoint digest does not match its rules',
 ) satisfies z.ZodType<
-	ProxyEndpointRow,
+	DeclaredProxyEndpointRow,
 	z.ZodTypeDef,
 	unknown
 >
 
+const OPS_ROW = opsProxyRow()
+
+/** The ops row exactly as `opsProxyRow()` builds it: every field a literal, its digest included. */
+const opsProxyEndpointRowSchema = z.object({
+	id: z.literal(OPS_ROW_ID),
+	kind: z.literal('protocol'),
+	method: z.literal(OPS_METHOD),
+	path: z.literal(OPS_ROW_PATH),
+	callers: z.tuple([]),
+	requirement: z.null(),
+	admission: z.object({ contentTypes: z.tuple([z.literal(OPS_CONTENT_TYPE)]), maxBytes: z.literal(OPS_ROW_MAX_BYTES) }).strict(),
+	delegation: z.null(),
+	digest: z.literal(OPS_ROW.digest),
+}).strict() satisfies z.ZodType<OpsProxyEndpointRow, z.ZodTypeDef, unknown>
+
 /** 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 {
+function crossOriginAllowed(kind: DeclaredProxyEndpointRow['kind'], form: CrossOriginForm | undefined): boolean {
 	return form === undefined || (CROSS_ORIGIN_KINDS.includes(kind) && (form !== 'any' || ANY_ORIGIN_KINDS.includes(kind)))
 }
 
@@ -276,7 +342,7 @@ const cspOriginsSchema = z.object({
 export const contractProxyAppSchema = z.object({
 	...proxyAppFields,
 	scheme: proxyAppScheme,
-	endpoints: z.array(proxyEndpointRowSchema),
+	endpoints: z.array(z.union([proxyEndpointRowSchema, opsProxyEndpointRowSchema])),
 	reservedPrefixes: z.array(z.string()),
 	snapshot: z.string().refine(isDigest),
 	csp: cspOriginsSchema,
@@ -284,6 +350,10 @@ export const contractProxyAppSchema = z.object({
 	crossOrigins: z.array(z.string().refine(isCrossOrigin)).nonempty().max(MAX_CROSS_ORIGINS).optional(),
 }).strict().superRefine((app, ctx) => {
 	checkCrossOrigins(app, ctx)
+	// Only the ops row lies under the ops prefix: another row there would be an application route at a platform path.
+	if (app.endpoints.some((row) => row.path.startsWith(OPS_PREFIX) && row.kind !== 'protocol')) {
+		ctx.addIssue({ code: 'custom', message: 'only the ops row serves the ops prefix' })
+	}
 	checkEndpointTable(app, ctx)
 }) satisfies z.ZodType<ContractProxyApp, z.ZodTypeDef, unknown>
 
@@ -374,9 +444,14 @@ 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).
+ * older release's (ADR-0062). `ops` adds the ops row, which only platform composition asks for and the artifact never
+ * carries.
  */
-export function contractProxyTable(artifact: ContractArtifact, digest: string = contractDigest(artifact)): ContractProxyTable {
+export function contractProxyTable(
+	artifact: ContractArtifact,
+	digest: string = contractDigest(artifact),
+	options: { readonly ops?: boolean } = {},
+): ContractProxyTable {
 	return {
 		endpoints: artifact.endpoints.map((row): ProxyEndpointRow => {
 			const rules = {
@@ -401,13 +476,68 @@ export function contractProxyTable(artifact: ContractArtifact, digest: string =
 				delegation: endpointDelegation(artifact, row),
 			}
 			return { ...credentialed, digest: requirementDigest(credentialed) }
-		}),
+		}).concat(options.ops === true ? [opsProxyRow()] : []),
 		reservedPrefixes: [...artifact.reservedPrefixes],
 		snapshot: digest,
 		csp: cspOrigins(artifact.csp),
 	}
 }
 
+/** Where and how a producer serves one contract application. */
+export interface ContractEntryPlacement {
+	readonly id: string
+	readonly hosts: readonly string[]
+	readonly upstream: string
+	readonly scheme: 'http' | 'https'
+	/** The approved contract's table, from `contractProxyTable`. */
+	readonly table: ContractProxyTable
+	readonly operationsOrigin?: string
+	/** The environment's list from Control's registry; an empty one is omitted. */
+	readonly crossOrigins?: readonly string[]
+}
+
+/**
+ * What the proxy of one older platform release parses of an application's manifest entry: a row, and the entry's CSP
+ * directives, each by that release's own parser (ADR-0062); and whether it serves the sign-out (ADR-0067 §5).
+ */
+export interface OlderProxyReader {
+	readonly row: (row: ProxyEndpointRow) => boolean
+	readonly csp: (csp: CspOrigins) => boolean
+	readonly signsOut: boolean
+}
+
+/**
+ * The proxies of the older releases a pin may run whose parsers Control holds. A pin's release is not recorded, so what
+ * any of them reads is what the pin may read.
+ */
+export type OlderProxyReaders = readonly [OlderProxyReader, ...OlderProxyReader[]]
+
+/**
+ * A contract application's manifest entry: the one form every producer builds. Refused when the proxy's own parser
+ * would refuse it, naming the fields and never their values, because an origin with userinfo may carry a key.
+ */
+export function contractProxyEntry(placement: ContractEntryPlacement): ContractProxyApp {
+	const { table, operationsOrigin, crossOrigins = [] } = placement
+	const entry: ContractProxyApp = {
+		id: placement.id,
+		hosts: [...placement.hosts],
+		upstream: placement.upstream,
+		scheme: placement.scheme,
+		endpoints: table.endpoints,
+		reservedPrefixes: table.reservedPrefixes,
+		snapshot: table.snapshot,
+		csp: table.csp,
+		...(operationsOrigin === undefined ? {} : { operationsOrigin }),
+		...(crossOrigins.length === 0 ? {} : { crossOrigins: [...crossOrigins] }),
+	}
+	const parsed = contractProxyAppSchema.safeParse(entry)
+	if (!parsed.success) {
+		const fields = new Set(parsed.error.issues.map((issue) => issue.path.length === 0 ? issue.message : issue.path.join('.')))
+		throw new Error(`proxy entry \`${placement.id}\` is one the proxy manifest refuses (${[...fields].join('; ')})`)
+	}
+	return entry
+}
+
 /** What a producer adds to an installation service's placement: the output of `serviceProxyTable`. */
 export type InstallationProxyTable = Pick<InstallationProxyApp, 'installation' | 'endpoints' | 'reservedPrefixes'>
 
@@ -441,6 +571,7 @@ export function findDuplicateProxyHost(apps: readonly Pick<ProxyApp, 'hosts'>[])
 
 export const proxyManifestSchema = z.object({
 	apps: z.array(proxyAppSchema),
+	brand: installationBrandSchema.optional(),
 }).strict().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' })