@fabrika/app 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.5.1",
+	"version": "0.5.3",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -93,14 +93,14 @@
 		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "0.5.1",
-		"@fabrika/auth-core": "0.5.1",
-		"@fabrika/db": "0.5.1",
-		"@fabrika/email": "0.5.1",
-		"@fabrika/jwks": "0.5.1",
-		"@fabrika/platform": "0.5.1",
-		"@fabrika/platform-node": "0.5.1",
-		"@fabrika/proxy-core": "0.5.1",
+		"@fabrika/auth": "0.5.3",
+		"@fabrika/auth-core": "0.5.3",
+		"@fabrika/db": "0.5.3",
+		"@fabrika/email": "0.5.3",
+		"@fabrika/jwks": "0.5.3",
+		"@fabrika/platform": "0.5.3",
+		"@fabrika/platform-node": "0.5.3",
+		"@fabrika/proxy-core": "0.5.3",
 		"jose": "^5.9.0"
 	},
 	"peerDependencies": {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.5.1
+version: 0.5.3
 description: >
   How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
   slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors

package/skill/references/app-setup.md

@@ -19,20 +19,20 @@ the SPA is added with it.
 		"test": "bun test --isolate"
 	},
 	"dependencies": {
-		"@fabrika/app": "0.5.1",
-		"@fabrika/db": "0.5.1",
-		"@fabrika/provider-zerops": "0.5.1",
-		"@fabrika/proxy-core": "0.5.1",
-		"@fabrika/ui": "0.5.1",
+		"@fabrika/app": "0.5.3",
+		"@fabrika/db": "0.5.3",
+		"@fabrika/provider-zerops": "0.5.3",
+		"@fabrika/proxy-core": "0.5.3",
+		"@fabrika/ui": "0.5.3",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "0.5.1",
-		"@fabrika/cli": "0.5.1",
-		"@fabrika/platform": "0.5.1",
+		"@fabrika/check": "0.5.3",
+		"@fabrika/cli": "0.5.3",
+		"@fabrika/platform": "0.5.3",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",

package/skill/references/endpoint.md

@@ -522,6 +522,22 @@ the invocation's transaction. `'write'` (a mutation, a job, a webhook) also inse
 then names the chain columns itself. Use it for an operator's cross-scope view, never to dodge a capability the caller
 should hold. The generated tests skip the other-scope leak case for such an endpoint.
 
+## Another origin: `crossOrigin`
+
+A page on another site (a partner's page, a separate marketing site, another application in the browser) calls an RPC
+endpoint only when the endpoint says `crossOrigin: true` beside its `access`, and an operator lists that page's origin
+for the environment in Control (`--cross-origin=https://partner.example` on `fabrika control apps environments put`). Both halves are
+needed: the contract says which endpoints, the environment says from where, so staging and production can list
+different pages. The approver sees the flag like any other access change.
+
+- **A key, never a session.** The page sends `Authorization: Bearer px_…` (a machine key, or a person's own key). A
+  person's session is never read for a request from a listed origin: the answer is 401 without a login bounce.
+- **The proxy answers CORS, the handler never does.** The proxy answers the preflight and sets
+  `Access-Control-Allow-Origin` on the answer; it deletes every `Access-Control-*` header a handler sets.
+- **Only RPC procedures.** A link procedure, an export, an SPA, a download and an upload refuse `crossOrigin`. A form
+  takes it too (`references/public-intake.md`).
+- **Test it** with `testKit(app, { crossOrigins: ['https://partner.example'] })` and a request carrying that `Origin`.
+
 ## Members
 
 `ctx.members` of an endpoint `on` or `in` a dimension reads the members of the nearest dimension, its own or one

package/skill/references/public-intake.md

@@ -405,6 +405,10 @@ export const contract = app.contract((c) => ({
   `<prefix>/__fabrika-config.json` as `public: { <VARIABLE>: <value> }`, and the approver sees each name. Never name
   a secret there: the contract refuses a variable that is both.
   `rate: { perClient, perForm }` (per minute, 10 and 100 by default) answers 429 past either limit.
+- **A form on someone else's page.** A form served from this application's own SPA needs nothing. A form a partner's
+  page or a separate marketing site submits needs `crossOrigin`: `true` for the origins an operator lists for the
+  environment in Control, `'*'` for any site (an embeddable widget). The proxy answers the browser's preflight and
+  the page can read the constant answer. Keep the honeypot, the challenge and the rate limit: `'*'` invites every site.
 - **Zerops shares one client address.** Until the platform reads the visitor's address behind the Zerops balancer,
   every visitor counts as one client there, so `perClient` acts as a second per-form limit: set it to the form's
   expected peak, never lower it to stop a flood. The challenge is the defense that does not depend on the address.

package/src/contract/artifact-schema.ts

@@ -2,10 +2,12 @@
 // object is strict and every field required, so a value that is not exactly an artifact is refused, not coerced.
 
 import {
+	ANY_ORIGIN_KINDS,
 	type ArrayShape,
 	type AttachmentShape,
 	BUILTIN_ROLE_KEYS,
 	type ContractArtifact,
+	CROSS_ORIGIN_KINDS,
 	displayNameProblem,
 	type EndpointRow,
 	JOB_MAILERS,
@@ -134,12 +136,14 @@ const endpointRow: z.ZodType<EndpointRow> = z.union([
 		kind: z.enum(['query', 'mutation', 'spa', 'upload', 'download']),
 		callers: z.tuple([caller], caller),
 		requirement,
+		crossOrigin: z.literal('environment').optional(),
 	}),
 	z.strictObject({
 		...rowBase,
 		kind: z.enum(['health', 'form', 'webhook', 'link-spa']),
 		callers: z.tuple([]),
 		requirement: z.null(),
+		crossOrigin: z.enum(['environment', 'any']).optional(),
 	}),
 	// A public SPA is a fixed static row: GET only, no body, no schemas.
 	z.strictObject({
@@ -152,7 +156,13 @@ const endpointRow: z.ZodType<EndpointRow> = z.union([
 		callers: z.tuple([]),
 		requirement: z.null(),
 	}),
-])
+]).refine(
+	// Only an RPC procedure and a form open to another origin, and only a form to any (ADR-0022).
+	(row) =>
+		!('crossOrigin' in row) || row.crossOrigin === undefined
+		|| (CROSS_ORIGIN_KINDS.includes(row.kind) && (row.crossOrigin !== 'any' || ANY_ORIGIN_KINDS.includes(row.kind))),
+	'this endpoint kind cannot be called cross-origin',
+)
 
 const scopeBinding = z.discriminatedUnion('kind', [
 	z.strictObject({ kind: z.literal('app') }),

package/src/contract/build.ts

@@ -11,6 +11,7 @@ import {
 	canonicalizeArtifact,
 	type ChallengeProvider,
 	type ContractArtifact,
+	type CrossOriginForm,
 	type CspExtensions,
 	type CspSource,
 	type DeclaredReach,
@@ -527,7 +528,15 @@ class ArtifactBuilder {
 				this.#prefix(where, mount.path)
 				this.#objectSchema(`${where} input`, mount.input)
 				this.#nonEmpty(`${where} appendTo`, mount.appendTo)
-				this.#anonymous(name, 'form', 'POST', mount.path, this.#bodyLimit(where, mount.maxBytes, CONTRACT_DEFAULTS.formMaxBytes), mount.input)
+				this.#anonymous(
+					name,
+					'form',
+					'POST',
+					mount.path,
+					this.#bodyLimit(where, mount.maxBytes, CONTRACT_DEFAULTS.formMaxBytes),
+					mount.input,
+					this.#crossOrigin(where, mount.crossOrigin, true),
+				)
 				return {
 					kind: 'form',
 					path: mount.path,
@@ -739,6 +748,7 @@ class ArtifactBuilder {
 			const id = `${name}.${path}`
 			const requirement = this.#linkRequirement(`procedure '${id}'`, procedure.access, mount)
 			this.#procedureSchemas(`procedure '${id}'`, procedure)
+			this.#noCrossOrigin(`procedure '${id}'`, procedure.crossOrigin, 'a link holder')
 			this.#declare(`procedure '${id}'`, id, procedure.declared, { kind: 'link', readOnly: procedure.type === 'query' })
 			if (requirement !== null) {
 				this.#row({
@@ -776,6 +786,9 @@ class ArtifactBuilder {
 		const where = `procedure '${id}'`
 		this.#procedureSchemas(where, procedure)
 		const requirement = this.#requirement(where, procedure)
+		const crossOrigin = source.kind === 'mount'
+			? this.#crossOrigin(where, procedure.crossOrigin, false)
+			: this.#noCrossOrigin(where, procedure.crossOrigin, 'a consuming application, from its server')
 		if (requirement !== null) {
 			this.#row({
 				id,
@@ -788,10 +801,38 @@ class ArtifactBuilder {
 				admission: JSON_ADMISSION,
 				input: procedure.input,
 				output: this.#output(where, procedure),
+				...crossOrigin,
 			})
 		}
 	}
 
+	/**
+	 * A procedure's or a form's `crossOrigin` (ADR-0022 "Cross-origin endpoints"): `true` admits the origins the
+	 * environment lists, `'*'` (a form only, `any`) every origin. Absent stays absent, so the row keeps its digest.
+	 */
+	#crossOrigin(where: string, value: unknown, anyOrigin: boolean): { readonly crossOrigin?: CrossOriginForm } {
+		if (value === undefined) {
+			return {}
+		}
+		if (value === true) {
+			return { crossOrigin: 'environment' }
+		}
+		if (anyOrigin && value === '*') {
+			return { crossOrigin: 'any' }
+		}
+		const allowed = anyOrigin ? "crossOrigin: true for the environment's listed origins, or crossOrigin: '*' for any" : 'crossOrigin: true'
+		this.#problem(where, `crossOrigin ${JSON.stringify(value)} is not a cross-origin form (allowed: ${allowed})`)
+		return {}
+	}
+
+	/** A procedure no page on another origin may call: `caller` is who calls it instead. */
+	#noCrossOrigin(where: string, value: unknown, caller: string): { readonly crossOrigin?: CrossOriginForm } {
+		if (value !== undefined) {
+			this.#problem(where, `is called by ${caller}, never cross-origin (only an RPC procedure of c.rpc and a form take crossOrigin)`)
+		}
+		return {}
+	}
+
 	/**
 	 * A procedure's answer: its output schema, or for an `attachment()` the file it encodes from the rows. A column is a
 	 * scalar cell, the name is fixed and safe in a header, and each limit is within `ATTACHMENT_LIMITS`.
@@ -854,8 +895,21 @@ class ArtifactBuilder {
 		path: string,
 		admission: BodyAdmission | null,
 		input: SchemaShape | null,
+		crossOrigin: { readonly crossOrigin?: CrossOriginForm } = {},
 	): void {
-		this.#row({ id: name, source: { kind: 'mount', name }, kind, method, path, callers: [], requirement: null, admission, input, output: null })
+		this.#row({
+			id: name,
+			source: { kind: 'mount', name },
+			kind,
+			method,
+			path,
+			callers: [],
+			requirement: null,
+			admission,
+			input,
+			output: null,
+			...crossOrigin,
+		})
 	}
 
 	#row(row: EndpointRow): void {

package/src/contract/declaration.ts

@@ -47,11 +47,11 @@ export interface BuilderFields {
 }
 
 export const BUILDER_FIELDS: Readonly<Record<Builder, BuilderFields>> = {
-	procedure: { options: ['input', 'output', 'access'], owned: ['~kind', 'type'] },
+	procedure: { options: ['input', 'output', 'access', 'crossOrigin'], owned: ['~kind', 'type'] },
 	rpc: { options: ['callers'], owned: ['kind', 'prefix', 'procedures'] },
 	link: { options: ['spa', 'dimension', 'grants', 'issuedBy', 'maxDays', 'procedures'], owned: ['kind', 'prefix'] },
 	spa: { options: ['dir', 'access', 'public'], owned: ['kind', 'prefix'] },
-	form: { options: ['input', 'appendTo', 'maxBytes', 'rate', 'honeypot', 'challenge', 'then'], owned: ['kind', 'path'] },
+	form: { options: ['input', 'appendTo', 'maxBytes', 'rate', 'honeypot', 'challenge', 'then', 'crossOrigin'], owned: ['kind', 'path'] },
 	webhook: { options: ['scheme', 'boundTo', 'actions', 'input', 'maxBytes'], owned: ['kind', 'path'] },
 	files: { options: ['owner', 'read', 'write', 'delete', 'maxBytes', 'types', 'maxPerOwner', 'link', 'scan'], owned: ['kind'] },
 	cron: { options: ['actions', 'scope', 'timeout', 'retries'], owned: ['kind', 'schedule'] },
@@ -155,6 +155,8 @@ export interface ProcedureDeclaration<S, Access = AccessDeclaration> extends Opt
 	readonly input: S | null
 	readonly output: S
 	readonly access: Access
+	/** `true` opens the procedure to the environment's listed origins, as written; `buildArtifact` refuses anything else. */
+	readonly crossOrigin?: unknown
 	/** What a procedure of the staged kit declares off the paved road; a `defineContract` procedure has none. */
 	readonly declared?: unknown
 	/**
@@ -237,6 +239,8 @@ export interface FormMountDeclaration<S> extends OptionsRecord {
 	readonly challenge?: { readonly provider: ChallengeProvider; readonly secret: string; readonly siteKey?: string }
 	/** The cron job of the contract that each accepted submission kicks. */
 	readonly then?: string
+	/** `true` (the environment's listed origins) or `'*'` (any origin), as written; `buildArtifact` refuses anything else. */
+	readonly crossOrigin?: unknown
 }
 
 export interface WebhookMountDeclaration<S> extends OptionsRecord {

package/src/contract/define.ts

@@ -220,6 +220,8 @@ export interface ProcedureDef<I, O, Acc> extends Owned<'~kind' | 'type'> {
 	readonly input?: I & NotLoose<I>
 	readonly output: O & NotLoose<O>
 	readonly access: Acc
+	/** A page on one of the environment's listed origins may call it, with a key (ADR-0022). An RPC procedure only. */
+	readonly crossOrigin?: true
 }
 
 export interface RpcMount<C extends readonly [RpcCaller, ...RpcCaller[]], T extends ProcedureTree> extends RpcMountDeclaration<Schema> {
@@ -322,6 +324,8 @@ export type FormOptions<I, T> =
 		readonly challenge?: FormChallengeOption
 		/** The cron job each accepted submission kicks, in the background of the constant answer. */
 		readonly then?: T
+		/** A page on another origin may submit it: `true` from the environment's listed origins, `'*'` from any. */
+		readonly crossOrigin?: true | '*'
 	}
 	& Owned<'kind' | 'path'>
 
@@ -435,6 +439,7 @@ function procedure<T extends ProcedureType, I extends InputSchema | null, O exte
 		input: def.input ?? null,
 		output: def.output,
 		access: def.access,
+		...(def.crossOrigin === undefined ? {} : { crossOrigin: def.crossOrigin }),
 		unknownOptions: unknownOptions(def, 'procedure'),
 	}
 }
@@ -488,6 +493,7 @@ export function surfaceKit<A extends string, D extends string, CD extends string
 			honeypot: options.honeypot,
 			challenge: options.challenge,
 			then: options.then,
+			...(options.crossOrigin === undefined ? {} : { crossOrigin: options.crossOrigin }),
 			unknownOptions: unknownOptions(options, 'form'),
 		}),
 		webhook: (path, options) => ({

package/src/contract/group.ts

@@ -80,6 +80,8 @@ export type EndpointDef<I, O, Acc, S, U, Cn, Is, Ix extends AnyDbIndex> =
 		readonly input?: I & NotLoose<I>
 		readonly output: O & NotLoose<O>
 		readonly access: Acc
+		/** A page on one of the environment's listed origins may call it, with a key (ADR-0022). An RPC endpoint only. */
+		readonly crossOrigin?: true
 	}
 	& DeclaredFields<S, U, Cn, Is, Ix>
 

package/src/contract/kit.ts

@@ -336,6 +336,7 @@ interface EndpointOptions<Access> extends DeclaredDeclaration {
 	readonly input?: Schema | null
 	readonly output: Schema
 	readonly access: Access
+	readonly crossOrigin?: true
 }
 
 function endpoint<Access>(type: ProcedureType, def: EndpointOptions<Access>): PendingSite<ProcedureDeclaration<Schema, Access>> {
@@ -345,6 +346,7 @@ function endpoint<Access>(type: ProcedureType, def: EndpointOptions<Access>): Pe
 		input: def.input ?? null,
 		output: def.output,
 		access: def.access,
+		...(def.crossOrigin === undefined ? {} : { crossOrigin: def.crossOrigin }),
 		declared: declaredOf(def),
 		unknownOptions: kitUnknownOptions(def, 'procedure'),
 	}

package/src/testing/kit.ts

@@ -115,6 +115,11 @@ export interface TestKitOptions {
 	 * `mail_not_configured`.
 	 */
 	readonly mail?: MemoryEmailSender | 'none'
+	/**
+	 * The origins the environment lists for the contract's `crossOrigin` endpoints, as an operator sets them in
+	 * Control; a page on one of them may call such an endpoint with a key. None when omitted.
+	 */
+	readonly crossOrigins?: readonly string[]
 }
 
 export interface TestConnection {
@@ -515,7 +520,15 @@ export function bootTestKit<C extends AnyContract>(
 		getJwks: () => jwks,
 	}
 
-	const proxy = endpointProxy({ artifact, appId, host, iam, issuer: TEST_ISSUER, delegations: membership ?? null })
+	const proxy = endpointProxy({
+		artifact,
+		appId,
+		host,
+		iam,
+		issuer: TEST_ISSUER,
+		delegations: membership ?? null,
+		...(options.crossOrigins === undefined ? {} : { crossOrigins: options.crossOrigins }),
+	})
 
 	// What requests leave running: a job a form's or a mutation's `then` kicked, or a failure's report.
 	const background = new Set<Promise<void>>()
@@ -546,7 +559,10 @@ export function bootTestKit<C extends AnyContract>(
 		for (const [header, value] of outcome.asserted) {
 			headers.set(header, value)
 		}
-		return application.fetch(new Request(request, { headers }), exec)
+		const answer = await application.fetch(new Request(request, { headers }), exec)
+		const decorated = new Headers(answer.headers)
+		outcome.decorate(decorated)
+		return new Response(answer.body, { status: answer.status, statusText: answer.statusText, headers: decorated })
 	}
 
 	function browser(caller?: TestCaller): RpcFetch {

package/src/testing/proxy.ts

@@ -12,10 +12,12 @@ import {
 	FORWARDED_PROTO_HEADER,
 	FORWARDED_URI_HEADER,
 	type IamGateway,
+	PREFLIGHT_HEADER,
 	PROXY_TOKEN_HEADER,
 	REQUEST_ID_HEADER,
 	type TokenCache,
 } from '@fabrika/proxy-core'
+import { applyCrossOriginHeaders, crossOriginHeaders } from '@fabrika/proxy-core/headers'
 import { contractProxyTable } from '@fabrika/proxy-core/manifest'
 
 /** What the proxy did with a request: answered it itself, or forwarded it with what only the proxy may set. */
@@ -26,6 +28,8 @@ export type ProxyOutcome =
 		readonly asserted: ReadonlyMap<string, string>
 		/** Whether the request's own `Authorization` reaches the application: not on an anonymous endpoint. */
 		readonly keepsAuthorization: boolean
+		/** What the application's answer is given for an admitted cross-origin request, over its own headers. */
+		readonly decorate: (headers: Headers) => void
 	}
 	| { readonly outcome: 'answer'; readonly response: Response }
 
@@ -48,6 +52,8 @@ export interface EndpointProxyOptions {
 	readonly delegations: DelegationIssuer | null
 	/** The proxy's token cache, as production keeps one; omitted, every request mints. */
 	readonly cache?: TokenCache
+	/** The origins the environment lists for the contract's cross-origin endpoints; none when omitted. */
+	readonly crossOrigins?: readonly string[]
 }
 
 const ASSERTED_HEADERS = [PROXY_TOKEN_HEADER, REQUEST_ID_HEADER, ENDPOINT_HEADER, DELEGATION_HEADER]
@@ -56,7 +62,14 @@ const ASSERTED_HEADERS = [PROXY_TOKEN_HEADER, REQUEST_ID_HEADER, ENDPOINT_HEADER
 export function endpointProxy(options: EndpointProxyOptions): TestProxy {
 	const verify = createVerifyService({
 		manifest: {
-			apps: [{ id: options.appId, hosts: [options.host], upstream: 'app', scheme: 'https', ...contractProxyTable(options.artifact) }],
+			apps: [{
+				id: options.appId,
+				hosts: [options.host],
+				upstream: 'app',
+				scheme: 'https',
+				...contractProxyTable(options.artifact),
+				...(options.crossOrigins === undefined || options.crossOrigins.length === 0 ? {} : { crossOrigins: [...options.crossOrigins] }),
+			}],
 		},
 		iam: options.iam,
 		issuer: options.issuer,
@@ -75,6 +88,12 @@ export function endpointProxy(options: EndpointProxyOptions): TestProxy {
 		if (!verification.ok) {
 			return { outcome: 'answer', response: verification }
 		}
+		// An admitted preflight: the decision's 2xx is the whole answer, as both enforcement points return it.
+		if (verification.headers.get(PREFLIGHT_HEADER) === '1') {
+			verification.headers.delete(PREFLIGHT_HEADER)
+			return { outcome: 'answer', response: verification }
+		}
+		const allowOrigin = verification.headers.get('Access-Control-Allow-Origin')
 		const asserted = new Map<string, string>()
 		for (const header of ASSERTED_HEADERS) {
 			const value = verification.headers.get(header)
@@ -82,6 +101,13 @@ export function endpointProxy(options: EndpointProxyOptions): TestProxy {
 				asserted.set(header, value)
 			}
 		}
-		return { outcome: 'forward', asserted, keepsAuthorization: asserted.has(PROXY_TOKEN_HEADER) }
+		return {
+			outcome: 'forward',
+			asserted,
+			keepsAuthorization: asserted.has(PROXY_TOKEN_HEADER),
+			decorate: (answer) => {
+				if (allowOrigin !== null) applyCrossOriginHeaders(answer, crossOriginHeaders(allowOrigin))
+			},
+		}
 	}
 }