@fabrika/app 0.7.0 → 0.8.1

package/package.json

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

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabrika-app
-version: 0.7.0
+version: 0.8.1
 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.7.0",
-		"@fabrika/db": "0.7.0",
-		"@fabrika/provider-zerops": "0.7.0",
-		"@fabrika/proxy-core": "0.7.0",
-		"@fabrika/ui": "0.7.0",
+		"@fabrika/app": "0.8.1",
+		"@fabrika/db": "0.8.1",
+		"@fabrika/provider-zerops": "0.8.1",
+		"@fabrika/proxy-core": "0.8.1",
+		"@fabrika/ui": "0.8.1",
 		"kysely": "0.29.6",
 		"react": "^19.0.0",
 		"react-dom": "^19.0.0",
 		"zod": "^3.25.76"
 	},
 	"devDependencies": {
-		"@fabrika/check": "0.7.0",
-		"@fabrika/cli": "0.7.0",
-		"@fabrika/platform": "0.7.0",
+		"@fabrika/check": "0.8.1",
+		"@fabrika/cli": "0.8.1",
+		"@fabrika/platform": "0.8.1",
 		"@happy-dom/global-registrator": "^20.11.2",
 		"@types/bun": "latest",
 		"@types/react": "^19.0.0",
@@ -160,16 +160,20 @@ export default serve(contract, { database: scoped(tables) })
   stylesheet origin in `styleSrc` and its font origin in `fontSrc`; font files under the SPA's `dir` need neither. No path under `/__fabrika`.
 - A public procedure's abuse control is its `admission`: `rate: { perClient, perEndpoint }` (per minute, shared by
   every instance; 10 and 100 by default for a public mutation; 429 past either) and
-  `challenge: { provider: 'turnstile', secret: 'TURNSTILE_SECRET', siteKey: 'TURNSTILE_SITE_KEY' }`. `honeypot(value)`
-  of `@fabrika/app` is true for a filled field the page hides: answer the same and write nothing. A challenge needs the
-  input field `challengeToken: z.string()`, which the page fills from the Turnstile widget rendered with `action` set
-  to the endpoint id with `_` for `.` (`api_visitors_register`), or to the challenge's own `action: 'register'` (at most
-  32 letters, digits, `_` and `-`, one per procedure); the framework verifies it on the server (a failed or replayed
-  token 400 `challenge_failed`, an unreachable provider 503, no row either way) and adds Turnstile's origin to the CSP. `secret` names an
-  application variable the human sets, never the value; without it the application does not boot. `siteKey` names
-  the variable with the widget's public site key, which every SPA mount serves its pages (below). On Zerops every
-  visitor still shares one client address (the balancer), so `perClient` acts as a second per-endpoint limit: raise
-  it, and use the challenge. `references/public-intake.md` builds a whole public intake on it.
+  `challenge: { provider: 'altcha', secret: 'ALTCHA_HMAC_KEY' }`. `honeypot(value)` of `@fabrika/app` is true for a
+  filled field the page hides: answer the same and write nothing. A challenge needs the input field
+  `challengeToken: z.string()`. An ALTCHA challenge is a proof of work the application issues at
+  `GET /__fabrika/challenge/<action>` (`challengeUrl(api.<procedure>)` of `@fabrika/app/client`; the action is the
+  endpoint id with `_` for `.`, `api_visitors_register`, or the challenge's own `action: 'register'`, at most 32
+  letters, digits, `_` and `-`, one per procedure) and verifies itself, asking no one: the page renders `Challenge` of
+  `@fabrika/ui/challenge`, which fills the field. A failed, expired or replayed one is 400 `challenge_failed`, no row.
+  `secret` names the application variable holding the HMAC key, which the human sets to a long random value
+  (32 characters at least), never the value itself; without it, or with a shorter one, the application does not boot. `cost` and `maxAgeMs` set the work and the lifetime
+  (`references/public-intake.md`). `provider: 'turnstile'` (with `siteKey`, verified at Cloudflare, an unreachable
+  provider 503) is the alternative when the human asks for it; it adds Cloudflare's origin to the CSP and serves the
+  site key to every SPA mount's pages (below). On Zerops every visitor still shares one client address (the balancer),
+  so `perClient` acts as a second per-endpoint limit: raise it, and use the challenge.
+  `references/public-intake.md` builds a whole public intake on it.
 - `defineApp(vocabulary, tables, { imports?, tokens? })`: `imports` names other applications' exports
   (`references/webhooks-links-connectors.md`), `tokens` the purposes of signed tokens (`references/endpoint.md`).
 - `c.rpc('/api/v1', groups, { compatibility: 'backward' })` promises a mount's callers a stable API
@@ -241,9 +245,9 @@ zerops:
         - bun run build:web
 ```
 
-The platform's build runs the tests, writes the entrypoint, runs `fabrika-check` and the type check. Its start script
-runs `fabrika db migrate`, `fabrika db codegen --verify` and `fabrika db test-isolation` before the server: the
-application is not ready until every generated test passes. It writes every `FABRIKA_*` variable; never set one.
+The platform's build runs the tests, writes the entrypoint, runs `fabrika-check` and the type check. Its init commands
+run `fabrika db migrate`, `fabrika db codegen --verify` and `fabrika db test-isolation` before the server starts: a
+version does not go live until every generated test passes. It writes every `FABRIKA_*` variable; never set one.
 
 ## The SPA (added when the application has one)
 

package/skill/references/dev.md

@@ -59,10 +59,13 @@ export default seed
 - `dev/dev.env` holds the application's variables for `app dev`, one `NAME=value` per line (`#` comments, quotes
   optional). They win over the shell's; a `FABRIKA_*` name is refused. Commit it: it holds stand-in values, never a
   real secret.
-- A public procedure's challenge passes in `app dev`: the stand-in answers Turnstile's siteverify for any token. Set the
-  challenge's `secret` variable to any value in `dev/dev.env`, and send a fresh `challengeToken` with each submission, as a test
-  does: a token is single use. For the widget on a page, set the `siteKey` variable to Turnstile's always-passing test
-  key `1x00000000000000000000AA`. Its token is the same every time, and `app dev` admits that one token again at each
+- A public procedure's ALTCHA challenge works in `app dev` as deployed, only cheaper: set the challenge's `secret`
+  variable in `dev/dev.env` to any value of at least 32 characters, as deployed, and the page's widget solves the challenge `app dev` issues in moments,
+  whatever the contract's `cost`. A solved challenge passes once, as deployed; the widget fetches a new one.
+- A Turnstile challenge passes in `app dev`: the stand-in answers Turnstile's siteverify for any token. Set its
+  `secret` variable to any value, and send a fresh `challengeToken` with each submission, as a test does: a token is
+  single use. For the widget on a page, set the `siteKey` variable to Turnstile's always-passing test key
+  `1x00000000000000000000AA`. Its token is the same every time, and `app dev` admits that one token again at each
   submission; a deployed application records it like any other, so there it passes once.
 - A job's e-mail goes to the kit's mail stand-in (`dev.mail`, as `kit.mail` in a test): nothing is delivered, and no
   mail variable is needed. The mail view lists each message, newest first, beside IAM's invitations: the recipient,
@@ -80,8 +83,7 @@ export default seed
 
 ```text dev/dev.env
 # Stand-in values for fabrika app dev.
-TURNSTILE_SECRET=dev
-TURNSTILE_SITE_KEY=1x00000000000000000000AA
+ALTCHA_HMAC_KEY=dev-altcha-hmac-key-of-32-characters
 ARCHIVE_URL=https://outbox.invalid/archive
 ARCHIVE_KEY=dev
 ```

package/skill/references/endpoint.md

@@ -558,13 +558,13 @@ should hold. The generated tests skip the other-scope leak case for such an endp
 
 Every procedure takes `admission` (who may send it, how often) and `limits` (how large, how long):
 
-| Option                              | Credentialed and link procedures                                                                       | Public procedures (`references/public-intake.md`)                 |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
-| `admission.rate` (calls per minute) | `perCaller`, `perEndpoint`; none by default                                                            | `perClient`, `perEndpoint`, `bytesPerHour`; a mutation 10 and 100 |
-| `admission.origins`                 | `'same-origin'` (default) or `'listed'`                                                                | `'same-origin'`, `'listed'` or `'any'`                            |
-| `admission.challenge`               | —                                                                                                      | `{ provider: 'turnstile', secret, siteKey, action? }`             |
-| `limits.maxBytes`                   | 64 KiB, at most 1 MiB; with file fields 64 KiB plus each file at its kind's `maxBytes`, at most 48 MiB | the same                                                          |
-| `limits.timeoutMs`                  | 10 s, at most 60 s                                                                                     | the same                                                          |
+| Option                              | Credentialed and link procedures                                                                       | Public procedures (`references/public-intake.md`)                                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `admission.rate` (calls per minute) | `perCaller`, `perEndpoint`; none by default                                                            | `perClient`, `perEndpoint`, `bytesPerHour`; a mutation 10 and 100                                                     |
+| `admission.origins`                 | `'same-origin'` (default) or `'listed'`                                                                | `'same-origin'`, `'listed'` or `'any'`                                                                                |
+| `admission.challenge`               | none                                                                                                   | `{ provider: 'altcha', secret, action?, cost?, maxAgeMs? }`, or `{ provider: 'turnstile', secret, siteKey, action? }` |
+| `limits.maxBytes`                   | 64 KiB, at most 1 MiB; with file fields 64 KiB plus each file at its kind's `maxBytes`, at most 48 MiB | the same                                                                                                              |
+| `limits.timeoutMs`                  | 10 s, at most 60 s                                                                                     | the same                                                                                                              |
 
 - A declared `rate` merges into the default; `null` turns one bucket off. Past a bucket the answer is 429.
 - Every bucket is charged before the body is read and stays charged whatever the handler does. A bucket is a database
@@ -572,6 +572,8 @@ Every procedure takes `admission` (who may send it, how often) and `limits` (how
 - The body must arrive within `max(30 s, maxBytes at 16 KiB/s)`: a stalled body is 408. The handler's time starts
   after the last byte, so a slow upload still commits.
 - The approver sees every effective value. A higher bucket, a dropped challenge or a longer time limit widens.
+- An `altcha` challenge adds the framework's own `GET /__fabrika/challenge/<action>`, which issues it from the
+  procedure's origins under buckets of its own (30 per client and 600 in all, at least twice the procedure's). The approver sees that endpoint too.
 
 ## Another origin: `admission.origins: 'listed'`
 

package/skill/references/public-intake.md

@@ -421,11 +421,7 @@ export const visitors = app.group({}, (r) => ({
 		access: { public: true },
 		actions: ['candidates.register'],
 		admission: {
-			challenge: {
-				provider: 'turnstile',
-				secret: 'TURNSTILE_SECRET',
-				siteKey: 'TURNSTILE_SITE_KEY',
-			},
+			challenge: { provider: 'altcha', secret: 'ALTCHA_HMAC_KEY' },
 			rate: { perClient: 100, perEndpoint: 100, bytesPerHour: 536870912 },
 		},
 		kicks: ['intake'],
@@ -479,14 +475,26 @@ export const visitors = app.group({}, (r) => ({
 - **`ctx.client`** is `{ ip, userAgent }` as the proxy saw them, for consent evidence in a column of the row; `ip` is
   `null` on Zerops. Never decide on either.
 - **Its abuse control.** `honeypot(input.website)` is true when the field the page hides is filled: answer the same
-  and write no row. `admission.challenge` makes the framework verify the Turnstile token in the input field
-  `challengeToken` before the handler runs (a failed or replayed token 400 `challenge_failed`, an unreachable provider 503, no row either way) and adds
-  Turnstile's origin to the CSP. `TURNSTILE_SECRET` is an application variable the human sets; without it the
-  application does not boot. `siteKey` names the variable with the widget's public site key, which every SPA mount
-  serves its pages; without it the application does not boot either. Another public value a page needs per
-  environment (a link target) goes in the SPA mount's `browserConfig` list: `c.spa('/', { …, browserConfig: ['SIGNUP_URL'] })`. Both
-  reach the page in `<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.
+  and write no row. `admission.challenge: { provider: 'altcha', secret: 'ALTCHA_HMAC_KEY' }` is a proof of work the
+  application issues and verifies itself: the framework serves `GET /__fabrika/challenge/<action>` (the endpoint id
+  with `_` for `.`, `api_visitors_register`, or the challenge's own `action`), from the procedure's origins with a
+  buckets of its own (30 per client and 600 in all per minute, and at least twice the procedure's), and verifies the solved challenge in the input field
+  `challengeToken` before the handler runs: a failed, expired or replayed one, or one issued for another host or
+  procedure, is 400 `challenge_failed`, no row. No request leaves the installation, no third party sees the visitor,
+  and there is no site key. `ALTCHA_HMAC_KEY` is an application variable the human sets to a long random value
+  (`openssl rand -base64 32`); without it, or with one under 32 characters, the application does not boot: every
+  challenge publishes a signature a short key could be guessed from, and the key forges every challenge. `cost`
+  (PBKDF2 iterations per attempt, 5000 by default, 1000 to 18000) and `maxAgeMs` (how long a challenge may be solved
+  and sent, ten minutes by default, a minute to an hour) are the contract's, and the approver sees both. A browser
+  makes up to 10000 attempts, about 5000 on average, a few seconds on a phone at the default; the build refuses a
+  `cost` a slow phone would not solve within the widget's 90 s or half of `maxAgeMs`. The CSP gains `worker-src 'self' blob:`, where the widget solves.
+- **Turnstile instead.** `challenge: { provider: 'turnstile', secret: 'TURNSTILE_SECRET', siteKey: 'TURNSTILE_SITE_KEY' }`
+  verifies Cloudflare's widget at Cloudflare (an unreachable provider is 503), adds Cloudflare's origin to the CSP, and
+  serves the site key to every SPA mount's pages. Use it only when the human asks for it: it needs a Cloudflare
+  account and a widget per hostname, and sends every visitor to a third party. Another public value a page needs per
+  environment (a link target) goes in the SPA mount's `browserConfig` list: `c.spa('/', { …, browserConfig: ['SIGNUP_URL'] })`.
+  It reaches the page in `<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.
   `admission.rate: { perClient, perEndpoint }` (per minute, 10 and 100 by default for a public mutation) answers 429
   past either limit; `null` turns one off. A public query counts nothing unless it declares a bucket, since each
   bucket is a database write per call: a page of twenty images costs no write. All public procedures of an instance
@@ -496,14 +504,16 @@ export const visitors = app.group({}, (r) => ({
   within it.
 - **The order of a public request**, each refusal with its answer: the origin rule (403), the in-flight share (503),
   every bucket (429), the bounded body and the strict input with its signed tokens (413, 400), the workload token (503
-  while the platform's identity service is down), the challenge (400, 503 when the provider is unreachable), the staged file parts, then the handler, the
+  while the platform's identity service is down), the challenge (400; Turnstile's 503 when Cloudflare is unreachable), the staged file parts, then the handler, the
   commit and the kicks.
 - **A form on someone else's page.** A page served from this application's own origin needs nothing. A partner's page
   or a separate marketing site needs `admission.origins`: `'listed'` for the origins an operator lists for the
   environment in Control, `'any'` for any site (an embeddable widget). Keep the honeypot, the challenge and the rate
   limit: `'any'` invites every site. Such a page is not yours to change in step with the application, so give it a URL
   and a widget action that do not follow your group names: `http: { path: '/register' }` and
-  `challenge: { …, action: 'register' }`. The path lies outside every mount's prefix (the root SPA's excepted).
+  `challenge: { …, action: 'register' }`, so its challenge is at `/__fabrika/challenge/register`. The path lies outside
+  every mount's prefix (the root SPA's excepted). That page bundles the `altcha` widget itself, points its `challenge`
+  attribute at the application's origin and that path, and needs `worker-src blob:` in its own CSP.
 - **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-endpoint limit: set it to the expected
   peak, never lower it to stop a flood. The challenge is the defense that does not depend on the address.
@@ -1064,23 +1074,6 @@ export const attach = async (file: File): Promise<string> => {
 }
 ```
 
-The public page reads its site key from the config the framework serves it, so one build serves every environment.
-
-```ts web/site/config.ts
-import { z } from 'zod/v4'
-
-const SiteConfig = z.object({
-	public: z.object({ TURNSTILE_SITE_KEY: z.string() }),
-})
-
-/** The Turnstile widget's site key, or `null` when the config is unreadable. */
-export const siteKey = async (): Promise<string | null> => {
-	const response = await fetch('/__fabrika-config.json')
-	const config = SiteConfig.safeParse(response.ok ? await response.json() : null)
-	return config.success ? config.data.public.TURNSTILE_SITE_KEY : null
-}
-```
-
 The public page calls the public procedure through the typed client, like any other. An input with a file is sent
 as a multipart body, and one without a file as JSON.
 
@@ -1127,8 +1120,57 @@ export const register = async (
 }
 ```
 
-- The page renders the Turnstile widget with the site key `siteKey()` reads and `action` set to the procedure's
-  endpoint id with `_` for `.` (`api_visitors_register`), and passes the widget's token. Say "check your inbox" on success whatever the address was.
+The page renders the challenge with `@fabrika/ui/challenge`, which bundles the `altcha` widget with the page (add
+`altcha` to the dependencies: it is the kit's optional peer). `challengeUrl` gives the address the widget fetches the
+procedure's challenge from; nothing else is configured per environment.
+
+```tsx web/site/register-form.tsx
+import { challengeUrl, createClient } from '@fabrika/app/client'
+import { Challenge } from '@fabrika/ui/challenge'
+import { useState } from 'react'
+import { contract } from '../../fabrika.contract'
+import { register } from './register'
+
+const api = createClient(contract, 'api')
+
+export function RegisterForm() {
+	const [token, setToken] = useState<string | null>(null)
+	// A challenge passes once: a new key renders a fresh one after a refusal.
+	const [attempt, setAttempt] = useState(0)
+	const [sent, setSent] = useState(false)
+	if (sent) return <p>Check your inbox.</p>
+	return (
+		<form
+			onSubmit={async (event) => {
+				event.preventDefault()
+				if (token === null) return
+				if (await register(event.currentTarget, token)) setSent(true)
+				else setAttempt((n) => n + 1)
+			}}
+		>
+			<input name="email" type="email" required aria-label="E-mail" />
+			<input name="full_name" required aria-label="Full name" />
+			<input name="website" tabIndex={-1} autoComplete="off" hidden />
+			<input
+				name="photo"
+				type="file"
+				accept="image/*"
+				capture="environment"
+				aria-label="Photo"
+			/>
+			<Challenge
+				key={attempt}
+				url={challengeUrl(api.visitors.register)}
+				onToken={setToken}
+			/>
+			<button type="submit" disabled={token === null}>Register</button>
+		</form>
+	)
+}
+```
+
+- Say "check your inbox" on success whatever the address was. The widget reads its texts in English; translate them
+  with `strings` (`<Challenge strings={{ label: 'Nejsem robot', verified: 'Ověřeno' }} … />`).
 - The resend form calls `api.visitors.resend({ email })`. It answers the same for an unknown, a verified and a
   rate-limited address; the job decides.
 - Build each SPA into its `dir` (`dist/site`, `dist/portal`, `dist/hr`): one `Bun.build` per `index.html` in
@@ -1752,9 +1794,11 @@ export const testMails = app.cron('* * * * *', {
   })` and calls `createClient(contract, 'portal', { fetch: kit.fetch, key: holder.key ?? '' })`.
 - The job asks IAM to issue and revoke links, and the kit's own IAM answers only the credentials of its callers, not a
   job's key, so `kit.runJob('intake')` needs `testKit(app, { membership })` with an `IamMembershipRpc` of your own that
-  answers `issueLink` and `revokeLink`. A test of a public procedure with a challenge passes `env: {
-  TURNSTILE_SECRET: '…', TURNSTILE_SITE_KEY: '…' }` and `challengeFetch`, a stand-in for Turnstile's answer, to `testKit`, and a fresh
-  `challengeToken` with each submission: a token is single use. A submission with a photo goes through the typed
+  answers `issueLink` and `revokeLink`. A test of a public procedure with an ALTCHA challenge passes `env: {
+  ALTCHA_HMAC_KEY: '<32 characters or more>' }` to `testKit` and a fresh `challengeToken: await kit.solveChallenge(api.visitors.register)`
+  with each submission: a challenge passes once. The kit issues the cheapest challenge whatever the contract's
+  `cost`, and verifies it as production does, so a solve takes milliseconds. A Turnstile challenge instead takes
+  `challengeFetch`, a stand-in for Cloudflare's answer, and any fresh token. A submission with a photo goes through the typed
   client over `kit.fetch`, and needs `files: new MemoryFileObjects()` in `testKit`; `kit.runJob('intake')` then
   writes the photo's reference into the candidate, and the scan job (`FILE_SCAN_JOB`, with a `scanner`) makes it
   readable. Test the refusals beside the success: no or a failed token, a filled honeypot, a file too large or of
@@ -1825,7 +1869,7 @@ if (postgres !== null) {
 		database: postgres.database,
 		files: new MemoryFileObjects(),
 		membership,
-		env: { TURNSTILE_SECRET: 'test', TURNSTILE_SITE_KEY: 'test-site-key' },
+		env: { ALTCHA_HMAC_KEY: 'test-altcha-hmac-key-of-32-characters' },
 	})
 	afterEach(() => kit.mail.heal())
 	const sentTo = (address: string) =>
@@ -1856,7 +1900,7 @@ if (postgres !== null) {
 					database: postgres.database,
 					files: new MemoryFileObjects(),
 					membership,
-					env: { TURNSTILE_SECRET: 'test', TURNSTILE_SITE_KEY: 'test-site-key' },
+					env: { ALTCHA_HMAC_KEY: 'test-altcha-hmac-key-of-32-characters' },
 					mail: 'none',
 				},
 			)

package/skill/references/spa.md

@@ -12,6 +12,7 @@ dependencies, `tsconfig.json` (`"jsx": "react-jsx"`) and `build-web.ts`.
 | `@fabrika/app/react`         | `FabrikaProvider`, `useQuery`, `useInfiniteQuery`, `useMutation`, `useAction`, `useDownload`, `useInvalidate`, `skip`, `useCaller`, `Can`, `FabrikaError` |
 | `@fabrika/app/react/testing` | `installDom`, `type`, `controlByLabel`, `waitForText`: a screen test's DOM and typing                                                                     |
 | `@fabrika/ui`                | the components below, `createRouter`, and `@fabrika/ui/styles.css`                                                                                        |
+| `@fabrika/ui/challenge`      | `Challenge`: the ALTCHA widget of a public procedure's challenge, at `challengeUrl(api.<procedure>)`; needs the `altcha` package (`public-intake.md`)     |
 
 ## The provider and the routes
 

package/skill/references/tests.md

@@ -300,10 +300,13 @@ if (postgres !== null) {
   without it the application does not boot. With `scan: true`, an upload stays `quarantined` until
   `kit.runJob(FILE_SCAN_JOB)` (`@fabrika/app/implement`) runs with a `scanner` passed to `testKit`: a `FileScanner`
   stand-in, or the real ClamAV one, `clamscanScanner()` of `@fabrika/app/bun`.
-- A challenge token is single use: a second submission with the same token answers 400 `challenge_failed`,
-  also when the test's `challengeFetch` answers success. Send a fresh token with each submission
-  (`crypto.randomUUID()`). `passingChallenge` (`@fabrika/app/testing`) is a `challengeFetch` that passes every token;
-  a stand-in of your own receives the check (`hostname`, `action`) a passing answer must confirm as its second argument.
+- A challenge passes once: a second submission with the same token answers 400 `challenge_failed`. For an ALTCHA
+  challenge, `await kit.solveChallenge(api.<procedure>)` fetches one through the kit's proxy and solves it, so send a
+  fresh one with each submission; the kit issues the cheapest challenge and verifies it as production does. For a
+  Turnstile challenge send a fresh token with each submission (`crypto.randomUUID()`), also when the test's
+  `challengeFetch` answers success. `passingChallenge` (`@fabrika/app/testing`) is a `challengeFetch` that passes every
+  token; a stand-in of your own receives the check (`hostname`, `action`) a passing answer must confirm as its second
+  argument.
 - `testKit` takes no `deps`, and a test may not start a server (`Bun.serve` is `forbidden-global`). Stand in for an
   outbound dependency through its variables: `env` points it at a test URL, and `spyOn(globalThis, 'fetch')` answers
   that URL only and passes every other request on to the real `fetch`.

package/src/client/contract.ts

@@ -9,7 +9,7 @@ import { z } from 'zod/v4'
 import { type AttachmentBrand, attachmentOf } from '../contract/attachment'
 import { isProcedure, type ProcedureTreeDeclaration, type ProcedureType, SURFACE_SECTIONS } from '../contract/declaration'
 import { FILE_INPUT_PART } from '../contract/defaults'
-import { joinPath, LINK_API_SEGMENT, procedurePath } from '../contract/defaults'
+import { challengePath, declaredChallengeAction, joinPath, LINK_API_SEGMENT, procedurePath } from '../contract/defaults'
 import type { AnyContract, InputSchema, Procedure, Schema, Surface } from '../contract/define'
 import { type ClientInput, type FileBrand, fileOf } from '../contract/file'
 import { type BounceConfig, type BounceOption, exchange, exchangeFile, resolveBounce, RpcError, type RpcFetch } from './transport'
@@ -201,6 +201,30 @@ interface TreeAt {
 	readonly path: string
 }
 
+/** Where each procedure of a client with an ALTCHA challenge fetches it, by the procedure's value. */
+const challengeUrls = new WeakMap<object, string>()
+
+/**
+ * The URL a page's ALTCHA widget fetches the challenge of `procedure` from (`GET /__fabrika/challenge/<action>`), on the
+ * client's `baseUrl`. Throws for a procedure whose `admission.challenge` is not `provider: 'altcha'`.
+ */
+export function challengeUrl(procedure: object): string {
+	const url = challengeUrls.get(procedure)
+	if (url === undefined) {
+		throw new Error("challengeUrl takes a procedure of a client createClient made whose admission.challenge is provider: 'altcha'")
+	}
+	return url
+}
+
+/** The action of a procedure's declared ALTCHA challenge, or `null`; `buildArtifact` refuses every other shape. */
+function altchaActionOf(admission: unknown, id: string): string | null {
+	const challenge: unknown = typeof admission === 'object' && admission !== null ? Reflect.get(admission, 'challenge') : undefined
+	if (typeof challenge !== 'object' || challenge === null || Reflect.get(challenge, 'provider') !== 'altcha') {
+		return null
+	}
+	return declaredChallengeAction(id, Reflect.get(challenge, 'action'))
+}
+
 function clientTree(
 	tree: ProcedureTreeDeclaration<Schema, unknown>,
 	at: TreeAt,
@@ -209,19 +233,27 @@ function clientTree(
 	const client: Record<string, unknown> = {}
 	for (const [name, node] of Object.entries(tree)) {
 		const path = at.path === '' ? name : `${at.path}.${name}`
-		client[name] = isProcedure(node)
-			? make({
-				id: `${at.mount}.${path}`,
-				url: `${at.origin}${procedurePath(at.base, path, node.http)}`,
-				method: httpMethodOf(node.http, node.type, node.output),
-				type: node.type,
-				input: node.input,
-				output: node.output,
-			}, {
-				...at,
-				path,
-			})
-			: clientTree(node, { ...at, path }, make)
+		if (!isProcedure(node)) {
+			client[name] = clientTree(node, { ...at, path }, make)
+			continue
+		}
+		const id = `${at.mount}.${path}`
+		const made = make({
+			id,
+			url: `${at.origin}${procedurePath(at.base, path, node.http)}`,
+			method: httpMethodOf(node.http, node.type, node.output),
+			type: node.type,
+			input: node.input,
+			output: node.output,
+		}, {
+			...at,
+			path,
+		})
+		const action = altchaActionOf(node.admission, id)
+		if (action !== null && (typeof made === 'function' || (typeof made === 'object' && made !== null))) {
+			challengeUrls.set(made, `${at.origin}${challengePath(action)}`)
+		}
+		client[name] = made
 	}
 	const group = Object.freeze(client)
 	clientNodes.set(group, { mount: at.mount, path: at.path, procedure: null })

package/src/client/index.ts

@@ -2,6 +2,7 @@
 export { type PageCaller, parsePageCaller } from './caller'
 export {
 	type AttachmentProcedure,
+	challengeUrl,
 	type ClientMount,
 	type ClientOptions,
 	type ClientTree,

package/src/contract/artifact-schema.ts

@@ -26,9 +26,18 @@ import {
 	type TablePolicyArtifact,
 	type TupleShape,
 } from '@fabrika/auth-core'
-import { isPolicyOrigin } from '@fabrika/proxy-core/headers'
+import { isPolicyOrigin, WORKER_BLOB_SOURCE } from '@fabrika/proxy-core/headers'
 import { z } from 'zod/v4'
-import { CHALLENGE_ACTION, JOB_LIMITS, PROCEDURE_LIMITS } from './defaults'
+import {
+	ALTCHA_LIMITS,
+	altchaSolvable,
+	CHALLENGE_ACTION,
+	CHALLENGE_PREFIX,
+	challengePath,
+	challengeRowId,
+	JOB_LIMITS,
+	PROCEDURE_LIMITS,
+} from './defaults'
 import { TOKEN_MAX_DAYS } from './token'
 import { webhookSchemeSchema } from './webhook-scheme'
 
@@ -186,6 +195,19 @@ const endpointRow: z.ZodType<EndpointRow> = z.union([
 		crossOrigin: z.enum(['environment', 'any']).optional(),
 		cache: endpointCacheSchema.optional(),
 	}).refine((row) => row.cache === undefined || row.method === 'GET', 'only a GET answer is cached'),
+	// The framework's own GET that issues the ALTCHA challenge of the public procedure its source names: no body, no schemas.
+	z.strictObject({
+		...rowBase,
+		kind: z.literal('public'),
+		source: z.strictObject({ kind: z.literal('challenge'), name }),
+		method: z.literal('GET'),
+		admission: z.null(),
+		input: z.null(),
+		output: z.null(),
+		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({
 		...rowBase,
@@ -219,7 +241,17 @@ const formRate = z.int().positive().max(10_000)
 const applicationVariable = z.string().regex(/^[A-Z][A-Z0-9_]*$/)
 const bucket = z.int().positive().max(PROCEDURE_LIMITS.maxPerMinute).nullable()
 const challenge = z.strictObject({ provider: z.literal('turnstile'), secret: applicationVariable, siteKey: applicationVariable.optional() })
-const procedureChallenge = challenge.extend({ action: z.string().regex(CHALLENGE_ACTION) })
+const challengeActionSchema = z.string().regex(CHALLENGE_ACTION)
+const procedureChallenge = z.discriminatedUnion('provider', [
+	challenge.extend({ action: challengeActionSchema }),
+	z.strictObject({
+		provider: z.literal('altcha'),
+		secret: applicationVariable,
+		action: challengeActionSchema,
+		cost: z.int().min(ALTCHA_LIMITS.minCost).max(ALTCHA_LIMITS.maxCost),
+		maxAgeMs: z.int().min(ALTCHA_LIMITS.minMaxAgeMs).max(ALTCHA_LIMITS.maxMaxAgeMs),
+	}).refine((challenge) => altchaSolvable(challenge.cost, challenge.maxAgeMs), 'a slow phone does not solve this challenge in time'),
+])
 
 const mount = z.discriminatedUnion('kind', [
 	z.strictObject({ kind: z.literal('rpc'), prefix: name, callers: z.array(rpcCaller), compatibility: z.literal('backward').optional() }),
@@ -350,6 +382,7 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 		frameSrc: z.array(cspSource).nonempty().optional(),
 		styleSrc: z.array(cspSource).nonempty().optional(),
 		fontSrc: z.array(cspSource).nonempty().optional(),
+		workerSrc: z.tuple([z.strictObject({ origin: z.literal(WORKER_BLOB_SOURCE), purpose: z.string().min(1) })]).optional(),
 	}),
 	tables: record(tablePolicy),
 	endpoints: z.array(endpointRow).superRefine((rows, context) => {
@@ -407,10 +440,36 @@ export const contractArtifactSchema: z.ZodType<ContractArtifact> = z.strictObjec
 	tokens: record(z.strictObject({ claims: schemaShapeSchema, maxDays: z.int().positive().max(TOKEN_MAX_DAYS) })).optional(),
 }).superRefine((artifact, context) => {
 	for (const row of artifact.endpoints) {
-		if (row.kind === 'public' && artifact.declared?.[row.id]?.actions === undefined) {
+		if (row.kind === 'public' && row.source.kind !== 'challenge' && artifact.declared?.[row.id]?.actions === undefined) {
 			context.addIssue({ code: 'custom', path: ['declared', row.id], message: 'a public procedure declares its workload actions' })
 		}
 	}
+	// Every ALTCHA challenge has exactly its own issuer, under its action, from the procedure's origins, with its own buckets.
+	const rows = new Map(artifact.endpoints.map((row) => [row.id, row]))
+	const issuers = artifact.endpoints.filter((row) => row.source.kind === 'challenge')
+	for (const [id, rules] of Object.entries(artifact.procedures ?? {})) {
+		if (rules.challenge?.provider !== 'altcha') continue
+		const issuer = rows.get(challengeRowId(id))
+		const procedure = rows.get(id)
+		if (
+			issuer === undefined || procedure === undefined || issuer.source.kind !== 'challenge' || issuer.source.name !== id
+			|| issuer.path !== challengePath(rules.challenge.action) || issuer.crossOrigin !== procedure.crossOrigin
+			|| artifact.procedures?.[issuer.id]?.challenge !== null
+		) {
+			context.addIssue({ code: 'custom', path: ['procedures', id, 'challenge'], message: 'an ALTCHA challenge has its own issuer row' })
+		}
+	}
+	for (const issuer of issuers) {
+		if (issuer.id !== challengeRowId(issuer.source.name) || artifact.procedures?.[issuer.source.name]?.challenge?.provider !== 'altcha') {
+			context.addIssue({ code: 'custom', path: ['endpoints'], message: `'${issuer.id}' issues the challenge of no ALTCHA procedure` })
+		}
+	}
+	if (issuers.length > 0 && !artifact.reservedPrefixes.includes(CHALLENGE_PREFIX)) {
+		context.addIssue({ code: 'custom', path: ['reservedPrefixes'], message: `an issuer row reserves ${CHALLENGE_PREFIX}` })
+	}
+	if ((artifact.csp.workerSrc !== undefined) !== issuers.length > 0) {
+		context.addIssue({ code: 'custom', path: ['csp', 'workerSrc'], message: 'workerSrc admits the workers of an ALTCHA challenge, and only those' })
+	}
 })
 
 function mailLocales(kind: MessageKind) {