@serve.zone/dcrouter 16.4.1 → 17.0.0

package/ts/email/classes.mail-edge-eligibility.ts

@@ -0,0 +1,205 @@
+import { REMOTE_INGRESS_MAIL_TAG } from '../../ts_interfaces/data/remoteingress.js';
+import type { IRemoteIngress } from '../../ts_interfaces/data/remoteingress.js';
+import type { EmailDomainDoc } from '../db/documents/classes.email-domain.doc.js';
+import type { DcRouter } from '../classes.dcrouter.js';
+
+export const MAIL_EGRESS_IDENTITY_MAX_AGE_MS = 45_000;
+
+export interface IMailEgressIdentity {
+  edgeId: string;
+  family: 4 | 6;
+  address: string;
+  heloHostname: string;
+  proof: 'sourceBound';
+  /** Edge-side time at which the configured source address was successfully bound. */
+  observedAt: number;
+  /** Hub-side heartbeat receipt time. */
+  hubReceivedAt: number;
+}
+
+export interface IMailEgressIdentitySnapshot {
+  supported: boolean;
+  reason?: string;
+  identities: IMailEgressIdentity[];
+}
+
+/** Boundary implemented against a released RemoteIngress identity-proof API. */
+export interface IEgressIdentitySource {
+  getSnapshot(): Promise<IMailEgressIdentitySnapshot>;
+}
+
+/**
+ * Reads the versioned RemoteIngress identity capability through TunnelManager.
+ * Older hubs do not expose `egressIdentityV1`; they remain explicitly
+ * unsupported instead of falling back to configured or peer addresses.
+ */
+export class ReleasedRemoteIngressEgressIdentitySource implements IEgressIdentitySource {
+  constructor(private dcRouterRef: DcRouter) {}
+
+  public async getSnapshot(): Promise<IMailEgressIdentitySnapshot> {
+    const status = await this.dcRouterRef.tunnelManager?.getAuthoritativeHubStatus();
+    const connectedEdges = status?.connectedEdges ?? [];
+    const capableEdges = connectedEdges.filter((edge) => (
+      Array.isArray(edge.capabilities) && edge.capabilities.includes('egressIdentityV1')
+    ));
+    if (capableEdges.length > 0) {
+      const identities: IMailEgressIdentity[] = [];
+      for (const edge of capableEdges) {
+        const report = edge.egressIdentity;
+        if (!report || report.proofMethod !== 'localSocketBind') continue;
+        for (const [family, observation] of [[4, report.ipv4], [6, report.ipv6]] as const) {
+          if (!observation || observation.stale === true) continue;
+          if (
+            typeof observation.address !== 'string'
+            || !Number.isFinite(observation.edgeObservedAtUnixMs)
+            || !Number.isFinite(observation.hubReceivedAtUnixMs)
+          ) continue;
+          const configured = this.dcRouterRef.remoteIngressManager?.getEdge(String(edge.edgeId));
+          const heloHostname = configured?.mailHostname?.trim();
+          if (!heloHostname) continue;
+          identities.push({
+            edgeId: String(edge.edgeId),
+            family,
+            address: observation.address,
+            heloHostname,
+            proof: 'sourceBound',
+            observedAt: observation.edgeObservedAtUnixMs,
+            hubReceivedAt: observation.hubReceivedAtUnixMs,
+          });
+        }
+      }
+      return { supported: true, identities };
+    }
+    return {
+      supported: false,
+      reason: 'RemoteIngress egress identity proof is unavailable until the capability release is consumed',
+      identities: [],
+    };
+  }
+}
+
+export interface IEligibleMailEdge {
+  edge: IRemoteIngress;
+  hostname: string;
+  identities: IMailEgressIdentity[];
+}
+
+export interface IMailEdgeEligibilityResult {
+  supported: boolean;
+  reason?: string;
+  edges: IEligibleMailEdge[];
+}
+
+/** Shared topology predicate used by DNS publication and outbound selection. */
+export class MailEdgeEligibility {
+  private lastUnscopedResult: IMailEdgeEligibilityResult = {
+    supported: false,
+    reason: 'mail edge eligibility has not been evaluated yet',
+    edges: [],
+  };
+
+  constructor(
+    private dcRouterRef: DcRouter,
+    private identitySource: IEgressIdentitySource,
+  ) {}
+
+  public async resolveForDomain(doc?: EmailDomainDoc): Promise<IMailEdgeEligibilityResult> {
+    const snapshot = await this.identitySource.getSnapshot();
+    if (!snapshot.supported) {
+      return this.recordUnscoped(doc, { supported: false, reason: snapshot.reason, edges: [] });
+    }
+
+    const manager = this.dcRouterRef.remoteIngressManager;
+    const tunnelManager = this.dcRouterRef.tunnelManager;
+    if (!manager || !tunnelManager) {
+      return this.recordUnscoped(doc, { supported: true, reason: 'RemoteIngress hub is not running', edges: [] });
+    }
+
+    const pin = doc?.remoteIngress?.edgeFilter || [];
+    const pinIds = pin.length > 0
+      ? new Set(manager.resolveEdgesByFilter(pin).map((edge) => edge.id))
+      : undefined;
+    const identitiesByEdge = new Map<string, IMailEgressIdentity[]>();
+    const now = Date.now();
+    for (const identity of snapshot.identities) {
+      if (identity.proof !== 'sourceBound') continue;
+      if (now - identity.observedAt > MAIL_EGRESS_IDENTITY_MAX_AGE_MS) continue;
+      if (now - identity.hubReceivedAt > MAIL_EGRESS_IDENTITY_MAX_AGE_MS) continue;
+      const entries = identitiesByEdge.get(identity.edgeId) || [];
+      entries.push(identity);
+      identitiesByEdge.set(identity.edgeId, entries);
+    }
+
+    const edges: IEligibleMailEdge[] = [];
+    for (const edge of manager.getAllEdges()) {
+      if (!edge.enabled || !edge.tags?.includes(REMOTE_INGRESS_MAIL_TAG)) continue;
+      // A domain pin narrows the mail-tagged pool; it never replaces the mail tag.
+      if (pinIds && !pinIds.has(edge.id)) continue;
+      if (!edge.egress?.enabled || !edge.egress.allowedPorts?.includes(25)) continue;
+      const status = tunnelManager.getEdgeStatus(edge.id);
+      if (!status?.connected || !status.lastHeartbeat) continue;
+      if (now - status.lastHeartbeat > MAIL_EGRESS_IDENTITY_MAX_AGE_MS) continue;
+      if (status.egressEnabled !== true || !status.capabilities?.includes('egressTcpV1')) continue;
+      const nativeQuic = status.transportMode === 'quic'
+        || (status.transportMode === 'quicWithFallback' && status.fallbackUsed === false);
+      if (!nativeQuic) continue;
+      const hostname = edge.mailHostname?.toLowerCase().replace(/\.$/, '');
+      if (!hostname) continue;
+
+      const identities = (identitiesByEdge.get(edge.id) || []).filter((identity) => {
+        if (identity.heloHostname.toLowerCase().replace(/\.$/, '') !== hostname) return false;
+        return identity.family === 4
+          ? Boolean(edge.publicIp && edge.publicIp === identity.address)
+          : Boolean(edge.publicIpV6 && edge.publicIpV6 === identity.address);
+      });
+      if (identities.length > 0) {
+        edges.push({ edge, hostname, identities });
+      }
+    }
+
+    edges.sort((left, right) => left.edge.id.localeCompare(right.edge.id));
+    return this.recordUnscoped(doc, {
+      supported: true,
+      ...(edges.length === 0 ? { reason: 'no live mail-tagged edge has a fresh source-bound identity' } : {}),
+      edges,
+    });
+  }
+
+  public getLastUnscopedResult(): IMailEdgeEligibilityResult {
+    return this.lastUnscopedResult;
+  }
+
+  private recordUnscoped(
+    doc: EmailDomainDoc | undefined,
+    result: IMailEdgeEligibilityResult,
+  ): IMailEdgeEligibilityResult {
+    if (!doc) this.lastUnscopedResult = result;
+    return result;
+  }
+
+  public async resolveActiveForDomain(doc: EmailDomainDoc): Promise<IMailEdgeEligibilityResult> {
+    const live = await this.resolveForDomain(doc);
+    const active = doc.reconciliation?.activeRevision;
+    if (!live.supported || !active) {
+      return {
+        supported: live.supported,
+        reason: live.reason || 'email domain has no validated active DNS revision',
+        edges: [],
+      };
+    }
+    const activeByEdge = new Map(active.edgeIdentities.map((identity) => [identity.edgeId, identity]));
+    const edges = live.edges.filter((candidate) => {
+      const activeIdentity = activeByEdge.get(candidate.edge.id);
+      if (!activeIdentity || activeIdentity.hostname !== candidate.hostname) return false;
+      return candidate.identities.length > 0 && candidate.identities.every((identity) => (
+        (identity.family === 4 && identity.address === activeIdentity.ipv4)
+        || (identity.family === 6 && identity.address === activeIdentity.ipv6)
+      ));
+    });
+    return {
+      supported: live.supported,
+      ...(edges.length === 0 ? { reason: 'no live edge is present in the validated active DNS revision' } : {}),
+      edges,
+    };
+  }
+}

package/ts/email/classes.mail-egress-coordinator.ts

@@ -4,9 +4,9 @@ import type {
 } from '@push.rocks/smartmta';
 import * as plugins from '../plugins.js';
 import { logger } from '../logger.js';
-import { REMOTE_INGRESS_MAIL_TAG } from '../../ts_interfaces/data/remoteingress.js';
 import type { IEmailOutboundEgressStatus, TEmailOutboundMode } from '../../ts_interfaces/data/email-settings.js';
 import type { DcRouter } from '../classes.dcrouter.js';
+import type { MailEdgeEligibility } from './classes.mail-edge-eligibility.js';
 
 /**
  * Routes outbound SMTP deliveries over RemoteIngress edges: resolves the
@@ -17,7 +17,10 @@ import type { DcRouter } from '../classes.dcrouter.js';
 export class MailEgressCoordinator {
   private dnsClient?: plugins.smartdns.dnsClientMod.Smartdns;
 
-  constructor(private dcRouterRef: DcRouter) {}
+  constructor(
+    private dcRouterRef: DcRouter,
+    private edgeEligibility: MailEdgeEligibility,
+  ) {}
 
   /**
    * smartmta connectionProxyProvider. Wired unconditionally so the outbound
@@ -30,6 +33,11 @@ export class MailEgressCoordinator {
   ): Promise<IOutboundConnectionProxy | null> {
     const mode = this.resolveOutboundModeStrict();
     if (mode === 'direct') {
+      if (context.senderDomain && await this.dcRouterRef.emailDomainManager?.getByDomain(context.senderDomain)) {
+        throw new Error(
+          `Managed sender domain ${context.senderDomain} has no validated direct-egress identity policy; refusing direct hub delivery`,
+        );
+      }
       return null;
     }
     return await this.createRemoteIngressConnectionProxy(context);
@@ -54,11 +62,14 @@ export class MailEgressCoordinator {
    * Readiness of the RemoteIngress outbound mail egress path (mail-tagged edges).
    */
   public getOutboundEgressStatus(): IEmailOutboundEgressStatus {
-    const tunnelManager = this.dcRouterRef.tunnelManager;
-    if (!tunnelManager) {
-      return { ready: false, eligibleEdgeCount: 0, reason: 'RemoteIngress hub is not running' };
-    }
-    return tunnelManager.getEgressReadiness([REMOTE_INGRESS_MAIL_TAG]);
+    const eligibility = this.edgeEligibility.getLastUnscopedResult();
+    return {
+      ready: eligibility.supported && eligibility.edges.length > 0,
+      eligibleEdgeCount: eligibility.edges.length,
+      ...(eligibility.edges.length === 0
+        ? { reason: eligibility.reason || 'no validated RemoteIngress mail edge is available' }
+        : {}),
+    };
   }
 
   /**
@@ -89,15 +100,19 @@ export class MailEgressCoordinator {
 
     await this.assertTargetIsNotOwnMailEdge(context);
 
-    // Per-domain pinning: a sender domain with a configured edgeFilter uses only
-    // matching edges; everything else uses the mail-tagged edge pool.
-    let edgeFilter: string[] = [REMOTE_INGRESS_MAIL_TAG];
-    if (context.senderDomain && this.dcRouterRef.emailDomainManager) {
-      const domain = await this.dcRouterRef.emailDomainManager.getByDomain(context.senderDomain);
-      if (domain?.remoteIngress?.edgeFilter?.length) {
-        edgeFilter = domain.remoteIngress.edgeFilter;
-      }
+    const managedDoc = context.senderDomain
+      ? await (await import('../db/documents/classes.email-domain.doc.js')).EmailDomainDoc.findByDomain(context.senderDomain)
+      : null;
+    const eligible = managedDoc
+      ? await this.edgeEligibility.resolveActiveForDomain(managedDoc)
+      : await this.edgeEligibility.resolveForDomain();
+    if (!eligible.supported || eligible.edges.length === 0) {
+      throw new Error(
+        `Outbound SMTP is not eligible${context.senderDomain ? ` for ${context.senderDomain}` : ''}: ${eligible.reason || 'no validated mail edge'}`,
+      );
     }
+    const eligibleById = new Map(eligible.edges.map((candidate) => [candidate.edge.id, candidate]));
+    const edgeFilter = [...eligibleById.keys()];
 
     const connectionTimeoutMs = this.dcRouterRef.options.emailConfig?.outbound?.connectionTimeout ?? 30_000;
     const proxy = await tunnelManager.startEgressTcpProxy({
@@ -108,12 +123,17 @@ export class MailEgressCoordinator {
       acceptTimeoutMs: connectionTimeoutMs,
       edgeFilter,
     });
+    const selected = eligibleById.get(proxy.edgeId);
+    if (!selected) {
+      await tunnelManager.stopEgressTcpProxy(proxy.proxyId).catch(() => undefined);
+      throw new Error(`RemoteIngress selected edge ${proxy.edgeId} outside the validated mail pool`);
+    }
     let closed = false;
     return {
       connectHost: proxy.listenHost,
       connectPort: proxy.listenPort,
       poolKey: `remoteIngress:${proxy.edgeId}:${context.host}:${context.port}`,
-      ehloHostname: this.dcRouterRef.remoteIngressManager?.getEdge(proxy.edgeId)?.mailHostname,
+      ehloHostname: selected.hostname,
       close: async () => {
         if (closed) {
           return;
@@ -138,11 +158,11 @@ export class MailEgressCoordinator {
    * allowed to become an availability hazard.
    */
   private async assertTargetIsNotOwnMailEdge(context: IOutboundConnectionProxyContext): Promise<void> {
-    const edgeIps = new Set(
-      (this.dcRouterRef.remoteIngressManager?.getAllEdges?.() || [])
-        .map((edge) => edge.publicIp)
-        .filter((ip): ip is string => Boolean(ip)),
-    );
+    const edgeIps = new Set<string>();
+    for (const edge of this.dcRouterRef.remoteIngressManager?.getAllEdges?.() || []) {
+      if (edge.publicIp) edgeIps.add(edge.publicIp);
+      if (edge.publicIpV6) edgeIps.add(edge.publicIpV6);
+    }
     if (edgeIps.size === 0) {
       return;
     }
@@ -155,8 +175,11 @@ export class MailEgressCoordinator {
         if (!this.dnsClient) {
           this.dnsClient = new plugins.smartdns.dnsClientMod.Smartdns({});
         }
-        const records = await this.dnsClient.getRecordsA(context.host);
-        targetIps = (records || []).map((record) => record.value);
+        const [aRecords, aaaaRecords] = await Promise.all([
+          this.dnsClient.getRecordsA(context.host),
+          this.dnsClient.getRecordsAAAA(context.host),
+        ]);
+        targetIps = [...(aRecords || []), ...(aaaaRecords || [])].map((record) => record.value);
       } catch {
         return;
       }

package/ts/email/classes.smartmta-blob-storage-manager.ts

@@ -0,0 +1,138 @@
+import * as plugins from '../plugins.js';
+import type { IBlobStorageManager } from '@push.rocks/smartmta';
+
+const SMARTMTA_BLOB_NAMESPACES = [
+  '/email/queue/',
+  '/email/attachments/',
+] as const;
+const DEFAULT_OBJECT_PREFIX = 'dcrouter/smartmta/';
+const MAX_STORAGE_KEY_BYTES = 1024;
+
+type TBlobBucket = Pick<
+  plugins.smartbucket.Bucket,
+  'fastExists' | 'fastGet' | 'fastPut' | 'fastRemove' | 'listAllObjects'
+>;
+
+export interface ISmartMtaBlobStorageConfig {
+  storageDescriptor: plugins.tsclass.storage.IStorageDescriptor;
+  bucketName: string;
+  objectPrefix?: string;
+  createBucketIfMissing?: boolean;
+}
+
+function normalizeObjectPrefix(prefixArg = DEFAULT_OBJECT_PREFIX): string {
+  const prefix = prefixArg.trim().replace(/^\/+|\/+$/g, '');
+  if (!prefix || prefix.includes('\\') || prefix.includes('\0')) {
+    throw new Error('SmartMTA blob objectPrefix must be a non-empty object-key prefix');
+  }
+  const segments = prefix.split('/');
+  if (segments.some((segment) => !segment || segment === '.' || segment === '..')) {
+    throw new Error('SmartMTA blob objectPrefix contains an invalid path segment');
+  }
+  return `${prefix}/`;
+}
+
+function normalizeBlobKey(keyArg: string, allowNamespaceRoot = false): string {
+  if (
+    typeof keyArg !== 'string' ||
+    !keyArg.startsWith('/') ||
+    keyArg.includes('\\') ||
+    keyArg.includes('\0') ||
+    Buffer.byteLength(keyArg, 'utf8') > MAX_STORAGE_KEY_BYTES
+  ) {
+    throw new Error('Invalid SmartMTA blob storage key');
+  }
+  const namespace = SMARTMTA_BLOB_NAMESPACES.find((candidate) => keyArg.startsWith(candidate));
+  if (!namespace) {
+    throw new Error(`Unsupported SmartMTA blob storage namespace: ${keyArg}`);
+  }
+  const remainder = keyArg.slice(namespace.length);
+  if (!allowNamespaceRoot && !remainder) {
+    throw new Error('SmartMTA blob storage key must identify an object');
+  }
+  if (remainder && remainder.split('/').some((segment) => !segment || segment === '.' || segment === '..')) {
+    throw new Error('SmartMTA blob storage key contains an invalid path segment');
+  }
+  return keyArg;
+}
+
+/**
+ * SmartMTA blob persistence backed by a SmartBucket bucket.
+ *
+ * The adapter accepts only SmartMTA queue and attachment namespaces and never
+ * maps object keys to local filesystem paths.
+ */
+export class SmartMtaBlobStorageManager implements IBlobStorageManager {
+  private readonly objectPrefix: string;
+
+  public constructor(
+    private readonly bucketRef: TBlobBucket,
+    objectPrefix = DEFAULT_OBJECT_PREFIX,
+  ) {
+    this.objectPrefix = normalizeObjectPrefix(objectPrefix);
+  }
+
+  public static async create(
+    configArg: ISmartMtaBlobStorageConfig,
+  ): Promise<SmartMtaBlobStorageManager> {
+    const bucketName = configArg.bucketName?.trim();
+    if (!bucketName) {
+      throw new Error('SmartMTA blob storage requires a bucketName');
+    }
+
+    const smartBucket = new plugins.smartbucket.SmartBucket(configArg.storageDescriptor);
+    let bucket: plugins.smartbucket.Bucket;
+    if (configArg.createBucketIfMissing) {
+      bucket = await smartBucket.bucketExists(bucketName)
+        ? await smartBucket.getBucketByName(bucketName)
+        : await smartBucket.createBucket(bucketName);
+    } else {
+      bucket = await smartBucket.getBucketByName(bucketName);
+    }
+
+    return new SmartMtaBlobStorageManager(bucket, configArg.objectPrefix);
+  }
+
+  public async get(keyArg: string): Promise<Buffer | null> {
+    const objectKey = this.toObjectKey(normalizeBlobKey(keyArg));
+    if (!(await this.bucketRef.fastExists({ path: objectKey }))) {
+      return null;
+    }
+    return Buffer.from(await this.bucketRef.fastGet({ path: objectKey }));
+  }
+
+  public async set(keyArg: string, valueArg: Buffer): Promise<void> {
+    if (!Buffer.isBuffer(valueArg)) {
+      throw new TypeError('SmartMTA blob storage values must be Buffers');
+    }
+    const objectKey = this.toObjectKey(normalizeBlobKey(keyArg));
+    await this.bucketRef.fastPut({
+      path: objectKey,
+      contents: Buffer.from(valueArg),
+      overwrite: true,
+    });
+  }
+
+  public async list(prefixArg: string): Promise<string[]> {
+    const prefix = normalizeBlobKey(prefixArg, true);
+    const objectPrefix = this.toObjectKey(prefix);
+    const keys: string[] = [];
+    for await (const objectKey of this.bucketRef.listAllObjects(objectPrefix)) {
+      if (!objectKey.startsWith(this.objectPrefix)) {
+        throw new Error(`SmartBucket returned an object outside the configured prefix: ${objectKey}`);
+      }
+      const key = `/${objectKey.slice(this.objectPrefix.length)}`;
+      keys.push(normalizeBlobKey(key));
+    }
+    return keys.sort();
+  }
+
+  public async delete(keyArg: string): Promise<void> {
+    const objectKey = this.toObjectKey(normalizeBlobKey(keyArg));
+    await this.bucketRef.fastRemove({ path: objectKey });
+  }
+
+  private toObjectKey(keyArg: string): string {
+    return `${this.objectPrefix}${keyArg.slice(1)}`;
+  }
+}

package/ts/email/classes.smartmta-storage-manager.ts

@@ -1,108 +1,111 @@
 import * as plugins from '../plugins.js';
-import type { IStorageManagerLike } from '@push.rocks/smartmta';
+import type { IStorageManager } from '@push.rocks/smartmta';
+import {
+  getSmartMtaTextNamespace,
+  hashSmartMtaStorageKey,
+  normalizeSmartMtaStorageKey,
+  validateSmartMtaTextValue,
+} from './smartmta-storage-policy.js';
 
-export class SmartMtaStorageManager implements IStorageManagerLike {
-  private readonly resolvedRootDir: string;
+interface ISmartMtaStorageDocument {
+  _id: string;
+  id: string;
+  key: string;
+  value: string;
+  createdAt: string;
+  updatedAt: string;
+}
 
-  constructor(private rootDir: string) {
-    this.resolvedRootDir = plugins.path.resolve(rootDir);
-    plugins.fsUtils.ensureDirSync(this.resolvedRootDir);
-  }
+export class SmartMtaStorageManager implements IStorageManager {
+  private readonly collection: any;
 
-  private normalizeKey(key: string): string {
-    return key.replace(/^\/+/, '').replace(/\\/g, '/');
+  constructor(smartdataDb: plugins.smartdata.SmartdataDb) {
+    this.collection = smartdataDb.mongoDb.collection('SmartMtaStorageDoc');
   }
 
-  private resolvePathForKey(key: string): string {
-    const normalizedKey = this.normalizeKey(key);
-    const resolvedPath = plugins.path.resolve(this.resolvedRootDir, normalizedKey);
+  private validateDocument(
+    document: ISmartMtaStorageDocument,
+    expectedKey?: string,
+  ): ISmartMtaStorageDocument {
+    const normalizedKey = normalizeSmartMtaStorageKey(document.key);
+    const expectedId = hashSmartMtaStorageKey(normalizedKey);
     if (
-      resolvedPath !== this.resolvedRootDir
-      && !resolvedPath.startsWith(`${this.resolvedRootDir}${plugins.path.sep}`)
+      document._id !== expectedId
+      || document.id !== expectedId
+      || document.key !== normalizedKey
+      || (expectedKey && document.key !== expectedKey)
+      || typeof document.value !== 'string'
     ) {
-      throw new Error(`Storage key escapes root directory: ${key}`);
+      throw new Error(`Corrupt SmartMTA storage document: ${document._id}`);
     }
-    return resolvedPath;
-  }
-
-  private toStorageKey(filePath: string): string {
-    const relativePath = plugins.path.relative(this.resolvedRootDir, filePath).split(plugins.path.sep).join('/');
-    return `/${relativePath}`;
+    validateSmartMtaTextValue(document.key, document.value);
+    return document;
   }
 
   public async get(key: string): Promise<string | null> {
-    const filePath = this.resolvePathForKey(key);
-    try {
-      return await plugins.fs.promises.readFile(filePath, 'utf8');
-    } catch (error: unknown) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-        return null;
-      }
-      throw error;
-    }
+    const normalizedKey = normalizeSmartMtaStorageKey(key);
+    getSmartMtaTextNamespace(normalizedKey);
+    const id = hashSmartMtaStorageKey(normalizedKey);
+    const document = await this.collection.findOne({ _id: id });
+    return document ? this.validateDocument(document, normalizedKey).value : null;
   }
 
   public async set(key: string, value: string): Promise<void> {
-    const filePath = this.resolvePathForKey(key);
-    await plugins.fs.promises.mkdir(plugins.path.dirname(filePath), { recursive: true });
-    await plugins.fs.promises.writeFile(filePath, value, 'utf8');
-  }
+    const normalizedKey = normalizeSmartMtaStorageKey(key);
+    validateSmartMtaTextValue(normalizedKey, value);
+    const id = hashSmartMtaStorageKey(normalizedKey);
+    const existing = await this.collection.findOne({ _id: id });
+    if (existing) {
+      this.validateDocument(existing, normalizedKey);
+    }
 
-  public async list(prefix: string): Promise<string[]> {
-    const prefixPath = this.resolvePathForKey(prefix);
-    try {
-      const stat = await plugins.fs.promises.stat(prefixPath);
-      if (stat.isFile()) {
-        return [this.toStorageKey(prefixPath)];
-      }
-    } catch (error: unknown) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-        return [];
-      }
-      throw error;
+    const now = new Date().toISOString();
+    await this.collection.updateOne(
+      { _id: id },
+      {
+        $set: {
+          id,
+          key: normalizedKey,
+          value,
+          updatedAt: now,
+        },
+        $setOnInsert: {
+          createdAt: now,
+        },
+      },
+      { upsert: true },
+    );
+
+    const stored = await this.collection.findOne({ _id: id });
+    if (!stored || this.validateDocument(stored, normalizedKey).value !== value) {
+      throw new Error(`SmartMTA storage write verification failed: ${normalizedKey}`);
     }
+  }
 
-    const results: string[] = [];
-    const walk = async (currentPath: string): Promise<void> => {
-      const entries = await plugins.fs.promises.readdir(currentPath, { withFileTypes: true });
-      for (const entry of entries) {
-        const entryPath = plugins.path.join(currentPath, entry.name);
-        if (entry.isDirectory()) {
-          await walk(entryPath);
-        } else if (entry.isFile()) {
-          results.push(this.toStorageKey(entryPath));
-        }
-      }
-    };
+  public async list(prefix: string): Promise<string[]> {
+    const normalizedPrefix = normalizeSmartMtaStorageKey(prefix);
+    getSmartMtaTextNamespace(normalizedPrefix);
+    const documents = await this.collection.find({
+      key: {
+        $gte: normalizedPrefix,
+        $lt: `${normalizedPrefix}\uffff`,
+      },
+    }).toArray();
 
-    await walk(prefixPath);
-    return results.sort();
+    return documents
+      .map((document: ISmartMtaStorageDocument) => this.validateDocument(document).key)
+      .filter((key: string) => key.startsWith(normalizedPrefix))
+      .sort();
   }
 
   public async delete(key: string): Promise<void> {
-    const targetPath = this.resolvePathForKey(key);
-    try {
-      const stat = await plugins.fs.promises.stat(targetPath);
-      if (stat.isDirectory()) {
-        await plugins.fs.promises.rm(targetPath, { recursive: true, force: true });
-      } else {
-        await plugins.fs.promises.unlink(targetPath);
-      }
-    } catch (error: unknown) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-        return;
-      }
-      throw error;
-    }
-
-    let currentDir = plugins.path.dirname(targetPath);
-    while (currentDir.startsWith(this.resolvedRootDir) && currentDir !== this.resolvedRootDir) {
-      const entries = await plugins.fs.promises.readdir(currentDir);
-      if (entries.length > 0) {
-        break;
-      }
-      await plugins.fs.promises.rmdir(currentDir);
-      currentDir = plugins.path.dirname(currentDir);
+    const normalizedKey = normalizeSmartMtaStorageKey(key);
+    getSmartMtaTextNamespace(normalizedKey);
+    const id = hashSmartMtaStorageKey(normalizedKey);
+    const existing = await this.collection.findOne({ _id: id });
+    if (existing) {
+      this.validateDocument(existing, normalizedKey);
+      await this.collection.deleteOne({ _id: id });
     }
   }
 }