@fabrika/app 0.6.0 → 0.8.0

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
 
@@ -356,10 +357,10 @@ export function EditTask(
 - `Form` shows its `error`: a summary on top, and each `fields[name]` under the `Field` of that `name`. `Field` gives
   its control the `name`, an `id`, its label and `aria-describedby`; the control needs nothing else. `Form` hands
   `onSubmit` the `FormData`: read the fields by name, and leave the checking to the procedure's schema.
-- A call that is no procedure — a file collection's `api.files.<name>.upload(owner, file)`, `list`, `download` —
-  runs through `useAction(async (input) => …)`, with the same state and error union; it refetches only what
+- A call that is no procedure of a client runs through `useAction(async (input) => …)`, with the same state and error union; it refetches only what
   `invalidates` names.
-- An attachment procedure (`output: attachment(…)`) downloads through `useDownload(api.reports.exportProject)`:
+- An attachment procedure (`output: attachment(…)`) or a file procedure (`output: file('<kind>')`) downloads through
+  `useDownload(api.reports.exportProject)`:
   `mutate(input)` saves the file and answers it, with the same state and error union. It runs on the provider's client,
   so a screen test downloads over the kit; never call `download(api.…)` of the module's client from a screen.
 
@@ -737,9 +738,9 @@ if (postgres !== null) {
 
 - `web/__tests__/dom.ts` comes first: imports run in order, and React reads `window` when it loads. `installDom` keeps
   Bun's `fetch`, `AbortController`, `URL`, `Blob`, `File`, `FormData` and its `ReadableStream`, `WritableStream` and
-  `TransformStream`, because the clients, the kit, a form's challenge, a form's file and a download run on them, and
+  `TransformStream`, because the clients, the kit, a challenge, a file field and a download run on them, and
   turns navigation off, so a download's link click leaves the page for the next test. A DOM registration of your own
-  keeps the same classes of Bun, or a form with a file fails in the kit. Run the tests with `bun test --isolate`, which
+  keeps the same classes of Bun, or an input with a file fails in the kit. Run the tests with `bun test --isolate`, which
   gives each file its own globals.
 - `await type('Title', 'report')` types into the control whose label (or `aria-label`) is `Title` as React reads a
   person typing; a select takes the option's value. `controlByLabel(label)` answers the control, and

package/skill/references/start.md

@@ -73,7 +73,8 @@ export default serve(contract, { database: null })
 - `defineApp(vocabulary)` declares no tables, so `serve` takes `database: null`, and only then. A handler has no
   `ctx.db`, `ctx.sql` or `unscoped` (a type error that names `defineApp(vocabulary, tables)`); it answers from the
   caller's grants (`ctx.within.values`, `ctx.principal`), the member directory, or a connector.
-- Forms, jobs and file collections keep their rows in tables, so an application gets them with its first table.
+- Jobs, queue tables, file columns and public procedures that record a row all need tables, so an application gets
+  them with its first table.
 
 ```ts fabrika.config.ts
 import { compileContract, schemaFromContract } from '@fabrika/app/contract'

package/skill/references/table-and-migration.md

@@ -149,7 +149,7 @@ INSERT INTO priorities (code, label, rank) VALUES ('low', 'Low', 1), ('normal',
 - Codegen types: `date` is a `YYYY-MM-DD` string; `timestamptz` reads a `Date` and takes a `Date` or a strict ISO 8601 string with `Z` or an offset;
   `int8` and `numeric` are strings; an enum is its literal union. JSON, `bytea`, arrays and domains are refused.
 - Plain SQL of the application's own schema only. Refused: another schema (`public.`, `app_…`), any `fabrika_*`
-  object (except a file collection's table, `references/files.md`), `GRANT`, roles, `CREATE EXTENSION`, `COPY`,
+  object (a file column references `fabrika_files (id)`, `references/files.md`), `GRANT`, roles, `CREATE EXTENSION`, `COPY`,
   `SET`, transaction control, `SECURITY DEFINER`, a domain, `serial` and sequences (use `GENERATED ALWAYS AS IDENTITY`),
   a function overload, and calls outside the reviewed built-ins.
 - Never edit, rename or delete a committed migration; add a new one. Change a schema by expand, switch, contract, and
@@ -223,6 +223,13 @@ export const tables = defineTables(vocabulary, columns)({
 		insert: ['row_count'],
 		createdBy: 'created_by',
 	},
+	task_attachments: {
+		scope: { child: 'tasks' },
+		actions: { read: 'tasks.read', insert: 'tasks.write', delete: 'tasks.write' },
+		insert: ['file'],
+		files: { file: 'attachments' },
+		createdBy: 'created_by',
+	},
 	priorities: {
 		scope: { reference: 'the priority codes; a migration changes them' },
 		actions: { read: 'tasks.read' },
@@ -244,7 +251,9 @@ export const tables = defineTables(vocabulary, columns)({
 - The key (`id`), the container column (`<container>_id`), a child's column (`<parent dimension>_id`) and the chain
   are derived. State `in: { column }` or `column` only off that convention.
 - `actions` maps `read`, `insert`, `update` and `delete` to vocabulary actions. `insert` and `update` list the columns
-  that those actions write; nothing else is writable.
+  that those actions write; nothing else is writable. Each operation names one action or a list, any of which allows
+  it: a table that staff and a public procedure both read names both (`read: ['crm.read', 'catalog.read']`). Never let
+  a role hold a public procedure's action to share a table: list the actions.
 - A dimension or child table may also list `appRead: ['<action>', …]`, actions besides `read` with which an `app: true`
   endpoint lists every row, read-only (an export, a bulk send), with the columns of that action, and
   `appCount: ['<action>', …]`, actions with which it only counts rows (`count({ where })`) and reads none, no aggregate
@@ -252,6 +261,19 @@ export const tables = defineTables(vocabulary, columns)({
 - `columns: { <column>: { read: '<action>' } }` hides a column from every capability of another action, in the data
   and in the types. `columns: { <column>: { write: '<action>' } }` lets only that action update the column (and that
   action updates nothing else); the column is then not in `update`.
+- `files: { <column>: '<kind>' }` makes a column a file column of a kind the contract declares (`c.files`):
+  `task_attachments.file` holds the files of a task (`references/files.md`). Its migration writes
+  `<column> UUID REFERENCES fabrika_files (id)` and an index the column leads; the checker's `file-column-migration`
+  refuses a file column without either.
+- `queue: { attempts: '<column>', due: '<column>', maxAttempts? }` makes the table a queue a job claims
+  (`references/jobs.md`). It needs `version` and an `update` action; `<due>` is a timestamp with a default of `now()`
+  that allows `null`, `<attempts>` an integer with a default of 0. The data layer writes both; an insert may set
+  `<due>`, never `<attempts>`.
+- `insert(values, { onConflict: { columns, do: 'nothing' | 'update' } })` writes idempotently (a webhook delivery, an
+  unsubscribe): `columns` must be a unique index the migrations create (`UNIQUE`, a primary key, or a
+  `CREATE UNIQUE INDEX` without `WHERE`), which the checker's `on-conflict-index` verifies. `'nothing'` needs the
+  insert action and answers `{ inserted: false }` on a conflict; `'update'` also needs the update action and writes
+  only the table's update columns.
 - A column has one write action. A state that two actions change is two columns: in `references/public-intake.md` the
   link holder's `candidates.verify` sets `verified_at`, HR's `candidates.review` sets `status`, and `logic.ts` derives
   the stage HR sees from both (`stageOf`).

package/skill/references/tests.md

@@ -9,7 +9,10 @@ longer writes. Commit them; never edit, format or import them (`generated-test-h
 - `src/__tests__/endpoint-access.test.ts`: every `on` and `in` endpoint refuses another scope's object (404 or 403);
   every `on` and `over` endpoint, and every `in` endpoint that declares `sql`, answers nothing of another scope; a
   caller with only an endpoint's write action, plus what IAM requires of it (below), reaches its own object (200). An
-  `app` or `creates` endpoint refuses a holder of its action in one scope only (403) and answers a global holder.
+  `app` or `creates` endpoint refuses a holder of its action in one scope only (403) and answers a global holder. An
+  endpoint of several `capabilities` adds a denied case per capability. A public procedure answers anyone without a
+  credential, or, behind a challenge, refuses a caller without a solved one. A file input is sent as a generated file
+  of its kind; a `GET` procedure's input goes in its URL.
 - Their kit stands in for IAM, as `testKit` does (below): it creates a scope, assigns or invites a member and issues a
   link under IAM's rules for the caller's grants. A repeated invitation answers the open one, `resend` restarts its
   7 days, and an organization's address is refused for an external role (`internal_mailbox`). So the caller of an endpoint with the dimension's `members.manage`
@@ -34,8 +37,8 @@ export const members = { 'api.tasks.assign': ['assignee'] }
 ```
 
 - `export const fixtures = { '<endpoint id>': { … } }` is an input for an endpoint whose schema the scaffold cannot
-  sample, such as a `regex` or a webhook's bind:
-  `{ 'webhooks.github.bind': { scope: 'acme', account: 'installation:1' } }`. The checker names each missing one,
+  sample, such as a `regex` (a webhook's account):
+  `{ 'api.integrations.connectGithub': { orgId: 'acme', account: 'installation:1' } }`. The checker names each missing one,
   and one of an endpoint that does not exist (`endpoint-fixture`). The access form's `from` field is
   replaced by the seeded scope.
 - `members['<endpoint id>']` lists the input fields that name a picked person the handler checks with
@@ -284,7 +287,7 @@ if (postgres !== null) {
 - `kit.runJob('<job>')` runs a cron job once and answers `{ status: 'succeeded', attempts }`. A job's `ctx.links`
   reaches the kit's stand-in IAM under the job's own key, so a job that declares `issues` issues and revokes links in a
   plain `testKit` and under `fabrika app dev`, as IAM allows it: for its declared mount only.
-- A form or a mutation that declares `then` starts its job in the background of the call. `kit.drain()` waits for
+- A mutation that kicks (`kicks`, `ctx.kick`) starts its job in the background of the call. `kit.drain()` waits for
   those runs, and `kit.runJob` first waits for them; every generated access case drains before it answers. The kicked
   run may start at once, so arm a fault before the call, never between the call and the run.
 - `kit.mail` is the stand-in for every job's mail transport (`MemoryEmailSender` of `@fabrika/app/testing`), so a test
@@ -297,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 form's 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/skill/references/webhooks-links-connectors.md

@@ -3,9 +3,10 @@
 Each of these lets someone in who is not a signed-in member of the scope. Ask the human before you add one, and say
 what it lets that caller do.
 
-## Webhooks (GitHub)
+## Webhooks
 
 ```ts src/github/endpoints.ts
+import { WebhookSecret } from '@fabrika/app/contract'
 import { z } from 'zod/v4'
 import { app } from '../app-kit'
 
@@ -27,19 +28,71 @@ export const github = app.webhook('/hooks/github', {
 			name: input.repository.full_name,
 		})
 	})
+
+const Connect = z.strictObject({
+	orgId: z.string(),
+	account: z.string().regex(/^(installation|repository):\d+$/),
+})
+
+/** Binds an org to a GitHub account: answers the secret and the URL once. */
+export const integrations = app.group({ callers: ['human'] }, (r) => ({
+	connectGithub: r.mutation({
+		input: Connect,
+		output: WebhookSecret,
+		access: { action: 'members.manage', on: 'org', from: 'orgId' },
+		binds: 'github',
+	})
+		.handle(({ input, ctx }) =>
+			ctx.webhooks('github').bind(ctx.target, input.account)
+		),
+}))
 ```
 
-- Mount it by name in the contract: `github,` beside `api`. It answers `POST /hooks/github/:bindingId`.
-- `boundTo` is a dimension with `members`. A holder of its `members.manage` binds an org to a GitHub account with the
-  generated `POST /api/webhooks.github.bind` (`{ scope, account: 'installation:<id>' | 'repository:<id>' }`), which
-  answers the secret and the URL once. The generated tests need a fixture for it (`references/tests.md`).
+- Mount it by name in the contract: `github,` beside `api`, and the group in `api`. It answers
+  `POST /hooks/github/:bindingId`.
+- A binding is made by a procedure that declares `binds: '<webhook>'` and calls `ctx.webhooks('<webhook>').bind(ref,
+  account)` with a capability on the bound value (`ctx.target`, an org here), in its transaction; `unbind(ref, id)`
+  removes one. A GitHub account is `installation:<id>` or `repository:<id>`. The answer carries the secret and the URL
+  once. The generated tests need a fixture for its input (`references/tests.md`).
 - The framework checks the signature, the account and the input (undeclared fields are dropped).
   `ctx.refs['<action>']` is a `Ref` of the bound org for each declared action.
-- It records the delivery key (a digest of the binding and the body) before the handler runs, and answers a body it
-  already ran in the last 30 days without running it again. A handler that throws commits nothing, and the key is
-  forgotten, so GitHub's redelivery runs it again from nothing. A process that dies after the record and before the
-  commit keeps the key and loses the delivery. So make every effect idempotent, and key an external effect after the
-  data work on `ctx.delivery.key`; never rely on exactly one run.
+- It claims the delivery key (a digest of the binding and the body) under a lease before the handler runs, marks it
+  complete in the handler's transaction, and answers a body it already ran in the last 30 days without running it
+  again. A handler that throws commits nothing, and a process that dies before the commit leaves the lease to expire,
+  so GitHub's redelivery runs it again from nothing. So make every effect idempotent, and key an external effect after
+  the data work on `ctx.delivery.key`; never rely on exactly one run.
+- An idempotent write needs no `sql`: `insert(values, { onConflict: { columns: ['<unique column>'], do: 'nothing' } })`
+  (or `do: 'update'`) on a unique index (`references/table-and-migration.md`).
+- **The verifier.** `scheme` is a preset or a shape the framework computes against the binding's secret; never verify
+  a signature yourself:
+
+  | `scheme`                                                                                                  | For                                                                      |
+  | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+  | `'github-sha256'`                                                                                         | GitHub; it also checks the account                                       |
+  | `'standard-webhooks'`                                                                                     | senders of the Standard Webhooks spec                                    |
+  | `'stripe'`                                                                                                | Stripe                                                                   |
+  | `'slack'`                                                                                                 | Slack events, slash commands and interactivity (JSON or a form)          |
+  | `'twilio'`                                                                                                | Twilio callbacks (a form, or JSON); signs the public URL                 |
+  | `{ hmac: { header, algorithm, encoding, prefix?, timestamp?, signed: 'body' \| 'timestamp.body', id? } }` | most other HMAC senders (Shopify, …)                                     |
+  | `{ basic: true }`                                                                                         | a sender that sends the secret as a Basic password (an inbound mail API) |
+  | `{ bearer: true }`                                                                                        | a sender that sends the secret as `Authorization: Bearer <secret>`       |
+
+  A signed timestamp must be within five minutes. Slack's URL check (`url_verification`) is answered for you. A form's
+  fields are the input, as strings or the scalars the schema reads.
+- **A secret the provider issues.** Stripe, Slack and Twilio show their signing secret only after you register the
+  URL. Bind first, show the URL, then take the provider's secret in a second mutation with the same `binds` and call
+  `ctx.webhooks('<webhook>').setSecret(capability, id, secret)`; until then deliveries are refused (401).
+  `setSecret` answers `false` when the value has no binding of that id. A `basic` or `bearer` secret never contains
+  `px_`: the proxy removes a platform key from every request.
+- **`boundTo: 'app'`** gives one binding for the whole application, for a provider with one endpoint per account
+  (Stripe). Its handler holds its `actions` application-wide, as a job does: `ctx.db.app('<action>')`. The procedure
+  that binds it takes an `app` capability: `access: { action, app: true }`, `binds`, and
+  `ctx.webhooks('<webhook>').bind(ctx.app, account)`.
+- `limits: { maxBytes?, timeoutMs? }`: the body is 1 MiB by default and at most 48 MiB; the handler runs 10 s by
+  default, at most 60 s. A webhook may declare `kicks`, `signs`, `egress`, `sql` and `unscoped`, and `ctx.files.put`
+  stores a file a provider sends (an inbound e-mail's attachment) for a file column: raise `limits.maxBytes` to the
+  mail you accept.
+- Not covered: a provider that validates its URL with a `GET`, or that needs a custom answer body.
 
 ## Share links
 
@@ -97,8 +150,8 @@ export const shared = app.link('/s', {
   that should work once records its use in the row: a `verify` sets `verified_at` once under `getForUpdate`, and a
   second call answers the same. IAM counts no uses.
 - A cron job may issue links too (`issues` on `app.cron`, `references/jobs.md`): a visitor without an account gets a
-  link by e-mail from a job that drains a form's inbox. `references/public-intake.md` is that recipe end to end, with
-  the files a link holder uploads (`link: true`, or `link: ['<mount>']` for some mounts only, `references/files.md`).
+  link by e-mail from a job that claims a public procedure's rows. `references/public-intake.md` is that recipe end to
+  end, with the files a link holder uploads through the link's own procedures (`references/files.md`).
 
 ## Connectors: another application's data
 

package/src/bun.ts

@@ -251,7 +251,7 @@ const STORAGE_VARIABLES = {
 } as const
 
 /**
- * The file collections' object storage (Zerops object storage, path-style), when the platform wrote its variables;
+ * The stored files' object storage (Zerops object storage, path-style), when the platform wrote its variables;
  * a partial set stops the boot. The credentials are never quoted in a message.
  */
 export function openFileStorage(framework: Readonly<Record<string, string>>): FileObjectStore | undefined {
@@ -394,6 +394,7 @@ async function startContractServer(
 		workloadTokens,
 		requireProxySecret: true,
 		localEmailProviders: LOCAL_EMAIL_PROVIDERS,
+		connections: databaseConnections(environment.framework[DATABASE_CONNECTIONS]) ?? DEFAULT_DATABASE_CONNECTIONS,
 		...(operationsFetch === undefined ? {} : { operationsFetch }),
 	})
 	// The work a request leaves running (a failure's report, a kicked run) is drained, within a bound, before the database closes.
@@ -464,7 +465,7 @@ export async function runContractJob(
 			workloadTokens,
 			requireProxySecret: true,
 			localEmailProviders: LOCAL_EMAIL_PROVIDERS,
-			// ClamAV on PATH, as the provider's build installs it for a `scan: true` collection; missing, the scan fails closed.
+			// ClamAV on PATH, as the provider's build installs it for a `scan: true` file kind; missing, the scan fails closed.
 			scanner: clamscanScanner(),
 		})
 			.jobs.run(name, options)