@marktiderman/genesis-forms 0.5.0 → 0.7.0

package/README.md

@@ -143,7 +143,7 @@ A `photo` field asks for up to a few photos, such as a picture of broken equipme
 returned, never the bytes: `PhotoRef[]`, each `{ id, name, type, size }`. The renderer uploads
 through the host (`onUpload` on genesis-forms-web's `Form`), so the engine and `validateSubmission`
 stay storage-agnostic; the host's server should check that every reference is a file it stored
-for this respondent and form before saving.
+for this respondent and form before saving (`checkUploads`, see [Uploads](#uploads)).
 
 | Prop | Default | Rule |
 | --- | --- | --- |
@@ -262,6 +262,91 @@ options only. Answers store the option's value; `summarizeValue` shows its label
 it. `parseForm` checks the shape of `optionsFrom`, and doesn't warn about rules comparing with
 values only the app knows.
 
+### Option details, filtered lists, search and links
+
+An option can carry more than its value and label, from the question's own `options` or the
+app's list:
+
+```ts
+{ value: "riverside", label: "Riverside Gym",
+  description: "12 Main St",                    // a muted line under the label
+  image: "https://cdn.example.com/riverside.png",      // a small picture; https only
+  attributes: { region: "north", coaches: ["ada", "sam"] } } // for filters and recall
+```
+
+`readOption` keeps each detail only when it is well formed and within `OPTION_LIMITS`
+(description 500 characters, image URL 2048 and `https://` only (`isHttpsUrl`), at most 20
+attributes, each a text or a list of up to 50 texts of 200 characters). `parseForm` reports a
+definition's malformed details; an app's list is read leniently (the bad detail is dropped).
+
+**Filtered by another answer.** `optionsFrom.filter` shows only the options whose attribute
+matches an earlier question's answer, such as coaches at the chosen location:
+
+```ts
+f.dropdown("location", { label: "Where?", optionsFrom: { source: "host", key: "locations" } });
+f.singleChoice("coach", {
+  label: "Who coached you?",
+  optionsFrom: { source: "host", key: "coaches", filter: { attribute: "location", field: "location" } },
+});
+// a coach: { value: "ada", label: "Ada", attributes: { location: ["riverside", "hilltop"] } }
+```
+
+`field` is the earlier question's key (`parseForm` checks it exists and comes first). An option
+matches when its attribute (a text or a list) shares a value with the answer (a text, or a
+multiple choice's list); one without the attribute never matches. Until that question is answered
+(or while it is off the path) every option shows. `visibleOptions(definition, field, values)`
+says what shows, `answersOnPath(state)` gives it the answers it should read, and React renderers
+use `useChoiceOptions` (genesis-forms-react). When the answer changes, the engine clears picks the
+filter no longer shows (`clearFilteredAnswers`, following on through filters of filters); a pick
+outside the filtered list is refused by the engine and by `validateSubmission`
+(`filteredChoiceError`).
+
+**Search.** `isSearchable(field, count)` says whether a renderer puts a search box over the
+options: `props.searchable` when it is true or false, else more than `SEARCHABLE_OPTION_COUNT`
+(10) options. `searchOptions(options, query)` is the match every renderer uses: every word of the
+query in the label, value or description, ignoring case and accents.
+
+**Preselect from a link.** `props.prefill: { param }` on a choice question takes a link's query
+parameter, such as `?location=hilltop`:
+
+```ts
+f.dropdown("location", { label: "Where?", optionsFrom: { source: "host", key: "locations" },
+  prefill: { param: "location", hideWhenPrefilled: true } });
+
+createForm(definition, { hostOptions: lists, linkParams: new URLSearchParams(location.search) });
+// or <Form hostOptions={lists} linkParams={new URLSearchParams(location.search)}>
+```
+
+`prefillFromLink(definition, params, values)` resolves it: the value is taken only when it is one
+of the options the question shows (a filtered list too), anything else is ignored; a multiple
+choice takes repeated parameters or one comma-separated value. The picks become `initialValues`
+(logged as `source: "prefill"` answers; the host's own `initialValues` win), so the server checks
+them like any answer. With `hideWhenPrefilled` the question is skipped while it holds the link's
+answer: `hiddenByPrefill(definition, state)` lists such questions, the engine's Next and Back step
+over them, and `respondentPath(definition, state)` is the path a renderer shows and counts. The
+answer is stored as usual. A parameter name is letters, digits, `_`, `-` and `.`, at most 64
+characters (`isPrefillParam`).
+
+**Snapshots of what was picked.** Store the option's label with its value, so reports group by the
+id and history keeps the name it had then:
+
+```ts
+import { answerSnapshots, answersFromSnapshots, withHostOptions } from "@marktiderman/genesis-forms/server";
+
+const shown = withHostOptions(definition, lists);
+const snapshots = answerSnapshots(shown, result.submission.answers);
+// { location: { value: "riverside", label: "Riverside Gym" }, helpers: [{ value: "ada", label: "Ada" }] }
+
+// An edit link: find each pick again in today's lists.
+const { answers, missing } = answersFromSnapshots(withHostOptions(definition, listsNow), stored);
+createForm(definition, { hostOptions: listsNow, initialValues: answers });
+```
+
+`answerSnapshots` covers questions with `optionsFrom`; a typed "Other" answer is marked `other`.
+`answersFromSnapshots` keeps a value still offered, else takes an option with the same label
+(ignoring case and accents), keeps a typed "Other" answer when the question still allows one, and
+reports the rest in `missing`. Both are also exported from the main entry.
+
 ### An "Other" answer
 
 ```ts
@@ -302,6 +387,107 @@ limits above (`maxEvents`, `maxValues`, `maxReplayWork`). Events of an unknown t
 client's log still replays. With `settings.clearHiddenValues: false`, a hidden field's value is kept
 only if its format is valid.
 
+### Edit links
+
+A respondent can change a sent response through a signed link, `?edit=<id>.<nonce>.<expires>.<sig>`:
+an HMAC-SHA256 (Web Crypto) under a server secret of at least 32 bytes, working for 30 days. The app
+keeps a nonce per response and changes it after each edit, so only the newest link works; it checks
+the nonce itself. Without a usable secret there are no edit links: signing returns null and nothing
+verifies.
+
+```ts
+import {
+  createEditSecretReader,
+  editLinkUrl,
+  verifyEditToken,
+  withEditLinkHeaders,
+} from "@marktiderman/genesis-forms/server";
+
+const editSecret = createEditSecretReader({ variable: "FORM_EDIT_SECRET" }); // warns once when missing
+const editUrl = await editLinkUrl(`/f/${slug}`, { id: response.id, nonce: response.editNonce }, editSecret(env));
+const claims = await verifyEditToken(url.searchParams.get("edit"), editSecret(env)); // then compare claims.nonce
+// The link is a credential: no Referer, no caching, on the page it opens.
+return withEditLinkHeaders(request, response, { isFormPage: (u) => u.pathname.startsWith("/f/") });
+```
+
+`signEditToken`, `withEditToken`, `isEditLinkRequest`, `isUsableEditSecret`, `EDIT_LINK_TTL_SECONDS`,
+`MIN_EDIT_SECRET_BYTES` and `EDIT_LINK_PARAM` are the parts. `carryAnswers` (main entry) moves a
+stored response's answers onto a newer version of the form by field key, for the edit page's prefill.
+
+### 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
+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
+open, and logs, when it answers null or throws. `RATE_LIMIT_DEFAULTS` holds 60 submits, 900 saves as
+they go and 120 photo uploads per 10 minutes.
+
+```ts
+const key = await rateLimitKey({ kind: "submit", scope: practiceId, ip: clientIp(request.headers), secret });
+if (!(await allow(store, { key, ...RATE_LIMIT_DEFAULTS.submit }, { log }))) return tooMany();
+```
+
+### Uploads
+
+A `photo` answer holds references, never bytes, so the server must check each one is a file it
+stored for this respondent. Two pieces do it, with the app's database and storage behind an
+`UploadStore` (`beginUpload`, `signUpload`, `uploadRefs`):
+
+- `createUploadHandler({ resolveForm, store, edit?, rateLimit?, ... })` is the endpoint the browser
+  asks for one signed upload per file (`(request, params) => Response`). It checks the form is open,
+  the field takes files and the file's type and size, the visit's attempt id or the edit link
+  (`edit.response` loads the response, the handler compares its nonce), and the rate limit
+  (`kind: "upload"`, 120 per 10 minutes by default), then records the upload and signs it.
+- `checkUploads(definition, answers, { formId, owner, store })`, on submit after
+  `validateSubmission`: every reference must be an upload this attempt (`{ attemptHash }`) or this
+  edit (`{ responseId }`: the response's own files, or ones uploaded for the edit) made, for that
+  field, finished, of a type and size the field takes, and no more than it takes. The stored name,
+  type and size replace what the browser sent; a refusal is keyed by field id.
+
+```ts
+import { attemptHash, checkUploads, createUploadHandler } from "@marktiderman/genesis-forms/server";
+
+export const POST = createUploadHandler<{ slug: string }>({
+  resolveForm: async (request, { slug }) => {
+    const found = await loadForm(request, slug); // null: 404
+    return found && { id: found.id, definition: found.definition, open: found.open, scope: found.practiceId, allowsEdits: found.allowEdit };
+  },
+  store: uploadStore, // beginUpload, signUpload, uploadRefs
+  edit: { secret: editSecret, response: (id, form) => loadSentResponse(id, form) }, // { id, editNonce } or null
+  rateLimit: { store: counter, secret: rateLimitSecret },
+});
+
+// On submit:
+const checked = await checkUploads(definition, result.submission.answers, {
+  formId,
+  owner: editing ? { responseId } : { attemptHash: await attemptHash(body.attemptId) },
+  store: uploadStore,
+}); // throws when the store can't read: answer 503
+if (!checked.ok) return Response.json({ errors: checked.errors }, { status: 422 });
+```
+
+The JSON (`UploadRequest`, `UploadGrant`, `UploadRefusal` in the main entry, for the browser; every
+response is `cache-control: no-store`):
+
+| Status | Body | When |
+| --- | --- | --- |
+| 200 | `{ ref: { id, name, type, size }, upload: { path, token, bucket?, url? } }` | Recorded and signed; `upload` is what `signUpload` returned. |
+| 400 | `{ error }` | Not a JSON object; no `attemptId` (a UUID) without `edit`; the field isn't an upload field. |
+| 403 | `{ error, code: "bad_link" }` | An edit link that doesn't verify, isn't the response's newest, or a form without edits. |
+| 404 | `{ error }` | `resolveForm` found no form. |
+| 409 | `{ error }`, or `code: "closed"` for an edit | The form isn't open. |
+| 413 | `{ error }` | The request is over 4,000 bytes, or the file is empty, not whole bytes or over the field's size. |
+| 415 | `{ error }` | Not `application/json`, or a file type the field doesn't take. |
+| 429 | `{ error }`, or `code: "too_many_photos"` | The rate limit, or the store's `{ tooMany: true }`. |
+| 500 / 503 | `{ error }` | Recording or signing failed / the form or the edit's response couldn't be loaded; the cause is logged, never sent. |
+
+The request is `{ fieldId, name, type, size }` plus `attemptId` or `edit`. `attemptHash(attemptId)`
+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.
+
 ## Destinations
 
 `@marktiderman/genesis-forms/destinations` sends a checked submission somewhere. No dependencies:

package/dist/destinations.cjs

@@ -436,6 +436,57 @@ function summarizeValue(value, field) {
   if (Array.isArray(value)) return value.join(", ");
   return String(value);
 }
+var OPTION_LIMITS = {
+  /** Characters in a description. */
+  description: 500,
+  /** Characters in an image URL. */
+  image: 2048,
+  /** Attributes on one option. */
+  attributes: 20,
+  /** Characters in an attribute's name. */
+  attributeName: 64,
+  /** Characters in one attribute value. */
+  attributeValue: 200,
+  /** Values in one attribute's list. */
+  attributeItems: 50
+};
+function isHttpsUrl(url) {
+  return typeof url === "string" && url.length <= OPTION_LIMITS.image && /^https:\/\/[^\s/?#@\\]+(?:[/?#][^\s]*)?$/i.test(url) && // No control characters anywhere (a line break would end a CSV row or an HTML attribute).
+  ![...url].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127);
+}
+function attributeName(name) {
+  return name.trim() !== "" && name.length <= OPTION_LIMITS.attributeName && !(name in Object.prototype);
+}
+function readAttributes(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const out = {};
+  let count = 0;
+  for (const name of Object.keys(raw)) {
+    if (count >= OPTION_LIMITS.attributes) break;
+    if (!attributeName(name)) continue;
+    const v = raw[name];
+    const fits = (x) => typeof x === "string" && x.length <= OPTION_LIMITS.attributeValue;
+    if (fits(v)) out[name] = v;
+    else if (Array.isArray(v) && v.length <= OPTION_LIMITS.attributeItems && v.every(fits)) out[name] = [...v];
+    else continue;
+    count++;
+  }
+  return count ? out : void 0;
+}
+function readOption(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const o = raw;
+  if (typeof o.value !== "string") return null;
+  const out = { value: o.value };
+  if (typeof o.label === "string") out.label = o.label;
+  if (typeof o.description === "string" && o.description.trim() && o.description.length <= OPTION_LIMITS.description) {
+    out.description = o.description;
+  }
+  if (isHttpsUrl(o.image)) out.image = o.image;
+  const attributes = readAttributes(o.attributes);
+  if (attributes) out.attributes = attributes;
+  return out;
+}
 var OTHER_MAX_LENGTH = 200;
 function otherOption(field) {
   const other = field.props?.other;
@@ -453,9 +504,10 @@ var typedOther = (field, value) => isOtherValue(field, value) && value.trim() !=
 function choiceOptions(field) {
   const raw = field.props?.options;
   if (!Array.isArray(raw)) return [];
-  return raw.flatMap(
-    (o) => o && typeof o === "object" && !Array.isArray(o) && typeof o.value === "string" ? [{ value: o.value, label: typeof o.label === "string" ? o.label : void 0 }] : []
-  );
+  return raw.flatMap((o) => {
+    const option = readOption(o);
+    return option ? [option] : [];
+  });
 }
 function optionLabel(field, value) {
   const option = choiceOptions(field).find((o) => o.value === value);