@serve.zone/coremail 1.0.2 → 1.2.0

package/dist_ts/index.js

@@ -1,4 +1,5 @@
 import { CoreMail } from './classes.coremail.js';
+import { logCoreMailFailure } from './coremail.log.js';
 export { CoreMail } from './classes.coremail.js';
 export { readCoreMailConfig } from './classes.config.js';
 export const runCli = async () => {
@@ -14,7 +15,9 @@ export const runCli = async () => {
             await coreMail.stop();
             process.exitCode = 0;
         }
-        catch {
+        catch (error) {
+            await logCoreMailFailure('lifecycle', 'SHUTDOWN_FAILED', error)
+                .catch(() => undefined);
             process.exitCode = 1;
         }
     };
@@ -36,4 +39,4 @@ export const runCli = async () => {
         throw error;
     }
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFFakQsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBQ2pELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBR3pELE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxLQUFLLElBQW1CLEVBQUU7SUFDOUMsTUFBTSxRQUFRLEdBQUcsSUFBSSxRQUFRLEVBQUUsQ0FBQztJQUNoQyxJQUFJLFFBQVEsR0FBRyxLQUFLLENBQUM7SUFDckIsTUFBTSxJQUFJLEdBQUcsS0FBSyxJQUFtQixFQUFFO1FBQ3JDLElBQUksUUFBUTtZQUFFLE9BQU87UUFDckIsUUFBUSxHQUFHLElBQUksQ0FBQztRQUNoQixPQUFPLENBQUMsR0FBRyxDQUFDLFFBQVEsRUFBRSxRQUFRLENBQUMsQ0FBQztRQUNoQyxPQUFPLENBQUMsR0FBRyxDQUFDLFNBQVMsRUFBRSxTQUFTLENBQUMsQ0FBQztRQUNsQyxJQUFJLENBQUM7WUFDSCxNQUFNLFFBQVEsQ0FBQyxJQUFJLEVBQUUsQ0FBQztZQUN0QixPQUFPLENBQUMsUUFBUSxHQUFHLENBQUMsQ0FBQztRQUN2QixDQUFDO1FBQUMsTUFBTSxDQUFDO1lBQ1AsT0FBTyxDQUFDLFFBQVEsR0FBRyxDQUFDLENBQUM7UUFDdkIsQ0FBQztJQUNILENBQUMsQ0FBQztJQUNGLE1BQU0sUUFBUSxHQUFHLEdBQUcsRUFBRTtRQUNwQixLQUFLLElBQUksRUFBRSxDQUFDO0lBQ2QsQ0FBQyxDQUFDO0lBQ0YsTUFBTSxTQUFTLEdBQUcsR0FBRyxFQUFFO1FBQ3JCLEtBQUssSUFBSSxFQUFFLENBQUM7SUFDZCxDQUFDLENBQUM7SUFDRixPQUFPLENBQUMsRUFBRSxDQUFDLFFBQVEsRUFBRSxRQUFRLENBQUMsQ0FBQztJQUMvQixPQUFPLENBQUMsRUFBRSxDQUFDLFNBQVMsRUFBRSxTQUFTLENBQUMsQ0FBQztJQUNqQyxJQUFJLENBQUM7UUFDSCxNQUFNLFFBQVEsQ0FBQyxLQUFLLEVBQUUsQ0FBQztJQUN6QixDQUFDO0lBQUMsT0FBTyxLQUFLLEVBQUUsQ0FBQztRQUNmLE9BQU8sQ0FBQyxHQUFHLENBQUMsUUFBUSxFQUFFLFFBQVEsQ0FBQyxDQUFDO1FBQ2hDLE9BQU8sQ0FBQyxHQUFHLENBQUMsU0FBUyxFQUFFLFNBQVMsQ0FBQyxDQUFDO1FBQ2xDLE1BQU0sUUFBUSxDQUFDLElBQUksRUFBRSxDQUFDLEtBQUssQ0FBQyxHQUFHLEVBQUUsQ0FBQyxTQUFTLENBQUMsQ0FBQztRQUM3QyxNQUFNLEtBQUssQ0FBQztJQUNkLENBQUM7QUFDSCxDQUFDLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFDakQsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFFdkQsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLHVCQUF1QixDQUFDO0FBQ2pELE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxNQUFNLHFCQUFxQixDQUFDO0FBR3pELE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxLQUFLLElBQW1CLEVBQUU7SUFDOUMsTUFBTSxRQUFRLEdBQUcsSUFBSSxRQUFRLEVBQUUsQ0FBQztJQUNoQyxJQUFJLFFBQVEsR0FBRyxLQUFLLENBQUM7SUFDckIsTUFBTSxJQUFJLEdBQUcsS0FBSyxJQUFtQixFQUFFO1FBQ3JDLElBQUksUUFBUTtZQUFFLE9BQU87UUFDckIsUUFBUSxHQUFHLElBQUksQ0FBQztRQUNoQixPQUFPLENBQUMsR0FBRyxDQUFDLFFBQVEsRUFBRSxRQUFRLENBQUMsQ0FBQztRQUNoQyxPQUFPLENBQUMsR0FBRyxDQUFDLFNBQVMsRUFBRSxTQUFTLENBQUMsQ0FBQztRQUNsQyxJQUFJLENBQUM7WUFDSCxNQUFNLFFBQVEsQ0FBQyxJQUFJLEVBQUUsQ0FBQztZQUN0QixPQUFPLENBQUMsUUFBUSxHQUFHLENBQUMsQ0FBQztRQUN2QixDQUFDO1FBQUMsT0FBTyxLQUFLLEVBQUUsQ0FBQztZQUNmLE1BQU0sa0JBQWtCLENBQUMsV0FBVyxFQUFFLGlCQUFpQixFQUFFLEtBQUssQ0FBQztpQkFDNUQsS0FBSyxDQUFDLEdBQUcsRUFBRSxDQUFDLFNBQVMsQ0FBQyxDQUFDO1lBQzFCLE9BQU8sQ0FBQyxRQUFRLEdBQUcsQ0FBQyxDQUFDO1FBQ3ZCLENBQUM7SUFDSCxDQUFDLENBQUM7SUFDRixNQUFNLFFBQVEsR0FBRyxHQUFHLEVBQUU7UUFDcEIsS0FBSyxJQUFJLEVBQUUsQ0FBQztJQUNkLENBQUMsQ0FBQztJQUNGLE1BQU0sU0FBUyxHQUFHLEdBQUcsRUFBRTtRQUNyQixLQUFLLElBQUksRUFBRSxDQUFDO0lBQ2QsQ0FBQyxDQUFDO0lBQ0YsT0FBTyxDQUFDLEVBQUUsQ0FBQyxRQUFRLEVBQUUsUUFBUSxDQUFDLENBQUM7SUFDL0IsT0FBTyxDQUFDLEVBQUUsQ0FBQyxTQUFTLEVBQUUsU0FBUyxDQUFDLENBQUM7SUFDakMsSUFBSSxDQUFDO1FBQ0gsTUFBTSxRQUFRLENBQUMsS0FBSyxFQUFFLENBQUM7SUFDekIsQ0FBQztJQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7UUFDZixPQUFPLENBQUMsR0FBRyxDQUFDLFFBQVEsRUFBRSxRQUFRLENBQUMsQ0FBQztRQUNoQyxPQUFPLENBQUMsR0FBRyxDQUFDLFNBQVMsRUFBRSxTQUFTLENBQUMsQ0FBQztRQUNsQyxNQUFNLFFBQVEsQ0FBQyxJQUFJLEVBQUUsQ0FBQyxLQUFLLENBQUMsR0FBRyxFQUFFLENBQUMsU0FBUyxDQUFDLENBQUM7UUFDN0MsTUFBTSxLQUFLLENBQUM7SUFDZCxDQUFDO0FBQ0gsQ0FBQyxDQUFDIn0=

package/dist_ts/interfaces.d.ts

@@ -79,7 +79,8 @@ export interface ICoreMailReadiness {
 }
 export interface ICoreMailAuthLimiterSnapshot {
     inFlight: number;
-    tokens: number;
+    waiting: number;
+    identities: number;
 }
 export interface ICoreMailPeer {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/coremail",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Authenticated mail persistence and delivery orchestration for serve.zone workloads.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
@@ -8,24 +8,24 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsdocker": "^3.1.1",
+    "@git.zone/tsbuild": "^4.4.3",
+    "@git.zone/tsdocker": "^3.5.8",
     "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^3.6.7",
+    "@git.zone/tstest": "6.0.0",
     "@git.zone/tswatch": "^3.3.5",
-    "@push.rocks/smartmongo": "^7.0.0",
-    "@types/node": "^26.1.1"
+    "@push.rocks/smartmongo": "9.0.0",
+    "@types/node": "26.5.0"
   },
   "dependencies": {
-    "@api.global/typedrequest": "^3.7.0",
-    "@api.global/typedrequest-interfaces": "^4.0.0",
-    "@api.global/typedserver": "^8.10.0",
-    "@api.global/typedsocket": "^5.1.1",
+    "@api.global/typedrequest": "^8.0.4",
+    "@api.global/typedrequest-interfaces": "^7.1.0",
+    "@api.global/typedserver": "^11.4.1",
+    "@api.global/typedsocket": "^8.2.1",
     "@push.rocks/projectinfo": "^5.1.0",
     "@push.rocks/smartbucket": "^4.11.0",
     "@push.rocks/smartdata": "^10.4.0",
     "@push.rocks/smartlog": "^3.2.2",
-    "@serve.zone/interfaces": "^23.0.4",
+    "@serve.zone/interfaces": "30.12.0",
     "argon2": "^0.45.1"
   },
   "files": [

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/coremail',
-  version: '1.0.2',
+  version: '1.2.0',
   description: 'Authenticated mail persistence and delivery orchestration for serve.zone workloads.'
 }

package/ts/classes.auth.ts

@@ -10,6 +10,7 @@ import {
   requireCoreMailIdentifier,
   requireCoreMailSafeInteger,
 } from './coremail.selectors.js';
+import { logCoreMailFailure } from './coremail.log.js';
 
 type TCoreMailDesiredState = plugins.serveZoneInterfaces.data.ICoreMailDesiredState;
 type TCoreMailBinding = plugins.serveZoneInterfaces.data.ICoreMailBindingDesiredState;
@@ -26,6 +27,13 @@ export class CoreMailAuthenticationError extends Error {
   }
 }
 
+export class CoreMailAuthLimitError extends CoreMailAuthenticationError {
+  public constructor() {
+    super();
+    this.name = 'CoreMailAuthLimitError';
+  }
+}
+
 export class CoreMailAuthorizationError extends Error {
   public constructor() {
     super('CoreMail authority is unavailable.');
@@ -40,52 +48,154 @@ export class CoreMailCapabilityDeniedError extends Error {
   }
 }
 
+export interface ICoreMailAuthLimiterOptions {
+  maximumInFlight?: number;
+  maximumWaiters?: number;
+  maximumWaitMs?: number;
+  identityCapacity?: number;
+  identityRefillPerSecond?: number;
+  maximumIdentities?: number;
+  now?: () => number;
+}
+
+interface IIdentityBucket {
+  tokens: number;
+  lastRefillAt: number;
+}
+
+interface ISlotWaiter {
+  grant: () => void;
+  expire: () => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
 export class CoreMailAuthLimiter {
+  private readonly maximumInFlight: number;
+  private readonly maximumWaiters: number;
+  private readonly maximumWaitMs: number;
+  private readonly identityCapacity: number;
+  private readonly identityRefillPerSecond: number;
+  private readonly maximumIdentities: number;
+  private readonly now: () => number;
+
   private inFlight = 0;
-  private tokens: number;
-  private lastRefillAt: number;
+  private readonly waiters: ISlotWaiter[] = [];
+  private readonly identityBuckets = new Map<string, IIdentityBucket>();
 
-  public constructor(
-    private readonly maximumInFlight = 4,
-    private readonly capacity = 8,
-    private readonly refillPerSecond = 2,
-    private readonly now: () => number = Date.now,
-  ) {
-    this.tokens = capacity;
-    this.lastRefillAt = now();
+  public constructor(optionsArg: ICoreMailAuthLimiterOptions = {}) {
+    this.maximumInFlight = optionsArg.maximumInFlight ?? 4;
+    this.maximumWaiters = optionsArg.maximumWaiters ?? 64;
+    this.maximumWaitMs = optionsArg.maximumWaitMs ?? 2_500;
+    this.identityCapacity = optionsArg.identityCapacity ?? 4;
+    this.identityRefillPerSecond = optionsArg.identityRefillPerSecond ?? 1;
+    this.maximumIdentities = optionsArg.maximumIdentities ?? 4_096;
+    this.now = optionsArg.now ?? Date.now;
   }
 
-  private refill(): void {
+  public snapshot(): ICoreMailAuthLimiterSnapshot {
+    return {
+      inFlight: this.inFlight,
+      waiting: this.waiters.length,
+      identities: this.identityBuckets.size,
+    };
+  }
+
+  public async run<T>(
+    identityArg: string,
+    workArg: () => Promise<T>,
+  ): Promise<T> {
+    this.consumeIdentityToken(identityArg);
+    await this.acquireSlot();
+    try {
+      return await workArg();
+    } finally {
+      this.releaseSlot();
+    }
+  }
+
+  private consumeIdentityToken(identityArg: string): void {
     const now = this.now();
-    const elapsedMs = Math.max(0, now - this.lastRefillAt);
-    if (elapsedMs < 1_000) {
+    const bucket = this.identityBuckets.get(identityArg);
+    if (!bucket) {
+      this.pruneIdentities(now);
+      this.identityBuckets.set(identityArg, {
+        tokens: this.identityCapacity - 1,
+        lastRefillAt: now,
+      });
       return;
     }
-    const intervals = Math.floor(elapsedMs / 1_000);
-    this.tokens = Math.min(
-      this.capacity,
-      this.tokens + (intervals * this.refillPerSecond),
-    );
-    this.lastRefillAt += intervals * 1_000;
+    const intervals = Math.floor(Math.max(0, now - bucket.lastRefillAt) / 1_000);
+    if (intervals > 0) {
+      bucket.tokens = Math.min(
+        this.identityCapacity,
+        bucket.tokens + (intervals * this.identityRefillPerSecond),
+      );
+      bucket.lastRefillAt += intervals * 1_000;
+    }
+    if (bucket.tokens < 1) {
+      throw new CoreMailAuthLimitError();
+    }
+    bucket.tokens--;
   }
 
-  public snapshot(): ICoreMailAuthLimiterSnapshot {
-    this.refill();
-    return { inFlight: this.inFlight, tokens: this.tokens };
+  private pruneIdentities(nowArg: number): void {
+    if (this.identityBuckets.size < this.maximumIdentities) {
+      return;
+    }
+    for (const [identity, bucket] of this.identityBuckets) {
+      const refilled = bucket.tokens + (
+        Math.floor(Math.max(0, nowArg - bucket.lastRefillAt) / 1_000)
+        * this.identityRefillPerSecond
+      );
+      if (refilled >= this.identityCapacity) {
+        this.identityBuckets.delete(identity);
+        if (this.identityBuckets.size < this.maximumIdentities) {
+          return;
+        }
+      }
+    }
+    for (const identity of this.identityBuckets.keys()) {
+      this.identityBuckets.delete(identity);
+      if (this.identityBuckets.size < this.maximumIdentities) {
+        return;
+      }
+    }
   }
 
-  public async run<T>(workArg: () => Promise<T>): Promise<T> {
-    this.refill();
-    if (this.inFlight >= this.maximumInFlight || this.tokens < 1) {
-      throw new CoreMailAuthenticationError();
+  private async acquireSlot(): Promise<void> {
+    if (this.inFlight < this.maximumInFlight) {
+      this.inFlight++;
+      return;
     }
-    this.tokens--;
-    this.inFlight++;
-    try {
-      return await workArg();
-    } finally {
-      this.inFlight--;
+    if (this.waiters.length >= this.maximumWaiters) {
+      throw new CoreMailAuthLimitError();
     }
+    await new Promise<void>((resolveArg, rejectArg) => {
+      const waiter: ISlotWaiter = {
+        grant: () => {
+          clearTimeout(waiter.timer);
+          resolveArg();
+        },
+        expire: () => {
+          const index = this.waiters.indexOf(waiter);
+          if (index >= 0) {
+            this.waiters.splice(index, 1);
+          }
+          rejectArg(new CoreMailAuthLimitError());
+        },
+        timer: setTimeout(() => waiter.expire(), this.maximumWaitMs),
+      };
+      this.waiters.push(waiter);
+    });
+  }
+
+  private releaseSlot(): void {
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter.grant();
+      return;
+    }
+    this.inFlight--;
   }
 }
 
@@ -108,7 +218,7 @@ const findAcceptedVerifier = (
 );
 
 export class CoreMailAuth {
-  public readonly limiter = new CoreMailAuthLimiter();
+  public readonly limiter: CoreMailAuthLimiter;
 
   public constructor(
     private readonly controlBootstrap:
@@ -116,7 +226,9 @@ export class CoreMailAuth {
     private readonly getActiveDesiredState: () =>
       Promise<TCoreMailDesiredState | null>,
     private readonly now: () => number = Date.now,
-  ) {}
+  ) {
+    this.limiter = new CoreMailAuthLimiter({ now: this.now });
+  }
 
   private requireFreshPeer(peerArg: ICoreMailPeer): void {
     const deadline = peerArg.context.state[coreMailPreAuthDeadlineKey];
@@ -130,19 +242,23 @@ export class CoreMailAuth {
     }
   }
 
-  private async verify(
-    verifierArg: TCoreMailVerifier | undefined,
-    secretArg: string,
-  ): Promise<void> {
+  private requireSecretShape(secretArg: unknown): string {
     if (
-      !verifierArg
-      || typeof secretArg !== 'string'
+      typeof secretArg !== 'string'
       || secretArg.length < 32
       || secretArg.length > 512
     ) {
       throw new CoreMailAuthenticationError();
     }
-    const verified = await this.limiter.run(async () =>
+    return secretArg;
+  }
+
+  private async verify(
+    verifierArg: TCoreMailVerifier,
+    secretArg: string,
+    identityArg: string,
+  ): Promise<void> {
+    const verified = await this.limiter.run(identityArg, async () =>
       plugins.argon2.verify(verifierArg.verificationHash, secretArg)
     );
     if (!verified) {
@@ -156,8 +272,10 @@ export class CoreMailAuth {
       plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailAuthenticateControl['request'],
   ): Promise<ICoreMailControlSession> {
     this.requireFreshPeer(peerArg);
+    let failureCode = 'INVALID_INPUT';
+    let credentialId: string | undefined;
     try {
-      const credentialId = requireCoreMailIdentifier(
+      credentialId = requireCoreMailIdentifier(
         requestArg.credentialId,
         'credentialId',
       );
@@ -166,13 +284,19 @@ export class CoreMailAuth {
         'credentialVersion',
         1,
       );
+      const credentialSecret = this.requireSecretShape(requestArg.credentialSecret);
+      failureCode = 'UNKNOWN_CREDENTIAL';
       const verifier = findAcceptedVerifier(
         this.controlBootstrap.credentials,
         credentialId,
         credentialVersion,
         this.now(),
       );
-      await this.verify(verifier, requestArg.credentialSecret);
+      if (!verifier) {
+        throw new CoreMailAuthenticationError();
+      }
+      failureCode = 'VERIFIER_REJECTED';
+      await this.verify(verifier, credentialSecret, `control:${credentialId}`);
       const session = Object.freeze<ICoreMailControlSession>({
         kind: 'control',
         peerId: peerArg.id,
@@ -182,8 +306,17 @@ export class CoreMailAuth {
       });
       peerArg.data.set(coreMailSessionKey, session);
       return session;
-    } catch {
+    } catch (error) {
       peerArg.close(4401, 'authentication failed');
+      await logCoreMailFailure(
+        'auth',
+        error instanceof CoreMailAuthLimitError ? 'LIMITER_EXHAUSTED' : failureCode,
+        undefined,
+        {
+          kind: 'control',
+          ...(credentialId === undefined ? {} : { credentialId }),
+        },
+      ).catch(() => undefined);
       throw new CoreMailAuthenticationError();
     }
   }
@@ -194,13 +327,16 @@ export class CoreMailAuth {
       plugins.serveZoneInterfaces.requests.coremail.IReq_CoreMailAuthenticateWorkload['request'],
   ): Promise<ICoreMailWorkloadSession> {
     this.requireFreshPeer(peerArg);
+    let failureCode = 'INVALID_INPUT';
+    let bindingId: string | undefined;
+    let credentialId: string | undefined;
     try {
       const desiredState = await this.getActiveDesiredState();
-      const bindingId = requireCoreMailIdentifier(
+      bindingId = requireCoreMailIdentifier(
         requestArg.bindingId,
         'bindingId',
       );
-      const credentialId = requireCoreMailIdentifier(
+      credentialId = requireCoreMailIdentifier(
         requestArg.credentialId,
         'credentialId',
       );
@@ -209,44 +345,64 @@ export class CoreMailAuth {
         'credentialVersion',
         1,
       );
+      const credentialSecret = this.requireSecretShape(requestArg.credentialSecret);
+      failureCode = 'UNKNOWN_BINDING';
       const binding = desiredState?.bindings.find((bindingArg) =>
         bindingArg.bindingId === bindingId
         && bindingArg.state !== 'disabled'
       );
-      const verifier = binding && findAcceptedVerifier(
+      if (!desiredState || !binding || binding.state === 'disabled') {
+        throw new CoreMailAuthenticationError();
+      }
+      failureCode = 'UNKNOWN_CREDENTIAL';
+      const verifier = findAcceptedVerifier(
         binding.credentials,
         credentialId,
         credentialVersion,
         this.now(),
       );
-      await this.verify(verifier, requestArg.credentialSecret);
+      if (!verifier) {
+        throw new CoreMailAuthenticationError();
+      }
+      failureCode = 'VERIFIER_REJECTED';
+      await this.verify(verifier, credentialSecret, `workload:${bindingId}`);
       const allowedOperations =
         plugins.serveZoneInterfaces.data.resolveCoreMailWorkloadOperations(
-          binding!.state,
-          binding!.capabilities,
+          binding.state,
+          binding.capabilities,
         );
       const session = Object.freeze<ICoreMailWorkloadSession>({
         kind: 'workload',
         peerId: peerArg.id,
-        tenantId: binding!.tenantId,
-        serviceId: binding!.serviceId,
-        bindingId: binding!.bindingId,
-        bindingRevision: binding!.revision,
-        configEpoch: desiredState!.configEpoch,
+        tenantId: binding.tenantId,
+        serviceId: binding.serviceId,
+        bindingId: binding.bindingId,
+        bindingRevision: binding.revision,
+        configEpoch: desiredState.configEpoch,
         credentialId,
         credentialVersion,
-        bindingState: binding!.state as 'active' | 'draining',
-        capabilities: Object.freeze([...binding!.capabilities]) as
+        bindingState: binding.state,
+        capabilities: Object.freeze([...binding.capabilities]) as
           plugins.serveZoneInterfaces.data.TCoreMailCapability[],
         allowedOperations: Object.freeze([...allowedOperations]) as
           plugins.serveZoneInterfaces.data.TCoreMailWorkloadOperation[],
-        coreMailTransferOrigin: desiredState!.gateway.coreMailTransferOrigin,
+        coreMailTransferOrigin: desiredState.gateway.coreMailTransferOrigin,
         authenticatedAt: this.now(),
       });
       peerArg.data.set(coreMailSessionKey, session);
       return session;
-    } catch {
+    } catch (error) {
       peerArg.close(4401, 'authentication failed');
+      await logCoreMailFailure(
+        'auth',
+        error instanceof CoreMailAuthLimitError ? 'LIMITER_EXHAUSTED' : failureCode,
+        undefined,
+        {
+          kind: 'workload',
+          ...(bindingId === undefined ? {} : { bindingId }),
+          ...(credentialId === undefined ? {} : { credentialId }),
+        },
+      ).catch(() => undefined);
       throw new CoreMailAuthenticationError();
     }
   }

package/ts/classes.config.ts

@@ -3,8 +3,13 @@ import type { ICoreMailConfig } from './interfaces.js';
 
 const requireEnv = (keyArg: string): string => {
   const value = process.env[keyArg];
-  if (!value || value.trim() !== value) {
-    throw new Error(`CoreMail requires a non-empty canonical ${keyArg}.`);
+  if (!value) {
+    throw new Error(`CoreMail requires ${keyArg} to be set and non-empty.`);
+  }
+  if (value.trim() !== value) {
+    throw new Error(
+      `CoreMail requires ${keyArg} to be canonical without surrounding whitespace.`,
+    );
   }
   return value;
 };

package/ts/classes.desiredstate.ts

@@ -145,8 +145,8 @@ export class CoreMailDesiredStateService {
           modelArg.state = 'active';
           modelArg.activatedAt = stateArg.updatedAt;
         },
-      }).catch(async () => {
-        await logCoreMailFailure('desired-state', 'SNAPSHOT_REPAIR_FAILED')
+      }).catch(async (error) => {
+        await logCoreMailFailure('desired-state', 'SNAPSHOT_REPAIR_FAILED', error)
           .catch(() => undefined);
       });
     }

package/ts/classes.gateway.ts

@@ -27,6 +27,21 @@ const gatewayAuthority = (serviceIdArg: string): ITransferAuthority => ({
   bindingId: '-',
 });
 
+export const stableStringify = (valueArg: unknown): string => {
+  if (Array.isArray(valueArg)) {
+    return `[${valueArg.map(stableStringify).join(',')}]`;
+  }
+  if (valueArg && typeof valueArg === 'object') {
+    const record = valueArg as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .filter((keyArg) => record[keyArg] !== undefined)
+      .sort()
+      .map((keyArg) => `${JSON.stringify(keyArg)}:${stableStringify(record[keyArg])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(valueArg) ?? 'null';
+};
+
 const normalizeTransferOrigin = (valueArg: unknown): string => {
   if (typeof valueArg !== 'string') {
     throw new Error('CoreMail gateway returned an invalid transfer origin.');
@@ -138,7 +153,7 @@ export class CoreMailGateway {
         if (!gateway) {
           await this.disconnect();
         } else {
-          const signature = JSON.stringify(gateway);
+          const signature = stableStringify(gateway);
           if (
             !this.socket
             || signature !== this.socketSignature
@@ -152,8 +167,8 @@ export class CoreMailGateway {
             this.queueAuthentication(gateway, signature);
           }
         }
-      } catch {
-        await logCoreMailFailure('gateway', 'RECONCILIATION_FAILED')
+      } catch (error) {
+        await logCoreMailFailure('gateway', 'RECONCILIATION_FAILED', error)
           .catch(() => undefined);
         await this.disconnect();
       }
@@ -264,12 +279,12 @@ export class CoreMailGateway {
         this.transferOrigin = transferOrigin;
         this.authenticatedSignature = signatureArg;
       })
-      .catch(async () => {
+      .catch(async (error) => {
         if (this.socketSignature === signatureArg) {
           this.authenticatedSignature = '';
           this.transferOrigin = null;
         }
-        await logCoreMailFailure('gateway', 'AUTHENTICATION_FAILED')
+        await logCoreMailFailure('gateway', 'AUTHENTICATION_FAILED', error)
           .catch(() => undefined);
       })
       .finally(() => {
@@ -596,8 +611,8 @@ export class CoreMailOutboundWorker {
   private async run(): Promise<void> {
     while (!this.stopController.signal.aborted) {
       if (this.gateway.isReady()) {
-        await this.processBatch().catch(async () => {
-          await logCoreMailFailure('worker', 'BATCH_FAILED')
+        await this.processBatch().catch(async (error) => {
+          await logCoreMailFailure('worker', 'BATCH_FAILED', error)
             .catch(() => undefined);
         });
       }
@@ -742,9 +757,10 @@ export class CoreMailOutboundWorker {
         response.status,
         leaseTokenArg,
       );
-    } catch {
-      await logCoreMailFailure('worker', 'DELIVERY_ATTEMPT_FAILED')
-        .catch(() => undefined);
+    } catch (error) {
+      await logCoreMailFailure('worker', 'DELIVERY_ATTEMPT_FAILED', error, {
+        submissionId: submissionArg.submissionId,
+      }).catch(() => undefined);
       const delayMs = Math.min(
         15 * 60 * 1000,
         1_000 * (2 ** Math.min(submissionArg.attempts, 9)),

package/ts/classes.maintenance.ts

@@ -315,9 +315,10 @@ export class CoreMailMaintenanceService {
     if (this.sweepTask) return await this.sweepTask;
     const controller = new AbortController();
     this.sweepController = controller;
-    const task = this.sweep(controller.signal).catch(async () => {
+    const task = this.sweep(controller.signal).catch(async (error) => {
       if (!controller.signal.aborted) {
-        await logCoreMailFailure('retention', 'SWEEP_FAILED').catch(() => undefined);
+        await logCoreMailFailure('retention', 'SWEEP_FAILED', error)
+          .catch(() => undefined);
       }
     });
     this.sweepTask = task;

package/ts/classes.server.ts

@@ -20,6 +20,7 @@ import type {
   ICoreMailWorkloadSession,
 } from './interfaces.js';
 import { CoreMailQuotaExceededError } from './coremail.quota.js';
+import { logCoreMailFailure } from './coremail.log.js';
 
 type TErrorCode = plugins.serveZoneInterfaces.data.TCoreMailErrorCode;
 
@@ -425,14 +426,21 @@ export class CoreMailServer {
     });
   }
 
+  /**
+   * Register one typed handler with uniform failure redaction.
+   *
+   * `handlerArg` is typed as typedrequest's own `THandlerFunction` rather than
+   * a hand-written signature: since typedrequest 8 both sides are wrapped in
+   * the `TReverseVirtualStreamDirections` mapped type, which does not reduce
+   * inside a generic wrapper, so any restatement of the shape stops being
+   * assignable. Concrete `IReq_*` types reduce normally, which is why the call
+   * sites below need no change.
+   */
   private addHandler<
     TRequest extends plugins.typedrequestInterfaces.ITypedRequest,
   >(
     methodArg: TRequest['method'],
-    handlerArg: (
-      requestArg: TRequest['request'],
-      toolsArg: ICoreMailTypedTools | undefined,
-    ) => Promise<TRequest['response']>,
+    handlerArg: plugins.typedrequest.THandlerFunction<TRequest>,
   ): void {
     this.router.addTypedHandler(new plugins.typedrequest.TypedHandler<TRequest>(
       methodArg,
@@ -440,7 +448,13 @@ export class CoreMailServer {
         try {
           return await handlerArg(requestArg, toolsArg);
         } catch (error) {
-          throw privacySafeError(error);
+          const safeError = privacySafeError(error);
+          if (safeError.errorData?.code === 'INVALID_REQUEST') {
+            await logCoreMailFailure('server', 'UNEXPECTED_HANDLER_FAILURE', error, {
+              method: methodArg,
+            }).catch(() => undefined);
+          }
+          throw safeError;
         }
       },
     ));