@serve.zone/dcrouter 18.0.2 → 18.1.1

package/ts/classes.dcrouter.ts

@@ -31,7 +31,7 @@ import { RemoteIngressHubLifecycle, RemoteIngressManager, TunnelManager, buildEd
 import { VpnAccessResolver, VpnManager, type IVpnManagerConfig } from './vpn/index.js';
 import { RouteConfigManager, ApiTokenManager, GatewayClientManager, ReferenceResolver, DbSeeder, TargetProfileManager, buildHttpRedirectRuntimeRoutes } from './config/index.js';
 import type { TVpnClientAllowEntry } from './config/classes.route-config-manager.js';
-import { SecurityLogger, ContentScanner, IPReputationChecker, SecurityPolicyManager, RoutePolicyAugmenter } from './security/index.js';
+import { SecurityLogger, ContentScanner, IPReputationChecker, SecurityPolicyManager, RoutePolicyAugmenter, AuthenticationEventManager } from './security/index.js';
 import { type IHttp3Config, augmentRoutesWithHttp3 } from './http3/index.js';
 import { applyDefaultInboundPolicy } from './email/inbound-policy.js';
 import { DnsManager } from './dns/manager.dns.js';
@@ -42,7 +42,7 @@ import { DomainOwnershipError } from './dns/domain-ownership.js';
 import { AcmeConfigManager } from './acme/manager.acme-config.js';
 import { SmartAcmeLifecycle } from './acme/classes.smartacme-lifecycle.js';
 import { AcmePermanentFailureError, classifyAcmeFailure } from './acme/acme-failure-classification.js';
-import { AcceptedEmailSpool, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, WorkAppMailManager, type ISmartMtaBlobStorageConfig, type TSmartMtaQueueItemLike } from './email/index.js';
+import { AcceptedEmailSpool, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, SmtpAccountManager, 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';
@@ -277,6 +277,7 @@ export class DcRouter {
   public emailServer?: UnifiedEmailServer;
   public radiusServer?: RadiusServer;
   public opsServer!: OpsServer;
+  private opsServerStopped = false;
   public metricsManager?: MetricsManager;
   private emailEventSubscriptions: Array<{
     emitter: { off(eventName: string, listener: (...args: any[]) => void): void };
@@ -326,11 +327,14 @@ export class DcRouter {
   public emailSettingsManager?: EmailSettingsManager;
   public emailDomainManager?: EmailDomainManager;
   public workAppMailManager: WorkAppMailManager;
+  /** Single composition owner of the email runtime auth block and route list. */
+  public smtpAccountManager: SmtpAccountManager;
   public acceptedEmailSpool: AcceptedEmailSpool;
   public mailEgressCoordinator: MailEgressCoordinator;
   public mailDnsSync: MailDnsSync;
   public mailEdgeEligibility: MailEdgeEligibility;
   public securityPolicyManager?: SecurityPolicyManager;
+  public authenticationEventManager: AuthenticationEventManager;
 
   // Auto-discovered public IP (populated by generateAuthoritativeRecords)
   public detectedPublicIp: string | null = null;
@@ -384,6 +388,9 @@ export class DcRouter {
       smartProxyConfig: coreTrafficConfig,
     };
 
+    // Authentication handlers and metrics share this single bounded event owner.
+    this.authenticationEventManager = new AuthenticationEventManager(this);
+
     // Capture smartmta's own log stream into the ops log buffer — without
     // this, mailer bridge crashes and delivery failures inside smartmta are
     // invisible to `getLogs` and postmortems.
@@ -392,6 +399,7 @@ export class DcRouter {
     // Resolve all data paths from baseDir
     this.resolvedPaths = paths.resolvePaths(this.options.baseDir);
     this.workAppMailManager = new WorkAppMailManager(this);
+    this.smtpAccountManager = new SmtpAccountManager(this);
     this.acceptedEmailSpool = new AcceptedEmailSpool(this);
     const mailEgressIdentitySource = new ReleasedRemoteIngressEgressIdentitySource(this);
     this.mailEdgeEligibility = new MailEdgeEligibility(this, mailEgressIdentitySource);
@@ -426,11 +434,12 @@ export class DcRouter {
       new plugins.taskbuffer.Service('OpsServer')
         .critical()
         .withStart(async () => {
+          this.opsServerStopped = false;
           this.opsServer = new OpsServer(this);
           await this.opsServer.start();
         })
         .withStop(async () => {
-          await this.opsServer?.stop();
+          await this.stopOpsServer();
         })
         .withRetry({ maxRetries: 0 }),
     );
@@ -477,11 +486,17 @@ export class DcRouter {
         .withRetry({ maxRetries: 0 }),
     );
 
-    // MetricsManager: optional, depends on OpsServer
+    // Keep the database alive through the MetricsManager's final persistence drain.
+    const metricsDependencies = ['OpsServer'];
+    if (this.options.dbConfig?.enabled !== false) {
+      metricsDependencies.push('DcRouterDb');
+    }
+
+    // MetricsManager: optional, depends on OpsServer and the database when enabled.
     this.serviceManager.addService(
       new plugins.taskbuffer.Service('MetricsManager')
         .optional()
-        .dependsOn('OpsServer')
+        .dependsOn(...metricsDependencies)
         .withStart(async () => {
           this.metricsManager = new MetricsManager(this);
           await this.metricsManager.start();
@@ -583,6 +598,26 @@ export class DcRouter {
       );
     }
 
+    // SmtpAccountManager: optional, depends on DcRouterDb — loads operator
+    // SMTP accounts into memory before EmailServer composes the auth block.
+    // The instance itself is constructed unconditionally in the constructor
+    // (composition must work with zero accounts when the DB is disabled);
+    // this service only manages the DB load.
+    if (this.options.dbConfig?.enabled !== false) {
+      this.serviceManager.addService(
+        new plugins.taskbuffer.Service('SmtpAccountManager')
+          .optional()
+          .dependsOn('DcRouterDb')
+          .withStart(async () => {
+            await this.smtpAccountManager.start();
+          })
+          .withStop(async () => {
+            await this.smtpAccountManager.stop();
+          })
+          .withRetry({ maxRetries: 1, baseDelayMs: 500 }),
+      );
+    }
+
     // Email Domain Manager: optional, depends on DcRouterDb
     if (this.options.dbConfig?.enabled !== false) {
       this.serviceManager.addService(
@@ -849,6 +884,8 @@ export class DcRouter {
     if (this.options.dbConfig?.enabled !== false) {
       const emailServiceDeps = ['SmartProxy', 'MetricsManager'];
       emailServiceDeps.push('EmailDomainManager');
+      // Accounts must be loaded before setupUnifiedEmailHandling composes auth.
+      emailServiceDeps.push('SmtpAccountManager');
       // Explicit dependency: the outbound mode must come from the DB-backed settings;
       // without it, deliveries defer via the coordinator's strict mode resolution
       // instead of going direct.
@@ -1795,6 +1832,17 @@ export class DcRouter {
     return names;
   }
 
+  private async stopOpsServer(): Promise<void> {
+    if (this.opsServerStopped) return;
+    this.opsServerStopped = true;
+    try {
+      await this.opsServer?.stop();
+    } catch (error) {
+      this.opsServerStopped = false;
+      throw error;
+    }
+  }
+
   public async stop() {
     logger.log('info', 'Stopping DcRouter services...');
 
@@ -1804,6 +1852,10 @@ export class DcRouter {
       this.serviceSubjectSubscription = undefined;
     }
 
+    // Stop accepting authenticated requests before MetricsManager performs its
+    // final durable authentication-event and email-traffic drain.
+    await this.stopOpsServer();
+
     // ServiceManager handles reverse-dependency-ordered shutdown
     await this.serviceManager.stop();
 
@@ -1903,7 +1955,7 @@ export class DcRouter {
       storageManager: this.smartMtaBlobStorageManager,
     };
 
-    let emailConfig: IUnifiedEmailServerOptions = await this.workAppMailManager.applyStoredIdentitiesToEmailConfig({
+    let emailConfig: IUnifiedEmailServerOptions = await this.smtpAccountManager.composeEmailConfig({
       ...this.options.emailConfig,
       ports: mappedEmailPorts,
       domains: applyDefaultInboundPolicy(this.options.emailConfig.domains),
@@ -1969,7 +2021,7 @@ export class DcRouter {
         repairResult.failedDomainIds.length > 0
         || repairResult.failedConfiguredDomains.length > 0
       )) {
-        emailConfig = await this.workAppMailManager.applyStoredIdentitiesToEmailConfig({
+        emailConfig = await this.smtpAccountManager.composeEmailConfig({
           ...emailConfig,
           domains: applyDefaultInboundPolicy(this.options.emailConfig?.domains),
         });
@@ -2003,6 +2055,13 @@ export class DcRouter {
     this.addEmailEventSubscription(emailServer, 'bridgeRecovered', () => {
       logger.log('info', 'Mailer bridge recovered after restart');
     });
+
+    // Live AUTH toggles restart only the SMTP listener; a failed restart
+    // leaves SMTP down while the rest of the server runs. Surface it loudly —
+    // isSmtpListenerActive() stays false until recovery.
+    this.addEmailEventSubscription(emailServer, 'smtpListenerRestartFailed', (err: unknown) => {
+      logger.log('error', `SMTP listener restart failed after an auth update — inbound SMTP is down until recovery: ${(err as Error)?.message || err}`);
+    });
     
     // Start the server
     try {
@@ -2066,7 +2125,6 @@ export class DcRouter {
 
         this.addEmailEventSubscription(emailServer.deliveryQueue, 'itemEnqueued', (item: any) => {
           const envelope = getEnvelope(item);
-          this.metricsManager!.trackEmailReceived(envelope.from);
           updateQueueSize();
           logger.log('info', `Email queued: ${envelope.from} → ${envelope.recipients.join(', ') || 'unknown'}`, { zone: 'email' });
         });

package/ts/db/documents/classes.authentication-event.doc.ts

@@ -0,0 +1,248 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type {
+  IAuthenticationEvent,
+  TAuthenticationFailureReason,
+  TAuthenticationSource,
+  TResolvedAuthenticationSource,
+} from '../../../ts_interfaces/data/stats.js';
+
+const DB_OPERATION_TIMEOUT_MS = 5_000;
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class AuthenticationEventDoc extends plugins.smartdata.SmartDataDbDoc<
+  AuthenticationEventDoc,
+  AuthenticationEventDoc
+> implements IAuthenticationEvent {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public timestamp!: number;
+
+  @plugins.smartdata.svDb()
+  public username!: string;
+
+  @plugins.smartdata.svDb()
+  public userId?: string;
+
+  @plugins.smartdata.svDb()
+  public success!: boolean;
+
+  @plugins.smartdata.svDb()
+  public requestedAuthSource!: TAuthenticationSource;
+
+  @plugins.smartdata.svDb()
+  public resolvedAuthSource?: TResolvedAuthenticationSource;
+
+  @plugins.smartdata.svDb()
+  public failureReason?: TAuthenticationFailureReason;
+
+  constructor() {
+    super();
+  }
+
+  public toApiObject(): IAuthenticationEvent {
+    return {
+      id: this.id,
+      timestamp: this.timestamp,
+      username: this.username,
+      success: this.success,
+      requestedAuthSource: this.requestedAuthSource,
+      ...(this.userId ? { userId: this.userId } : {}),
+      ...(this.resolvedAuthSource ? { resolvedAuthSource: this.resolvedAuthSource } : {}),
+      ...(this.failureReason ? { failureReason: this.failureReason } : {}),
+    };
+  }
+
+  private static async getNativeCollection() {
+    const smartdataCollection = (AuthenticationEventDoc as typeof AuthenticationEventDoc & {
+      collection: plugins.smartdata.SmartdataCollection<AuthenticationEventDoc>;
+    }).collection;
+    await smartdataCollection.init();
+    const probe = new AuthenticationEventDoc();
+    await smartdataCollection.markUniqueIndexes(probe.uniqueIndexes || []);
+    await smartdataCollection.createRegularIndexes(probe.regularIndexes || []);
+    return smartdataCollection.mongoDbCollection;
+  }
+
+  private static toPersistedFields(eventArg: IAuthenticationEvent): IAuthenticationEvent {
+    return {
+      id: eventArg.id,
+      timestamp: eventArg.timestamp,
+      username: eventArg.username,
+      success: eventArg.success,
+      requestedAuthSource: eventArg.requestedAuthSource,
+      ...(eventArg.userId !== undefined ? { userId: eventArg.userId } : {}),
+      ...(eventArg.resolvedAuthSource !== undefined
+        ? { resolvedAuthSource: eventArg.resolvedAuthSource }
+        : {}),
+      ...(eventArg.failureReason !== undefined ? { failureReason: eventArg.failureReason } : {}),
+    };
+  }
+
+  private static validateEvent(eventArg: IAuthenticationEvent): void {
+    if (
+      typeof eventArg.id !== 'string'
+      || !eventArg.id.trim()
+      || !Number.isSafeInteger(eventArg.timestamp)
+      || eventArg.timestamp < 0
+      || typeof eventArg.username !== 'string'
+      || !eventArg.username.trim()
+      || typeof eventArg.success !== 'boolean'
+      || !['auto', 'local', 'idp.global'].includes(eventArg.requestedAuthSource)
+    ) {
+      throw new Error('Invalid authentication event');
+    }
+    if (
+      eventArg.userId !== undefined
+      && (typeof eventArg.userId !== 'string' || !eventArg.userId.trim())
+    ) {
+      throw new Error('Invalid authentication event user ID');
+    }
+    if (
+      eventArg.resolvedAuthSource !== undefined
+      && eventArg.resolvedAuthSource !== 'local'
+      && eventArg.resolvedAuthSource !== 'idp.global'
+    ) {
+      throw new Error('Invalid resolved authentication source');
+    }
+    if (
+      eventArg.failureReason !== undefined
+      && ![
+        'invalidCredentials',
+        'serviceUnavailable',
+        'identityIssuanceFailed',
+        'internalError',
+      ].includes(eventArg.failureReason)
+    ) {
+      throw new Error('Invalid authentication failure reason');
+    }
+    if (eventArg.success && eventArg.failureReason) {
+      throw new Error('Successful authentication events cannot carry a failure reason');
+    }
+    if (!eventArg.success && !eventArg.failureReason) {
+      throw new Error('Failed authentication events require a failure reason');
+    }
+  }
+
+  public static async upsertMany(eventsArg: IAuthenticationEvent[]): Promise<void> {
+    if (eventsArg.length === 0) return;
+    if (eventsArg.length > 500) {
+      throw new Error('AuthenticationEventDoc.upsertMany accepts at most 500 events');
+    }
+    for (const event of eventsArg) {
+      AuthenticationEventDoc.validateEvent(event);
+    }
+    const collection = await AuthenticationEventDoc.getNativeCollection();
+    await collection.bulkWrite(
+      eventsArg.map((event) => {
+        const timestamp = new Date(event.timestamp).toISOString();
+        const persistedEvent = AuthenticationEventDoc.toPersistedFields(event);
+        return {
+          updateOne: {
+            filter: { id: event.id },
+            update: {
+              $setOnInsert: {
+                ...persistedEvent,
+                _createdAt: timestamp,
+                _updatedAt: timestamp,
+              },
+            },
+            upsert: true,
+          },
+        };
+      }),
+      { ordered: false, timeoutMS: DB_OPERATION_TIMEOUT_MS },
+    );
+  }
+
+  public static async getWindowSummary(
+    cutoffArg: number,
+    limitArg = 100,
+  ): Promise<{
+    successes: number;
+    failures: number;
+    events: IAuthenticationEvent[];
+  }> {
+    if (!Number.isSafeInteger(cutoffArg) || cutoffArg < 0) {
+      throw new Error('AuthenticationEventDoc.getWindowSummary requires a valid cutoff');
+    }
+    if (!Number.isSafeInteger(limitArg) || limitArg <= 0 || limitArg > 500) {
+      throw new Error('AuthenticationEventDoc.getWindowSummary requires a limit from 1 to 500');
+    }
+    const collection = await AuthenticationEventDoc.getNativeCollection();
+    const selector = { timestamp: { $gte: cutoffArg } };
+    const cursor = collection
+      .find(selector, { timeoutMS: DB_OPERATION_TIMEOUT_MS })
+      .sort({ timestamp: -1, id: -1 })
+      .limit(limitArg);
+    try {
+      const [successes, failures, rows] = await Promise.all([
+        collection.countDocuments(
+          { ...selector, success: true },
+          { timeoutMS: DB_OPERATION_TIMEOUT_MS },
+        ),
+        collection.countDocuments(
+          { ...selector, success: false },
+          { timeoutMS: DB_OPERATION_TIMEOUT_MS },
+        ),
+        cursor.toArray(),
+      ]);
+      return {
+        successes,
+        failures,
+        events: rows.map((row) => AuthenticationEventDoc
+          .createInstanceFromMongoDbNativeDoc(row as any)
+          .toApiObject()),
+      };
+    } finally {
+      await cursor.close({ timeoutMS: DB_OPERATION_TIMEOUT_MS });
+    }
+  }
+
+  public static async findExistingIds(idsArg: string[]): Promise<Set<string>> {
+    const ids = [...new Set(idsArg)];
+    if (ids.length === 0) return new Set();
+    if (ids.length > 500) {
+      throw new Error('AuthenticationEventDoc.findExistingIds accepts at most 500 ids');
+    }
+    const collection = await AuthenticationEventDoc.getNativeCollection();
+    const rows = await collection
+      .find(
+        { id: { $in: ids } },
+        { projection: { id: 1 }, timeoutMS: DB_OPERATION_TIMEOUT_MS },
+      )
+      .toArray();
+    return new Set(rows.map((row) => String(row.id)));
+  }
+
+  public static async pruneBefore(cutoffArg: number): Promise<number> {
+    if (!Number.isSafeInteger(cutoffArg) || cutoffArg < 0) {
+      throw new Error('AuthenticationEventDoc.pruneBefore requires a valid cutoff');
+    }
+    const collection = await AuthenticationEventDoc.getNativeCollection();
+    let deletedCount = 0;
+    while (true) {
+      const rows = await collection
+        .find(
+          { timestamp: { $lt: cutoffArg } },
+          { projection: { _id: 1 }, timeoutMS: DB_OPERATION_TIMEOUT_MS },
+        )
+        .sort({ timestamp: 1, _id: 1 })
+        .limit(500)
+        .toArray();
+      if (rows.length === 0) break;
+      const result = await collection.deleteMany(
+        { _id: { $in: rows.map((row) => row._id) } },
+        { timeoutMS: DB_OPERATION_TIMEOUT_MS },
+      );
+      deletedCount += result.deletedCount;
+      if (rows.length < 500) break;
+    }
+    return deletedCount;
+  }
+}

package/ts/db/documents/classes.email-traffic-bucket.doc.ts

@@ -0,0 +1,161 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const DB_OPERATION_TIMEOUT_MS = 5_000;
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+export interface IEmailTrafficBucketCounts {
+  sent: number;
+  received: number;
+  failed: number;
+}
+
+export interface IEmailTrafficBucketSnapshot extends IEmailTrafficBucketCounts {
+  bucketStart: number;
+}
+
+@plugins.smartdata.Collection(() => getDb())
+export class EmailTrafficBucketDoc extends plugins.smartdata.SmartDataDbDoc<
+  EmailTrafficBucketDoc,
+  EmailTrafficBucketDoc
+> implements IEmailTrafficBucketSnapshot {
+  @plugins.smartdata.unI()
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public bucketStart!: number;
+
+  @plugins.smartdata.svDb()
+  public sent: number = 0;
+
+  @plugins.smartdata.svDb()
+  public received: number = 0;
+
+  @plugins.smartdata.svDb()
+  public failed: number = 0;
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  constructor() {
+    super();
+  }
+
+  private static async getNativeCollection() {
+    const smartdataCollection = (EmailTrafficBucketDoc as typeof EmailTrafficBucketDoc & {
+      collection: plugins.smartdata.SmartdataCollection<EmailTrafficBucketDoc>;
+    }).collection;
+    await smartdataCollection.init();
+    const probe = new EmailTrafficBucketDoc();
+    await smartdataCollection.markUniqueIndexes(probe.uniqueIndexes || []);
+    await smartdataCollection.createRegularIndexes(probe.regularIndexes || []);
+    return smartdataCollection.mongoDbCollection;
+  }
+
+  private static validateSnapshot(snapshotArg: IEmailTrafficBucketSnapshot): void {
+    const counts = [snapshotArg.sent, snapshotArg.received, snapshotArg.failed];
+    if (
+      !Number.isSafeInteger(snapshotArg.bucketStart)
+      || snapshotArg.bucketStart < 0
+      || snapshotArg.bucketStart % 60_000 !== 0
+      || counts.some((count) => !Number.isSafeInteger(count) || count < 0)
+    ) {
+      throw new Error('Invalid email traffic bucket snapshot');
+    }
+  }
+
+  /** Persist retry-safe absolute monotonic counters. */
+  public static async persistAbsolute(snapshotsArg: IEmailTrafficBucketSnapshot[]): Promise<void> {
+    if (snapshotsArg.length === 0) return;
+    if (snapshotsArg.length > 500) {
+      throw new Error('EmailTrafficBucketDoc.persistAbsolute accepts at most 500 buckets');
+    }
+    for (const snapshot of snapshotsArg) {
+      EmailTrafficBucketDoc.validateSnapshot(snapshot);
+    }
+    const collection = await EmailTrafficBucketDoc.getNativeCollection();
+    const now = Date.now();
+    const updatedAt = new Date(now).toISOString();
+    await collection.bulkWrite(
+      snapshotsArg.map((snapshot) => ({
+        updateOne: {
+          filter: { bucketStart: snapshot.bucketStart },
+          update: {
+            $max: {
+              sent: snapshot.sent,
+              received: snapshot.received,
+              failed: snapshot.failed,
+            },
+            $set: {
+              updatedAt: now,
+              _updatedAt: updatedAt,
+            },
+            $setOnInsert: {
+              id: `email-traffic-${snapshot.bucketStart}`,
+              bucketStart: snapshot.bucketStart,
+              createdAt: now,
+              _createdAt: updatedAt,
+            },
+          },
+          upsert: true,
+        },
+      })),
+      { ordered: false, timeoutMS: DB_OPERATION_TIMEOUT_MS },
+    );
+  }
+
+  public static async loadSince(cutoffArg: number): Promise<IEmailTrafficBucketSnapshot[]> {
+    if (!Number.isSafeInteger(cutoffArg) || cutoffArg < 0) {
+      throw new Error('EmailTrafficBucketDoc.loadSince requires a valid cutoff');
+    }
+    const collection = await EmailTrafficBucketDoc.getNativeCollection();
+    const cursor = collection
+      .find(
+        { bucketStart: { $gte: cutoffArg } },
+        { timeoutMS: DB_OPERATION_TIMEOUT_MS },
+      )
+      .sort({ bucketStart: 1 });
+    try {
+      const rows = await cursor.toArray();
+      return rows.map((row) => ({
+        bucketStart: Number(row.bucketStart),
+        sent: Number(row.sent || 0),
+        received: Number(row.received || 0),
+        failed: Number(row.failed || 0),
+      }));
+    } finally {
+      await cursor.close({ timeoutMS: DB_OPERATION_TIMEOUT_MS });
+    }
+  }
+
+  public static async pruneBefore(cutoffArg: number): Promise<number> {
+    if (!Number.isSafeInteger(cutoffArg) || cutoffArg < 0) {
+      throw new Error('EmailTrafficBucketDoc.pruneBefore requires a valid cutoff');
+    }
+    const collection = await EmailTrafficBucketDoc.getNativeCollection();
+    let deletedCount = 0;
+    while (true) {
+      const rows = await collection
+        .find(
+          { bucketStart: { $lt: cutoffArg } },
+          { projection: { _id: 1 }, timeoutMS: DB_OPERATION_TIMEOUT_MS },
+        )
+        .sort({ bucketStart: 1, _id: 1 })
+        .limit(500)
+        .toArray();
+      if (rows.length === 0) break;
+      const result = await collection.deleteMany(
+        { _id: { $in: rows.map((row) => row._id) } },
+        { timeoutMS: DB_OPERATION_TIMEOUT_MS },
+      );
+      deletedCount += result.deletedCount;
+      if (rows.length < 500) break;
+    }
+    return deletedCount;
+  }
+}