@serve.zone/dcrouter 17.7.0 → 17.8.0

package/ts/email/classes.accepted-email-spool.ts

@@ -145,6 +145,10 @@ export interface IAcceptRawEmailOptions {
   processAfterAccept?: boolean;
   /** Explicit direction override for programmatic submitters. Defaults to the session-authenticated rule. */
   direction?: TCachedEmailDirection;
+  /** Exact authenticated outbound identity and replay metadata. */
+  submissionCredentialId?: string;
+  submissionIdempotencyKey?: string;
+  submissionDigest?: string;
 }
 
 /**
@@ -221,7 +225,7 @@ export class AcceptedEmailSpool {
       await cachedEmail.save();
       await this.notifyEmailQueuePersisted(cachedEmail, 'email-accepted');
     } catch (error) {
-      await this.deleteRawMessage(cachedEmail).catch(() => undefined);
+      await this.cleanupRawMessageAfterSaveFailure(cachedEmail, error);
       throw error;
     }
     if (context.abortSignal?.aborted) {
@@ -262,6 +266,9 @@ export class AcceptedEmailSpool {
     cachedEmail.cc = [];
     cachedEmail.bcc = [];
     cachedEmail.subject = optionsArg.subject || this.extractHeader(rawMessage, 'subject') || '';
+    cachedEmail.submissionCredentialId = optionsArg.submissionCredentialId;
+    cachedEmail.submissionIdempotencyKey = optionsArg.submissionIdempotencyKey;
+    cachedEmail.submissionDigest = optionsArg.submissionDigest;
     const persistedRawMessage = this.setDcRouterCacheIdHeader(rawMessage, cachedEmail.id);
     await this.persistRawMessage(cachedEmail, persistedRawMessage);
     cachedEmail.status = 'pending';
@@ -287,7 +294,7 @@ export class AcceptedEmailSpool {
       await cachedEmail.save();
       await this.notifyEmailQueuePersisted(cachedEmail, 'raw-email-accepted');
     } catch (error) {
-      await this.deleteRawMessage(cachedEmail).catch(() => undefined);
+      await this.cleanupRawMessageAfterSaveFailure(cachedEmail, error);
       throw error;
     }
 
@@ -875,9 +882,11 @@ export class AcceptedEmailSpool {
       cachedEmail.status = 'deferred';
       cachedEmail.lastError = item.lastError || 'SmartMTA delivery deferred';
       const smartMtaNextAttempt = item.nextAttempt || new Date(Date.now() + ACCEPTED_EMAIL_RETRY_DELAY_MS);
+      cachedEmail.smartMtaNextAttempt = smartMtaNextAttempt;
       cachedEmail.nextAttempt = new Date(smartMtaNextAttempt.getTime() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
     } else {
       cachedEmail.status = 'queued';
+      cachedEmail.smartMtaNextAttempt = undefined;
       cachedEmail.nextAttempt = new Date(Date.now() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
     }
     await cachedEmail.save();
@@ -954,6 +963,7 @@ export class AcceptedEmailSpool {
     }
     this.updateSmartMtaRouteData(cachedEmail, queueItem, status);
     const smartMtaNextAttempt = queueItem.nextAttempt || new Date(Date.now() + ACCEPTED_EMAIL_RETRY_DELAY_MS);
+    cachedEmail.smartMtaNextAttempt = status === 'deferred' ? smartMtaNextAttempt : undefined;
     cachedEmail.nextAttempt = new Date(smartMtaNextAttempt.getTime() + ACCEPTED_EMAIL_QUEUE_LEASE_MS);
     await cachedEmail.save();
     await this.notifyEmailQueuePersisted(cachedEmail, 'email-live-queue-postponed');
@@ -1016,6 +1026,38 @@ export class AcceptedEmailSpool {
     await blobStorage.delete(cachedEmailArg.rawContentObjectKey);
   }
 
+  private async cleanupRawMessageAfterSaveFailure(
+    cachedEmailArg: CachedEmail,
+    saveErrorArg: unknown,
+  ): Promise<void> {
+    try {
+      await this.deleteRawMessage(cachedEmailArg);
+      return;
+    } catch (deleteError: unknown) {
+      // Keep a durable, immediately-expired reference. CacheCleaner retries the
+      // SmartBucket deletion before removing this recovery document.
+      cachedEmailArg.submissionCredentialId = undefined;
+      cachedEmailArg.submissionIdempotencyKey = undefined;
+      cachedEmailArg.submissionDigest = undefined;
+      cachedEmailArg.markFailed(
+        `Accepted-email persistence failed; raw-message cleanup pending: ${(saveErrorArg as Error).message}`,
+      );
+      cachedEmailArg.setTTL(0);
+      try {
+        await cachedEmailArg.save();
+      } catch (recoveryError: unknown) {
+        throw new AggregateError(
+          [saveErrorArg, deleteError, recoveryError],
+          `Accepted-email persistence and durable raw-message cleanup failed for ${cachedEmailArg.id}`,
+        );
+      }
+      logger.log(
+        'warn',
+        `Persisted raw-message cleanup recovery for ${cachedEmailArg.id}: ${(deleteError as Error).message}`,
+      );
+    }
+  }
+
   private async persistRawMessage(cachedEmailArg: CachedEmail, rawMessageArg: string): Promise<void> {
     const blobStorage = this.dcRouterRef.getSmartMtaBlobStorageManager();
     if (!blobStorage) {

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

@@ -383,6 +383,7 @@ export class WorkAppMailManager {
     authArg: plugins.servezoneInterfaces.requests.mail.IMailSubmissionRequestAuth,
     messageArg: plugins.servezoneInterfaces.data.IMailOutboundMessagePayload,
     outboundIdentityIdArg?: string,
+    idempotencyKeyArg?: string,
   ): Promise<TMailEnqueueResponse> {
     if (!this.dcRouterRef.emailServer) {
       return { accepted: false, message: 'Email server is not running' };
@@ -394,19 +395,41 @@ export class WorkAppMailManager {
         outboundIdentityIdArg,
       );
       await this.assertIdentityOutboundReady(identity);
+      const idempotencyKey = this.normalizeMailIdempotencyKey(idempotencyKeyArg);
+      const submissionDigest = idempotencyKey
+        ? this.getMailSubmissionDigest(identity, messageArg)
+        : undefined;
+      const existingReplay = idempotencyKey
+        ? await this.getMailSubmissionReplay(identity, idempotencyKey, submissionDigest!)
+        : undefined;
+      if (existingReplay) return existingReplay;
       const rawMessage = this.buildOutboundRawMessage(identity, messageArg);
       const recipients = this.getMessageRecipients(messageArg);
       const session = this.buildAuthenticatedSession(identity, messageArg.from, recipients, rawMessage);
-      const acceptance = await this.dcRouterRef.acceptedEmailSpool.acceptRawMessage({
-        rawMessage,
-        envelope: {
-          mailFrom: identity.address,
-          rcptTo: recipients,
-        },
-        session,
-        messageId: this.extractHeader(rawMessage, 'message-id'),
-        subject: messageArg.subject,
-      });
+      let acceptance;
+      try {
+        acceptance = await this.dcRouterRef.acceptedEmailSpool.acceptRawMessage({
+          rawMessage,
+          envelope: {
+            mailFrom: identity.address,
+            rcptTo: recipients,
+          },
+          session,
+          messageId: this.extractHeader(rawMessage, 'message-id'),
+          subject: messageArg.subject,
+          ...(idempotencyKey ? {
+            submissionCredentialId: identity.id,
+            submissionIdempotencyKey: idempotencyKey,
+            submissionDigest,
+          } : {}),
+        });
+      } catch (errorArg) {
+        const racedReplay = idempotencyKey
+          ? await this.getMailSubmissionReplay(identity, idempotencyKey, submissionDigest!)
+          : undefined;
+        if (racedReplay) return racedReplay;
+        throw errorArg;
+      }
       return {
         accepted: acceptance.accepted,
         spoolItemId: acceptance.spoolItemId,
@@ -421,6 +444,70 @@ export class WorkAppMailManager {
     }
   }
 
+  private normalizeMailIdempotencyKey(valueArg?: string): string | undefined {
+    if (valueArg === undefined) return undefined;
+    if (
+      typeof valueArg !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._/-]{0,199}$/.test(valueArg)
+    ) throw new Error('Mail idempotencyKey is invalid');
+    return valueArg;
+  }
+
+  private canonicalMailSubmissionJson(valueArg: unknown): string {
+    if (valueArg === null || typeof valueArg === 'string' || typeof valueArg === 'boolean') {
+      return JSON.stringify(valueArg);
+    }
+    if (typeof valueArg === 'number') {
+      if (!Number.isFinite(valueArg)) throw new Error('Mail submission contains an invalid number');
+      return JSON.stringify(valueArg);
+    }
+    if (Array.isArray(valueArg)) {
+      return `[${valueArg.map((itemArg) => this.canonicalMailSubmissionJson(itemArg)).join(',')}]`;
+    }
+    if (valueArg && typeof valueArg === 'object') {
+      const entries = Object.entries(valueArg as Record<string, unknown>)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([leftKey], [rightKey]) => leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0);
+      return `{${entries.map(([keyArg, entryValue]) => (
+        `${JSON.stringify(keyArg)}:${this.canonicalMailSubmissionJson(entryValue)}`
+      )).join(',')}}`;
+    }
+    throw new Error('Mail submission contains an unsupported value');
+  }
+
+  private getMailSubmissionDigest(
+    identityArg: IStoredWorkAppMailIdentity,
+    messageArg: plugins.servezoneInterfaces.data.IMailOutboundMessagePayload,
+  ): string {
+    const canonical = this.canonicalMailSubmissionJson({
+      identityId: identityArg.id,
+      message: messageArg,
+      version: 1,
+    });
+    return `sha256:${plugins.crypto.createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+  }
+
+  private async getMailSubmissionReplay(
+    identityArg: IStoredWorkAppMailIdentity,
+    idempotencyKeyArg: string,
+    submissionDigestArg: string,
+  ): Promise<TMailEnqueueResponse | undefined> {
+    const existing = await CachedEmail.findBySubmissionIdempotencyKey(
+      identityArg.id,
+      idempotencyKeyArg,
+    );
+    if (!existing) return undefined;
+    if (existing.submissionDigest !== submissionDigestArg) {
+      throw new Error('Mail idempotencyKey was reused with different message semantics');
+    }
+    return {
+      accepted: true,
+      spoolItemId: existing.id,
+      outboundIdentity: this.toMailOutboundIdentity(identityArg),
+      message: 'Idempotent service-mail replay',
+    };
+  }
+
   public async getMailDeliveryStatus(
     spoolItemIdArg: string,
   ): Promise<TMailDeliveryStatusResponse> {

package/ts/index.ts

@@ -15,6 +15,9 @@ export * from './radius/index.js';
 // Remote Ingress module
 export * from './remoteingress/index.js';
 
+// Web Push provider module
+export * from './webpush/index.js';
+
 // HTTP/3 module
 export type { IHttp3Config } from './http3/index.js';
 

package/ts/opsserver/classes.opsserver.ts

@@ -41,6 +41,8 @@ export class OpsServer {
   private acmeConfigHandler!: handlers.AcmeConfigHandler;
   private emailDomainHandler!: handlers.EmailDomainHandler;
   private gatewayClientHandler!: handlers.GatewayClientHandler;
+  private webPushControlHandler!: handlers.WebPushControlHandler;
+  private webPushAppHandler!: handlers.WebPushAppHandler;
   private configEventHandler!: handlers.ConfigEventHandler;
   private smtpRealtimeUnsubscribe?: () => void;
   private emailQueueRealtimeUnsubscribe?: () => void;
@@ -106,6 +108,8 @@ export class OpsServer {
     this.acmeConfigHandler = new handlers.AcmeConfigHandler(this);
     this.emailDomainHandler = new handlers.EmailDomainHandler(this);
     this.gatewayClientHandler = new handlers.GatewayClientHandler(this);
+    this.webPushControlHandler = new handlers.WebPushControlHandler(this);
+    this.webPushAppHandler = new handlers.WebPushAppHandler(this);
     this.configEventHandler = new handlers.ConfigEventHandler(this);
     this.smtpRealtimeUnsubscribe =
       this.dcRouterRef.acceptedEmailSpool?.onSmtpTransactionPersisted?.((eventArg) => {

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

@@ -180,11 +180,13 @@ export class EmailOpsHandler {
     const { headers, body } = this.parseRawEmail(rawContent);
     const session = this.parseCachedEmailSession(doc);
 
-    const nextAttemptMs = doc.nextAttempt ? new Date(doc.nextAttempt).getTime() : NaN;
+    // Display SmartMTA's true retry schedule — doc.nextAttempt is the spool's
+    // recovery lease (retry time + 30min grace), not the user-facing countdown.
+    const nextAttemptMs = doc.smartMtaNextAttempt ? new Date(doc.smartMtaNextAttempt).getTime() : NaN;
     return {
       ...base,
       smtpTransactions: structuredClone(doc.smtpTransactions || []),
-      ...((base.status === 'pending' || base.status === 'deferred') && Number.isFinite(nextAttemptMs) && nextAttemptMs > 0
+      ...(base.status === 'deferred' && Number.isFinite(nextAttemptMs) && nextAttemptMs > 0
         ? {
             nextAttemptAt: nextAttemptMs,
             nextAttemptNumber: (doc.attempts || 0) + 1,

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

@@ -524,6 +524,7 @@ export class GatewayClientHandler {
             dataArg.auth || {},
             dataArg.message,
             dataArg.outboundIdentityId,
+            dataArg.idempotencyKey,
           );
         },
       ),
@@ -609,6 +610,12 @@ export class GatewayClientHandler {
       http3: {
         enabled: dcRouter.options.http3?.enabled !== false,
       },
+      webPush: {
+        bindings: Boolean(dcRouter.webPushManager?.isReady),
+        delivery: Boolean(dcRouter.webPushManager?.isReady),
+        cancellation: Boolean(dcRouter.webPushManager?.isReady),
+        vapidRotation: Boolean(dcRouter.webPushManager?.isReady),
+      },
     };
   }
 
@@ -1346,9 +1353,9 @@ export class GatewayClientHandler {
     if (!sourceBindings) {
       return {
         success: false,
-        message: sourceProfileRef
+        message: sourceProfileRef?.trim()
           ? `source profile '${sourceProfileRef}' not found`
-          : 'PUBLIC source profile not found',
+          : 'STANDARD source profile not found',
       };
     }
 
@@ -1747,7 +1754,7 @@ export class GatewayClientHandler {
   ): interfaces.data.IRouteSourceBinding[] | undefined {
     const resolver = this.opsServerRef.dcRouterRef.referenceResolver;
     const profiles = resolver?.listProfiles() || [];
-    const wantedRef = (requestedProfileRefArg || 'public').trim().toLowerCase();
+    const wantedRef = (requestedProfileRefArg?.trim() || 'standard').toLowerCase();
     const profile = profiles.find((profileArg: interfaces.data.ISourceProfile) => {
       return profileArg.id.trim().toLowerCase() === wantedRef;
     }) || profiles.find((profileArg: interfaces.data.ISourceProfile) => {

package/ts/opsserver/handlers/index.ts

@@ -23,3 +23,5 @@ export * from './email-domain.handler.js';
 export * from './gatewayclient.handler.js';
 export * from './realtime.handler.js';
 export * from './config-event.handler.js';
+export * from './webpush-control.handler.js';
+export * from './webpush-app.handler.js';

package/ts/opsserver/handlers/webpush-app.handler.ts

@@ -0,0 +1,105 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+
+export class WebPushAppHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  public constructor(private readonly opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private registerHandlers(): void {
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_GetWebPushServiceStatus
+      >(
+        'getWebPushServiceStatus',
+        async (dataArg) => {
+          const manager = this.opsServerRef.dcRouterRef.webPushManager;
+          if (!manager.isReady) return manager.getUnavailableServiceStatus();
+          return await manager.getServiceStatus(dataArg.auth);
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_EnqueueWebPush
+      >(
+        'enqueueWebPush',
+        async (dataArg) => {
+          try {
+            return await this.opsServerRef.dcRouterRef.webPushManager.enqueue(
+              dataArg.auth,
+              {
+                idempotencyKey: dataArg.idempotencyKey,
+                subscriptionId: dataArg.subscriptionId,
+                subscription: dataArg.subscription,
+                vapidKeyId: dataArg.vapidKeyId,
+                payload: dataArg.payload,
+                ttlSeconds: dataArg.ttlSeconds,
+                urgency: dataArg.urgency,
+                collapseKey: dataArg.collapseKey,
+              },
+            );
+          } catch (error: unknown) {
+            return {
+              accepted: false,
+              message: this.safeMessage(error),
+            };
+          }
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_CancelWebPush
+      >(
+        'cancelWebPush',
+        async (dataArg) => {
+          try {
+            const result = await this.opsServerRef.dcRouterRef.webPushManager.cancel(
+              dataArg.auth,
+              dataArg.target,
+            );
+            return {
+              success: true,
+              ...result,
+            };
+          } catch (error: unknown) {
+            return {
+              success: false,
+              cancelledCount: 0,
+              alreadyTerminalCount: 0,
+              message: this.safeMessage(error),
+            };
+          }
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_GetWebPushDeliveryStatus
+      >(
+        'getWebPushDeliveryStatus',
+        async (dataArg) => {
+          return {
+            delivery: await this.opsServerRef.dcRouterRef.webPushManager.getDeliveryStatus(
+              dataArg.auth,
+              dataArg.spoolItemId,
+            ),
+          };
+        },
+      ),
+    );
+  }
+
+  private safeMessage(errorArg: unknown): string {
+    return errorArg instanceof plugins.typedrequest.TypedResponseError
+      ? errorArg.message
+      : 'Web Push delivery operation failed';
+  }
+}

package/ts/opsserver/handlers/webpush-control.handler.ts

@@ -0,0 +1,257 @@
+import * as plugins from '../../plugins.js';
+import type { OpsServer } from '../classes.opsserver.js';
+import type { WebPushBindingDoc } from '../../db/index.js';
+import type { IWebPushControllerMutation } from '../../webpush/classes.webpush-manager.js';
+import {
+  requireGatewayMachineAuth,
+  type IGatewayMachineAuthContext,
+} from '../helpers/gateway-client-auth.js';
+
+type IWebPushResourceOwner = plugins.servezoneInterfaces.data.IWebPushResourceOwner;
+
+export class WebPushControlHandler {
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+
+  public constructor(private readonly opsServerRef: OpsServer) {
+    this.opsServerRef.typedrouter.addTypedRouter(this.typedrouter);
+    this.registerHandlers();
+  }
+
+  private registerHandlers(): void {
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_ListWebPushBindings
+      >(
+        'listWebPushBindings',
+        async (dataArg) => {
+          const auth = await this.requireControlAuth(dataArg.auth, 'readWebPush');
+          const owner = this.scopeOwnerFilter(auth, dataArg.owner);
+          const manager = this.opsServerRef.dcRouterRef.webPushManager;
+          return {
+            bindings: await manager.listBindings(owner),
+          };
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_SyncWebPushBinding
+      >(
+        'syncWebPushBinding',
+        async (dataArg) => {
+          try {
+            const request = dataArg as typeof dataArg & {
+              controller: IWebPushControllerMutation;
+            };
+            const auth = await this.requireControlAuth(dataArg.auth, 'manageWebPush');
+            this.assertExactOwner(auth, dataArg.binding.owner);
+            const result = await this.opsServerRef.dcRouterRef.webPushManager.syncBinding(
+              dataArg.binding,
+              request.controller,
+              auth.userId,
+            );
+            return {
+              success: true,
+              binding: result.binding,
+              credential: result.credential,
+            };
+          } catch (error: unknown) {
+            return {
+              success: false,
+              message: this.safeMessage(error),
+            };
+          }
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_DeleteWebPushBinding
+      >(
+        'deleteWebPushBinding',
+        async (dataArg) => {
+          try {
+            const request = dataArg as typeof dataArg & {
+              id?: string;
+              owner: IWebPushResourceOwner;
+              controller: IWebPushControllerMutation;
+            };
+            const auth = await this.requireControlAuth(dataArg.auth, 'manageWebPush');
+            this.assertExactOwner(auth, request.owner);
+            return {
+              success: await this.opsServerRef.dcRouterRef.webPushManager.deleteBinding({
+                ...(request.id !== undefined ? { id: request.id } : {}),
+                owner: request.owner,
+                controller: request.controller,
+              }, auth.userId),
+            };
+          } catch (error: unknown) {
+            return {
+              success: false,
+              message: this.safeMessage(error),
+            };
+          }
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_RotateWebPushCredential
+      >(
+        'rotateWebPushCredential',
+        async (dataArg) => {
+          try {
+            const auth = await this.requireControlAuth(dataArg.auth, 'manageWebPush');
+            const manager = this.opsServerRef.dcRouterRef.webPushManager;
+            const binding = await manager.getBindingByCredentialId(dataArg.credentialId);
+            if (!binding) {
+              throw new plugins.typedrequest.TypedResponseError('Web Push binding not found');
+            }
+            this.assertExactOwner(auth, this.bindingOwner(binding));
+            return {
+              success: true,
+              credential: await manager.rotateCredential(dataArg.credentialId),
+            };
+          } catch (error: unknown) {
+            return {
+              success: false,
+              message: this.safeMessage(error),
+            };
+          }
+        },
+      ),
+    );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<
+        plugins.servezoneInterfaces.requests.webpush.IReq_RotateWebPushVapidKey
+      >(
+        'rotateWebPushVapidKey',
+        async (dataArg) => {
+          try {
+            const auth = await this.requireControlAuth(dataArg.auth, 'manageWebPush');
+            const binding = await this.requireAuthorizedBinding(auth, dataArg.bindingId);
+            return {
+              success: true,
+              binding: await this.opsServerRef.dcRouterRef.webPushManager.rotateVapidKey(
+                binding.id,
+              ),
+            };
+          } catch (error: unknown) {
+            return {
+              success: false,
+              message: this.safeMessage(error),
+            };
+          }
+        },
+      ),
+    );
+  }
+
+  private async requireControlAuth(
+    authArg: plugins.servezoneInterfaces.requests.webpush.IWebPushControlRequestAuth,
+    capabilityArg: 'readWebPush' | 'manageWebPush',
+  ): Promise<IGatewayMachineAuthContext> {
+    const auth = await requireGatewayMachineAuth(
+      this.opsServerRef,
+      authArg,
+      capabilityArg === 'manageWebPush'
+        ? 'gateway-clients:write'
+        : 'gateway-clients:read',
+    );
+    if (auth.isAdmin) return auth;
+    if (
+      auth.policy?.role !== 'gatewayClient'
+      || auth.policy.capabilities?.[capabilityArg] !== true
+    ) {
+      throw new plugins.typedrequest.TypedResponseError(
+        `token capability missing: ${capabilityArg}`,
+      );
+    }
+    return auth;
+  }
+
+  private scopeOwnerFilter(
+    authArg: IGatewayMachineAuthContext,
+    requestedArg: Partial<IWebPushResourceOwner> | undefined,
+  ): Partial<IWebPushResourceOwner> {
+    if (authArg.isAdmin) return requestedArg || {};
+    const gatewayClient = authArg.gatewayClient;
+    if (!gatewayClient) {
+      throw new plugins.typedrequest.TypedResponseError(
+        'gateway-client credential required',
+      );
+    }
+    if (
+      requestedArg?.gatewayClientType !== undefined
+      && requestedArg.gatewayClientType !== gatewayClient.type
+    ) {
+      throw new plugins.typedrequest.TypedResponseError(
+        'gateway-client credential cannot access another Web Push owner',
+      );
+    }
+    if (
+      requestedArg?.gatewayClientId !== undefined
+      && requestedArg.gatewayClientId !== gatewayClient.id
+    ) {
+      throw new plugins.typedrequest.TypedResponseError(
+        'gateway-client credential cannot access another Web Push owner',
+      );
+    }
+    return {
+      gatewayClientType: gatewayClient.type,
+      gatewayClientId: gatewayClient.id,
+      ...(requestedArg?.appInstanceId !== undefined
+        ? { appInstanceId: requestedArg.appInstanceId }
+        : {}),
+    };
+  }
+
+  private assertExactOwner(
+    authArg: IGatewayMachineAuthContext,
+    ownerArg: IWebPushResourceOwner,
+  ): void {
+    if (authArg.isAdmin) return;
+    const gatewayClient = authArg.gatewayClient;
+    if (
+      !gatewayClient
+      || ownerArg.gatewayClientType !== gatewayClient.type
+      || ownerArg.gatewayClientId !== gatewayClient.id
+    ) {
+      throw new plugins.typedrequest.TypedResponseError(
+        'gateway-client credential cannot access another Web Push owner',
+      );
+    }
+  }
+
+  private async requireAuthorizedBinding(
+    authArg: IGatewayMachineAuthContext,
+    bindingIdArg: string,
+  ): Promise<WebPushBindingDoc> {
+    const binding = await this.opsServerRef.dcRouterRef.webPushManager.getBindingById(
+      bindingIdArg,
+    );
+    if (!binding) {
+      throw new plugins.typedrequest.TypedResponseError('Web Push binding not found');
+    }
+    this.assertExactOwner(authArg, this.bindingOwner(binding));
+    return binding;
+  }
+
+  private bindingOwner(bindingArg: WebPushBindingDoc): IWebPushResourceOwner {
+    return {
+      gatewayClientType: bindingArg.ownerGatewayClientType,
+      gatewayClientId: bindingArg.ownerGatewayClientId,
+      appInstanceId: bindingArg.ownerAppInstanceId,
+    };
+  }
+
+  private safeMessage(errorArg: unknown): string {
+    return errorArg instanceof plugins.typedrequest.TypedResponseError
+      ? errorArg.message
+      : 'Web Push control operation failed';
+  }
+}