arcane-os 0.28.1 → 0.28.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.28.2
+
+- Redirect unmatched Mail server routes with `303 See Other` to
+  `https://<current hostname>/404.html`, using the request's HTTP/1 Host or
+  HTTP/2 authority and omitting the API listener port. The redirect has an empty
+  body and uses the existing HTTP server response interface.
+- Preserve `/v1/mail` requests with query strings, CORS and OPTIONS behavior,
+  method and API errors, subscription handling, and the complete Mail provider
+  and cancellation lifecycle. Client APIs, npm resource paths, dependencies,
+  and listener configuration are unchanged.
+
 ## 0.28.1
 
 - DBOPFS initialization opens the application's existing storage scope without

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.28.1` SDK contract. Applications pin one exact npm
+This checkout defines the `0.28.2` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/reference/mail.md

@@ -712,6 +712,22 @@ 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.
 
+Requests whose path does not match `/v1/mail` receive `303 See Other` with an
+empty body and `Location: https://<current-hostname>/404.html`. The destination
+uses the request's HTTP/2 authority or HTTP/1.1 Host hostname, omits the API port,
+and replaces the requested path and query. For example:
+
+| Unmatched request URL | Redirect destination |
+| --- | --- |
+| `https://mail.thewizardnexus.com:4433/` | `https://mail.thewizardnexus.com/404.html` |
+| `https://mail.precrisis.ai:4433/missing?example=1` | `https://mail.precrisis.ai/404.html` |
+
+The HTTPS website on the current hostname owns that page. The mail listener
+only returns the redirect. Requests to `/v1/mail`, including its query-bearing
+form, retain the existing CORS policy, OPTIONS preflight, method handling, and
+structured API errors. For example, `GET /v1/mail` still receives `405`.
+Subscription verification and its automatic same-IP exception remain unchanged.
+
 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

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

@@ -4,6 +4,9 @@ The [same-IP subscription exception follow-up](#same-ip-subscription-exception-f
 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.
+The [unmatched-route redirect follow-up](#unmatched-route-redirect-follow-up)
+records the later change from a missing-route JSON error to the hostname's
+HTTPS 404 page.
 
 | Decision | Behavior | Why it matters | Source status at this review |
 | --- | --- | --- | --- |
@@ -601,3 +604,28 @@ 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.
+
+## Unmatched-route redirect follow-up
+
+The user selected the Stripe server's redirect behavior for unmatched mail
+routes. The existing SDK `handleMailRequest` route decision owns this behavior:
+an unmatched path returns `303 See Other` with an empty body and a Location of
+`https://<current-hostname>/404.html`. The request authority supplies the hostname;
+the destination omits the API port and replaces the original path and query.
+The website on that hostname owns the page content.
+
+| 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 |
+| --- | --- | --- | --- | --- |
+| Unmatched-path JSON `404` response | No. The selected result is navigation to the hostname's 404 page. | Keeping it would preserve the superseded response instead of the requested navigation. | Yes, when replaced with the redirect at the existing route decision. | Replace only this response with `303` and an empty body. |
+| Current-hostname HTTPS redirect without the API port | Yes. It sends visitors to the requested website page. | One request-authority parse supplies the hostname for every deployment without another setting or domain table. | No. Removing it loses the explicitly selected destination. | Keep the decision inline in the existing native request handler; add no server, dependency, proxy, or file-serving path. |
+| Matched `/v1/mail` CORS, OPTIONS, method errors, subscription verification, same-IP exception, and delivery results | Yes. Existing applications depend on these mail contracts. | An unmatched navigation does not change how an actual API request is handled or reported. | No. Redirecting actual API failures would hide the caller's delivery outcome. | Preserve `/v1/mail` and its query-bearing form, including OPTIONS preflight, `405` for unsupported methods, and structured API errors. |
+
+An unmatched request ends at its existing route branch without entering
+subscription verification, report parsing, or provider delivery. There is one
+redirect response per unmatched request, with no new asynchronous wait, DNS
+lookup, configuration read, timer, or retained state. This is a source-level
+operation description; no timing improvement or deployed result is claimed.
+
+This follow-up is based on source review. This documentation author ran no local
+tests, checks, builds, server launches, or production requests. Delivery and
+selected-package verification remain with their respective owners.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -85,7 +85,7 @@
     "test": "npm run test:unit && npm run test:functional && npm run test:integration && npm run test:regression",
     "test:release": "node ./bin/arcane-test.mjs test/npm-release.test.mjs",
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
-    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
+    "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/modal.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
     "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",

package/src/mail-server.mjs

@@ -877,8 +877,21 @@ function createConfiguredMailHandler(configuration){
         });
 
         try{
-            if(request.url!==RESEND_MAIL_PATH&&!request.url?.startsWith(`${RESEND_MAIL_PATH}?`)){
-                throw new MailGatewayFault('mail_route_not_found',{statusCode:404});
+            if (request.url !== RESEND_MAIL_PATH && !request.url?.startsWith(`${RESEND_MAIL_PATH}?`)) {
+                const requestAuthority = request.authority || request.headers.host || '';
+                const hostname = new URL(`https://${requestAuthority}`).hostname;
+                response.writeHead(
+                    303,
+                    {
+                        'content-type': 'text/plain; charset=utf-8',
+                        'location': `https://${hostname}/404.html`
+                    }
+                );
+                response.end();
+                if (!request.readableEnded && !request.destroyed) {
+                    request.resume();
+                }
+                return;
             }
             const requestOrigin=request.headers.origin;
             if(requestOrigin){