@serve.zone/dcrouter 15.10.0 → 15.11.0

package/ts/email/classes.workapp-mail-manager.ts

@@ -7,7 +7,7 @@ import type {
 } from '@push.rocks/smartmta';
 import type { Buffer } from 'node:buffer';
 import * as plugins from '../plugins.js';
-import type { CachedEmail } from '../db/index.js';
+import { CachedEmail } from '../db/index.js';
 import type { DcRouter } from '../classes.dcrouter.js';
 import type * as interfaces from '../../ts_interfaces/index.js';
 
@@ -30,8 +30,38 @@ type TMailAddressBindingSyncResponse = plugins.servezoneInterfaces.requests.mail
 type TMailAddressBindingDeleteResponse = plugins.servezoneInterfaces.requests.mail.IReq_DeleteMailAddressBinding['response'];
 type TMailCredentialRotateResponse = plugins.servezoneInterfaces.requests.mail.IReq_RotateMailCredential['response'];
 type TMailEnqueueResponse = plugins.servezoneInterfaces.requests.mail.IReq_EnqueueMail['response'];
+type TMailDeliveryStatusResponse = plugins.servezoneInterfaces.requests.mail.IReq_GetMailDeliveryStatus['response'];
 type TMailEndpointRegistrationResponse = plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint['response'];
 type TWorkAppMailBinding = plugins.servezoneInterfaces.data.IWorkAppMailBinding;
+type TCachedEmailWithTimestamps = CachedEmail & {
+  createdAt?: Date | number | string;
+  updatedAt?: Date | number | string;
+};
+type TSmartMtaStatusQueueItem = {
+  status?: 'pending' | 'processing' | 'queued' | 'delivered' | 'failed' | 'deferred';
+  attempts?: number;
+  nextAttempt?: Date;
+  lastError?: string;
+  processingResult?: {
+    headers?: Record<string, string>;
+    email?: {
+      headers?: Record<string, string>;
+    };
+  };
+};
+type TCachedEmailRouteData = {
+  session?: {
+    user?: {
+      username?: string;
+    };
+  };
+  smartMta?: {
+    status?: 'queued' | 'deferred' | 'delivered' | 'failed';
+    nextAttempt?: string;
+    lastError?: string;
+    updatedAt?: string;
+  };
+};
 
 interface IStoredWorkAppMailIdentity {
   id: string;
@@ -370,6 +400,31 @@ export class WorkAppMailManager {
     }
   }
 
+  public async getMailDeliveryStatus(
+    spoolItemIdArg: string,
+  ): Promise<TMailDeliveryStatusResponse> {
+    const cachedEmail = await this.getCachedEmailById(spoolItemIdArg);
+    if (!cachedEmail) {
+      return { attempts: [] };
+    }
+    return await this.buildMailDeliveryStatus(cachedEmail);
+  }
+
+  public async getMailDeliveryStatusForCredential(
+    authArg: plugins.servezoneInterfaces.requests.mail.IMailSubmissionRequestAuth,
+    spoolItemIdArg: string,
+  ): Promise<TMailDeliveryStatusResponse> {
+    const identity = await this.authenticateMailCredential(authArg);
+    const cachedEmail = await this.getCachedEmailById(spoolItemIdArg);
+    if (!cachedEmail) {
+      return { attempts: [] };
+    }
+    if (!this.cachedEmailBelongsToIdentity(cachedEmail, identity)) {
+      throw new Error('Mail credential is not authorized for this spool item');
+    }
+    return await this.buildMailDeliveryStatus(cachedEmail);
+  }
+
   public async registerServiceMailEndpoint(
     authArg: plugins.servezoneInterfaces.requests.mail.IMailSubmissionRequestAuth,
     peerArg: { tags?: Set<string> },
@@ -889,6 +944,144 @@ export class WorkAppMailManager {
     return this.normalizeInboundTarget(identity.inboundTarget || this.toMailInboundTarget(identity.inbound));
   }
 
+  private async getCachedEmailById(spoolItemIdArg: string): Promise<CachedEmail | null> {
+    const spoolItemId = String(spoolItemIdArg || '').trim();
+    if (!spoolItemId || !this.dcRouterRef.dcRouterDb?.isReady()) {
+      return null;
+    }
+    return await CachedEmail.findById(spoolItemId);
+  }
+
+  private async buildMailDeliveryStatus(
+    cachedEmailArg: CachedEmail,
+  ): Promise<TMailDeliveryStatusResponse> {
+    const queueItem = this.findQueueItemForCachedEmail(cachedEmailArg.id);
+    const routeData = this.parseCachedEmailRouteData(cachedEmailArg);
+    const owner = await this.resolveCachedEmailOwner(cachedEmailArg);
+    const status = this.mapMailSpoolStatus(cachedEmailArg, queueItem);
+    const cachedEmailWithTimestamps = cachedEmailArg as TCachedEmailWithTimestamps;
+    const createdAt = this.toTimestamp(cachedEmailWithTimestamps.createdAt) || Date.now();
+    const updatedAt = this.toTimestamp(cachedEmailWithTimestamps.updatedAt) || createdAt;
+    const nextAttemptAt = status === 'delivered' || status === 'failed'
+      ? undefined
+      : this.toTimestamp(queueItem?.nextAttempt) || this.toTimestamp(routeData.smartMta?.nextAttempt) || this.toTimestamp(cachedEmailArg.nextAttempt);
+    const lastError = queueItem?.lastError || cachedEmailArg.lastError || routeData.smartMta?.lastError || undefined;
+
+    return {
+      spoolItem: {
+        id: cachedEmailArg.id,
+        owner,
+        direction: this.getCachedEmailSessionUsername(cachedEmailArg) ? 'outbound' : 'inbound',
+        status,
+        envelope: {
+          mailFrom: cachedEmailArg.from,
+          rcptTo: cachedEmailArg.to || [],
+        },
+        messageId: cachedEmailArg.messageId,
+        subject: cachedEmailArg.subject,
+        target: this.getCachedEmailSessionUsername(cachedEmailArg)
+          ? { type: 'mtaRelay', label: 'SmartMTA outbound relay' }
+          : undefined,
+        attempts: Math.max(cachedEmailArg.attempts || 0, queueItem?.attempts || 0),
+        nextAttemptAt,
+        lastError,
+        createdAt,
+        updatedAt,
+      },
+      attempts: [],
+    };
+  }
+
+  private findQueueItemForCachedEmail(cachedEmailIdArg: string): TSmartMtaStatusQueueItem | undefined {
+    const emailServer = this.dcRouterRef.emailServer;
+    if (!emailServer?.getQueueItems) {
+      return undefined;
+    }
+    return (emailServer.getQueueItems() as TSmartMtaStatusQueueItem[]).find((itemArg) => {
+      return this.getQueueItemCachedEmailId(itemArg) === cachedEmailIdArg;
+    });
+  }
+
+  private getQueueItemCachedEmailId(itemArg: TSmartMtaStatusQueueItem): string | undefined {
+    const headerName = 'x-dcrouter-cached-email-id';
+    const headers = itemArg?.processingResult?.headers || itemArg?.processingResult?.email?.headers;
+    if (!headers) {
+      return undefined;
+    }
+    const matchingHeaderName = Object.keys(headers).find((keyArg) => keyArg.toLowerCase() === headerName);
+    return matchingHeaderName ? headers[matchingHeaderName] : undefined;
+  }
+
+  private async resolveCachedEmailOwner(
+    cachedEmailArg: CachedEmail,
+  ): Promise<plugins.servezoneInterfaces.data.IMailResourceOwner | undefined> {
+    const username = this.getCachedEmailSessionUsername(cachedEmailArg);
+    if (!username) {
+      return undefined;
+    }
+    const identity = (await this.readStoredIdentities()).find((identityArg) => identityArg.smtp.username === username);
+    return identity ? this.toMailOwner(identity.ownership) : undefined;
+  }
+
+  private cachedEmailBelongsToIdentity(
+    cachedEmailArg: CachedEmail,
+    identityArg: IStoredWorkAppMailIdentity,
+  ): boolean {
+    return this.normalizeAddress(cachedEmailArg.from || '') === identityArg.address
+      && this.getCachedEmailSessionUsername(cachedEmailArg) === identityArg.smtp.username;
+  }
+
+  private getCachedEmailSessionUsername(cachedEmailArg: CachedEmail): string | undefined {
+    const routeData = this.parseCachedEmailRouteData(cachedEmailArg);
+    const username = routeData.session?.user?.username;
+    return typeof username === 'string' && username ? username : undefined;
+  }
+
+  private parseCachedEmailRouteData(cachedEmailArg: CachedEmail): TCachedEmailRouteData {
+    try {
+      return cachedEmailArg.routeData ? JSON.parse(cachedEmailArg.routeData) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  private mapMailSpoolStatus(
+    cachedEmailArg: CachedEmail,
+    queueItemArg?: TSmartMtaStatusQueueItem,
+  ): plugins.servezoneInterfaces.data.TMailSpoolStatus {
+    if (!queueItemArg && cachedEmailArg.status === 'pending') {
+      return 'accepted';
+    }
+    const status = queueItemArg?.status || cachedEmailArg.status;
+    switch (status) {
+      case 'processing':
+        return 'delivering';
+      case 'delivered':
+        return 'delivered';
+      case 'deferred':
+        return 'deferred';
+      case 'failed':
+        return 'failed';
+      case 'pending':
+      case 'queued':
+      default:
+        return 'queued';
+    }
+  }
+
+  private toTimestamp(valueArg: unknown): number | undefined {
+    if (!valueArg) {
+      return undefined;
+    }
+    if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
+      return valueArg;
+    }
+    const timestamp = valueArg instanceof Date
+      ? valueArg.getTime()
+      : new Date(String(valueArg)).getTime();
+    return Number.isFinite(timestamp) ? timestamp : undefined;
+  }
+
   private async authenticateMailCredential(
     authArg: plugins.servezoneInterfaces.requests.mail.IMailSubmissionRequestAuth,
     addressArg?: string,

package/ts/opsserver/handlers/gatewayclient.handler.ts

@@ -350,6 +350,34 @@ export class GatewayClientHandler {
       ),
     );
 
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.mail.IReq_GetMailDeliveryStatus>(
+        'getMailDeliveryStatus',
+        async (dataArg) => {
+          const manager = this.opsServerRef.dcRouterRef.workAppMailManager;
+          if (!manager) {
+            return { attempts: [] };
+          }
+
+          const authData = dataArg.auth || {};
+          const mailSubmissionAuth = authData as plugins.servezoneInterfaces.requests.mail.IMailSubmissionRequestAuth;
+          if (mailSubmissionAuth.credentialId || mailSubmissionAuth.credentialSecret) {
+            return await manager.getMailDeliveryStatusForCredential(
+              mailSubmissionAuth,
+              dataArg.spoolItemId,
+            );
+          }
+
+          const auth = await this.requireAuth(authData, 'gateway-clients:read');
+          const status = await manager.getMailDeliveryStatus(dataArg.spoolItemId);
+          if (!this.isMailDeliveryStatusAllowed(auth, status)) {
+            return { attempts: [] };
+          }
+          return status;
+        },
+      ),
+    );
+
     this.typedrouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.mail.IReq_RegisterServiceMailEndpoint>(
         'registerServiceMailEndpoint',
@@ -609,6 +637,22 @@ export class GatewayClientHandler {
     });
   }
 
+  private isMailDeliveryStatusAllowed(
+    auth: TAuthContext,
+    statusArg: plugins.servezoneInterfaces.data.IMailDeliveryStatus,
+  ): boolean {
+    const policy = auth.token?.policy;
+    if (!policy || policy.role !== 'gatewayClient') {
+      return true;
+    }
+    const owner = statusArg.spoolItem?.owner;
+    if (!owner || !policy.gatewayClient) {
+      return false;
+    }
+    return owner.gatewayClientType === policy.gatewayClient.type
+      && owner.gatewayClientId === policy.gatewayClient.id;
+  }
+
   private async filterWorkAppMailBindingsAllowed(
     auth: TAuthContext,
     managerArg: any,

package/ts/readme.md

@@ -68,7 +68,7 @@ await router.start();
 - The DB is enabled by default and uses an embedded local database when no external MongoDB URL is provided.
 - System routes from config, email, and DNS are persisted with stable ownership and are toggle-only.
 - API-created routes are the only routes intended for full CRUD from the dashboard or client SDK.
-- Gateway-client mail bindings can create inbound `smtpForward` routes and managed SMTP users. Managed users are restricted to their exact claimed address for envelope and header `From`.
+- Gateway-client mail bindings can create inbound `smtpForward` routes and managed SMTP users. Managed users are restricted to their exact claimed address for envelope and header `From`, and service-mail credentials can query their own delivery spool status after enqueueing mail.
 - Qualifying HTTPS forward routes on port `443` get HTTP/3 augmentation by default.
 - The published package exposes the `dcrouter` npm bin through `./cli.js`; `runCli()` is the supported code-level bootstrap entrypoint.
 

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/dcrouter',
-  version: '15.10.0',
+  version: '15.11.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }