arcane-os 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.16.0
+
+- Make mail hosting domain-based: use the current browser origin by default,
+  preserve explicit endpoints, support any application name, and remove
+  loopback-only binding and request admission. Keep exact configured CORS
+  allowlists and recipient policy for To, Cc, and Bcc. Make the CLI sender
+  override optional so reports and provider templates can supply their sender.
+- Replace the local app-key and digest mechanism with optional
+  `verifySubscription({appName, subscriptionKey, signal})` configuration.
+  Verification is disabled until configured for the staged service setup.
+  A configured verifier must accept each app and bearer key before provider
+  delivery; rejection, service failure, and cancellation remain distinct.
+- Remove redundant header reconstruction, address/origin rewriting, local
+  provider payload and identifier grammars, duplicate setup, manual response
+  length calculation, unused CLI queue options, and absent-observer work.
+  Preserve complete provider fields and responses, idempotency, caller-selected
+  deadlines, concurrent requests, and owned shutdown. Report observer and
+  escaped handler failures without changing provider acceptance.
+- Resolve subscription credentials from the current User at HTTP delivery,
+  preserving explicit credentials and User replacement. Update mail references
+  and include the method-by-method gate report.
+
+## 0.15.2
+
+- Rename the private mail configuration helper to `optionalTimeoutMs` so its
+  name describes the optional timeout duration it validates. Preserve accepted
+  values, defaults, and request lifecycle behavior.
+
 ## 0.15.1
 
 - Use the published `node-http-server` public lifecycle for the mail gateway.

package/README.md

@@ -19,10 +19,18 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.15.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.16.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
+The [mail gateway](docs/reference/mail.md) serves the configured host and defaults
+browser mail to `/v1/mail` on the current domain. Multiple applications can share
+one server with explicit allowed origins. Subscription verification is disabled
+until a `verifySubscription` callback is configured; that callback receives the
+application name and bearer subscription key before each provider attempt.
+See the [method and action gate report](docs/reviews/mail-server-purpose-review.md)
+for the removals, retained responsibilities, and naming decisions.
+
 Applications can enable [PWA installation and offline resources](docs/reference/pwa.md)
 through their app descriptor. The SDK generates manifests, an independent
 registration module and a service worker, with clean browser resource URLs,

package/docs/reference/cli.md

@@ -34,7 +34,7 @@ and exits nonzero on failure. Machine output is defined by
 | `arcane repo status\|pull\|push` | Runs one selected repository operation for the current app workspace. |
 | `arcane mail key set\|status\|delete` | Manages one server-only Resend API-key profile in Windows Credential Manager. |
 | `arcane mail send` | Performs one explicit, idempotency-keyed Resend attempt from a complete JSON report on redirected stdin. |
-| `arcane mail serve` | Starts one credential-protected numeric-loopback Arcane-to-Resend gateway for the selected app, Origin, and recipients. |
+| `arcane mail serve` | Starts one Arcane-to-Resend gateway with a server-only provider profile, a selected listener, and optional CORS and recipient configuration. |
 
 ## Parser-wide options
 
@@ -46,9 +46,9 @@ meaning and cardinality rules:
 | `--path` | directory | `new` |
 | `--display-name` | string | `new`, `init` |
 | `--workspace` | directory | Commands that select an external or integrated workspace; defaults to `.`. |
-| `--app` | app id | Workspace/app operations except shared scope and `verify-bundle`; also the exact `mail serve` caller id. |
+| `--app` | app id or label | Workspace/app operations except shared scope and `verify-bundle`; optional diagnostic label for `mail serve`. |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
-| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTP at `127.0.0.1:8025` and admits numeric loopback only. |
+| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTP at `0.0.0.0:8025` and accepts an explicit bind host. |
 | `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
 | `--public` | flag | `dev`; binds to `0.0.0.0` unless `--host` explicitly selects another address. |
 | `--http` | flag | `dev` only; serves source and PWA routes on one HTTP listener selected by `--port`, without TLS. |
@@ -61,10 +61,10 @@ meaning and cardinality rules:
 | `--test-file` | repository-relative `.test.mjs` | `test --scope shared` only |
 | `--artifact` | bundle path | `bundle`, `verify-bundle` |
 | `--profile` | credential profile id | `mail send`, `mail serve` |
-| `--from` | verified sender | `mail send`, `mail serve` |
-| `--origin` | exact browser origin | `mail serve` |
+| `--from` | optional sender override | `mail send`, `mail serve`; otherwise the report or provider template supplies the sender. |
+| `--origin` | optional exact browser origin | `mail serve`; selects an explicit CORS allowed origin. |
 | `--allow-to` | optional comma-separated addresses | `mail serve` |
-| `--report-key` | nonempty safe-character string | `mail send`; caller-owned stable Resend idempotency key |
+| `--report-key` | nonempty string | `mail send`; caller-owned stable Resend idempotency key, forwarded unchanged |
 | `--request-timeout` | optional integer from 1 through 2147483647 milliseconds | `mail send`, `mail serve` |
 | `--output` | `human`, `json`, `ndjson` | Every invocation; the final occurrence wins. |
 | `--git` | flag | `new` |
@@ -73,7 +73,6 @@ meaning and cardinality rules:
 | `--require-local-ai` | flag | `doctor` |
 | `--overwrite` | flag | `bundle` only |
 | `--secret-stdin` | flag | `mail key set`; requires redirected input |
-| `--app-key-stdin` | flag | `mail serve`; requires redirected input |
 | `--report-stdin` | flag | `mail send`; requires redirected JSON input |
 | `--help`, `-h` | flag | Prints help and exits zero. |
 | `--version`, `-v` | flag | Prints the exact SDK version and exits zero. |
@@ -835,10 +834,10 @@ or positional values.
 ### One-shot provider send
 
 `mail send` performs exactly one Resend provider attempt without starting a
-loopback server:
+server:
 
 ```text
-arcane mail send --profile <profile> --from <verified-sender> --report-key <id> --report-stdin [--request-timeout <ms>]
+arcane mail send --profile <profile> [--from <verified-sender>] --report-key <id> --report-stdin [--request-timeout <ms>]
 ```
 
 `--report-stdin` is mandatory and rejects a terminal before attaching input
@@ -854,15 +853,16 @@ shape:
 }
 ```
 
-The required fields are `type`, `to`, `subject`, and at least one of `text` or
-`html`; additional JSON-compatible provider fields are preserved. Direct CLI
-sending requires at least one explicit recipient, including for `error`
-reports. The Resend credential comes only from the selected Windows Credential
-Manager profile; neither it nor report content is accepted through argv or
-environment variables.
+The CLI forwards the complete provider fields, including template requests.
+Resend owns their accepted shape. The adapter removes the application-only
+`type` field and applies `--from` when supplied; otherwise the report or provider
+template supplies the sender. Direct CLI sending has
+no configured fallback recipients. The Resend credential comes only from the
+selected Windows Credential Manager profile; neither it nor report content is
+accepted through argv or environment variables.
 
-The caller owns `--report-key`. It must contain one or more ASCII letters, digits,
-periods, underscores, colons, or hyphens. Reuse the same key only with the same
+The caller owns the nonempty `--report-key`, which is forwarded unchanged.
+Reuse the same key only with the same
 logical report when deliberately reconciling or retrying an
 ambiguous attempt. The CLI never retries automatically.
 
@@ -875,32 +875,46 @@ available request and outcome detail. Cancellation before the
 provider attempt exits 130 without sending; cancellation, timeout, or transport
 loss after the attempt begins is ambiguous because Resend may have accepted it.
 
-### Authenticated local gateway
+### Mail gateway
 
 `mail serve` starts one owned Node HTTP gateway:
 
 ```text
-arcane mail serve --profile <profile> --from <verified-sender> --app <id> --origin <exact-origin> [--allow-to <addresses>] [--app-key-stdin] [--host 127.0.0.1] [--port 8025] [--request-timeout <ms>]
+arcane mail serve --profile <profile> [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 8025] [--request-timeout <ms>]
 ```
 
 The selected credential profile supplies only the server-side Resend API key.
-A separate local mail app key is read through a hidden prompt. Structured
-output requires `--app-key-stdin` with redirected input; the app key is never an
-argv value or part of the server result. The browser must use the same value as
-`arcane.config.mail.appKey`.
-
-The CLI admits only numeric loopback host values accepted by the gateway. The
-gateway also binds the exact app id, Origin, and sender, and it requires the
-separate app key by default. `--allow-to` optionally supplies a comma-separated
-recipient allowlist with no fixed recipient-count ceiling. `--request-timeout`
+The CLI does not read a browser app key. Its optional `--app` value labels the
+server; the incoming request's `X-Mail-App` identifies the application for
+subscription verification. The HTTP authentication contract pairs that
+application with `Authorization: Bearer <subscription_key>`.
+
+Subscription verification is disabled for this initial service setup. The
+programmatic `createToolchain().mail({action: 'serve', ...})` path accepts
+`verifySubscription({appName, subscriptionKey, signal})`; supplying that callback
+enables verification before each provider attempt. It must resolve to `true`
+to accept the request. An invalid subscription receives 401; verifier service
+failure receives retryable 503; cancellation stops verification before sending.
+The callback connects the actual TWiN Stripe endpoint when its contract is
+ready. There is no guessed URL, response schema, or command-line endpoint flag.
+
+The listener defaults to `0.0.0.0`; `--host` selects another bind host. Browser
+mail defaults to `/v1/mail` on the current domain. `--origin` is optional and
+selects an explicit CORS allowlist when supplied. `--allow-to` optionally
+supplies a comma-separated recipient allowlist. CLI parsing preserves supplied
+address spelling and repeated entries. Programmatic `errorTo` selects fallback
+recipients for error reports; when omitted, the selected `allowTo` list supplies
+that fallback. `--request-timeout`
 adds a caller-selected provider-attempt timeout from 1 through 2147483647
 milliseconds, the Node timer range. When it is omitted, the SDK adds no
 provider timeout.
 
 After binding, `server.ready` reports lifecycle fields such as
-protocol, app id, loopback address, port, URL, and caller-authentication mode.
+protocol, optional app label, bind address, port, URL, and `callerAuthentication`
+(`none` or `subscription`). Human output states whether verification is disabled
+or configured.
 The command owns the server until its lifecycle ends or `SIGINT`/`SIGTERM`
-cancels it. Resend and local app credentials never appear in results or events;
+cancels it. The server's Resend credential remains outside results and events;
 per-request observer events preserve the complete delivery, report, provider
 outcome, and failure detail available to the gateway.
 

package/docs/reference/mail.md

@@ -1,8 +1,8 @@
 # Mail gateway and durable outbox
 
 Arcane Mail is a pure-JavaScript SDK path. It does not use WebAssembly: mail is
-network and durable-state work, while the Resend credential belongs in the
-local Node gateway rather than in browser or WebAssembly state.
+network and durable-state work. The Resend credential belongs in the Node
+gateway and is never included in browser or WebAssembly state.
 
 ## Ownership and availability
 
@@ -12,7 +12,7 @@ local Node gateway rather than in browser or WebAssembly state.
 | `MailOutbox.mjs` | Browser or compatible injected storage | Stores exact requests in the `mail_outbox` DBOPFS table before delivery and normalizes terminal, retry, and reconciliation states. |
 | `MailTransport.mjs` | Browser, WebView, or compatible Fetch host | Sends one already-persisted request to the configured Arcane gateway with the stable report key as its idempotency key. |
 | `arcane mail send` | Node on the local machine | Reads one complete provider-neutral report from redirected stdin and performs one explicit Resend attempt with a caller-owned idempotency key. |
-| `arcane mail serve` | Node on the local machine | Authenticates the local caller, protects the provider credential, applies any explicitly configured recipient policy, and makes the single server-side Resend request. |
+| `arcane mail serve` | Node on the configured host | Owns caller verification, protects the provider credential, applies explicitly configured recipient and origin settings, and makes one server-side Resend request. |
 | `arcane mail key ...` | Node on Windows | Stores, inspects, or deletes a Resend API key in Windows Credential Manager. |
 
 The browser never receives the Resend API key. The gateway never writes that
@@ -49,52 +49,81 @@ boundary; ordinary operators use `arcane mail send`, `arcane mail serve`, and
 `arcane mail key ...`. This keeps Node credential and server authority out of a
 browser import while preserving one shared CLI/toolchain implementation.
 
-## Two separate credential boundaries
+## Provider and subscription credentials
 
 Arcane Mail deliberately separates two credentials:
 
 - The **Resend API key** is provider authority. `arcane mail key set <profile>`
   stores it in Windows Credential Manager. `mail send --profile <profile>` and
   `mail serve --profile <profile>` read it only inside the owning Node process.
-- The **mail app key** authenticates one browser/application caller to the
-  loopback gateway. It is supplied to `mail serve` through hidden terminal
-  input, or through redirected input with `--app-key-stdin`, and must match the
-  browser's `arcane.config.mail.appKey`. It is a nonempty printable ASCII
-  bearer-like local authentication value, never the Resend API key.
+- The **subscription key** is the application user's subscription credential.
+  When present, the browser sends it as `Authorization: Bearer <subscriptionKey>`,
+  with the exact application name in `X-Mail-App`. The application name identifies the
+  subscription account to verify; it is a separate field from the key and the
+  report content.
 
 Do not put either secret on the command line. Command-line arguments may be
-recorded by the operating system or shell history. Structured CLI output
-requires the matching explicit redirected-input flag and rejects TTY input so
-the terminal cannot echo a secret.
-
-The mail app key is not confidential from scripts executing in the same page:
-same-runtime script or XSS can read browser configuration and issue the same
-request. Inject it at runtime, never hardcode it in shipped assets, protect the
-page's script boundary, restrict the exact gateway destination, and rotate it
-when page or process trust is lost. It protects the loopback server from
-unadmitted local callers; it is not provider authority or a replacement for
-browser application security.
+recorded by the operating system or shell history. The credential-store
+command uses hidden terminal input or explicitly selected redirected input;
+subscription credentials are supplied through runtime configuration.
+
+Subscription credentials stay in runtime configuration or the canonical User
+entity. They are not added to reports, outbox records, delivery events, or
+provider payloads. Supply credentials at runtime; do not hardcode them in
+shipped source or fixtures.
 
 ## Configure the browser runtime
 
-One application declares an exact app id, gateway endpoint, and local app key:
+Configure Mail before its durable lifecycle starts:
 
 ```javascript
 globalThis.arcane = globalThis.arcane || {};
 globalThis.arcane.config = globalThis.arcane.config || {};
 globalThis.arcane.config.mail = {
-    appName: 'arcane-dev',
-    appKey: localMailAppKey,
-    endpoint: 'http://127.0.0.1:8025/v1/mail'
+    appName: 'My application'
 };
 ```
 
-The transport endpoint must be HTTPS or loopback HTTP at `localhost`,
-`127.0.0.1`, or `[::1]`. The SDK CLI gateway itself binds numeric loopback only. An
-explicit HTTPS endpoint receives the app key as `X-Mail-Key`, so its ownership
-and trust must be verified before configuration. A hosted default is derived
-only when the page declares an admitted Arcane mail base domain; otherwise
-configuration fails rather than selecting an arbitrary remote host.
+`appName` is an arbitrary nonempty string, preserved as supplied. `BOSS` and
+`TWiN` are examples, not an enum or an admission list. When `appName` is omitted,
+Mail reads the page's `arcane-app-id` metadata without changing its value.
+
+On an HTTP or HTTPS page, the default endpoint is `/v1/mail` on the current
+origin, including its port. Mail does not infer a base domain, select a mail
+subdomain, or treat loopback addresses specially. An explicit `endpoint` may
+select a shared server on another domain. The transport resolves it through
+the URL parser and accepts HTTP or HTTPS; relative URLs and query strings are
+supported. The gateway routes by pathname. Its configured CORS origins must
+include a caller on another origin.
+
+An explicit `endpoint: ''` disables HTTP delivery and selects the existing
+native `Arcane.mail.send` fallback when available. Pages with a non-HTTP origin
+also have no default HTTP endpoint. Configured HTTP delivery takes precedence
+over an available native bridge.
+
+An explicit nonempty string `subscriptionKey` supplies the HTTP credential.
+When it is omitted, Mail resolves the current canonical User entity at the actual HTTP delivery,
+waits for its existing `load()` operation, and reads `subscription_key`.
+An injected `options.user` retains precedence, including an explicit `null`.
+Mail does not retain a separate User instance, so later deliveries observe a
+replacement canonical User. This adds no page-startup wait, polling, new
+credential storage, or migration of saved data.
+
+An absent key, `null`, or an empty string omits the Authorization header; the
+transport does not block initial setup because a key is missing. Explicit
+`subscriptionKey: null` or `subscriptionKey: ''` also skips User lookup.
+A supplied value of another type is rejected. A gateway with subscription
+verification configured owns rejection of requests without a usable key.
+
+For a caller-owned key and shared endpoint:
+
+```javascript
+globalThis.arcane.config.mail = {
+    appName: 'Another application',
+    subscriptionKey: currentSubscriptionKey,
+    endpoint: 'https://mail.example.test/v1/mail'
+};
+```
 
 The ordinary browser transport has no automatic request deadline and reads the
 complete gateway response. A caller may explicitly supply a positive
@@ -107,7 +136,7 @@ accepted the request.
 `Mail.send(to, subject, payload, messageStyle, messageType)` preserves the
 existing signature. `messageType` is `error`, `report`, or `crisis_detected`.
 Report and crisis mail require at least one recipient; error mail may use the
-gateway's configured allowlisted fallback recipients.
+gateway's configured fallback recipients.
 
 In a browser, the module owns the one `window.mail` singleton. An explicit
 `new Mail(config, options)` may configure that owned singleton only before its
@@ -124,9 +153,10 @@ option `{includeContext:true}`, every message also captures
 current User entity and add its `username`, `email`, `language`, and `phone`
 values to the locally rendered content. Those fields are then stored and sent
 unencrypted as part of the message, so the application owns consent, purpose,
-recipient scope, retention, and disclosure. Without that option, Mail neither
-loads the User profile nor adds the path/profile fields. The generated
-`source_at` timestamp, caller-supplied payload, subject, type, and recipients
+recipient scope, retention, and disclosure. Without that option, Mail adds no
+path/profile fields to the report. HTTP subscription lookup may still load
+the User at delivery without copying profile fields into the report. The
+generated `source_at` timestamp, caller-supplied payload, subject, type, and recipients
 remain part of the requested report in either mode.
 
 The public `Mail` integration requires its compatible DBOPFS adapter. Before the
@@ -145,8 +175,9 @@ durable claims then belong to that adapter's implemented `get`, `set`,
 default uses `navigator.locks`; when that cross-context authority is absent,
 the outbox reports `MAIL_OUTBOX_LOCK_UNAVAILABLE` and does not start the drain.
 
-Call `await mail.start()` during application startup so pre-existing records
-are scanned even when the application does not send a new report. The first
+Start `mail.start()` during application startup so pre-existing records are
+scanned even when the application does not send a new report. Observe its
+completion or error without holding page rendering behind the drain. The first
 `send()` also starts the lifecycle if needed.
 
 | Mail method/property | Contract |
@@ -218,9 +249,14 @@ boundary.
 Mail publishes complete semantic events through the SDK singleton event
 authority. Public detail includes the full mutable durable record, serialized
 report, result or failure, provider details, and complete drain inventory
-available at that transition. It never includes the Resend API key or mail app
-key. Listener exceptions are observational and cannot change a committed mail
-operation result.
+available at that transition. It never includes the Resend API key or
+subscription key. Listener exceptions are observational and cannot change a
+committed mail operation result.
+
+Provider IDs, provider codes, and nonempty failure codes retain their complete
+string values through delivery, persistence, and retrieval. They have no SDK
+character grammar. Missing values retain the existing fallback behavior.
+Request IDs and outbox filenames retain their existing contracts.
 
 When both an explicit endpoint and native `Arcane.mail.send` exist, Mail uses
 the configured HTTP endpoint so the authenticated SDK gateway can return its
@@ -232,7 +268,7 @@ unavailability is a non-ambiguous retryable failure. Once a valid accepted
 result has returned, a racing lifecycle cancellation cannot erase that
 committed acceptance result.
 
-## Operate the CLI and local gateway
+## Operate the CLI and gateway
 
 Store one Resend key under a local profile:
 
@@ -251,19 +287,20 @@ Perform one provider attempt directly from the SDK CLI:
 arcane mail send --profile arcane-dev --from "Arcane <verified@example.com>" --report-key <stable-id> --report-stdin
 ```
 
-The redirected UTF-8 JSON input is read completely. A report requires `type`,
-`to`, `subject`, and at least one of `text` or `html`; additional
-JSON-compatible provider fields are preserved. Direct CLI sends require at
-least one explicit recipient, including for `error` reports. Message content is
-not accepted in argv. Programmatic results and observer events preserve the
-complete report, provider request, provider response, and error detail while
+The redirected UTF-8 JSON object is read completely. Its fields and values
+are retained; the Resend adapter removes the SDK's `type` routing field,
+uses `from` when configured (otherwise the report or provider template supplies
+the sender), and applies configured error-recipient fallback
+when applicable. Resend evaluates its own required provider fields. Message
+content is not accepted in argv. Programmatic results and observer events
+preserve the complete report, provider request, provider response, and error detail while
 never exposing either credential.
 
-The caller must create and retain a safe-character `--report-key` before the
+The caller must create and retain a nonempty `--report-key` before the
 attempt. It is the Resend idempotency key and may be reused only with the same
 serialized report content for an intentional retry or reconciliation. The
 CLI performs exactly one attempt and never retries automatically. Exit zero
-requires a successful Resend response containing a valid provider id; that is
+requires a successful Resend response containing a nonempty string provider id; that is
 provider acceptance, not an inbox-delivery claim. Timeout, connection loss, or
 cancellation after the provider attempt begins is returned as an ambiguous
 nonzero outcome because the provider may already have accepted the request.
@@ -272,16 +309,80 @@ For both CLI mail operations, `--request-timeout` accepts 1 through 2147483647
 milliseconds, the Node timer range. When omitted, the SDK adds no provider
 deadline.
 
-Start the authenticated gateway:
+Start the gateway:
 
 ```text
-arcane mail serve --profile arcane-dev --from "Arcane <verified@example.com>" --app arcane-dev --origin http://127.0.0.1:8000 --allow-to recipient@example.com
+arcane mail serve --profile arcane-dev --from "Arcane <verified@example.com>"
 ```
 
-Human output prompts for the separate mail app key with hidden input.
-Non-interactive structured output requires `--app-key-stdin` and redirected
-stdin. The server binds numeric loopback only; the default is
-`127.0.0.1:8025/v1/mail`.
+The default listener is `0.0.0.0:8025`; `--host` and `--port` select its bind
+address and port. The server can serve callers from multiple domains on the
+same machine. Route the page's `/v1/mail` to this listener, or configure an
+explicit shared endpoint in the caller.
+
+`--app` is an optional server event label and does not restrict incoming
+application names. `--from` is an optional shared sender override; omit it to
+preserve each report's sender or its provider template's default.
+`--origin` selects an exact allowed caller origin; the
+programmatic `origin` option also accepts an array for multiple origins. With
+no origins configured, the gateway accepts an Origin matching its request
+Host using HTTP or HTTPS. Requests without Origin continue normally.
+Cross-origin preflight permits `Content-Type`, `Idempotency-Key`, `X-Mail-App`,
+and `Authorization`. This is origin configuration, not a loopback policy.
+
+`--allow-to` explicitly limits recipients when supplied. With it omitted, the
+gateway imposes no recipient allowlist. When configured, the list applies to
+every recipient in the resolved `to`, `cc`, and `bcc` fields, whether supplied
+as a string or an array. Sender, recipient, subject, and body
+values are not trimmed, lowercased, or filtered by an SDK email grammar at
+the gateway. Error reports with an empty `to` array use configured fallback
+recipients; other report content is preserved.
+
+## Configure subscription verification
+
+Subscription verification is disabled during initial setup when
+`verifySubscription` is omitted. The server reports
+`callerAuthentication: 'none'` and can perform mail delivery without a
+subscription key. Starting the ordinary CLI gateway uses this mode. This does
+not claim that a subscription was checked.
+
+The hosting process enables verification by supplying the programmatic
+`verifySubscription` function through
+`createToolchain().mail({action:'serve', verifySubscription, ...options})`.
+The server then reports `callerAuthentication: 'subscription'`. The callback
+contract is:
+
+```javascript
+verifySubscription({appName, subscriptionKey, signal})
+```
+
+It may return a promise. Return exactly `true` for a valid subscription;
+return `false` for an invalid one, and throw when the verifier service fails.
+The gateway also treats any other returned value as invalid. `appName` is the
+exact incoming `X-Mail-App` value, `subscriptionKey` is the incoming Bearer
+key, and `signal` follows the request lifecycle. These control fields stay
+separate from the mail report and Resend payload. The verifier runs for each
+POST request before any provider attempt; results are not cached.
+
+| Configured-verifier outcome | Gateway response |
+| --- | --- |
+| Missing, empty, or repeated `X-Mail-App` | `400 mail_invalid_headers` |
+| Missing or malformed Bearer credential | `401 mail_subscription_required` |
+| Callback returns anything except `true` | `401 mail_subscription_invalid` |
+| Callback throws | `503 mail_subscription_verification_failed`, retryable with the configured `retryableDelayMs` |
+| Request cancelled while verifying | `408 mail_request_cancelled`, with no provider attempt |
+
+The `401` responses include `WWW-Authenticate: Bearer`. A successful callback
+permits the existing mail-delivery path; it is not itself a mail-acceptance
+result. The SDK supplies no default verification URL or built-in Stripe
+endpoint adapter. Connecting the actual subscription endpoint is a separate
+hosting integration.
+
+CLI startup output says `Subscription verification: disabled` or
+`Subscription verification: configured`. Structured `server.ready` output
+includes the corresponding `callerAuthentication` value.
+
+## Gateway request lifecycle
 
 The gateway uses the published `node-http-server` instance lifecycle. Its raw
 request hook hands the original request and response directly to the mail
@@ -289,17 +390,15 @@ handler before body parsing or static routing. Socket inactivity timeout remains
 disabled; caller-selected mail deadlines, cancellation, and complete responses
 remain owned by the mail handler.
 
-The gateway protects the provider credential by requiring:
-
-- its exact numeric-loopback `Host` authority and `/v1/mail` route;
-- an exact configured `Origin`, app id, and constant-time app-key match;
-- complete JSON requests with at least one recipient, or configured fallback
-  recipients for an `error` report;
-- an optional explicit recipient allowlist when one is configured; and
-- one fixed Resend endpoint with the stable Arcane report key forwarded as
-  `Idempotency-Key`.
+The gateway handles POST requests to `/v1/mail` and the corresponding OPTIONS
+preflight. JSON parsing owns request readability; the gateway does not reject
+a parseable body because of its Content-Type spelling. One nonempty
+`Idempotency-Key` is forwarded unchanged to the fixed Resend endpoint. The
+browser and gateway preserve complete request and response content without
+body-size gates. With no event observer, the gateway does not construct event
+payloads or parse a second provider-request representation for observation.
 
-The gateway returns `202` only after Resend returns a valid provider id.
+The gateway returns `202` only after Resend returns a nonempty string provider id.
 Transport loss, an explicit caller-selected timeout, an invalid success body,
 or an unreadable provider response returns an explicit uncertain result and never claims
 delivery. Rate limits, concurrent idempotency requests, permanent validation
@@ -308,8 +407,8 @@ results with the complete available provider response or error detail.
 
 ## Operational verification
 
-The focused SDK tests use only synthetic keys, addresses, responses, storage,
-and loopback requests. They do not contact Resend or send email. A live
+The focused SDK tests use synthetic keys, addresses, responses, storage,
+and local HTTP requests. They do not contact Resend or send email. A live
 acceptance send is a separate operational boundary: use a disposable message,
-the real allowlist, and the selected credential profile, then verify both the
+the selected recipient configuration and credential profile, then verify both the
 gateway's provider-acceptance id and the intended inbox outcome.