@serve.zone/dcrouter 17.0.0 → 17.1.0

package/ts/email/reconcile-mail-dns-singleton.ts

@@ -0,0 +1,224 @@
+import { DnsRecordDoc } from '../db/documents/classes.dns-record.doc.js';
+import type {
+  IEmailDnsRecordIntent,
+  IEmailDomainOperationError,
+  TEmailDnsVerificationOutcome,
+} from '../../ts_interfaces/data/email-domain.js';
+import {
+  classifyMailTxtRecord,
+  type IMailDnsTxtPolicyResult,
+} from './mail-dns-txt-policy.js';
+
+export interface IMailDnsMutationClient {
+  createRecord(args: {
+    domainId: string;
+    name: string;
+    type: 'MX' | 'TXT' | 'A' | 'AAAA';
+    value: string;
+    ttl: number;
+    createdBy: string;
+    managedBy: string;
+    managedOwnerId: string;
+    managedRecordKey: string;
+  }): Promise<{ success: boolean; id?: string; message?: string }>;
+  updateRecord(args: {
+    id: string;
+    name?: string;
+    value?: string;
+    ttl?: number;
+  }): Promise<{ success: boolean; message?: string }>;
+  deleteRecord(id: string): Promise<{ success: boolean; message?: string }>;
+}
+
+export interface IReconcileMailDnsSingletonOptions {
+  intent: IEmailDnsRecordIntent;
+  rrset: DnsRecordDoc[];
+  dnsManager: IMailDnsMutationClient;
+  managedBy: string;
+  createdBy: string;
+  evaluate: (
+    intent: IEmailDnsRecordIntent,
+    values: string[],
+  ) => Promise<IMailDnsTxtPolicyResult>;
+}
+
+const outcomeError = (
+  intent: IEmailDnsRecordIntent,
+  outcome: Exclude<TEmailDnsVerificationOutcome, 'valid'>,
+  message: string,
+): IEmailDomainOperationError => {
+  let code: string;
+  if (outcome === 'missing') code = 'DNS_RECORD_MISSING';
+  else if (outcome === 'propagation') code = 'DNS_PROPAGATION_PENDING';
+  else if (outcome === 'duplicate') code = 'DNS_PUBLIC_SINGLETON_DUPLICATE';
+  else if (outcome === 'conflict') code = 'DNS_SINGLETON_CONFLICT';
+  else if (outcome === 'invalid') code = 'DNS_SINGLETON_INVALID';
+  else {
+    code = intent.value.trim().toLowerCase().startsWith('v=spf1')
+      ? 'DNS_SPF_AUTHORIZATION_LOOKUP_FAILED'
+      : 'DNS_LOOKUP_FAILED';
+  }
+  return {
+    code,
+    message,
+    recordKey: intent.key,
+    retryable: outcome === 'missing' || outcome === 'propagation' || outcome === 'lookup-error',
+  };
+};
+
+export function applyMailDnsVerificationResult(
+  intent: IEmailDnsRecordIntent,
+  result: IMailDnsTxtPolicyResult,
+  phase: 'reconcile' | 'verify',
+): void {
+  intent.verificationOutcome = result.outcome;
+  if (result.outcome === 'valid') {
+    intent.error = undefined;
+    intent.effectiveValue = result.effectiveValue;
+    intent.status = phase === 'verify' ? 'valid' : 'satisfied';
+    if (phase === 'verify') intent.validatedAt = new Date().toISOString();
+    return;
+  }
+  intent.status = result.outcome === 'conflict' || result.outcome === 'duplicate'
+    ? 'conflict'
+    : result.outcome === 'invalid'
+      ? 'failed'
+      : 'pending';
+  intent.error = outcomeError(
+    intent,
+    result.outcome,
+    result.reason || `${intent.type} ${intent.name} did not validate`,
+  );
+}
+
+function isSingletonAuthenticationIntent(intent: IEmailDnsRecordIntent): boolean {
+  if (intent.type !== 'TXT') return false;
+  const normalized = intent.value.trim().toLowerCase();
+  return normalized.startsWith('v=spf1')
+    || normalized.startsWith('v=dmarc1')
+    || normalized.startsWith('v=dkim1');
+}
+
+function exactIntentOwner(
+  record: DnsRecordDoc,
+  intent: IEmailDnsRecordIntent,
+  managedBy: string,
+): boolean {
+  return record.managedBy === managedBy
+    && record.managedOwnerId === intent.ownerId
+    && record.managedRecordKey === intent.key;
+}
+
+async function deleteOwnedRecords(
+  records: DnsRecordDoc[],
+  options: IReconcileMailDnsSingletonOptions,
+): Promise<boolean> {
+  for (const record of records) {
+    const result = await options.dnsManager.deleteRecord(record.id);
+    if (!result.success) {
+      options.intent.status = 'pending';
+      options.intent.verificationOutcome = 'duplicate';
+      options.intent.error = {
+        code: 'DNS_SINGLETON_DUPLICATE_CLEANUP_FAILED',
+        message: result.message || `Failed to remove duplicate ${options.intent.type} ${options.intent.name}`,
+        recordKey: options.intent.key,
+        retryable: true,
+      };
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Reconcile SPF, DMARC, and DKIM singleton TXT records without adopting or
+ * mutating operator policy. Returns false for non-singleton intents.
+ */
+export async function reconcileMailDnsSingleton(
+  options: IReconcileMailDnsSingletonOptions,
+): Promise<boolean> {
+  const { intent, rrset, managedBy } = options;
+  if (!isSingletonAuthenticationIntent(intent)) return false;
+
+  const exactOwned = rrset
+    .filter((record) => exactIntentOwner(record, intent, managedBy))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const otherManaged = rrset.filter((record) => (
+    record.managedBy === managedBy && !exactIntentOwner(record, intent, managedBy)
+  ));
+  const operator = rrset.filter((record) => record.managedBy !== managedBy);
+  const relevantOtherManaged = otherManaged.filter((record) => (
+    classifyMailTxtRecord(intent, record.value).relevant
+  ));
+  const relevantOperator = operator.filter((record) => (
+    classifyMailTxtRecord(intent, record.value).relevant
+  ));
+
+  if (relevantOperator.length > 0) {
+    if (!await deleteOwnedRecords(exactOwned, options)) return true;
+    if (relevantOtherManaged.length > 0) {
+      applyMailDnsVerificationResult(intent, {
+        outcome: 'conflict',
+        reason: `Another managed owner controls ${intent.type} ${intent.name}`,
+      }, 'reconcile');
+      return true;
+    }
+    const result = await options.evaluate(intent, relevantOperator.map((record) => record.value));
+    applyMailDnsVerificationResult(intent, result, 'reconcile');
+    if (result.outcome === 'valid') intent.satisfactionSource = 'operator';
+    return true;
+  }
+
+  if (relevantOtherManaged.length > 0) {
+    if (!await deleteOwnedRecords(exactOwned, options)) return true;
+    applyMailDnsVerificationResult(intent, {
+      outcome: 'conflict',
+      reason: `Another managed owner controls ${intent.type} ${intent.name}`,
+    }, 'reconcile');
+    return true;
+  }
+
+  const managed = exactOwned[0];
+  if (exactOwned.length > 1 && !await deleteOwnedRecords(exactOwned.slice(1), options)) {
+    return true;
+  }
+  if (managed) {
+    if (managed.value.trim() !== intent.value.trim() || managed.name !== intent.name) {
+      const result = await options.dnsManager.updateRecord({
+        id: managed.id,
+        name: intent.name,
+        value: intent.value,
+        ttl: intent.ttl,
+      });
+      if (!result.success) throw new Error(result.message || `Failed to update ${intent.key}`);
+    }
+    intent.providerRecordId = managed.providerRecordId;
+    intent.status = 'satisfied';
+    intent.satisfactionSource = 'managed';
+    intent.effectiveValue = intent.value;
+    intent.verificationOutcome = undefined;
+    intent.error = undefined;
+    intent.lastAttemptAt = new Date().toISOString();
+    return true;
+  }
+
+  const result = await options.dnsManager.createRecord({
+    domainId: intent.domainId,
+    name: intent.name,
+    type: intent.type,
+    value: intent.value,
+    ttl: intent.ttl,
+    createdBy: options.createdBy,
+    managedBy,
+    managedOwnerId: intent.ownerId,
+    managedRecordKey: intent.key,
+  });
+  if (!result.success) throw new Error(result.message || `Failed to create ${intent.key}`);
+  intent.status = 'satisfied';
+  intent.satisfactionSource = 'managed';
+  intent.effectiveValue = intent.value;
+  intent.verificationOutcome = undefined;
+  intent.error = undefined;
+  intent.lastAttemptAt = new Date().toISOString();
+  return true;
+}

package/ts/opsserver/classes.opsserver.ts

@@ -18,6 +18,7 @@ export class OpsServer {
 
   // Handler instances
   public adminHandler!: handlers.AdminHandler;
+  public realtimeHandler!: handlers.RealtimeHandler;
   private configHandler!: handlers.ConfigHandler;
   private logsHandler!: handlers.LogsHandler;
   private securityHandler!: handlers.SecurityHandler;
@@ -40,6 +41,8 @@ export class OpsServer {
   private acmeConfigHandler!: handlers.AcmeConfigHandler;
   private emailDomainHandler!: handlers.EmailDomainHandler;
   private gatewayClientHandler!: handlers.GatewayClientHandler;
+  private smtpRealtimeUnsubscribe?: () => void;
+  private emailQueueRealtimeUnsubscribe?: () => void;
 
   constructor(dcRouterRefArg: DcRouter) {
     this.dcRouterRef = dcRouterRefArg;
@@ -79,6 +82,7 @@ export class OpsServer {
     this.typedrouter.addTypedRouter(this.adminRouter);
 
     // Instantiate all handlers — they self-register with the appropriate router
+    this.realtimeHandler = new handlers.RealtimeHandler(this);
     this.configHandler = new handlers.ConfigHandler(this);
     this.logsHandler = new handlers.LogsHandler(this);
     this.securityHandler = new handlers.SecurityHandler(this);
@@ -101,7 +105,21 @@ export class OpsServer {
     this.acmeConfigHandler = new handlers.AcmeConfigHandler(this);
     this.emailDomainHandler = new handlers.EmailDomainHandler(this);
     this.gatewayClientHandler = new handlers.GatewayClientHandler(this);
+    this.smtpRealtimeUnsubscribe =
+      this.dcRouterRef.acceptedEmailSpool?.onSmtpTransactionPersisted?.((eventArg) => {
+        this.invalidateRealtime(['smtpAttempts', 'emailQueue'], {
+          changedIds: [eventArg.cachedEmailId],
+          reason: 'smtp-transaction-persisted',
+        });
+      });
 
+    this.emailQueueRealtimeUnsubscribe =
+      this.dcRouterRef.acceptedEmailSpool?.onEmailQueuePersisted?.((eventArg) => {
+        this.invalidateRealtime('emailQueue', {
+          changedIds: [eventArg.cachedEmailId],
+          reason: eventArg.reason,
+        });
+      });
     console.log('✅ OpsServer TypedRequest handlers initialized');
   }
 
@@ -114,10 +132,34 @@ export class OpsServer {
     );
   }
 
+  public invalidateRealtime(
+    resourcesArg:
+      | interfaces.requests.TOpsRealtimeResource
+      | interfaces.requests.TOpsRealtimeResource[],
+    optionsArg: { changedIds?: string[]; reason?: string } = {},
+  ): void {
+    this.realtimeHandler?.invalidate(resourcesArg, optionsArg);
+  }
+
+  public async getAuthenticatedRealtimeConnections(): Promise<
+    plugins.typedsocket.ISmartServeConnectionWrapper[]
+  > {
+    return this.realtimeHandler
+      ? await this.realtimeHandler.getAuthenticatedConnections()
+      : [];
+  }
+
   public async stop() {
     if (this.adminHandler) {
       await this.adminHandler.stop();
     }
+    this.smtpRealtimeUnsubscribe?.();
+    this.smtpRealtimeUnsubscribe = undefined;
+    this.emailQueueRealtimeUnsubscribe?.();
+    this.emailQueueRealtimeUnsubscribe = undefined;
+    if (this.realtimeHandler) {
+      this.realtimeHandler.cleanup();
+    }
     // Clean up log handler streams and push destination before stopping the server
     if (this.logsHandler) {
       this.logsHandler.cleanup();

package/ts/opsserver/handlers/certificate.handler.ts

@@ -67,7 +67,14 @@ export class CertificateHandler {
         'reprovisionCertificateDomain',
         async (dataArg) => {
           await this.requireAuth(dataArg, 'certificates:write');
-          return this.reprovisionCertificateDomain(dataArg.domain, dataArg.forceRenew);
+          const result = await this.reprovisionCertificateDomain(dataArg.domain, dataArg.forceRenew);
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.('certificates', {
+              changedIds: [dataArg.domain],
+              reason: 'certificate-reprovisioned',
+            });
+          }
+          return result;
         }
       )
     );
@@ -78,7 +85,14 @@ export class CertificateHandler {
         'deleteCertificate',
         async (dataArg) => {
           await this.requireAuth(dataArg, 'certificates:write');
-          return this.deleteCertificate(dataArg.domain);
+          const result = await this.deleteCertificate(dataArg.domain);
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.('certificates', {
+              changedIds: [dataArg.domain],
+              reason: 'certificate-deleted',
+            });
+          }
+          return result;
         }
       )
     );
@@ -100,7 +114,14 @@ export class CertificateHandler {
         'importCertificate',
         async (dataArg) => {
           await this.requireAuth(dataArg, 'certificates:write');
-          return this.importCertificate(dataArg.cert);
+          const result = await this.importCertificate(dataArg.cert);
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.('certificates', {
+              changedIds: [dataArg.cert.domainName],
+              reason: 'certificate-imported',
+            });
+          }
+          return result;
         }
       )
     );

package/ts/opsserver/handlers/config.handler.ts

@@ -35,9 +35,9 @@ export class ConfigHandler {
     const resolvedPaths = dcRouter.resolvedPaths;
 
     // --- System ---
-    const storageBackend: 'filesystem' | 'custom' | 'memory' = opts.dbConfig?.mongoDbUrl
-      ? 'custom'
-      : 'filesystem';
+    const storageBackend: 'smartdata-external' | 'smartdata-local' = opts.dbConfig?.mongoDbUrl
+      ? 'smartdata-external'
+      : 'smartdata-local';
 
     const proxyIps = opts.proxyIps || [];
 
@@ -48,7 +48,9 @@ export class ConfigHandler {
       proxyIps,
       uptime: Math.floor(process.uptime()),
       storageBackend,
-      storagePath: opts.dbConfig?.storagePath || resolvedPaths.defaultTsmDbPath,
+      storagePath: opts.dbConfig?.mongoDbUrl
+        ? null
+        : opts.dbConfig?.storagePath || resolvedPaths.defaultTsmDbPath,
     };
 
     // --- SmartProxy ---
@@ -161,7 +163,9 @@ export class ConfigHandler {
     const dbConfig = opts.dbConfig;
     const cache: interfaces.requests.IConfigData['cache'] = {
       enabled: dbConfig?.enabled !== false,
-      storagePath: dbConfig?.storagePath || resolvedPaths.defaultTsmDbPath,
+      storagePath: dbConfig?.mongoDbUrl
+        ? null
+        : dbConfig?.storagePath || resolvedPaths.defaultTsmDbPath,
       dbName: dbConfig?.dbName || 'dcrouter',
       defaultTTLDays: 30,
       cleanupIntervalHours: dbConfig?.cleanupIntervalHours || 1,

package/ts/opsserver/handlers/dns-provider.handler.ts

@@ -90,6 +90,10 @@ export class DnsProviderHandler {
             credentials: dataArg.credentials,
             createdBy: userId,
           });
+          this.opsServerRef.invalidateRealtime?.('dns', {
+            changedIds: [id],
+            reason: 'dns-provider-created',
+          });
           return { success: true, id };
         },
       ),
@@ -110,6 +114,12 @@ export class DnsProviderHandler {
             name: dataArg.name,
             credentials: dataArg.credentials,
           });
+          if (ok) {
+            this.opsServerRef.invalidateRealtime?.('dns', {
+              changedIds: [dataArg.id],
+              reason: 'dns-provider-updated',
+            });
+          }
           return ok ? { success: true } : { success: false, message: 'Provider not found' };
         },
       ),
@@ -126,7 +136,14 @@ export class DnsProviderHandler {
           }
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
-          return await dnsManager.deleteProvider(dataArg.id, dataArg.force ?? false);
+          const result = await dnsManager.deleteProvider(dataArg.id, dataArg.force ?? false);
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: [dataArg.id],
+              reason: 'dns-provider-deleted',
+            });
+          }
+          return result;
         },
       ),
     );

package/ts/opsserver/handlers/dns-record.handler.ts

@@ -62,7 +62,7 @@ export class DnsRecordHandler {
           const userId = await this.requireAuth(dataArg, 'dns-records:write');
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
-          return await dnsManager.createRecord({
+          const result = await dnsManager.createRecord({
             domainId: dataArg.domainId,
             name: dataArg.name,
             type: dataArg.type,
@@ -71,6 +71,13 @@ export class DnsRecordHandler {
             proxied: dataArg.proxied,
             createdBy: userId,
           });
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: result.id ? [result.id] : undefined,
+              reason: 'dns-record-created',
+            });
+          }
+          return result;
         },
       ),
     );
@@ -83,13 +90,20 @@ export class DnsRecordHandler {
           await this.requireAuth(dataArg, 'dns-records:write');
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
-          return await dnsManager.updateRecord({
+          const result = await dnsManager.updateRecord({
             id: dataArg.id,
             name: dataArg.name,
             value: dataArg.value,
             ttl: dataArg.ttl,
             proxied: dataArg.proxied,
           });
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: [dataArg.id],
+              reason: 'dns-record-updated',
+            });
+          }
+          return result;
         },
       ),
     );
@@ -102,7 +116,14 @@ export class DnsRecordHandler {
           await this.requireAuth(dataArg, 'dns-records:write');
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
-          return await dnsManager.deleteRecord(dataArg.id);
+          const result = await dnsManager.deleteRecord(dataArg.id);
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: [dataArg.id],
+              reason: 'dns-record-deleted',
+            });
+          }
+          return result;
         },
       ),
     );

package/ts/opsserver/handlers/domain.handler.ts

@@ -68,6 +68,10 @@ export class DomainHandler {
               description: dataArg.description,
               createdBy: userId,
             });
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: [id],
+              reason: 'domain-created',
+            });
             return { success: true, id };
           } catch (err: unknown) {
             return { success: false, message: (err as Error).message };
@@ -90,6 +94,10 @@ export class DomainHandler {
               domainNames: dataArg.domainNames,
               createdBy: userId,
             });
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: importedIds,
+              reason: 'domains-imported',
+            });
             return { success: true, importedIds };
           } catch (err: unknown) {
             return { success: false, message: (err as Error).message };
@@ -109,6 +117,12 @@ export class DomainHandler {
           const ok = await dnsManager.updateDomain(dataArg.id, {
             description: dataArg.description,
           });
+          if (ok) {
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: [dataArg.id],
+              reason: 'domain-updated',
+            });
+          }
           return ok ? { success: true } : { success: false, message: 'Domain not found' };
         },
       ),
@@ -123,6 +137,12 @@ export class DomainHandler {
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
           const ok = await dnsManager.deleteDomain(dataArg.id);
+          if (ok) {
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: [dataArg.id],
+              reason: 'domain-deleted',
+            });
+          }
           return ok ? { success: true } : { success: false, message: 'Domain not found' };
         },
       ),
@@ -136,7 +156,14 @@ export class DomainHandler {
           await this.requireAuth(dataArg, 'domains:write');
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
-          return await dnsManager.syncDomain(dataArg.id);
+          const result = await dnsManager.syncDomain(dataArg.id);
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: [dataArg.id],
+              reason: 'domain-synced',
+            });
+          }
+          return result;
         },
       ),
     );
@@ -149,12 +176,19 @@ export class DomainHandler {
           await this.requireAuth(dataArg, 'domains:write');
           const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
           if (!dnsManager) return { success: false, message: 'DnsManager not initialized' };
-          return await dnsManager.migrateDomain({
+          const result = await dnsManager.migrateDomain({
             id: dataArg.id,
             targetSource: dataArg.targetSource,
             targetProviderId: dataArg.targetProviderId,
             deleteExistingProviderRecords: dataArg.deleteExistingProviderRecords,
           });
+          if (result.success) {
+            this.opsServerRef.invalidateRealtime?.(['dns', 'emailDomains'], {
+              changedIds: [dataArg.id],
+              reason: 'domain-migrated',
+            });
+          }
+          return result;
         },
       ),
     );

package/ts/opsserver/handlers/email-domain.handler.ts

@@ -178,8 +178,6 @@ export class EmailDomainHandler {
               remoteIngress: dataArg.remoteIngress,
             });
             const result = normalizeEmailDomainActionResult(rawResult);
-            if (!result.success) return result;
-
             const resultRecord = isRecord(rawResult) ? rawResult : undefined;
             const domain = isRecord(resultRecord?.domain)
               ? resultRecord.domain as unknown as interfaces.data.IEmailDomain
@@ -210,7 +208,8 @@ export class EmailDomainHandler {
               rateLimits: dataArg.rateLimits,
               remoteIngress: dataArg.remoteIngress,
             });
-            return normalizeEmailDomainActionResult(rawResult);
+            const result = normalizeEmailDomainActionResult(rawResult);
+            return result;
           } catch (err: unknown) {
             return normalizeEmailDomainActionFailure(err, 'Failed to update email domain');
           }
@@ -229,7 +228,8 @@ export class EmailDomainHandler {
           }
           try {
             const rawResult: unknown = await this.manager.deleteEmailDomain(dataArg.id);
-            return normalizeEmailDomainActionResult(rawResult);
+            const result = normalizeEmailDomainActionResult(rawResult);
+            return result;
           } catch (err: unknown) {
             return normalizeEmailDomainActionFailure(err, 'Failed to delete email domain');
           }
@@ -249,7 +249,6 @@ export class EmailDomainHandler {
           try {
             const rawResult: unknown = await this.manager.validateDns(dataArg.id);
             const result = normalizeEmailDomainActionResult(rawResult);
-            if (!result.success) return result;
 
             const resultRecord = isRecord(rawResult) ? rawResult : undefined;
             const records = (

package/ts/opsserver/handlers/email-ops.handler.ts

@@ -134,7 +134,7 @@ export class EmailOpsHandler {
     if (this.isCachedEmailStoreAvailable()) {
       const cachedEmail = await CachedEmail.findById(emailId);
       if (cachedEmail) {
-        return this.mapCachedEmailToEmailDetail(cachedEmail);
+        return await this.mapCachedEmailToEmailDetail(cachedEmail);
       }
     }
     return null;
@@ -158,23 +158,34 @@ export class EmailOpsHandler {
       subject: doc.subject || '',
       timestamp: new Date(doc.acceptedAt || 0).toISOString(),
       messageId: doc.messageId || '',
-      size: this.formatSize(doc.rawContent?.length || 0),
+      size: this.formatSize(doc.rawContentSize || 0),
     };
   }
 
   /**
    * Map a CachedEmail row to catalog IEmailDetail format
    */
-  private mapCachedEmailToEmailDetail(doc: CachedEmail): interfaces.requests.IEmailDetail {
+  private async mapCachedEmailToEmailDetail(
+    doc: CachedEmail,
+  ): Promise<interfaces.requests.IEmailDetail> {
     const base = this.mapCachedEmailToEmail(doc);
-    const { headers, body } = this.parseRawEmail(doc.rawContent || '');
+    let rawContent = '';
+    try {
+      rawContent = (await this.opsServerRef.dcRouterRef.acceptedEmailSpool.readRawMessage(doc))
+        .toString('utf8');
+    } catch {
+      // Transaction history and delivery state remain available when a retained
+      // legacy row no longer has its raw payload.
+    }
+    const { headers, body } = this.parseRawEmail(rawContent);
     const session = this.parseCachedEmailSession(doc);
 
     return {
       ...base,
+      smtpTransactions: structuredClone(doc.smtpTransactions || []),
       toList: doc.to || [],
       cc: doc.cc || [],
-      smtpLog: [],
+      smtpLog: this.flattenSmtpTransactions(doc.smtpTransactions || []),
       connectionInfo: {
         sourceIp: session.remoteAddress || '',
         sourceHostname: session.clientHostname || '',
@@ -344,9 +355,10 @@ export class EmailOpsHandler {
 
     return {
       ...base,
+      smtpTransactions: structuredClone(item.smtpTransactions || []),
       toList,
       cc,
-      smtpLog: [],
+      smtpLog: this.flattenSmtpTransactions(item.smtpTransactions || []),
       connectionInfo: {
         sourceIp: '',
         sourceHostname: '',
@@ -393,6 +405,17 @@ export class EmailOpsHandler {
     }
   }
 
+  private flattenSmtpTransactions(
+    transactionsArg: interfaces.requests.ISmtpTransactionAttempt[],
+  ): interfaces.requests.ISmtpLogEntry[] {
+    return transactionsArg.flatMap((transaction) => transaction.transcript.map((entry) => ({
+      timestamp: new Date(entry.timestampMs).toISOString(),
+      direction: entry.direction,
+      command: entry.text,
+      responseCode: entry.responseCode,
+    })));
+  }
+
   /**
    * Format byte size to human-readable string
    */