@serve.zone/platformclient 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/platformclient",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "private": false,
   "description": "a module that makes it really easy to use the serve.zone platform inside your app",
   "main": "dist_ts/index.js",
@@ -9,12 +9,14 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsbuild": "^4.4.3",
     "@git.zone/tsbundle": "^2.13.0",
     "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^4.1.1",
+    "@git.zone/tstest": "6.1.0",
+    "@push.rocks/smartmongo": "9.0.0",
     "@push.rocks/smartserve": "6.2.1",
-    "@types/node": "26.4.1"
+    "@serve.zone/coremail": "1.2.0",
+    "@types/node": "26.5.0"
   },
   "dependencies": {
     "@api.global/typedrequest": "^8.0.4",
@@ -23,7 +25,7 @@
     "@push.rocks/qenv": "^6.1.4",
     "@push.rocks/smartlog": "^3.2.2",
     "@push.rocks/smartntml": "^2.0.9",
-    "@serve.zone/interfaces": "^30.2.0"
+    "@serve.zone/interfaces": "^30.13.0"
   },
   "repository": {
     "type": "git",

package/readme.md

@@ -65,6 +65,12 @@ Service mail credentials come only from workload environment variables. Standard
 
 Managed Web Push uses a separate, credential-scoped TypedSocket connection configured with `WEB_PUSH_TYPED_URL`, `WEB_PUSH_API_CREDENTIAL_ID`, and `WEB_PUSH_API_CREDENTIAL_SECRET`. These values form one atomic workload environment bundle: all three values are required and partial bundles fail closed. `webPushConnector` never accepts or sends caller-provided authentication or resource-owner fields; dcrouter derives the service scope from the injected credential.
 
+Service mail can instead be routed through a cluster-scoped CoreMail instance. The default sender uses `MAIL_COREMAIL_URL`, `MAIL_COREMAIL_BINDING_ID`, `MAIL_COREMAIL_CREDENTIAL_ID`, `MAIL_COREMAIL_CREDENTIAL_VERSION`, and `MAIL_COREMAIL_CREDENTIAL_SECRET`. Additional sender addresses use scoped `MAIL_<TOKEN>_COREMAIL_*` variants under the same address token as the other mail variables, for example `MAIL_TEST_SERVICE_GATED_ONE_COREMAIL_URL`. Cloudly provisions this group for clusters and Onebox for single hosts.
+
+Precedence matches the dcrouter variables: if any scoped `MAIL_<TOKEN>_COREMAIL_*` value is present, that scoped group is used on its own and the unscoped group is not consulted for that address. The group is atomic — a partially configured group fails closed with the exact missing variable names rather than silently falling back to dcrouter. When a CoreMail group resolves for the selected address, `sendMail()`, `sendText()`, `sendHtml()`, `getMailDeliveryStatus()`, and `registerInboundHandler()` use CoreMail; otherwise they use the dcrouter `MAIL_TYPED_URL` path, exactly as before. `MAIL_COREMAIL_URL` must be one canonical `https://.../socket` URL; `http://` and `ws://` are accepted only for loopback hosts, mirroring the rule TypedSocket itself enforces.
+
+Each distinct binding gets its own connector instance, so a service may hold an unscoped group and several scoped groups at once and send from any of them.
+
 SMTP compatibility credentials are still discoverable with `getServiceMailCredentials()` for applications that explicitly implement SMTP themselves. Those compatibility variables are `SMTP_HOST`, `SMTP_PORT`, `SMTP_TLS_MODE`, `SMTP_USERNAME`, and `SMTP_PASSWORD`, plus scoped `MAIL_<TOKEN>_SMTP_*` variants. They are not used by `sendMail()`, `sendText()`, `sendHtml()`, or `registerInboundHandler()`.
 
 ```typescript
@@ -159,7 +165,7 @@ if (status.ready) {
 }
 ```
 
-`getServiceMailStatus().ready` means the typed service-mail path is configured. The status also exposes `transport`, `typedUrl`, `typedCredentialConfigured`, and `smtpReady` so applications can distinguish standard TypedSocket mail from explicit SMTP compatibility configuration. Send helpers return `spoolItemId`, which can be passed to `getMailDeliveryStatus()` to inspect accepted, queued, deferred, delivered, or failed delivery state. Set `replyTo` to one bare mailbox address when replies should go somewhere other than the managed sender. Dcrouter validates that field and renders the authoritative `Reply-To` header; do not supply `Reply-To` through the free-form `headers` object.
+`getServiceMailStatus().ready` means the typed service-mail path is configured. The status also exposes `transport`, `typedUrl`, `typedCredentialConfigured`, `coreMailConfigured`, `coreMailEndpointUrl`, and `smtpReady` so applications can distinguish CoreMail, standard TypedSocket mail, and explicit SMTP compatibility configuration. `transport` is `'coremail'` when a CoreMail group resolves, `'typedsocket'` for the dcrouter path, `'smtp'` when only SMTP compatibility values are present, and `'none'` otherwise. A partially configured CoreMail group reports `ready: false` with the exact missing `MAIL_COREMAIL_*` names in `missing`. Send helpers return `spoolItemId`, which can be passed to `getMailDeliveryStatus()` to inspect accepted, queued, deferred, delivered, or failed delivery state. Set `replyTo` to one bare mailbox address when replies should go somewhere other than the managed sender. Dcrouter validates that field and renders the authoritative `Reply-To` header; do not supply `Reply-To` through the free-form `headers` object.
 
 Specific sender address:
 
@@ -181,7 +187,7 @@ await client.emailConnector.registerInboundHandler(async (message) => {
 });
 ```
 
-`registerInboundHandler()` registers the dedicated mail connection as the typed endpoint for the configured service mail address. dcrouter then delivers inbound messages through `deliverInboundMail`. After reconnect, exact credential-scoped endpoint registration completes before the mail connection becomes ready. A denied or malformed registration prevents readiness.
+`registerInboundHandler()` behaves according to the resolved transport. On the dcrouter path it registers the dedicated mail connection as the typed endpoint for the configured service mail address, and dcrouter then delivers inbound messages through `deliverInboundMail`. When a CoreMail group resolves for that address, CoreMail is pull-based instead: the connector that owns the address's binding runs a bounded polling loop that lists pending deliveries, fetches each MIME body, invokes the handler with the same message shape the dcrouter path produces, and acknowledges the delivery as `processed` only after the handler resolves. A handler that throws, or returns `{ accepted: false }`, leaves the delivery pending for a later tick. The loop starts on first registration, never overlaps ticks, backs off on transport failure, and is stopped by `stop()`. Tune it with `setCoreMailInboundPollOptions({ intervalMs, pageLimit })` before registering; the default is one tick every 5000 ms over 25 deliveries, with a floor of 250 ms. After reconnect, exact credential-scoped endpoint registration completes before the mail connection becomes ready. A denied or malformed registration prevents readiness.
 
 Inbound message normalization for webhook or direct TypedRequest-style delivery:
 
@@ -310,7 +316,28 @@ The exported `TServiceMailSubmissionErrorCode` type contains the supported dcrou
 
 ## CoreMail
 
-`coreMailConnector` is a server-runtime API for standalone CoreMail workload bindings. It is not a browser or cross-origin API. Pass the injected workload authority explicitly; the connector never reads credential material from platform-binding metadata. The endpoint must be one canonical `https://.../socket` URL.
+There are two ways to reach CoreMail, and most applications want the first.
+
+**As the service-mail transport.** Set the `MAIL_COREMAIL_*` group described under [Configuration](#configuration) and keep using `emailConnector`: `sendMail()`, `getServiceMailStatus()`, `getMailDeliveryStatus()`, and `registerInboundHandler()` all route through CoreMail automatically, with the same `IServiceMailSendOptions` input as the dcrouter path. No CoreMail-specific application code is required.
+
+```typescript
+import { SzPlatformClient } from '@serve.zone/platformclient';
+
+const client = new SzPlatformClient();
+await client.init(); // reads MAIL_COREMAIL_* from the workload environment
+
+const sent = await client.emailConnector.sendMail({
+  to: 'recipient@example.com',
+  subject: 'Sent through CoreMail',
+  text: 'Bodies and attachments become uploaded parts automatically.',
+});
+
+const status = await client.emailConnector.getMailDeliveryStatus(sent.spoolItemId!);
+```
+
+Bodies, HTML, and attachments become CoreMail parts with client-computed SHA-256 digests and lengths, uploaded and finalized for you. Contract limits (1 MiB text, 2 MiB HTML, 16 attachments, 10 MiB each, 17 MiB aggregate, 100 recipients) are enforced before anything is sent. `idempotencyKey` is passed through; CoreMail requires one, so a fresh key is generated when the caller omits it, which reproduces the dcrouter semantics of an unkeyed send. CoreMail error codes that `TMailSubmissionErrorCode` also carries surface unchanged on `ServiceMailSubmissionError.code`; codes with no counterpart become a generic `Error` carrying the code.
+
+**As a direct workload API.** `coreMailConnector` is a server-runtime API for standalone CoreMail workload bindings, for applications that manage submissions or inbound deliveries themselves. It is not a browser or cross-origin API. Pass the injected workload authority explicitly; the connector never reads credential material from platform-binding metadata. The endpoint must be one canonical `https://.../socket` URL, or an `http://`/`ws://` loopback URL for local development.
 
 ```typescript
 import { SzPlatformClient } from '@serve.zone/platformclient';
@@ -356,6 +383,10 @@ try {
 
 Outbound delivery is descriptor-first: call `prepareOutboundSubmission()`, upload every declared byte sequence with `uploadOutboundPart()`, then call `finalizeOutboundSubmission()`. Upload and download grants are path-only, same-origin, one-time capabilities. The connector validates the authenticated operation set, grant context, transfer headers, byte length, and SHA-256 digest before completing a transfer. A general platform authorization string is not required when the client is configured only for CoreMail.
 
+Manual polling as shown above is only needed when driving `coreMailConnector` directly. Applications using CoreMail as the service-mail transport should call `emailConnector.registerInboundHandler()` instead and let the connector own the loop.
+
+`configure()` is one-shot per connector instance. When several bindings are configured through the `MAIL_COREMAIL_*` groups, `emailConnector` keeps one connector per binding — reusing `client.coreMailConnector` for the first or matching binding and creating dedicated instances for the rest — and stops the ones it created in `stop()`.
+
 ## Platform Bindings
 
 Platform bindings allow a workload to discover value-free endpoint and capability metadata from its runtime environment. Secret values are injected separately as workload environment variables or explicit connector options.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/platformclient',
-  version: '4.0.0',
+  version: '4.1.0',
   description: 'a module that makes it really easy to use the serve.zone platform inside your app'
 }

package/ts/classes.platformclient.ts

@@ -75,6 +75,7 @@ export class SzPlatformClient {
       return;
     }
 
+    await this.configureCoreMailFromEnv();
     this.platformBindings = this.mergePlatformBindings(
       this.platformBindings,
       await this.discoverPlatformBindings()
@@ -298,6 +299,45 @@ export class SzPlatformClient {
     return error;
   }
 
+  /**
+   * Configures the CoreMail connector from the unscoped MAIL_COREMAIL_* group
+   * when no programmatic `coreMail` option was supplied. Per-address groups
+   * (MAIL_<TOKEN>_COREMAIL_*) are resolved by the email connector at send time;
+   * this only establishes the default binding so init() can authenticate early.
+   * A partially configured group throws rather than starting unconfigured.
+   */
+  private async configureCoreMailFromEnv(): Promise<void> {
+    if (this.coreMailConnector.isConfigured) return;
+    const endpointUrl = await this.getConfiguredEnvVar('MAIL_COREMAIL_URL');
+    const bindingId = await this.getConfiguredEnvVar('MAIL_COREMAIL_BINDING_ID');
+    const credentialId = await this.getConfiguredEnvVar('MAIL_COREMAIL_CREDENTIAL_ID');
+    const credentialVersion = await this.getConfiguredEnvVar('MAIL_COREMAIL_CREDENTIAL_VERSION');
+    const credentialSecret = await this.getConfiguredEnvVar('MAIL_COREMAIL_CREDENTIAL_SECRET');
+    const present = [endpointUrl, bindingId, credentialId, credentialVersion, credentialSecret];
+    if (!present.some(Boolean)) return;
+    const missing = [
+      ...(endpointUrl ? [] : ['MAIL_COREMAIL_URL']),
+      ...(bindingId ? [] : ['MAIL_COREMAIL_BINDING_ID']),
+      ...(credentialId ? [] : ['MAIL_COREMAIL_CREDENTIAL_ID']),
+      ...(credentialVersion ? [] : ['MAIL_COREMAIL_CREDENTIAL_VERSION']),
+      ...(credentialSecret ? [] : ['MAIL_COREMAIL_CREDENTIAL_SECRET']),
+    ];
+    if (missing.length > 0) {
+      throw new Error(`CoreMail is partially configured. Missing: ${missing.join(', ')}`);
+    }
+    const parsedVersion = Number(credentialVersion);
+    if (!Number.isSafeInteger(parsedVersion) || parsedVersion < 1) {
+      throw new Error('MAIL_COREMAIL_CREDENTIAL_VERSION must be a positive integer');
+    }
+    this.coreMailConnector.configure({
+      endpointUrl: endpointUrl!,
+      bindingId: bindingId!,
+      credentialId: credentialId!,
+      credentialVersion: parsedVersion,
+      credentialSecret: credentialSecret!,
+    });
+  }
+
   private async discoverPlatformBindings() {
     const bindings: plugins.servezoneInterfaces.platform.IPlatformBinding[] = [];
     const envBindings = await this.getConfiguredEnvVar('SERVEZONE_PLATFORM_BINDINGS');

package/ts/coremail/classes.coremailconnector.ts

@@ -19,6 +19,29 @@ export interface ISzCoreMailConnectorOptions {
   credentialSecret: string;
 }
 
+/** Default cadence for the pull-based inbound loop. */
+export const szCoreMailInboundPollDefaults = Object.freeze({
+  intervalMs: 5_000,
+  minimumIntervalMs: 250,
+  maximumBackoffMs: 120_000,
+  pageLimit: 25,
+});
+
+export interface ISzCoreMailInboundPollOptions {
+  /** Tick cadence in milliseconds; defaults to 5000, floored at 250. */
+  intervalMs?: number;
+  /** Deliveries requested per tick; defaults to 25. */
+  pageLimit?: number;
+}
+
+/**
+ * Invoked once per pending delivery. Resolving acknowledges the delivery as
+ * `processed`; throwing leaves it pending for a later tick.
+ */
+export type TSzCoreMailInboundHandler = (
+  resultArg: ISzCoreMailInboundFetchResult,
+) => Promise<void> | void;
+
 export interface ISzCoreMailUploadPartOptions {
   submissionId: string;
   part: plugins.servezoneInterfaces.data.ICoreMailContentDescriptor;
@@ -70,11 +93,37 @@ export class SzCoreMailConnector {
   private readonly stopController = new AbortController();
   private readonly activeOperations = new Set<Promise<unknown>>();
   private stopPromise?: Promise<void>;
+  private inboundHandler?: TSzCoreMailInboundHandler;
+  private inboundPollOptions = { intervalMs: 0, pageLimit: 0 };
+  private inboundTimer?: ReturnType<typeof setTimeout>;
+  private inboundTickPromise?: Promise<void>;
+  private inboundConsecutiveFailures = 0;
 
   public get isConfigured(): boolean {
     return Boolean(this.options);
   }
 
+  /**
+   * Value-free identity of the binding this connector is configured for, or
+   * undefined while unconfigured. Deliberately excludes credentialSecret: it
+   * exists so a caller holding several bindings can tell whether this instance
+   * already serves one of them, which never requires the secret.
+   */
+  public get configuredBinding(): Readonly<{
+    endpointUrl: string;
+    bindingId: string;
+    credentialId: string;
+    credentialVersion: number;
+  }> | undefined {
+    if (!this.options) return undefined;
+    return Object.freeze({
+      endpointUrl: this.options.endpointUrl,
+      bindingId: this.options.bindingId,
+      credentialId: this.options.credentialId,
+      credentialVersion: this.options.credentialVersion,
+    });
+  }
+
   public configure(optionsArg: ISzCoreMailConnectorOptions): void {
     if (this.stopped) {
       throw new Error('CoreMail connector has stopped.');
@@ -181,18 +230,144 @@ export class SzCoreMailConnector {
     };
   }
 
+  /**
+   * Starts the bounded pull loop (list -> fetch -> acknowledge). CoreMail never
+   * pushes inbound mail, so the workload polls. One registration owns the loop;
+   * re-registering replaces the handler without starting a second timer.
+   */
+  public startInboundPolling(
+    handlerArg: TSzCoreMailInboundHandler,
+    optionsArg: ISzCoreMailInboundPollOptions = {},
+  ): void {
+    this.requireOptions();
+    if (typeof handlerArg !== 'function') {
+      throw new Error('CoreMail inbound handler must be a function.');
+    }
+    const requestedInterval = optionsArg.intervalMs ?? szCoreMailInboundPollDefaults.intervalMs;
+    if (!Number.isSafeInteger(requestedInterval) || requestedInterval < szCoreMailInboundPollDefaults.minimumIntervalMs) {
+      throw new Error(
+        `CoreMail inbound intervalMs must be an integer of at least ${szCoreMailInboundPollDefaults.minimumIntervalMs}.`,
+      );
+    }
+    const requestedPageLimit = optionsArg.pageLimit ?? szCoreMailInboundPollDefaults.pageLimit;
+    if (
+      !Number.isSafeInteger(requestedPageLimit)
+      || requestedPageLimit < 1
+      || requestedPageLimit > plugins.servezoneInterfaces.data.coreMailLimits.inboundPageSize
+    ) {
+      throw new Error(
+        `CoreMail inbound pageLimit must be an integer between 1 and ${plugins.servezoneInterfaces.data.coreMailLimits.inboundPageSize}.`,
+      );
+    }
+    this.inboundHandler = handlerArg;
+    this.inboundPollOptions = { intervalMs: requestedInterval, pageLimit: requestedPageLimit };
+    this.inboundConsecutiveFailures = 0;
+    if (!this.inboundTimer && !this.inboundTickPromise) {
+      this.scheduleInboundTick(0);
+    }
+  }
+
+  /** Stops the pull loop and awaits the tick in flight. */
+  public async stopInboundPolling(): Promise<void> {
+    this.inboundHandler = undefined;
+    if (this.inboundTimer) {
+      clearTimeout(this.inboundTimer);
+      this.inboundTimer = undefined;
+    }
+    await this.inboundTickPromise?.catch(() => undefined);
+  }
+
   public stop(): Promise<void> {
     this.stopPromise ??= this.stopInner();
     return this.stopPromise;
   }
 
+  private scheduleInboundTick(delayMsArg: number): void {
+    if (this.stopped || !this.inboundHandler) return;
+    this.inboundTimer = setTimeout(() => {
+      this.inboundTimer = undefined;
+      // One tick at a time: the next tick is only scheduled once this one settles.
+      const tick = this.runInboundTick().catch(() => undefined).finally(() => {
+        if (this.inboundTickPromise === tick) this.inboundTickPromise = undefined;
+        this.scheduleInboundTick(this.nextInboundDelayMs());
+      });
+      this.inboundTickPromise = tick;
+    }, delayMsArg);
+    this.inboundTimer.unref?.();
+  }
+
+  /** Exponential backoff on transport failure, capped; reset by a clean tick. */
+  private nextInboundDelayMs(): number {
+    if (this.inboundConsecutiveFailures === 0) return this.inboundPollOptions.intervalMs;
+    const backoff = this.inboundPollOptions.intervalMs * 2 ** Math.min(this.inboundConsecutiveFailures, 16);
+    return Math.min(backoff, szCoreMailInboundPollDefaults.maximumBackoffMs);
+  }
+
+  private async runInboundTick(): Promise<void> {
+    const handler = this.inboundHandler;
+    if (this.stopped || !handler) return;
+    try {
+      const page = await this.listInboundDeliveries({ limit: this.inboundPollOptions.pageLimit });
+      this.inboundConsecutiveFailures = 0;
+      for (const delivery of page.deliveries) {
+        if (this.stopped || this.inboundHandler !== handler) return;
+        if (delivery.state === 'acknowledged') continue;
+        let fetched: ISzCoreMailInboundFetchResult;
+        try {
+          fetched = await this.fetchInboundDelivery(delivery);
+        } catch (error) {
+          // Leave the delivery pending; a later tick retries the fetch.
+          this.inboundConsecutiveFailures++;
+          return;
+        }
+        try {
+          await handler(fetched);
+        } catch {
+          // A throwing handler must not acknowledge. The delivery stays pending.
+          continue;
+        }
+        await this.acknowledgeInboundDelivery({
+          deliveryId: fetched.delivery.deliveryId,
+          outcome: 'processed',
+        });
+      }
+    } catch (error) {
+      this.inboundConsecutiveFailures++;
+    }
+  }
+
+  /**
+   * Mirrors the loopback rule TypedSocket enforces before it downgrades a
+   * connection to an insecure WebSocket. See `isLoopbackHostname` in
+   * node_modules/@api.global/typedsocket/dist_ts/classes.typedsocket.js:257-267,
+   * applied at classes.typedsocket.js:986-988
+   * ('TypedSocket insecure WebSocket transport is restricted to loopback hosts.').
+   * Keeping the predicates identical means this connector never accepts an
+   * endpoint that TypedSocket would refuse one layer down.
+   */
+  private isLoopbackHostname(hostnameArg: string): boolean {
+    const hostname = hostnameArg.toLowerCase().replace(/^\[(.*)\]$/, '$1');
+    if (hostname === 'localhost' || hostname.endsWith('.localhost') || hostname === '::1') {
+      return true;
+    }
+    const octets = hostname.split('.');
+    return octets.length === 4
+      && octets.every((octetArg) => /^\d{1,3}$/.test(octetArg) && Number(octetArg) <= 255)
+      && Number(octets[0]) === 127;
+  }
+
   private normalizeOptions(
     optionsArg: ISzCoreMailConnectorOptions,
   ): ISzCoreMailConnectorOptions {
     const endpointUrl = new URL(optionsArg.endpointUrl);
+    // TypedSocket maps http:/ws: onto ws: and https:/wss: onto wss:
+    // (classes.typedsocket.js:974-985), so the same four schemes are accepted
+    // here; the insecure pair stays restricted to loopback authorities.
+    const isSecureProtocol = endpointUrl.protocol === 'https:' || endpointUrl.protocol === 'wss:';
+    const isInsecureProtocol = endpointUrl.protocol === 'http:' || endpointUrl.protocol === 'ws:';
     if (
       optionsArg.endpointUrl.trim() !== optionsArg.endpointUrl
-      || endpointUrl.protocol !== 'https:'
+      || (!isSecureProtocol && !isInsecureProtocol)
       || endpointUrl.username
       || endpointUrl.password
       || endpointUrl.search
@@ -202,6 +377,11 @@ export class SzCoreMailConnector {
     ) {
       throw new Error('CoreMail endpointUrl must be one canonical HTTPS /socket URL.');
     }
+    if (isInsecureProtocol && !this.isLoopbackHostname(endpointUrl.hostname)) {
+      throw new Error(
+        'CoreMail insecure endpointUrl is restricted to loopback hosts.',
+      );
+    }
     for (const [name, value] of [
       ['bindingId', optionsArg.bindingId],
       ['credentialId', optionsArg.credentialId],
@@ -397,8 +577,13 @@ export class SzCoreMailConnector {
       throw new Error('CoreMail returned an invalid transfer origin.');
     }
     const url = new URL(valueArg);
+    // The transfer origin must follow the same scheme rule as endpointUrl: a
+    // loopback CoreMail reached over http: also issues http: transfer grants,
+    // so restricting this to https: would make loopback deployments unusable.
+    const isSecureProtocol = url.protocol === 'https:';
+    const isInsecureProtocol = url.protocol === 'http:';
     if (
-      url.protocol !== 'https:'
+      (!isSecureProtocol && !isInsecureProtocol)
       || url.username
       || url.password
       || url.search
@@ -408,6 +593,9 @@ export class SzCoreMailConnector {
     ) {
       throw new Error('CoreMail returned a noncanonical transfer origin.');
     }
+    if (isInsecureProtocol && !this.isLoopbackHostname(url.hostname)) {
+      throw new Error('CoreMail returned an insecure non-loopback transfer origin.');
+    }
     return valueArg;
   }
 
@@ -689,7 +877,7 @@ export class SzCoreMailConnector {
         response.status !== 200
         || response.headers.get('content-type') !== grantArg.contentType
         || response.headers.get('content-length') !== String(grantArg.lengthBytes)
-        || response.headers.get('cache-control') !== 'no-store'
+        || !this.forbidsStoringResponse(response.headers.get('cache-control'))
         || response.headers.get('x-content-type-options') !== 'nosniff'
         || !responseBody
       ) {
@@ -794,6 +982,22 @@ export class SzCoreMailConnector {
     return url.toString();
   }
 
+  /**
+   * A one-time transfer payload must never be cached, but the exact spelling of
+   * Cache-Control is not ours to dictate: CoreMail's transfer service sets
+   * 'no-store' and typedserver's `noCache: true` then expands it to the full
+   * directive set ('no-store, no-cache, must-revalidate, proxy-revalidate,
+   * max-age=0'). Requiring byte equality with 'no-store' rejected every real
+   * CoreMail response, so assert the directive is present instead.
+   */
+  private forbidsStoringResponse(cacheControlArg: string | null): boolean {
+    if (!cacheControlArg) return false;
+    return cacheControlArg
+      .split(',')
+      .map((directiveArg) => directiveArg.trim().toLowerCase())
+      .includes('no-store');
+  }
+
   private async createSha256(
     bytesArg: Uint8Array,
   ): Promise<plugins.servezoneInterfaces.data.TCoreMailSha256> {
@@ -906,6 +1110,14 @@ export class SzCoreMailConnector {
   private async stopInner(): Promise<void> {
     this.stopped = true;
     this.generation++;
+    this.inboundHandler = undefined;
+    if (this.inboundTimer) {
+      clearTimeout(this.inboundTimer);
+      this.inboundTimer = undefined;
+    }
+    const inboundTick = this.inboundTickPromise;
+    this.inboundTickPromise = undefined;
+    await inboundTick?.catch(() => undefined);
     this.stopController.abort(this.createAbortError());
     const connection = this.connection;
     const pendingConnection = this.pendingConnection;