@serve.zone/platformclient 3.0.0 → 4.0.0

package/readme.md

@@ -19,7 +19,7 @@ import { SzPlatformClient } from '@serve.zone/platformclient';
 
 const platformClient = new SzPlatformClient({
   token: process.env.SERVEZONE_PLATFORM_TOKEN,
-  platformUrl: process.env.SERVEZONE_PLATFORM_URL,
+  cloudlyUrl: process.env.SERVEZONE_PLATFORM_URL,
 });
 
 await platformClient.init();
@@ -49,14 +49,16 @@ The request and response payloads come from `@serve.zone/interfaces`, so TypeScr
 
 ## Configuration
 
-The shared platform connection needs an authorization string and a platform endpoint. Authorization comes from explicit options or environment values. Value-free platform bindings can supply endpoint discovery metadata, but never credentials.
+The shared platform connection requires a Cloudly machine token and an explicit HTTPS Cloudly origin. On each connection it exchanges the token for an API machine identity and registers that JWT on the physical socket before initialization succeeds. Reconnect repeats both steps, and a live connection renews its identity before expiry. Rejected credentials, invalid registration replies, or failed renewal close the connection. Value-free platform bindings describe capabilities; they never select the Cloudly authority or provide credentials.
 
 | Value | Sources |
 | --- | --- |
 | Authorization | Constructor string, `authorizationString`, `authorization`, `token`, `init()` argument, `SERVEZONE_PLATFORM_AUTHORIZATION`, or `SERVEZONE_PLATFORM_TOKEN`. |
-| Platform URL | `url`, `platformUrl`, `SERVEZONE_PLATFORM_URL`, or the first active binding endpoint using `typedrequest` or `http`. |
+| Cloudly URL | `cloudlyUrl`, `url`, `platformUrl`, or `SERVEZONE_PLATFORM_URL`; an explicit HTTPS origin is required. |
 | Platform bindings | Constructor `binding` or `bindings`, `SERVEZONE_PLATFORM_BINDING`, or `SERVEZONE_PLATFORM_BINDINGS`. |
 
+Workloads should receive their service-scoped `platform:session` token through `SERVEZONE_PLATFORM_AUTHORIZATION`. A deployment token does not grant a platform session. The SDK never sends the token to a binding or mail endpoint. Token exchange and registration bypass request payload hooks and disable automatic RPC retries.
+
 Binding environment variables must contain JSON encoded, value-free `IPlatformBinding` objects from `@serve.zone/interfaces`.
 
 Service mail credentials come only from workload environment variables. Standard platformclient mail uses dcrouter TypedSocket/TypedRequest service credentials. The default sender uses `MAIL_FROM`, `MAIL_TYPED_URL`, `MAIL_API_CREDENTIAL_ID`, and `MAIL_API_CREDENTIAL_SECRET`. Additional configured sender addresses use scoped variables such as `MAIL_TEST_SERVICE_GATED_ONE_FROM`, `MAIL_TEST_SERVICE_GATED_ONE_TYPED_URL`, `MAIL_TEST_SERVICE_GATED_ONE_API_CREDENTIAL_ID`, and `MAIL_TEST_SERVICE_GATED_ONE_API_CREDENTIAL_SECRET`.
@@ -83,6 +85,10 @@ const client = new SzPlatformClient({
 await client.init();
 ```
 
+## Socket 8 migration
+
+Version 4 requires Socket 8 peers: upgrade Cloudly and the dedicated dcrouter mail/Web Push endpoints together with their clients. Older Socket 4/5 servers are incompatible. Set `SERVEZONE_PLATFORM_URL` to Cloudly's HTTPS origin and retain `MAIL_TYPED_URL` for the dedicated mail endpoint. Replace legacy platform tokens with Cloudly service credentials; initialization no longer accepts a successful transport handshake as authentication. CoreMail, SMTP credential discovery, mail delivery status, attachments, Reply-To, and debug connector behavior remain available.
+
 ## Debug Mode
 
 Pass `test` as the authorization string to activate debug mode for the shared platform connection and the legacy service connectors. Those connectors log or return deterministic test values instead of sending real platform requests. CoreMail has no debug transport: omit CoreMail configuration in debug clients, because calling `coreMailConnector` methods still requires normal workload authentication.
@@ -110,12 +116,12 @@ The current SMS verification method is spelled `sendSmsVerifcation()` in code. U
 
 ## Lifecycle
 
-`SzPlatformClient` keeps TypedSocket connections open for platform requests, CoreMail, typed service-mail delivery, and managed Web Push delivery. Call `stop()` when a short-lived process, worker, or test is done with the client.
+`SzPlatformClient` keeps separate TypedSocket connections for Cloudly, CoreMail, typed service mail, and managed Web Push. Call `stop()` to cancel initialization, renewal, and restoration and join their cleanup. `requireTypedSocket()` returns the authenticated Cloudly connection while its identity is valid; `typedsocket` is optional. The mail router is private to its own connection, so Cloudly and Web Push peers cannot invoke inbound mail handlers.
 
 ```typescript
 const client = new SzPlatformClient({
   token: process.env.SERVEZONE_PLATFORM_TOKEN,
-  platformUrl: process.env.SERVEZONE_PLATFORM_URL,
+  cloudlyUrl: process.env.SERVEZONE_PLATFORM_URL,
 });
 
 await client.init();
@@ -141,6 +147,7 @@ const status = await client.emailConnector.getServiceMailStatus();
 if (status.ready) {
   const sendResult = await client.emailConnector.sendText({
     to: 'user@example.com',
+    replyTo: 'customer@example.com',
     subject: 'Service mail ready',
     text: 'This message was sent through the managed service mail identity.',
   });
@@ -152,7 +159,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.
+`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.
 
 Specific sender address:
 
@@ -174,7 +181,7 @@ await client.emailConnector.registerInboundHandler(async (message) => {
 });
 ```
 
-`registerInboundHandler()` registers this client connection as the typed endpoint for the configured service mail address. dcrouter then delivers inbound messages through the shared `deliverInboundMail` TypedRequest contract.
+`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.
 
 Inbound message normalization for webhook or direct TypedRequest-style delivery:
 
@@ -279,6 +286,28 @@ await client.letterConnector.sendLetter({
 
 Service-mail and managed Web Push helper types are exported from `@serve.zone/platformclient`. `IServiceMailSendResult.spoolItemId` identifies the dcrouter delivery spool item for follow-up status queries through `getMailDeliveryStatus(spoolItemId, address?)`. `IServiceWebPushEnqueueOptions` and `TServiceWebPushCancellationTarget` mirror the credential-scoped Web Push delivery contract without exposing auth or owner fields. The legacy platform-service request fields remain under `platform.email`, `platform.sms`, `platform.pushnotification`, and `platform.letter`.
 
+Dcrouter rejections with a stable submission code are exposed as `ServiceMailSubmissionError`. Uncoded rejections remain plain `Error` instances:
+
+```typescript
+import { ServiceMailSubmissionError } from '@serve.zone/platformclient';
+
+try {
+  await client.emailConnector.sendText({
+    to: 'user@example.com',
+    replyTo: 'customer@example.com',
+    subject: 'Service mail',
+    text: 'Hello',
+  });
+} catch (error) {
+  if (error instanceof ServiceMailSubmissionError) {
+    console.error(error.code);
+  }
+  throw error;
+}
+```
+
+The exported `TServiceMailSubmissionErrorCode` type contains the supported dcrouter rejection codes.
+
 ## 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.
@@ -366,7 +395,7 @@ The package is authored as ESM TypeScript and builds source folders with `tsbuil
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [repository license file](./license).
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [repository license file](./license.md).
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

package/ts/00_commitinfo_data.ts

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

package/ts/classes.platformclient.ts

@@ -15,6 +15,8 @@ export interface ISzPlatformClientOptions {
   token?: string;
   url?: string;
   platformUrl?: string;
+  /** Explicit HTTPS Cloudly origin. Bindings never select this authority. */
+  cloudlyUrl?: string;
   binding?: plugins.servezoneInterfaces.platform.IPlatformBinding;
   bindings?: plugins.servezoneInterfaces.platform.IPlatformBinding[];
   coreMail?: ISzCoreMailConnectorOptions;
@@ -26,7 +28,13 @@ export class SzPlatformClient {
   private connectionAddress?: string;
   public platformBindings: plugins.servezoneInterfaces.platform.IPlatformBinding[] = [];
   public typedrouter: plugins.typedrequest.TypedRouter = new plugins.typedrequest.TypedRouter();
-  public typedsocket!: plugins.typedsocket.TypedSocket;
+  public typedsocket?: plugins.typedsocket.TypedSocket;
+  private identity?: plugins.servezoneInterfaces.data.IIdentity;
+  private authenticationGeneration = 0;
+  private authenticationAbort?: AbortController;
+  private authenticationOperations = new Set<Promise<unknown>>();
+  private renewalTimer?: ReturnType<typeof setTimeout>;
+  private statusSubscription?: { unsubscribe(): void };
   private qenvInstance = new plugins.qenv.Qenv();
   private stopped = false;
   private initPromise?: Promise<void>;
@@ -77,25 +85,41 @@ export class SzPlatformClient {
       return;
     }
     if (!this.authorizationString) throw new Error('authorizationString is required');
+    if (this.authorizationString.length > 8192 || /[\x00-\x20\x7f]/.test(this.authorizationString)) {
+      throw new Error('Platform authorization is invalid.');
+    }
     const socket = await plugins.typedsocket.TypedSocket.createClient(
-      this.typedrouter as any,
+      this.typedrouter,
       await this.getConnectionAddress(),
-      { abortSignal: this.platformSocketAbortController.signal },
+      {
+        autoReconnect: true, maxRetries: 100, initialBackoffMs: 1000, maxBackoffMs: 30_000,
+        abortSignal: this.platformSocketAbortController.signal,
+        restoreConnection: (context) => {
+          this.invalidateAuthentication();
+          const generation = this.authenticationGeneration;
+          return this.trackAuthentication(this.authenticate(context.createTypedRequest, context.abortSignal, generation));
+        },
+      },
     );
     if (this.stopped) {
-      await socket.stop().catch(() => undefined);
+      await socket.stop();
       throw this.createAbortError();
     }
     this.typedsocket = socket;
     try {
-      await this.setAuthorizationTag();
+      this.statusSubscription = socket.statusSubject.subscribe((status) => {
+        if (status === 'disconnected') this.invalidateAuthentication();
+        if (status === 'connected') this.scheduleRenewal(socket);
+      });
+      this.scheduleRenewal(socket);
       this.assertRunning();
       if (this.coreMailConnector.isConfigured) {
         await this.coreMailConnector.init();
         this.assertRunning();
       }
     } catch (error) {
-      await socket.stop().catch(() => undefined);
+      this.invalidateAuthentication();
+      await socket.stop();
       throw error;
     }
   }
@@ -131,7 +155,7 @@ export class SzPlatformClient {
       optionsArg.authorization ||
       optionsArg.token ||
       this.authorizationString;
-    this.connectionAddress = optionsArg.url || optionsArg.platformUrl || this.connectionAddress;
+    this.connectionAddress = optionsArg.cloudlyUrl || optionsArg.url || optionsArg.platformUrl || this.connectionAddress;
     this.platformBindings = this.mergePlatformBindings(
       this.platformBindings,
       [optionsArg.binding, ...(optionsArg.bindings || [])].filter(
@@ -146,34 +170,12 @@ export class SzPlatformClient {
   private async getConnectionAddress() {
     const connectionAddress =
       this.connectionAddress ||
-      (await this.getConfiguredEnvVar('SERVEZONE_PLATFORM_URL')) ||
-      this.getConnectionAddressFromBindings();
-    if (!connectionAddress) throw new Error('SERVEZONE_PLATFORM_URL or platform binding endpoint is required');
-    return connectionAddress;
-  }
-
-  private getConnectionAddressFromBindings() {
-    for (const binding of this.platformBindings) {
-      if (binding.desiredState === 'disabled' || binding.status === 'failed') {
-        continue;
-      }
-      if (!this.isSupportedConnectorCapability(binding.capability)) {
-        continue;
-      }
-      const endpoint = binding.endpoints?.find((endpointArg) => {
-        return endpointArg.protocol === 'typedrequest' || endpointArg.protocol === 'http';
-      });
-      const endpointUrl = endpoint?.internalUrl || endpoint?.externalUrl;
-      if (endpointUrl) {
-        return endpointUrl;
-      }
-    }
-  }
-
-  private isSupportedConnectorCapability(
-    capabilityArg: plugins.servezoneInterfaces.platform.TPlatformCapability
-  ) {
-    return ['email', 'sms', 'pushnotification', 'letter'].includes(capabilityArg);
+      (await this.getConfiguredEnvVar('SERVEZONE_PLATFORM_URL'));
+    if (!connectionAddress) throw new Error('An explicit Cloudly URL is required.');
+    const parsed = new URL(connectionAddress);
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.search || parsed.hash
+      || parsed.pathname !== '/') throw new Error('Cloudly URL must be an HTTPS origin.');
+    return parsed.origin;
   }
 
   private async getConfiguredAuthorizationString() {
@@ -183,19 +185,81 @@ export class SzPlatformClient {
     );
   }
 
-  private async setAuthorizationTag() {
-    if (!this.authorizationString) {
-      return;
-    }
+  public requireTypedSocket(): plugins.typedsocket.TypedSocket {
+    this.assertRunning();
+    if (!this.typedsocket || this.typedsocket.getStatus() !== 'connected' || !this.identity
+      || this.identity.expiresAt <= Date.now()) throw new Error('Cloudly platform session is unavailable.');
+    return this.typedsocket;
+  }
+
+  private invalidateAuthentication(): void {
+    this.authenticationGeneration++;
+    this.authenticationAbort?.abort();
+    this.authenticationAbort = undefined;
+    this.identity = undefined;
+    if (this.renewalTimer) clearTimeout(this.renewalTimer);
+    this.renewalTimer = undefined;
+  }
+
+  private trackAuthentication<T>(operation: Promise<T>): Promise<T> {
+    this.authenticationOperations.add(operation);
+    void operation.then(() => this.authenticationOperations.delete(operation), () => this.authenticationOperations.delete(operation));
+    return operation;
+  }
+
+  private async authenticate(createRequest: plugins.typedsocket.TTypedSocketRestoreRequestFactory,
+    signal: AbortSignal, generation: number): Promise<void> {
+    const requireCurrent = () => {
+      this.assertRunning(); signal.throwIfAborted();
+      if (generation !== this.authenticationGeneration) throw this.createAbortError();
+    };
     try {
-      await this.typedsocket.setTag('authorization' as any, this.authorizationString);
-    } catch (error) {
-      if (await this.getConfiguredEnvVar('SERVEZONE_PLATFORMCLIENT_DEBUG')) {
-        console.warn('Could not set platform authorization tag:', (error as Error).message);
+      requireCurrent();
+      const exchange = createRequest<plugins.servezoneInterfaces.requests.identity.IRequest_Any_Cloudly_CoreflowManager_GetIdentityByToken>(
+        'getIdentityByToken');
+      exchange.skipHooks = true;
+      const response = await exchange.fire({ token: this.authorizationString! }, { maxRetries: 0, abortSignal: signal });
+      requireCurrent();
+      const identity = response.identity;
+      if (!identity || identity.type !== 'machine' || identity.role !== 'api'
+        || typeof identity.userId !== 'string' || !/^service-machine:[a-f0-9]{64}$/.test(identity.userId)
+        || !Number.isSafeInteger(identity.expiresAt) || identity.expiresAt <= Date.now() + 1000) {
+        throw new Error('Invalid platform identity.');
       }
+      const requestData = plugins.servezoneInterfaces.data.snapshotRegisterCloudlyClientSessionRequestV1({
+        schemaVersion: 1, identity: { jwt: identity.jwt },
+      });
+      const registration = createRequest<plugins.servezoneInterfaces.requests.runtimesession.IReq_Any_Cloudly_RegisterCloudlyClientSessionV1>(
+        'registerCloudlyClientSessionV1');
+      registration.skipHooks = true;
+      const registered = await registration.fire(requestData, { maxRetries: 0, abortSignal: signal });
+      plugins.servezoneInterfaces.data.snapshotRegisterCloudlyClientSessionResponseV1(registered);
+      requireCurrent();
+      this.identity = { type: identity.type, role: identity.role, userId: identity.userId,
+        name: identity.userId, expiresAt: identity.expiresAt, jwt: requestData.identity.jwt };
+    } catch {
+      if (this.stopped || signal.aborted || generation !== this.authenticationGeneration) throw this.createAbortError();
+      throw new Error('Cloudly platform authentication failed.');
     }
   }
 
+  private scheduleRenewal(socket: plugins.typedsocket.TypedSocket): void {
+    if (this.renewalTimer) clearTimeout(this.renewalTimer);
+    if (this.stopped || this.typedsocket !== socket || !this.identity) return;
+    const generation = this.authenticationGeneration;
+    const remaining = this.identity.expiresAt - Date.now();
+    this.renewalTimer = setTimeout(() => {
+      this.renewalTimer = undefined;
+      if (this.stopped || this.typedsocket !== socket || generation !== this.authenticationGeneration) return;
+      const abort = new AbortController(); this.authenticationAbort = abort;
+      const work = this.trackAuthentication(this.authenticate(
+        (method) => socket.createTypedRequest(method), abort.signal, generation));
+      void work.then(() => this.scheduleRenewal(socket), () => {
+        if (!this.stopped && generation === this.authenticationGeneration) void this.stop().catch(() => undefined);
+      });
+    }, Math.max(1, Math.min(30 * 60 * 1000, Math.floor(remaining / 2))));
+  }
+
   public stop(): Promise<void> {
     this.stopPromise ??= this.stopInner();
     return this.stopPromise;
@@ -203,21 +267,26 @@ export class SzPlatformClient {
 
   private async stopInner(): Promise<void> {
     this.stopped = true;
+    this.invalidateAuthentication();
+    this.statusSubscription?.unsubscribe();
+    this.statusSubscription = undefined;
     this.platformSocketAbortController.abort(this.createAbortError());
     const socket = this.typedsocket;
-    await Promise.allSettled([
+    this.typedsocket = undefined;
+    const results = await Promise.allSettled([
       this.emailConnector.stop(),
       this.webPushConnector.stop(),
       this.coreMailConnector.stop(),
       socket?.stop(),
-      this.initPromise,
     ]);
-    if (this.typedsocket && this.typedsocket !== socket) {
-      await this.typedsocket.stop().catch(() => undefined);
-    }
+    await this.initPromise?.catch(() => undefined);
+    while (this.authenticationOperations.size) await Promise.allSettled([...this.authenticationOperations]);
+    const failures = results.filter((result): result is PromiseRejectedResult => result.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map(result => result.reason), 'Platform client shutdown failed.');
   }
 
-  private assertRunning(): void {
+  /** Connector admission guard; shutdown is terminal for this client lifetime. */
+  public assertRunning(): void {
     if (this.stopped) {
       throw this.createAbortError();
     }

package/ts/email/classes.emailconnector.ts

@@ -51,6 +51,8 @@ export interface IServiceMailSendOptions {
   to: string | string[];
   cc?: string | string[];
   bcc?: string | string[];
+  /** One bare mailbox address rendered as the authoritative Reply-To header by dcrouter. */
+  replyTo?: string;
   subject: string;
   text?: string;
   html?: string;
@@ -58,6 +60,19 @@ export interface IServiceMailSendOptions {
   attachments?: IServiceMailAttachment[];
 }
 
+export type TServiceMailSubmissionErrorCode =
+  plugins.servezoneInterfaces.data.TMailSubmissionErrorCode;
+
+export class ServiceMailSubmissionError extends Error {
+  constructor(
+    public readonly code: TServiceMailSubmissionErrorCode,
+    messageArg: string,
+  ) {
+    super(messageArg);
+    this.name = 'ServiceMailSubmissionError';
+  }
+}
+
 export interface IServiceMailSendResult {
   messageId?: string;
   spoolItemId?: string;
@@ -91,12 +106,11 @@ export class SzEmailConnector {
   private mailTypedSocketUrl?: string;
   private mailTypedSocketPromise?: Promise<plugins.typedsocket.TypedSocket>;
   private mailTypedSocketAbortController?: AbortController;
-  private mailTypedSocketStatusSubscription?: { unsubscribe: () => void };
+  private readonly mailRouter = new plugins.typedrequest.TypedRouter();
+  private readonly restorationOperations = new Set<Promise<void>>();
   private inboundHandler?: TServiceMailInboundHandler;
   private inboundTypedHandlerRegistered = false;
   private inboundEndpointRegistrations = new Set<string>();
-  private inboundEndpointReplayPromise?: Promise<void>;
-  private readonly inboundEndpointReplayRetryDelaysMs = [500, 1000, 2000, 5000];
 
   constructor(platformClientRefArg: SzPlatformClient) {
     this.platformClientRef = platformClientRefArg;
@@ -121,7 +135,7 @@ export class SzEmailConnector {
     }
 
     const typedRequest =
-      this.platformClientRef.typedsocket.createTypedRequest<plugins.servezoneInterfaces.platform.email.IReq_SendEmail>(
+      this.platformClientRef.requireTypedSocket().createTypedRequest<plugins.servezoneInterfaces.platform.email.IReq_SendEmail>(
         'sendEmail'
       );
     const response = await typedRequest.fire(optionsArg);
@@ -231,6 +245,7 @@ export class SzEmailConnector {
         to: this.listToArray(optionsArg.to),
         cc: optionsArg.cc ? this.listToArray(optionsArg.cc) : undefined,
         bcc: optionsArg.bcc ? this.listToArray(optionsArg.bcc) : undefined,
+        ...(optionsArg.replyTo !== undefined ? { replyTo: optionsArg.replyTo } : {}),
         subject: optionsArg.subject,
         text: optionsArg.text,
         html: optionsArg.html,
@@ -243,7 +258,11 @@ export class SzEmailConnector {
       },
     });
     if (!result.accepted) {
-      throw new Error(result.message || 'service mail was not accepted by dcrouter');
+      const message = result.message || 'service mail was not accepted by dcrouter';
+      if (result.errorCode) {
+        throw new ServiceMailSubmissionError(result.errorCode, message);
+      }
+      throw new Error(message);
     }
     return {
       messageId: result.spoolItemId,
@@ -283,15 +302,13 @@ export class SzEmailConnector {
     const credentials = await this.getServiceMailTypedCredentials(addressArg);
     const typedSocket = await this.getMailTypedSocket(credentials.typedUrl);
     const result = await this.registerServiceMailEndpoint(typedSocket, credentials);
-    const registeredAddresses = result.addresses?.length ? result.addresses : [credentials.from];
-    for (const address of registeredAddresses) {
-      this.inboundEndpointRegistrations.add(address.trim().toLowerCase());
-    }
+    this.inboundEndpointRegistrations.add(credentials.from);
     return result;
   }
 
   public async stop(): Promise<void> {
     await this.stopMailTypedSocket();
+    while (this.restorationOperations.size) await Promise.allSettled([...this.restorationOperations]);
   }
 
   public normalizeInboundMessage(payloadArg: unknown): IServiceMailInboundMessage {
@@ -341,7 +358,7 @@ export class SzEmailConnector {
   private ensureInboundTypedHandler(): void {
     if (this.inboundTypedHandlerRegistered) return;
     this.inboundTypedHandlerRegistered = true;
-    this.platformClientRef.typedrouter.addTypedHandler(
+    this.mailRouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.mail.IReq_DeliverInboundMail>(
         'deliverInboundMail',
         async (dataArg) => {
@@ -425,6 +442,7 @@ export class SzEmailConnector {
   }
 
   private async getMailTypedSocket(urlArg: string): Promise<plugins.typedsocket.TypedSocket> {
+    this.platformClientRef.assertRunning();
     const normalizedUrl = this.normalizeTypedSocketUrl(urlArg);
     if (this.mailTypedSocket && this.mailTypedSocketUrl === normalizedUrl) {
       return this.mailTypedSocket;
@@ -435,20 +453,27 @@ export class SzEmailConnector {
     if (this.mailTypedSocket || this.mailTypedSocketPromise) {
       await this.stopMailTypedSocket();
     }
+    this.platformClientRef.assertRunning();
     this.mailTypedSocketUrl = normalizedUrl;
     const abortController = new AbortController();
     this.mailTypedSocketAbortController = abortController;
     const socketPromise = plugins.typedsocket.TypedSocket.createClient(
-      this.platformClientRef.typedrouter,
+      this.mailRouter,
       normalizedUrl,
-      { autoReconnect: true, abortSignal: abortController.signal },
+      { autoReconnect: true, abortSignal: abortController.signal,
+        restoreConnection: (context) => {
+          const operation = this.restoreMailConnection(context, normalizedUrl, abortController.signal);
+          this.restorationOperations.add(operation);
+          void operation.then(() => this.restorationOperations.delete(operation), () => this.restorationOperations.delete(operation));
+          return operation;
+        },
+      },
     );
     this.mailTypedSocketPromise = socketPromise;
     try {
       const socket = await socketPromise;
       if (this.mailTypedSocketPromise === socketPromise && this.mailTypedSocketUrl === normalizedUrl) {
         this.mailTypedSocket = socket;
-        this.watchMailTypedSocketStatus(socket);
       } else {
         await socket.stop();
       }
@@ -467,148 +492,49 @@ export class SzEmailConnector {
     const socket = this.mailTypedSocket;
     const socketPromise = this.mailTypedSocketPromise;
     const abortController = this.mailTypedSocketAbortController;
-    const statusSubscription = this.mailTypedSocketStatusSubscription;
     this.mailTypedSocket = undefined;
     this.mailTypedSocketPromise = undefined;
     this.mailTypedSocketUrl = undefined;
     this.mailTypedSocketAbortController = undefined;
-    this.mailTypedSocketStatusSubscription = undefined;
-    statusSubscription?.unsubscribe();
     abortController?.abort();
     if (socket) {
       await socket.stop();
       return;
     }
     if (socketPromise) {
-      try {
-        const pendingSocket = await socketPromise;
-        await pendingSocket.stop();
-      } catch {
-        // The pending connection already failed; there is no socket to stop.
-      }
-    }
-  }
-
-  private watchMailTypedSocketStatus(socketArg: plugins.typedsocket.TypedSocket): void {
-    this.mailTypedSocketStatusSubscription?.unsubscribe();
-    this.mailTypedSocketStatusSubscription = socketArg.statusSubject.subscribe((statusArg) => {
-      void this.handleMailTypedSocketStatus(socketArg, statusArg);
-    });
-  }
-
-  private async handleMailTypedSocketStatus(
-    socketArg: plugins.typedsocket.TypedSocket,
-    statusArg: plugins.typedsocket.TConnectionStatus,
-  ): Promise<void> {
-    if (statusArg !== 'connected' || this.mailTypedSocket !== socketArg) {
-      return;
-    }
-    try {
-      await this.replayInboundEndpointRegistrationsWithRetry(socketArg);
-    } catch (error) {
-      console.warn('Could not re-register service mail endpoint after reconnect:', (error as Error).message);
-    }
-  }
-
-  private async replayInboundEndpointRegistrationsWithRetry(
-    socketArg: plugins.typedsocket.TypedSocket,
-  ): Promise<void> {
-    if (!this.inboundEndpointRegistrations.size) {
-      return;
-    }
-    if (this.inboundEndpointReplayPromise) {
-      return await this.inboundEndpointReplayPromise;
-    }
-
-    const replayPromise = this.replayInboundEndpointRegistrationsWithRetryInner(socketArg);
-    this.inboundEndpointReplayPromise = replayPromise;
-    try {
-      await replayPromise;
-    } finally {
-      if (this.inboundEndpointReplayPromise === replayPromise) {
-        this.inboundEndpointReplayPromise = undefined;
-      }
+      const pendingSocket = await socketPromise.catch(() => undefined);
+      await pendingSocket?.stop();
     }
   }
 
-  private async replayInboundEndpointRegistrationsWithRetryInner(
-    socketArg: plugins.typedsocket.TypedSocket,
+  private async restoreMailConnection(
+    context: plugins.typedsocket.ITypedSocketConnectionRestoreContext,
+    url: string, signal: AbortSignal,
   ): Promise<void> {
-    let lastError: unknown;
-    const delays = [0, ...this.inboundEndpointReplayRetryDelaysMs];
-    for (let attemptIndex = 0; attemptIndex < delays.length; attemptIndex++) {
-      if (this.mailTypedSocket !== socketArg) {
-        return;
-      }
-      if (attemptIndex > 0) {
-        const shouldContinue = await this.waitForInboundEndpointReplayRetry(socketArg, delays[attemptIndex]);
-        if (!shouldContinue) {
-          return;
-        }
-      }
-      try {
-        await this.replayInboundEndpointRegistrationsOnce(socketArg);
-        return;
-      } catch (error) {
-        lastError = error;
-      }
-    }
-    throw lastError instanceof Error
-      ? lastError
-      : new Error('Could not re-register service mail endpoint after reconnect');
-  }
-
-  private async replayInboundEndpointRegistrationsOnce(
-    socketArg: plugins.typedsocket.TypedSocket,
-  ): Promise<void> {
-    for (const address of this.inboundEndpointRegistrations.values()) {
-      if (this.mailTypedSocket !== socketArg) {
-        return;
-      }
+    for (const address of this.inboundEndpointRegistrations) {
+      signal.throwIfAborted(); context.abortSignal.throwIfAborted();
       const credentials = await this.getServiceMailTypedCredentials(address);
-      if (this.normalizeTypedSocketUrl(credentials.typedUrl) !== this.mailTypedSocketUrl) {
-        continue;
-      }
-      await this.registerServiceMailEndpoint(socketArg, credentials);
+      if (credentials.typedUrl !== url) continue;
+      await this.registerServiceMailEndpoint({ createTypedRequest: context.createTypedRequest }, credentials, context.abortSignal);
+      signal.throwIfAborted(); context.abortSignal.throwIfAborted();
     }
   }
 
-  private async waitForInboundEndpointReplayRetry(
-    socketArg: plugins.typedsocket.TypedSocket,
-    delayMsArg: number,
-  ): Promise<boolean> {
-    if (this.mailTypedSocket !== socketArg) {
-      return false;
-    }
-    const abortSignal = this.mailTypedSocketAbortController?.signal;
-    if (abortSignal?.aborted) {
-      return false;
-    }
-    return await new Promise<boolean>((resolve) => {
-      const resolveOnce = (resultArg: boolean) => {
-        clearTimeout(timeout);
-        abortSignal?.removeEventListener('abort', abortHandler);
-        resolve(resultArg && this.mailTypedSocket === socketArg);
-      };
-      const abortHandler = () => resolveOnce(false);
-      const timeout = setTimeout(() => resolveOnce(true), delayMsArg);
-      abortSignal?.addEventListener('abort', abortHandler, { once: true });
-    });
-  }
-
   private async registerServiceMailEndpoint(
-    typedSocketArg: plugins.typedsocket.TypedSocket,
+    typedSocketArg: Pick<plugins.typedsocket.TypedSocket, 'createTypedRequest'>,
     credentialsArg: IServiceMailTypedCredentials,
+    abortSignal?: AbortSignal,
   ): Promise<plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint['response']> {
     const request = typedSocketArg.createTypedRequest<plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint>('registerServiceMailEndpoint');
+    request.skipHooks = true;
     const result = await request.fire({
       auth: {
         credentialId: credentialsArg.credentialId,
         credentialSecret: credentialsArg.credentialSecret,
       },
       addresses: [credentialsArg.from],
-    });
-    if (!result.success) {
+    }, { maxRetries: 0, abortSignal });
+    if (!result.success || result.addresses?.length !== 1 || result.addresses[0] !== credentialsArg.from) {
       throw new Error(result.message || 'Could not register service mail endpoint');
     }
     return result;