@serve.zone/dcrouter 18.1.0 → 18.2.0

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';
@@ -49,6 +49,32 @@ import type { IEmailOutboundEgressStatus, IEmailPortConfig, IEmailServerSettings
 import type { IDcRouterRouteConfig, IRemoteIngressHubSettings, IRemoteIngressPerformanceConfig, TRemoteIngressHubSettingsUpdate } from '../ts_interfaces/data/remoteingress.js';
 import type { ISecurityCompiledPolicy } from '../ts_interfaces/data/security-policy.js';
 
+/**
+ * dcrouter's superset of SmartMTA's SMTP TLS options.
+ *
+ * SmartMTA consumes PEM content (`certPem`/`keyPem`). Deployments configure
+ * certificate FILES, so dcrouter accepts the path form too and loads it eagerly
+ * at startup — a path that cannot be read fails startup rather than silently
+ * leaving the listener without TLS.
+ */
+export interface IDcRouterEmailTlsConfig extends NonNullable<IUnifiedEmailServerOptions['tls']> {
+  /** Path to the certificate chain PEM file. Requires keyPath. */
+  certPath?: string;
+  /** Path to the private key PEM file. Requires certPath. */
+  keyPath?: string;
+}
+
+/** dcrouter's email server options: SmartMTA's, with the path-shaped tls block. */
+export type IDcRouterEmailConfig = Omit<IUnifiedEmailServerOptions, 'tls'> & {
+  tls?: IDcRouterEmailTlsConfig;
+};
+
+/** Whether an email configuration carries any SMTP AUTH credentials. */
+const emailConfigHasAuth = (emailConfigArg: IUnifiedEmailServerOptions | undefined): boolean =>
+  !!emailConfigArg?.auth?.required
+  || !!emailConfigArg?.auth?.users?.length
+  || !!emailConfigArg?.auth?.accounts?.length;
+
 export interface IDcRouterOptions {
   /** Base directory for all dcrouter data. Defaults to ~/.serve.zone/dcrouter */
   baseDir?: string;
@@ -66,7 +92,7 @@ export interface IDcRouterOptions {
    * Email server configuration
    * This enables all email handling with pattern-based routing
    */
-  emailConfig?: IUnifiedEmailServerOptions;
+  emailConfig?: IDcRouterEmailConfig;
 
   /** SmartBucket configuration for durable SmartMTA queue and attachment blobs. */
   emailBlobStorage?: ISmartMtaBlobStorageConfig;
@@ -277,6 +303,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 };
@@ -333,6 +360,7 @@ export class DcRouter {
   public mailDnsSync: MailDnsSync;
   public mailEdgeEligibility: MailEdgeEligibility;
   public securityPolicyManager?: SecurityPolicyManager;
+  public authenticationEventManager: AuthenticationEventManager;
 
   // Auto-discovered public IP (populated by generateAuthoritativeRecords)
   public detectedPublicIp: string | null = null;
@@ -386,6 +414,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.
@@ -429,11 +460,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 }),
     );
@@ -480,11 +512,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();
@@ -1611,6 +1649,10 @@ export class DcRouter {
           expiryDate: event.expiryDate, issuedAt: new Date().toISOString(),
           source: event.source,
         });
+        // Renewals arrive here too. The SMTP listener holds its PEM material as
+        // listener-level Rust configuration, so a renewed mail-hostname
+        // certificate must be pushed or STARTTLS keeps serving the stale one.
+        void this.reapplyEmailTlsMaterial(event.domain);
       });
 
       // Note: smartproxy v27.5.0 emits only 'certificate-issued' and 'certificate-failed'.
@@ -1820,6 +1862,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...');
 
@@ -1829,6 +1882,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();
 
@@ -1928,6 +1985,10 @@ export class DcRouter {
       storageManager: this.smartMtaBlobStorageManager,
     };
 
+    const emailTls = await this.resolveEmailTlsMaterial();
+    const tlsTerminatedPorts = this.resolveEdgeTerminatedEmailPorts(portMapping);
+    this.logEmailAuthTransportPosture(emailConfigHasAuth(baseEmailConfig), emailTls, mappedEmailPorts, tlsTerminatedPorts, mappedSecurePort);
+
     let emailConfig: IUnifiedEmailServerOptions = await this.smtpAccountManager.composeEmailConfig({
       ...this.options.emailConfig,
       ports: mappedEmailPorts,
@@ -1935,6 +1996,7 @@ export class DcRouter {
       dkimKeyProvisioning: 'caller-managed',
       persistRoutes: this.options.emailConfig.persistRoutes ?? false,
       queue: queueOptions,
+      ...(emailTls ? { tls: { ...baseEmailConfig.tls, certPem: emailTls.certPem, keyPem: emailTls.keyPem } } : {}),
       outbound: {
         ...baseEmailConfig.outbound,
         connectionProxyProvider: (context) => this.mailEgressCoordinator.provideConnectionProxy(context),
@@ -1944,6 +2006,7 @@ export class DcRouter {
         ...(mappedSecurePort !== undefined
           ? { securePort: mappedSecurePort }
           : {}),
+        ...(tlsTerminatedPorts.length > 0 ? { tlsTerminatedPorts } : {}),
         recipientValidation: true,
         proxyProtocol: {
           ...baseEmailConfig.smtp?.proxyProtocol,
@@ -2098,7 +2161,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' });
         });
@@ -2152,6 +2214,168 @@ export class DcRouter {
     this.mailDnsSync.requestSync('email server start');
   }
 
+  /**
+   * Resolve the PEM material for the SMTP listener.
+   *
+   * SmartMTA consumes `tls.certPem`/`tls.keyPem`; a path-shaped `tls` block is
+   * ignored, which leaves the Rust listener with no TLS material at all — no
+   * STARTTLS on the plain submission ports. Resolution order matches the
+   * RemoteIngress tunnel precedent: explicit paths, then the ACME cert store.
+   *
+   * Explicitly configured paths that cannot be read FAIL STARTUP. Silently
+   * continuing without TLS is what produced a cleartext submission port in
+   * production, so a broken explicit configuration must be impossible to miss.
+   */
+  private async resolveEmailTlsMaterial(): Promise<{ certPem: string; keyPem: string; source: string } | undefined> {
+    const tlsConfig = this.options.emailConfig?.tls as (IUnifiedEmailServerOptions['tls'] & {
+      certPath?: string;
+      keyPath?: string;
+    }) | undefined;
+
+    if (tlsConfig?.certPem && tlsConfig?.keyPem) {
+      return { certPem: tlsConfig.certPem, keyPem: tlsConfig.keyPem, source: 'inline PEM' };
+    }
+
+    if (tlsConfig?.certPath || tlsConfig?.keyPath) {
+      if (!tlsConfig.certPath || !tlsConfig.keyPath) {
+        throw new Error(
+          'emailConfig.tls requires both certPath and keyPath when either is configured',
+        );
+      }
+      let certPem: string;
+      let keyPem: string;
+      try {
+        certPem = await plugins.fs.promises.readFile(tlsConfig.certPath, 'utf8');
+        keyPem = await plugins.fs.promises.readFile(tlsConfig.keyPath, 'utf8');
+      } catch (error: unknown) {
+        throw new Error(
+          `Unable to read the configured SMTP TLS material (certPath=${tlsConfig.certPath}, keyPath=${tlsConfig.keyPath}): ${(error as Error).message}`,
+        );
+      }
+      if (!certPem.trim() || !keyPem.trim()) {
+        throw new Error(
+          `The configured SMTP TLS material is empty (certPath=${tlsConfig.certPath}, keyPath=${tlsConfig.keyPath})`,
+        );
+      }
+      logger.log('info', `SMTP TLS material loaded from configured paths (${tlsConfig.certPath})`);
+      return { certPem, keyPem, source: `configured paths (${tlsConfig.certPath})` };
+    }
+
+    const mailHostname = this.options.emailConfig?.hostname;
+    if (mailHostname) {
+      try {
+        const stored = await ProxyCertDoc.findByDomain(mailHostname);
+        if (stored?.publicKey && stored?.privateKey) {
+          logger.log('info', `SMTP TLS material loaded from the stored ACME certificate for ${mailHostname}`);
+          return { certPem: stored.publicKey, keyPem: stored.privateKey, source: `stored ACME certificate for ${mailHostname}` };
+        }
+      } catch (error: unknown) {
+        logger.log('warn', `Unable to read the stored certificate for the mail hostname ${mailHostname}: ${(error as Error).message}`);
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Push renewed TLS material to the running SMTP listener.
+   *
+   * Only reacts to the mail hostname, and only when explicit paths are NOT
+   * configured — an operator-managed file pair is not superseded by an ACME
+   * renewal for the same name. SmartMTA restarts just the Rust listener when
+   * the PEM material actually changes.
+   */
+  private async reapplyEmailTlsMaterial(domainArg: string): Promise<void> {
+    const emailServer = this.emailServer;
+    const mailHostname = this.options.emailConfig?.hostname;
+    if (!emailServer || !mailHostname) return;
+    if (domainArg.toLowerCase() !== mailHostname.toLowerCase()) return;
+    const tlsConfig = this.options.emailConfig?.tls;
+    if (tlsConfig?.certPath || tlsConfig?.keyPath) return;
+
+    try {
+      const emailTls = await this.resolveEmailTlsMaterial();
+      if (!emailTls) return;
+      emailServer.updateOptions({
+        tls: { ...this.options.emailConfig?.tls, certPem: emailTls.certPem, keyPem: emailTls.keyPem },
+      });
+      if (this.options.emailConfig) {
+        this.options.emailConfig.tls = {
+          ...this.options.emailConfig.tls,
+          certPem: emailTls.certPem,
+          keyPem: emailTls.keyPem,
+        };
+      }
+      logger.log('info', `Pushed renewed SMTP TLS material for ${mailHostname} to the email listener`);
+    } catch (error: unknown) {
+      logger.log('error', `Unable to apply renewed SMTP TLS material for ${mailHostname}: ${(error as Error).message}`);
+    }
+  }
+
+  /**
+   * Internal SMTP ports whose public leg is TLS-terminated by CoreTraffic.
+   *
+   * Those backend legs arrive as plaintext even though the client's channel was
+   * encrypted, so without declaring them the AUTH-requires-encryption gate would
+   * refuse authentication on the only encrypted submission port. Derived from
+   * the generated route set rather than hardcoding 465, so it stays true when
+   * emailPortConfig changes.
+   */
+  private resolveEdgeTerminatedEmailPorts(portMapping: Record<number, number>): number[] {
+    if (!this.options.emailConfig) return [];
+    const terminatedPorts: number[] = [];
+    for (const route of this.emailRouteBuilder.generateEmailRoutes(this.options.emailConfig)) {
+      if ((route.action as { tls?: { mode?: string } }).tls?.mode !== 'terminate') continue;
+      const publicPorts = Array.isArray(route.match?.ports) ? route.match.ports : [];
+      for (const publicPort of publicPorts) {
+        if (typeof publicPort !== 'number') continue;
+        const internalPort = portMapping[publicPort] || publicPort + 10000;
+        // The implicit-TLS securePort is terminated by smartmta itself.
+        if (internalPort === this.options.emailConfig.smtp?.securePort) continue;
+        if (!terminatedPorts.includes(internalPort)) {
+          terminatedPorts.push(internalPort);
+        }
+      }
+    }
+    return terminatedPorts;
+  }
+
+  /**
+   * State the transport posture of every SMTP listener port at startup.
+   *
+   * AUTH is only offered on an encrypted transport, so an operator has to be
+   * able to see at a glance which submission ports can actually authenticate —
+   * missing certificate material silently disabling AUTH on 587 would otherwise
+   * look like a client problem.
+   */
+  private logEmailAuthTransportPosture(
+    authConfigured: boolean,
+    emailTls: { source: string } | undefined,
+    mappedPorts: number[],
+    tlsTerminatedPorts: number[],
+    mappedSecurePort: number | undefined,
+  ): void {
+    const authCapable: number[] = [];
+    const cleartext: number[] = [];
+    for (const port of mappedPorts) {
+      if (port === mappedSecurePort || tlsTerminatedPorts.includes(port) || emailTls) {
+        authCapable.push(port);
+      } else {
+        cleartext.push(port);
+      }
+    }
+    logger.log(
+      'info',
+      `SMTP transport posture: TLS material=${emailTls ? emailTls.source : 'NONE'}, edge-terminated ports=[${tlsTerminatedPorts.join(', ') || 'none'}], implicit-TLS port=${mappedSecurePort ?? 'none'}, AUTH-capable ports=[${authCapable.join(', ') || 'none'}]`,
+    );
+    if (authConfigured && !emailTls && cleartext.length > 0) {
+      logger.log(
+        'error',
+        `SMTP AUTH is configured but ports [${cleartext.join(', ')}] have no TLS material and no upstream TLS terminator — AUTH is refused there because credentials must never cross a cleartext channel. Configure emailConfig.tls.certPath/keyPath, or provision an ACME certificate for ${this.options.emailConfig?.hostname || 'the mail hostname'}.`,
+      );
+    }
+  }
+
   /**
    * Readiness of the RemoteIngress outbound mail egress path (mail-tagged edges).
    */

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;
+  }
+}