@blamejs/core 0.11.24 → 0.11.26

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.26 (2026-05-20) — **`b.mail.server.submission` — CHUNKING / BDAT (RFC 3030).** The outbound submission listener now advertises and accepts the RFC 3030 BDAT (binary data) command, the chunked-upload alternative to DATA. Operators with large outbound payloads (attachments, MIME multipart bodies, encoded HTML) no longer pay the dot-stuffing cost of DATA; clients can stream chunks of arbitrary size and finalise with a `BDAT 0 LAST` (or `BDAT N LAST` for the final chunk). Mixing DATA + BDAT within one transaction is refused per RFC 3030 §3. Same `agent.handoff` contract — the body bytes arrive at the agent layer in their canonical SMTP form, no dot-stuffing applied (BDAT payloads are opaque). **Added:** *EHLO advertises `CHUNKING` + new `BDAT <chunk-size> [LAST]` command* — The EHLO 250-line list now includes `CHUNKING` (RFC 3030 §2.1). A new `BDAT` command handler accepts `BDAT <chunk-size> [LAST]` after MAIL FROM + RCPT TO; the server reads exactly `<chunk-size>` bytes from the socket — no dot-stuffing, no end-of-data marker — and acknowledges with `250 2.0.0 <octets> octets received`. Multiple BDAT chunks accumulate into the message body; the final chunk carries the `LAST` keyword and triggers the same agent-handoff path as DATA. A `BDAT 0 LAST` finalises an empty trailer when the last chunk's byte count is unknown in advance. · *Cumulative size cap honoured up-front* — `BDAT <large-size>` is refused with `552 5.3.4 BDAT cumulative size <total> exceeds maxMessageBytes (<cap>)` BEFORE the server begins reading bytes off the wire. A misconfigured client that pipelines `BDAT 999999999 LAST` and 1 GB of body is rejected at the command line, not after the byte stream lands. The collector bound on the receive side enforces the same cap as a backstop. · *Mid-segment payload drainage* — When `BDAT N LAST\r\n<payload>` arrives in one TCP segment (typical for pipelined small messages), the line-loop drains the post-`\r\n` bytes from the command buffer straight into the BDAT collector before returning. Any tail bytes after the BDAT chunk completes get re-fed as the next command. Operators get pipelining + chunking with no extra round-trip cost. **Security:** *BDAT state cleared on every STARTTLS upgrade* — Same threat model as CVE-2021-38371 (Exim) / CVE-2021-33515 (Dovecot): pre-handshake bytes a malicious peer pipelined MUST NOT reach the post-TLS state machine. The STARTTLS handler clears `inBdatChunk` / `bdatRemaining` / `bdatCollector` / `bdatTotalBytes` alongside the existing line-buffer + DATA-collector reset, so a smuggled `BDAT <n>` + body that lands before the TLS upgrade can't bleed into the encrypted transaction. · *Refusal on BDAT outside transaction* — BDAT before MAIL FROM / with zero RCPT returns `503 5.5.1` and does not enter chunk-collection mode. A misbehaving client that issues BDAT eagerly cannot leak state into the next transaction; the RSET reset path also clears all BDAT-side state. · *Pipelining race gate mirrors DATA* — If the operator's `recipientPolicy` is async and not all RCPT verdicts have resolved, BDAT returns `451 4.5.0 RCPT TO verdicts pending; reissue BDAT after recipient replies` — same shape as the DATA pipelining-race gate. The transaction never commits with a partially-resolved recipient set. **References:** [RFC 3030 (SMTP Service Extensions — CHUNKING / BDAT / BINARYMIME)](https://www.rfc-editor.org/rfc/rfc3030.html) · [RFC 5321 (SMTP)](https://www.rfc-editor.org/rfc/rfc5321.html) · [RFC 6409 (Message Submission for Mail)](https://www.rfc-editor.org/rfc/rfc6409.html) · [RFC 8314 (Cleartext considered obsolete — submission ports)](https://www.rfc-editor.org/rfc/rfc8314.html) · [CVE-2021-38371 (Exim STARTTLS injection)](https://nvd.nist.gov/vuln/detail/CVE-2021-38371) · [CVE-2021-33515 (Dovecot STARTTLS pre-handshake state leak)](https://nvd.nist.gov/vuln/detail/CVE-2021-33515)
+
+- v0.11.25 (2026-05-20) — **Five new primitives: sealed-token mail FTS + Stripe HMAC-SHA256 webhook verify + `b.money` + `b.fsm` + `b.auth.botChallenge`.** Five additive primitives in one release. Every consumer building on the framework — mail UIs, billing pipelines, e-commerce backends, multi-step business workflows, public web endpoints — now finds the substrate in-tree instead of reimplementing it. None of these replaces a default; every primitive is opt-in at the call site. Mail full-text search hashes tokens with the per-deployment vault salt before any byte hits the SQLite FTS5 index, so the index is searchable but a database dump leaks nothing readable. The Stripe-shaped HMAC-SHA-256 verifier sits next to the existing PQC and SHA3-512 webhook signers; the `whsec_` prefix stays in the key bytes per Stripe's spec; signatures are constant-time-compared and replay-defended via an operator-supplied nonce store. `b.money` arithmetic is BigInt-only across 40 ISO 4217 currencies with largest-remainder allocation and banker's-rounding FX conversion. `b.fsm` is the in-process sibling of `b.agent.saga` — declarative state + transition definition, guards, async on-enter/on-exit, drop-silent audit on every transition, with a transition-serialisation lock that makes concurrent `.transition()` calls deterministic. `b.auth.botChallenge` composes `b.httpClient` for siteverify against Cloudflare Turnstile (default), hCaptcha, and reCAPTCHA-v3 — the secret bytes never appear in any audit metadata. **Added:** *`b.mailStore.fts` — sealed-token full-text index + `b.mailStore.create().search(folder, filter)`* — Every `appendMessage` now inserts a row into a SQLite FTS5 virtual table whose subject / address / body columns hold space-separated 16-char hex hashes — vault-salted SHA3 over each NFC-normalised token. The salt is the same `b.vault.getDerivedHashSalt()` `b.cryptoField` uses for sealed-column derived hashes, so rotating the vault salt invalidates the FTS index in step with every other sealed-row hash. Query terms go through the same tokenize → hash transform on the search path and issue FTS5 MATCH against the hash-token rows — the index is fully searchable without ever materialising the plaintext on disk. `b.mail.agent.search({ folder, filter })` now accepts `text` / `subject` / `body` / `from` / `to` filter keys; the agent layer hands them to the store. `hardExpunge` deletes the FTS row inside the same transaction as the canonical message row so the two cannot drift. Limits: 8192 tokens / row / field, 2..64 codepoint length band, 8 MiB input cap per field. Exact-token only (no prefix wildcard, no stemmer) — the cost of sealed-at-rest. · *`b.webhook.verify({ alg: 'hmac-sha256-stripe', secret, header, body, toleranceMs?, nonceStore? })` + `b.webhook.sign(...)`* — Stripe-spec inbound webhook signature verifier (Paddle + Shopify use the same shape). Parses `Stripe-Signature: t=<unix>,v1=<hex>[,v1=<hex>...]`, validates the timestamp is within the tolerance window (default 5 min; refuses below 30s), HMAC-SHA-256s `<t>.<body>` with the `whsec_...` secret bytes verbatim (the prefix IS the key — `b.webhook.verify` never strips it), and walks the v1 entries with `b.crypto.timingSafeEqual` so a rotation grace window doesn't leak which entry matched. `b.webhook.sign` is the round-trip companion for outbound Stripe-shaped emission and round-trip tests. Optional `nonceStore: { has(k), set(k, ttlMs) }` records the accepted signature so a replay within the tolerance window refuses. The header value is hard-capped at 4096 bytes and per-`v1` hex at 256 chars (anti-DoS). · *`b.money` — decimal-safe money + 40-currency ISO 4217 catalog* — BigInt minor units throughout — Number is refused at construction. Currency exponents covering 0 (JPY/KRW), 2 (USD/EUR/GBP/…), 3 (KWD/BHD/JOD/OMR/TND), 4 (CLF) are pre-populated. Surface: `b.money.of(amount, code)` / `b.money.fromMinorUnits(bigint, code)` / `b.money.parse('12.50 USD')` / `b.money.zero(code)` plus instance methods `.add` / `.subtract` / `.multiply` / `.allocate(weights[])` / `.negate` / `.abs` / `.equals` / comparison family / `.toMinorUnits()` / `.toString()` / `.toJSON()` / `.format(locale?)`. `b.money.convert(money, toCurrency, fxRateProvider)` rounds half-to-even (banker's rounding) by default. Cross-currency arithmetic throws; `0.10 + 0.20 === 0.30` exactly. Allocation uses largest-remainder so $10 / 3 = [$3.34, $3.33, $3.33] with sum preserved. · *`b.fsm` — in-process state machine (sibling of `b.agent.saga`)* — `b.fsm.define({ name, initial, states, transitions })` returns a frozen machine factory. `Machine.create({ initialContext })` returns an instance with `.state` / `.context` / `.history` / `.allowed()` / `.can(name)` / `.transition(name, opts)` / `.toJSON()`. Transitions carry an optional guard (predicate; refusal throws `fsm/guard-refused`) and trigger per-state `onEnter` / `onExit` side-effects (sync or returned-Promise — `.transition` awaits). Every transition emits a `fsm.<machineName>.transition` audit event via `b.audit.safeEmit` (drop-silent on hot path), including the actor + metadata the caller passed in. A transition lock serialises concurrent `.transition()` calls — the test suite exercises five parallel transitions and verifies only the legal path runs. State + transition names are identifier-shape only (`safeSql.DEFAULT_IDENTIFIER_RE`) so a name never lands in SQL / HTML un-validated. `Machine.restore(snapshot)` rebuilds an instance from a prior `.toJSON()` snapshot — state + history + context survive a process restart. · *`b.auth.botChallenge.create({ secret, provider?, ... }) → { verify(token, opts?) }`* — Server-side challenge-response verifier for Cloudflare Turnstile (default), hCaptcha, and reCAPTCHA-v3. Composes `b.httpClient` for the outbound `/siteverify` POST — every request rides the framework's SSRF guard + DNS pinning + retry policy; the operator's secret never appears in a URL or any audit metadata field. Body encoding is `application/x-www-form-urlencoded` per the provider specs. Returns `{ ok, provider, hostname, action, challengeTs, score?, raw }` on success; throws `BotChallengeError` with structured codes (`invalid-token`, `timeout`, `hostname-mismatch`, `action-mismatch`, `provider-error`) on failure, with the upstream `error-codes` array exposed at `err.errorCodes`. Per-factory `allowedHostnames` + `allowedActions` allowlists; per-call `expectedHostname` + `expectedAction` overrides. Tokens are refused at the factory boundary if empty / non-string / > 4096 bytes, before any outbound call. **Security:** *Mail FTS index leaks zero plaintext (sealed-at-rest invariant extended)* — Pre-v0.11.25, the only operator-facing search path on `b.mail.agent` was a modseq cursor + post-fetch unseal — fast for cursoring but useless for text content discovery. Plaintext-FTS would have broken the sealed-at-rest invariant. The new index hashes every indexed token with the per-deployment vault salt before insert; a `sqlite3 .dump` produces ASCII-hex tokens indistinguishable from random. The same vault salt protects every `b.cryptoField`-sealed column, so adding the FTS index does NOT widen the cryptographic trust boundary. · *Stripe verifier defends the documented attack surface* — Constant-time HMAC compare (timing-safe across the v1 rotation list — operators don't leak which entry matched). Per-`v1` 256-hex anti-DoS cap. Tolerance-window minimum 30s — refuses operator misconfiguration that would accept hour-old signatures. The `whsec_` prefix preservation is encoded as a `codebase-patterns` detector (`stripe-hmac-sha256-no-strip-whsec-prefix`) so re-introducing the strip-bug is impossible without tripping a release gate. · *Bot-challenge secret never reaches audit / logs* — `b.auth.botChallenge` audit emits `{ provider, hostname, ok, errorCodes }` — the operator's secret bytes never appear in any metadata key. A `codebase-patterns` detector (`bot-challenge-secret-not-in-audit`) scans `lib/auth/bot-challenge.js` for any `audit.*emit` window that references `secret` so a future refactor cannot regress. **Detectors:** *Five new `codebase-patterns` detectors encode the shape-specific bug classes* — `stripe-hmac-sha256-no-strip-whsec-prefix` flags `secret.replace(/^whsec_/, '')` / `secret.slice(6)` near an HMAC call (the `whsec_` prefix IS the key). `no-number-money-arithmetic` flags `b.money.of(<Number>, ...)` and Number / Money arithmetic (precision lost; only BigInt / string OK at construction). `fsm-transition-without-await` flags `<fsm>.transition(...)` without `await` or `.then` in `lib/` (the transition is async; sync misuse swallows errors). `bot-challenge-secret-not-in-audit` is file-scoped to `lib/auth/bot-challenge.js` and flags any `audit.*emit` window or `metadata: { ... }` object literal referencing `secret`. Each detector is wired into `codebase-patterns.test.js`'s `run()` so every future commit re-checks the shape. **References:** [RFC 2104 (HMAC)](https://www.rfc-editor.org/rfc/rfc2104.html) · [RFC 6234 (US Secure Hash Algorithms — SHA-256)](https://www.rfc-editor.org/rfc/rfc6234.html) · [Stripe webhook signature spec](https://docs.stripe.com/webhooks/signature) · [Paddle webhook signature verification](https://developer.paddle.com/webhooks/signature-verification) · [Shopify webhooks — HMAC verification](https://shopify.dev/docs/apps/webhooks/configuration/https) · [ISO 4217 (Currency codes + minor unit catalog)](https://www.iso.org/iso-4217-currency-codes.html) · [IEEE 754 (the float-precision problem `b.money` avoids)](https://standards.ieee.org/standard/754-2019.html) · [Cloudflare Turnstile — server-side validation](https://developers.cloudflare.com/turnstile/get-started/server-side-validation/) · [hCaptcha — verify the user response server-side](https://docs.hcaptcha.com/) · [reCAPTCHA-v3 — server-side verification](https://developers.google.com/recaptcha/docs/v3) · [OWASP ASVS v5 §11.5 — bot defense controls](https://owasp.org/www-project-application-security-verification-standard/) · [RFC 9051 (IMAP4rev2 — SEARCH semantics)](https://www.rfc-editor.org/rfc/rfc9051.html) · [RFC 8621 (JMAP Mail — Email/query)](https://www.rfc-editor.org/rfc/rfc8621.html) · [SQLite FTS5](https://www.sqlite.org/fts5.html) · [UML State Machine (OMG UML 2.5.1 §14)](https://www.omg.org/spec/UML/2.5.1)
+
 - v0.11.24 (2026-05-20) — **`b.mail.send.deliver` — turnkey outbound SMTP composer (MX → MTA-STS → DANE → REQUIRETLS → DSN).** One factory wires together the full outbound mail chain. The operator hands the primitive an envelope (`{ from, to, rfc822 }`) and gets back per-recipient outcomes: `delivered`, `deferred` (with retry budget), or `failed` (with the corresponding RFC 3464 DSN already composed and the configured DSN sink invoked). Per-recipient handling is independent — one recipient permanently failing does not interfere with another's delivery or retry. MX records are resolved live (operator may inject a resolver for testing), MTA-STS policy (RFC 8461) is fetched + matched against the resolved MX before TLS, DANE TLSA records (RFC 7672) are consulted when present, REQUIRETLS (RFC 8689) is honored, and the per-host SMTP transport is the framework's `b.mail.smtpTransport`. SMTP outcomes are classified deterministically: hard 5xx + null-MX → permanent (with DSN); soft 4xx + DNS / connect / TLS errors → transient (with backoff budget). Recipient cap (1000 per call) and per-host / per-lookup timeout caps are baked in. **Added:** *`b.mail.send.deliver.create(opts) → async deliver(envelope)` — composed outbound delivery* — Factory returns a `deliver(envelope)` async function. `envelope = { from, to[], rfc822 }`. Returns `{ delivered: [{...}], deferred: [{...}], failed: [{...}] }`. Composes `b.network.smtp.policy.mtaSts.fetch` + `.matchMx`, `b.network.smtp.policy.dane.tlsa` + `.verifyChain`, `b.mail.smtpTransport.create`, and `b.audit.safeEmit`. Required opts: `hostname` (EHLO + MAIL FROM identity). Optional: `resolver` (object exposing `resolveMx` / `resolve` — defaults to node:dns/promises); `policy.mtaSts.enabled` (default true); `policy.dane.enabled` (default true); `retry.maxAttempts` (default 5); `retry.backoffMs` (default exponential 60s/5m/30m/2h/12h); `dsn.from` + `dsn.onPermanentFailure(messageBuffer, ctx)` (required only when DSN delivery is desired); `timeouts.mxLookupMs` (default 5s); `timeouts.perHostMs` (default 60s); `transportFactory` (test-injection override). · *Per-recipient outcome classifier (`_classifySmtpOutcome`)* — Maps SMTP reply codes + Node socket / TLS errors onto the `permanent` / `transient` axis. Permanent: SMTP 5xx (any subclass), null-MX RFC 7505 sentinel `.`, no-MX-records, RFC 5321 §3.6.2 unrouteable. Transient: SMTP 4xx (any subclass), TCP connection refused / reset / timeout, TLS handshake failure (when MTA-STS / DANE is not enforce-mode), DNS NXDOMAIN at lookup time. Once `retry.maxAttempts` is exhausted, transient is escalated to permanent with reason `retry exhausted (after N attempts)`. · *RFC 3464 DSN composer (`_buildDsnMessage`)* — Builds a `multipart/report; report-type=delivery-status` message with three parts: human-readable explanation, `message/delivery-status` block (Reporting-MTA, Original-Recipient, Final-Recipient, Action: failed, Status: 5.x.x), and a `message/rfc822-headers` block carrying the failed message's headers. Boundary token is generated via `b.crypto.generateToken(12)` so it can't collide with attacker-chosen header / body bytes. The composed DSN is passed to the operator-supplied `dsn.onPermanentFailure(message, ctx)` sink — the primitive does not itself send the DSN, keeping the operator in control of which transport carries DSNs (typically the same submission service). · *MX failover + per-host audit* — MX records are walked in priority order. A failed connect / TLS / 4xx on the first host falls over to the next; only when every MX has been tried does the recipient receive its final outcome. Each per-host failure emits a structured audit event (`mail.send.deliver.host-fail` with `recipient` + `mxHost` + `priority` + `reason`); the final outcome emits `mail.send.deliver.delivered` / `.deferred` / `.permanent-fail`. Audit is drop-silent on the hot path (catch + ignore). · *Recipient + envelope hard caps* — `MAX_RECIPIENTS_PER_CALL = 1000` refuses oversized fan-out at the factory boundary (5xx-style DoS prevention). `envelope.rfc822` accepts a Buffer or UTF-8 string — strings are converted at the boundary so downstream byte-level reasoning (DKIM, REQUIRETLS, length headers) sees stable bytes. Bad-envelope refusals carry `DeliverError` codes `deliver/bad-envelope`, `/bad-envelope-from`, `/bad-envelope-to`, `/too-many-recipients`, `/bad-envelope-rfc822` — operators get structured surface for each refusal class. **Security:** *MTA-STS enforcement before TLS handshake (RFC 8461)* — When `policy.mtaSts.enabled` (default), MTA-STS policy is fetched for the recipient domain. If the policy mode is `enforce` and a resolved MX hostname does not match an `mx:` entry, the host is refused without attempting TLS. This closes the MX-substitution attack window (`b.mail.send.deliver` cannot be diverted to an attacker-controlled MX even when DNS is hijacked, as long as the recipient publishes MTA-STS). · *DANE TLSA verification when present (RFC 7672)* — When `policy.dane.enabled` (default) and the recipient domain publishes TLSA records, the SMTP transport's TLS certificate chain is verified against the TLSA hash before the SMTP command pipeline starts. TLSA records take precedence over PKIX trust roots for SMTP — RFC 7672 §2.2. · *Boundary token unguessable (DSN boundary-injection defense)* — MIME boundary token in composed DSNs is 12 random bytes hex-encoded via `b.crypto.generateToken` (SHAKE256 over OS-RNG) — not `Date.now()` + `Math.random()`. The boundary appears verbatim in the message; a predictable boundary would let an attacker who controls the failed message's headers craft byte sequences that close the boundary early + inject MIME parts. **Detectors:** *`per-recipient-loop-fallthrough-to-failed` (codebase-patterns)* — A new detector flags per-recipient delivery loops where the `delivered` branch does not exit the iteration before falling into the permanent-failure / DSN-emit path. Encodes the bug class that was caught during this slice's bring-up — a recipient delivering successfully also being added to `failed[]` because the `if (delivered)` branch lacked an explicit `continue`. **References:** [RFC 5321 (Simple Mail Transfer Protocol)](https://www.rfc-editor.org/rfc/rfc5321.html) · [RFC 3464 (Extensible Message Format for Delivery Status Notifications)](https://www.rfc-editor.org/rfc/rfc3464.html) · [RFC 7505 (Null MX no-service resource record)](https://www.rfc-editor.org/rfc/rfc7505.html) · [RFC 8461 (SMTP MTA Strict Transport Security — MTA-STS)](https://www.rfc-editor.org/rfc/rfc8461.html) · [RFC 7672 (SMTP Security via Opportunistic DANE TLS)](https://www.rfc-editor.org/rfc/rfc7672.html) · [RFC 8689 (SMTP REQUIRETLS option)](https://www.rfc-editor.org/rfc/rfc8689.html) · [RFC 3463 (Enhanced Mail System Status Codes)](https://www.rfc-editor.org/rfc/rfc3463.html)
 
 - v0.11.23 (2026-05-20) — **`b.mail.agent.expunge` — hard EXPUNGE with legal-hold + retention-floor refusal gates.** Operators (and the future IMAP EXPUNGE + JMAP Email/set destroyed wire-protocol adapters) get a single canonical path for permanent message removal that refuses to delete anything currently under legal hold or still inside the regulator-mandated retention window. The gate runs per-message; refused ids carry an explicit reason (`legal-hold` / `retention-floor` / `not-in-folder`) plus the floor + age + posture metadata that drove the refusal — wire adapters mirror those reasons to operators verbatim. The destructive SQL runs only on the surviving id set, inside a backend transaction that also bumps folder modseq + decrements quota atomically. **Added:** *`b.mail.agent.expunge({ actor, folder, objectIds })` — hard EXPUNGE primitive* — Composes two refusal gates before the destructive SQL runs. (1) Legal-hold gate: any message whose `legal_hold` flag is set refuses with reason `legal-hold`. The mail-store layer surfaces the flag in per-row metadata; this layer maps it to the operator-facing refusal. (2) Retention-floor gate: under a configured compliance posture (`hipaa` / `pci-dss` / `gdpr` / `soc2`), the regulator-mandated minimum retention TTL is read from `b.retention.COMPLIANCE_RETENTION_FLOOR_MS[posture]` and any message whose age (`now - receivedAt`) is below the floor refuses with reason `retention-floor` plus `floorMs` + `ageMs` + `posture` metadata. Returns `{ deleted: <ids>, refused: [{ id, reason, ... }] }`. Audit event `mail.agent.expunge.success` carries the requested / deleted / refused counts and a reason histogram so dashboards can spot abnormal refusal patterns without parsing per-id detail. · *`b.mailStore.create(...).hardExpunge(folder, objectIds)` — destructive SQL primitive* — Removes messages permanently from a folder inside a single backend transaction: deletes the message row + its flag rows, bumps the folder modseq, decrements the per-folder quota by the freed bytes / count. Returns `{ rows, deleted, refused }` where `refused` carries `{ id, reason: 'legal-hold' | 'not-in-folder' }` for each id the SQL gate refused (legal-hold is mirrored from the column; not-in-folder catches stale ids). The agent layer (`b.mail.agent.expunge`) is responsible for the retention-floor gate; this primitive is the wire-protocol-shaped backend surface. · *`b.mailStore.create(...).fetchByObjectId` returns `legalHold: boolean`* — Pre-existing fetch path now consistently exposes the legal-hold flag in its return shape. Previously the field existed in the returned object via a separate path; this commit consolidates the duplicate exports into a single canonical `legalHold` boolean derived from the SQLite `legal_hold` INTEGER column. **References:** [RFC 9051 (IMAP4rev2 — EXPUNGE semantics, §6.4.3)](https://www.rfc-editor.org/rfc/rfc9051.html) · [RFC 8621 (JMAP Mail — Email/set destroyed)](https://www.rfc-editor.org/rfc/rfc8621.html) · [45 CFR §164.316 (HIPAA — retention of records)](https://www.ecfr.gov/current/title-45/subtitle-A/subchapter-C/part-164/subpart-C/section-164.316) · [PCI-DSS v4.0.1 §3.5.1.1 (retention of cardholder data)](https://www.pcisecuritystandards.org/document_library) · [GDPR Art. 17 (right to erasure — operator-side accountability)](https://gdpr-info.eu/art-17-gdpr/)

package/index.js

@@ -204,6 +204,8 @@ var agentStream = require("./lib/agent-stream");
 var agentEventBus = require("./lib/agent-event-bus");
 var agentTenant = require("./lib/agent-tenant");
 var agentSaga = require("./lib/agent-saga");
+var fsm = require("./lib/fsm");
+var money = require("./lib/money");
 var agentPostureChain = require("./lib/agent-posture-chain");
 var agentTrace = require("./lib/agent-trace");
 var agentSnapshot = require("./lib/agent-snapshot");
@@ -256,6 +258,7 @@ var auth = {
   oid4vp:           require("./lib/auth/oid4vp"),
   saml:             require("./lib/auth/saml"),
   openidFederation: require("./lib/auth/openid-federation"),
+  botChallenge:     require("./lib/auth/bot-challenge"),
 };
 var template = require("./lib/template");
 var render = require("./lib/render");
@@ -531,6 +534,8 @@ module.exports = {
   guardTraceContext: guardTraceContext,
   guardSnapshotEnvelope: guardSnapshotEnvelope,
   agent:            { orchestrator: agentOrchestrator, idempotency: agentIdempotency, stream: agentStream, eventBus: agentEventBus, tenant: agentTenant, saga: agentSaga, postureChain: agentPostureChain, trace: agentTrace, snapshot: agentSnapshot },
+  fsm:              fsm,
+  money:            money,
   guardArchive:     guardArchive,
   guardJson:        guardJson,
   guardYaml:        guardYaml,

package/lib/auth/bot-challenge.js

@@ -0,0 +1,573 @@
+"use strict";
+/**
+ * @module     b.auth.botChallenge
+ * @nav        Identity
+ * @title      Bot Challenge Verifier
+ * @order      375
+ *
+ * @intro
+ *   Server-side verifier for the modern privacy-preserving bot-
+ *   challenge widgets: Cloudflare Turnstile, hCaptcha, and Google
+ *   reCAPTCHA v3. The client-side widget produces a short-lived
+ *   token; the server POSTs that token (along with the operator's
+ *   secret + optionally the remote IP) to the provider's siteverify
+ *   endpoint and inspects the verdict.
+ *
+ *   Why a verifier and not a heuristic — `b.middleware.botGuard`
+ *   inspects User-Agent / Accept-Language / fetch-metadata for
+ *   stale crawlers, but a determined adversary forges those bytes
+ *   trivially. A widget-issued token is a cryptographic claim from
+ *   the provider that the request originated from a human (or a
+ *   passable approximation under reCAPTCHA-v3's score model).
+ *
+ *   The verifier:
+ *
+ *     - POSTs the token via `b.httpClient` — every outbound hop
+ *       goes through `b.ssrfGuard` + the framework's DNS pinning,
+ *       so a redirect to a cloud-metadata endpoint can't smuggle
+ *       past the first-hop gate. Raw `node:http` / `node:https` /
+ *       global `fetch` is never used.
+ *     - Sends the secret in the POST body as
+ *       `application/x-www-form-urlencoded` (Cloudflare's
+ *       documented shape). The secret never appears in the URL,
+ *       query string, headers, log lines, or audit metadata.
+ *     - Refuses a token that is not a non-empty string under
+ *       `MAX_TOKEN_BYTES` (4 KiB) — Cloudflare tokens cap around
+ *       2 KiB; a 1 MiB "token" is operator misuse or an attack.
+ *     - Validates `success === true` AND (when configured)
+ *       hostname-in-allowlist AND action-in-allowlist before
+ *       returning. The provider's hostname / action fields are
+ *       embedded in the token by the widget; operators using
+ *       multi-domain or multi-action deployments allowlist the
+ *       expected values to refuse cross-site token replay.
+ *     - For reCAPTCHA-v3, exposes the `score` (0.0–1.0) on the
+ *       success shape so the operator can threshold per-route.
+ *     - Audits every verify call drop-silent via
+ *       `b.audit.safeEmit` (action `auth.bot_challenge.verify`,
+ *       outcome `success` / `failure`, metadata
+ *       `{ provider, hostname?, ok, errorCodes? }`). The token
+ *       and secret NEVER appear in audit metadata; only the
+ *       token's 8-char prefix surfaces, and only when the operator
+ *       has opted into trace-level metadata.
+ *
+ *   Compose with `b.authBotChallenge` (the adaptive staircase gate)
+ *   by passing the verifier's `verify` function as the staircase's
+ *   `challengeFn` — failed-auth attempts ride the staircase up to
+ *   the challenge stage, the operator renders the Turnstile widget,
+ *   and the verifier validates the resulting token. The two
+ *   primitives are deliberately separate concerns.
+ *
+ *   References:
+ *     - Cloudflare Turnstile siteverify
+ *       https://developers.cloudflare.com/turnstile/get-started/server-side-validation/
+ *     - hCaptcha siteverify
+ *       https://docs.hcaptcha.com/#verify-the-user-response-server-side
+ *     - reCAPTCHA v3 siteverify
+ *       https://developers.google.com/recaptcha/docs/v3
+ *     - OWASP ASVS v5 §11.5 (bot-defense controls)
+ *     - RFC 6749 §4.1.3 (`application/x-www-form-urlencoded` body
+ *       conventions for OAuth-style endpoints)
+ *
+ * @card
+ *   Server-side verifier for Cloudflare Turnstile / hCaptcha / reCAPTCHA-v3 widget tokens with SSRF-guarded outbound, hostname + action allowlists, and drop-silent audit.
+ */
+
+var nodeQuerystring = require("node:querystring");
+
+var lazyRequire  = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+var safeJson     = require("../safe-json");
+var C            = require("../constants");
+var { BotChallengeError } = require("../framework-error");
+
+var httpClient = lazyRequire(function () { return require("../http-client"); });
+var audit      = lazyRequire(function () { return require("../audit"); });
+
+// ---- constants ----
+
+// Token byte ceiling. Turnstile tokens hover around 2 KiB; hCaptcha is
+// similar; reCAPTCHA-v3 tokens are slightly larger but well under 4 KiB.
+// A token that exceeds this cap is operator misuse (passed the wrong
+// field) or a probe — refuse at the boundary rather than forwarding
+// kilobytes of operator-supplied bytes to the provider.
+var MAX_TOKEN_BYTES   = C.BYTES.kib(4);
+
+// Default wall-clock timeout for the siteverify round-trip. Five seconds
+// is the documented Cloudflare service-level target with healthy
+// headroom; operators can override per-call but cannot drop below
+// MIN_TIMEOUT_MS without the create() factory refusing the opts.
+var DEFAULT_TIMEOUT_MS = C.TIME.seconds(5);
+var MIN_TIMEOUT_MS     = 500; // anti-misconfiguration floor              // allow:raw-byte-literal — 500ms wall-clock floor, not a byte literal
+
+// Response-body cap. Provider siteverify responses are small JSON
+// (well under 4 KiB); a multi-MiB response is either a redirect to
+// HTML (shouldn't happen — providers terminate JSON-only) or an
+// attacker-shaped probe via DNS poisoning.
+var MAX_RESPONSE_BYTES = C.BYTES.kib(64);
+
+// Allowed siteverify response Content-Type — providers return
+// `application/json` (Cloudflare + hCaptcha) or
+// `application/json; charset=utf-8` (Google). The verifier rejects
+// other content types rather than attempting to parse arbitrary bodies.
+var EXPECTED_CONTENT_TYPE_PREFIX = "application/json";
+
+// Number of characters of the token's prefix that surface in audit
+// metadata for diagnosability. Eight characters is small enough that
+// the surfaced bytes are not the secret token (≈ 48 bits visible vs.
+// ~2 KiB total), but large enough to cluster verifications belonging
+// to the same widget render in a debug session.
+var TOKEN_PREFIX_AUDIT_CHARS = 8;                                          // allow:raw-byte-literal — debug-prefix length, not a byte literal
+
+// ---- provider catalog ----
+//
+// Each provider entry exposes:
+//   endpoint        — the siteverify URL (https only)
+//   contentTypeBody — the POST body's Content-Type
+//   parseResponse(body, raw) → { ok, hostname, action, ts, score?, errorCodes }
+//
+// The parseResponse contract is uniform across providers even though
+// each provider's response shape differs slightly. Cloudflare /
+// hCaptcha return `{ success, hostname, action, challenge_ts,
+// "error-codes" }`; Google reCAPTCHA-v3 also returns `score` (and
+// `action` is REQUIRED for v3).
+//
+// Each parseResponse normalises the raw body into the unified shape.
+// `errorCodes` is always an array of strings (possibly empty); `ok`
+// reflects the provider's success flag verbatim with no operator-
+// configurable bypass.
+
+function _parseCloudflareLike(rawObj) {
+  var errorCodes = [];
+  var raw = rawObj && typeof rawObj === "object" ? rawObj : {};
+  if (Array.isArray(raw["error-codes"])) {
+    for (var i = 0; i < raw["error-codes"].length; i++) {
+      var ec = raw["error-codes"][i];
+      if (typeof ec === "string") errorCodes.push(ec);
+    }
+  }
+  return {
+    ok:          raw.success === true,
+    hostname:    typeof raw.hostname === "string" ? raw.hostname : null,
+    action:      typeof raw.action === "string" ? raw.action : null,
+    challengeTs: typeof raw.challenge_ts === "string" ? raw.challenge_ts : null,
+    score:       null,
+    errorCodes:  errorCodes,
+  };
+}
+
+function _parseRecaptchaV3(rawObj) {
+  var base = _parseCloudflareLike(rawObj);
+  var raw = rawObj && typeof rawObj === "object" ? rawObj : {};
+  if (typeof raw.score === "number" && isFinite(raw.score)) {
+    base.score = raw.score;
+  }
+  return base;
+}
+
+var PROVIDERS = Object.freeze({
+  "turnstile": Object.freeze({
+    endpoint:        "https://challenges.cloudflare.com/turnstile/v0/siteverify",
+    contentTypeBody: "application/x-www-form-urlencoded",
+    parseResponse:   _parseCloudflareLike,
+  }),
+  "hcaptcha": Object.freeze({
+    endpoint:        "https://api.hcaptcha.com/siteverify",
+    contentTypeBody: "application/x-www-form-urlencoded",
+    parseResponse:   _parseCloudflareLike,
+  }),
+  "recaptcha-v3": Object.freeze({
+    endpoint:        "https://www.google.com/recaptcha/api/siteverify",
+    contentTypeBody: "application/x-www-form-urlencoded",
+    parseResponse:   _parseRecaptchaV3,
+  }),
+});
+
+var DEFAULT_PROVIDER = "turnstile";
+
+var ALLOWED_CREATE_OPTS = [
+  "secret", "provider", "httpClient", "timeoutMs",
+  "allowedHostnames", "allowedActions", "audit",
+];
+
+var ALLOWED_VERIFY_OPTS = [
+  "remoteIp", "expectedAction", "expectedHostname",
+];
+
+// ---- helpers ----
+
+function _requireNonEmptyString(name, val) {
+  if (typeof val !== "string" || val.length === 0) {
+    throw new BotChallengeError("bot-challenge/bad-opt",
+      name + ": expected non-empty string, got " + typeof val);
+  }
+}
+
+function _normaliseAllowlist(name, val) {
+  if (val === undefined || val === null) return null;
+  if (!Array.isArray(val)) {
+    throw new BotChallengeError("bot-challenge/bad-opt",
+      name + ": expected array of strings or null/undefined, got " + typeof val);
+  }
+  var out = [];
+  for (var i = 0; i < val.length; i++) {
+    var entry = val[i];
+    if (typeof entry !== "string" || entry.length === 0) {
+      throw new BotChallengeError("bot-challenge/bad-opt",
+        name + "[" + i + "]: expected non-empty string");
+    }
+    out.push(entry);
+  }
+  if (out.length === 0) {
+    throw new BotChallengeError("bot-challenge/bad-opt",
+      name + ": allowlist must contain at least one entry when set");
+  }
+  return Object.freeze(out);
+}
+
+function _httpClientShape(client, callerLabel) {
+  if (client === undefined || client === null) return null;
+  if (typeof client !== "object" || typeof client.request !== "function") {
+    throw new BotChallengeError("bot-challenge/bad-opt",
+      callerLabel + ": httpClient must be a b.httpClient-shaped object (request fn)");
+  }
+  return client;
+}
+
+function _normaliseTimeoutMs(val) {
+  if (val === undefined || val === null) return DEFAULT_TIMEOUT_MS;
+  if (typeof val !== "number" || !isFinite(val) || val < MIN_TIMEOUT_MS ||
+      Math.floor(val) !== val) {
+    throw new BotChallengeError("bot-challenge/bad-opt",
+      "timeoutMs: expected integer >= " + MIN_TIMEOUT_MS + " ms, got " +
+      JSON.stringify(val));
+  }
+  return val;
+}
+
+function _byteLengthOf(s) {
+  // Conservative UTF-8 byte count. Buffer.byteLength is the right
+  // tool here because Turnstile tokens are ASCII-base64url today —
+  // but the contract is in bytes, not chars.
+  return Buffer.byteLength(s, "utf8");
+}
+
+function _isTimeoutError(err) {
+  if (!err) return false;
+  if (err.code === "TIMEOUT" || err.code === "WALL_CLOCK_TIMEOUT" ||
+      err.code === "IDLE_TIMEOUT") return true;
+  if (err.name === "AbortError") return true;
+  var msg = err.message || "";
+  return /timeout|timed out|aborted/i.test(msg);
+}
+
+function _safeAudit(safeEmit, action, outcome, metadata) {
+  if (typeof safeEmit !== "function") return;
+  try {
+    safeEmit({
+      action:   action,
+      outcome:  outcome,
+      metadata: metadata || {},
+    });
+  } catch (_e) { /* drop-silent — audit is best-effort */ }
+}
+
+function _resolveAuditSafeEmit(auditOpt) {
+  // Operator-supplied audit takes precedence (mirrors `b.audit` shape).
+  // Fall back to the framework's global `b.audit` via lazyRequire so
+  // the verifier emits without explicit wiring. Drop-silent on every
+  // failure path (per validation-tier rule §5, hot-path observability
+  // sinks NEVER throw).
+  if (auditOpt && typeof auditOpt.safeEmit === "function") {
+    return auditOpt.safeEmit.bind(auditOpt);
+  }
+  try {
+    var global = audit();
+    if (global && typeof global.safeEmit === "function") {
+      return global.safeEmit.bind(global);
+    }
+  } catch (_e) { /* no global audit available */ }
+  return null;
+}
+
+// ---- public surface ----
+
+/**
+ * @primitive  b.auth.botChallenge.create
+ * @signature  b.auth.botChallenge.create(opts)
+ * @since      0.11.25
+ * @status     stable
+ * @compliance gdpr, soc2
+ * @related    b.authBotChallenge.create, b.middleware.botGuard, b.httpClient
+ *
+ * Build a server-side verifier for a bot-challenge widget token.
+ * Returns `{ verify(token, verifyOpts?) }`. The factory throws on
+ * malformed opts; `verify` throws a typed `BotChallengeError` on
+ * any verification failure and resolves on success.
+ *
+ * @opts
+ *   secret:            string,    // provider-issued site secret — preserved verbatim
+ *   provider:          string,    // "turnstile" | "hcaptcha" | "recaptcha-v3" (default "turnstile")
+ *   httpClient:        Object,    // b.httpClient-shaped { request } — default: framework http-client
+ *   timeoutMs:         number,    // wall-clock cap for the siteverify call (default 5_000; minimum 500)
+ *   allowedHostnames:  string[],  // optional hostname allowlist — verify refuses tokens whose embedded hostname is absent
+ *   allowedActions:    string[],  // optional action allowlist — verify refuses tokens whose embedded action is absent
+ *   audit:             Object,    // optional b.audit-shaped sink; defaults to framework global b.audit
+ *
+ * @example
+ *   var verifier = b.auth.botChallenge.create({
+ *     secret:            process.env.TURNSTILE_SECRET,
+ *     provider:          "turnstile",
+ *     allowedHostnames:  ["app.example.com"],
+ *     allowedActions:    ["login", "signup"],
+ *   });
+ *
+ *   // In a login handler:
+ *   try {
+ *     var verdict = await verifier.verify(req.body["cf-turnstile-response"], {
+ *       remoteIp:         b.requestHelpers.clientIp(req),
+ *       expectedAction:   "login",
+ *     });
+ *     // verdict.ok === true; verdict.hostname / verdict.action / verdict.challengeTs populated.
+ *   } catch (e) {
+ *     // e instanceof b.auth.botChallenge.BotChallengeError
+ *     // e.code === "bot-challenge/invalid-token" (or hostname-mismatch / timeout / etc.)
+ *   }
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ALLOWED_CREATE_OPTS, "auth.botChallenge.create");
+
+  _requireNonEmptyString("secret", opts.secret);
+  // Preserve the secret verbatim — provider secrets are
+  // case-sensitive and carry no canonical-form transformation rule.
+  var secret = opts.secret;
+
+  var providerKey = opts.provider !== undefined ? opts.provider : DEFAULT_PROVIDER;
+  if (typeof providerKey !== "string" || !PROVIDERS[providerKey]) {
+    var supported = Object.keys(PROVIDERS).join(", ");
+    throw new BotChallengeError("bot-challenge/bad-opt",
+      "provider: expected one of [" + supported + "], got " + JSON.stringify(providerKey));
+  }
+  var providerSpec = PROVIDERS[providerKey];
+
+  var client = _httpClientShape(opts.httpClient, "auth.botChallenge.create") || httpClient();
+  var timeoutMs = _normaliseTimeoutMs(opts.timeoutMs);
+  var allowedHostnames = _normaliseAllowlist("allowedHostnames", opts.allowedHostnames);
+  var allowedActions   = _normaliseAllowlist("allowedActions",   opts.allowedActions);
+
+  if (opts.audit !== undefined) {
+    validateOpts.auditShape(opts.audit, "auth.botChallenge.create", BotChallengeError);
+  }
+  var safeEmit = _resolveAuditSafeEmit(opts.audit);
+
+  async function verify(token, verifyOpts) {
+    verifyOpts = verifyOpts || {};
+    validateOpts(verifyOpts, ALLOWED_VERIFY_OPTS, "auth.botChallenge.verify");
+
+    var tokenPrefix = (typeof token === "string"
+      ? token.slice(0, TOKEN_PREFIX_AUDIT_CHARS)
+      : "");
+
+    // Boundary refusals — every reject here is typed + audited.
+    if (typeof token !== "string" || token.length === 0) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "empty-token",
+      });
+      throw new BotChallengeError("bot-challenge/invalid-token",
+        "token must be a non-empty string");
+    }
+    if (_byteLengthOf(token) > MAX_TOKEN_BYTES) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "token-too-large",
+        prefix: tokenPrefix,
+      });
+      throw new BotChallengeError("bot-challenge/invalid-token",
+        "token exceeds " + MAX_TOKEN_BYTES + " bytes");
+    }
+
+    var expectedAction = verifyOpts.expectedAction !== undefined
+      ? verifyOpts.expectedAction : null;
+    if (expectedAction !== null && (typeof expectedAction !== "string" ||
+        expectedAction.length === 0)) {
+      throw new BotChallengeError("bot-challenge/bad-opt",
+        "expectedAction: expected non-empty string");
+    }
+    var expectedHostname = verifyOpts.expectedHostname !== undefined
+      ? verifyOpts.expectedHostname : null;
+    if (expectedHostname !== null && (typeof expectedHostname !== "string" ||
+        expectedHostname.length === 0)) {
+      throw new BotChallengeError("bot-challenge/bad-opt",
+        "expectedHostname: expected non-empty string");
+    }
+    if (verifyOpts.remoteIp !== undefined && verifyOpts.remoteIp !== null &&
+        (typeof verifyOpts.remoteIp !== "string" || verifyOpts.remoteIp.length === 0)) {
+      throw new BotChallengeError("bot-challenge/bad-opt",
+        "remoteIp: expected non-empty string when set");
+    }
+
+    // Compose the application/x-www-form-urlencoded body. The secret
+    // is in the body — never the URL/query/headers/audit metadata.
+    var bodyFields = { secret: secret, response: token };
+    if (verifyOpts.remoteIp) bodyFields.remoteip = verifyOpts.remoteIp;
+    var body = nodeQuerystring.stringify(bodyFields);
+
+    var res;
+    try {
+      res = await client.request({
+        method:    "POST",
+        url:       providerSpec.endpoint,
+        body:      body,
+        headers:   { "Content-Type": providerSpec.contentTypeBody },
+        timeoutMs: timeoutMs,
+        maxBytes:  MAX_RESPONSE_BYTES,
+      });
+    } catch (e) {
+      if (_isTimeoutError(e)) {
+        _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+          provider: providerKey, ok: false, reason: "timeout",
+          prefix: tokenPrefix,
+        });
+        throw new BotChallengeError("bot-challenge/timeout",
+          "siteverify timed out after " + timeoutMs + " ms");
+      }
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "transport",
+        prefix: tokenPrefix,
+        // Surface the underlying message but not the secret/token bytes.
+        message: (e && e.message) || String(e),
+      });
+      throw new BotChallengeError("bot-challenge/transport-error",
+        "siteverify transport failure: " + ((e && e.message) || String(e)));
+    }
+
+    if (res.statusCode < 200 || res.statusCode >= 300) {                  // allow:raw-byte-literal — HTTP 2xx range bounds
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "non-2xx",
+        statusCode: res.statusCode, prefix: tokenPrefix,
+      });
+      throw new BotChallengeError("bot-challenge/provider-error",
+        "siteverify returned non-2xx status " + res.statusCode);
+    }
+
+    // Defensive Content-Type guard — providers return JSON.
+    var ctHeader = (res.headers && (res.headers["content-type"] ||
+                                     res.headers["Content-Type"])) || "";
+    if (typeof ctHeader !== "string" ||
+        ctHeader.toLowerCase().indexOf(EXPECTED_CONTENT_TYPE_PREFIX) !== 0) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "bad-content-type",
+        contentType: ctHeader, prefix: tokenPrefix,
+      });
+      throw new BotChallengeError("bot-challenge/provider-error",
+        "siteverify returned non-JSON Content-Type: " + ctHeader);
+    }
+
+    var raw;
+    try {
+      var bodyText = Buffer.isBuffer(res.body)
+        ? res.body.toString("utf8")
+        : String(res.body || "");
+      raw = safeJson.parse(bodyText, { maxBytes: MAX_RESPONSE_BYTES });
+    } catch (e) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "parse-error",
+        prefix: tokenPrefix,
+      });
+      throw new BotChallengeError("bot-challenge/provider-error",
+        "siteverify response parse failed: " + ((e && e.message) || String(e)));
+    }
+
+    var parsed = providerSpec.parseResponse(raw, res);
+
+    if (!parsed.ok) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider:   providerKey, ok: false, reason: "provider-rejected",
+        errorCodes: parsed.errorCodes, hostname: parsed.hostname,
+        prefix:     tokenPrefix,
+      });
+      var err = new BotChallengeError("bot-challenge/invalid-token",
+        "siteverify rejected token: " +
+        (parsed.errorCodes.length ? parsed.errorCodes.join(",") : "(no error-codes)"));
+      err.errorCodes = parsed.errorCodes;
+      throw err;
+    }
+
+    // Hostname allowlist — factory-configured allowlist OR per-call
+    // expectedHostname (the per-call value overrides the allowlist for
+    // exact-match in the same call but does not relax the allowlist).
+    if (allowedHostnames && (!parsed.hostname ||
+        allowedHostnames.indexOf(parsed.hostname) === -1)) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "hostname-mismatch",
+        hostname: parsed.hostname, prefix: tokenPrefix,
+      });
+      throw new BotChallengeError("bot-challenge/hostname-mismatch",
+        "hostname '" + parsed.hostname + "' not in allowedHostnames");
+    }
+    if (expectedHostname !== null && parsed.hostname !== expectedHostname) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "hostname-mismatch",
+        hostname: parsed.hostname, expectedHostname: expectedHostname,
+        prefix:   tokenPrefix,
+      });
+      throw new BotChallengeError("bot-challenge/hostname-mismatch",
+        "hostname '" + parsed.hostname + "' does not match expectedHostname '" +
+        expectedHostname + "'");
+    }
+
+    // Action allowlist — same shape as hostname.
+    if (allowedActions && (!parsed.action ||
+        allowedActions.indexOf(parsed.action) === -1)) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "action-mismatch",
+        action: parsed.action, hostname: parsed.hostname,
+        prefix:   tokenPrefix,
+      });
+      throw new BotChallengeError("bot-challenge/action-mismatch",
+        "action '" + parsed.action + "' not in allowedActions");
+    }
+    if (expectedAction !== null && parsed.action !== expectedAction) {
+      _safeAudit(safeEmit, "auth.bot_challenge.verify", "failure", {
+        provider: providerKey, ok: false, reason: "action-mismatch",
+        action: parsed.action, expectedAction: expectedAction,
+        hostname: parsed.hostname, prefix: tokenPrefix,
+      });
+      throw new BotChallengeError("bot-challenge/action-mismatch",
+        "action '" + parsed.action + "' does not match expectedAction '" +
+        expectedAction + "'");
+    }
+
+    var successMeta = {
+      provider:   providerKey, ok: true,
+      hostname:   parsed.hostname, action: parsed.action,
+      prefix:     tokenPrefix,
+    };
+    if (parsed.score !== null) successMeta.score = parsed.score;
+    _safeAudit(safeEmit, "auth.bot_challenge.verify", "success", successMeta);
+
+    var result = {
+      ok:          true,
+      provider:    providerKey,
+      hostname:    parsed.hostname,
+      action:      parsed.action,
+      challengeTs: parsed.challengeTs,
+      raw:         raw,
+    };
+    if (parsed.score !== null) result.score = parsed.score;
+    return result;
+  }
+
+  return { verify: verify };
+}
+
+module.exports = {
+  create:             create,
+  PROVIDERS:          PROVIDERS,
+  BotChallengeError:  BotChallengeError,
+  DEFAULTS: Object.freeze({
+    provider:       DEFAULT_PROVIDER,
+    timeoutMs:      DEFAULT_TIMEOUT_MS,
+    minTimeoutMs:   MIN_TIMEOUT_MS,
+    maxTokenBytes:  MAX_TOKEN_BYTES,
+  }),
+};