@serve.zone/dcrouter 17.7.1 → 17.9.0

package/ts/classes.dcrouter.ts

@@ -40,6 +40,7 @@ import { GatewayRouteDnsReconciler } from './dns/classes.gateway-route-dns-recon
 import { AcmeConfigManager } from './acme/manager.acme-config.js';
 import { SmartAcmeLifecycle } from './acme/classes.smartacme-lifecycle.js';
 import { AcceptedEmailSpool, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, WorkAppMailManager, type ISmartMtaBlobStorageConfig, type TSmartMtaQueueItemLike } from './email/index.js';
+import { WebPushManager } from './webpush/index.js';
 import type { IRoute } from '../ts_interfaces/data/route-management.js';
 import type { IEmailOutboundEgressStatus, IEmailPortConfig, IEmailServerSettings, IEmailServerSettingsSeed, TEmailOutboundMode, TEmailServerSettingsUpdate } from '../ts_interfaces/data/email-settings.js';
 import type { IDcRouterRouteConfig, IRemoteIngressHubSettings, IRemoteIngressPerformanceConfig, TRemoteIngressHubSettingsUpdate } from '../ts_interfaces/data/remoteingress.js';
@@ -356,6 +357,7 @@ export class DcRouter {
   public dnsServerRuntime: DnsServerRuntime;
   public emailRouteBuilder: EmailRouteBuilder;
   public routePolicyAugmenter: RoutePolicyAugmenter;
+  public webPushManager: WebPushManager;
 
   // TypedRouter for API endpoints
   public typedrouter = new plugins.typedrequest.TypedRouter();
@@ -399,6 +401,9 @@ export class DcRouter {
     this.dnsServerRuntime = new DnsServerRuntime(this);
     this.emailRouteBuilder = new EmailRouteBuilder(this);
     this.routePolicyAugmenter = new RoutePolicyAugmenter(this);
+    // Construct before OpsServer so early handlers can report unavailable safely.
+    // Secret reads remain deferred until WebPushProvider.start().
+    this.webPushManager = new WebPushManager();
 
     // Initialize service manager and register all services
     this.serviceManager = new plugins.taskbuffer.ServiceManager({
@@ -452,6 +457,24 @@ export class DcRouter {
       );
     }
 
+    // Web Push provider: disabled by default. Enabled mode is critical and
+    // depends on the migrated database; disabled mode reads no provider secrets.
+    const webPushDependencies = this.options.dbConfig?.enabled === false
+      ? []
+      : ['DcRouterDb'];
+    this.serviceManager.addService(
+      new plugins.taskbuffer.Service('WebPushProvider')
+        .critical()
+        .dependsOn(...webPushDependencies)
+        .withStart(async () => {
+          await this.webPushManager.start();
+        })
+        .withStop(async () => {
+          await this.webPushManager.stop();
+        })
+        .withRetry({ maxRetries: 0 }),
+    );
+
     // MetricsManager: optional, depends on OpsServer
     this.serviceManager.addService(
       new plugins.taskbuffer.Service('MetricsManager')
@@ -1048,6 +1071,12 @@ export class DcRouter {
       logger.log('info', `Remote Ingress: tunnel port=${remoteIngressHubSettings.tunnelPort}, edges=${edgeCount} registered/${connectedCount} connected`);
     }
 
+    // Web Push provider summary
+    logger.log(
+      'info',
+      `Web Push Provider: ${this.webPushManager.isReady ? 'ready' : this.webPushManager.isEnabled ? 'unavailable' : 'disabled'}`,
+    );
+
     // Database summary
     if (this.dcRouterDb) {
       logger.log('info', `Database: ${this.dcRouterDb.isEmbedded() ? 'embedded' : 'external'}, db=${this.dcRouterDb.getDbName()}, cleaner=${this.cacheCleaner?.isActive() ? 'active' : 'inactive'} (${(this.options.dbConfig?.cleanupIntervalHours || 1)}h interval)`);

package/ts/config/classes.db-seeder.ts

@@ -102,6 +102,14 @@ const DEFAULT_PROFILES: Array<NonNullable<ISeedData['profiles']>[number]> = [
       },
     },
   },
+  {
+    name: 'LOCAL NETWORK',
+    description: 'RFC1918, IPv6 ULA, and loopback sources for direct hub and private control-plane routes',
+    security: {
+      ipAllowList: ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', '127.0.0.0/8', 'fc00::/7', '::1'],
+      maxConnections: 1000,
+    },
+  },
   {
     name: 'STANDARD',
     description: 'Standard internal access with common private subnets',

package/ts/config/classes.gateway-client-manager.ts

@@ -33,6 +33,8 @@ const defaultCapabilities: IGatewayClient['capabilities'] = {
   manageMail: false,
   readCertificates: false,
   requestCertificates: false,
+  readWebPush: false,
+  manageWebPush: false,
 };
 
 export class GatewayClientManager {

package/ts/config/helpers.http-redirects.ts

@@ -3,7 +3,7 @@ import {
   canonicalizeSourceRouteId,
   type IHttpRedirectInfo,
 } from '../../ts_interfaces/data/route-management.js';
-import type { IDcRouterRouteConfig, IRouteRemoteIngress } from '../../ts_interfaces/data/remoteingress.js';
+import type { IDcRouterRouteConfig, IRouteIngress, IRouteRemoteIngress } from '../../ts_interfaces/data/remoteingress.js';
 
 const AUTO_REDIRECT_ROUTE_PREFIX = 'dcrouter-auto-http-redirect';
 const REDIRECT_STATUS_CODE = 301;
@@ -18,6 +18,7 @@ interface IRedirectCandidate {
   pathPattern?: string;
   sourceRouteNames: Set<string>;
   sourceRouteIds: Set<string>;
+  ingress: IRouteIngress;
   remoteIngress?: IRouteRemoteIngress;
 }
 
@@ -97,6 +98,7 @@ function collectRedirectCandidates(routes: plugins.smartproxy.IRouteConfig[]): I
       if (existing) {
         existing.sourceRouteNames.add(getRouteDisplayName(route));
         if (route.id) existing.sourceRouteIds.add(canonicalizeSourceRouteId(route.id));
+        existing.ingress = mergeIngress(existing.ingress, getRouteIngress(route as IDcRouterRouteConfig));
         existing.remoteIngress = mergeRemoteIngress(existing.remoteIngress, (route as IDcRouterRouteConfig).remoteIngress);
         continue;
       }
@@ -109,6 +111,7 @@ function collectRedirectCandidates(routes: plugins.smartproxy.IRouteConfig[]): I
         pathPattern: route.match.path,
         sourceRouteNames: new Set([getRouteDisplayName(route)]),
         sourceRouteIds: new Set(route.id ? [canonicalizeSourceRouteId(route.id)] : []),
+        ingress: getRouteIngress(route as IDcRouterRouteConfig),
         remoteIngress: mergeRemoteIngress(undefined, (route as IDcRouterRouteConfig).remoteIngress),
       });
     }
@@ -301,10 +304,37 @@ function buildRuntimeRedirectRoute(candidate: IRedirectCandidate): IDcRouterRout
       type: 'socket-handler',
       socketHandler: createHttpRedirectHandler(REDIRECT_TARGET_TEMPLATE, REDIRECT_STATUS_CODE),
     },
+    ingress: candidate.ingress,
     ...(candidate.remoteIngress ? { remoteIngress: candidate.remoteIngress } : {}),
   };
 }
 
+function getRouteIngress(route: IDcRouterRouteConfig): IRouteIngress {
+  if (route.ingress) {
+    return {
+      directHub: route.ingress.directHub,
+      smartVpn: route.ingress.smartVpn,
+    };
+  }
+  if (route.vpnOnly) {
+    return {
+      directHub: false,
+      smartVpn: true,
+    };
+  }
+  return {
+    directHub: true,
+    smartVpn: true,
+  };
+}
+
+function mergeIngress(current: IRouteIngress, next: IRouteIngress): IRouteIngress {
+  return {
+    directHub: current.directHub || next.directHub,
+    smartVpn: current.smartVpn || next.smartVpn,
+  };
+}
+
 function mergeRemoteIngress(
   current: IRouteRemoteIngress | undefined,
   next: IRouteRemoteIngress | undefined,

package/ts/config/helpers.special-forwards.ts

@@ -31,6 +31,9 @@ export function buildLetsEncryptHttp01Route(
   const edgeFilter = configArg.remoteIngress?.edgeFilter
     ?.map((entry) => entry.trim())
     .filter(Boolean);
+  if (configArg.remoteIngress?.enabled !== true) {
+    throw new Error('Public HTTP-01 forwards require RemoteIngress');
+  }
 
   return {
     name,
@@ -48,14 +51,14 @@ export function buildLetsEncryptHttp01Route(
       type: 'forward',
       targets: [target],
     },
-    ...(configArg.remoteIngress?.enabled
-      ? {
-          remoteIngress: {
-            enabled: true,
-            ...(edgeFilter?.length ? { edgeFilter } : {}),
-          },
-        }
-      : {}),
+    ingress: {
+      directHub: false,
+      smartVpn: false,
+    },
+    remoteIngress: {
+      enabled: true,
+      ...(edgeFilter?.length ? { edgeFilter } : {}),
+    },
   };
 }
 

package/ts/db/documents/classes.cached.email.ts

@@ -130,6 +130,18 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
   @plugins.smartdata.svDb()
   public rawContentSize: number = 0;
 
+  /** Resolved outbound identity id that scopes a service-mail replay key. */
+  @plugins.smartdata.svDb()
+  public submissionCredentialId?: string;
+
+  /** Caller-supplied replay key. It must remain absent for non-idempotent mail. */
+  @plugins.smartdata.svDb()
+  public submissionIdempotencyKey?: string;
+
+  /** Digest of the exact authenticated outbound submission semantics. */
+  @plugins.smartdata.svDb()
+  public submissionDigest?: string;
+
   /** Bounded durable SMTP transaction history copied from SmartMTA. */
   @plugins.smartdata.svDb()
   public smtpTransactions: ICachedEmailSmtpTransaction[] = [];
@@ -242,12 +254,47 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
 
   public override async createSavableObject(): Promise<CachedEmail> {
     const savableObject = await super.createSavableObject();
+    const submissionFields = [
+      this.submissionCredentialId,
+      this.submissionIdempotencyKey,
+      this.submissionDigest,
+    ];
+    if (submissionFields.every((valueArg) => valueArg === undefined)) {
+      delete savableObject.submissionCredentialId;
+      delete savableObject.submissionIdempotencyKey;
+      delete savableObject.submissionDigest;
+    } else if (
+      typeof this.submissionCredentialId !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(this.submissionCredentialId)
+      || typeof this.submissionIdempotencyKey !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._/-]{0,199}$/.test(this.submissionIdempotencyKey)
+      || typeof this.submissionDigest !== 'string'
+      || !/^sha256:[a-f0-9]{64}$/.test(this.submissionDigest)
+    ) {
+      throw new Error('CachedEmail submission idempotency metadata is invalid');
+    }
     if (this.rawContentObjectKey) {
       delete savableObject.rawContent;
     }
     return savableObject;
   }
 
+  public static async findBySubmissionIdempotencyKey(
+    credentialIdArg: string,
+    idempotencyKeyArg: string,
+  ): Promise<CachedEmail | null> {
+    if (
+      typeof credentialIdArg !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(credentialIdArg)
+      || typeof idempotencyKeyArg !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._/-]{0,199}$/.test(idempotencyKeyArg)
+    ) throw new Error('CachedEmail submission idempotency selector is invalid');
+    return await CachedEmail.getInstance({
+      submissionCredentialId: credentialIdArg,
+      submissionIdempotencyKey: idempotencyKeyArg,
+    });
+  }
+
   /**
    * Create a new CachedEmail with a unique ID
    */

package/ts/db/documents/classes.webpush-admission.doc.ts

@@ -0,0 +1,48 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+/**
+ * Durable, binding-scoped Web Push admission counters.
+ *
+ * A credential rotation must not reset these counters, so the stable binding
+ * id and lifecycle generation are the authority rather than a credential id.
+ */
+@plugins.smartdata.Collection(() => getDb())
+export class WebPushAdmissionDoc extends plugins.smartdata.SmartDataDbDoc<
+  WebPushAdmissionDoc,
+  WebPushAdmissionDoc
+> {
+  @plugins.smartdata.svDb()
+  public bindingId!: string;
+
+  @plugins.smartdata.svDb()
+  public lifecycleGeneration!: number;
+
+  @plugins.smartdata.svDb()
+  public shortWindowStartedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public shortWindowCount!: number;
+
+  @plugins.smartdata.svDb()
+  public longWindowStartedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public longWindowCount!: number;
+
+  @plugins.smartdata.svDb()
+  public revision!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public purgeAt!: Date;
+
+  public static getNativeCollection():
+    plugins.smartdata.SmartdataCollection<WebPushAdmissionDoc>['mongoDbCollection'] {
+    return getDb().mongoDb.collection('WebPushAdmissionDoc');
+  }
+}

package/ts/db/documents/classes.webpush-binding.doc.ts

@@ -0,0 +1,147 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { IWebPushEncryptedEnvelope } from '../../webpush/classes.webpush-crypto.js';
+
+export interface IWebPushStoredCredential {
+  id: string;
+  status: plugins.servezoneInterfaces.data.TWebPushCredentialStatus;
+  hmacKeyId: string;
+  secretHash?: string;
+  createdAt: number;
+  updatedAt: number;
+  lastRotatedAt: number | null;
+  validUntil: number | null;
+}
+
+export interface IWebPushStoredVapidKey {
+  id: string;
+  publicKey: string;
+  status: plugins.servezoneInterfaces.data.TWebPushVapidKeyStatus;
+  createdAt: number;
+  activatedAt: number | null;
+  retireAfter: number | null;
+  retiredAt: number | null;
+  privateKeyEnvelope?: IWebPushEncryptedEnvelope;
+}
+
+export interface IWebPushCredentialRotationRecovery {
+  requestedCredentialId: string;
+  resultingCredentialId: string;
+  lifecycleGeneration: number;
+  secretEnvelope: IWebPushEncryptedEnvelope;
+  createdAt: number;
+  expiresAt: number;
+}
+
+export type TWebPushControllerIntent = 'enabled' | 'disabled' | 'deleted';
+
+export interface IWebPushStoredControllerFence {
+  id: string;
+  epoch: string;
+  generation: number;
+  operationId: string;
+  intent: TWebPushControllerIntent;
+  requestDigest: string;
+  appliedAt: number;
+}
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class WebPushBindingDoc extends plugins.smartdata.SmartDataDbDoc<
+  WebPushBindingDoc,
+  WebPushBindingDoc
+> {
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public ownerGatewayClientType!: plugins.servezoneInterfaces.data.TGatewayClientType;
+
+  @plugins.smartdata.svDb()
+  public ownerGatewayClientId!: string;
+
+  @plugins.smartdata.svDb()
+  public ownerAppInstanceId!: string;
+
+  @plugins.smartdata.svDb()
+  public enabled!: boolean;
+
+  @plugins.smartdata.svDb()
+  public status!: plugins.servezoneInterfaces.data.TWebPushBindingStatus;
+
+  @plugins.smartdata.svDb()
+  public credential!: IWebPushStoredCredential;
+
+  /** At most one still-valid overlap credential; expired entries are scrubbed. */
+  @plugins.smartdata.svDb()
+  public previousCredentials: IWebPushStoredCredential[] = [];
+
+  /** MUST BE ABSENT outside the bounded idempotent credential-rotation replay window. */
+  @plugins.smartdata.svDb()
+  public credentialRotationRecovery?: IWebPushCredentialRotationRecovery;
+
+  @plugins.smartdata.svDb()
+  public vapidKeys: IWebPushStoredVapidKey[] = [];
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  @plugins.smartdata.svDb()
+  public mutationRevision!: number;
+
+  @plugins.smartdata.svDb()
+  public lifecycleGeneration!: number;
+
+  /** Highest durably applied controller mutation for this owner-reserving binding. */
+  @plugins.smartdata.svDb()
+  public controllerFence?: IWebPushStoredControllerFence;
+
+  /** MUST BE ABSENT unless this owner-reserving binding is a deletion tombstone. */
+  @plugins.smartdata.svDb()
+  public deletedAt?: number;
+
+  public static getNativeCollection():
+    plugins.smartdata.SmartdataCollection<WebPushBindingDoc>['mongoDbCollection'] {
+    return getDb().mongoDb.collection('WebPushBindingDoc');
+  }
+
+  public override async createSavableObject(): Promise<WebPushBindingDoc> {
+    const savable = await super.createSavableObject();
+    if (savable.credential.secretHash === undefined) {
+      delete savable.credential.secretHash;
+    }
+    savable.previousCredentials = (savable.previousCredentials || []).map((credentialArg) => ({
+      ...credentialArg,
+      lastRotatedAt: credentialArg.lastRotatedAt ?? null,
+      validUntil: credentialArg.validUntil ?? null,
+    })).map((credentialArg) => {
+      if (credentialArg.secretHash === undefined) delete credentialArg.secretHash;
+      return credentialArg;
+    });
+    if (savable.credentialRotationRecovery === undefined) {
+      delete savable.credentialRotationRecovery;
+    }
+    if (savable.controllerFence === undefined) delete savable.controllerFence;
+    savable.vapidKeys = (savable.vapidKeys || []).map((keyArg) => {
+      const normalized = {
+        ...keyArg,
+        activatedAt: keyArg.activatedAt ?? null,
+        retireAfter: keyArg.retireAfter ?? null,
+        retiredAt: keyArg.retiredAt ?? null,
+      };
+      if (normalized.privateKeyEnvelope === undefined) {
+        delete normalized.privateKeyEnvelope;
+      }
+      return normalized;
+    });
+    if (savable.deletedAt === undefined) delete savable.deletedAt;
+    return savable;
+  }
+}

package/ts/db/documents/classes.webpush-spool.doc.ts

@@ -0,0 +1,136 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { IWebPushEncryptedEnvelope } from '../../webpush/classes.webpush-crypto.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class WebPushSpoolDoc extends plugins.smartdata.SmartDataDbDoc<
+  WebPushSpoolDoc,
+  WebPushSpoolDoc
+> {
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public schemaVersion: 1 = 1;
+
+  @plugins.smartdata.svDb()
+  public bindingId!: string;
+
+  @plugins.smartdata.svDb()
+  public lifecycleGeneration!: number;
+
+  /** Credential that created this item; used only for the idempotency namespace. */
+  @plugins.smartdata.svDb()
+  public credentialId!: string;
+
+  @plugins.smartdata.svDb()
+  public hmacKeyId!: string;
+
+  @plugins.smartdata.svDb()
+  public idempotencyKeyDigest!: string;
+
+  @plugins.smartdata.svDb()
+  public requestDigest!: string;
+
+  @plugins.smartdata.svDb()
+  public subscriptionId!: string;
+
+  @plugins.smartdata.svDb()
+  public endpointDigest!: string;
+
+  @plugins.smartdata.svDb()
+  public vapidKeyId!: string;
+
+  @plugins.smartdata.svDb()
+  public subscriptionEnvelope?: IWebPushEncryptedEnvelope;
+
+  @plugins.smartdata.svDb()
+  public payloadEnvelope?: IWebPushEncryptedEnvelope;
+
+  @plugins.smartdata.svDb()
+  public payloadBytes!: number;
+
+  @plugins.smartdata.svDb()
+  public ttlSeconds!: number;
+
+  @plugins.smartdata.svDb()
+  public urgency!: plugins.servezoneInterfaces.data.TWebPushUrgency;
+
+  @plugins.smartdata.svDb()
+  public topic: string | null = null;
+
+  @plugins.smartdata.svDb()
+  public state!: plugins.servezoneInterfaces.data.TWebPushDeliveryState;
+
+  @plugins.smartdata.svDb()
+  public attempts: number = 0;
+
+  @plugins.smartdata.svDb()
+  public acceptedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public nextAttemptAt!: number;
+
+  @plugins.smartdata.svDb()
+  public expiresAt!: number;
+
+  /** MUST BE ABSENT while the item is not leased. */
+  @plugins.smartdata.svDb()
+  public leaseToken?: string;
+
+  /** MUST BE ABSENT while the item is not leased. */
+  @plugins.smartdata.svDb()
+  public leaseExpiresAt?: number;
+
+  /** MUST BE ABSENT until cancellation races with an in-flight send. */
+  @plugins.smartdata.svDb()
+  public cancelRequestedAt?: number;
+
+  /** MUST BE ABSENT until an in-flight cancellation records its terminal reason. */
+  @plugins.smartdata.svDb()
+  public cancelErrorCode?: string;
+
+  /** MUST BE ABSENT before a terminal transition. */
+  @plugins.smartdata.svDb()
+  public terminalAt?: number;
+
+  @plugins.smartdata.svDb()
+  public pushServiceStatusCode: number | null = null;
+
+  @plugins.smartdata.svDb()
+  public errorCode: string | null = null;
+
+  /** MUST BE ABSENT until terminal retention begins. */
+  @plugins.smartdata.svDb()
+  public purgeAt?: Date;
+
+  public static getNativeCollection():
+    plugins.smartdata.SmartdataCollection<WebPushSpoolDoc>['mongoDbCollection'] {
+    return getDb().mongoDb.collection('WebPushSpoolDoc');
+  }
+
+  public override async createSavableObject(): Promise<WebPushSpoolDoc> {
+    const savable = await super.createSavableObject();
+    for (const field of [
+      'subscriptionEnvelope',
+      'payloadEnvelope',
+      'leaseToken',
+      'leaseExpiresAt',
+      'cancelRequestedAt',
+      'cancelErrorCode',
+      'terminalAt',
+      'purgeAt',
+    ] as const) {
+      if (savable[field] === undefined) delete savable[field];
+    }
+    savable.topic = savable.topic ?? null;
+    savable.pushServiceStatusCode = savable.pushServiceStatusCode ?? null;
+    savable.errorCode = savable.errorCode ?? null;
+    return savable;
+  }
+}

package/ts/db/documents/index.ts

@@ -41,5 +41,10 @@ export * from './classes.acme-config.doc.js';
 // Email domain management
 export * from './classes.email-domain.doc.js';
 export * from './classes.email-server-settings.doc.js';
+
+// Web Push provider documents
+export * from './classes.webpush-binding.doc.js';
+export * from './classes.webpush-admission.doc.js';
+export * from './classes.webpush-spool.doc.js';
 export * from './classes.smartmta-storage.doc.js';
 export * from './classes.ops-config-event.doc.js';

package/ts/email/classes.accepted-email-spool.ts

@@ -145,6 +145,10 @@ export interface IAcceptRawEmailOptions {
   processAfterAccept?: boolean;
   /** Explicit direction override for programmatic submitters. Defaults to the session-authenticated rule. */
   direction?: TCachedEmailDirection;
+  /** Exact authenticated outbound identity and replay metadata. */
+  submissionCredentialId?: string;
+  submissionIdempotencyKey?: string;
+  submissionDigest?: string;
 }
 
 /**
@@ -221,7 +225,7 @@ export class AcceptedEmailSpool {
       await cachedEmail.save();
       await this.notifyEmailQueuePersisted(cachedEmail, 'email-accepted');
     } catch (error) {
-      await this.deleteRawMessage(cachedEmail).catch(() => undefined);
+      await this.cleanupRawMessageAfterSaveFailure(cachedEmail, error);
       throw error;
     }
     if (context.abortSignal?.aborted) {
@@ -262,6 +266,9 @@ export class AcceptedEmailSpool {
     cachedEmail.cc = [];
     cachedEmail.bcc = [];
     cachedEmail.subject = optionsArg.subject || this.extractHeader(rawMessage, 'subject') || '';
+    cachedEmail.submissionCredentialId = optionsArg.submissionCredentialId;
+    cachedEmail.submissionIdempotencyKey = optionsArg.submissionIdempotencyKey;
+    cachedEmail.submissionDigest = optionsArg.submissionDigest;
     const persistedRawMessage = this.setDcRouterCacheIdHeader(rawMessage, cachedEmail.id);
     await this.persistRawMessage(cachedEmail, persistedRawMessage);
     cachedEmail.status = 'pending';
@@ -287,7 +294,7 @@ export class AcceptedEmailSpool {
       await cachedEmail.save();
       await this.notifyEmailQueuePersisted(cachedEmail, 'raw-email-accepted');
     } catch (error) {
-      await this.deleteRawMessage(cachedEmail).catch(() => undefined);
+      await this.cleanupRawMessageAfterSaveFailure(cachedEmail, error);
       throw error;
     }
 
@@ -1019,6 +1026,38 @@ export class AcceptedEmailSpool {
     await blobStorage.delete(cachedEmailArg.rawContentObjectKey);
   }
 
+  private async cleanupRawMessageAfterSaveFailure(
+    cachedEmailArg: CachedEmail,
+    saveErrorArg: unknown,
+  ): Promise<void> {
+    try {
+      await this.deleteRawMessage(cachedEmailArg);
+      return;
+    } catch (deleteError: unknown) {
+      // Keep a durable, immediately-expired reference. CacheCleaner retries the
+      // SmartBucket deletion before removing this recovery document.
+      cachedEmailArg.submissionCredentialId = undefined;
+      cachedEmailArg.submissionIdempotencyKey = undefined;
+      cachedEmailArg.submissionDigest = undefined;
+      cachedEmailArg.markFailed(
+        `Accepted-email persistence failed; raw-message cleanup pending: ${(saveErrorArg as Error).message}`,
+      );
+      cachedEmailArg.setTTL(0);
+      try {
+        await cachedEmailArg.save();
+      } catch (recoveryError: unknown) {
+        throw new AggregateError(
+          [saveErrorArg, deleteError, recoveryError],
+          `Accepted-email persistence and durable raw-message cleanup failed for ${cachedEmailArg.id}`,
+        );
+      }
+      logger.log(
+        'warn',
+        `Persisted raw-message cleanup recovery for ${cachedEmailArg.id}: ${(deleteError as Error).message}`,
+      );
+    }
+  }
+
   private async persistRawMessage(cachedEmailArg: CachedEmail, rawMessageArg: string): Promise<void> {
     const blobStorage = this.dcRouterRef.getSmartMtaBlobStorageManager();
     if (!blobStorage) {