@marktiderman/genesis-forms 0.8.0 → 0.9.0

package/README.md

@@ -78,7 +78,8 @@ const version = eventFeedback.hash();         // content fingerprint for publish
 | `parseForm(json)` | Check a stored or built definition: structure, text fields, references, operators, recall. Never throws. |
 | `createForm(def)` | The engine: values, visibility, path, Next/Back with history, validation, submit, an event log. Framework-agnostic `subscribe` / `getState`. |
 | `replay(def, events)` | Rebuild a response from its event log. |
-| `registerFieldType` | Add a field type. Non-JSON values must provide `serialize` and `deserialize`; `normalize` sets the stored form (email trims). A field whose type is not registered accepts no answer. |
+| `registerFieldType`, `registerContentType` | Add a field or content kind: one definition the engine, `parseForm`, validation, the server and snapshots all read. See [Kinds](#kinds-the-content-type-registry). A field whose type is not registered accepts no answer. |
+| `mergeResponses(def, base, patch)` | A saved draft plus what changed since, as the answers to store: for resuming and partial saves. See [Merging partial responses](#merging-partial-responses). |
 | `coerceHidden(def, raw, { sources })` | Type hidden inputs by their declarations; reports dropped names in `ignored`. |
 | `isFormEvent(value)` | Guard for one well-formed event-log entry. |
 | `isSensitive(block)` | `sensitive: true` on a field, or the `props.sensitive` alias. Hidden inputs take `sensitive: true` too (`f.hidden.string({ source: "server", sensitive: true })`); devtools masks both. |
@@ -362,6 +363,65 @@ one such value per question, not blank and at most `OTHER_MAX_LENGTH` (200) char
 a question with `other`. `otherOption(field)` reads the setting; `isOtherValue(field, value)` tells a
 typed answer from an option.
 
+### Kinds: the content-type registry
+
+Every field kind (`short-text`, `single-choice`, `photo`…) and content kind (`heading`, `text`) is
+one registered definition. Nothing else in the package switches on a type name, so a host's own
+kind gets everything a built-in gets:
+
+| Member | What reads it |
+| --- | --- |
+| `checkProps(props, check)` | `parseForm`: the kind's settings, reported at `blocks[i].props.<path>`. `check` has `issue`, `text`, `optionalText`, `optionalBoolean`, `optionalInt`, `ordered` and `name`. |
+| `choice: { multiple }` | The answer shape: one option (a text) or several (a list). A choice kind takes `options`, `optionsFrom` (with filters), `prefill`, `other`, search, and snapshots, like `single-choice` and `multi-choice`. |
+| `literal` | `parseForm`'s warning about a logic literal that can never match: `"string"`, `"number"`, `"boolean"`, or a function of the props. |
+| `validate(value, field)` | The engine and `validateSubmission`. A validator that throws refuses the answer with `VALIDATOR_FAILED_MESSAGE`. |
+| `isEmpty`, `normalize`, `summarize` | The empty check, the stored form, the display text (recall, exports, emails). |
+| `snapshot`, `fromSnapshot` | `answerSnapshots` and `answersFromSnapshots` for a kind that isn't a choice. |
+| `samples` | `coverage()` and the other test tools. |
+
+```ts
+import { registerFieldType, registerContentType } from "@marktiderman/genesis-forms";
+
+registerFieldType({
+  type: "acme/cards", label: "Cards", category: "choice", value: { json: true },
+  operators: ["eq", "neq", "answered", "empty"], a11y: { semantics: "group" },
+  choice: { multiple: false }, literal: "string",
+  checkProps: (props, check) => check.optionalInt(props.columns, "columns", 1),
+});
+registerContentType({ type: "acme/message", label: "Message", text: (block) => block.text });
+```
+
+The registry is shared by every form in the process (the server's checks too), so:
+
+- a built-in kind's name is refused unless you pass `{ replace: true }`;
+- what you register is stored as a frozen copy: changing your object, or what `getFieldType`
+  returns, changes nothing;
+- a choice kind without its own `validate` gets the built-in check for its shape, so its answers
+  are always one of its options (or a typed "Other");
+- a `validate` that throws refuses the answer, a `checkProps` that throws is one issue, and a
+  throwing `literal`, `snapshot` or `fromSnapshot` is skipped; `isEmpty`, `normalize` and
+  `summarize` must not throw;
+- an unknown content kind's issue names every registered kind, so registering one changes that
+  message for every form ("Must be heading, text or acme/message.").
+
+A content block carries `text` and, for a host's kind, `props`. `contentText(block)` is its display
+text. A renderer draws a content kind it doesn't know as that text.
+
+### Merging partial responses
+
+`mergeResponses(definition, base, patch, { hidden?, hostOptions?, offPath? })` lays `patch` over
+`base` (both answers by field id) and returns the answers to store, in the form's order:
+
+1. a field in `patch` takes its value; `null` clears it;
+2. unknown ids, `calculated` fields (worked out again) and, on an anonymous form, identifying
+   fields are dropped; so are empty answers;
+3. a pick a filtered list no longer shows is dropped, whichever side changed;
+4. answers on a path the merged answers no longer take (hidden by logic, jumped over) are
+   **dropped**, unless `offPath: "keep"`. The default follows the form: kept only with
+   `settings.clearHiddenValues: false`, as `validateSubmission` keeps them.
+
+It checks nothing else: pass the result to `validateSubmission` or `createForm`'s `initialValues`.
+
 ### Props for the host
 
 Props a field type doesn't use are kept and ignored: the engine, `parseForm` and
@@ -416,9 +476,21 @@ stored response's answers onto a newer version of the form by field key, for the
 
 ### Rate limits
 
-The submit endpoint's limit, without the counter: `clientIp(headers, trusted?)` reads the first
-trusted proxy header (`DEFAULT_TRUSTED_IP_HEADERS`: `x-vercel-forwarded-for`, `x-forwarded-for`,
-`x-real-ip`; trust only headers your proxy overwrites), `addressPrefix` keeps an IPv4 address whole
+The submit endpoint's limit, without the counter: `clientIp(headers, options?)` reads the first
+trusted platform header (`DEFAULT_TRUSTED_IP_HEADERS`: `x-vercel-forwarded-for` and
+`cf-connecting-ip`, which Vercel and Cloudflare set themselves). `x-forwarded-for` is not read by
+default: its leftmost entries are whatever the client sent, so only the entry your own proxy
+appended can be trusted. Behind your own proxies, opt in with `forwardedForHops`, the number of
+proxies that each append an address, and `clientIp` takes the entry that many places from the
+right (1: the rightmost); pass `headers: []` as well, since off Vercel or Cloudflare a client can
+send those headers itself. A list of header names on its own also works as the second argument.
+
+```ts
+clientIp(request.headers); // on Vercel or behind Cloudflare
+clientIp(request.headers, { headers: [], forwardedForHops: 1 }); // behind one load balancer you run
+```
+
+`addressPrefix` keeps an IPv4 address whole
 and an IPv6 one by its /64, and `rateLimitKey({ kind, scope, ip, secret })` is
 `<kind>:<scope>:<hex HMAC-SHA256 of the prefix>`, so the address is never stored. The app's
 `RateLimitStore.hit(key, limit, windowSeconds)` counts (shared by every instance); `allow` fails
@@ -488,6 +560,214 @@ The request is `{ fieldId, name, type, size }` plus `attemptId` or `edit`. `atte
 is the hex SHA-256 the store keeps for the attempt. `messages` overrides any of the words
 (`UPLOAD_MESSAGES`). genesis-forms-web's `signedUploadHost` is the browser half.
 
+### Submitting: `submitResponse`
+
+The one call a submit endpoint makes. It checks the submission again (`validateSubmission`, then
+`checkUploads`), snapshots the options picked (`answerSnapshots`) and hands one record to the app's
+store, keyed by the device's idempotency key, so a retry never stores a second response. No HTTP and
+no delivery: the endpoint, the store and the destinations' outbox are the app's. Edits to a stored response and progress saves are out of scope: it takes a finished submission only.
+
+```ts
+import { submitResponse, type SubmissionStore } from "@marktiderman/genesis-forms/server";
+
+const result = await submitResponse(await request.json(), {
+  definition: published, // loaded by the server
+  hostOptions: { locations: await locationsFor(practice) }, // loaded afresh, never from the client
+  context: { member: memberId }, // server inputs
+  store, // SubmissionStore
+  formId: form.id, // how the store keys it; default definition.id
+  version: form.publishedVersion, // stored as definitionVersion; default fingerprint(definition)
+  open: form.acceptingResponses, // false answers "closed"
+  rateLimit: async () => allow(counter, { key: await rateLimitKey({ kind: "submit", scope: practice, ip, secret }), ...RATE_LIMIT_DEFAULTS.submit }),
+  uploads: { store: uploadStore }, // needed when the form has upload fields; the owner is the request's attemptId
+});
+return Response.json(result, { status: result.ok ? 201 : 200 });
+```
+
+Answer `duplicate` as a success: the response is already stored, so the device must clear it from its outbox, not retry it. The outbox treats `ok: true` and `reason: "duplicate"` alike.
+
+The contract, which the client outbox and the server side are both built against:
+
+```ts
+function submitResponse(input: SubmitRequest, options: SubmitResponseOptions): Promise<SubmitResult>;
+
+interface SubmitRequest extends SubmissionInput { // answers | events, hidden
+  idempotencyKey: string; // made once on the device (a UUID); /^[A-Za-z0-9_-]{16,128}$/
+  clientSubmittedAt?: number; // the device's clock, untrusted
+  attemptId?: string; // the visit's attempt, for upload fields
+}
+
+type SubmitResult =
+  | { ok: true; id: string; receivedAt: string }
+  | { ok: false; reason: "duplicate"; id: string; receivedAt: string }
+  | { ok: false; reason: "invalid"; errors: Record<string, string> }
+  | { ok: false; reason: "conflict" }
+  | { ok: false; reason: "closed" }
+  | { ok: false; reason: "rate_limited"; retryAfterSeconds?: number }
+  | { ok: false; reason: "store_failed" };
+
+interface SubmissionStore {
+  find(formId: string, idempotencyKey: string): Promise<StoredSubmissionRef | null>;
+  save(record: SubmissionRecord): Promise<{ id: string } | { duplicate: StoredSubmissionRef }>;
+}
+interface StoredSubmissionRef { id: string; receivedAt: string; inputHash: string }
+```
+
+The checks run in this order: the idempotency key, `store.find` (a response already stored under
+it), `open`, `rateLimit`, `validateSubmission` (always complete; drafts are never submitted), the
+uploads named, then `store.save`.
+
+| Result | Meaning | The device |
+|---|---|---|
+| `ok: true` | Stored now, as `id`. Queue its deliveries. | Drops it from the outbox. |
+| `duplicate` | Already stored under this key with these answers, as `id`. Deliver nothing again. | Drops it: the earlier try went through. |
+| `invalid` | `errors` keyed by field id, `""` for the whole: a failed check, or a malformed body or key. | Keeps it as failed, for the respondent to fix or discard. |
+| `conflict` | A response is stored under this key with other answers (the hashes differ). | Keeps it as failed. |
+| `closed` | `open: false`. | Keeps it as failed. |
+| `rate_limited` | `rateLimit` answered false, or `{ retryAfterSeconds }` (sent back, rounded up). A throw lets it on (fails open) and is logged. | Retries later, no sooner than `retryAfterSeconds`. |
+| `store_failed` | `find`, `save` or the upload store threw, `save` answered no id, or a duplicate came back without its id, time or hash. The cause is logged, without answers. | Retries later. |
+
+More reasons may be added; a device treats one it doesn't know as a retry, so it keeps the submission.
+
+Answer every result as JSON with whatever status code suits (the outbox reads the body, not the
+status). `submitResponse` throws only for the server's own mistakes: a published definition that
+doesn't parse, or a form with upload fields and no `uploads`; answer those 500 and the device retries.
+
+The store's side:
+
+- **One response per `formId` and `idempotencyKey`.** Put a unique index on the pair. `find` reads
+  the row under a key (it is asked first, so a retry of a response that went through is answered
+  `duplicate` even after the form closed, the client is rate limited, the definition changed or its
+  uploads were taken). When `save`'s insert hits the index anyway (two retries raced), read that row
+  and answer `{ duplicate: { id, receivedAt, inputHash } }`.
+- **Keep `inputHash`.** It is the hex SHA-256 of the answers, events and hidden inputs as sent. A
+  duplicate is answered `duplicate` only when the hashes match; a key reused for other answers is
+  `conflict`, never taken as delivered. A ref without its hash is answered `store_failed`.
+- **Mark `uploadIds` taken by the response** in the same transaction (the checked ids of the files
+  the answers name), so they aren't purged as abandoned.
+- **Save and queue deliveries in one transaction**, so a stored response is always delivered. For a
+  destination, `{ id, answers, hidden, context, ending, submittedAt: receivedAt }` is a
+  `DeliverySubmission`.
+
+`SubmissionRecord` holds `formId`, `idempotencyKey`, `inputHash`, `definitionVersion`, `receivedAt`
+(ISO), `clientSubmittedAt` (ISO or null, untrusted), the checked `answers` (uploads as stored,
+calculated fields worked out here), `hidden`, `context`, `ending`, `ignored`, `snapshots` and
+`uploadIds`.
+
+## Drafts and the offline outbox
+
+Both run on the device, in the browser and in React Native, and keep their data in a
+`KeyValueStorage`: `{ getItem, setItem, removeItem }`, each answering at once or with a promise.
+`localStorage` is one (`webStorage()` looks it up on each call, so server rendering is safe), React
+Native's AsyncStorage is one, and MMKV takes three lines:
+
+```ts
+const storage: KeyValueStorage = {
+  getItem: (key) => mmkv.getString(key) ?? null,
+  setItem: (key, value) => mmkv.set(key, value),
+  removeItem: (key) => mmkv.delete(key),
+};
+```
+
+`memoryStorage()` keeps nothing past the page or app, for tests.
+
+### Drafts
+
+```ts
+import { createDraftStore, webStorage } from "@marktiderman/genesis-forms";
+import { useFormDraft } from "@marktiderman/genesis-forms-react";
+
+const drafts = createDraftStore(webStorage()); // or AsyncStorage, MMKV
+const { engine, draft, savedAt, clear } = useFormDraft(definition, { store: drafts, respondent: sessionId });
+```
+
+`useFormDraft` is `useForm` with a draft: the saved answers are put back when the form opens, at
+the furthest question reached (`resumeAt`), saved again 800 ms after each change (`delayMs`), and
+flushed when the page is hidden or the component unmounts. With a store that answers at once the
+engine is ready on the first render; with an async one `engine` is null until the draft is read.
+`draft` says what happened: `restored`, `discarded`, `none`, `error` (it couldn't be read: the form
+starts empty, and the stored draft is left alone until the respondent answers something) or
+`loading`. In React Native, call `flush()` from an `AppState` listener when the app goes to the
+background; on the web the hook flushes on `pagehide` and when the page is hidden.
+
+- A draft is keyed by form and respondent (a user id, or a session id made once on the device).
+  `version` (default `fingerprint(definition)`) is stored inside it. At the same version it is put
+  back as it is. At another version it is put back only when every answer still fits (the question
+  is there, of the same type, and the answer passes its format checks); otherwise the whole draft is
+  removed, never half put back (`restoreDraft`, reason `version`). Drafts older than 30 days
+  (`maxAgeMs`) are removed too (`expired`).
+- Sensitive answers (`isSensitive`) are left out unless `keepSensitive: true`, so they never sit in
+  the device's storage; calculated fields and withheld identifying ones are never saved.
+- Answers cleared to nothing remove the draft (one that was restored, or one this visit saved). A
+  save that fails goes to `onError` (default `console.warn`); autosave never throws.
+- Call `clear()` only once the submission is safe: after `outbox.enqueue` resolved.
+
+Without React: `createDraftAutosave(engine, store, key, options)` (with `flush`, `clear`,
+`dispose`), `draftOf(engine, key)` and `restoreDraft(definition, draft, { version })`.
+
+### The outbox
+
+```ts
+import { createSubmitOutbox, webStorage } from "@marktiderman/genesis-forms";
+import { useSubmitOutbox } from "@marktiderman/genesis-forms-react";
+
+// Once, for the whole app.
+export const outbox = createSubmitOutbox({
+  storage: webStorage(),
+  send: async (item, { signal }) => {
+    const res = await fetch(`/api/forms/${item.formId}/submit`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(item.request),
+      signal,
+    });
+    return res.json(); // the SubmitResult, whatever the status
+  },
+});
+
+// On submit: queue it, then clear the draft.
+if (engine.submit()) {
+  await outbox.enqueue({ formId, submission: { events: engine.getState().events }, attemptId });
+  await clear();
+}
+
+// Or with useFormController: the same thing as its onSubmit. It resolves once the submission
+// is stored on the device, so the ending shows offline; a storage failure sets phase "failed".
+const controller = useFormController(engine, { onSubmit: outboxSubmit(outbox, { formId, attemptId, clearDraft: clear }) });
+
+// Anywhere: what's waiting.
+const { pending, failed, items, online } = useSubmitOutbox(outbox);
+```
+
+- `enqueue` resolves once the submission is in storage, with a new idempotency key (or the one
+  passed: the same key twice queues it once). It rejects when storage can't take it; keep the draft
+  then and tell the respondent.
+- It sends when online, oldest first and one at a time, and backs off between tries (about 2 s,
+  doubling to 15 min, with jitter; `backoff`), the same body and key every time. Coming online sends
+  what's pending at once. `useSubmitOutbox` follows the browser's `online` and `offline` events; in
+  React Native pass `trackOnline: false` and call `outbox.setOnline` from NetInfo.
+- `send` answers the endpoint's `SubmitResult` (`submitOutcome` maps it). `ok` and `duplicate` are
+  delivered and removed (`onDelivered`). `invalid` and `closed` keep it as `failed` with the server's
+  `rejection`. Anything else (a throw, a timeout after 30 s, `rate_limited`, `store_failed`, a body
+  that isn't a `SubmitResult`) is tried again, up to 10 tries (`maxAttempts`), then kept as `failed`.
+  Nothing is dropped silently: a failed submission stays, in storage too, until `retry(id)` or
+  `discard(id)`. One that ran out of tries (not one the server refused) starts again from its first
+  try each time the outbox starts and each time the device comes back online. A `rate_limited`
+  answer's `retryAfterSeconds` is waited out.
+- To let the respondent fix a refused submission, open the form from `item.request` (`replay` its
+  `events`, or `initialValues` from its `answers`), `discard` the old one and `enqueue` the corrected
+  one: it gets a new key.
+- `discard` takes it out of the queue at once: no send starts after it is called.
+- The outbox holds the whole submission, sensitive answers too, in the device's storage until the
+  server has it. Pick the storage with that in mind (MMKV with encryption, say).
+- It is kept across restarts: each submission under its own key and an index beside it. The index
+  is changed one outbox at a time (in one JS context, and across tabs where Web Locks exist), and
+  each change writes back every submission that outbox holds, so two tabs on one storage keep each
+  other's. Both may send one; its key makes the server store it once. An entry that can't be read is
+  logged, listed in `unreadable` and left in storage.
+- Where there is no `crypto.randomUUID` (React Native without a polyfill) pass `createKey`
+  (expo-crypto's `randomUUID`); `createSubmitOutbox` throws without one.
+
 ## Destinations
 
 `@marktiderman/genesis-forms/destinations` sends a checked submission somewhere. No dependencies:
@@ -557,7 +837,7 @@ submission. On an anonymous form identifying fields get no column. `sensitive` f
 | --- | --- | --- |
 | `emailDestination({ provider, from, replyTo?, render?, sensitive? })` | `{ to: string \| string[], subject? }` | HTML and plain text from the definition (`renderEmail`), every value HTML-escaped. Subject, From, To and Reply-To are stripped of line breaks or refused, so no answer can add a header. At most 50 recipients. Sensitive fields masked by default. The idempotency key is the delivery id plus a hash of the recipients. `resendProvider({ apiKey })` is built in; any `EmailProvider` works. `render` and `emailBody(lines)` let an app write its own content and keep the escaping. |
 | `sheetsDestination({ account \| accessToken, escapeFormulas?, sensitive? })` | `{ spreadsheetId, sheetName? }` | Signs in with a service account (`account`) or with an access token the app supplies (`accessToken(config, { destinationId })`, for a sheet a person connected with Google sign-in: see `googleOAuthAccessToken`). Service-account JWT signed with WebCrypto (RS256), token cached per process. Creates the tab, writes and freezes the header, adds a column for a new key without moving others, appends with `valueInputOption=RAW`, so Sheets stores text exactly as typed and never runs it as a formula (`@team thanks` stays `@team thanks`). No `'` is added by default, since RAW would store it literally; `escapeFormulas: true` adds one (headers included) for a sheet that is exported and opened elsewhere. `escapeFormula(cell)` is the same opt-in guard for CSV you write yourself: text starting with `=`, `@`, tab or CR, or with `+`/`-` followed by anything but number punctuation, gets a leading `'`. Keeps the tab, header and last row in `state`, so a normal delivery is one request. On `redelivery`, skips ids already in the last 500 rows. On `update` (an edit), reads the id column and overwrites the response's row where it is, appending only when the row is gone. A 403/404 says to share the sheet with the service account (or, with `accessToken`, that it is no longer connected). |
-| `webhookDestination({ secret, url?, resolveHost?, allowInsecureUrls?, allowPrivateHosts?, sensitive? })` | `{ url }` | [Standard Webhooks](https://www.standardwebhooks.com): `webhook-id`, `webhook-timestamp`, `webhook-signature: v1,<HMAC-SHA256>`. The secret is base64 (at least 16 bytes decoded), usually `whsec_`-prefixed; as in every Standard Webhooks library the prefix is optional and the rest is always base64-decoded, so receivers verify with the same string. A secret that is not padded standard base64 (a raw passphrase, say) fails permanently rather than signing deliveries no receiver could verify. Generate one with `newWebhookSecret()`. Body `{ type: "form.submitted", timestamp, data: { form, submission, row } }` (`form.updated` on `update`). `url(config, { destinationId })` looks the address up when it is kept out of config. https only, no URL credentials, no localhost or private, loopback or link-local address literals, redirects not followed. Pass `resolveHost` to also refuse a hostname that resolves to a non-public address (checked before every request; see below). Without it, such a hostname is not caught; either way, if untrusted users pick URLs, send from a network that cannot reach internal services. Receivers check with `verifyWebhook({ secret, headers, body })` (constant-time, five-minute tolerance). |
+| `webhookDestination({ secret, url?, resolveHost?, allowInsecureUrls?, allowPrivateHosts?, sensitive? })` | `{ url }` | [Standard Webhooks](https://www.standardwebhooks.com): `webhook-id`, `webhook-timestamp`, `webhook-signature: v1,<HMAC-SHA256>`. The secret is base64 (at least 24 bytes decoded, `MIN_WEBHOOK_SECRET_BYTES`, as the spec recommends), usually `whsec_`-prefixed; as in every Standard Webhooks library the prefix is optional and the rest is always base64-decoded, so receivers verify with the same string. A secret that is not padded standard base64 (a raw passphrase, say) fails permanently rather than signing deliveries no receiver could verify. Generate one with `newWebhookSecret()` (32 bytes). To rotate without downtime, pass `secret` as an array (new and old, or a resolver returning one): every delivery is signed with each, space-separated in `webhook-signature`, so the receiver verifies with either until it drops the old one. Body `{ type: "form.submitted", timestamp, data: { form, submission, row } }` (`form.updated` on `update`); `timestamp` is when the event happened (the submission's `submittedAt`, else the send time), while the `webhook-timestamp` header is the send time. A 410 Gone fails permanently with `disable: true`, the receiver asking to be switched off; the runner passes it on as `disable: true` on the `failed` outcome, so the app can disable the destination. `url(config, { destinationId })` looks the address up when it is kept out of config. https only, no URL credentials, no localhost or private, loopback or link-local address literals, redirects not followed. Pass `resolveHost` to also refuse a hostname that resolves to a non-public address (checked before every request; see below). Without it, such a hostname is not caught; either way, if untrusted users pick URLs, send through an egress proxy that refuses internal addresses (see below). Receivers check with `verifyWebhook({ secret, headers, body })` (constant-time, five-minute tolerance; `secret` may be an array during a rotation). |
 | `slackDestination({ url?, resolveHost?, message? })` | `{ url }` | One message per submission to a Slack incoming webhook (`https://hooks.slack.com/services/…` only; anything else fails permanently). The heading (`New response: <title>`, `Updated response` on `update`), each answer as `label: value` in form order, then a link back or the response id. Every value is escaped (`escapeSlack`), so typed text can't mention `@channel` or make a link; answers over 1,500 characters are cut. Sensitive fields masked by default. `message(input)` sets the heading, extra lines, a link and fields to `omit` per delivery; `slackMessage(submission, definition, options)` builds the same text on its own. The URL is the credential, so `url(config, { destinationId })` can look it up. |
 
 ### Sending by answer
@@ -581,8 +861,11 @@ destinations) resolves the name and refuses it unless every address is public by
 benchmarking, multicast, IPv4-mapped, NAT64, 6to4 and Teredo ranges. A lookup that fails is
 retryable; a private address is not. In Node, `resolveHost` can be
 `(host) => dns.promises.lookup(host, { all: true }).then((a) => a.map((x) => x.address))`. The
-name is checked and then fetched, so a name re-pointed in between (DNS rebinding) is not caught:
-where untrusted people choose URLs, also send from a network that cannot reach internal services.
+name is checked and then fetched, so a name re-pointed in between (DNS rebinding) is not caught,
+and no check made before `fetch` can close that gap. Where untrusted people choose URLs, send
+through an egress proxy that resolves the name itself and refuses internal addresses at connect
+time (Smokescreen, say, or a host's own outbound proxy), passing a `fetch` that goes through it,
+or from a network that cannot reach internal services at all.
 
 ### Google sign-in for sheets
 
@@ -604,7 +887,11 @@ sheetsDestination({
 Webhook and Slack URLs, signing secrets and refresh tokens should not sit in config. The helpers
 seal them for whatever store the app uses: `deriveSecretKey(appKey, purpose)` derives an AES-256-GCM
 key from a 32-byte app secret (base64 or base64url, as `openssl rand -base64 32` prints) with
-HKDF-SHA-256, one key per purpose; `sealSecret(key, plaintext, aad)` gives `v1.<iv>.<ciphertext>`
+HKDF-SHA-256, one key per purpose. `deriveSecretKey(appKey, purpose, { salt })` takes an HKDF salt
+(bytes, or text as UTF-8); it defaults to empty, which every key derived before the option used,
+so leave it out to keep opening what is already sealed. For a new app, a fixed app-wide random salt
+(32 random bytes kept as config) is recommended; it need not be secret but must never change once
+anything is sealed with it. `sealSecret(key, plaintext, aad)` gives `v1.<iv>.<ciphertext>`
 (base64url), bound to `aad` (the row it belongs to), and `openSecret(key, sealed, aad)` opens it,
 failing permanently for another row, another purpose or a rotated key.
 
@@ -640,8 +927,10 @@ match `config.when`), `skipped` (the destination returned `notSent`, a deliberat
 cap; never retried), `retry` with `retryAt`, and `failed`. A retryable failure with the service's
 Retry-After is deferred without counting an attempt (`counted: false`), up to `maxDeferrals`
 (default 24, counted by the store in `ClaimedDelivery.deferrals`); any other retryable
-failure backs off by attempt (`defaultBackoff`: 1 minute doubling to 6 hours) until `maxAttempts`
-(default 8), then fails. Permanent failures and unknown kinds fail at once. A destination that
+failure backs off by attempt (`defaultBackoff`: 5 minutes, quadrupling, at most 24 hours, each
+wait jittered by ±20%; about 3 days across the default attempts, as Standard Webhooks suggests)
+until `maxAttempts` (default 8), then fails. A `failed` outcome with `disable: true` is a receiver
+asking to be switched off (a webhook's 410). Permanent failures and unknown kinds fail at once. A destination that
 throws is reduced to a safe message. `run` returns a `DeliveryReport` of counts, including `stale`
 (record resolved false) and `unrecorded` (record threw; the lease runs out and the row comes back).