@serve.zone/dcrouter 17.7.0 → 17.8.0

package/dist_ts_web/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/dcrouter',
-    version: '17.7.0',
+    version: '17.8.0',
     description: 'A multifaceted routing service handling mail and SMS delivery functions.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHNfd2ViLzAwX2NvbW1pdGluZm9fZGF0YS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUNILE1BQU0sQ0FBQyxNQUFNLFVBQVUsR0FBRztJQUN4QixJQUFJLEVBQUUsc0JBQXNCO0lBQzVCLE9BQU8sRUFBRSxRQUFRO0lBQ2pCLFdBQVcsRUFBRSwwRUFBMEU7Q0FDeEYsQ0FBQSJ9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@serve.zone/dcrouter",
   "private": false,
-  "version": "17.7.0",
+  "version": "17.8.0",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "bin": {
@@ -16,13 +16,14 @@
   "license": "MIT",
   "devDependencies": {
     "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsbundle": "^2.11.2",
+    "@git.zone/tsbundle": "^2.11.3",
     "@git.zone/tsdeno": "^1.7.0",
-    "@git.zone/tsdocker": "^3.0.0",
+    "@git.zone/tsdocker": "^3.1.0",
     "@git.zone/tsrun": "^2.0.5",
     "@git.zone/tstest": "^3.6.6",
     "@git.zone/tswatch": "^3.3.5",
-    "@types/node": "26.1.1"
+    "@types/node": "26.1.1",
+    "@types/web-push": "3.6.4"
   },
   "dependencies": {
     "@api.global/typedrequest": "^3.3.2",
@@ -46,7 +47,7 @@
     "@push.rocks/smartguard": "^3.1.2",
     "@push.rocks/smartjwt": "^2.5.1",
     "@push.rocks/smartlog": "^3.2.2",
-    "@push.rocks/smartmcp": "^0.2.0",
+    "@push.rocks/smartmcp": "^0.3.0",
     "@push.rocks/smartmetrics": "^3.0.3",
     "@push.rocks/smartmigration": "1.4.1",
     "@push.rocks/smartmta": "^8.2.1",
@@ -63,13 +64,15 @@
     "@push.rocks/smartvpn": "1.21.0",
     "@push.rocks/taskbuffer": "^8.0.2",
     "@serve.zone/catalog": "^2.19.0",
-    "@serve.zone/interfaces": "^17.1.0",
-    "@serve.zone/remoteingress": "^5.0.1",
+    "@serve.zone/interfaces": "^18.0.0",
+    "@serve.zone/remoteingress": "^5.0.3",
     "@tsclass/tsclass": "^9.5.1",
     "@types/qrcode": "^1.5.6",
+    "ipaddr.js": "^2.4.0",
     "lru-cache": "^11.5.2",
     "qrcode": "^1.5.4",
-    "uuid": "^14.0.1"
+    "uuid": "^14.0.1",
+    "web-push": "3.6.7"
   },
   "keywords": [
     "mail service",
@@ -113,7 +116,8 @@
     "deno.json",
     "tsconfig.json",
     ".smartconfig.json",
-    "readme.md"
+    "readme.md",
+    "third-party-notices.md"
   ],
   "engines": {
     "node": ">=22"

package/readme.md

@@ -136,6 +136,33 @@ Important runtime behavior:
 - Email listener ports can be remapped internally, for example public `25`, `587`, and `465` to unprivileged internal ports.
 - `emailOutboundMode: 'remoteIngress'` requires an enabled RemoteIngress hub and an eligible connected QUIC edge with SMTP egress enabled. If no eligible edge is available, outbound delivery fails or defers instead of silently falling back to direct SMTP from the hub.
 
+## Web Push Provider
+
+Web Push is disabled by default and does not read its secret configuration while disabled. It requires DB-backed persistence and the `17.8.0` migration. Enable it only after all three secret values are present:
+
+| Environment variable | Value |
+| --- | --- |
+| `DCROUTER_WEB_PUSH_ENABLED` | `true`, `1`, `on`, or `yes` starts the provider and worker. `false`, `0`, `off`, `no`, unset, or empty disables it. Any other value fails startup. |
+| `DCROUTER_WEB_PUSH_MASTER_KEY_RING` | JSON or a `base64Object:` JSON value containing AES-256 keys used for encrypted VAPID and queued-delivery envelopes. |
+| `DCROUTER_WEB_PUSH_HMAC_KEY_RING` | The same key-ring shape, with different key material, used for credentials and opaque request/endpoint digests. |
+| `DCROUTER_WEB_PUSH_VAPID_SUBJECT` | An HTTPS URL or `mailto:` contact passed to push services. |
+
+Each key ring has the form `{"currentKeyId":"key-2026-07","keys":{"key-2026-07":"<32-byte-unpadded-base64url>"}}`, supports at most eight distinct keys, and must name a configured current key. Encryption and HMAC rings must never reuse key material.
+
+Operational behavior:
+
+- Control-plane callers need gateway-client `readWebPush` or `manageWebPush` capability. App calls use the one-time binding credential returned by `syncWebPushBinding`; the active credential record stores only its HMAC verifier. To recover a lost rotation response, dcrouter may return the same issuance again during its 15-minute overlap window; that recovery secret is AES-GCM encrypted at rest and is removed when the window expires.
+- Every sync or delete carries a durable controller id, stable epoch, monotonically increasing generation, operation id, and intent. Sync accepts only `enabled`; delete accepts `disabled` or `deleted`, an exact owner, and an optional binding id. Exact same-generation retries resume cleanup and replay the durable outcome, while lower generations, changed controller epochs, or conflicting same-generation requests fail closed. An owner-reserving delete tombstone is created even when a timed-out create has not returned a binding id, so the late create cannot reactivate the provider.
+- A binding admits 120 new requests per minute and 5,000 per hour, atomically across workers and restarts. Matching idempotent replays do not consume admission. The nonterminal queue is capped at 10,000 items per binding.
+- Payloads are limited to 3,500 UTF-8 bytes, TTL must be from 1 through 86,400 seconds, delivery makes at most eight attempts, and each retry sends the remaining TTL. Terminal rows retain only non-secret delivery metadata for seven days.
+- Subscription endpoints must be public HTTPS hostnames on port 443. DNS is bounded and pinned for the request; IP literals, credentials, fragments, and any answer containing a non-global address are rejected.
+- App credential rotation has a 15-minute overlap. VAPID rotation retains retiring keys for 90 days and, if necessary, until old queued items have terminally drained, with four VAPID keys maximum. Rotate before reaching that bound.
+- For a key-ring rotation, add new unique key material, set `currentKeyId`, restart, and keep old encryption keys until every VAPID, delivery, and credential-recovery envelope using them has been rotated or purged. Keep each old HMAC key only until no current or overlap credential references its key id; terminal and idempotency retention does not require the old HMAC key. Remove old keys only after those conditions are true.
+- `deleteWebPushBinding` is a destructive tombstone operation: it revokes and removes all credential hashes, prior credentials, credential-recovery envelopes, and encrypted VAPID private keys; cancels and scrubs queued work; and clears admission state. Queued work is terminalized immediately, but an already sending request remains `sending` until the remote response wins or its lease expires. An expired lease after cancellation is recorded as a failed delivery with an unknown remote outcome, never as a confirmed cancellation. Delete/disable reports success only after that lifecycle drains; a bounded drain timeout returns a retryable failure, and the same controller operation resumes cleanup. Re-enabling the same owner creates a new lifecycle, credential, and VAPID key. Clients must recreate browser push subscriptions and must not reuse deleted credentials.
+- The worker performs bounded maintenance every cycle and at startup, repeatedly removing expired credential overlap/recovery state, drained retiring or retired VAPID private keys, stale admission state, and incomplete disabled/deleted lifecycle cleanup without materializing an unbounded collection.
+
+For a staged rollout, deploy with `DCROUTER_WEB_PUSH_ENABLED=false`, confirm the migration and health of the rest of dcrouter, install the three secret values, enable one gateway-client binding, and exercise status/enqueue/delivery/cancellation before expanding. To roll back worker activity, set the feature flag to `false` and restart; durable unexpired items remain encrypted and resume after re-enable. Do not delete bindings as a rollback mechanism because deletion is intentionally irreversible.
+
 ## Route Ownership
 
 dcrouter keeps generated and operator-created routes separate so automation can reconcile safely.

package/third-party-notices.md

@@ -0,0 +1,37 @@
+# Third-Party Notices
+
+## web-push
+
+`web-push` is used under the Mozilla Public License 2.0.
+
+Copyright 2015 Marco Castelluccio
+
+This Source Code Form is subject to the terms of the Mozilla Public License,
+v. 2.0. If a copy of the MPL was not distributed with this file, you can
+obtain one at <https://mozilla.org/MPL/2.0/>.
+
+Source: <https://github.com/web-push-libs/web-push>
+
+## http_ece
+
+`http_ece` is used transitively through `web-push`.
+
+Copyright (c) 2015 Martin Thomson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ts/00_commitinfo_data.ts

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

package/ts/classes.dcrouter.ts

@@ -40,6 +40,7 @@ import { GatewayRouteDnsReconciler } from './dns/classes.gateway-route-dns-recon
 import { AcmeConfigManager } from './acme/manager.acme-config.js';
 import { SmartAcmeLifecycle } from './acme/classes.smartacme-lifecycle.js';
 import { AcceptedEmailSpool, EmailDomainManager, EmailRouteBuilder, EmailSettingsManager, MailDnsSync, MailEdgeEligibility, MailEgressCoordinator, ReleasedRemoteIngressEgressIdentitySource, SmartMtaBlobStorageManager, SmartMtaStorageManager, WorkAppMailManager, type ISmartMtaBlobStorageConfig, type TSmartMtaQueueItemLike } from './email/index.js';
+import { WebPushManager } from './webpush/index.js';
 import type { IRoute } from '../ts_interfaces/data/route-management.js';
 import type { IEmailOutboundEgressStatus, IEmailPortConfig, IEmailServerSettings, IEmailServerSettingsSeed, TEmailOutboundMode, TEmailServerSettingsUpdate } from '../ts_interfaces/data/email-settings.js';
 import type { IDcRouterRouteConfig, IRemoteIngressHubSettings, IRemoteIngressPerformanceConfig, TRemoteIngressHubSettingsUpdate } from '../ts_interfaces/data/remoteingress.js';
@@ -356,6 +357,7 @@ export class DcRouter {
   public dnsServerRuntime: DnsServerRuntime;
   public emailRouteBuilder: EmailRouteBuilder;
   public routePolicyAugmenter: RoutePolicyAugmenter;
+  public webPushManager: WebPushManager;
 
   // TypedRouter for API endpoints
   public typedrouter = new plugins.typedrequest.TypedRouter();
@@ -399,6 +401,9 @@ export class DcRouter {
     this.dnsServerRuntime = new DnsServerRuntime(this);
     this.emailRouteBuilder = new EmailRouteBuilder(this);
     this.routePolicyAugmenter = new RoutePolicyAugmenter(this);
+    // Construct before OpsServer so early handlers can report unavailable safely.
+    // Secret reads remain deferred until WebPushProvider.start().
+    this.webPushManager = new WebPushManager();
 
     // Initialize service manager and register all services
     this.serviceManager = new plugins.taskbuffer.ServiceManager({
@@ -452,6 +457,24 @@ export class DcRouter {
       );
     }
 
+    // Web Push provider: disabled by default. Enabled mode is critical and
+    // depends on the migrated database; disabled mode reads no provider secrets.
+    const webPushDependencies = this.options.dbConfig?.enabled === false
+      ? []
+      : ['DcRouterDb'];
+    this.serviceManager.addService(
+      new plugins.taskbuffer.Service('WebPushProvider')
+        .critical()
+        .dependsOn(...webPushDependencies)
+        .withStart(async () => {
+          await this.webPushManager.start();
+        })
+        .withStop(async () => {
+          await this.webPushManager.stop();
+        })
+        .withRetry({ maxRetries: 0 }),
+    );
+
     // MetricsManager: optional, depends on OpsServer
     this.serviceManager.addService(
       new plugins.taskbuffer.Service('MetricsManager')
@@ -1048,6 +1071,12 @@ export class DcRouter {
       logger.log('info', `Remote Ingress: tunnel port=${remoteIngressHubSettings.tunnelPort}, edges=${edgeCount} registered/${connectedCount} connected`);
     }
 
+    // Web Push provider summary
+    logger.log(
+      'info',
+      `Web Push Provider: ${this.webPushManager.isReady ? 'ready' : this.webPushManager.isEnabled ? 'unavailable' : 'disabled'}`,
+    );
+
     // Database summary
     if (this.dcRouterDb) {
       logger.log('info', `Database: ${this.dcRouterDb.isEmbedded() ? 'embedded' : 'external'}, db=${this.dcRouterDb.getDbName()}, cleaner=${this.cacheCleaner?.isActive() ? 'active' : 'inactive'} (${(this.options.dbConfig?.cleanupIntervalHours || 1)}h interval)`);

package/ts/config/classes.gateway-client-manager.ts

@@ -33,6 +33,8 @@ const defaultCapabilities: IGatewayClient['capabilities'] = {
   manageMail: false,
   readCertificates: false,
   requestCertificates: false,
+  readWebPush: false,
+  manageWebPush: false,
 };
 
 export class GatewayClientManager {

package/ts/db/documents/classes.cached.email.ts

@@ -130,6 +130,18 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
   @plugins.smartdata.svDb()
   public rawContentSize: number = 0;
 
+  /** Resolved outbound identity id that scopes a service-mail replay key. */
+  @plugins.smartdata.svDb()
+  public submissionCredentialId?: string;
+
+  /** Caller-supplied replay key. It must remain absent for non-idempotent mail. */
+  @plugins.smartdata.svDb()
+  public submissionIdempotencyKey?: string;
+
+  /** Digest of the exact authenticated outbound submission semantics. */
+  @plugins.smartdata.svDb()
+  public submissionDigest?: string;
+
   /** Bounded durable SMTP transaction history copied from SmartMTA. */
   @plugins.smartdata.svDb()
   public smtpTransactions: ICachedEmailSmtpTransaction[] = [];
@@ -162,11 +174,21 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
   public maxAttempts: number = 3;
 
   /**
-   * Timestamp for next delivery attempt
+   * Timestamp for next delivery attempt.
+   * For SmartMTA-managed deliveries this is a RECOVERY LEASE (SmartMTA's retry
+   * time + grace), used by the spool to detect a silently dead queue — it is
+   * NOT the user-facing retry schedule; that lives in smartMtaNextAttempt.
    */
   @plugins.smartdata.svDb()
   public nextAttempt!: Date;
 
+  /**
+   * SmartMTA's actual next scheduled retry (display value for the ops UI).
+   * Only set while the delivery is deferred inside the SmartMTA queue.
+   */
+  @plugins.smartdata.svDb()
+  public smartMtaNextAttempt?: Date;
+
   /**
    * Last error message if delivery failed
    */
@@ -232,12 +254,47 @@ export class CachedEmail extends plugins.smartdata.SmartdataCachedDocument<Cache
 
   public override async createSavableObject(): Promise<CachedEmail> {
     const savableObject = await super.createSavableObject();
+    const submissionFields = [
+      this.submissionCredentialId,
+      this.submissionIdempotencyKey,
+      this.submissionDigest,
+    ];
+    if (submissionFields.every((valueArg) => valueArg === undefined)) {
+      delete savableObject.submissionCredentialId;
+      delete savableObject.submissionIdempotencyKey;
+      delete savableObject.submissionDigest;
+    } else if (
+      typeof this.submissionCredentialId !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(this.submissionCredentialId)
+      || typeof this.submissionIdempotencyKey !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._/-]{0,199}$/.test(this.submissionIdempotencyKey)
+      || typeof this.submissionDigest !== 'string'
+      || !/^sha256:[a-f0-9]{64}$/.test(this.submissionDigest)
+    ) {
+      throw new Error('CachedEmail submission idempotency metadata is invalid');
+    }
     if (this.rawContentObjectKey) {
       delete savableObject.rawContent;
     }
     return savableObject;
   }
 
+  public static async findBySubmissionIdempotencyKey(
+    credentialIdArg: string,
+    idempotencyKeyArg: string,
+  ): Promise<CachedEmail | null> {
+    if (
+      typeof credentialIdArg !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(credentialIdArg)
+      || typeof idempotencyKeyArg !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9:._/-]{0,199}$/.test(idempotencyKeyArg)
+    ) throw new Error('CachedEmail submission idempotency selector is invalid');
+    return await CachedEmail.getInstance({
+      submissionCredentialId: credentialIdArg,
+      submissionIdempotencyKey: idempotencyKeyArg,
+    });
+  }
+
   /**
    * Create a new CachedEmail with a unique ID
    */

package/ts/db/documents/classes.webpush-admission.doc.ts

@@ -0,0 +1,48 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+/**
+ * Durable, binding-scoped Web Push admission counters.
+ *
+ * A credential rotation must not reset these counters, so the stable binding
+ * id and lifecycle generation are the authority rather than a credential id.
+ */
+@plugins.smartdata.Collection(() => getDb())
+export class WebPushAdmissionDoc extends plugins.smartdata.SmartDataDbDoc<
+  WebPushAdmissionDoc,
+  WebPushAdmissionDoc
+> {
+  @plugins.smartdata.svDb()
+  public bindingId!: string;
+
+  @plugins.smartdata.svDb()
+  public lifecycleGeneration!: number;
+
+  @plugins.smartdata.svDb()
+  public shortWindowStartedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public shortWindowCount!: number;
+
+  @plugins.smartdata.svDb()
+  public longWindowStartedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public longWindowCount!: number;
+
+  @plugins.smartdata.svDb()
+  public revision!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public purgeAt!: Date;
+
+  public static getNativeCollection():
+    plugins.smartdata.SmartdataCollection<WebPushAdmissionDoc>['mongoDbCollection'] {
+    return getDb().mongoDb.collection('WebPushAdmissionDoc');
+  }
+}

package/ts/db/documents/classes.webpush-binding.doc.ts

@@ -0,0 +1,147 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { IWebPushEncryptedEnvelope } from '../../webpush/classes.webpush-crypto.js';
+
+export interface IWebPushStoredCredential {
+  id: string;
+  status: plugins.servezoneInterfaces.data.TWebPushCredentialStatus;
+  hmacKeyId: string;
+  secretHash?: string;
+  createdAt: number;
+  updatedAt: number;
+  lastRotatedAt: number | null;
+  validUntil: number | null;
+}
+
+export interface IWebPushStoredVapidKey {
+  id: string;
+  publicKey: string;
+  status: plugins.servezoneInterfaces.data.TWebPushVapidKeyStatus;
+  createdAt: number;
+  activatedAt: number | null;
+  retireAfter: number | null;
+  retiredAt: number | null;
+  privateKeyEnvelope?: IWebPushEncryptedEnvelope;
+}
+
+export interface IWebPushCredentialRotationRecovery {
+  requestedCredentialId: string;
+  resultingCredentialId: string;
+  lifecycleGeneration: number;
+  secretEnvelope: IWebPushEncryptedEnvelope;
+  createdAt: number;
+  expiresAt: number;
+}
+
+export type TWebPushControllerIntent = 'enabled' | 'disabled' | 'deleted';
+
+export interface IWebPushStoredControllerFence {
+  id: string;
+  epoch: string;
+  generation: number;
+  operationId: string;
+  intent: TWebPushControllerIntent;
+  requestDigest: string;
+  appliedAt: number;
+}
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class WebPushBindingDoc extends plugins.smartdata.SmartDataDbDoc<
+  WebPushBindingDoc,
+  WebPushBindingDoc
+> {
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public ownerGatewayClientType!: plugins.servezoneInterfaces.data.TGatewayClientType;
+
+  @plugins.smartdata.svDb()
+  public ownerGatewayClientId!: string;
+
+  @plugins.smartdata.svDb()
+  public ownerAppInstanceId!: string;
+
+  @plugins.smartdata.svDb()
+  public enabled!: boolean;
+
+  @plugins.smartdata.svDb()
+  public status!: plugins.servezoneInterfaces.data.TWebPushBindingStatus;
+
+  @plugins.smartdata.svDb()
+  public credential!: IWebPushStoredCredential;
+
+  /** At most one still-valid overlap credential; expired entries are scrubbed. */
+  @plugins.smartdata.svDb()
+  public previousCredentials: IWebPushStoredCredential[] = [];
+
+  /** MUST BE ABSENT outside the bounded idempotent credential-rotation replay window. */
+  @plugins.smartdata.svDb()
+  public credentialRotationRecovery?: IWebPushCredentialRotationRecovery;
+
+  @plugins.smartdata.svDb()
+  public vapidKeys: IWebPushStoredVapidKey[] = [];
+
+  @plugins.smartdata.svDb()
+  public createdAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public createdBy!: string;
+
+  @plugins.smartdata.svDb()
+  public mutationRevision!: number;
+
+  @plugins.smartdata.svDb()
+  public lifecycleGeneration!: number;
+
+  /** Highest durably applied controller mutation for this owner-reserving binding. */
+  @plugins.smartdata.svDb()
+  public controllerFence?: IWebPushStoredControllerFence;
+
+  /** MUST BE ABSENT unless this owner-reserving binding is a deletion tombstone. */
+  @plugins.smartdata.svDb()
+  public deletedAt?: number;
+
+  public static getNativeCollection():
+    plugins.smartdata.SmartdataCollection<WebPushBindingDoc>['mongoDbCollection'] {
+    return getDb().mongoDb.collection('WebPushBindingDoc');
+  }
+
+  public override async createSavableObject(): Promise<WebPushBindingDoc> {
+    const savable = await super.createSavableObject();
+    if (savable.credential.secretHash === undefined) {
+      delete savable.credential.secretHash;
+    }
+    savable.previousCredentials = (savable.previousCredentials || []).map((credentialArg) => ({
+      ...credentialArg,
+      lastRotatedAt: credentialArg.lastRotatedAt ?? null,
+      validUntil: credentialArg.validUntil ?? null,
+    })).map((credentialArg) => {
+      if (credentialArg.secretHash === undefined) delete credentialArg.secretHash;
+      return credentialArg;
+    });
+    if (savable.credentialRotationRecovery === undefined) {
+      delete savable.credentialRotationRecovery;
+    }
+    if (savable.controllerFence === undefined) delete savable.controllerFence;
+    savable.vapidKeys = (savable.vapidKeys || []).map((keyArg) => {
+      const normalized = {
+        ...keyArg,
+        activatedAt: keyArg.activatedAt ?? null,
+        retireAfter: keyArg.retireAfter ?? null,
+        retiredAt: keyArg.retiredAt ?? null,
+      };
+      if (normalized.privateKeyEnvelope === undefined) {
+        delete normalized.privateKeyEnvelope;
+      }
+      return normalized;
+    });
+    if (savable.deletedAt === undefined) delete savable.deletedAt;
+    return savable;
+  }
+}

package/ts/db/documents/classes.webpush-spool.doc.ts

@@ -0,0 +1,136 @@
+import * as plugins from '../../plugins.js';
+import { DcRouterDb } from '../classes.dcrouter-db.js';
+import type { IWebPushEncryptedEnvelope } from '../../webpush/classes.webpush-crypto.js';
+
+const getDb = () => DcRouterDb.getInstance().getDb();
+
+@plugins.smartdata.Collection(() => getDb())
+export class WebPushSpoolDoc extends plugins.smartdata.SmartDataDbDoc<
+  WebPushSpoolDoc,
+  WebPushSpoolDoc
+> {
+  @plugins.smartdata.svDb()
+  public id!: string;
+
+  @plugins.smartdata.svDb()
+  public schemaVersion: 1 = 1;
+
+  @plugins.smartdata.svDb()
+  public bindingId!: string;
+
+  @plugins.smartdata.svDb()
+  public lifecycleGeneration!: number;
+
+  /** Credential that created this item; used only for the idempotency namespace. */
+  @plugins.smartdata.svDb()
+  public credentialId!: string;
+
+  @plugins.smartdata.svDb()
+  public hmacKeyId!: string;
+
+  @plugins.smartdata.svDb()
+  public idempotencyKeyDigest!: string;
+
+  @plugins.smartdata.svDb()
+  public requestDigest!: string;
+
+  @plugins.smartdata.svDb()
+  public subscriptionId!: string;
+
+  @plugins.smartdata.svDb()
+  public endpointDigest!: string;
+
+  @plugins.smartdata.svDb()
+  public vapidKeyId!: string;
+
+  @plugins.smartdata.svDb()
+  public subscriptionEnvelope?: IWebPushEncryptedEnvelope;
+
+  @plugins.smartdata.svDb()
+  public payloadEnvelope?: IWebPushEncryptedEnvelope;
+
+  @plugins.smartdata.svDb()
+  public payloadBytes!: number;
+
+  @plugins.smartdata.svDb()
+  public ttlSeconds!: number;
+
+  @plugins.smartdata.svDb()
+  public urgency!: plugins.servezoneInterfaces.data.TWebPushUrgency;
+
+  @plugins.smartdata.svDb()
+  public topic: string | null = null;
+
+  @plugins.smartdata.svDb()
+  public state!: plugins.servezoneInterfaces.data.TWebPushDeliveryState;
+
+  @plugins.smartdata.svDb()
+  public attempts: number = 0;
+
+  @plugins.smartdata.svDb()
+  public acceptedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public updatedAt!: number;
+
+  @plugins.smartdata.svDb()
+  public nextAttemptAt!: number;
+
+  @plugins.smartdata.svDb()
+  public expiresAt!: number;
+
+  /** MUST BE ABSENT while the item is not leased. */
+  @plugins.smartdata.svDb()
+  public leaseToken?: string;
+
+  /** MUST BE ABSENT while the item is not leased. */
+  @plugins.smartdata.svDb()
+  public leaseExpiresAt?: number;
+
+  /** MUST BE ABSENT until cancellation races with an in-flight send. */
+  @plugins.smartdata.svDb()
+  public cancelRequestedAt?: number;
+
+  /** MUST BE ABSENT until an in-flight cancellation records its terminal reason. */
+  @plugins.smartdata.svDb()
+  public cancelErrorCode?: string;
+
+  /** MUST BE ABSENT before a terminal transition. */
+  @plugins.smartdata.svDb()
+  public terminalAt?: number;
+
+  @plugins.smartdata.svDb()
+  public pushServiceStatusCode: number | null = null;
+
+  @plugins.smartdata.svDb()
+  public errorCode: string | null = null;
+
+  /** MUST BE ABSENT until terminal retention begins. */
+  @plugins.smartdata.svDb()
+  public purgeAt?: Date;
+
+  public static getNativeCollection():
+    plugins.smartdata.SmartdataCollection<WebPushSpoolDoc>['mongoDbCollection'] {
+    return getDb().mongoDb.collection('WebPushSpoolDoc');
+  }
+
+  public override async createSavableObject(): Promise<WebPushSpoolDoc> {
+    const savable = await super.createSavableObject();
+    for (const field of [
+      'subscriptionEnvelope',
+      'payloadEnvelope',
+      'leaseToken',
+      'leaseExpiresAt',
+      'cancelRequestedAt',
+      'cancelErrorCode',
+      'terminalAt',
+      'purgeAt',
+    ] as const) {
+      if (savable[field] === undefined) delete savable[field];
+    }
+    savable.topic = savable.topic ?? null;
+    savable.pushServiceStatusCode = savable.pushServiceStatusCode ?? null;
+    savable.errorCode = savable.errorCode ?? null;
+    return savable;
+  }
+}

package/ts/db/documents/index.ts

@@ -41,5 +41,10 @@ export * from './classes.acme-config.doc.js';
 // Email domain management
 export * from './classes.email-domain.doc.js';
 export * from './classes.email-server-settings.doc.js';
+
+// Web Push provider documents
+export * from './classes.webpush-binding.doc.js';
+export * from './classes.webpush-admission.doc.js';
+export * from './classes.webpush-spool.doc.js';
 export * from './classes.smartmta-storage.doc.js';
 export * from './classes.ops-config-event.doc.js';