@wildo-ai/saas-models 1.1.5 → 1.1.7

package/dist/esm/security/submission-challenge/submission-challenge.shared.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The challenge a public submission answers before the backend accepts it (#1735).
+ *
+ * ## Why two kinds, and why the second one is not optional
+ *
+ * A captcha vendor that analyses visitors for its own purposes needs their consent (Google reCAPTCHA:
+ * CNIL Délibération SAN-2023-003, recorded on the frontend consent classification), so a visitor who
+ * declines must still be able to submit. If declining meant "no challenge", a bot would decline too and
+ * the captcha would protect nothing. So an application that protects a form accepts EITHER:
+ *
+ * - a vendor token (`PROVIDER_TOKEN`) — obtained by the consented vendor's browser part and verified by its
+ *   backend part (reCAPTCHA `siteverify`);
+ * - a proof of work (`PROOF_OF_WORK`) — the engine's own challenge, consent-exempt because nothing leaves
+ *   the application and nothing is stored in the visitor's browser: the backend issues a salted SHA-256
+ *   puzzle signed with an application key, the browser searches for the number, the backend re-derives it.
+ *   It makes each submission cost the sender CPU time instead of identifying anyone.
+ *
+ * A submission with neither, or with one that fails, is refused: the challenge fails CLOSED.
+ *
+ * The proof-of-work scheme is ALTCHA's: challenge = SHA-256(salt + number), the client iterates numbers until the hash
+ * matches. The signature here covers the salt as well as the hash (HMAC(salt + "\n" + challenge)): the hash input has
+ * no separator and the salt ends in its expiry digits, so a signature over the hash alone would let digits move from
+ * the number onto the salt and forge a later expiry.
+ * spec-cite: https://altcha.org/docs/proof-of-work/ (read through its search summary 2026-09-29) — the scheme
+ * is described, not quoted; the field names below are this framework's own.
+ *
+ * ## Browser-safe on purpose
+ *
+ * The website's contact form encodes and solves challenges in the visitor's browser, so this file imports
+ * nothing and uses only `globalThis.crypto.subtle`, which both browsers and Node provide.
+ */
+/** Which kind of answer a submission carries. */
+export declare enum SubmissionChallengeResponseKind {
+    /** A token from a consented captcha vendor's browser part, verified by the same vendor's backend part. */
+    PROVIDER_TOKEN = "provider_token",
+    /** The engine's own consent-exempt proof of work. */
+    PROOF_OF_WORK = "proof_of_work"
+}
+/**
+ * The actions the ENGINE's own protected operations are bound to. A vendor token is minted for an action and the
+ * backend refuses one minted for another, so a token solved on one form cannot be replayed on another.
+ *
+ * This enum names the engine's actions only. An application protects its OWN anonymous operation by declaring
+ * `submissionChallenge: { action: '<its action>' }` on the operation variant (#1985), with an action it names in its
+ * own vocabulary; see {@link ResourceOperationSubmissionChallenge} for why the declaration takes a name rather than a
+ * member of this enum.
+ */
+export declare enum SubmissionChallengeAction {
+    /** The public contact form (`POST /inbound-contacts`). */
+    INBOUND_CONTACT = "inbound_contact"
+}
+/**
+ * The names a submission-challenge action may take: letters, digits, underscores and slashes, 1 to 100 characters.
+ *
+ * The character set is the captcha vendor's. The action is sent to Google reCAPTCHA as the `action` a token is minted
+ * for and checked against on `siteverify`, and reCAPTCHA v3 states "Actions might contain only alphanumeric
+ * characters, slashes, and underscores." A name outside it would be minted by no vendor, so every token for it would
+ * be refused. The 100-character bound is this framework's own: nothing longer is a name a person reads in a console.
+ * spec-cite: https://developers.google.com/recaptcha/docs/v3 §"Actions" (fetched 2026-09-29)
+ */
+export declare const SUBMISSION_CHALLENGE_ACTION_PATTERN: RegExp;
+/** Whether `value` is an action name a captcha vendor can mint a token for. See {@link SUBMISSION_CHALLENGE_ACTION_PATTERN}. */
+export declare function isSubmissionChallengeActionName(value: unknown): value is string;
+/**
+ * An operation variant's declaration that an UNAUTHENTICATED caller answers a submission challenge (#1985).
+ *
+ * `action` is a NAME (an open identifier), not a member of {@link SubmissionChallengeAction}, so an application can
+ * protect its own anonymous create (a waitlist, a quote request) without the engine growing a member for it. The
+ * engine's own operations pass their enum member; an application passes a member of its own enum. What keeps the name
+ * honest is the grammar ({@link SUBMISSION_CHALLENGE_ACTION_PATTERN}), which the resource factory enforces.
+ *
+ * Rejected alternatives, recorded because each was on the table:
+ * - A closed engine enum grown one member per protected operation. The engine cannot know an application's forms, so
+ *   an application's own create could never be protected: exactly the gap this declaration closes.
+ * - Deriving the action from the operation (`<resource>/<operation>`). It needs no authoring, but a resource or variant
+ *   identifier may carry characters the vendor refuses (a hyphen), so the derivation would have to rewrite them, and two
+ *   operations could then collide on one action with nothing saying so. A declared name is visible, reviewable and fixed.
+ */
+export interface ResourceOperationSubmissionChallenge {
+    /** The action a vendor token must have been minted for. Name one per form: sharing it lets a token move between them. */
+    readonly action: string;
+}
+/** The only hash the proof of work uses. Named so the wire value has one runtime source. */
+export declare enum ProofOfWorkAlgorithm {
+    SHA_256 = "SHA-256"
+}
+/** A proof-of-work challenge as the backend issues it. Every field is echoed back unchanged in the answer. */
+export interface ProofOfWorkChallenge {
+    readonly algorithm: ProofOfWorkAlgorithm;
+    /** Random, and carries the expiry (`<hex>?expires=<unix seconds>`) so the signature covers it. */
+    readonly salt: string;
+    /** Hex SHA-256 of `salt + number` for the secret number. */
+    readonly challenge: string;
+    /** The largest number the search has to try. */
+    readonly maxNumber: number;
+    /** Hex HMAC-SHA-256 of `salt`, a newline and `challenge`, under the application's challenge key — so the salt and its expiry cannot be edited. */
+    readonly signature: string;
+}
+/** What a submission sends, in the `WildoHeaderKeys.SUBMISSION_CHALLENGE_RESPONSE` header, JSON-encoded. */
+export type SubmissionChallengeResponse = {
+    readonly kind: SubmissionChallengeResponseKind.PROVIDER_TOKEN;
+    /** The captcha provider whose browser part minted the token (`recaptcha`). */
+    readonly providerRef: string;
+    readonly token: string;
+} | {
+    readonly kind: SubmissionChallengeResponseKind.PROOF_OF_WORK;
+    readonly challenge: ProofOfWorkChallenge;
+    /** The number the browser found. */
+    readonly number: number;
+};
+/**
+ * Where a browser asks for a proof-of-work challenge, under the API base path. The ONE source of this path: the
+ * backend's route table (`MANUAL_CONTROLLER_ROUTES_URLS`) reads it from here, so a browser form can reach it without
+ * pulling that whole table into its bundle.
+ */
+export declare const SUBMISSION_CHALLENGE_PROOF_OF_WORK_PATH = "/submission-challenges/proof-of-work";
+/**
+ * The stable `error.code` of a refused public submission — what a client branches on (the engine hoists an error's
+ * `context.code` to the top-level `error.code` of its response). A form answers either one again, with the proof of
+ * work.
+ */
+export declare enum SubmissionChallengeRefusalCode {
+    /** No answer was sent, and the application protects this form. */
+    REQUIRED = "SUBMISSION_CHALLENGE_REQUIRED",
+    /** An answer was sent and not accepted. */
+    REFUSED = "SUBMISSION_CHALLENGE_REFUSED"
+}
+/** The largest encoded answer the backend reads; anything longer is refused before it is parsed. */
+export declare const SUBMISSION_CHALLENGE_RESPONSE_MAX_LENGTH = 8192;
+/** Encode an answer for the request header. */
+export declare function encodeSubmissionChallengeResponse(response: SubmissionChallengeResponse): string;
+/** Hex SHA-256 of `salt + number` — the one hash both the solver and the backend compute. */
+export declare function hashProofOfWorkCandidate(salt: string, number: number): Promise<string>;
+/**
+ * Find the number a challenge was built from, or `undefined` when none up to `maxNumber` matches (a
+ * challenge not issued by this scheme). Yields to the event loop every `yieldEvery` tries so a page stays
+ * responsive while it searches.
+ */
+export declare function solveProofOfWorkChallenge(challenge: ProofOfWorkChallenge, options?: {
+    readonly yieldEvery?: number;
+    readonly signal?: AbortSignal;
+}): Promise<SubmissionChallengeResponse | undefined>;
+//# sourceMappingURL=submission-challenge.shared.d.ts.map

package/dist/esm/security/submission-challenge/submission-challenge.shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submission-challenge.shared.d.ts","sourceRoot":"","sources":["../../../../src/security/submission-challenge/submission-challenge.shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,iDAAiD;AACjD,oBAAY,+BAA+B;IACzC,0GAA0G;IAC1G,cAAc,mBAAmB;IACjC,qDAAqD;IACrD,aAAa,kBAAkB;CAChC;AAED;;;;;;;;GAQG;AACH,oBAAY,yBAAyB;IACnC,0DAA0D;IAC1D,eAAe,oBAAoB;CACpC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC,QAA4B,CAAC;AAE7E,gIAAgI;AAChI,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE/E;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oCAAoC;IACnD,yHAAyH;IACzH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,4FAA4F;AAC5F,oBAAY,oBAAoB;IAC9B,OAAO,YAAY;CACpB;AAED,8GAA8G;AAC9G,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACzC,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kJAAkJ;IAClJ,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,4GAA4G;AAC5G,MAAM,MAAM,2BAA2B,GACnC;IACA,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC,cAAc,CAAC;IAC9D,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACC;IACA,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC,aAAa,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACzC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEJ;;;;GAIG;AACH,eAAO,MAAM,uCAAuC,yCAAyC,CAAC;AAE9F;;;;GAIG;AACH,oBAAY,8BAA8B;IACxC,kEAAkE;IAClE,QAAQ,kCAAkC;IAC1C,2CAA2C;IAC3C,OAAO,iCAAiC;CACzC;AAED,oGAAoG;AACpG,eAAO,MAAM,wCAAwC,OAAO,CAAC;AAE7D,+CAA+C;AAC/C,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,2BAA2B,GAAG,MAAM,CAE/F;AAMD,6FAA6F;AAC7F,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5F;AAED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,oBAAoB,EAC/B,OAAO,GAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC5E,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAUlD"}

package/dist/esm/security/submission-challenge/submission-challenge.shared.js

@@ -0,0 +1,123 @@
+/**
+ * The challenge a public submission answers before the backend accepts it (#1735).
+ *
+ * ## Why two kinds, and why the second one is not optional
+ *
+ * A captcha vendor that analyses visitors for its own purposes needs their consent (Google reCAPTCHA:
+ * CNIL Délibération SAN-2023-003, recorded on the frontend consent classification), so a visitor who
+ * declines must still be able to submit. If declining meant "no challenge", a bot would decline too and
+ * the captcha would protect nothing. So an application that protects a form accepts EITHER:
+ *
+ * - a vendor token (`PROVIDER_TOKEN`) — obtained by the consented vendor's browser part and verified by its
+ *   backend part (reCAPTCHA `siteverify`);
+ * - a proof of work (`PROOF_OF_WORK`) — the engine's own challenge, consent-exempt because nothing leaves
+ *   the application and nothing is stored in the visitor's browser: the backend issues a salted SHA-256
+ *   puzzle signed with an application key, the browser searches for the number, the backend re-derives it.
+ *   It makes each submission cost the sender CPU time instead of identifying anyone.
+ *
+ * A submission with neither, or with one that fails, is refused: the challenge fails CLOSED.
+ *
+ * The proof-of-work scheme is ALTCHA's: challenge = SHA-256(salt + number), the client iterates numbers until the hash
+ * matches. The signature here covers the salt as well as the hash (HMAC(salt + "\n" + challenge)): the hash input has
+ * no separator and the salt ends in its expiry digits, so a signature over the hash alone would let digits move from
+ * the number onto the salt and forge a later expiry.
+ * spec-cite: https://altcha.org/docs/proof-of-work/ (read through its search summary 2026-09-29) — the scheme
+ * is described, not quoted; the field names below are this framework's own.
+ *
+ * ## Browser-safe on purpose
+ *
+ * The website's contact form encodes and solves challenges in the visitor's browser, so this file imports
+ * nothing and uses only `globalThis.crypto.subtle`, which both browsers and Node provide.
+ */
+/** Which kind of answer a submission carries. */
+export var SubmissionChallengeResponseKind;
+(function (SubmissionChallengeResponseKind) {
+    /** A token from a consented captcha vendor's browser part, verified by the same vendor's backend part. */
+    SubmissionChallengeResponseKind["PROVIDER_TOKEN"] = "provider_token";
+    /** The engine's own consent-exempt proof of work. */
+    SubmissionChallengeResponseKind["PROOF_OF_WORK"] = "proof_of_work";
+})(SubmissionChallengeResponseKind || (SubmissionChallengeResponseKind = {}));
+/**
+ * The actions the ENGINE's own protected operations are bound to. A vendor token is minted for an action and the
+ * backend refuses one minted for another, so a token solved on one form cannot be replayed on another.
+ *
+ * This enum names the engine's actions only. An application protects its OWN anonymous operation by declaring
+ * `submissionChallenge: { action: '<its action>' }` on the operation variant (#1985), with an action it names in its
+ * own vocabulary; see {@link ResourceOperationSubmissionChallenge} for why the declaration takes a name rather than a
+ * member of this enum.
+ */
+export var SubmissionChallengeAction;
+(function (SubmissionChallengeAction) {
+    /** The public contact form (`POST /inbound-contacts`). */
+    SubmissionChallengeAction["INBOUND_CONTACT"] = "inbound_contact";
+})(SubmissionChallengeAction || (SubmissionChallengeAction = {}));
+/**
+ * The names a submission-challenge action may take: letters, digits, underscores and slashes, 1 to 100 characters.
+ *
+ * The character set is the captcha vendor's. The action is sent to Google reCAPTCHA as the `action` a token is minted
+ * for and checked against on `siteverify`, and reCAPTCHA v3 states "Actions might contain only alphanumeric
+ * characters, slashes, and underscores." A name outside it would be minted by no vendor, so every token for it would
+ * be refused. The 100-character bound is this framework's own: nothing longer is a name a person reads in a console.
+ * spec-cite: https://developers.google.com/recaptcha/docs/v3 §"Actions" (fetched 2026-09-29)
+ */
+export const SUBMISSION_CHALLENGE_ACTION_PATTERN = /^[A-Za-z0-9_/]{1,100}$/u;
+/** Whether `value` is an action name a captcha vendor can mint a token for. See {@link SUBMISSION_CHALLENGE_ACTION_PATTERN}. */
+export function isSubmissionChallengeActionName(value) {
+    return typeof value === 'string' && SUBMISSION_CHALLENGE_ACTION_PATTERN.test(value);
+}
+/** The only hash the proof of work uses. Named so the wire value has one runtime source. */
+export var ProofOfWorkAlgorithm;
+(function (ProofOfWorkAlgorithm) {
+    ProofOfWorkAlgorithm["SHA_256"] = "SHA-256";
+})(ProofOfWorkAlgorithm || (ProofOfWorkAlgorithm = {}));
+/**
+ * Where a browser asks for a proof-of-work challenge, under the API base path. The ONE source of this path: the
+ * backend's route table (`MANUAL_CONTROLLER_ROUTES_URLS`) reads it from here, so a browser form can reach it without
+ * pulling that whole table into its bundle.
+ */
+export const SUBMISSION_CHALLENGE_PROOF_OF_WORK_PATH = '/submission-challenges/proof-of-work';
+/**
+ * The stable `error.code` of a refused public submission — what a client branches on (the engine hoists an error's
+ * `context.code` to the top-level `error.code` of its response). A form answers either one again, with the proof of
+ * work.
+ */
+export var SubmissionChallengeRefusalCode;
+(function (SubmissionChallengeRefusalCode) {
+    /** No answer was sent, and the application protects this form. */
+    SubmissionChallengeRefusalCode["REQUIRED"] = "SUBMISSION_CHALLENGE_REQUIRED";
+    /** An answer was sent and not accepted. */
+    SubmissionChallengeRefusalCode["REFUSED"] = "SUBMISSION_CHALLENGE_REFUSED";
+})(SubmissionChallengeRefusalCode || (SubmissionChallengeRefusalCode = {}));
+/** The largest encoded answer the backend reads; anything longer is refused before it is parsed. */
+export const SUBMISSION_CHALLENGE_RESPONSE_MAX_LENGTH = 8192;
+/** Encode an answer for the request header. */
+export function encodeSubmissionChallengeResponse(response) {
+    return JSON.stringify(response);
+}
+function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Hex SHA-256 of `salt + number` — the one hash both the solver and the backend compute. */
+export async function hashProofOfWorkCandidate(salt, number) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(`${salt}${number}`));
+    return toHex(digest);
+}
+/**
+ * Find the number a challenge was built from, or `undefined` when none up to `maxNumber` matches (a
+ * challenge not issued by this scheme). Yields to the event loop every `yieldEvery` tries so a page stays
+ * responsive while it searches.
+ */
+export async function solveProofOfWorkChallenge(challenge, options = {}) {
+    const yieldEvery = options.yieldEvery ?? 1000;
+    for (let number = 0; number <= challenge.maxNumber; number += 1) {
+        if (options.signal?.aborted)
+            return undefined;
+        if (await hashProofOfWorkCandidate(challenge.salt, number) === challenge.challenge) {
+            return { kind: SubmissionChallengeResponseKind.PROOF_OF_WORK, challenge, number };
+        }
+        if (number % yieldEvery === yieldEvery - 1)
+            await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+    return undefined;
+}
+//# sourceMappingURL=submission-challenge.shared.js.map

package/dist/esm/security/submission-challenge/submission-challenge.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submission-challenge.shared.js","sourceRoot":"","sources":["../../../../src/security/submission-challenge/submission-challenge.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The challenge a public submission answers before the backend accepts it (#1735).\n *\n * ## Why two kinds, and why the second one is not optional\n *\n * A captcha vendor that analyses visitors for its own purposes needs their consent (Google reCAPTCHA:\n * CNIL Délibération SAN-2023-003, recorded on the frontend consent classification), so a visitor who\n * declines must still be able to submit. If declining meant \"no challenge\", a bot would decline too and\n * the captcha would protect nothing. So an application that protects a form accepts EITHER:\n *\n * - a vendor token (`PROVIDER_TOKEN`) — obtained by the consented vendor's browser part and verified by its\n *   backend part (reCAPTCHA `siteverify`);\n * - a proof of work (`PROOF_OF_WORK`) — the engine's own challenge, consent-exempt because nothing leaves\n *   the application and nothing is stored in the visitor's browser: the backend issues a salted SHA-256\n *   puzzle signed with an application key, the browser searches for the number, the backend re-derives it.\n *   It makes each submission cost the sender CPU time instead of identifying anyone.\n *\n * A submission with neither, or with one that fails, is refused: the challenge fails CLOSED.\n *\n * The proof-of-work scheme is ALTCHA's: challenge = SHA-256(salt + number), the client iterates numbers until the hash\n * matches. The signature here covers the salt as well as the hash (HMAC(salt + \"\\n\" + challenge)): the hash input has\n * no separator and the salt ends in its expiry digits, so a signature over the hash alone would let digits move from\n * the number onto the salt and forge a later expiry.\n * spec-cite: https://altcha.org/docs/proof-of-work/ (read through its search summary 2026-09-29) — the scheme\n * is described, not quoted; the field names below are this framework's own.\n *\n * ## Browser-safe on purpose\n *\n * The website's contact form encodes and solves challenges in the visitor's browser, so this file imports\n * nothing and uses only `globalThis.crypto.subtle`, which both browsers and Node provide.\n */\n\n/** Which kind of answer a submission carries. */\nexport enum SubmissionChallengeResponseKind {\n  /** A token from a consented captcha vendor's browser part, verified by the same vendor's backend part. */\n  PROVIDER_TOKEN = 'provider_token',\n  /** The engine's own consent-exempt proof of work. */\n  PROOF_OF_WORK = 'proof_of_work',\n}\n\n/**\n * The actions the ENGINE's own protected operations are bound to. A vendor token is minted for an action and the\n * backend refuses one minted for another, so a token solved on one form cannot be replayed on another.\n *\n * This enum names the engine's actions only. An application protects its OWN anonymous operation by declaring\n * `submissionChallenge: { action: '<its action>' }` on the operation variant (#1985), with an action it names in its\n * own vocabulary; see {@link ResourceOperationSubmissionChallenge} for why the declaration takes a name rather than a\n * member of this enum.\n */\nexport enum SubmissionChallengeAction {\n  /** The public contact form (`POST /inbound-contacts`). */\n  INBOUND_CONTACT = 'inbound_contact',\n}\n\n/**\n * The names a submission-challenge action may take: letters, digits, underscores and slashes, 1 to 100 characters.\n *\n * The character set is the captcha vendor's. The action is sent to Google reCAPTCHA as the `action` a token is minted\n * for and checked against on `siteverify`, and reCAPTCHA v3 states \"Actions might contain only alphanumeric\n * characters, slashes, and underscores.\" A name outside it would be minted by no vendor, so every token for it would\n * be refused. The 100-character bound is this framework's own: nothing longer is a name a person reads in a console.\n * spec-cite: https://developers.google.com/recaptcha/docs/v3 §\"Actions\" (fetched 2026-09-29)\n */\nexport const SUBMISSION_CHALLENGE_ACTION_PATTERN = /^[A-Za-z0-9_/]{1,100}$/u;\n\n/** Whether `value` is an action name a captcha vendor can mint a token for. See {@link SUBMISSION_CHALLENGE_ACTION_PATTERN}. */\nexport function isSubmissionChallengeActionName(value: unknown): value is string {\n  return typeof value === 'string' && SUBMISSION_CHALLENGE_ACTION_PATTERN.test(value);\n}\n\n/**\n * An operation variant's declaration that an UNAUTHENTICATED caller answers a submission challenge (#1985).\n *\n * `action` is a NAME (an open identifier), not a member of {@link SubmissionChallengeAction}, so an application can\n * protect its own anonymous create (a waitlist, a quote request) without the engine growing a member for it. The\n * engine's own operations pass their enum member; an application passes a member of its own enum. What keeps the name\n * honest is the grammar ({@link SUBMISSION_CHALLENGE_ACTION_PATTERN}), which the resource factory enforces.\n *\n * Rejected alternatives, recorded because each was on the table:\n * - A closed engine enum grown one member per protected operation. The engine cannot know an application's forms, so\n *   an application's own create could never be protected: exactly the gap this declaration closes.\n * - Deriving the action from the operation (`<resource>/<operation>`). It needs no authoring, but a resource or variant\n *   identifier may carry characters the vendor refuses (a hyphen), so the derivation would have to rewrite them, and two\n *   operations could then collide on one action with nothing saying so. A declared name is visible, reviewable and fixed.\n */\nexport interface ResourceOperationSubmissionChallenge {\n  /** The action a vendor token must have been minted for. Name one per form: sharing it lets a token move between them. */\n  readonly action: string;\n}\n\n/** The only hash the proof of work uses. Named so the wire value has one runtime source. */\nexport enum ProofOfWorkAlgorithm {\n  SHA_256 = 'SHA-256',\n}\n\n/** A proof-of-work challenge as the backend issues it. Every field is echoed back unchanged in the answer. */\nexport interface ProofOfWorkChallenge {\n  readonly algorithm: ProofOfWorkAlgorithm;\n  /** Random, and carries the expiry (`<hex>?expires=<unix seconds>`) so the signature covers it. */\n  readonly salt: string;\n  /** Hex SHA-256 of `salt + number` for the secret number. */\n  readonly challenge: string;\n  /** The largest number the search has to try. */\n  readonly maxNumber: number;\n  /** Hex HMAC-SHA-256 of `salt`, a newline and `challenge`, under the application's challenge key — so the salt and its expiry cannot be edited. */\n  readonly signature: string;\n}\n\n/** What a submission sends, in the `WildoHeaderKeys.SUBMISSION_CHALLENGE_RESPONSE` header, JSON-encoded. */\nexport type SubmissionChallengeResponse =\n  | {\n    readonly kind: SubmissionChallengeResponseKind.PROVIDER_TOKEN;\n    /** The captcha provider whose browser part minted the token (`recaptcha`). */\n    readonly providerRef: string;\n    readonly token: string;\n  }\n  | {\n    readonly kind: SubmissionChallengeResponseKind.PROOF_OF_WORK;\n    readonly challenge: ProofOfWorkChallenge;\n    /** The number the browser found. */\n    readonly number: number;\n  };\n\n/**\n * Where a browser asks for a proof-of-work challenge, under the API base path. The ONE source of this path: the\n * backend's route table (`MANUAL_CONTROLLER_ROUTES_URLS`) reads it from here, so a browser form can reach it without\n * pulling that whole table into its bundle.\n */\nexport const SUBMISSION_CHALLENGE_PROOF_OF_WORK_PATH = '/submission-challenges/proof-of-work';\n\n/**\n * The stable `error.code` of a refused public submission — what a client branches on (the engine hoists an error's\n * `context.code` to the top-level `error.code` of its response). A form answers either one again, with the proof of\n * work.\n */\nexport enum SubmissionChallengeRefusalCode {\n  /** No answer was sent, and the application protects this form. */\n  REQUIRED = 'SUBMISSION_CHALLENGE_REQUIRED',\n  /** An answer was sent and not accepted. */\n  REFUSED = 'SUBMISSION_CHALLENGE_REFUSED',\n}\n\n/** The largest encoded answer the backend reads; anything longer is refused before it is parsed. */\nexport const SUBMISSION_CHALLENGE_RESPONSE_MAX_LENGTH = 8192;\n\n/** Encode an answer for the request header. */\nexport function encodeSubmissionChallengeResponse(response: SubmissionChallengeResponse): string {\n  return JSON.stringify(response);\n}\n\nfunction toHex(buffer: ArrayBuffer): string {\n  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, '0')).join('');\n}\n\n/** Hex SHA-256 of `salt + number` — the one hash both the solver and the backend compute. */\nexport async function hashProofOfWorkCandidate(salt: string, number: number): Promise<string> {\n  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(`${salt}${number}`));\n  return toHex(digest);\n}\n\n/**\n * Find the number a challenge was built from, or `undefined` when none up to `maxNumber` matches (a\n * challenge not issued by this scheme). Yields to the event loop every `yieldEvery` tries so a page stays\n * responsive while it searches.\n */\nexport async function solveProofOfWorkChallenge(\n  challenge: ProofOfWorkChallenge,\n  options: { readonly yieldEvery?: number; readonly signal?: AbortSignal } = {},\n): Promise<SubmissionChallengeResponse | undefined> {\n  const yieldEvery = options.yieldEvery ?? 1000;\n  for (let number = 0; number <= challenge.maxNumber; number += 1) {\n    if (options.signal?.aborted) return undefined;\n    if (await hashProofOfWorkCandidate(challenge.salt, number) === challenge.challenge) {\n      return { kind: SubmissionChallengeResponseKind.PROOF_OF_WORK, challenge, number };\n    }\n    if (number % yieldEvery === yieldEvery - 1) await new Promise((resolve) => setTimeout(resolve, 0));\n  }\n  return undefined;\n}\n"]}