@marktiderman/genesis-forms 0.4.2 → 0.6.0

package/dist/server.d.cts

@@ -1,5 +1,195 @@
-import { J as Json, e as FormEvent, F as FormDefinition } from './types-BBKBQ8sp.cjs';
-import { F as FieldValidator } from './validate-BXXqi0fq.cjs';
+import { F as FieldValidator, H as HostOptions } from './validate-B5WKHbst.cjs';
+export { A as AnswerSnapshot, d as OptionSnapshot, f as RestoredAnswers, h as answerSnapshots, i as answersFromSnapshots, $ as withHostOptions } from './validate-B5WKHbst.cjs';
+import { J as Json, e as FormEvent, F as FormDefinition } from './types-oAckGR_Z.cjs';
+
+/**
+ * Edit links for a sent response: `<id>.<nonce>.<expires>.<sig>`, where sig is the
+ * base64url HMAC-SHA256 of `edit-link:v2:<id>.<nonce>.<expires>` under a server-only
+ * secret of at least 32 bytes.
+ *
+ * - id: the response's uuid.
+ * - nonce: the response's current edit nonce, kept by the app. The app refuses a link
+ *   whose nonce is no longer the response's, so changing the nonce revokes every link
+ *   made before (change it after each edit: only the newest link works).
+ * - expires: when the link stops working, in Unix seconds, about 30 days after it was
+ *   made (`EDIT_LINK_TTL_SECONDS`).
+ *
+ * Without a usable secret (missing, or shorter than `MIN_EDIT_SECRET_BYTES`) there are no
+ * edit links: signing returns null and every token fails to verify.
+ *
+ * Web Crypto only, no storage: the app keeps the nonce and checks it. Moved up from
+ * Breakthrough's src/lib/forms/edit-link.ts unchanged, so links it signed still verify.
+ */
+/** How long a new edit link works: 30 days. */
+declare const EDIT_LINK_TTL_SECONDS: number;
+/** The shortest secret edit links are signed with: 32 bytes (UTF-8), as long as the HMAC. */
+declare const MIN_EDIT_SECRET_BYTES = 32;
+/** The query parameter an edit link's token travels in: `?edit=<token>`. */
+declare const EDIT_LINK_PARAM = "edit";
+/** Whether `secret` can sign edit links: a string of at least `MIN_EDIT_SECRET_BYTES` bytes. */
+declare function isUsableEditSecret(secret: string | null | undefined): secret is string;
+/** What an edit link says: the response, its nonce when the link was made, and when it stops working. */
+interface EditLinkClaims {
+    /** The response's id, in lower case. */
+    id: string;
+    nonce: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+interface EditLinkOptions {
+    /** The current time in milliseconds (tests); `Date.now()` by default. */
+    now?: number | undefined;
+    /** How long the link works, in seconds; `EDIT_LINK_TTL_SECONDS` by default. */
+    ttlSeconds?: number | undefined;
+}
+/**
+ * The edit token for a response and its current nonce, working for `ttlSeconds` from
+ * now; null when there is no usable secret (no edit links) or the id or nonce is malformed.
+ */
+declare function signEditToken(link: {
+    id: string;
+    nonce: string;
+}, secret: string | null | undefined, options?: EditLinkOptions): Promise<string | null>;
+/**
+ * What a token says, or null when it is malformed, its signature does not match, it has
+ * expired (or claims to last longer than `ttlSeconds` from now), or there is no usable
+ * secret. Whether the nonce is still the response's is the caller's check. The
+ * comparison is Web Crypto's HMAC verify, which runs in constant time.
+ */
+declare function verifyEditToken(token: string | null | undefined, secret: string | null | undefined, options?: EditLinkOptions): Promise<EditLinkClaims | null>;
+/**
+ * A form link with the edit token added: `<formUrl>?edit=<token>` (or `&edit=` when it
+ * has a query). `param` names the parameter; `EDIT_LINK_PARAM` by default.
+ */
+declare function withEditToken(formUrl: string, token: string, param?: string): string;
+interface EditLinkUrlOptions extends EditLinkOptions {
+    /** The query parameter; `EDIT_LINK_PARAM` by default. */
+    param?: string | undefined;
+}
+/**
+ * The link that reopens a response for editing: `formUrl` (the page that shows the form,
+ * with any query it needs) plus a token signed for the response's current nonce. Null
+ * when there are no edit links (no usable secret) or the id or nonce is malformed.
+ */
+declare function editLinkUrl(formUrl: string, link: {
+    id: string;
+    nonce: string;
+}, secret: string | null | undefined, options?: EditLinkUrlOptions): Promise<string | null>;
+/** Where the edit-secret reader reports a missing or short secret. */
+type EditSecretLog = (message: string) => void;
+/** Reads the edit-link secret from an environment, warning once when there is none. */
+interface EditSecretReader {
+    /** The secret, or null (no edit links) when it is missing or too short; warns once, never with the secret. */
+    (env: Record<string, string | undefined>, log?: EditSecretLog): string | null;
+    /** Tests only: warn again. */
+    reset(): void;
+}
+/**
+ * A reader for the environment variable that holds the edit-link secret (such as
+ * `FEEDBACK_EDIT_SECRET`). Without one of at least `MIN_EDIT_SECRET_BYTES` bytes there are
+ * no edit links, and the first read says so through `log` (the call's, else the
+ * reader's, else `console.warn`); later reads stay quiet until `reset()`.
+ */
+declare function createEditSecretReader(options: {
+    variable: string;
+    log?: EditSecretLog | undefined;
+}): EditSecretReader;
+interface EditLinkRequestOptions {
+    /** The query parameter; `EDIT_LINK_PARAM` by default. */
+    param?: string | undefined;
+    /**
+     * Whether the URL is a page that shows a form (an edit link is only honoured there,
+     * such as `/f/<slug>`). Every URL by default.
+     */
+    isFormPage?: ((url: URL) => boolean) | undefined;
+}
+/** Whether this request is a form page opened with an edit link (the parameter present, even empty). */
+declare function isEditLinkRequest(url: URL, options?: EditLinkRequestOptions): boolean;
+/**
+ * The response, with `Referrer-Policy: no-referrer` and `Cache-Control: private, no-store`
+ * added when the request carried an edit link; otherwise the same response, untouched.
+ * The link is a credential, so it never leaves in a Referer header (an HTTP header, not
+ * only the page's meta tag, so it holds before the page has parsed and for every request
+ * the page makes), and the page, prefilled with the response, is never cached.
+ */
+declare function withEditLinkHeaders(request: Request, response: Response, options?: EditLinkRequestOptions): Response;
+
+/**
+ * The pieces of a submit endpoint's rate limit that aren't storage: the client's
+ * address, the part of it that names one client, a key that never holds the address,
+ * and a check that fails open. The counter itself is the app's (`RateLimitStore`), so
+ * every server instance can share it (a row in Postgres, a key in Redis).
+ *
+ * Web Crypto only. Moved up from Breakthrough's src/lib/feedback/rate-limit.server.ts;
+ * keys made here equal the ones it made, so a deploy doesn't reset anyone's count.
+ */
+/**
+ * The headers a proxy reports the client's address in, most trusted first. Trust only
+ * headers your proxy sets (and overwrites): a client can send any of them itself.
+ */
+declare const DEFAULT_TRUSTED_IP_HEADERS: readonly string[];
+/**
+ * How many submits, saves as they go and photo uploads one client may make per scope
+ * (a practice, an account) in a window.
+ *
+ * - submit: 60 responses per 10 minutes: a class at one gym's Wi-Fi fits.
+ * - progress: saving answers as they go. A visit counts once, against `submit`, at its
+ *   first save; its later saves (each Next, the send, a reload picking up where it was)
+ *   count here, in the same window: 60 people answering 10 questions each on one Wi-Fi fit.
+ * - upload: 120 photos per 10 minutes: that class, a couple of photos each.
+ */
+declare const RATE_LIMIT_DEFAULTS: {
+    readonly submit: {
+        readonly limit: 60;
+        readonly windowSeconds: 600;
+    };
+    readonly progress: {
+        readonly limit: 900;
+        readonly windowSeconds: 600;
+    };
+    readonly upload: {
+        readonly limit: 120;
+        readonly windowSeconds: 600;
+    };
+};
+/**
+ * The client's address as the proxy reports it, used only as a rate-limit key: the first
+ * entry of the first of `trusted` that is set, trimmed, else `"unknown"`.
+ */
+declare function clientIp(headers: Pick<Headers, "get">, trusted?: readonly string[]): string;
+/** The part of an address that names one client: an IPv4 address whole, an IPv6 address by its /64. */
+declare function addressPrefix(ip: string): string;
+/**
+ * The stored key, `<kind>:<scope>:<hex HMAC-SHA256 of the address prefix>`: what is
+ * counted (such as `submit`, `progress`, `upload`), whose count it is (a practice id),
+ * and the client, which is never stored as its address. `secret` is a server secret.
+ */
+declare function rateLimitKey(input: {
+    kind: string;
+    scope: string;
+    ip: string;
+    secret: string;
+}): Promise<string>;
+/** The app's shared counter. */
+interface RateLimitStore {
+    /**
+     * Count one hit on `key` in its current `windowSeconds` window: true while the count is
+     * within `limit`, false past it, null when it could not count.
+     */
+    hit(key: string, limit: number, windowSeconds: number): Promise<boolean | null>;
+}
+/**
+ * True when the request may go on. Fails open: when the store can't count (it answers
+ * null or throws) the request goes on and `log` says so with `message`.
+ */
+declare function allow(store: RateLimitStore, check: {
+    key: string;
+    limit: number;
+    windowSeconds: number;
+}, options?: {
+    log?: ((message: string) => void) | undefined;
+    message?: string | undefined;
+}): Promise<boolean>;
 
 interface SubmissionInput {
     /** Answers keyed by field id. Ignored when `events` is given. */
@@ -35,6 +225,13 @@ interface SubmissionOptions {
      * replay counts: the submit that follows it does not.
      */
     maxReplayWork?: number | undefined;
+    /**
+     * The option lists the app supplies for `optionsFrom: { source: "host" }`
+     * choice fields, loaded here on the server (never taken from the client):
+     * an answer must be one of the field's own options or of these. Pass what
+     * the form was shown with, loaded afresh, such as the current staff.
+     */
+    hostOptions?: HostOptions | undefined;
 }
 interface CheckedSubmission {
     status: "draft" | "completed";
@@ -74,11 +271,11 @@ declare const RAW_EVENTS_PER_EVENT = 10;
  * Check a submission against the published definition. Never throws on a
  * malformed submission: it returns `{ ok: false, errors: { "": … } }`.
  */
-declare function validateSubmission(definition: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
+declare function validateSubmission(published: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
 /**
  * The definition as respondents may see it. R1 forms hold nothing secret;
  * assessment answer keys (R4) will be stripped here.
  */
 declare function publicDefinition(definition: FormDefinition): FormDefinition;
 
-export { type CheckedSubmission, MAX_EVENTS, MAX_REPLAY_WORK, MAX_SUBMISSION_VALUES, RAW_EVENTS_PER_EVENT, type SubmissionInput, type SubmissionOptions, type SubmissionResult, publicDefinition, validateSubmission };
+export { type CheckedSubmission, DEFAULT_TRUSTED_IP_HEADERS, EDIT_LINK_PARAM, EDIT_LINK_TTL_SECONDS, type EditLinkClaims, type EditLinkOptions, type EditLinkRequestOptions, type EditLinkUrlOptions, type EditSecretLog, type EditSecretReader, HostOptions, MAX_EVENTS, MAX_REPLAY_WORK, MAX_SUBMISSION_VALUES, MIN_EDIT_SECRET_BYTES, RATE_LIMIT_DEFAULTS, RAW_EVENTS_PER_EVENT, type RateLimitStore, type SubmissionInput, type SubmissionOptions, type SubmissionResult, addressPrefix, allow, clientIp, createEditSecretReader, editLinkUrl, isEditLinkRequest, isUsableEditSecret, publicDefinition, rateLimitKey, signEditToken, validateSubmission, verifyEditToken, withEditLinkHeaders, withEditToken };

package/dist/server.d.ts

@@ -1,5 +1,195 @@
-import { J as Json, e as FormEvent, F as FormDefinition } from './types-BBKBQ8sp.js';
-import { F as FieldValidator } from './validate-BjNwF1UE.js';
+import { F as FieldValidator, H as HostOptions } from './validate-GpTXPwyl.js';
+export { A as AnswerSnapshot, d as OptionSnapshot, f as RestoredAnswers, h as answerSnapshots, i as answersFromSnapshots, $ as withHostOptions } from './validate-GpTXPwyl.js';
+import { J as Json, e as FormEvent, F as FormDefinition } from './types-oAckGR_Z.js';
+
+/**
+ * Edit links for a sent response: `<id>.<nonce>.<expires>.<sig>`, where sig is the
+ * base64url HMAC-SHA256 of `edit-link:v2:<id>.<nonce>.<expires>` under a server-only
+ * secret of at least 32 bytes.
+ *
+ * - id: the response's uuid.
+ * - nonce: the response's current edit nonce, kept by the app. The app refuses a link
+ *   whose nonce is no longer the response's, so changing the nonce revokes every link
+ *   made before (change it after each edit: only the newest link works).
+ * - expires: when the link stops working, in Unix seconds, about 30 days after it was
+ *   made (`EDIT_LINK_TTL_SECONDS`).
+ *
+ * Without a usable secret (missing, or shorter than `MIN_EDIT_SECRET_BYTES`) there are no
+ * edit links: signing returns null and every token fails to verify.
+ *
+ * Web Crypto only, no storage: the app keeps the nonce and checks it. Moved up from
+ * Breakthrough's src/lib/forms/edit-link.ts unchanged, so links it signed still verify.
+ */
+/** How long a new edit link works: 30 days. */
+declare const EDIT_LINK_TTL_SECONDS: number;
+/** The shortest secret edit links are signed with: 32 bytes (UTF-8), as long as the HMAC. */
+declare const MIN_EDIT_SECRET_BYTES = 32;
+/** The query parameter an edit link's token travels in: `?edit=<token>`. */
+declare const EDIT_LINK_PARAM = "edit";
+/** Whether `secret` can sign edit links: a string of at least `MIN_EDIT_SECRET_BYTES` bytes. */
+declare function isUsableEditSecret(secret: string | null | undefined): secret is string;
+/** What an edit link says: the response, its nonce when the link was made, and when it stops working. */
+interface EditLinkClaims {
+    /** The response's id, in lower case. */
+    id: string;
+    nonce: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+interface EditLinkOptions {
+    /** The current time in milliseconds (tests); `Date.now()` by default. */
+    now?: number | undefined;
+    /** How long the link works, in seconds; `EDIT_LINK_TTL_SECONDS` by default. */
+    ttlSeconds?: number | undefined;
+}
+/**
+ * The edit token for a response and its current nonce, working for `ttlSeconds` from
+ * now; null when there is no usable secret (no edit links) or the id or nonce is malformed.
+ */
+declare function signEditToken(link: {
+    id: string;
+    nonce: string;
+}, secret: string | null | undefined, options?: EditLinkOptions): Promise<string | null>;
+/**
+ * What a token says, or null when it is malformed, its signature does not match, it has
+ * expired (or claims to last longer than `ttlSeconds` from now), or there is no usable
+ * secret. Whether the nonce is still the response's is the caller's check. The
+ * comparison is Web Crypto's HMAC verify, which runs in constant time.
+ */
+declare function verifyEditToken(token: string | null | undefined, secret: string | null | undefined, options?: EditLinkOptions): Promise<EditLinkClaims | null>;
+/**
+ * A form link with the edit token added: `<formUrl>?edit=<token>` (or `&edit=` when it
+ * has a query). `param` names the parameter; `EDIT_LINK_PARAM` by default.
+ */
+declare function withEditToken(formUrl: string, token: string, param?: string): string;
+interface EditLinkUrlOptions extends EditLinkOptions {
+    /** The query parameter; `EDIT_LINK_PARAM` by default. */
+    param?: string | undefined;
+}
+/**
+ * The link that reopens a response for editing: `formUrl` (the page that shows the form,
+ * with any query it needs) plus a token signed for the response's current nonce. Null
+ * when there are no edit links (no usable secret) or the id or nonce is malformed.
+ */
+declare function editLinkUrl(formUrl: string, link: {
+    id: string;
+    nonce: string;
+}, secret: string | null | undefined, options?: EditLinkUrlOptions): Promise<string | null>;
+/** Where the edit-secret reader reports a missing or short secret. */
+type EditSecretLog = (message: string) => void;
+/** Reads the edit-link secret from an environment, warning once when there is none. */
+interface EditSecretReader {
+    /** The secret, or null (no edit links) when it is missing or too short; warns once, never with the secret. */
+    (env: Record<string, string | undefined>, log?: EditSecretLog): string | null;
+    /** Tests only: warn again. */
+    reset(): void;
+}
+/**
+ * A reader for the environment variable that holds the edit-link secret (such as
+ * `FEEDBACK_EDIT_SECRET`). Without one of at least `MIN_EDIT_SECRET_BYTES` bytes there are
+ * no edit links, and the first read says so through `log` (the call's, else the
+ * reader's, else `console.warn`); later reads stay quiet until `reset()`.
+ */
+declare function createEditSecretReader(options: {
+    variable: string;
+    log?: EditSecretLog | undefined;
+}): EditSecretReader;
+interface EditLinkRequestOptions {
+    /** The query parameter; `EDIT_LINK_PARAM` by default. */
+    param?: string | undefined;
+    /**
+     * Whether the URL is a page that shows a form (an edit link is only honoured there,
+     * such as `/f/<slug>`). Every URL by default.
+     */
+    isFormPage?: ((url: URL) => boolean) | undefined;
+}
+/** Whether this request is a form page opened with an edit link (the parameter present, even empty). */
+declare function isEditLinkRequest(url: URL, options?: EditLinkRequestOptions): boolean;
+/**
+ * The response, with `Referrer-Policy: no-referrer` and `Cache-Control: private, no-store`
+ * added when the request carried an edit link; otherwise the same response, untouched.
+ * The link is a credential, so it never leaves in a Referer header (an HTTP header, not
+ * only the page's meta tag, so it holds before the page has parsed and for every request
+ * the page makes), and the page, prefilled with the response, is never cached.
+ */
+declare function withEditLinkHeaders(request: Request, response: Response, options?: EditLinkRequestOptions): Response;
+
+/**
+ * The pieces of a submit endpoint's rate limit that aren't storage: the client's
+ * address, the part of it that names one client, a key that never holds the address,
+ * and a check that fails open. The counter itself is the app's (`RateLimitStore`), so
+ * every server instance can share it (a row in Postgres, a key in Redis).
+ *
+ * Web Crypto only. Moved up from Breakthrough's src/lib/feedback/rate-limit.server.ts;
+ * keys made here equal the ones it made, so a deploy doesn't reset anyone's count.
+ */
+/**
+ * The headers a proxy reports the client's address in, most trusted first. Trust only
+ * headers your proxy sets (and overwrites): a client can send any of them itself.
+ */
+declare const DEFAULT_TRUSTED_IP_HEADERS: readonly string[];
+/**
+ * How many submits, saves as they go and photo uploads one client may make per scope
+ * (a practice, an account) in a window.
+ *
+ * - submit: 60 responses per 10 minutes: a class at one gym's Wi-Fi fits.
+ * - progress: saving answers as they go. A visit counts once, against `submit`, at its
+ *   first save; its later saves (each Next, the send, a reload picking up where it was)
+ *   count here, in the same window: 60 people answering 10 questions each on one Wi-Fi fit.
+ * - upload: 120 photos per 10 minutes: that class, a couple of photos each.
+ */
+declare const RATE_LIMIT_DEFAULTS: {
+    readonly submit: {
+        readonly limit: 60;
+        readonly windowSeconds: 600;
+    };
+    readonly progress: {
+        readonly limit: 900;
+        readonly windowSeconds: 600;
+    };
+    readonly upload: {
+        readonly limit: 120;
+        readonly windowSeconds: 600;
+    };
+};
+/**
+ * The client's address as the proxy reports it, used only as a rate-limit key: the first
+ * entry of the first of `trusted` that is set, trimmed, else `"unknown"`.
+ */
+declare function clientIp(headers: Pick<Headers, "get">, trusted?: readonly string[]): string;
+/** The part of an address that names one client: an IPv4 address whole, an IPv6 address by its /64. */
+declare function addressPrefix(ip: string): string;
+/**
+ * The stored key, `<kind>:<scope>:<hex HMAC-SHA256 of the address prefix>`: what is
+ * counted (such as `submit`, `progress`, `upload`), whose count it is (a practice id),
+ * and the client, which is never stored as its address. `secret` is a server secret.
+ */
+declare function rateLimitKey(input: {
+    kind: string;
+    scope: string;
+    ip: string;
+    secret: string;
+}): Promise<string>;
+/** The app's shared counter. */
+interface RateLimitStore {
+    /**
+     * Count one hit on `key` in its current `windowSeconds` window: true while the count is
+     * within `limit`, false past it, null when it could not count.
+     */
+    hit(key: string, limit: number, windowSeconds: number): Promise<boolean | null>;
+}
+/**
+ * True when the request may go on. Fails open: when the store can't count (it answers
+ * null or throws) the request goes on and `log` says so with `message`.
+ */
+declare function allow(store: RateLimitStore, check: {
+    key: string;
+    limit: number;
+    windowSeconds: number;
+}, options?: {
+    log?: ((message: string) => void) | undefined;
+    message?: string | undefined;
+}): Promise<boolean>;
 
 interface SubmissionInput {
     /** Answers keyed by field id. Ignored when `events` is given. */
@@ -35,6 +225,13 @@ interface SubmissionOptions {
      * replay counts: the submit that follows it does not.
      */
     maxReplayWork?: number | undefined;
+    /**
+     * The option lists the app supplies for `optionsFrom: { source: "host" }`
+     * choice fields, loaded here on the server (never taken from the client):
+     * an answer must be one of the field's own options or of these. Pass what
+     * the form was shown with, loaded afresh, such as the current staff.
+     */
+    hostOptions?: HostOptions | undefined;
 }
 interface CheckedSubmission {
     status: "draft" | "completed";
@@ -74,11 +271,11 @@ declare const RAW_EVENTS_PER_EVENT = 10;
  * Check a submission against the published definition. Never throws on a
  * malformed submission: it returns `{ ok: false, errors: { "": … } }`.
  */
-declare function validateSubmission(definition: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
+declare function validateSubmission(published: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
 /**
  * The definition as respondents may see it. R1 forms hold nothing secret;
  * assessment answer keys (R4) will be stripped here.
  */
 declare function publicDefinition(definition: FormDefinition): FormDefinition;
 
-export { type CheckedSubmission, MAX_EVENTS, MAX_REPLAY_WORK, MAX_SUBMISSION_VALUES, RAW_EVENTS_PER_EVENT, type SubmissionInput, type SubmissionOptions, type SubmissionResult, publicDefinition, validateSubmission };
+export { type CheckedSubmission, DEFAULT_TRUSTED_IP_HEADERS, EDIT_LINK_PARAM, EDIT_LINK_TTL_SECONDS, type EditLinkClaims, type EditLinkOptions, type EditLinkRequestOptions, type EditLinkUrlOptions, type EditSecretLog, type EditSecretReader, HostOptions, MAX_EVENTS, MAX_REPLAY_WORK, MAX_SUBMISSION_VALUES, MIN_EDIT_SECRET_BYTES, RATE_LIMIT_DEFAULTS, RAW_EVENTS_PER_EVENT, type RateLimitStore, type SubmissionInput, type SubmissionOptions, type SubmissionResult, addressPrefix, allow, clientIp, createEditSecretReader, editLinkUrl, isEditLinkRequest, isUsableEditSecret, publicDefinition, rateLimitKey, signEditToken, validateSubmission, verifyEditToken, withEditLinkHeaders, withEditToken };