arcane-os 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.21.0
+
+- Serve mail over HTTPS with HTTP/2 through the published `node-http-server`
+  PEM API, with HTTP/1.1 fallback on the same selected port, default 8025.
+  Preserve the friendly occupied-port failure and owned listener lifecycle.
+- Read `MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH` with the provider profile
+  from `.env.json` in one startup read. Resolve relative PEM paths from that
+  file's directory and report missing TLS settings before binding. Keep file
+  and TLS handling portable across Windows, Linux and macOS.
+- Use native HTTP/2 headers and authority for the mail and CORS contracts,
+  preserving exact report content, subscription verification, provider
+  outcomes, existing credential injection and cancellation.
+- Extend the mail reference and purpose-gate report with TLS ownership and
+  configuration; add focused protocol and configuration test source.
+
 ## 0.20.0
 
 - Restore repository-shaped application packages: selected app files remain

package/README.md

@@ -19,12 +19,13 @@ 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.20.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.21.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
+The [mail gateway](docs/reference/mail.md) serves HTTPS with HTTP/2 on port 8025,
+using certificate paths from `.env.json`, 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.

package/docs/reference/cli.md

@@ -48,7 +48,7 @@ meaning and cardinality rules:
 | `--workspace` | directory | Commands that select an external or integrated workspace; defaults to `.`. |
 | `--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 `0.0.0.0:8025` and accepts an explicit bind host. |
+| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTPS with HTTP/2 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. |
@@ -906,7 +906,7 @@ loss after the attempt begins is ambiguous because Resend may have accepted it.
 
 ### Mail gateway
 
-`mail serve` starts one owned Node HTTP gateway:
+`mail serve` starts one owned HTTPS gateway with HTTP/2:
 
 ```text
 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>]
@@ -914,6 +914,30 @@ arcane mail serve [--profile <profile>] [--from <verified-sender>] [--app <label
 
 The selected `.env.json` profile supplies only the server-side Resend API key;
 omitting `--profile` selects `mail`.
+
+Add the listener's certificate configuration at the top level of the same file:
+
+```json
+{
+  "RESEND_API_KEY": "",
+  "MAIL_TLS_CERT_PATH": ".arcane/mail/fullchain.pem",
+  "MAIL_TLS_KEY_PATH": ".arcane/mail/private-key.pem"
+}
+```
+
+Supply an existing PEM certificate chain and its private key. Paths resolve
+relative to `.env.json`, or may be absolute. They are shared across provider
+profiles. 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 `.env.json`.
+
+The selected `node-http-server` module negotiates HTTP/2 with HTTP/1.1 fallback
+on the same HTTPS port, default `8025`, with no plain-HTTP listener. Callers use
+a hostname covered by the certificate, such as
+`https://mail.example.com:8025/v1/mail`; `0.0.0.0` identifies the bind address.
+Restart the gateway after replacing renewed certificate files. Certificate
+issuance and renewal remain with the deployment's certificate owner.
+
 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

package/docs/reference/mail.md

@@ -273,11 +273,13 @@ committed acceptance result.
 ## Operate the CLI and gateway
 
 Create `.env.json` in the directory from which the mail command runs, then fill
-in the provider key:
+in the provider key and the HTTPS certificate paths:
 
 ```json
 {
-  "RESEND_API_KEY": ""
+  "RESEND_API_KEY": "",
+  "MAIL_TLS_CERT_PATH": "",
+  "MAIL_TLS_KEY_PATH": ""
 }
 ```
 
@@ -370,6 +372,34 @@ 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.
 
+`mail serve` uses HTTPS with HTTP/2 on that selected port. The published
+`node-http-server` PEM API owns TLS and negotiates HTTP/2 or HTTP/1.1 on the
+same listener. It creates no additional plain-HTTP listener. The returned URL
+uses `https://`; `0.0.0.0` is the bind address, so callers use the deployed
+domain, for example `https://mail.example.com:8025/v1/mail`.
+
+Set `MAIL_TLS_CERT_PATH` to the PEM certificate chain and `MAIL_TLS_KEY_PATH`
+to its PEM private-key file. These top-level settings belong to the listener
+and apply regardless of the selected provider profile. Relative paths resolve
+from the directory containing `.env.json`; absolute paths are also accepted.
+The certificate must cover the hostname callers use. One certificate may
+cover multiple names; the gateway does not require one certificate per calling
+application. Keep private-key files outside tracked source, such as in the
+already-ignored `.arcane/` directory or an existing host certificate directory.
+
+Startup reads the JSON configuration once, reports missing TLS settings before
+binding, and lets the TLS owner report unreadable or unusable PEM files. It
+does not generate certificates, modify system trust, or add a renewal watcher.
+Restart the gateway after the configured certificate files are renewed.
+The same Node file and TLS APIs are used on Windows, Linux, and macOS; Android
+requires a compatible Node host and accessible configuration and certificate
+paths. These platform contracts are separate from actual platform execution.
+
+The public `createToolchain().mail({action: 'serve', ...options})` operation
+uses the same JSON certificate pair. Internally, `startResendMailServer` accepts
+`certPath` and `keyPath` and retains its existing HTTP behavior when neither
+is supplied. That internal function is not an npm package export.
+
 If the selected port is occupied, startup reports
 `Mail port <port> is already taken, possibly by another mail server.`
 The CLI exits with status 1. Programmatic callers receive the same message,
@@ -383,7 +413,8 @@ 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.
+authority (`:authority` for HTTP/2, `Host` for HTTP/1.1) 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.
 
@@ -423,7 +454,7 @@ 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 empty `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` |
@@ -435,6 +466,11 @@ result. The SDK supplies no default verification URL or built-in Stripe
 endpoint adapter. Connecting the actual subscription endpoint is a separate
 hosting integration.
 
+The gateway uses Node's native header representations. HTTP/1.1 uses
+`headersDistinct`, retaining its repeated-field detection. HTTP/2 uses the
+compatibility request's `headers` object; Node owns duplicate joining or
+discarding for each field. The SDK does not split a native header value again.
+
 CLI startup output says `Subscription verification: disabled` or
 `Subscription verification: configured`. Structured `server.ready` output
 includes the corresponding `callerAuthentication` value.

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

@@ -391,3 +391,35 @@ review does not claim execution on those platforms or an actual provider send.
 The updated test source covers disposable JSON storage, exact named selection,
 preservation of other settings, missing settings, credential-free error output,
 cancellation before writes, and CLI defaults. Local tests and checks were not run.
+
+## HTTPS and HTTP/2 follow-up
+
+The user explicitly selected HTTPS with HTTP/2. The mail listener remains on
+its dedicated configured port, default 8025, with the published
+`node-http-server` module owning TLS, protocol negotiation and listener/session
+shutdown. This increment preserves the provider attempt, report content,
+subscription callback, sender selection, recipient configuration and cancellation.
+
+| Method or action | Gates | Decision, callers, and concrete purpose |
+| --- | --- | --- |
+| `readMailServerSettings` | Y/Y/N | Read the same `.env.json` once for server startup, select the existing provider profile and resolve the two shared PEM path settings relative to that file. This avoids a second configuration read and platform-specific credential or certificate processes. |
+| `readMailProviderKey` and `serveMailGateway` | Y/Y/N | Preserve the existing credential-injection interface and missing-provider error while consuming the already-read startup key. Require the selected TLS pair before binding; forward only the paths to the listener. Direct provider sending and key CRUD remain unchanged. |
+| `MAIL_TLS_CERT_PATH` and `MAIL_TLS_KEY_PATH` | Y/Y/N | Clear top-level names identify certificate and private-key file paths for one listener, independently of any provider profile or calling application. Missing settings and unusable JSON values name the field without printing its content. |
+| `startResendMailServer` TLS options | Y/Y/N | Add `certPath` and `keyPath` through the module's published PEM API. HTTPS-only mode creates one listener with HTTP/2 and HTTP/1.1 negotiation on the selected port. This internal source integration retains its existing HTTP behavior when neither path is supplied; it is not an npm package export. The public toolchain mail operation requires the JSON pair. |
+| `listenForMailRequests` and returned URL | Y/Y/N | Observe the actual secure listener for bind errors and advertise HTTPS when selected. Preserve the friendly occupied-port failure, native cause, cancellation and owned shutdown. |
+| Native mail header access and current-domain comparison | Y/Y/Y | Remove the HTTP/1-only assumption that every request has `headersDistinct` and `Host`. HTTP/2 supplies native `headers` and `authority`; consume those directly without rebuilding or splitting headers. Node owns its HTTP/2 duplicate-field behavior. |
+| Certificate generation, platform trust changes, renewal watchers, duplicate PEM reads and a development-server import | N/N/Y | Add none. The operator supplies an existing certificate pair; the HTTP server module owns PEM loading. The development resolver has development-specific defaults and errors, so importing or extracting it adds no useful shared behavior for these two path resolutions. |
+
+Ordinary startup performs one JSON read, two path resolutions and one listener
+launch. Certificate file reads occur once at the module's transport owner.
+There are no new per-request file reads, provider requests, polling loops or
+certificate processes. These are source observations, not measured speedups.
+The JSON and Node TLS paths are portable across Windows, Linux and macOS;
+Android needs a compatible Node host and readable configuration/certificate files.
+
+Focused test source covers TLS option selection, the secure listener's occupied
+port, HTTP/2 header/authority handling, provider and subscription forwarding,
+JSON paths and missing TLS settings. Synthetic TLS selection is not evidence of
+an encrypted handshake. No local tests, checks, server launch, real TLS
+negotiation or provider send were performed for this follow-up review. Selected
+package and publication results belong to the delivery record.

package/package.json

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

package/src/cli/main.mjs

@@ -86,6 +86,7 @@ Usage:
   ${CLI_NAME} mail key delete [profile]
   ${CLI_NAME} mail send [--profile <profile>] [--from <address>] --report-key <id> --report-stdin [--request-timeout <ms>]
   ${CLI_NAME} mail serve [--profile <profile>] [--from <address>] [--app <label>] [--origin <origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 8025] [--request-timeout <ms>]
+    HTTPS/HTTP2; .env.json supplies RESEND_API_KEY, MAIL_TLS_CERT_PATH, and MAIL_TLS_KEY_PATH.
 
 Development:
   --public                      Bind dev to all IPv4 interfaces (0.0.0.0) and print network URLs.

package/src/mail-credentials.mjs

@@ -111,6 +111,32 @@ export async function readMailCredential(options={}){
     return configuredMailKey(settings,location);
 }
 
+export async function readMailServerSettings(options = {}) {
+    const location = mailCredentialLocation(options);
+    const settings = await readMailSettings(location.filePath, options.signal);
+    const serverSettings = (options.readCredential ?? null) === null
+        ? {apiKey: configuredMailKey(settings, location)}
+        : {};
+    const tlsSettings = {
+        MAIL_TLS_CERT_PATH: 'certPath',
+        MAIL_TLS_KEY_PATH: 'keyPath'
+    };
+    for (const [setting, option] of Object.entries(tlsSettings)) {
+        const value = settings[setting];
+        if (value === undefined || value === null || value === '') {
+            continue;
+        }
+        if (!is.string(value)) {
+            throw new ArcaneError(
+                ERROR_CODES.usage,
+                `${setting} in ${location.filePath} must be a PEM file path string.`
+            );
+        }
+        serverSettings[option] = path.resolve(path.dirname(location.filePath), value);
+    }
+    return serverSettings;
+}
+
 export async function getMailCredentialStatus(options={}){
     const location=mailCredentialLocation(options);
     const settings=await readMailSettings(location.filePath,options.signal);

package/src/mail-server.mjs

@@ -134,20 +134,33 @@ function createRequestId(factory){
     return randomUUID();
 }
 
-function requireRequestHeader(request,headerName){
-    const headerValues=request.headersDistinct[headerName]??[];
-    if(headerValues.length!==1||!headerValues[0]){
-        throw new MailGatewayFault('mail_invalid_headers',{statusCode:400});
+function readRequestHeader(request, headerName) {
+    const distinctHeaders = request.headersDistinct;
+    if (distinctHeaders) {
+        const headerValues = distinctHeaders[headerName] ?? [];
+        return headerValues.length === 1 ? headerValues[0] : undefined;
+    }
+    // HTTP/2 owns header normalization and does not expose headersDistinct.
+    return request.headers[headerName];
+}
+
+function requireRequestHeader(request, headerName) {
+    const headerValue = readRequestHeader(request, headerName);
+    if (!headerValue) {
+        throw new MailGatewayFault(
+            'mail_invalid_headers',
+            {statusCode: 400}
+        );
     }
-    return headerValues[0];
+    return headerValue;
 }
 
 async function verifyMailSubscription(request,configuration,signal){
     const appName=requireRequestHeader(request,'x-mail-app');
-    const authorizationHeaders=request.headersDistinct.authorization??[];
-    const subscriptionKey=authorizationHeaders.length===1
-        ?/^Bearer (.+)$/iu.exec(authorizationHeaders[0])?.[1]
-        :undefined;
+    const authorization = readRequestHeader(request, 'authorization');
+    const subscriptionKey = authorization
+        ? /^Bearer (.+)$/iu.exec(authorization)?.[1]
+        : undefined;
     if(!subscriptionKey){
         throw new MailGatewayFault('mail_subscription_required',{statusCode:401});
     }
@@ -869,10 +882,11 @@ function createConfiguredMailHandler(configuration){
             }
             const requestOrigin=request.headers.origin;
             if(requestOrigin){
+                const requestAuthority = request.authority || request.headers.host;
                 const originAllowed=configuration.allowedOrigins.size>0
                     ?configuration.allowedOrigins.has(requestOrigin)
-                    :requestOrigin===`https://${request.headers.host}`
-                        ||requestOrigin===`http://${request.headers.host}`;
+                    :requestOrigin===`https://${requestAuthority}`
+                        ||requestOrigin===`http://${requestAuthority}`;
                 if(!originAllowed){
                     throw new MailGatewayFault('mail_origin_not_allowed',{statusCode:403});
                 }
@@ -1008,7 +1022,8 @@ function listenForMailRequests(mailServer){
             server.removeListener('error',onError);
             resolve(server);
         });
-        mailServer.server.once('error',onError);
+        const listener = mailServer.secureServer ?? mailServer.server;
+        listener.once('error', onError);
     });
 }
 
@@ -1017,11 +1032,24 @@ export async function startResendMailServer(options={}){
     if(configuration.signal?.aborted){
         throw configuration.signal.reason??new Error('Mail server start was cancelled.');
     }
-    const mailServer=new Server({
-        host:configuration.host,
-        port:configuration.port,
-        server:{timeout:0}
-    });
+    if ((options.certPath === undefined) !== (options.keyPath === undefined)) {
+        throw configurationError('Mail HTTPS requires both certPath and keyPath when either is supplied.');
+    }
+    const httpsSelected = options.certPath !== undefined;
+    const mailServer = new Server(
+        {
+            host: configuration.host,
+            port: configuration.port,
+            server: {timeout: 0},
+            https: httpsSelected ? {
+                certificate: options.certPath,
+                privateKey: options.keyPath,
+                port: configuration.port,
+                only: true,
+                http2: true
+            } : {}
+        }
+    );
     const requestHandler=createConfiguredMailHandler(configuration);
     mailServer.onRawRequest=function routeRawMailRequest(request,response){
         requestHandler.handle(request,response);
@@ -1050,7 +1078,7 @@ export async function startResendMailServer(options={}){
         throw configurationError('Mail server has no TCP listener address.');
     }
     const displayHost=address.address.includes(':')?`[${address.address}]`:address.address;
-    const origin=`http://${displayHost}:${String(address.port)}`;
+    const origin = `${httpsSelected ? 'https' : 'http'}://${displayHost}:${String(address.port)}`;
     let closePromise=null;
     let resolveLifecycle;
     let rejectLifecycle;

package/src/mail.mjs

@@ -5,6 +5,7 @@ import {
     getMailCredentialStatus,
     mailCredentialLocation,
     readMailCredential,
+    readMailServerSettings,
     setMailCredential
 } from './mail-credentials.mjs';
 import {sendResendMail,startResendMailServer} from './mail-server.mjs';
@@ -125,10 +126,11 @@ async function sendMailFromReport(options){
     }
 }
 
-async function readMailProviderKey(options){
-    const readCredential=resolveMailCommandDependency(options,'readCredential',readMailCredential);
+async function readMailProviderKey(options, serverSettings){
     const credentialOptions=mailCredentialOptions(options);
-    const apiKey=await readCredential(credentialOptions);
+    const apiKey = serverSettings !== undefined && (options.readCredential ?? null) === null
+        ? serverSettings.apiKey
+        : await resolveMailCommandDependency(options, 'readCredential', readMailCredential)(credentialOptions);
     if(apiKey===null){
         const location=mailCredentialLocation(credentialOptions);
         throw new ArcaneError(
@@ -147,10 +149,25 @@ async function readMailProviderKey(options){
 
 async function serveMailGateway(options){
     const startServer=resolveMailCommandDependency(options,'startServer',startResendMailServer);
+    const readServerSettings = resolveMailCommandDependency(options, 'readServerSettings', readMailServerSettings);
     throwIfAborted(options.signal);
-    let apiKey=await readMailProviderKey(options);
+    const serverSettings = await readServerSettings(
+        {...mailCredentialOptions(options), readCredential: options.readCredential}
+    );
+    throwIfAborted(options.signal);
+    let apiKey=await readMailProviderKey(options, serverSettings);
     try{
         throwIfAborted(options.signal);
+        const missingSettings = [];
+        if (!serverSettings.certPath) missingSettings.push('MAIL_TLS_CERT_PATH');
+        if (!serverSettings.keyPath) missingSettings.push('MAIL_TLS_KEY_PATH');
+        if (missingSettings.length) {
+            const location = mailCredentialLocation(options);
+            throw new ArcaneError(
+                ERROR_CODES.prerequisiteMissing,
+                `Missing ${missingSettings.join(', ')} in ${location.filePath}. Mail HTTPS requires a certificate and private key.`
+            );
+        }
         const recipientAllowlist=mailRecipientOptions(options.allowTo,'allowTo');
         const errorRecipients=options.errorTo===undefined
             ? recipientAllowlist
@@ -162,10 +179,12 @@ async function serveMailGateway(options){
                 ?[]
                 :is.array(options.origin)?[...options.origin]:[options.origin],
             bodyTimeoutMs:options.bodyTimeoutMs,
+            certPath:serverSettings.certPath,
             errorRecipients,
             fetchImpl:options.fetchImpl,
             from:options.from,
             host:options.host??'0.0.0.0',
+            keyPath:serverSettings.keyPath,
             onEvent:options.onEvent,
             port:options.port,
             providerTimeoutMs:options.requestTimeout,