@serve.zone/dcrouter 20.2.0 → 32.0.1

package/dist_ts_web/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/dcrouter',
-    version: '20.2.0',
+    version: '32.0.1',
     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": "20.2.0",
+  "version": "32.0.1",
   "description": "A multifaceted routing service handling mail and SMS delivery functions.",
   "type": "module",
   "bin": {
@@ -15,7 +15,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.3",
+    "@git.zone/tsbuild": "^4.5.0",
     "@git.zone/tsbundle": "^2.13.0",
     "@git.zone/tsdeno": "^1.8.0",
     "@git.zone/tsdocker": "^3.5.8",
@@ -24,7 +24,7 @@
     "@git.zone/tswatch": "^3.3.5",
     "@push.rocks/smartdb-v2": "npm:@push.rocks/smartdb@2.14.6",
     "@push.rocks/smartdb-v5.2": "npm:@push.rocks/smartdb@5.2.2",
-    "@types/node": "26.5.0",
+    "@types/node": "26.5.1",
     "@types/web-push": "3.6.4"
   },
   "dependencies": {
@@ -51,7 +51,7 @@
     "@push.rocks/smartlog": "^3.2.2",
     "@push.rocks/smartmcp": "^0.3.0",
     "@push.rocks/smartmetrics": "^3.0.3",
-    "@push.rocks/smartmigration": "1.5.0",
+    "@push.rocks/smartmigration": "1.7.0",
     "@push.rocks/smartmta": "^9.5.0",
     "@push.rocks/smartnetwork": "^4.10.1",
     "@push.rocks/smartpath": "^6.0.0",
@@ -66,7 +66,7 @@
     "@push.rocks/smartvpn": "1.22.0",
     "@push.rocks/taskbuffer": "^9.0.2",
     "@serve.zone/catalog": "^4.0.0",
-    "@serve.zone/interfaces": "30.14.0",
+    "@serve.zone/interfaces": "^32.0.0",
     "@serve.zone/remoteingress": "^5.2.5",
     "@tsclass/tsclass": "^9.5.1",
     "@types/qrcode": "^1.5.6",

package/readme.md

@@ -324,13 +324,14 @@ continue occupying quota and reservations. A changed payload cannot reuse an
 idempotency key. Retrying the same payload/key never intentionally creates a
 second operation.
 
-Schema migration `19.1.0` installs the indexes and backfills legacy certificate
-identities without rewriting PEM data. Rollout and staging-CA validation are
+Schema migration `testing-access-and-exact-certificate-identities` (`18.8.0` to
+`19.1.0`) installs the indexes and backfills legacy certificate identities
+without rewriting PEM data. Rollout and staging-CA validation are
 separate operational steps; isolated tests do not issue public certificates.
 
 ## 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:
+Web Push is disabled by default and does not read its secret configuration while disabled. It requires DB-backed persistence and the `web-push-provider-schema` migration. Enable it only after all three secret values are present:
 
 | Environment variable | Value |
 | --- | --- |
@@ -349,6 +350,7 @@ Operational behavior:
 - 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.
+- Upgrading to 32.0.0 reseals every stored Web Push envelope under new associated data, so `DCROUTER_WEB_PUSH_MASTER_KEY_RING` must hold the key each existing envelope names before the first 32.0.0 start; otherwise the `webpush-encryption-context` migration refuses by name and dcrouter does not start. The push payload also loses its `schemaVersion` member with `@serve.zone/interfaces` 32, so a service worker that reads it must stop expecting the field.
 - 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.
@@ -368,6 +370,15 @@ dcrouter keeps generated and operator-created routes separate so automation can
 
 System routes are persisted with stable `systemKey` values. Ordinary operator-created API routes are editable through generic route CRUD. Routes carrying managed ownership metadata, including Special Forwards and gateway-client routes, reject generic structural updates and deletion so their owning workflow keeps canonical match, priority, source-policy, and ownership fields intact.
 
+A gateway-client route is keyed by `metadata.externalKey`, spelled
+`<gatewayClientType>:<gatewayClientId>:<appId>:<routeKey>`. The route key is a bare hostname, or
+`route:<routeRef>` when the client owns a route reference without a hostname, or
+`host-route:<base64url([hostname, routeRef])>` when it owns one hostname under a specific route
+reference. dcrouter composes and matches the key itself: a gateway client sends ownership fields
+and never an `externalKey`. Upgrading to 32.0.1 rewrites stored keys from the released
+`v2:host-route:` spelling through the `host-route-key` migration step; a key that still spells
+the old prefix afterwards is treated as malformed and listed with its route hostname only.
+
 ## DNS Authority
 
 Which zones the embedded DNS server may answer for authoritatively is database
@@ -666,6 +677,8 @@ await route.toggle(true);
 
 Use `@serve.zone/dcrouter/interfaces` or `@serve.zone/dcrouter-interfaces` when you want dcrouter-local raw TypedRequest contracts instead of resource managers. Use `@serve.zone/interfaces` for the canonical machine-facing gateway client route, DNS, domain, and mail contracts shared with Onebox and Cloudly.
 
+dcrouter 32.0.0 builds against `@serve.zone/interfaces` 32.0.0: the installed interfaces release is the contract version, there is no version field on the wire and no per-shape version suffix. dcrouter serves no session that carries the 32 protocol handshake and opens none — its gateway-client, mail, Web Push and CoreMail gateway contracts are unchanged in 32.0.0 and carry no protocol offer — so no caller has to send one.
+
 Gateway-client mail contracts let Cloudly or Onebox claim exact app addresses, attach inbound `smtpForward` targets, enable managed outbound SMTP credentials, rotate those credentials, enqueue service mail, and query delivery status through TypedRequest. `getGatewayClientMailDomainCount` requires an authenticated, enabled gateway-client credential with the `gateway-clients:read` scope and `readMail` capability. It returns only that credential owner's distinct domain count; it does not accept a caller-selected owner and does not load bindings, DNS details, or recent mail. Managed SMTP users can only send as their exact claimed address; mismatched envelope or header `From` values are rejected before relay. Typed submissions may set `replyTo` to one bare printable-ASCII mailbox address. Dcrouter validates it authoritatively and renders one `Reply-To` header; custom headers remain unable to override `Reply-To` or any other protected MIME field. Delivery status queries return the dcrouter spool item state, including deferred SmartMTA errors and next retry timestamps when outbound delivery is temporarily delayed.
 
 ### Email Operations Views
@@ -765,7 +778,6 @@ The peer carries verifier material only:
 
 ```json
 {
-  "schemaVersion": 1,
   "coreMailServiceId": "coremail-prod",
   "transferOrigin": "https://coremail.example.com",
   "credentials": [
@@ -773,7 +785,7 @@ The peer carries verifier material only:
       "credentialId": "coremail-gateway",
       "version": 2,
       "state": "current",
-      "format": "argon2id-v1",
+      "format": "argon2id",
       "verificationHash": "$argon2id$v=19$m=65536,t=3,p=1$<salt>$<digest>"
     }
   ]
@@ -858,7 +870,9 @@ Supported environment overrides include:
 
 ## Docker Image
 
-Release builds publish a multi-arch OCI image at `code.foss.global/serve.zone/dcrouter:latest` for `linux/amd64` and `linux/arm64`. The image sets `DCROUTER_MODE=OCI_CONTAINER` and starts `node ./cli.js`.
+Release builds publish a multi-arch OCI image for `linux/amd64` and `linux/arm64`. The image sets `DCROUTER_MODE=OCI_CONTAINER` and starts `node ./cli.js`.
+
+From 32.0.0 on the image is built from `Dockerfile_##version##`, so `tsdocker` publishes it under the release version tag only — `code.foss.global/serve.zone/dcrouter:32.0.0` for this release — and dcrouter publishes no `latest` tag again. The existing `dcrouter:latest` stays frozen at the 20.2.0 build for consumers that still pull it by that name, including Onebox's managed dcrouter, so pin dcrouter by version.
 
 ```bash
 docker run --rm --name dcrouter \
@@ -866,7 +880,7 @@ docker run --rm --name dcrouter \
   -v dcrouter-data:/data \
   -e DCROUTER_BASE_DIR=/data \
   -e DCROUTER_TLS_EMAIL=ops@example.com \
-  code.foss.global/serve.zone/dcrouter:latest
+  code.foss.global/serve.zone/dcrouter:32.0.0
 ```
 
 Host networking is the simplest container mode for a gateway that owns HTTP/S, SMTP, DNS, RADIUS, remote ingress, and dynamic proxy ports. For narrower deployments, publish only the ports you enable in `IDcRouterOptions` or via the `DCROUTER_*` environment overrides.
@@ -900,6 +914,7 @@ Useful source entry points:
 - `ts/opsserver/classes.opsserver.ts` wires the dashboard server and TypedRequest handlers.
 - `ts/remoteingress/` integrates `@serve.zone/remoteingress` with stored edge registrations.
 - `ts_migrations/index.ts` contains all DB schema migration steps.
+- `Dockerfile_##version##` builds the service image; the file name is the published image tag.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

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

package/ts/classes.dcrouter.ts

@@ -1339,11 +1339,9 @@ export class DcRouter {
       const migration = await createApplicationMigrationRunner(this.dcRouterDb.getDb(), {
         remoteIngressHubSettings: this.getRemoteIngressHubSettingsMigrationSeed(),
         emailServerSettings: this.getEmailSettingsMigrationSeed(),
-        legacySmartMtaStoragePath: plugins.path.join(
-          this.resolvedPaths.dataDir,
-          'smartmta-storage',
+        webPushMasterKeyRing: await this.qenv.getEnvVarOnDemand(
+          'DCROUTER_WEB_PUSH_MASTER_KEY_RING',
         ),
-        legacyRawMessageBlobStorage: this.smartMtaBlobStorageManager,
       });
       const migrationResult = await migration.run();
       if (migrationResult.stepsApplied.length > 0) {

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

@@ -12,9 +12,6 @@ export class WebPushSpoolDoc extends plugins.smartdata.SmartDataDbDoc<
   @plugins.smartdata.svDb()
   public id!: string;
 
-  @plugins.smartdata.svDb()
-  public schemaVersion: 1 = 1;
-
   @plugins.smartdata.svDb()
   public bindingId!: string;
 

package/ts/email/classes.coremail-gateway.manager.ts

@@ -210,7 +210,7 @@ export class CoreMailGatewayManager {
   ): Promise<{ success: boolean; peer?: TPeerDesiredState; message?: string }> {
     let record: ICoreMailGatewayPeerRecord;
     try {
-      // The normalizer is the contract gate: argon2id-v1 verifier form, exactly
+      // The normalizer is the contract gate: argon2id verifier form, exactly
       // one current credential, and the current version greater than every
       // retiring one. It is never relaxed for a producer's convenience.
       record = normalizeCoreMailGatewayPeerRecord(ownerArg, peerArg);
@@ -259,7 +259,6 @@ export class CoreMailGatewayManager {
 
   private toPeerDesiredState(peerArg: ICoreMailGatewayPeerRecord): TPeerDesiredState {
     return data().normalizeCoreMailGatewayPeerDesiredState({
-      schemaVersion: 1,
       coreMailServiceId: peerArg.coreMailServiceId,
       transferOrigin: peerArg.transferOrigin,
       credentials: peerArg.credentials.map((credentialArg) => ({ ...credentialArg })),

package/ts/email/coremail-gateway-authority.ts

@@ -52,7 +52,7 @@ export function createCoreMailGatewayPeerId(
 /**
  * Normalize one peer record through the shared contract. The desired-state
  * payload is validated by the interfaces normalizer, which is also what
- * rejects plaintext credential material: only argon2id-v1 verifier strings
+ * rejects plaintext credential material: only argon2id verifier strings
  * survive it.
  */
 export function normalizeCoreMailGatewayPeerRecord(

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

@@ -11,6 +11,12 @@ import {
   normalizeGatewayTargetHost,
   requireGatewayMachineAuth,
 } from '../helpers/gateway-client-auth.js';
+import {
+  buildGatewayClientHostRouteKey,
+  buildGatewayClientRouteName,
+  parseGatewayClientHostRouteKey,
+} from '../helpers/gateway-client-route-key.js';
+import { logger } from '../../logger.js';
 
 type TResolvedGatewayClientOwnership = Required<Pick<plugins.servezoneInterfaces.data.IGatewayClientOwnership,
   'gatewayClientType' | 'gatewayClientId' | 'appId'
@@ -1171,15 +1177,22 @@ export class GatewayClientHandler {
     const routeKey = metadata.externalKey?.startsWith(prefix)
       ? metadata.externalKey.slice(prefix.length)
       : '';
-    const combinedOwnership = this.parseCombinedGatewayClientRouteKey(routeKey);
+    const combinedOwnership = parseGatewayClientHostRouteKey(routeKey);
     if (combinedOwnership) {
       ownership.hostname = combinedOwnership.hostname;
       ownership.routeRef = combinedOwnership.routeRef;
-    } else if (routeKey.startsWith('v2:host-route:')) {
-      // A malformed versioned key must not be exposed as a hostname.
-      ownership.hostname = this.getRouteHostnames(routeArg.route)[0];
     } else if (routeKey.startsWith('route:')) {
       ownership.routeRef = routeKey.slice('route:'.length);
+    } else if (routeKey.includes(':')) {
+      // A hostname carries no colon, so a colon-bearing key that parses as neither of the two
+      // other forms states ownership this router cannot prove. Report what the route actually
+      // serves rather than the key, and say so instead of dropping the key silently.
+      logger.log(
+        'warn',
+        `Gateway client route ${routeArg.id} carries a malformed route key '${routeKey}'; listing it with its route hostname only.`,
+        { routeId: routeArg.id },
+      );
+      ownership.hostname = this.getRouteHostnames(routeArg.route)[0];
     } else if (routeKey) {
       ownership.hostname = routeKey;
     } else {
@@ -1659,8 +1672,7 @@ export class GatewayClientHandler {
     const routeRef = ownership.routeRef?.trim();
     let routeKey: string;
     if (hostname && routeRef) {
-      const payload = Buffer.from(JSON.stringify([hostname, routeRef]), 'utf8').toString('base64url');
-      routeKey = `v2:host-route:${payload}`;
+      routeKey = buildGatewayClientHostRouteKey(hostname, routeRef);
     } else if (hostname) {
       routeKey = hostname;
     } else {
@@ -1674,35 +1686,6 @@ export class GatewayClientHandler {
     ].map((part) => part.trim()).join(':');
   }
 
-  private parseCombinedGatewayClientRouteKey(
-    routeKeyArg: string,
-  ): { hostname: string; routeRef: string } | undefined {
-    const prefix = 'v2:host-route:';
-    if (!routeKeyArg.startsWith(prefix)) {
-      return undefined;
-    }
-    const payload = routeKeyArg.slice(prefix.length);
-    if (!payload || !/^[A-Za-z0-9_-]+$/.test(payload)) {
-      return undefined;
-    }
-    try {
-      const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
-      if (
-        !Array.isArray(parsed)
-        || parsed.length !== 2
-        || parsed.some((value) => typeof value !== 'string' || !value.trim())
-      ) {
-        return undefined;
-      }
-      return {
-        hostname: parsed[0].trim().toLowerCase(),
-        routeRef: parsed[1].trim(),
-      };
-    } catch {
-      return undefined;
-    }
-  }
-
   private validateGatewayRouteConfig(
     routeArg: unknown,
   ): plugins.servezoneInterfaces.data.IGatewayRouteConfig {
@@ -1882,7 +1865,7 @@ export class GatewayClientHandler {
       } as any;
     }
     if (!normalizedRoute.name) {
-      normalizedRoute.name = `gateway-client-${externalKey.replace(/[^a-zA-Z0-9-]+/g, '-').slice(0, 80)}`;
+      normalizedRoute.name = buildGatewayClientRouteName(externalKey);
     }
     return normalizedRoute;
   }

package/ts/opsserver/helpers/gateway-client-route-key.ts

@@ -0,0 +1,64 @@
+/**
+ * The route-key half of a gateway-client route's `externalKey`, owned here so the composer,
+ * the parser, the generated route name and the migration that rewrote stored keys all read
+ * one spelling.
+ *
+ * A stored key is `<gatewayClientType>:<gatewayClientId>:<appId>:<routeKey>`, and the route key
+ * is one of three forms: a bare hostname, `route:<routeRef>` when the client owns a route
+ * reference without a hostname, and the combined form below when it owns one hostname under a
+ * specific route reference. The combined payload is base64url so the whole key stays one opaque
+ * segment, and neither other form can be mistaken for it: a hostname carries no colon, and the
+ * route-reference form has a different prefix.
+ */
+export const gatewayClientHostRouteKeyPrefix = 'host-route:';
+
+export interface IGatewayClientHostRouteKey {
+  hostname: string;
+  routeRef: string;
+}
+
+export function buildGatewayClientHostRouteKey(
+  hostnameArg: string,
+  routeRefArg: string,
+): string {
+  const payload = Buffer.from(JSON.stringify([hostnameArg, routeRefArg]), 'utf8').toString('base64url');
+  return `${gatewayClientHostRouteKeyPrefix}${payload}`;
+}
+
+/**
+ * Read a combined route key back. Returns undefined for every key that is not one — including a
+ * key that carries the prefix but no decodable payload, so a malformed key can never be served
+ * as ownership it does not state.
+ */
+export function parseGatewayClientHostRouteKey(
+  routeKeyArg: string,
+): IGatewayClientHostRouteKey | undefined {
+  if (!routeKeyArg.startsWith(gatewayClientHostRouteKeyPrefix)) {
+    return undefined;
+  }
+  const payload = routeKeyArg.slice(gatewayClientHostRouteKeyPrefix.length);
+  if (!payload || !/^[A-Za-z0-9_-]+$/.test(payload)) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    if (
+      !Array.isArray(parsed)
+      || parsed.length !== 2
+      || parsed.some((value) => typeof value !== 'string' || !value.trim())
+    ) {
+      return undefined;
+    }
+    return {
+      hostname: parsed[0].trim().toLowerCase(),
+      routeRef: parsed[1].trim(),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** The route name generated for a gateway-client route whose producer sent none. */
+export function buildGatewayClientRouteName(externalKeyArg: string): string {
+  return `gateway-client-${externalKeyArg.replace(/[^a-zA-Z0-9-]+/g, '-').slice(0, 80)}`;
+}

package/ts/webpush/classes.webpush-crypto.ts

@@ -6,7 +6,6 @@ export interface IWebPushKeyRing {
 }
 
 export interface IWebPushEncryptedEnvelope {
-  version: 1;
   algorithm: 'aes-256-gcm';
   keyId: string;
   nonce: string;
@@ -14,6 +13,9 @@ export interface IWebPushEncryptedEnvelope {
   tag: string;
 }
 
+/** Exact member set of a sealed envelope; anything else is refused, never read. */
+const ENVELOPE_KEYS = ['algorithm', 'ciphertext', 'keyId', 'nonce', 'tag'].join(',');
+
 export interface IWebPushAadContext {
   gatewayClientId: string;
   appInstanceId: string;
@@ -33,7 +35,6 @@ const KEY_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
 const BASE64URL_KEY_PATTERN = /^[A-Za-z0-9_-]{43}$/;
 const BASE64URL_VALUE_PATTERN = /^[A-Za-z0-9_-]+$/;
 const KEY_RING_LIMIT = 8;
-const AAD_SCHEMA_VERSION = 1;
 
 function requirePlainObject(
   valueArg: unknown,
@@ -146,7 +147,6 @@ export function buildWebPushAad(contextArg: IWebPushAadContext): Buffer {
     }
   }
   return Buffer.from(canonicalJson({
-    schemaVersion: AAD_SCHEMA_VERSION,
     gatewayClientId: contextArg.gatewayClientId,
     appInstanceId: contextArg.appInstanceId,
     bindingId: contextArg.bindingId,
@@ -185,6 +185,81 @@ export function canonicalJson(valueArg: unknown): string {
   return JSON.stringify(canonicalize(valueArg));
 }
 
+/**
+ * Seal one value under a key ring's current key. Kept beside the reader so the
+ * two sides of an envelope cannot drift, and exposed at ring level so a caller
+ * that holds only the encryption ring — the migration that reseals stored
+ * envelopes — does not have to restate the format.
+ */
+export function sealWebPushEnvelope(
+  keyRingArg: IWebPushKeyRing,
+  valueArg: unknown,
+  aadContextArg: IWebPushAadContext,
+): IWebPushEncryptedEnvelope {
+  const keyId = keyRingArg.currentKeyId;
+  const key = keyRingArg.keys.get(keyId);
+  if (!key) throw new Error('Current Web Push encryption key is unavailable');
+  const nonce = plugins.crypto.randomBytes(12);
+  const cipher = plugins.crypto.createCipheriv('aes-256-gcm', key, nonce);
+  cipher.setAAD(buildWebPushAad(aadContextArg));
+  const ciphertext = Buffer.concat([
+    cipher.update(canonicalJson(valueArg), 'utf8'),
+    cipher.final(),
+  ]);
+  return {
+    algorithm: 'aes-256-gcm',
+    keyId,
+    nonce: nonce.toString('base64url'),
+    ciphertext: ciphertext.toString('base64url'),
+    tag: cipher.getAuthTag().toString('base64url'),
+  };
+}
+
+/** Open one envelope. An envelope whose member set is not exactly the sealed one is refused, never read. */
+export function openWebPushEnvelope<T>(
+  keyRingArg: IWebPushKeyRing,
+  envelopeArg: IWebPushEncryptedEnvelope,
+  aadContextArg: IWebPushAadContext,
+): T {
+  if (
+    envelopeArg === null
+    || typeof envelopeArg !== 'object'
+    || Object.keys(envelopeArg).sort().join(',') !== ENVELOPE_KEYS
+    || envelopeArg.algorithm !== 'aes-256-gcm'
+    || typeof envelopeArg.keyId !== 'string'
+    || !KEY_ID_PATTERN.test(envelopeArg.keyId)
+  ) {
+    throw new Error('Web Push encrypted envelope is malformed');
+  }
+  const key = keyRingArg.keys.get(envelopeArg.keyId);
+  if (!key) throw new Error('Web Push encrypted envelope references an unavailable key');
+  const nonce = decodeBase64UrlExact(envelopeArg.nonce, 12, 'Web Push envelope nonce');
+  const tag = decodeBase64UrlExact(envelopeArg.tag, 16, 'Web Push envelope tag');
+  if (
+    typeof envelopeArg.ciphertext !== 'string'
+    || !envelopeArg.ciphertext
+    || !BASE64URL_VALUE_PATTERN.test(envelopeArg.ciphertext)
+  ) {
+    throw new Error('Web Push envelope ciphertext is malformed');
+  }
+  const ciphertext = Buffer.from(envelopeArg.ciphertext, 'base64url');
+  if (ciphertext.toString('base64url') !== envelopeArg.ciphertext) {
+    throw new Error('Web Push envelope ciphertext is malformed');
+  }
+  try {
+    const decipher = plugins.crypto.createDecipheriv('aes-256-gcm', key, nonce);
+    decipher.setAAD(buildWebPushAad(aadContextArg));
+    decipher.setAuthTag(tag);
+    const plaintext = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final(),
+    ]).toString('utf8');
+    return JSON.parse(plaintext) as T;
+  } catch (error: unknown) {
+    throw new Error('Web Push encrypted envelope authentication failed', { cause: error });
+  }
+}
+
 export class WebPushCrypto {
   public constructor(
     private readonly encryptionRing: IWebPushKeyRing,
@@ -205,66 +280,14 @@ export class WebPushCrypto {
     valueArg: unknown,
     aadContextArg: IWebPushAadContext,
   ): IWebPushEncryptedEnvelope {
-    const keyId = this.encryptionRing.currentKeyId;
-    const key = this.encryptionRing.keys.get(keyId);
-    if (!key) throw new Error('Current Web Push encryption key is unavailable');
-    const nonce = plugins.crypto.randomBytes(12);
-    const cipher = plugins.crypto.createCipheriv('aes-256-gcm', key, nonce);
-    cipher.setAAD(buildWebPushAad(aadContextArg));
-    const ciphertext = Buffer.concat([
-      cipher.update(canonicalJson(valueArg), 'utf8'),
-      cipher.final(),
-    ]);
-    const tag = cipher.getAuthTag();
-    return {
-      version: 1,
-      algorithm: 'aes-256-gcm',
-      keyId,
-      nonce: nonce.toString('base64url'),
-      ciphertext: ciphertext.toString('base64url'),
-      tag: tag.toString('base64url'),
-    };
+    return sealWebPushEnvelope(this.encryptionRing, valueArg, aadContextArg);
   }
 
   public decryptJson<T>(
     envelopeArg: IWebPushEncryptedEnvelope,
     aadContextArg: IWebPushAadContext,
   ): T {
-    if (
-      envelopeArg?.version !== 1
-      || envelopeArg.algorithm !== 'aes-256-gcm'
-      || typeof envelopeArg.keyId !== 'string'
-      || !KEY_ID_PATTERN.test(envelopeArg.keyId)
-    ) {
-      throw new Error('Web Push encrypted envelope is malformed');
-    }
-    const key = this.encryptionRing.keys.get(envelopeArg.keyId);
-    if (!key) throw new Error('Web Push encrypted envelope references an unavailable key');
-    const nonce = decodeBase64UrlExact(envelopeArg.nonce, 12, 'Web Push envelope nonce');
-    const tag = decodeBase64UrlExact(envelopeArg.tag, 16, 'Web Push envelope tag');
-    if (
-      typeof envelopeArg.ciphertext !== 'string'
-      || !envelopeArg.ciphertext
-      || !BASE64URL_VALUE_PATTERN.test(envelopeArg.ciphertext)
-    ) {
-      throw new Error('Web Push envelope ciphertext is malformed');
-    }
-    const ciphertext = Buffer.from(envelopeArg.ciphertext, 'base64url');
-    if (ciphertext.toString('base64url') !== envelopeArg.ciphertext) {
-      throw new Error('Web Push envelope ciphertext is malformed');
-    }
-    try {
-      const decipher = plugins.crypto.createDecipheriv('aes-256-gcm', key, nonce);
-      decipher.setAAD(buildWebPushAad(aadContextArg));
-      decipher.setAuthTag(tag);
-      const plaintext = Buffer.concat([
-        decipher.update(ciphertext),
-        decipher.final(),
-      ]).toString('utf8');
-      return JSON.parse(plaintext) as T;
-    } catch (error: unknown) {
-      throw new Error('Web Push encrypted envelope authentication failed', { cause: error });
-    }
+    return openWebPushEnvelope<T>(this.encryptionRing, envelopeArg, aadContextArg);
   }
 
   public hmac(

package/ts/webpush/classes.webpush-manager.ts

@@ -237,10 +237,10 @@ function normalizePayload(payloadArg: IWebPushNotificationPayload): IWebPushNoti
     throw new plugins.typedrequest.TypedResponseError('Web Push payload is malformed');
   }
   const keys = Object.keys(payloadArg).sort();
-  if (keys.join(',') !== 'event,eventId,route,schemaVersion') {
+  if (keys.join(',') !== 'event,eventId,route') {
     throw new plugins.typedrequest.TypedResponseError('Web Push payload contains unsupported fields');
   }
-  if (payloadArg.schemaVersion !== 1 || payloadArg.event !== 'notificationAvailable') {
+  if (payloadArg.event !== 'notificationAvailable') {
     throw new plugins.typedrequest.TypedResponseError('Web Push payload schema is unsupported');
   }
   const eventId = requireOpaqueId(payloadArg.eventId, 'Web Push payload eventId');
@@ -261,7 +261,6 @@ function normalizePayload(payloadArg: IWebPushNotificationPayload): IWebPushNoti
     throw new plugins.typedrequest.TypedResponseError('Web Push payload route must be same-origin');
   }
   const normalized = {
-    schemaVersion: 1 as const,
     event: 'notificationAvailable' as const,
     eventId,
     route,

package/ts_web/00_commitinfo_data.ts

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