arcane-os 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.

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.1` 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

@@ -985,7 +985,16 @@ application with `Authorization: Bearer <subscription_key>`.
 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
@@ -1016,7 +1025,7 @@ 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:
 
@@ -586,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
@@ -602,13 +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. Ordinary `mail serve` does not require either header.
+is configured and the same-IP exception does not apply. Ordinary `mail serve`
+does not require either header.
 
 | Configured-verifier outcome | Gateway response |
 | --- | --- |
@@ -654,10 +687,14 @@ 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 that sends its own emails, its host integration must
-also avoid the circular request path `mail -> verify subscription -> send mail ->
-verify subscription`. The SDK supplies a callback for verification; it does not
-choose that service's caller flow or enable it in ordinary CLI startup.
+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
 

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. |
@@ -541,3 +546,58 @@ 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.1",
+  "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,{