@serve.zone/dcrouter 34.6.0 → 34.7.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "34.6.0",
+  "version": "34.7.1",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "bin": {
@@ -15,6 +15,8 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
+    "@api.global/typedrequest-coremail-client": "npm:@api.global/typedrequest@9.1.0",
+    "@api.global/typedsocket-coremail-client": "npm:@api.global/typedsocket@9.0.2",
     "@git.zone/tsdeno": "^1.15.0",
     "@git.zone/tsdocker": "^3.14.0",
     "@git.zone/tsrepo": "^2.1.0",
@@ -29,8 +31,10 @@
   },
   "dependencies": {
     "@api.global/typedrequest": "8.0.4",
+    "@api.global/typedrequest-coremail": "npm:@api.global/typedrequest@9.2.2",
     "@api.global/typedrequest-interfaces": "7.1.0",
     "@api.global/typedserver": "13.0.2",
+    "@api.global/typedserver-coremail": "npm:@api.global/typedserver@16.0.2",
     "@api.global/typedsocket": "8.5.0",
     "@apiclient.xyz/cloudflare": "^8.0.2",
     "@aws-sdk/client-s3": "^3.1111.0",

package/readme.md

@@ -161,7 +161,7 @@ Bootstrap behavior:
 | `baseDir` | Root directory for dcrouter runtime data. Defaults to `~/.serve.zone/dcrouter`. |
 | `coreTrafficConfig` | Main CoreTraffic route configuration for HTTP/HTTPS/TCP/SNI traffic. `smartProxyConfig` remains accepted as a legacy alias. |
 | `emailConfig` | UnifiedEmailServer configuration: hostname, ports, domains, and mail routes. |
-| `emailOutboundMode` | Outbound SMTP mode. Defaults to `remoteIngress`; explicit `direct` mode lets unmanaged/static senders dial from the hub. |
+| `emailOutboundMode` | Outbound SMTP mode; explicit `direct` mode lets unmanaged/static senders dial from the hub. With the database enabled it seeds the stored email settings on first start only; after that the stored settings are authoritative, they default to `remoteIngress`, and the mode changes through the email settings API or Ops UI. Without the database it is read directly on every delivery and has no default: while it is unset, outbound mail defers. |
 | `emailPortConfig` | External-to-internal email port mapping and received-email storage path. |
 | `tls` | Legacy/static TLS and ACME contact settings used to seed certificate config. |
 | `dnsNsDomains` | Nameserver hostnames used for generated NS records and DoH routes. A zone becomes authoritative by having its public NS records observed naming one of these. |
@@ -1172,11 +1172,27 @@ order, so the producer canonicalises the string before sending it.
 
 | Setting | Owner | Canonical form |
 | --- | --- | --- |
-| `gateway.endpointUrl` (in CoreMail's desired state) | producer | `wss://<dcrouter-ops-host>/` — **with** the trailing slash |
+| `gateway.endpointUrl` (in CoreMail's desired state) | producer | `wss://<gateway-host>/` — **with** the trailing slash |
 | `transferOrigin` (in the peer above) | producer | `https://<coremail-host>` — origin only, **no** trailing slash |
 
-`endpointUrl` points at dcrouter's ops server port (`opsServerPort`, default
-`3000`) — the same TypedSocket surface platformclient's `MAIL_TYPED_URL` reaches.
+Which host `endpointUrl` names depends on CoreMail's TypedSocket major, because
+the TypedSocket handshake refuses a peer of another wire:
+
+- CoreMail up to 32 (TypedSocket 8) dials dcrouter's ops server port
+  (`opsServerPort`, default `3000`) — the same TypedSocket surface
+  platformclient's `MAIL_TYPED_URL` reaches.
+- CoreMail 33 and later (TypedSocket 9; wire 9 is shared by TypedSocket 9 and 10)
+  dials the CoreMail gateway listener, `IDcRouterOptions.coreMailGatewayServer`.
+  It is disabled when the option is absent. The option has `port` and a nonempty
+  exact `hostnames` list; it always binds `127.0.0.1` and serves its socket at `/`,
+  so the operator routes one hub hostname to that port and lists the same hostname
+  in `hostnames` (other hosts, other paths, HTTP and browser Origins are answered
+  `404`). In OCI mode the option goes into the `DCROUTER_CONFIG_PATH` JSON. The
+  listener serves the three gateway calls and nothing else: no Ops, admin or
+  workload mail methods. It authenticates with the CoreMail credential behind the
+  same per-credential-id attempt limit as the ops surface and adds no source-address
+  check. The ops server keeps serving CoreMail on TypedSocket 8 alongside it.
+
 `transferOrigin` is CoreMail's own HTTPS origin, from which dcrouter fetches and
 to which it uploads message bytes; dcrouter returns it verbatim during
 authentication and CoreMail refuses the session unless it matches its own desired

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '34.6.0',
+  version: '34.7.1',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }

package/ts/classes.dcrouter.ts

@@ -25,6 +25,7 @@ import { createApplicationMigrationRunner } from '../ts_migrations/index.js';
 
 import { OpsServer } from './opsserver/index.js';
 import type { IWorkloadMailServerOptions } from './opsserver/classes.workload-mail-server.js';
+import type { ICoreMailGatewayServerOptions } from './opsserver/classes.coremail-gateway-server.js';
 import { MetricsManager, OpsEventManager } from './monitoring/index.js';
 import { RadiusServer, type IRadiusServerConfig } from './radius/index.js';
 import { RemoteIngressHubLifecycle, RemoteIngressManager, TunnelManager, buildEdgeOnlyDerivationRoutes } from './remoteingress/index.js';
@@ -115,7 +116,13 @@ export interface IDcRouterOptions {
   /** SmartBucket configuration for durable SmartMTA queue and attachment blobs. */
   emailBlobStorage?: ISmartMtaBlobStorageConfig;
 
-  /** Outbound SMTP connection mode. Defaults to direct unless DB settings override it. */
+  /**
+   * Outbound SMTP connection mode. With the database enabled it seeds the
+   * stored email settings on first start only; after that the stored settings
+   * are authoritative, and they default to `remoteIngress`. Without the
+   * database it is read directly on every delivery and has no default: while
+   * it is unset, outbound mail defers.
+   */
   emailOutboundMode?: TEmailOutboundMode;
 
   /**
@@ -230,6 +237,13 @@ export interface IDcRouterOptions {
   /** Disabled unless explicitly configured; loopback-only, separately routed two-operation mail API. */
   workloadMailServer?: IWorkloadMailServerOptions;
 
+  /**
+   * Disabled unless explicitly configured; loopback-only listener that serves the CoreMail gateway,
+   * and nothing else, to CoreMail on TypedSocket 9 or 10, behind one hub hostname route (Linus
+   * ruling 70, L2). The Ops server keeps serving the gateway on TypedSocket 8.
+   */
+  coreMailGatewayServer?: ICoreMailGatewayServerOptions;
+
   /** Optional OpsServer account authentication settings. */
   adminAuth?: {
     /** Optional idp.global password-authentication URL override. Defaults to the SDK's hosted https://app.idp.global endpoint. Can also be set through DCROUTER_IDP_GLOBAL_URL. */
@@ -479,9 +493,10 @@ export class DcRouter {
       store: new CoreMailGatewayStore(),
       runtime: createCoreMailGatewayRuntime(this),
     });
-    // CoreMail connects as a TypedSocket client to the ops surface, which
-    // serves this router through the OpsServer's own chain. Registering here
-    // keeps the manager independent of OpsServer construction.
+    // CoreMail on TypedSocket 8 connects as a TypedSocket client to the ops
+    // surface, which serves this router through the OpsServer's own chain.
+    // Registering here keeps the manager independent of OpsServer construction.
+    // CoreMail on wire 9 connects to the `coreMailGatewayServer` listener instead.
     this.typedrouter.addTypedRouter(this.coreMailGatewayManager.typedrouter);
     this.smtpAccountManager = new SmtpAccountManager(this);
     this.acceptedEmailSpool = new AcceptedEmailSpool(this);

package/ts/email/classes.coremail-gateway.manager.ts

@@ -67,6 +67,19 @@ interface ICoreMailPeerLike {
   context: { state: Record<string, unknown> };
 }
 
+/**
+ * A CoreMail connection on one of the sockets the gateway is served on: the Ops
+ * server's TypedSocket 8 or the CoreMail gateway listener's wire 9. A request to
+ * CoreMail goes out on the socket the connection belongs to.
+ */
+export interface ICoreMailGatewayConnection {
+  peer: ICoreMailPeerLike;
+  fire<T extends plugins.typedrequestInterfaces.ITypedRequest>(
+    methodArg: T['method'],
+    requestArg: T['request'],
+  ): Promise<T['response']>;
+}
+
 interface ICoreMailQueueItemLike {
   id: string;
   status: 'pending' | 'processing' | 'delivered' | 'failed' | 'deferred';
@@ -87,11 +100,8 @@ export interface ICoreMailGatewayRuntime {
     idempotencyKeyArg: string,
   ): Promise<string>;
   getQueueItem(queueItemIdArg: string): ICoreMailQueueItemLike | undefined;
-  findConnection(tagArg: string): Promise<{ peer: ICoreMailPeerLike } | undefined>;
-  createRequest<T extends plugins.typedrequestInterfaces.ITypedRequest>(
-    methodArg: T['method'],
-    connectionArg: unknown,
-  ): { fire(requestArg: T['request']): Promise<T['response']> };
+  /** The connection with this routing tag on any socket the gateway is served on. */
+  findConnection(tagArg: string): Promise<ICoreMailGatewayConnection | undefined>;
 }
 
 export interface ICoreMailGatewayManagerOptions {
@@ -121,14 +131,55 @@ export class CoreMailInboundRefusedError extends Error {
   }
 }
 
+/**
+ * The contract error a gateway request is refused with. It is definitive
+ * unless it names when to retry: CoreMail takes a non-retryable
+ * `AUTHENTICATION_FAILED` as the verdict on its credential and stops
+ * connecting with it.
+ */
 const contractError = (
   codeArg: TErrorCode,
-  retryableArg = false,
+  retryAfterMsArg?: number,
 ): plugins.typedrequest.TypedResponseError =>
-  new plugins.typedrequest.TypedResponseError('CoreMail gateway request rejected.', {
-    code: codeArg,
-    retryable: retryableArg,
-  } satisfies plugins.servezoneInterfaces.data.ICoreMailErrorData);
+  new plugins.typedrequest.TypedResponseError(
+    'CoreMail gateway request rejected.',
+    (retryAfterMsArg === undefined
+      ? { code: codeArg, retryable: false }
+      : { code: codeArg, retryable: true, retryAfterMs: retryAfterMsArg }
+    ) satisfies plugins.servezoneInterfaces.data.ICoreMailErrorData,
+  );
+
+/**
+ * Whether a replayed envelope is the one the stored handoff was prepared with.
+ * Compares values, never encodings: the stored envelope is whatever the
+ * document store returns, and its key order is not part of the data. The
+ * recipient order is, as it is in the submission digest.
+ */
+const isSameCoreMailEnvelope = (
+  storedArg: plugins.servezoneInterfaces.data.ICoreMailEnvelope,
+  replayedArg: plugins.servezoneInterfaces.data.ICoreMailEnvelope,
+): boolean =>
+  storedArg.mailFrom === replayedArg.mailFrom
+  && storedArg.rcptTo.length === replayedArg.rcptTo.length
+  && storedArg.rcptTo.every((recipientArg, indexArg) => recipientArg === replayedArg.rcptTo[indexArg]);
+
+/**
+ * Answers a wire-9 request with the handler's own contract refusal: TypedRequest 9
+ * answers an error of another class, TypedRequest 8's `TypedResponseError`
+ * included, as an internal error without its `errorData`.
+ */
+const onCoreMailGatewayWire = <TRequest, TResponse>(
+  handlerArg: (requestArg: TRequest, toolsArg: unknown) => Promise<TResponse>,
+) => async (requestArg: TRequest, toolsArg?: unknown): Promise<TResponse> => {
+  try {
+    return await handlerArg(requestArg, toolsArg);
+  } catch (error: unknown) {
+    if (error instanceof plugins.typedrequest.TypedResponseError) {
+      throw new plugins.typedrequestCoreMail.TypedResponseError(error.errorText, error.errorData);
+    }
+    throw error;
+  }
+};
 
 const toTimestamp = (valueArg: Date | number | undefined): number | undefined => {
   if (valueArg === undefined) return undefined;
@@ -146,6 +197,7 @@ const toTimestamp = (valueArg: Date | number | undefined): number | undefined =>
  * `…CompleteInboundHandoff` and `…CompleteOutboundHandoff` back on the peer.
  */
 export class CoreMailGatewayManager {
+  /** The gateway's handlers on TypedSocket 8, which the Ops server serves. */
   public typedrouter = new plugins.typedrequest.TypedRouter();
 
   private readonly store: ICoreMailGatewayStore;
@@ -184,7 +236,7 @@ export class CoreMailGatewayManager {
     this.verifyCredential = optionsArg.verifyCredential
       ?? (async (hashArg, secretArg) => await plugins.argon2.verify(hashArg, secretArg));
     this.enqueueRetryDelaysMs = optionsArg.enqueueRetryDelaysMs ?? [1_000, 5_000, 15_000];
-    this.registerHandlers();
+    this.registerGatewayHandlers(this.typedrouter);
   }
 
   // -------------------------------------------------------- peer provisioning
@@ -274,31 +326,52 @@ export class CoreMailGatewayManager {
 
   // ---------------------------------------------------------------- handlers
 
-  private registerHandlers(): void {
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<TReq_Authenticate>(
+  /**
+   * Registers the gateway's three handlers on the router it is handed (Linus
+   * rulings 39, 3f, and 70, L2): this manager's `typedrouter` (TypedSocket 8,
+   * served by the Ops server) and the CoreMail gateway listener's router (wire 9,
+   * `CoreMailGatewayServer`). Both run the same handler bodies, and the session
+   * an authentication sets lives on the peer of the socket it arrived on.
+   */
+  public registerGatewayHandlers(
+    routerArg: plugins.typedrequest.TypedRouter | plugins.typedrequestCoreMail.TypedRouter,
+  ): void {
+    const authenticate = async (dataArg: TReq_Authenticate['request'], toolsArg: unknown) =>
+      await this.authenticate(this.requirePeer(toolsArg), dataArg);
+    const prepareOutboundHandoff = async (
+      dataArg: TReq_PrepareOutboundHandoff['request'],
+      toolsArg: unknown,
+    ) => await this.prepareOutboundHandoff(this.requireSession(this.requirePeer(toolsArg)), dataArg);
+    const getOutboundStatus = async (dataArg: TReq_GetOutboundStatus['request'], toolsArg: unknown) =>
+      await this.getOutboundStatus(this.requireSession(this.requirePeer(toolsArg)), dataArg);
+
+    if (routerArg instanceof plugins.typedrequestCoreMail.TypedRouter) {
+      routerArg.addTypedHandler(new plugins.typedrequestCoreMail.TypedHandler<TReq_Authenticate>(
         'coreMailGatewayAuthenticate',
-        async (dataArg, toolsArg) => await this.authenticate(this.requirePeer(toolsArg), dataArg),
-      ),
-    );
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<TReq_PrepareOutboundHandoff>(
+        onCoreMailGatewayWire(authenticate),
+      ));
+      routerArg.addTypedHandler(new plugins.typedrequestCoreMail.TypedHandler<TReq_PrepareOutboundHandoff>(
         'coreMailGatewayPrepareOutboundHandoff',
-        async (dataArg, toolsArg) => await this.prepareOutboundHandoff(
-          this.requireSession(this.requirePeer(toolsArg)),
-          dataArg,
-        ),
-      ),
-    );
-    this.typedrouter.addTypedHandler(
-      new plugins.typedrequest.TypedHandler<TReq_GetOutboundStatus>(
+        onCoreMailGatewayWire(prepareOutboundHandoff),
+      ));
+      routerArg.addTypedHandler(new plugins.typedrequestCoreMail.TypedHandler<TReq_GetOutboundStatus>(
         'coreMailGatewayGetOutboundStatus',
-        async (dataArg, toolsArg) => await this.getOutboundStatus(
-          this.requireSession(this.requirePeer(toolsArg)),
-          dataArg,
-        ),
-      ),
-    );
+        onCoreMailGatewayWire(getOutboundStatus),
+      ));
+      return;
+    }
+    routerArg.addTypedHandler(new plugins.typedrequest.TypedHandler<TReq_Authenticate>(
+      'coreMailGatewayAuthenticate',
+      authenticate,
+    ));
+    routerArg.addTypedHandler(new plugins.typedrequest.TypedHandler<TReq_PrepareOutboundHandoff>(
+      'coreMailGatewayPrepareOutboundHandoff',
+      prepareOutboundHandoff,
+    ));
+    routerArg.addTypedHandler(new plugins.typedrequest.TypedHandler<TReq_GetOutboundStatus>(
+      'coreMailGatewayGetOutboundStatus',
+      getOutboundStatus,
+    ));
   }
 
   private requirePeer(toolsArg: unknown): ICoreMailPeerLike {
@@ -320,8 +393,9 @@ export class CoreMailGatewayManager {
 
   /**
    * Every gateway method other than the handshake requires an authenticated
-   * CoreMail session on this exact connection. The ops TypedSocket surface is
-   * shared with other client types, so presence on the socket proves nothing.
+   * CoreMail session on this exact connection. The Ops TypedSocket surface is
+   * shared with other client types and the gateway listener takes any peer that
+   * reaches it, so presence on a socket proves nothing.
    */
   private requireSession(peerArg: ICoreMailPeerLike): ICoreMailGatewaySession {
     const session = peerArg.data.get(coreMailGatewaySessionKey) as
@@ -353,7 +427,12 @@ export class CoreMailGatewayManager {
       bucket.refilledAt += intervals * 1_000;
     }
     if (bucket.tokens < 1) {
-      throw contractError('AUTHENTICATION_FAILED');
+      // A spent budget says nothing about the credential, so the refusal is
+      // retryable once the next token refills.
+      throw contractError(
+        'AUTHENTICATION_FAILED',
+        Math.max(1, Math.ceil(bucket.refilledAt + 1_000 - now)),
+      );
     }
     bucket.tokens -= 1;
   }
@@ -515,7 +594,7 @@ export class CoreMailGatewayManager {
         || existing.submissionDigest !== submissionDigest
         || existing.rawMimeSha256 !== message.rawMime.sha256
         || existing.rawMimeLengthBytes !== message.rawMime.lengthBytes
-        || JSON.stringify(existing.envelope) !== JSON.stringify(message.envelope)
+        || !isSameCoreMailEnvelope(existing.envelope, message.envelope)
       ) {
         throw contractError('IDEMPOTENCY_CONFLICT');
       }
@@ -929,7 +1008,7 @@ export class CoreMailGatewayManager {
     if (!connection || !session || session.coreMailServiceId !== coreMailServiceIdArg) {
       throw new Error('No authenticated CoreMail gateway peer is connected');
     }
-    return await this.runtime.createRequest<T>(methodArg, connection).fire(requestArg);
+    return await connection.fire<T>(methodArg, requestArg);
   }
 
   private async isPeerConnected(coreMailServiceIdArg: string): Promise<boolean> {

package/ts/email/coremail-gateway-runtime.ts

@@ -1,13 +1,26 @@
 import * as plugins from '../plugins.js';
 import type { DcRouter } from '../classes.dcrouter.js';
-import type { ICoreMailGatewayRuntime } from './classes.coremail-gateway.manager.js';
+import type {
+  ICoreMailGatewayConnection,
+  ICoreMailGatewayRuntime,
+} from './classes.coremail-gateway.manager.js';
+
+/** A CoreMail connection on a TypedSocket 8 server, with requests bound to that socket. */
+export const toCoreMailGatewayConnection = (
+  typedsocketArg: plugins.typedsocket.TypedSocket,
+  connectionArg: plugins.typedsocket.ISmartServeConnectionWrapper,
+): ICoreMailGatewayConnection => ({
+  peer: connectionArg.peer,
+  fire: async (methodArg, requestArg) =>
+    await typedsocketArg.createTypedRequest(methodArg, connectionArg).fire(requestArg),
+});
 
 /**
  * Binds the CoreMail gateway manager to the live dcrouter runtime.
  *
  * Everything the manager needs from dcrouter passes through this adapter, so
  * the manager stays testable against a stub and dcrouter keeps ownership of
- * the smartmta server and the ops TypedSocket.
+ * the smartmta server and the sockets the gateway is served on.
  */
 export const createCoreMailGatewayRuntime = (
   dcRouterArg: DcRouter,
@@ -28,20 +41,14 @@ export const createCoreMailGatewayRuntime = (
 
   getQueueItem: (queueItemIdArg) => dcRouterArg.emailServer?.getQueueItem(queueItemIdArg),
 
+  // The CoreMail gateway listener first: a CoreMail on TypedSocket 9 or 10 can
+  // reach only that one. A CoreMail on TypedSocket 8 reaches only the Ops server.
   findConnection: async (tagArg) => {
+    const listenerConnection = await dcRouterArg.opsServer?.coreMailGatewayServer?.findConnection(tagArg);
+    if (listenerConnection) return listenerConnection;
     const typedsocket = dcRouterArg.opsServer?.server?.typedserver?.typedsocket;
     if (!typedsocket) return undefined;
-    return await typedsocket.findTargetConnectionByTag(tagArg as never) as never;
-  },
-
-  createRequest: (methodArg, connectionArg) => {
-    const typedsocket = dcRouterArg.opsServer?.server?.typedserver?.typedsocket;
-    if (!typedsocket) {
-      throw new Error('OpsServer TypedSocket is not available for CoreMail gateway requests');
-    }
-    return typedsocket.createTypedRequest(
-      methodArg as never,
-      connectionArg as plugins.typedsocket.ISmartServeConnectionWrapper,
-    ) as never;
+    const connection = await typedsocket.findTargetConnectionByTag(tagArg);
+    return connection ? toCoreMailGatewayConnection(typedsocket, connection) : undefined;
   },
 });

package/ts/opsserver/classes.coremail-gateway-server.ts

@@ -0,0 +1,104 @@
+import * as plugins from '../plugins.js';
+import type {
+  CoreMailGatewayManager,
+  ICoreMailGatewayConnection,
+} from '../email/classes.coremail-gateway.manager.js';
+
+/**
+ * The one path the listener serves. The URL CoreMail dials, Cloudly's
+ * `coreMailGatewayEndpointUrl`, is a bare wss origin, so the socket sits at the
+ * root of the hub hostname that routes to this listener.
+ */
+export const COREMAIL_GATEWAY_SOCKET_PATH = '/';
+
+/** Opt-in loopback listener (Linus ruling 70, L2). Its hub hostname route is the operator's. */
+export interface ICoreMailGatewayServerOptions {
+  /** Port on 127.0.0.1; 0 asks the OS for one. */
+  port: number;
+  /** Hostnames of the hub route that forwards to this port; any other Host is answered 404. */
+  hostnames: readonly string[];
+}
+
+type TCoreMailGatewayTypedServer = plugins.typedserverCoreMail.TypedServer;
+
+/**
+ * The CoreMail gateway on wire 9 (TypedSocket 9 and 10), separate from the Ops
+ * server, which keeps serving it on TypedSocket 8. It serves the gateway's
+ * three handlers and nothing else: no Ops router, admin or workload mail, no
+ * HTTP RPC, no client tags and no built-in methods. Authentication is the
+ * gateway's own, the CoreMail credential behind the per-credential-id attempt
+ * limiter; the listener adds no source check.
+ */
+export class CoreMailGatewayServer {
+  private server?: TCoreMailGatewayTypedServer;
+  /** Peers are looked up only between a completed start and the beginning of stop. */
+  private serving = false;
+
+  constructor(
+    private readonly options: ICoreMailGatewayServerOptions,
+    private readonly manager: Pick<CoreMailGatewayManager, 'registerGatewayHandlers'>,
+  ) {}
+
+  public get listeningPort(): number | null {
+    return this.server?.listeningPort ?? null;
+  }
+
+  public async start(): Promise<void> {
+    if (this.server) throw new Error('CoreMail gateway server already started');
+    if (!Number.isInteger(this.options.port) || this.options.port < 0 || this.options.port > 65535) {
+      throw new Error('CoreMail gateway port must be an integer from 0 to 65535');
+    }
+    const router = new plugins.typedrequestCoreMail.TypedRouter();
+    this.manager.registerGatewayHandlers(router);
+    const server = new plugins.typedserverCoreMail.TypedServer({
+      port: this.options.port,
+      listenHostname: '127.0.0.1',
+      cors: false,
+      surfaces: [{
+        name: 'coremail-gateway',
+        match: { hostnames: this.options.hostnames, pathPrefixes: [COREMAIL_GATEWAY_SOCKET_PATH] },
+        websocketTypedRouter: router,
+        typedRequestPath: false,
+        includeBuiltinTypedHandlers: false,
+        healthzEndpoint: false,
+        cors: false,
+        requestAdmission: () => new Response('Not Found', { status: 404 }),
+        websocketAdmission: (contextArg) => (
+          contextArg.url.pathname === COREMAIL_GATEWAY_SOCKET_PATH
+          && !contextArg.url.search
+          && !contextArg.request.headers.has('origin')
+        ) ? true : new Response('Not Found', { status: 404 }),
+      }],
+    });
+    this.server = server;
+    try {
+      await server.start();
+    } catch (error) {
+      try { await this.stop(); } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], 'CoreMail gateway startup and cleanup failed');
+      }
+      throw error;
+    }
+    this.serving = true;
+  }
+
+  /** The CoreMail connection with this routing tag on this listener, requests bound to its socket. */
+  public async findConnection(tagArg: string): Promise<ICoreMailGatewayConnection | undefined> {
+    const server = this.server;
+    if (!server || !this.serving) return undefined;
+    const connection = await server.typedsocket.findTargetConnectionByTag(tagArg);
+    if (!connection) return undefined;
+    return {
+      peer: connection.peer,
+      fire: async (methodArg, requestArg) =>
+        await server.typedsocket.createTypedRequest(methodArg, connection).fire(requestArg),
+    };
+  }
+
+  public async stop(): Promise<void> {
+    this.serving = false;
+    const server = this.server;
+    await server?.stop();
+    if (this.server === server) this.server = undefined;
+  }
+}

package/ts/opsserver/classes.opsserver.ts

@@ -8,6 +8,7 @@ import * as interfaces from '../../ts_interfaces/index.js';
 import { McpManager } from './classes.mcpmanager.js';
 import { createLogStreamAuthorizationAdapter } from './helpers/logstream-auth.js';
 import { WorkloadMailServer } from './classes.workload-mail-server.js';
+import { CoreMailGatewayServer } from './classes.coremail-gateway-server.js';
 import type { IListeningSocket } from '../config/helpers.listeners.js';
 
 export class OpsServer {
@@ -58,6 +59,8 @@ export class OpsServer {
   // Detach the edges start() adds to the dcRouter's main typedrouter, which outlives this server.
   private dcRouterEdgeDisposers: Array<() => void> = [];
   private workloadMailServer?: WorkloadMailServer;
+  /** The CoreMail gateway listener (wire 9) while it runs; absent unless configured. */
+  public coreMailGatewayServer?: CoreMailGatewayServer;
   /** The port the Ops server listens on from its completed start until its stop begins. */
   private listeningPort?: number;
 
@@ -67,8 +70,8 @@ export class OpsServer {
 
   /**
    * The Ops server's socket once its start completed: typedserver binds every address (`0.0.0.0`)
-   * and refuses `start()` on an address another socket holds. The workload mail listener binds
-   * 127.0.0.1 only and is never public, so it is not listed.
+   * and refuses `start()` on an address another socket holds. The workload mail and CoreMail
+   * gateway listeners bind 127.0.0.1 only and are never public, so they are not listed.
    */
   public getListeningSockets(): IListeningSocket[] {
     return this.listeningPort === undefined
@@ -107,6 +110,13 @@ export class OpsServer {
         );
         await this.workloadMailServer.start();
       }
+      if (this.dcRouterRef.options.coreMailGatewayServer) {
+        this.coreMailGatewayServer = new CoreMailGatewayServer(
+          this.dcRouterRef.options.coreMailGatewayServer,
+          this.dcRouterRef.coreMailGatewayManager,
+        );
+        await this.coreMailGatewayServer.start();
+      }
     } catch (startError) {
       // Nobody stops a server whose start failed (ServiceManager rolls back only the services that
       // started), so undo this start here and keep its error first.
@@ -241,6 +251,10 @@ export class OpsServer {
           await this.workloadMailServer?.stop();
           this.workloadMailServer = undefined;
         }),
+        attempt(async () => {
+          await this.coreMailGatewayServer?.stop();
+          this.coreMailGatewayServer = undefined;
+        }),
         attempt(() => this.server?.stop()),
         attempt(() => this.logsHandler?.cleanup()),
       ]);

package/ts/plugins.ts

@@ -55,6 +55,18 @@ export {
   typedsocket,
 }
 
+// The CoreMail gateway listener's wire (Linus ruling 70, L1 and L2): TypedServer 16 with its
+// TypedSocket 10 (wire major 9) and the TypedRequest 9 copy that TypedServer resolves, under aliases
+// only `CoreMailGatewayServer` and the gateway handlers it serves use. Everything else stays on the
+// TypedSocket 8 packages above.
+import * as typedrequestCoreMail from '@api.global/typedrequest-coremail';
+import * as typedserverCoreMail from '@api.global/typedserver-coremail';
+
+export {
+  typedrequestCoreMail,
+  typedserverCoreMail,
+}
+
 // @idp.global scope
 import * as idpSdkServer from '@idp.global/sdk/server';
 

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '34.6.0',
+  version: '34.7.1',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }