@serve.zone/dcrouter 15.9.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

@@ -196,6 +196,17 @@ export class GatewayClientHandler {
       ),
     );
 
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_GetGatewayClientRoutes>(
+        'getGatewayClientRoutes',
+        async (dataArg) => {
+          const auth = await this.requireAuth(dataArg, 'gateway-clients:read');
+          this.assertCapability(auth, 'readDnsRecords');
+          return { routes: this.listGatewayClientRoutes(auth, dataArg.gatewayClientId) };
+        },
+      ),
+    );
+
 
     this.typedrouter.addTypedHandler(
       new plugins.typedrequest.TypedHandler<plugins.servezoneInterfaces.requests.gateway.IReq_SyncGatewayClientRoute>(
@@ -339,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',
@@ -429,13 +468,23 @@ export class GatewayClientHandler {
     throw new plugins.typedrequest.TypedResponseError(`token capability missing: ${String(capability)}`);
   }
 
-  private resolveGatewayClientId(auth: TAuthContext, requestedId?: string): string | undefined {
-    const policyClient = auth.token?.policy?.gatewayClient;
-    if (!policyClient) return requestedId;
+  private resolveGatewayClientRouteFilter(
+    auth: TAuthContext,
+    requestedId?: string,
+  ): { gatewayClientId?: string; gatewayClientType?: string } {
+    const policy = auth.token?.policy;
+    if (policy?.role !== 'gatewayClient') return { gatewayClientId: requestedId };
+    const policyClient = policy.gatewayClient;
+    if (!policyClient) {
+      throw new plugins.typedrequest.TypedResponseError('gateway client token is missing gatewayClient binding');
+    }
     if (requestedId && requestedId !== policyClient.id) {
       throw new plugins.typedrequest.TypedResponseError('gateway client token cannot access another gateway client');
     }
-    return policyClient.id;
+    return {
+      gatewayClientId: policyClient.id,
+      gatewayClientType: policyClient.type,
+    };
   }
 
   private resolveGatewayClientOwnership(
@@ -588,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,
@@ -665,25 +730,85 @@ export class GatewayClientHandler {
     return [];
   }
 
-  private getOwnedRoutes(gatewayClientId?: string): interfaces.data.IMergedRoute[] {
+  private getOwnedRoutes(routeFilter: { gatewayClientId?: string; gatewayClientType?: string }): interfaces.data.IMergedRoute[] {
     const manager = this.opsServerRef.dcRouterRef.routeConfigManager;
     if (!manager) return [];
     return manager.getMergedRoutes().routes.filter((route) => {
       const metadata = route.metadata;
       if (!metadata) return false;
       if (metadata.ownerType !== 'gatewayClient') return false;
-      return gatewayClientId ? metadata.gatewayClientId === gatewayClientId : true;
+      if (routeFilter.gatewayClientId && metadata.gatewayClientId !== routeFilter.gatewayClientId) return false;
+      if (routeFilter.gatewayClientType && (metadata.gatewayClientType || 'custom') !== routeFilter.gatewayClientType) return false;
+      return true;
     });
   }
 
+  private listGatewayClientRoutes(
+    auth: TAuthContext,
+    requestedGatewayClientId?: string,
+  ): plugins.servezoneInterfaces.data.IGatewayClientRoute[] {
+    const routeFilter = this.resolveGatewayClientRouteFilter(auth, requestedGatewayClientId);
+    return this.getOwnedRoutes(routeFilter)
+      .map((routeArg) => this.toGatewayClientRoute(routeArg))
+      .filter((routeArg): routeArg is plugins.servezoneInterfaces.data.IGatewayClientRoute => {
+        if (!routeArg) return false;
+        if (auth.token?.policy?.role !== 'gatewayClient') return true;
+        return !routeArg.ownership.hostname
+          || this.matchesHostnamePatterns(routeArg.ownership.hostname, auth.token.policy.hostnamePatterns || []);
+      });
+  }
+
+  private toGatewayClientRoute(
+    routeArg: interfaces.data.IMergedRoute,
+  ): plugins.servezoneInterfaces.data.IGatewayClientRoute | null {
+    const metadata = routeArg.metadata;
+    if (!metadata || metadata.ownerType !== 'gatewayClient') return null;
+    const ownership = this.toGatewayClientOwnership(routeArg);
+    if (!ownership.hostname && !ownership.routeRef) return null;
+    const route = structuredClone(routeArg.route) as any;
+    delete route.security;
+    return {
+      id: routeArg.id,
+      name: route.name || routeArg.id,
+      enabled: routeArg.enabled,
+      ownership,
+      route,
+      sourceProfileRef: metadata.sourceBindings?.find((bindingArg) => bindingArg.sourceProfileRef)?.sourceProfileRef,
+      managePath: `/routes/${routeArg.id}`,
+    };
+  }
+
+  private toGatewayClientOwnership(
+    routeArg: interfaces.data.IMergedRoute,
+  ): plugins.servezoneInterfaces.data.IGatewayClientOwnership {
+    const metadata = routeArg.metadata!;
+    const ownership: plugins.servezoneInterfaces.data.IGatewayClientOwnership = {
+      gatewayClientType: metadata.gatewayClientType || 'custom',
+      gatewayClientId: metadata.gatewayClientId || '',
+      appId: metadata.gatewayClientAppId || '',
+    };
+    const prefix = `${ownership.gatewayClientType}:${ownership.gatewayClientId}:${ownership.appId}:`;
+    const routeKey = metadata.externalKey?.startsWith(prefix)
+      ? metadata.externalKey.slice(prefix.length)
+      : '';
+    if (routeKey.startsWith('route:')) {
+      ownership.routeRef = routeKey.slice('route:'.length);
+    } else if (routeKey) {
+      ownership.hostname = routeKey;
+    } else {
+      ownership.hostname = this.getRouteHostnames(routeArg.route)[0];
+    }
+    return ownership;
+  }
+
   private async listGatewayClientDomains(
     auth: TAuthContext,
     requestedGatewayClientId?: string,
   ): Promise<plugins.servezoneInterfaces.data.IGatewayDomain[]> {
     const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
     if (!dnsManager) return [];
-    const gatewayClientId = this.resolveGatewayClientId(auth, requestedGatewayClientId);
-    const ownedRoutes = this.getOwnedRoutes(gatewayClientId);
+    const routeFilter = this.resolveGatewayClientRouteFilter(auth, requestedGatewayClientId);
+    const ownedRoutes = this.getOwnedRoutes(routeFilter);
     const routeHostnames = ownedRoutes.flatMap((route) => this.getRouteHostnames(route.route));
     const docs = await dnsManager.listDomains();
 
@@ -716,8 +841,8 @@ export class GatewayClientHandler {
   ): Promise<plugins.servezoneInterfaces.data.IGatewayDnsRecord[]> {
     const dnsManager = this.opsServerRef.dcRouterRef.dnsManager;
     if (!dnsManager) return [];
-    const gatewayClientId = this.resolveGatewayClientId(auth, requestedGatewayClientId);
-    const ownedRoutes = this.getOwnedRoutes(gatewayClientId);
+    const routeFilter = this.resolveGatewayClientRouteFilter(auth, requestedGatewayClientId);
+    const ownedRoutes = this.getOwnedRoutes(routeFilter);
     const domains = await dnsManager.listDomains();
     const records: plugins.servezoneInterfaces.data.IGatewayDnsRecord[] = [];
 

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.9.0',
+  version: '15.11.0',
   description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 }