@fabrika/app 0.5.5 → 0.7.0

package/src/implement/verifiers.ts

@@ -0,0 +1,299 @@
+// A webhook delivery's signature, checked over the raw body before anything parses it. Each verifier is framework
+// code: a preset reads its provider's headers, an `hmac` shape computes the declared HMAC, `basic` and `bearer` compare
+// the secret itself. Every comparison is constant-time.
+
+import { FORM_URLENCODED_TYPE, type HmacAlgorithm, type HmacScheme, type WebhookScheme } from '@fabrika/auth-core'
+
+/** How far a signed timestamp may be from now: the window in which a captured delivery could be replayed. */
+export const WEBHOOK_TIMESTAMP_TOLERANCE_MS = 5 * 60 * 1000
+
+/** The prefix of a Standard Webhooks secret, whose rest is the key in base64. */
+const STANDARD_SECRET_PREFIX = 'whsec_'
+
+const ALGORITHMS: Readonly<Record<HmacAlgorithm, string>> = { sha1: 'SHA-1', sha256: 'SHA-256', sha512: 'SHA-512' }
+
+const encoder = new TextEncoder()
+
+/** What a verifier reads of a delivery. */
+export interface SignedDelivery {
+	readonly headers: Headers
+	readonly body: Uint8Array<ArrayBuffer>
+	/**
+	 * The URL the provider posted to: `FABRIKA_APP_ORIGIN` and the request's path and query, which Twilio signs. `null`
+	 * where the environment has no public origin.
+	 */
+	readonly url: string | null
+}
+
+/** Whether the delivery proves it holds `secret` under `scheme`. `now` is the clock a signed timestamp is checked against. */
+export async function verifyDelivery(scheme: WebhookScheme, delivery: SignedDelivery, secret: string, now: number): Promise<boolean> {
+	const { headers, body } = delivery
+	switch (scheme) {
+		case 'github-sha256':
+			return await verifyHmac(GITHUB, headers, encoder.encode(secret), body, now)
+		case 'slack':
+			return await verifySlack(headers, encoder.encode(secret), body, now)
+		case 'stripe':
+			return await verifyStripe(headers.get('Stripe-Signature'), encoder.encode(secret), body, now)
+		case 'standard-webhooks':
+			return await verifyStandard(headers, standardKey(secret), body, now)
+		case 'twilio':
+			return await verifyTwilio(delivery, encoder.encode(secret))
+	}
+	if ('hmac' in scheme) {
+		return await verifyHmac(scheme.hmac, headers, encoder.encode(secret), body, now)
+	}
+	const authorization = headers.get('Authorization')
+	if ('basic' in scheme) {
+		return await sameText(basicPassword(authorization), secret)
+	}
+	return await sameText(bearerToken(authorization), secret)
+}
+
+/** GitHub's `X-Hub-Signature-256: sha256=<hex>`, an HMAC-SHA256 of the body. */
+const GITHUB: HmacScheme = { header: 'X-Hub-Signature-256', algorithm: 'sha256', encoding: 'hex', prefix: 'sha256=', signed: 'body' }
+
+async function verifyHmac(
+	scheme: HmacScheme,
+	headers: Headers,
+	key: Uint8Array<ArrayBuffer>,
+	body: Uint8Array<ArrayBuffer>,
+	now: number,
+): Promise<boolean> {
+	const header = headers.get(scheme.header)
+	const prefix = scheme.prefix ?? ''
+	if (header === null || !header.startsWith(prefix)) {
+		return false
+	}
+	const signature = decode(header.slice(prefix.length), scheme.encoding)
+	if (signature === null) {
+		return false
+	}
+	const parts: string[] = []
+	if (scheme.id !== undefined) {
+		const id = headers.get(scheme.id)
+		if (id === null || id === '') {
+			return false
+		}
+		parts.push(id)
+	}
+	if (scheme.signed === 'timestamp.body') {
+		const timestamp = scheme.timestamp === undefined ? null : headers.get(scheme.timestamp)
+		if (timestamp === null || !fresh(timestamp, now)) {
+			return false
+		}
+		parts.push(timestamp)
+	}
+	return await hmacVerifies(scheme.algorithm, key, [signature], signedContent(parts, body))
+}
+
+/** Stripe's `Stripe-Signature: t=<seconds>,v1=<hex>[,v1=<hex>…]` over `<t>.<body>`; a rotated secret sends two `v1`. */
+async function verifyStripe(header: string | null, key: Uint8Array<ArrayBuffer>, body: Uint8Array<ArrayBuffer>, now: number): Promise<boolean> {
+	if (header === null) {
+		return false
+	}
+	let timestamp: string | null = null
+	const signatures: Uint8Array<ArrayBuffer>[] = []
+	for (const item of header.split(',')) {
+		const separator = item.indexOf('=')
+		const name = item.slice(0, separator).trim()
+		const value = item.slice(separator + 1).trim()
+		if (separator > 0 && name === 't') {
+			timestamp = value
+		} else if (separator > 0 && name === 'v1') {
+			const signature = decode(value, 'hex')
+			if (signature !== null) {
+				signatures.push(signature)
+			}
+		}
+	}
+	if (timestamp === null || !fresh(timestamp, now)) {
+		return false
+	}
+	return await hmacVerifies('sha256', key, signatures, signedContent([timestamp], body))
+}
+
+/** Slack's `X-Slack-Signature: v0=<hex>`, an HMAC-SHA256 of `v0:<X-Slack-Request-Timestamp>:<body>`, within five minutes. */
+async function verifySlack(headers: Headers, key: Uint8Array<ArrayBuffer>, body: Uint8Array<ArrayBuffer>, now: number): Promise<boolean> {
+	const timestamp = headers.get('X-Slack-Request-Timestamp')
+	const header = headers.get('X-Slack-Signature')
+	if (timestamp === null || header === null || !header.startsWith('v0=') || !fresh(timestamp, now)) {
+		return false
+	}
+	const signature = decode(header.slice(3), 'hex')
+	return signature !== null && (await hmacVerifies('sha256', key, [signature], prefixed(`v0:${timestamp}:`, body)))
+}
+
+/**
+ * Twilio's `X-Twilio-Signature`: the base64 HMAC-SHA1 of the URL it posted to, followed by a form's parameters sorted by
+ * name, each name then its value. A JSON body is signed through the URL instead: its `bodySHA256` parameter must be
+ * the body's SHA-256. Twilio signs no timestamp.
+ */
+async function verifyTwilio(delivery: SignedDelivery, key: Uint8Array<ArrayBuffer>): Promise<boolean> {
+	const header = delivery.headers.get('X-Twilio-Signature')
+	const signature = header === null ? null : decode(header, 'base64')
+	const content = await twilioSigned(delivery)
+	return signature !== null && content !== null && (await hmacVerifies('sha1', key, [signature], encoder.encode(content)))
+}
+
+async function twilioSigned({ headers, body, url }: SignedDelivery): Promise<string | null> {
+	if (url === null) {
+		return null
+	}
+	if (headers.get('Content-Type')?.split(';')[0]?.trim().toLowerCase() === FORM_URLENCODED_TYPE) {
+		const text = utf8(body)
+		if (text === null) {
+			return null
+		}
+		const parameters = [...new URLSearchParams(text)].sort(([leftName, leftValue], [rightName, rightValue]) =>
+			compareText(leftName, rightName) || compareText(leftValue, rightValue)
+		)
+		return url + parameters.map(([name, value]) => name + value).join('')
+	}
+	const claimed = new URL(url).searchParams.get('bodySHA256')
+	const digest = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', body)), (byte) => byte.toString(16).padStart(2, '0')).join('')
+	return claimed?.toLowerCase() === digest ? url : null
+}
+
+function compareText(left: string, right: string): number {
+	return left < right ? -1 : left > right ? 1 : 0
+}
+
+/** Standard Webhooks: `webhook-signature: v1,<base64> …` over `<webhook-id>.<webhook-timestamp>.<body>`. */
+async function verifyStandard(headers: Headers, key: Uint8Array<ArrayBuffer> | null, body: Uint8Array<ArrayBuffer>, now: number): Promise<boolean> {
+	const id = headers.get('webhook-id')
+	const timestamp = headers.get('webhook-timestamp')
+	const header = headers.get('webhook-signature')
+	if (key === null || id === null || id === '' || timestamp === null || header === null || !fresh(timestamp, now)) {
+		return false
+	}
+	const signatures = header.split(' ').flatMap((entry) => {
+		const signature = entry.startsWith('v1,') ? decode(entry.slice(3), 'base64') : null
+		return signature === null ? [] : [signature]
+	})
+	return await hmacVerifies('sha256', key, signatures, signedContent([id, timestamp], body))
+}
+
+/** A Standard Webhooks secret is `whsec_` and the key in base64; `null` when it is not. */
+export function standardKey(secret: string): Uint8Array<ArrayBuffer> | null {
+	return secret.startsWith(STANDARD_SECRET_PREFIX) ? decode(secret.slice(STANDARD_SECRET_PREFIX.length), 'base64') : null
+}
+
+/** A timestamp in Unix seconds within the tolerance of `now`. */
+function fresh(timestamp: string, now: number): boolean {
+	if (!/^[0-9]{1,12}$/.test(timestamp)) {
+		return false
+	}
+	return Math.abs(now - Number(timestamp) * 1000) <= WEBHOOK_TIMESTAMP_TOLERANCE_MS
+}
+
+/** `<part>.<part>.<body>`: what a timestamped or identified signature covers. */
+function signedContent(parts: readonly string[], body: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer> {
+	return parts.length === 0 ? body : prefixed(`${parts.join('.')}.`, body)
+}
+
+function prefixed(head: string, body: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer> {
+	const bytes = encoder.encode(head)
+	const content = new Uint8Array(bytes.byteLength + body.byteLength)
+	content.set(bytes, 0)
+	content.set(body, bytes.byteLength)
+	return content
+}
+
+/** Whether one of `signatures` is the HMAC of `content`; `crypto.subtle.verify` compares in constant time. */
+async function hmacVerifies(
+	algorithm: HmacAlgorithm,
+	key: Uint8Array<ArrayBuffer>,
+	signatures: readonly Uint8Array<ArrayBuffer>[],
+	content: Uint8Array<ArrayBuffer>,
+): Promise<boolean> {
+	if (signatures.length === 0 || key.byteLength === 0) {
+		return false
+	}
+	const imported = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: ALGORITHMS[algorithm] }, false, ['verify'])
+	let verified = false
+	for (const signature of signatures) {
+		verified = (await crypto.subtle.verify('HMAC', imported, signature, content)) || verified
+	}
+	return verified
+}
+
+/** The password of `Authorization: Basic <base64(user:password)>`; the user name is not checked. */
+function basicPassword(authorization: string | null): string | null {
+	const match = authorization === null ? null : /^Basic ([A-Za-z0-9+/]+={0,2})$/i.exec(authorization)
+	const credentials = match?.[1] === undefined ? null : decode(match[1], 'base64')
+	const text = credentials === null ? null : utf8(credentials)
+	const separator = text?.indexOf(':') ?? -1
+	return text === null || separator < 0 ? null : text.slice(separator + 1)
+}
+
+function utf8(bytes: Uint8Array): string | null {
+	try {
+		return new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+	} catch {
+		return null
+	}
+}
+
+function bearerToken(authorization: string | null): string | null {
+	const match = authorization === null ? null : /^Bearer (\S+)$/i.exec(authorization)
+	return match?.[1] ?? null
+}
+
+/** Whether two texts are equal, compared as SHA-256 digests in constant time. */
+async function sameText(given: string | null, expected: string): Promise<boolean> {
+	if (given === null || expected === '') {
+		return false
+	}
+	const [left, right] = await Promise.all(
+		[given, expected].map(async (text) => new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(text)))),
+	)
+	if (left === undefined || right === undefined) {
+		return false
+	}
+	let difference = 0
+	for (let index = 0; index < left.byteLength; index++) {
+		difference |= (left[index] ?? 0) ^ (right[index] ?? 0)
+	}
+	return difference === 0
+}
+
+/** Bytes of a hex or base64 text; `null` when it is not one. */
+function decode(text: string, encoding: 'hex' | 'base64'): Uint8Array<ArrayBuffer> | null {
+	if (encoding === 'hex') {
+		if (!/^(?:[0-9a-fA-F]{2})+$/.test(text)) {
+			return null
+		}
+		const bytes = new Uint8Array(text.length / 2)
+		for (let index = 0; index < bytes.byteLength; index++) {
+			bytes[index] = Number.parseInt(text.slice(index * 2, index * 2 + 2), 16)
+		}
+		return bytes
+	}
+	if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(text) || text === '') {
+		return null
+	}
+	const binary = atob(text)
+	const bytes = new Uint8Array(binary.length)
+	for (let index = 0; index < binary.length; index++) {
+		bytes[index] = binary.charCodeAt(index)
+	}
+	return bytes
+}
+
+/** The GitHub account a payload names, as a binding records it: `installation:<id>` or `repository:<id>`. */
+export function githubAccounts(payload: unknown): readonly string[] {
+	const accounts: string[] = []
+	for (const kind of ['installation', 'repository'] as const) {
+		const holder = ownField(payload, kind)
+		const id = ownField(holder, 'id')
+		if (typeof id === 'number' && Number.isSafeInteger(id) && id > 0) {
+			accounts.push(`${kind}:${id}`)
+		}
+	}
+	return accounts
+}
+
+function ownField(value: unknown, name: string): unknown {
+	return typeof value === 'object' && value !== null && Object.hasOwn(value, name) ? Reflect.get(value, name) : undefined
+}

package/src/implement/webhook.ts

@@ -1,24 +1,22 @@
-// `c.webhook` for GitHub (docs/reference/application-runtime.md). A holder of the bound dimension's `members.manage`
-// creates a binding through the generated `webhooks.<name>.bind` endpoint; the framework generates the secret and
-// keeps the binding in `fabrika_webhook_bindings`. A delivery is checked in a fixed order — the binding, the
-// signature over the raw body, the account, the input, the delivery id — before its handler sees a `Ref` of the
-// bound value only.
+// A webhook's bindings and deliveries (docs/reference/application-runtime.md). A procedure that declares `binds`
+// creates a binding through `ctx.webhooks('<name>')`. The framework generates the secret, or the procedure sets the one
+// the provider issued, and keeps the binding in `fabrika_webhook_bindings`. A delivery is checked in a fixed order —
+// the binding, the signature, the account, the input, the delivery key — before its handler sees a `Ref` of the bound
+// value, or its application-wide capabilities when the webhook is bound to `'app'`.
 
-import type { WebhookTables } from '@fabrika/db/framework'
+import { API_KEY_PREFIX, type ScopeBinding, type WebhookScheme } from '@fabrika/auth-core'
+import { type CapabilityAuthority, describeGrant } from '@fabrika/db/capability'
+import type { Session, WebhookTables } from '@fabrika/db/framework'
 import { uuidv7 } from '@fabrika/platform'
 import { z } from 'zod/v4'
-import { joinPath, WEBHOOK_ACCOUNT_PATTERN, WEBHOOK_SCOPE_FIELD } from '../contract/defaults'
-import { NotFoundError } from '../errors'
-import { Ref } from './capability'
-
-/** The input and output of the generated binding endpoints; `build.ts`'s `WEBHOOK_BIND_*` shapes describe them. */
-export const webhookBindInput = z.strictObject({
-	[WEBHOOK_SCOPE_FIELD]: z.string().min(1),
-	account: z.string().regex(new RegExp(WEBHOOK_ACCOUNT_PATTERN)),
-})
-export const webhookBindOutput = z.strictObject({ id: z.uuid(), url: z.string().min(1), secret: z.string().min(1) })
-export const webhookUnbindInput = z.strictObject({ [WEBHOOK_SCOPE_FIELD]: z.string().min(1), id: z.uuid() })
-export const webhookUnbindOutput = z.strictObject({ id: z.uuid() })
+import { joinPath } from '../contract/defaults'
+import type { WebhookBindings, WebhookSecret } from '../contract/webhook-binding'
+import { BadRequestError } from '../errors'
+import { CapabilityRefusedError } from './capability'
+import { standardKey } from './verifiers'
+
+/** A GitHub account a binding accepts: an App installation or a repository, by numeric id. */
+const GITHUB_ACCOUNT = /^(?:installation|repository):[1-9][0-9]{0,19}$/
 
 /** The workload a delivery runs as: no person, only the binding. It creates no scope and manages no member. */
 export interface WebhookPrincipal {
@@ -37,6 +35,12 @@ export function webhookSubject(bindingId: string): string {
  */
 export const WEBHOOK_REPLAY_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
 
+/**
+ * How long a delivery's claim outlasts its handler's time limit: a copy that arrives later finds the claim held and is
+ * answered as received; once the lease passed without a completion (a crash, a lost connection), the redelivery runs.
+ */
+export const WEBHOOK_CLAIM_GRACE_MS = 30_000
+
 /**
  * `sha256:<hex>` of the binding id and the signed body: what replay protection and an idempotent handler key on.
  * A redelivery of one event has the same key, whatever its `X-GitHub-Delivery` says.
@@ -55,54 +59,131 @@ export interface WebhookDelivery {
 	readonly key: string
 }
 
-/** 32 random bytes as hex: the HMAC key GitHub signs with, shown once to the member who binds. */
-function generateSecret(): string {
+/**
+ * 32 random bytes, shown once to the member who binds: as hex, the key a provider signs with or sends as its password
+ * or token; for Standard Webhooks, `whsec_` and the bytes in base64, as its senders expect.
+ */
+function generateSecret(scheme: WebhookScheme): string {
 	const bytes = crypto.getRandomValues(new Uint8Array(32))
+	if (scheme === 'standard-webhooks') {
+		return `whsec_${btoa(String.fromCharCode(...bytes))}`
+	}
 	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('')
 }
 
-export interface BindingHandlers {
-	bind(args: { readonly input: Readonly<Record<string, unknown>>; readonly ctx: object }): Promise<z.output<typeof webhookBindOutput>>
-	unbind(args: { readonly input: Readonly<Record<string, unknown>>; readonly ctx: object }): Promise<z.output<typeof webhookUnbindOutput>>
+/** The scope a binding of a webhook bound to `'app'` records: the application, which has no value. */
+export const APP_BINDING_SCOPE = Object.freeze({ type: 'app', value: '' })
+
+/** The longest account a binding records for a provider other than GitHub. */
+const MAX_ACCOUNT_LENGTH = 200
+
+/** The longest secret a provider may issue for a binding. */
+const MAX_SECRET_LENGTH = 512
+
+/** What a procedure that binds needs of its webhook: where deliveries arrive, how they are signed, what they reach. */
+export interface BindableWebhook {
+	readonly name: string
+	readonly path: string
+	readonly scheme: WebhookScheme
+	readonly boundTo: ScopeBinding
 }
 
-/** What the `in` access form handed a binding endpoint: the checked `Ref` of the value, and the person. */
-function accessOf(ctx: object): { readonly scope: Ref<string, string>; readonly principal: string } {
-	const target: unknown = Reflect.get(ctx, 'target')
-	const principal: unknown = Reflect.get(ctx, 'principal')
-	const id: unknown = typeof principal === 'object' && principal !== null ? Reflect.get(principal, 'id') : undefined
-	if (!(target instanceof Ref) || typeof id !== 'string') {
-		throw new TypeError('a binding endpoint runs for a person, with the Ref of its in access form')
-	}
-	return { scope: target, principal: id }
+/** Where `ctx.webhooks` runs: the procedure's transaction, bound to its request like every handle. */
+export interface BindingSite {
+	readonly site: string
+	readonly webhook: BindableWebhook
+	readonly tables: () => WebhookTables
+	readonly authority: CapabilityAuthority
+	readonly session: () => Promise<Session>
+	readonly check: () => void
+	/** Who binds: the caller's subject, recorded with the binding. */
+	readonly principal: string
 }
 
-/** The framework's handlers of `webhooks.<name>.bind` and `.unbind`. */
-export function bindingHandlers(webhook: string, path: string, tables: () => WebhookTables): BindingHandlers {
-	return {
-		async bind({ input, ctx }) {
-			const { scope, principal } = accessOf(ctx)
-			const account = z.parse(webhookBindInput.shape.account, input['account'])
+/** `ctx.webhooks` of a procedure that declares `binds`: only its declared webhook, only on the value its capability names. */
+export function webhookBindings(site: BindingSite): (name: string) => WebhookBindings {
+	const { webhook } = site
+	const scopeOf = (capability: unknown): { readonly type: string; readonly value: string } => {
+		site.check()
+		const grant = site.authority.resolve(capability)
+		if (webhook.boundTo.kind === 'app' && grant.kind === 'app') {
+			return APP_BINDING_SCOPE
+		}
+		if (webhook.boundTo.kind === 'dimension' && grant.kind === 'ref' && grant.dimension === webhook.boundTo.dimension) {
+			return { type: grant.dimension, value: grant.id }
+		}
+		const wanted = webhook.boundTo.kind === 'app' ? 'an app capability (ctx.app)' : `a Ref of ${webhook.boundTo.dimension}`
+		throw new CapabilityRefusedError(
+			'wrong_binding',
+			`${site.site}: webhook '${webhook.name}' binds with ${wanted}, and it was handed ${describeGrant(grant)}`,
+		)
+	}
+	const bindings: WebhookBindings = Object.freeze({
+		async bind(capability: unknown, account: unknown): Promise<WebhookSecret> {
+			const scope = scopeOf(capability)
+			const recorded = accountOf(webhook.scheme, account)
 			const id = uuidv7()
-			const secret = generateSecret()
-			await tables().createBinding({
-				id,
-				webhook,
-				scope: { type: scope.dimension, value: scope.value },
-				account,
-				secret,
-				createdBy: principal,
-				createdAt: Date.now(),
-			})
-			return { id, url: joinPath(path, id), secret }
+			const secret = generateSecret(webhook.scheme)
+			await site.tables().createBinding(
+				{ id, webhook: webhook.name, scope, account: recorded, secret, createdBy: site.principal, createdAt: Date.now() },
+				await site.session(),
+			)
+			return { id, url: joinPath(webhook.path, id), secret }
 		},
-		async unbind({ input, ctx }) {
-			const { scope } = accessOf(ctx)
-			const id = z.parse(webhookUnbindInput.shape.id, input['id'])
-			if (!(await tables().removeBinding(webhook, id, { type: scope.dimension, value: scope.value }))) {
-				throw new NotFoundError('Not found')
+		async setSecret(capability: unknown, id: unknown, secret: unknown): Promise<boolean> {
+			const scope = scopeOf(capability)
+			const issued = issuedSecret(webhook.scheme, secret)
+			if (typeof id !== 'string' || !z.uuid().safeParse(id).success) {
+				return false
 			}
-			return { id }
+			return await site.tables().replaceSecret(webhook.name, id, scope, issued, await site.session())
 		},
+		async unbind(capability: unknown, id: unknown): Promise<boolean> {
+			const scope = scopeOf(capability)
+			if (typeof id !== 'string' || !z.uuid().safeParse(id).success) {
+				return false
+			}
+			return await site.tables().removeBinding(webhook.name, id, scope, await site.session())
+		},
+	})
+	return (name) => {
+		if (name !== webhook.name) {
+			throw new CapabilityRefusedError('undeclared_binding', `${site.site} does not declare binds: '${String(name)}'`)
+		}
+		return bindings
+	}
+}
+
+/** The account a binding records: GitHub's `installation:<id>` or `repository:<id>`, another provider's own label. */
+function accountOf(scheme: WebhookScheme, account: unknown): string {
+	if (scheme === 'github-sha256') {
+		if (typeof account !== 'string' || !GITHUB_ACCOUNT.test(account)) {
+			throw new BadRequestError("A GitHub binding's account is installation:<id> or repository:<id>")
+		}
+		return account
+	}
+	const printable = (text: string) => [...text].every((char) => char >= ' ' && char !== '\u007f')
+	if (typeof account !== 'string' || account === '' || account.length > MAX_ACCOUNT_LENGTH || !printable(account)) {
+		throw new BadRequestError(`A binding's account is a text of 1 to ${MAX_ACCOUNT_LENGTH} printable characters`)
+	}
+	return account
+}
+
+/**
+ * A secret the provider issued, as the binding's verifier can use it: printable text of 1 to 512 characters; a Standard
+ * Webhooks one is `whsec_` and base64; a Basic password or bearer token never carries a platform key, which the proxy
+ * removes from every request (ADR-0022 rule 3).
+ */
+function issuedSecret(scheme: WebhookScheme, secret: unknown): string {
+	const printable = (text: string) => [...text].every((char) => char > ' ' && char !== '\u007f')
+	if (typeof secret !== 'string' || secret === '' || secret.length > MAX_SECRET_LENGTH || !printable(secret)) {
+		throw new BadRequestError(`A webhook secret is a text of 1 to ${MAX_SECRET_LENGTH} printable characters without spaces`)
+	}
+	if (scheme === 'standard-webhooks' && standardKey(secret) === null) {
+		throw new BadRequestError('A Standard Webhooks secret is whsec_ and the key in base64')
+	}
+	if (typeof scheme === 'object' && !('hmac' in scheme) && secret.includes(API_KEY_PREFIX)) {
+		throw new BadRequestError(`A Basic password or bearer token cannot contain ${API_KEY_PREFIX}: the proxy removes a platform key from every request`)
 	}
+	return secret
 }

package/src/implement/workload.ts

@@ -1,12 +1,14 @@
-// A job's and a webhook's authority (ADR-0022 "Principal kinds"): Control reconciles one `px_` key per workload from
-// the approved snapshot and writes it as `FABRIKA_<KIND>_<NAME>_KEY`; IAM signs a token from it carrying the actions
-// the reconciled schema declares. The framework mints a capability only for an action that token carries, so the
+// A job's, a webhook's and a public procedure's authority (ADR-0022 "Principal kinds"): Control reconciles one `px_` key
+// per workload from the approved snapshot and writes it under `workloadKeyVariable`; IAM signs a token from it carrying
+// the actions the reconciled schema declares. The framework mints a capability only for an action that token carries, so the
 // authority comes from IAM, not from the application's own copy of the contract.
 
 import {
 	API_KEY_PREFIX,
 	type ContractArtifact,
+	contractWorkloads,
 	type MintFromKeyResult,
+	type OwnWorkloadKind,
 	type PermissionEntry,
 	TOKEN_REFRESH_SKEW_SECONDS,
 	WORKLOAD_TOKEN_PATH,
@@ -15,7 +17,7 @@ import {
 import type { TokenVerifier } from '@fabrika/jwks'
 import { z } from 'zod/v4'
 
-export type WorkloadKindOf = 'job' | 'webhook'
+export type WorkloadKindOf = OwnWorkloadKind
 
 /** Where a workload exchanges its key for a token: IAM's public `WORKLOAD_TOKEN_PATH`, or a stand-in in a test. */
 export interface WorkloadTokenSource {
@@ -124,6 +126,11 @@ export class WorkloadCredential {
 	}
 }
 
+/** The key a workload's credential is found under: `job:<name>`, `webhook:<name>`, `public:<endpoint id>`. */
+export function workloadSite(kind: WorkloadKindOf, name: string): string {
+	return `${kind}:${name}`
+}
+
 export interface WorkloadCredentialsInput {
 	readonly artifact: ContractArtifact
 	readonly framework: Readonly<Record<string, string>>
@@ -132,26 +139,21 @@ export interface WorkloadCredentialsInput {
 	readonly verifier: TokenVerifier
 }
 
-/** `job:<name>` and `webhook:<name>` → the workload's credential, or why one cannot start to `problems`. */
+/** `workloadSite(kind, name)` → the workload's credential, or why one cannot start to `problems`. */
 export function workloadCredentials(input: WorkloadCredentialsInput, problems: string[]): ReadonlyMap<string, WorkloadCredential> {
-	const workloads: [WorkloadKindOf, string][] = [
-		...Object.keys(input.artifact.jobs).map((name): [WorkloadKindOf, string] => ['job', name]),
-		...Object.entries(input.artifact.mounts).flatMap((
-			[name, mount],
-		): [WorkloadKindOf, string][] => (mount.kind === 'webhook' ? [['webhook', name]] : [])),
-	]
+	const workloads = contractWorkloads(input.artifact)
 	const credentials = new Map<string, WorkloadCredential>()
 	if (workloads.length > 0 && input.source === undefined) {
-		problems.push('the contract declares jobs or webhooks, and the runtime adapter supplies no IAM token exchange for their keys')
+		problems.push('the contract declares jobs, webhooks or public procedures, and the runtime adapter supplies no IAM token exchange for their keys')
 	}
-	for (const [kind, name] of workloads) {
+	for (const { kind, name } of workloads) {
 		const variable = workloadKeyVariable(kind, name)
 		const key = input.framework[variable]?.trim() ?? ''
 		if (!key.startsWith(API_KEY_PREFIX) || key.length <= API_KEY_PREFIX.length) {
 			problems.push(`${variable} is not set to a px_ key; Control writes the credential of the ${kind} '${name}' into every deploy`)
 		} else if (input.source !== undefined) {
 			credentials.set(
-				`${kind}:${name}`,
+				workloadSite(kind, name),
 				new WorkloadCredential({ kind, name, key, audience: input.audience, source: input.source, verifier: input.verifier }),
 			)
 		}

package/src/index.ts

@@ -30,6 +30,9 @@ export {
 // ─── Rows ────────────────────────────────────────────────────────────
 export { fromPage, fromRow, type RowInput } from './from-row.js'
 
+// ─── Public procedures ───────────────────────────────────────────────
+export { honeypot } from './honeypot.js'
+
 // ─── Auth contract ───────────────────────────────────────────────────
 export type { AuthContext, Scope } from '@fabrika/auth'