arcane-os 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.25.0
+
+- Automatically skip configured mail subscription verification when the actual
+  requester connection IP equals the server-side IP of that connection. This
+  lets services sharing that IP and local development send without a subscription
+  key. Other requester IPs, including other intranet machines, still use the
+  configured verification callback.
+- Use native connection addresses for HTTP/1 and HTTP/2, with no environment
+  setting, domain lookup, forwarded-header interpretation, or special loopback rule.
+  Preserve CORS, report handling, provider delivery, and existing caller APIs.
+- Document the IP rule and its purpose gates; update focused test source for
+  the exemption and the remaining subscription-verification paths.
+
+## 0.24.1
+
+- Add a mail CLI parameter table with command scope, purpose, and defaults.
+  Explain the difference between `--app`, `X-Mail-App`, `--report-stdin`, and
+  the nonsecret `--report-key` used for intentional same-message retries.
+- Remove redundant default-profile configuration and the alternate-account
+  placeholder from the main mail example. Align the CLI reference with the
+  shared configuration and credential files while preserving named-profile APIs.
+- Clarify when subscription headers are required, how ordinary delivery failures
+  retain their existing report, and the separate browser callback and verification
+  service paths that can create feedback. Runtime behavior is unchanged.
+
 ## 0.24.0
 
 - Read nonsecret mail settings from `arcane.config.json.mail` and provider keys

package/README.md

@@ -19,7 +19,7 @@ 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.24.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.25.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -31,7 +31,11 @@ Existing root credential, profile, and TLS settings remain supported. Browser
 mail defaults to `/v1/mail` on the current domain, and 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.
+application name and bearer subscription key before provider attempts from other
+requester IPs. Requests whose actual connection source IP equals the server-side
+IP of that connection automatically skip subscription verification, including
+local development. Other intranet machines still need verification. The exception
+requires no environment setting or domain lookup.
 See the [method and action gate report](docs/reviews/mail-server-purpose-review.md)
 for the removals, retained responsibilities, and naming decisions.
 

package/docs/reference/cli.md

@@ -812,10 +812,13 @@ npm exec -- arcane repo status
 
 ## `arcane mail`
 
-### Resend credential profiles
+### Configuration and provider credentials
 
-The mail commands read `.arcane.env.json` from the invocation directory on Windows,
-Linux, and macOS. The credential subcommands select one profile in that file:
+Mail reads nonsecret settings from `arcane.config.json.mail` and the Resend key
+from `.arcane.env.json.mail.apiKey` in the invocation directory on Windows,
+Linux, and macOS. See [Mail CLI parameters](mail.md#mail-cli-parameters) for the
+complete parameter, configuration-field, default, and precedence reference.
+The credential subcommands manage the provider key:
 
 ```text
 arcane mail key set [profile] [--secret-stdin]
@@ -826,26 +829,43 @@ arcane mail key delete [profile]
 `key set` reads the Resend API key from a hidden terminal prompt. The
 `--secret-stdin` form is for deliberately redirected non-interactive input and
 rejects a TTY before reading. The key is written to `.arcane.env.json` and is never
-accepted in argv or returned in status output. The optional profile defaults
-to `mail`, which selects top-level `RESEND_API_KEY`. Any other exact profile
-selects `MAIL_PROFILES[profile].RESEND_API_KEY`, with no default-key fallback.
+accepted in argv or returned in status output. The optional credential-command
+profile defaults to `mail`, independently of the send/serve configuration.
 
-The minimal file is:
+The minimal `.arcane.env.json` is:
 
 ```json
 {
-  "RESEND_API_KEY": ""
+  "mail": {
+    "apiKey": ""
+  }
 }
 ```
 
 Fill in the key before starting mail, and add `.arcane.env.json` to the project's
-`.gitignore`; the SDK repository already ignores it. Set and delete preserve
-the file's other settings and profiles. Status returns the selected profile,
+`.gitignore`; the SDK repository already ignores it. Keep nonsecret listener
+settings, including certificate file paths, in `arcane.config.json.mail`.
+
+Named profiles remain an optional CLI/toolchain compatibility feature for
+selecting another stored Resend key. An exact name selects
+`mail.profiles[name].apiKey`; the name is independent of incoming application
+names, domains, and subscription keys. One server process uses one selected
+Resend key for all its requests. An absent named key never falls back to the
+default account. Existing root `RESEND_API_KEY` and
+`MAIL_PROFILES[name].RESEND_API_KEY` remain fallbacks when the corresponding
+nested key property is absent. A nested property containing null or an empty
+string means the selected key is absent and takes precedence over a legacy key.
+
+Set and delete preserve the file's other settings and profile containers. New
+keys are written to the nested mail member. Existing legacy keys are updated
+in place unless the selected nested key property exists; delete removes both
+representations of only the selected key. Status returns the selected profile,
 `provider:'resend'`, `storage:'.arcane.env.json'`, and `exists`. Delete returns
 `exists:false` for both a removed and an already-absent credential.
 
-Programmatic `createToolchain().mail(...)` resolves the configuration directory
-from `cwd ?? workspaceRoot ?? process.cwd()`. This uses ordinary Node file
+Programmatic `createToolchain().mail(...)` resolves both files from the directory
+selected by `cwd ?? workspaceRoot ?? process.cwd()`, with no upward search.
+This uses ordinary Node file
 access rather than platform-specific credential processes. An Android host
 supplies a compatible Node runtime and an accessible configuration directory.
 Existing Windows Credential Manager records remain untouched; the JSON reader
@@ -854,11 +874,13 @@ populate or depend on process environment variables for this key.
 
 The SDK's installation directory does not affect this location. With an SDK
 under `my-site/arcane-os-sdk/`, run the command from `my-site/` and keep
-`my-site/.arcane.env.json` alongside that directory. Existing deployments using
+`my-site/arcane.config.json` and `my-site/.arcane.env.json` alongside that
+directory. Existing deployments using
 SDK 0.22.1 or earlier must rename `.env.json` to `.arcane.env.json` while
 preserving its contents; the loader reads only the new name.
 
-Missing files or missing/empty selected keys stop `send` and `serve` with the
+Each file is an optional configuration source. Missing or empty selected keys
+stop `send` and `serve` with the
 configuration path and exact JSON setting to fill in. Invalid JSON and file
 access failures remain observable without printing credential content.
 
@@ -890,11 +912,16 @@ shape:
 
 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 `.arcane.env.json` profile; omitting `--profile` selects `mail`. Neither the
-key nor report content is accepted through argv or process environment variables.
+`type` field and applies the shared sender from `--from` or `mail.from` when
+supplied; otherwise the report or provider template supplies the sender. Direct
+CLI sending has no configured fallback recipients and requires no listener TLS
+paths. It consumes the configured provider timeout and retry guidance.
+
+The Resend credential comes from the selected `.arcane.env.json` entry.
+An explicit `--profile` overrides `arcane.config.json.mail.profile`; omitting
+both selects the default `mail.apiKey`, with the legacy fallback described
+above. Neither the key nor report content is accepted through argv or process
+environment variables.
 
 The caller owns the nonempty `--report-key`, which is forwarded unchanged.
 Reuse the same key only with the same
@@ -918,22 +945,28 @@ loss after the attempt begins is ambiguous because Resend may have accepted it.
 arcane mail serve [--profile <profile>] [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 4433] [--request-timeout <ms>]
 ```
 
-The selected `.arcane.env.json` profile supplies only the server-side Resend API key;
-omitting `--profile` selects `mail`.
+The selected `.arcane.env.json` entry supplies only the server-side Resend API
+key. An explicit `--profile` overrides `arcane.config.json.mail.profile`;
+omitting both selects the default key.
 
-Add the listener's certificate configuration at the top level of the same file:
+Add the listener's certificate paths to `arcane.config.json`:
 
 ```json
 {
-  "RESEND_API_KEY": "",
-  "MAIL_TLS_CERT_PATH": ".arcane/mail/fullchain.pem",
-  "MAIL_TLS_KEY_PATH": ".arcane/mail/private-key.pem"
+  "mail": {
+    "certPath": ".arcane/mail/fullchain.pem",
+    "keyPath": ".arcane/mail/private-key.pem"
+  }
 }
 ```
 
 Supply an existing PEM certificate chain and its private key. Paths resolve
-relative to `.arcane.env.json`, or may be absolute. They are shared across provider
-profiles. Missing TLS settings name the fields to fill in before a listener
+relative to the selected configuration directory, or may be absolute. They
+belong to the listener regardless of the provider key selected. Legacy root
+`MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH` in `.arcane.env.json` remain
+fallbacks for omitted config paths. Explicit programmatic `certPath` and
+`keyPath` options override those files. Missing TLS settings name the fields
+to fill in before a listener
 opens; the TLS owner reports PEM file errors. Keep private-key material outside
 tracked source. The SDK repository already ignores `.arcane/` and `.arcane.env.json`.
 
@@ -949,30 +982,50 @@ 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
+Subscription verification is disabled when no callback is configured. 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`
+enables verification for requests whose actual connection source IP differs
+from the server-side IP of that connection. The gateway compares the native
+`request.socket.remoteAddress` with `request.socket.localAddress`. A nonempty,
+equal requester IP skips subscription verification and needs neither a bearer
+key nor an application header for that check. No environment setting or domain
+lookup is involved. Local development qualifies under the same rule; another
+machine on an intranet still needs verification. Missing connection metadata
+does not qualify. CORS and the remaining mail requirements still apply.
+
+For requests requiring verification, the callback 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.
+The listener defaults to `0.0.0.0:4433`; `mail.host` and `mail.port` configure
+the listener, and explicit `--host` and `--port` override them. Browser mail
+defaults to `/v1/mail` on the current domain. `mail.origins` supplies an exact
+origin array; `--origin` replaces it with one origin. Repeated `--origin`
+options keep the last value. An absent or empty list selects the current
+request authority. Other Origins receive `403 mail_origin_not_allowed`;
+requests without an Origin continue normally. This CORS configuration does
+not filter client IPs or give loopback special treatment.
+
+`mail.recipientAllowlist` supplies the recipient list; `--allow-to` replaces it
+with a comma-separated list. CLI parsing preserves supplied address spelling
+and repeated entries. Programmatic `errorTo` or `mail.errorRecipients` selects
+fallback recipients for error reports. When neither is supplied, the effective
+recipient allowlist supplies that fallback; an explicit empty array supplies
+none. The [Mail CLI parameters](mail.md#mail-cli-parameters) reference also
+documents programmatic aliases and list-replacement precedence.
+
+`--request-timeout` overrides `mail.providerTimeoutMs` and accepts 1 through
+2147483647 milliseconds, the Node timer range. An absent effective timeout
+adds no provider deadline; programmatic/configured null also selects no
+deadline. `mail.bodyTimeoutMs` selects the optional request-body deadline.
 
 After binding, `server.ready` reports lifecycle fields such as
 protocol, optional app label, bind address, port, URL, and `callerAuthentication`
 (`none` or `subscription`). Human output states whether verification is disabled
-or configured.
+or configured; configured verification includes the automatic same-IP exception.
 The command owns the server until its lifecycle ends or `SIGINT`/`SIGTERM`
 cancels it. The server's Resend credential remains outside results and events;
 per-request observer events preserve the complete delivery, report, provider

package/docs/reference/mail.md

@@ -115,7 +115,8 @@ 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.
+verification configured owns rejection of requests without a usable key,
+subject to its [automatic same-IP exception](#automatic-same-ip-exception).
 
 For a caller-owned key and shared endpoint:
 
@@ -272,6 +273,40 @@ committed acceptance result.
 
 ## Operate the CLI and gateway
 
+### Mail CLI parameters
+
+`mail serve` starts the shared mail server. `mail send` makes one direct Resend
+request. `mail key set|status|delete` manages the provider credential.
+
+| Parameter | Command | What it does | When omitted |
+| --- | --- | --- | --- |
+| `--app <label>` | `mail serve` | Supplies a fallback application label for server events. An incoming `X-Mail-App` supplies the request's label. This option does not choose a Stripe account or limit which apps may send mail. | Uses `mail.appId` when configured; otherwise adds no fallback label. |
+| `--from <sender>` | `mail serve`, `mail send` | Overrides the sender, for example `"Dragon Dispatch <dispatch@example.com>"`. On the server, the override applies to every report. Resend must accept that sender. | Uses `mail.from` when configured, then the report's `from` or provider template default. |
+| `--report-stdin` | `mail send` | Reads one complete UTF-8 report JSON object from redirected standard input, including recipients, subject, body, and other provider fields. | Required; the command reports a usage error. |
+| `--report-key <id>` | `mail send` | Identifies one intended email and is forwarded unchanged as Resend's `Idempotency-Key`. Use a new value for a new email; reuse the value and unchanged report for an intentional retry. It is not a credential. | Required; the command reports a usage error. |
+| `--host <address>` | `mail serve` | Selects the listener bind address. `0.0.0.0` accepts connections through all IPv4 interfaces. | Uses `mail.host`, then `0.0.0.0`. |
+| `--port <number>` | `mail serve` | Selects the HTTPS listener port. Explicit `0` asks the operating system for an available port. | Uses `mail.port`, then `4433`. |
+| `--origin <origin>` | `mail serve` | Replaces the configured CORS origins with one exact browser origin, including scheme and any nondefault port. Use the JSON `origins` array for multiple origins; repeated flags keep only the last value. | Uses `mail.origins`; an absent or empty list uses the current request authority. Requests without an `Origin` header continue normally. |
+| `--allow-to <addresses>` | `mail serve` | Replaces the recipient allowlist with a comma-separated list. Applies to `to`, `cc`, and `bcc`, and supplies error-report fallback recipients unless `mail.errorRecipients` is configured separately. | Uses `mail.recipientAllowlist`; an absent or empty list leaves recipients unrestricted. |
+| `--request-timeout <ms>` | `mail serve`, `mail send` | Sets the deadline for one Resend request, in milliseconds. A timeout after sending begins leaves delivery uncertain; it does not schedule a retry. | Uses `mail.providerTimeoutMs`; absent or null adds no provider deadline. |
+| `--profile <name>` | `mail serve`, `mail send` | Selects an alternate saved Resend credential for this invocation. One listener uses that selected provider key for all callers. | Uses `mail.profile` if configured, otherwise the normal `mail.apiKey`. The single-key setup needs no profile setting. |
+| `[profile]` | `mail key set\|status\|delete` | Optional positional name of the credential to manage; it is not a flag. | Manages the normal `mail.apiKey`, independently of `mail.profile`. |
+| `--secret-stdin` | `mail key set` | Reads the Resend API key from deliberately redirected standard input instead of the hidden terminal prompt. | Prompts with hidden input. Machine-output mode requires redirected input. |
+| `--output human\|json\|ndjson` | All mail commands | Selects readable console output, one JSON result, or newline-delimited JSON events. | Uses `human`. |
+| `--help` | CLI | Displays CLI help instead of running the mail operation. | Runs the requested operation. |
+| `--version` | CLI | Displays the SDK version instead of running the mail operation. | Runs the requested operation. |
+
+There is no `--report` flag. `--report-stdin` supplies the message;
+`--report-key` identifies that same message across attempts. Browser `Mail.send()`
+generates and retains its report key automatically.
+
+Mail reads configuration from the directory in which the command runs;
+`--workspace` does not relocate these mail files. Mail HTTPS uses `mail.certPath`
+and `mail.keyPath` in JSON. The `--cert`, `--key`, `--https`, and `--http-port`
+flags belong to browser `dev`/`run`, and `--http` belongs to `dev`.
+
+### Mail configuration
+
 Keep app-supplied SDK settings under named capability members, starting with
 `mail`. Put the nonsecret mail settings in `arcane.config.json` in the directory
 from which the command runs:
@@ -285,7 +320,6 @@ from which the command runs:
       "https://dragons.example",
       "https://www.dragons.example"
     ],
-    "profile": "mail",
     "certPath": "certificates/fullchain.pem",
     "keyPath": "certificates/private-key.pem"
   }
@@ -333,24 +367,16 @@ injected providers, `fetchImpl`, `onEvent`, `requestIdFactory`,
 runtime inputs, not JSON settings. Reports and their idempotency keys remain
 inputs to each send operation.
 
-The default credential profile `mail` selects `.arcane.env.json.mail.apiKey`.
-Other profile names select exact entries in `.arcane.env.json.mail.profiles`:
+The single-key configuration above needs no `profile` or `profiles` member.
+Omitting the selection uses `.arcane.env.json.mail.apiKey`; multiple apps and
+domains can share that provider key.
 
-```json
-{
-  "mail": {
-    "apiKey": "",
-    "profiles": {
-      "another-provider-account": {
-        "apiKey": ""
-      }
-    }
-  }
-}
-```
-
-An absent named profile does not fall back to the default key. The profile
-selects Resend provider credentials; it is separate from the incoming
+For callers that already select an alternate credential, named-profile support
+remains available: `--profile <name>` or `mail.profile` selects
+`.arcane.env.json.mail.profiles[name].apiKey`. An absent named profile does not
+fall back to the default key. Selection happens once when send or serve starts;
+it does not map incoming apps or domains to different provider accounts.
+The profile selects Resend provider credentials, separately from the incoming
 application name and subscriber key. Existing top-level `RESEND_API_KEY` and
 `MAIL_PROFILES[profile].RESEND_API_KEY` remain supported. A nested selected
 `apiKey` takes precedence when the property exists, including null or an empty
@@ -449,8 +475,8 @@ arcane mail send --from "Arcane <verified@example.com>" --report-key <stable-id>
 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
+the sender). Direct sending supplies no fallback recipients. 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.
@@ -561,10 +587,40 @@ Subscription verification is disabled during initial setup when
 subscription key. Starting the ordinary CLI gateway uses this mode. This does
 not claim that a subscription was checked.
 
+### Automatic same-IP exception
+
+The gateway automatically skips subscription verification when the incoming
+connection's nonempty `request.socket.remoteAddress` equals
+`request.socket.localAddress`. This also applies when a verifier is configured
+and the request has no subscription key or supplies an invalid one. The
+verification callback is not called for that request.
+
+No `.arcane.env.json` setting or domain allowlist is needed. The comparison uses
+the actual source and destination IP addresses exposed by Node's request socket
+for HTTP/1.1 and HTTP/2. It adds no DNS lookup, configuration read, cache, or
+interface scan. `Origin`, `Host`, `Forwarded`, and `X-Forwarded-For` do not
+establish the connection's IP equality.
+
+| Caller connection | Subscription behavior with a verifier configured |
+| --- | --- |
+| The verification service connects to mail using the same source and destination IP | Skips subscription checking, allowing its service-generated emails without a subscriber key. |
+| A local development request has equal source and destination IPs, including an ordinary loopback connection | Uses the same automatic exception. There is no special loopback rule. |
+| Another machine on the same intranet connects from a different IP | Uses the configured subscription verifier. Sharing a network or subnet supplies no exception. |
+| Two services on one machine connect through different interface IPs | Uses the configured subscription verifier when the actual addresses differ. Machine identity alone supplies no exception. |
+| The request has no usable socket source address | Uses the configured subscription verifier; absent addresses do not count as equal. |
+
+The exception skips only subscription checking. Existing CORS, route, method,
+idempotency-key, report, recipient, and provider handling still apply. The gateway
+continues to require its Resend provider credential and reports acceptance only
+after the provider accepts the email.
+
+### Verification callback contract
+
 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
+The server then reports `callerAuthentication: 'subscription'`, identifying the
+configured mode while retaining the same-IP exception above. The callback
 contract is:
 
 ```javascript
@@ -577,7 +633,15 @@ 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.
+POST request outside the same-IP exception before any provider attempt; results
+are not cached.
+
+`X-Mail-App` identifies the originating app so the verifier can select that
+app's subscription account, such as the appropriate Stripe account for `BOSS`
+or `TWiN`. It is separate from the gateway's optional `--app` event label.
+The missing-header and Bearer errors below apply only when `verifySubscription`
+is configured and the same-IP exception does not apply. Ordinary `mail serve`
+does not require either header.
 
 | Configured-verifier outcome | Gateway response |
 | --- | --- |
@@ -602,6 +666,36 @@ CLI startup output says `Subscription verification: disabled` or
 `Subscription verification: configured`. Structured `server.ready` output
 includes the corresponding `callerAuthentication` value.
 
+## Error reports and retries
+
+An incoming report with `type: 'error'` is an email supplied by its caller.
+The gateway's `errorRecipients` setting only supplies fallback recipients for
+that report when its `to` array is empty. A gateway or provider failure returns
+an HTTP error and diagnostic events; it does not generate another error email.
+Gateway event-handler failures are written to the console. Each POST and each
+direct CLI send performs at most one provider attempt, with no automatic server retry.
+
+The browser outbox retains the same report and key after a retryable delivery
+failure. Each drain attempts each eligible record once; a later startup,
+connectivity event, or explicit drain can retry it. Browser `Errors` notification
+failure retains the same pending occurrence and logs a warning without scheduling
+itself again.
+
+A separate browser callback path can feed back into error reporting: a mail-event
+subscriber that repeatedly throws can reach global error capture, create another
+error report, and trigger another mail event. Subscriber failures cannot change
+an already committed mail result, though global capture can report them as new
+errors. This is a source-level possibility, not evidence of a deployed loop.
+
+For a verification service's own emails sent through the same IP, the gateway
+skips its subscription callback and proceeds to provider delivery. That removes
+the circular dependency `mail -> verify subscription -> send mail -> verify
+subscription` for this connection path. Connections from a different IP still
+use the configured callback, whose owning service must preserve a verification
+path that can return without recursively depending on another verification.
+The exception does not change the separate browser event-subscriber behavior
+described above.
+
 ## Gateway request lifecycle
 
 The gateway uses the published `node-http-server` instance lifecycle. Its raw

package/docs/reviews/mail-server-purpose-review.md

@@ -1,5 +1,10 @@
 [Roshi's Codex PRIME] The gateway review and its portable credential follow-up apply the same three purpose gates. The gateway removals preserve complete delivery outcomes, configured CORS and recipient policy, and the optional subscription verifier. Mail credentials now belong in the user-selected `.arcane.env.json`, with one portable Node implementation for Windows, Linux, and macOS and a compatible Node host as the Android adaptation boundary. The original gateway inventory below uses baseline `f055e05`; the credential follow-up reviews the Windows storage implementation present at SDK `0.18.0`. Commit, package, publication, and actual platform execution outcomes belong to the delivery record rather than to this source-review report.
 
+The [same-IP subscription exception follow-up](#same-ip-subscription-exception-follow-up)
+records the later user-selected change to when the optional verifier runs. The
+earlier inventories retain their stated historical scope; current verification
+skips requests whose actual connection source and destination IPs are equal.
+
 | Decision | Behavior | Why it matters | Source status at this review |
 | --- | --- | --- | --- |
 | Remove | Loopback-only admission, manual header reconstruction, address/origin normalization, local payload grammar, manual content-length scan, dead queue knobs | These restrict supported use, rewrite supplied values, or repeat work already owned elsewhere. | Removed from the inspected source; naming-only changes carry no runtime claim. |
@@ -480,7 +485,7 @@ files. Their explicit precedence and credential compatibility rules are in the
 | `readMailConfiguration` | Y/Y/N | Keep the cohesive configuration at the SDK owner. Send/serve read each required file once, in parallel when both are needed. A send with an injected credential reader skips the unused secrets file; incoming HTTP requests use the resolved configuration without file reads. Other capability settings stay untouched. |
 | CLI's early default host, port, and send/serve profile values | Y/Y/Y | Remove premature default assignment. The same defaults remain after file configuration resolves, while explicit CLI values retain priority. Assigning defaults before reading JSON would conceal the deployment's chosen settings. |
 | `origins` string array and list replacement | Y/Y/N | Keep one exact list for multiple caller domains. Explicit options replace the file list, including empty arrays. Existing `origin`, `allowTo`, `errorTo`, and `requestTimeout` aliases remain compatible and win over their canonical programmatic names when both are supplied. No normalization or list-merging helper is needed. |
-| Root provider-key, named-profile, and TLS compatibility | Y/Y/N | Preserve live deployments using `RESEND_API_KEY`, `MAIL_PROFILES`, `MAIL_TLS_CERT_PATH`, and `MAIL_TLS_KEY_PATH`. Nested selected key presence takes priority even when null or empty. Named profiles never select a different account's default key. |
+| Root provider-key, named-profile, and TLS compatibility | Y/Y/N | Preserve supported inputs using `RESEND_API_KEY`, `MAIL_PROFILES`, `MAIL_TLS_CERT_PATH`, and `MAIL_TLS_KEY_PATH`. Nested selected key presence takes priority even when null or empty. Named profiles never select a different account's default key. Named-profile deployment use is unverified; the retained behavior is a compatibility contract. |
 | Key set/status/delete operations | Y/Y/N | Preserve credential management and secret-free status. New keys use the nested member; existing legacy keys are updated in place unless a nested key exists. Delete removes both selected representations to prevent an old credential reappearing, preserving other keys, settings, and profile containers. Key commands still default to `mail` independently of the serving profile. |
 | Send configuration | Y/Y/N | Use the same profile, sender, provider-timeout, and retry-guidance settings for direct sending. A send needs provider authority and its report, so listener certificates remain a serve-only prerequisite. Reports and idempotency keys remain per-operation inputs. |
 | Explicit runtime dependencies and callbacks | Y/Y/N | Preserve `readCredential`, provider injection, observation, cancellation, and subscription callbacks as programmatic inputs. A function or signal is not JSON configuration. The portable browser mail import retains its existing dependency boundary. |
@@ -507,3 +512,92 @@ adaptation. Local tests, checks, server launches, live mail sends, and platform
 execution were not performed by this documentation author. Selected package
 verification and publication outcomes belong to the release owner's delivery
 record.
+
+## Parameter examples and error-report path clarification
+
+The ordinary shared mail server needs one Resend key. Its current-domain
+behavior, origin list, and incoming application/subscription verification do
+not select among provider profiles. A named profile selects one stored key
+for an entire send or server invocation. Source inspection found named CLI and
+toolchain inputs plus synthetic tests; it did not establish a deployment that
+uses named mail profiles.
+
+| Method or action | Gates | Decision, callers, and concrete purpose |
+| --- | --- | --- |
+| Explicit default `profile: 'mail'` in setup examples | N/N/Y | Remove the redundant setting. Omission already selects the default key when no named configuration is supplied. CLI send/serve still honor an explicitly selected profile or `mail.profile`. |
+| Extra `another-provider-account` credential placeholder | N/N/Y | Remove it from ordinary setup. It adds an unused account choice to a one-key configuration. Existing optional named-profile behavior remains documented without presenting another account as a setup requirement. |
+| Named-profile CLI/toolchain capability and credential CRUD | Y/Y/N for compatibility | Retain the supported optional profile argument and exact named-key operations. Concrete application/deployment use is unverified. This is an account-selection contract, separate from removing redundant default arguments; its retention makes no claim that the nominal deployment needs it. |
+| Full CLI parameter explanation | Y/Y/N | Keep one canonical [Mail CLI parameters](../reference/mail.md#mail-cli-parameters) table. The CLI reference links to it and describes the current split configuration, selected values, defaults, aliases, and provider behavior without another competing table. |
+| Claim that mail errors can never produce an error-report loop | N/N/Y | Replace the absolute claim with the source-path qualification below. Ordinary server failures do not send another mail; a repeatedly failing browser event subscriber can produce new global error incidents during error-mail delivery. |
+
+The Node gateway reports ordinary request/provider failures through responses,
+observer results, or its console logger. Its error reporter does not call the
+mail sender. In the browser, `Errors` owns global `error` and
+`unhandledrejection` capture and sends error notifications through Mail. A
+failed notification remains pending with a warning rather than immediately
+creating another notification from that send failure.
+
+There is a separate conditional path: a subscriber that repeatedly throws
+while handling Mail events reaches the event authority's listener-failure
+reporter. In browsers with `reportError`, that failure can become a new global
+error incident. Sending that incident through Mail can invoke the same failing
+subscriber again. A loop therefore depends on that subscriber and the active
+global error handler; it is not an automatic server response to an ordinary
+mail failure. This is a static source-path finding, not an observed production
+incident or an executed reproduction. This documentation clarification changes
+no error, subscription, retry, or delivery behavior.
+
+## Same-IP subscription exception follow-up
+
+The user selected an automatic same-IP exception so the verification service can
+send its own emails without a subscriber key. This supersedes the proposed
+domain exception in `.arcane.env.json`; neither an environment setting nor a
+domain allowlist is needed. The reusable decision belongs in the SDK's existing
+`handleMailRequest`, immediately at its subscription-verification branch.
+Application-owned messages, sender choices, subscription accounts, and the
+verification callback remain with their existing owners.
+
+The condition is a nonempty `request.socket.remoteAddress` equal to
+`request.socket.localAddress`. Matching requests skip `verifyMailSubscription`
+and the configured `verifySubscription` callback, including when the request
+has no subscriber key or supplies an invalid one. Requests with different or
+unavailable socket addresses retain the configured verification path. Omitting
+the callback continues to select the existing no-verification setup.
+
+| Method or action | Gate 1: Do we care? | Gate 2: Why is it worth the work? | Gate 3: Can we remove it without losing the required result? | Decision and concrete effect |
+| --- | --- | --- | --- | --- |
+| Automatic source/destination IP equality at `handleMailRequest` | Yes. The verifier needs to send service mail without a subscriber key. | It identifies the exact connection case the user selected using already-available socket fields. | No. Removing the exception would restore the verifier's dependency on subscription checking for its own mail. | Keep one inline equality decision with a nonempty source address. No new helper or configuration owner. |
+| Subscription checking for a matching connection | The subscription-verification capability matters; this particular call does not. | Requiring it for the verifier's own email adds an unnecessary dependency and can create a circular service call. | Yes. The user expressly permits these senders regardless of their subscription. | Skip the callback and its asynchronous wait for matching requests. A callback that contacts the verification service makes no such request on this path. |
+| Proposed `.arcane.env.json` domain exception, DNS resolution, address cache, and interface enumeration | No. The selected rule is actual IP equality and requires no setup. | These would introduce configuration, I/O, retained state, or a broader machine/domain interpretation absent from the selected outcome. | Yes. Native request socket fields already supply both values. | Add none. Secret files, named provider profiles, and current configuration loading remain unchanged. |
+| `Origin`, `Host`, `Forwarded`, or `X-Forwarded-For` as evidence of matching connection IPs | No. These request fields do not define the native socket endpoints. | Reading them for this exception would change its meaning and duplicate unrelated routing or CORS concerns. | Yes. The actual socket exposes the relevant addresses directly. | Keep header handling at its existing owner; none of these headers selects the exception. |
+| Special loopback, intranet, subnet, or same-machine rules | No. The selected condition is equal IPs. | A larger address policy would grant a different exception and add work. | Yes. Equal local-development addresses already use the ordinary equality path. | Add none. Another intranet machine with a different IP still uses configured verification. Services on one machine using different interface IPs may also require it. |
+| CORS, routing, methods, idempotency, report/recipient handling, provider result, and cancellation | Yes. These continue to determine the actual mail outcome. | Skipping subscription checking does not change the requested delivery or lifecycle contracts. | No. Their retained behavior supports complete delivery and honest results. | Preserve these owners and their current ordering. Provider acceptance remains separate from the subscription decision. |
+
+The operation graph adds one synchronous connection-address comparison at the
+existing request owner. A matching request avoids subscription header checking,
+callback invocation, and its asynchronous verification wait, then uses the
+ordinary provider path. There is no new file read, DNS request, timer, polling,
+cache, helper, shared-state lock, startup barrier, or per-platform process.
+Requests continue independently under the existing handler lifecycle. These are
+source-level operation changes, not measured timing improvements.
+
+The selected `node-http-server` raw-request hook supplies the native Node request.
+HTTP/1.1 and HTTP/2 both expose the needed address properties; the same Node
+contract applies on Windows, Linux, and macOS, with Android requiring a compatible
+Node host. The local socket address is the actual destination used by the
+connection, including when the listener binds `0.0.0.0`.
+[Node socket addresses](https://nodejs.org/api/net.html#socketlocaladdress) and
+[HTTP/2 request sockets](https://nodejs.org/api/http2.html#requestsocket)
+document these properties.
+
+For equal connection IPs, the verification service's own mail proceeds without
+calling that service again. This removes its circular subscription dependency
+on this path. It does not claim that arbitrary callback code or a repeatedly
+failing browser mail-event subscriber cannot create a separate feedback loop.
+The existing error and retry distinctions remain documented in the
+[mail reference](../reference/mail.md#error-reports-and-retries).
+
+This follow-up records the selected behavior and source review. No local test,
+check, build, server launch, live mail send, or platform execution was performed
+by this documentation author. Release and runtime evidence remain with the
+corresponding operation's owner.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/mail-server.mjs

@@ -899,8 +899,16 @@ function createConfiguredMailHandler(configuration){
             if(request.method!=='POST'){
                 throw new MailGatewayFault('mail_method_not_allowed',{statusCode:405});
             }
-            if(configuration.verifySubscription){
-                appId=await verifyMailSubscription(request,configuration,requestController.signal);
+            if (configuration.verifySubscription) {
+                const requesterIp = request.socket?.remoteAddress;
+                const serverIp = request.socket?.localAddress;
+                if (!requesterIp || requesterIp !== serverIp) {
+                    appId = await verifyMailSubscription(
+                        request,
+                        configuration,
+                        requestController.signal
+                    );
+                }
             }
             idempotencyKey=requireRequestHeader(request,'idempotency-key');
             const requestText=await readRequestBodyText(request,{