arcane-os 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.22.0
+
+- Export `generateDocumentImportMaps()` from `arcane-os` for explicitly selected
+  host HTML documents and an existing materialized runtime. Generate each
+  document's SDK import URLs from its authored base without app discovery or
+  imposing an application layout.
+- Preserve complete authored HTML, resource URLs, custom import maps and script
+  loading order while updating only SDK-managed map blocks. Encode runtime
+  filenames and rebase both targets and URL compatibility keys.
+- Inventory the selected runtime once per batch, prepare every document before
+  writing, and expose ordered write events, cancellation and event-delivery
+  failures. Document the public API and add focused behavioral test source.
+- Preserve the platform's existing cancellation code in the import-map and
+  runtime-inventory paths, including ordinary `AbortController.abort()`.
+
+## 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.22.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/architecture.md

@@ -74,6 +74,16 @@ migration; the current tree has no OS-to-SDK synchronization path.
 
 ## Workspace profiles
 
+Hosts with an existing HTML layout can call the root-exported
+[`generateDocumentImportMaps()`](reference/sdk-api.md#generatedocumentimportmaps)
+with a document root, explicit page paths, and an already materialized runtime.
+This SDK-owned operation builds the shared map once and renders each page's
+URLs from its authored base, preserving page content and script order. It
+updates only SDK-managed inline maps; the host owns document selection,
+runtime materialization, serving, and coordination with other writers. This
+path requires no application descriptor or `apps/<id>/` layout and leaves the
+app-scoped toolchain operation unchanged.
+
 An external workspace maps the exact runtime shipped by its locked `arcane-os`
 dependency. An Arcane OS checkout is an integrated SDK consumer, not the owner
 of portable runtime source. For live shared development, the explicit

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/inventory/package-api.json

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 209,
+  "memberCount": 210,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -772,6 +772,22 @@
       "protocol": "Node ESM",
       "normalization": "ArcaneError and JSON-safe error normalization"
     },
+    {
+      "id": "root:generateDocumentImportMaps",
+      "name": "generateDocumentImportMaps",
+      "displayName": "generateDocumentImportMaps()",
+      "kind": "function",
+      "signature": "async generateDocumentImportMaps({documentRoot, runtimeRoot, documents, version=SDK_VERSION, deploymentUrl, signal, onEvent}={})",
+      "entrypoints": [
+        "arcane-os"
+      ],
+      "primaryImport": "arcane-os",
+      "group": "Runtime and app descriptors",
+      "summary": "Writes SDK-managed inline import maps for explicit host documents using an existing materialized runtime and each document's authored base.",
+      "availability": "Node on Windows, Linux, and macOS",
+      "protocol": "Explicit host documents",
+      "normalization": "Absolute filesystem result paths, document-relative browser maps, ordered write events, cancellation, and degraded event-delivery reporting"
+    },
     {
       "id": "root:getSdkBrowserRuntimeRoot",
       "name": "getSdkBrowserRuntimeRoot",

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/reference/protocols.md

@@ -47,7 +47,7 @@ These protocols normalize orchestration and results. They do not normalize a
 Windows EXE, Linux DEB, Android APK, and portable directory into the same
 artifact kind.
 
-Managed browser imports have three supported control-plane entrypoints. The CLI
+App-scoped managed browser imports have three supported control-plane entrypoints. The CLI
 uses `arcane import-map`; Node callers use
 `executeOperation('import-map', options)` or
 `createToolchain(defaults).importMap(options)`. These are three routes to the
@@ -70,6 +70,9 @@ subpath owns shared speech-input cleanup and has the same
 managed browser key. There is
 no exported `importMapApplication()` function, `generateImportMap()` function, or
 `arcane-os/import-map` package subpath.
+Explicit host document lists use the separate root-exported
+[`generateDocumentImportMaps()`](sdk-api.md#generatedocumentimportmaps) API
+described below; they do not enter app discovery.
 
 The application dependency boundary is conditional. Only an application that
 actually consumes Arcane declares one exact published `arcane-os` version in
@@ -147,6 +150,27 @@ unsafe structure and grants no Core capability or provider authority.
 See [EventManager and time-travel review](event-manager.md) for the callable
 surface, DOM privacy defaults, playback modes, and recovery behavior.
 
+## Explicit host documents
+
+`generateDocumentImportMaps()` accepts one document root, an existing
+materialized runtime root, and explicit document-root-relative paths. It
+inventories the runtime and constructs the shared browser map once per call,
+then resolves each document's map against its first href-bearing base or its
+own URL. An absolute or root-relative base, or a relative base traversing above
+the document root, requires the caller's directory `deploymentUrl`; target-only
+bases leave URL resolution unchanged.
+
+The operation preserves authored content, resource URLs, custom import maps,
+and script order, updating only SDK-managed inline map blocks. It prepares all
+documents before sequential writes and reports `import-map.documents.started`,
+`import-map.write.progress`, and `import-map.documents.completed`. Cancellation
+can leave completed document writes in place. Successful writes remain
+successful when event delivery fails, with a degraded-delivery record in the
+return value. Runtime materialization, serving, and writer coordination remain
+with the caller. See the [API guide](sdk-api.md#generatedocumentimportmaps) for
+the complete inputs, results, errors, and example. The app-scoped discovery and
+map-artifact lifecycle below remains separate.
+
 ## Browser runtime delivery
 
 External and modern integrated workspaces keep the same application URLs and a

package/docs/reference/sdk-api.md

@@ -153,6 +153,7 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `executeNativeBuildPlan()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `executeOperation()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
 | `fail()` | function | `arcane-os` | Errors | Node |
+| `generateDocumentImportMaps()` | function | `arcane-os` | Runtime and app descriptors | Node; explicit documents and an existing materialized runtime |
 | `getSdkBrowserRuntimeRoot()` | function | `arcane-os` | Runtime and app descriptors | Node |
 | `getSdkRoot()` | function | `arcane-os` | Runtime and app descriptors | Node |
 | `getTargetAdapter()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
@@ -1137,6 +1138,161 @@ import {APP_DESCRIPTOR_SCHEMA_VERSION} from 'arcane-os';
 console.log(APP_DESCRIPTOR_SCHEMA_VERSION);
 ```
 
+## generateDocumentImportMaps()
+
+### Overview
+
+Writes SDK-managed inline browser import maps into explicitly selected HTML
+documents. Hosts can keep their existing page layout and use an already
+materialized Arcane runtime without an app descriptor, app discovery, or an
+`apps/<id>/` directory. The existing app-scoped `arcane import-map` operation
+continues to own descriptor-selected application pages and its map artifact.
+
+### Signature and result
+
+```text
+async generateDocumentImportMaps({
+    documentRoot,
+    runtimeRoot = path.join(documentRoot, 'arcane'),
+    documents,
+    version = SDK_VERSION,
+    deploymentUrl,
+    signal,
+    onEvent
+} = {})
+```
+
+Import it from `arcane-os`.
+
+| Input | Contract |
+| --- | --- |
+| `documentRoot` | Required filesystem directory containing the selected documents. Returned root paths are absolute. |
+| `runtimeRoot` | Existing materialized runtime directory containing `modules/`, `entities/`, `sdk/`, and its other selected content. Defaults to `arcane/` under `documentRoot`. Pass an absolute path when selecting another directory; relative root arguments resolve from the current working directory. |
+| `documents` | Required nonempty array of document-root-relative file paths, such as `['shell/home.html', 'settings.html']`. Use forward slashes and normalized paths without a leading `./` or parent traversal. Duplicate paths are processed once, in first-selected order. |
+| `version` | Version used in generated import-map targets and URL compatibility keys. Defaults to the installed SDK's `SDK_VERSION`; `null` selects unversioned map URLs. Authored resource URLs outside the managed map stay unchanged. |
+| `deploymentUrl` | Optional absolute directory URL ending in `/` that corresponds to `documentRoot`, such as `https://example.com/control/`. Required when a selected document has an absolute or root-relative base URL, or a relative base that traverses above `documentRoot`. |
+| `signal` | Optional `AbortSignal`, observed during inventory, document preparation, and before each write. |
+| `onEvent` | Optional named callback receiving the ordered events below. An asynchronous callback is awaited before the operation continues. |
+
+The resolved result contains:
+
+```text
+{
+    documentRoot,
+    runtimeRoot,
+    documentPaths,
+    documentCount,
+    documents: [{path, filePath, imports}],
+    committed: true
+}
+```
+
+`documentPaths` and each `filePath` are absolute filesystem paths. Each `path`
+is relative to `documentRoot`; `imports` is the complete map rendered for that
+document. The operation inventories the runtime once, builds the shared map
+once, and reads the selected documents with up to four concurrent readers.
+It renders every document before writing any of them, then writes in selected
+order. `committed: true` means all selected writes completed; the batch is not
+an atomic filesystem transaction.
+
+### Document URLs and authored content
+
+The first `<base>` with an `href` determines each document's effective base.
+A target-only base, such as `<base target="_blank">`, does not change URL
+resolution. With no base, `shell/home.html` resolves the default runtime through
+`../arcane/`. With `<base href="../">`, the same page resolves it through
+`./arcane/`. Generated URLs include the selected version when one is supplied.
+
+The host serves the runtime at the same relative location as `runtimeRoot`
+has to `documentRoot`. `deploymentUrl` supplies that directory's public URL
+when an authored base needs an origin or deployment path to resolve correctly.
+For example, `https://example.com/control/` corresponds to `documentRoot`, so
+its default runtime is served at `https://example.com/control/arcane/`.
+Cross-origin bases produce absolute runtime map URLs. Without `deploymentUrl`,
+an absolute or root-relative base causes a `TypeError` before any document is
+written. A relative base that traverses above `documentRoot` also requires
+`deploymentUrl`, even if later path segments return into the physical directory:
+the filesystem's parent names do not establish public deployment paths.
+The two filesystem roots must share a volume.
+
+The generator replaces only SDK-marked `<script type="importmap"
+data-arcane-import-map>` ranges, consolidating multiple SDK blocks into one.
+It preserves complete authored HTML around those ranges, including whitespace,
+resource URLs, custom import maps, and the attributes and order of classic,
+module, `async`, and `defer` scripts. Custom maps remain separate and are not
+merged into the SDK map. The managed block follows the effective base and
+precedes executable scripts and module preloads. An authored base that follows
+one of those loads is reported as `ARCANE_IMPORT_MAP_INVALID` before writes.
+
+This operation writes only the selected HTML files. The caller owns runtime
+materialization, document selection, serving, and coordination with other
+document writers. It creates no map sidecar, copies no runtime content, and
+starts no build or browser.
+
+### Events, errors, and cancellation
+
+| Event | Fields |
+| --- | --- |
+| `import-map.documents.started` | `documentRoot`, `runtimeRoot`, and the complete `documentPaths` selection. |
+| `import-map.write.progress` | `paths`: all absolute document paths successfully written so far. |
+| `import-map.documents.completed` | The successful result fields, including `committed: true`. |
+
+If an event callback throws or rejects, generation continues. A successful
+return additionally reports `eventDelivery: {status: 'degraded', errorCode:
+'ARCANE_EVENT_DELIVERY_FAILED', message}` for the first callback failure.
+
+Invalid options can throw `TypeError`; document/map structure failures use
+`ARCANE_IMPORT_MAP_INVALID`, runtime inventory failures use
+`ARCANE_RUNTIME_INVALID`, and filesystem failures propagate. All started
+preparation reads settle before rejection; multiple failures are
+reported together in an `AggregateError`. Cancellation
+rejects with the signal's error reason when supplied, otherwise an operation
+cancellation error; an error lacking a code receives `ARCANE_CANCELLED`.
+Preparation failures occur before writes. Cancellation or a filesystem failure
+during writing can leave earlier completed files updated; the operation does
+not roll those files back. An in-flight filesystem write completes before the
+next cancellation boundary.
+
+### Availability and normalization
+
+**Node on Windows, Linux, and macOS.** Filesystem paths are resolved with the
+host path API; browser import URLs use forward slashes and URL encoding. Deep
+protocol: [Explicit host documents](protocols.md#explicit-host-documents).
+
+### Example
+
+A dragon observatory keeps its control page at `shell/home.html`, settings at
+`settings.html`, and its selected Arcane runtime at `arcane/`. Run this from
+that document root after materializing the runtime:
+
+```javascript
+import {generateDocumentImportMaps} from 'arcane-os';
+
+const controller = new AbortController();
+
+function reportImportMapEvent(event) {
+    console.log(event);
+}
+
+const result = await generateDocumentImportMaps(
+    {
+        documentRoot: process.cwd(),
+        documents: ['shell/home.html', 'settings.html'],
+        signal: controller.signal,
+        onEvent: reportImportMapEvent
+    }
+);
+
+for (const document of result.documents) {
+    console.log(document.path, document.imports['arcane/AI']);
+}
+```
+
+Change the explicit document list to update another host page. If either page
+uses `<base href="/control/">`, add
+`deploymentUrl: 'https://example.com/control/'` to the options. Both pages keep
+their authored layout and receive map URLs appropriate to their own base.
+
 ## getSdkBrowserRuntimeRoot()
 
 ### Overview

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.22.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/import-map.mjs

@@ -3,6 +3,7 @@ import {lstat,mkdir,readFile as readFileFromDisk,readdir,realpath,writeFile} fro
 import path from 'node:path';
 import {pathToFileURL} from 'node:url';
 import {SDK_VERSION} from './constants.mjs';
+import {listRuntimeFiles} from './runtime.mjs';
 
 const is = new Is(false);
 
@@ -39,7 +40,7 @@ function fail(message,code='ARCANE_IMPORT_MAP_INVALID'){
 function throwIfAborted(signal){
     if(!signal?.aborted)return;
     const error=signal.reason instanceof Error?signal.reason:new Error('Operation cancelled.');
-    error.code=error.code||'ARCANE_CANCELLED';
+    if(error.code===undefined)error.code='ARCANE_CANCELLED';
     throw error;
 }
 
@@ -1296,9 +1297,16 @@ function validateInventory(files){
     return exact;
 }
 
-export async function buildImportMap({files,signal,version=SDK_VERSION}={}){
+function encodedUrlPath(relative) {
+    return relative.split('/').map(encodeURIComponent).join('/');
+}
+
+export async function buildImportMap({files,signal,version=SDK_VERSION,encodePaths=false}={}){
     throwIfAborted(signal);
     const inventory=validateInventory(files);
+    function runtimeTarget(relative) {
+        return `./arcane/${encodePaths ? encodedUrlPath(relative) : relative}`;
+    }
     const modules=[...inventory]
         .filter(relative=>relative.startsWith('modules/')
             &&!relative.slice('modules/'.length).includes('/')
@@ -1308,7 +1316,7 @@ export async function buildImportMap({files,signal,version=SDK_VERSION}={}){
     for(const relative of modules){
         throwIfAborted(signal);
         const name=path.posix.basename(relative).replace(JAVASCRIPT_EXTENSION,'');
-        registerSpecifier(namedRegistry,`arcane/${name}`,`./arcane/${relative}`);
+        registerSpecifier(namedRegistry,`arcane/${name}`,runtimeTarget(relative));
     }
     const entities=[...inventory].filter(relative=>relative.startsWith('entities/')
         &&!relative.slice('entities/'.length).includes('/')
@@ -1316,7 +1324,7 @@ export async function buildImportMap({files,signal,version=SDK_VERSION}={}){
     for(const relative of entities){
         throwIfAborted(signal);
         const name=path.posix.basename(relative).replace(JAVASCRIPT_EXTENSION,'');
-        registerSpecifier(namedRegistry,`arcane/entities/${name}`,`./arcane/${relative}`);
+        registerSpecifier(namedRegistry,`arcane/entities/${name}`,runtimeTarget(relative));
     }
     for(const [specifier,relative] of STATIC_RUNTIME_PACKAGE_IMPORTS){
         if(inventory.has(relative)){
@@ -1363,7 +1371,8 @@ export async function buildImportMap({files,signal,version=SDK_VERSION}={}){
     }
     for(const relative of [...inventory].sort(compareText)){
         if(JAVASCRIPT_EXTENSION.test(relative)){
-            registerSpecifier(namedRegistry,`./arcane/${relative}`,`./arcane/${relative}`);
+            const target=runtimeTarget(relative);
+            registerSpecifier(namedRegistry,target,target);
         }
     }
     const imports={};
@@ -2062,8 +2071,7 @@ function removeManagedBlocks(html,blocks){
     return result;
 }
 
-function firstModulePosition(html){
-    const structure=scanHtmlStructure(html);
+function firstModulePosition(html,structure=scanHtmlStructure(html)){
     let first=-1;
     for(const script of structure.scripts){
         const attributes=parseTagAttributes(script.open);
@@ -2434,6 +2442,312 @@ export async function readApplicationTestImportMapContext({
     });
 }
 
+function documentImportMapStructure(html) {
+    const structure = scanHtmlStructure(html);
+    const managed = [];
+    const executableTypes = new Set(
+        [
+            '', 'module', 'application/ecmascript', 'application/javascript',
+            'application/x-ecmascript', 'application/x-javascript',
+            'text/ecmascript', 'text/javascript', 'text/javascript1.0',
+            'text/javascript1.1', 'text/javascript1.2', 'text/javascript1.3',
+            'text/javascript1.4', 'text/javascript1.5', 'text/jscript',
+            'text/livescript', 'text/x-ecmascript', 'text/x-javascript'
+        ]
+    );
+    let firstLoad = firstModulePosition(html, structure);
+    let base = null;
+    for (const element of structure.bases) {
+        const attributes = parseTagAttributes(element.open);
+        if (!attributes.has('href')) continue;
+        base = {
+            ...element,
+            href:structuralAttribute(attributes, 'href', 'base')
+        };
+        break;
+    }
+    for (const script of structure.scripts) {
+        const attributes = parseTagAttributes(script.open);
+        const type = scriptType(attributes);
+        if (type === 'importmap' && attributes.has(MANAGED_IMPORT_MAP_ATTRIBUTE)) {
+            if (!script.closed) fail('Document contains an unterminated SDK import-map script.');
+            managed.push(script);
+        }
+        if (executableTypes.has(type) && (firstLoad < 0 || script.start < firstLoad)) {
+            firstLoad = script.start;
+        }
+    }
+    if (base && firstLoad >= 0 && base.end > firstLoad) {
+        fail('Document base must precede executable scripts and modulepreloads.');
+    }
+    return {
+        structure,
+        managed,
+        firstLoad,
+        base
+    };
+}
+
+function documentRelativeUrl(target, base) {
+    if (target.protocol !== base.protocol || target.host !== base.host) return target.href;
+    const directory = new URL('.', base);
+    const baseSegments = directory.pathname.split('/');
+    baseSegments.pop();
+    const targetSegments = target.pathname.split('/');
+    let shared = 0;
+    while (shared < baseSegments.length && shared < targetSegments.length - 1
+        && baseSegments[shared] === targetSegments[shared]) {
+        shared += 1;
+    }
+    // URL paths retain empty segments; filesystem relative() would collapse them.
+    const relative = [
+        ...new Array(baseSegments.length - shared).fill('..'),
+        ...targetSegments.slice(shared)
+    ].join('/');
+    const pathname = relative.startsWith('./') || relative.startsWith('../')
+        ? relative : `./${relative}`;
+    return `${pathname}${target.search}${target.hash}`;
+}
+
+function documentImports(imports, context, baseHref, relative) {
+    const documentUrl = new URL(encodedUrlPath(relative), context.deployment);
+    // Match URL parser normalization only for resolving the base; preserve authored HTML.
+    const baseAddress = (baseHref ?? '').replace(/[\t\r\n]/gu, '').replace(
+        /^[\u0000-\u0020]+|[\u0000-\u0020]+$/gu,
+        ''
+    );
+    if (!context.explicitDeployment && /^(?:[\\/]|[A-Za-z][A-Za-z0-9+.-]*:)/u.test(baseAddress)) {
+        throw new TypeError('An absolute or root-relative document base requires deploymentUrl.');
+    }
+    if (!context.explicitDeployment) {
+        let depth = relative.split('/').length - 1;
+        const basePath = baseAddress.split(/[?#]/u)[0].replaceAll('\\', '/');
+        for (const part of basePath.split('/')) {
+            const segment = part.replace(/%2e/giu, '.');
+            if (segment === '..') {
+                if (depth === 0) {
+                    throw new TypeError('A document base traversing above documentRoot requires deploymentUrl.');
+                }
+                depth -= 1;
+            } else if (segment !== '.') {
+                depth += 1;
+            }
+        }
+    }
+    const base = baseHref === undefined ? documentUrl : new URL(baseHref, documentUrl);
+    function rebaseUrl(value) {
+        if (value.startsWith('./arcane/')) {
+            return documentRelativeUrl(new URL(value.substring('./arcane/'.length), context.runtime), base);
+        }
+        if (value.startsWith('./node_modules/')) {
+            return documentRelativeUrl(new URL(value, context.deployment), base);
+        }
+        return value;
+    }
+    const rebased = {};
+    for (const [specifier, target] of Object.entries(imports)) {
+        rebased[rebaseUrl(specifier)] = rebaseUrl(target);
+    }
+    return rebased;
+}
+
+function renderDocumentImportMap(html, imports, state) {
+    const {structure, managed, firstLoad, base} = state;
+    const newline = html.includes('\r\n') ? '\r\n' : '\n';
+    const json = JSON.stringify({imports}, null, 2).replaceAll('<', '\\u003c');
+    const block = `<script type="importmap" ${MANAGED_IMPORT_MAP_ATTRIBUTE}>${newline}${json}${newline}</script>`;
+    const firstManaged = managed[0];
+    const replaceInPlace = firstManaged
+        && (!base || firstManaged.start >= base.end)
+        && (firstLoad < 0 || firstManaged.start < firstLoad);
+    const edits = managed.map(
+        function replaceSdkMap(script, index) {
+            return {
+                start:script.start,
+                end:script.end,
+                value:replaceInPlace && index === 0 ? block : ''
+            };
+        }
+    );
+    if (!replaceInPlace) {
+        const candidate = firstLoad >= 0 ? firstLoad
+            : structure.headClose >= 0 ? structure.headClose
+                : structure.bodyClose >= 0 ? structure.bodyClose : html.length;
+        const insertion = Math.max(candidate, base?.end ?? 0);
+        edits.push(
+            {
+                start:insertion,
+                end:insertion,
+                value:block
+            }
+        );
+    }
+    // Exact script ranges are SDK-owned; surrounding whitespace and author maps are not.
+    return applyReferenceEdits(html, edits);
+}
+
+/** Generate SDK maps for explicitly selected documents without imposing an app layout. */
+export async function generateDocumentImportMaps({
+    documentRoot,
+    runtimeRoot,
+    documents,
+    version = SDK_VERSION,
+    deploymentUrl,
+    signal,
+    onEvent
+} = {}) {
+    if (!is.string(documentRoot) || !documentRoot.trim()) {
+        throw new TypeError('generateDocumentImportMaps documentRoot must be a nonempty string.');
+    }
+    if (!is.array(documents) || documents.length === 0) {
+        throw new TypeError('generateDocumentImportMaps documents must be a nonempty array of relative paths.');
+    }
+    throwIfAborted(signal);
+    const root = path.resolve(documentRoot);
+    const runtime = path.resolve(runtimeRoot ?? path.join(root, 'arcane'));
+    const selected = [...new Set(documents.map(
+        function documentPath(value) {
+            return safeRelativePath(value, 'document path');
+        }
+    ))];
+    const deployment = deploymentUrl === undefined
+        ? pathToFileURL(`${root}${path.sep}`) : new URL(deploymentUrl);
+    if (!deployment.pathname.endsWith('/')) {
+        throw new TypeError('deploymentUrl must name a directory URL ending in /.');
+    }
+    const relativeRuntime = path.relative(root, runtime).split(path.sep).join('/');
+    if (path.isAbsolute(path.relative(root, runtime))) {
+        throw new TypeError('documentRoot and runtimeRoot must share a filesystem volume.');
+    }
+    const context = {
+        deployment,
+        runtime:new URL(relativeRuntime ? `${encodedUrlPath(relativeRuntime)}/` : './', deployment),
+        explicitDeployment:deploymentUrl !== undefined
+    };
+    const documentPaths = selected.map(
+        function resolveDocumentPath(relative) {
+            return path.join(root, ...relative.split('/'));
+        }
+    );
+    let eventError = await emit(
+        onEvent,
+        {
+            type:'import-map.documents.started',
+            documentRoot:root,
+            runtimeRoot:runtime,
+            documentPaths
+        }
+    );
+    const documentStates = new Array(selected.length);
+    const pending = selected.entries();
+    async function readDocuments() {
+        for (const [index, relative] of pending) {
+            throwIfAborted(signal);
+            const html = await readFileFromDisk(documentPaths[index], 'utf8');
+            throwIfAborted(signal);
+            documentStates[index] = {
+                path:relative,
+                filePath:documentPaths[index],
+                html,
+                state:documentImportMapStructure(html)
+            };
+        }
+    }
+    const readers = Array.from(
+        {length:Math.min(4, selected.length)},
+        readDocuments
+    );
+    const outcomes = await Promise.allSettled(
+        [
+            listRuntimeFiles(
+                {
+                    runtimeRoot:runtime,
+                    signal
+                }
+            ),
+            ...readers
+        ]
+    );
+    throwIfAborted(signal);
+    const errors = outcomes.filter(
+        function failedRead(outcome) {
+            return outcome.status === 'rejected';
+        }
+    ).map(
+        function readError(outcome) {
+            return outcome.reason;
+        }
+    );
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, 'Document import-map preparation failed.');
+    const built = await buildImportMap(
+        {
+            files:outcomes[0].value,
+            signal,
+            version,
+            encodePaths:true
+        }
+    );
+    const rendered = documentStates.map(
+        function renderSelectedDocument(document) {
+            throwIfAborted(signal);
+            const imports = documentImports(built.imports, context, document.state.base?.href, document.path);
+            return {
+                path:document.path,
+                filePath:document.filePath,
+                imports,
+                html:renderDocumentImportMap(document.html, imports, document.state)
+            };
+        }
+    );
+    const paths = [];
+    for (const document of rendered) {
+        throwIfAborted(signal);
+        await writeFile(document.filePath, document.html, 'utf8');
+        paths.push(document.filePath);
+        const deliveryError = await emit(
+            onEvent,
+            {
+                type:'import-map.write.progress',
+                paths:[...paths]
+            }
+        );
+        eventError ??= deliveryError;
+    }
+    const result = {
+        documentRoot:root,
+        runtimeRoot:runtime,
+        documentPaths,
+        documentCount:documentPaths.length,
+        documents:rendered.map(
+            function documentResult(document) {
+                return {
+                    path:document.path,
+                    filePath:document.filePath,
+                    imports:document.imports
+                };
+            }
+        ),
+        committed:true
+    };
+    const completedError = await emit(
+        onEvent,
+        {
+            type:'import-map.documents.completed',
+            ...result
+        }
+    );
+    eventError ??= completedError;
+    if (eventError) {
+        result.eventDelivery = {
+            status:'degraded',
+            errorCode:'ARCANE_EVENT_DELIVERY_FAILED',
+            message:String(eventError?.message ?? eventError)
+        };
+    }
+    return result;
+}
+
 async function generateImportMapUnlocked({
     workspaceRoot,
     appId,

package/src/index.mjs

@@ -135,6 +135,7 @@ export {
     readSdkBrowserRuntimeFile
 } from './sdk-browser-runtime.mjs';
 export {materializeWorkspaceRuntimeContent} from './workspace-runtime.mjs';
+export {generateDocumentImportMaps} from './import-map.mjs';
 export {
     discoverApps,
     inspectWorkspaceProfile,

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,

package/src/runtime.mjs

@@ -17,7 +17,7 @@ function fail(message,code='ARCANE_RUNTIME_INVALID'){
 function throwIfAborted(signal){
     if(!signal?.aborted)return;
     const error=signal.reason instanceof Error?signal.reason:new Error('Operation cancelled.');
-    error.code=error.code||'ARCANE_CANCELLED';
+    if(error.code===undefined)error.code='ARCANE_CANCELLED';
     throw error;
 }