@serve.zone/dcrouter 17.7.1 → 17.8.0

package/ts/webpush/classes.webpush-transport.ts

@@ -0,0 +1,241 @@
+import * as plugins from '../plugins.js';
+import {
+  createPinnedWebPushAgent,
+  resolveWebPushEndpoint,
+  WebPushEndpointPolicyError,
+  type TWebPushDnsLookup,
+} from './helpers.webpush-endpoint.js';
+
+export interface IWebPushTransportRequest {
+  subscription: plugins.webpush.PushSubscription;
+  payload: string;
+  ttlSeconds: number;
+  urgency: plugins.webpush.Urgency;
+  topic?: string;
+  vapid: {
+    subject: string;
+    publicKey: string;
+    privateKey: string;
+  };
+}
+
+export interface IWebPushTransportResponse {
+  statusCode: number;
+  retryAfter?: string;
+}
+
+export interface IWebPushTransport {
+  send(requestArg: IWebPushTransportRequest): Promise<IWebPushTransportResponse>;
+}
+
+export type TWebPushTransportErrorCode =
+  | 'PUSH_DNS_TIMEOUT'
+  | 'PUSH_REQUEST_TIMEOUT'
+  | 'PUSH_RESPONSE_TOO_LARGE'
+  | 'PUSH_RESPONSE_INVALID'
+  | 'PUSH_NETWORK_ERROR';
+
+export class WebPushTransportError extends Error {
+  public constructor(
+    public readonly code: TWebPushTransportErrorCode,
+    optionsArg: { cause?: unknown } = {},
+  ) {
+    super(code, optionsArg);
+    this.name = 'WebPushTransportError';
+  }
+}
+
+export interface IWebPushHttpTransportOptions {
+  dnsLookup?: TWebPushDnsLookup;
+  dnsTimeoutMs?: number;
+  connectTimeoutMs?: number;
+  requestTimeoutMs?: number;
+  maxResponseBytes?: number;
+}
+
+const normalizeRetryAfter = (valueArg: string | string[] | undefined): string | undefined => {
+  if (Array.isArray(valueArg)) return valueArg[0]?.slice(0, 128);
+  return typeof valueArg === 'string' ? valueArg.slice(0, 128) : undefined;
+};
+
+export class WebPushHttpTransport implements IWebPushTransport {
+  private readonly dnsLookup?: TWebPushDnsLookup;
+  private readonly dnsTimeoutMs: number;
+  private readonly connectTimeoutMs: number;
+  private readonly requestTimeoutMs: number;
+  private readonly maxResponseBytes: number;
+
+  public constructor(optionsArg: IWebPushHttpTransportOptions = {}) {
+    this.dnsLookup = optionsArg.dnsLookup;
+    this.dnsTimeoutMs = this.normalizePositiveInteger(
+      optionsArg.dnsTimeoutMs,
+      5_000,
+      'dnsTimeoutMs',
+    );
+    this.connectTimeoutMs = this.normalizePositiveInteger(
+      optionsArg.connectTimeoutMs,
+      10_000,
+      'connectTimeoutMs',
+    );
+    this.requestTimeoutMs = this.normalizePositiveInteger(
+      optionsArg.requestTimeoutMs,
+      15_000,
+      'requestTimeoutMs',
+    );
+    this.maxResponseBytes = this.normalizePositiveInteger(
+      optionsArg.maxResponseBytes,
+      16_384,
+      'maxResponseBytes',
+    );
+  }
+
+  public async send(requestArg: IWebPushTransportRequest): Promise<IWebPushTransportResponse> {
+    const sendDeadline = Date.now() + this.requestTimeoutMs;
+    let resolved: Awaited<ReturnType<typeof resolveWebPushEndpoint>>;
+    try {
+      resolved = await new Promise<Awaited<ReturnType<typeof resolveWebPushEndpoint>>>(
+        (resolve, reject) => {
+          let settled = false;
+          const settle = (
+            errorArg: unknown,
+            valueArg?: Awaited<ReturnType<typeof resolveWebPushEndpoint>>,
+          ) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            if (errorArg) reject(errorArg);
+            else resolve(valueArg!);
+          };
+          const timer = setTimeout(() => {
+            settle(new WebPushTransportError('PUSH_DNS_TIMEOUT'));
+          }, Math.min(this.dnsTimeoutMs, this.requestTimeoutMs));
+          resolveWebPushEndpoint(
+            requestArg.subscription.endpoint,
+            this.dnsLookup,
+          ).then(
+            (valueArg) => settle(null, valueArg),
+            (errorArg) => settle(errorArg),
+          );
+        },
+      );
+    } catch (error: unknown) {
+      if (error instanceof WebPushEndpointPolicyError) throw error;
+      if (error instanceof WebPushTransportError) throw error;
+      throw new WebPushTransportError('PUSH_NETWORK_ERROR', { cause: error });
+    }
+    const remainingRequestTimeoutMs = sendDeadline - Date.now();
+    if (remainingRequestTimeoutMs <= 0) {
+      throw new WebPushTransportError('PUSH_REQUEST_TIMEOUT');
+    }
+    const agent = createPinnedWebPushAgent(resolved);
+    try {
+      const requestDetails = plugins.webpush.generateRequestDetails(
+        requestArg.subscription,
+        requestArg.payload,
+        {
+          TTL: requestArg.ttlSeconds,
+          contentEncoding: 'aes128gcm',
+          urgency: requestArg.urgency,
+          ...(requestArg.topic ? { topic: requestArg.topic } : {}),
+          vapidDetails: requestArg.vapid,
+        },
+      );
+      if (
+        requestDetails.method !== 'POST'
+        || requestDetails.endpoint !== requestArg.subscription.endpoint
+        || !Buffer.isBuffer(requestDetails.body)
+      ) {
+        throw new WebPushTransportError('PUSH_RESPONSE_INVALID');
+      }
+      return await new Promise<IWebPushTransportResponse>((resolve, reject) => {
+        let settled = false;
+        let requestTimer: NodeJS.Timeout | undefined;
+        const settle = (
+          errorArg: Error | null,
+          responseArg?: IWebPushTransportResponse,
+        ) => {
+          if (settled) return;
+          settled = true;
+          if (requestTimer) clearTimeout(requestTimer);
+          if (errorArg) reject(errorArg);
+          else resolve(responseArg!);
+        };
+        const pushRequest = plugins.https.request({
+          protocol: 'https:',
+          hostname: resolved.hostname,
+          servername: resolved.hostname,
+          port: 443,
+          path: `${resolved.url.pathname}${resolved.url.search}`,
+          method: 'POST',
+          headers: requestDetails.headers,
+          agent,
+          timeout: Math.min(this.connectTimeoutMs, remainingRequestTimeoutMs),
+          maxHeaderSize: 16_384,
+          setHost: true,
+        }, (pushResponse) => {
+          let responseBytes = 0;
+          pushResponse.on('data', (chunkArg: Buffer | string) => {
+            responseBytes += Buffer.byteLength(chunkArg);
+            if (responseBytes > this.maxResponseBytes) {
+              const error = new WebPushTransportError('PUSH_RESPONSE_TOO_LARGE');
+              settle(error);
+              pushResponse.destroy(error);
+              pushRequest.destroy(error);
+            }
+          });
+          pushResponse.once('end', () => {
+            const statusCode = pushResponse.statusCode;
+            if (!Number.isSafeInteger(statusCode) || statusCode! < 100 || statusCode! > 599) {
+              settle(new WebPushTransportError('PUSH_RESPONSE_INVALID'));
+              return;
+            }
+            settle(null, {
+              statusCode: statusCode!,
+              retryAfter: normalizeRetryAfter(pushResponse.headers['retry-after']),
+            });
+          });
+          pushResponse.once('error', (errorArg) => {
+            settle(
+              errorArg instanceof WebPushTransportError
+                ? errorArg
+                : new WebPushTransportError('PUSH_NETWORK_ERROR', { cause: errorArg }),
+            );
+          });
+        });
+        pushRequest.once('timeout', () => {
+          const error = new WebPushTransportError('PUSH_REQUEST_TIMEOUT');
+          settle(error);
+          pushRequest.destroy(error);
+        });
+        pushRequest.once('error', (errorArg) => {
+          settle(
+            errorArg instanceof WebPushTransportError
+              ? errorArg
+              : new WebPushTransportError('PUSH_NETWORK_ERROR', { cause: errorArg }),
+          );
+        });
+        requestTimer = setTimeout(() => {
+          const error = new WebPushTransportError('PUSH_REQUEST_TIMEOUT');
+          settle(error);
+          pushRequest.destroy(error);
+        }, remainingRequestTimeoutMs);
+        requestTimer.unref();
+        pushRequest.end(requestDetails.body);
+      });
+    } finally {
+      agent.destroy();
+    }
+  }
+
+  private normalizePositiveInteger(
+    valueArg: number | undefined,
+    defaultArg: number,
+    labelArg: string,
+  ): number {
+    const value = valueArg ?? defaultArg;
+    if (!Number.isSafeInteger(value) || value <= 0) {
+      throw new Error(`Web Push transport ${labelArg} must be a positive integer`);
+    }
+    return value;
+  }
+}

package/ts/webpush/helpers.webpush-endpoint.ts

@@ -0,0 +1,150 @@
+import type { LookupFunction } from 'node:net';
+import * as plugins from '../plugins.js';
+
+export type TWebPushEndpointPolicyErrorCode =
+  | 'ENDPOINT_URL_INVALID'
+  | 'ENDPOINT_SCHEME_INVALID'
+  | 'ENDPOINT_PORT_INVALID'
+  | 'ENDPOINT_AUTHORITY_INVALID'
+  | 'ENDPOINT_FRAGMENT_INVALID'
+  | 'ENDPOINT_IP_LITERAL_FORBIDDEN'
+  | 'ENDPOINT_DNS_EMPTY'
+  | 'ENDPOINT_DNS_UNSAFE';
+
+export class WebPushEndpointPolicyError extends Error {
+  public constructor(public readonly code: TWebPushEndpointPolicyErrorCode) {
+    super(code);
+    this.name = 'WebPushEndpointPolicyError';
+  }
+}
+
+export interface IWebPushDnsAddress {
+  address: string;
+  family: number;
+}
+
+export type TWebPushDnsLookup = (
+  hostnameArg: string,
+) => Promise<IWebPushDnsAddress[]>;
+
+export interface IWebPushResolvedEndpoint {
+  url: URL;
+  hostname: string;
+  address: string;
+  family: 4 | 6;
+}
+
+const defaultDnsLookup: TWebPushDnsLookup = async (hostnameArg) => {
+  return await plugins.dns.promises.lookup(hostnameArg, {
+    all: true,
+    verbatim: true,
+  });
+};
+
+export function isGloballyRoutableWebPushAddress(addressArg: string): boolean {
+  const family = plugins.net.isIP(addressArg);
+  if (family !== 4 && family !== 6) return false;
+  try {
+    const parsed = plugins.ipaddr.parse(addressArg);
+    if (
+      parsed.kind() === 'ipv6'
+      && 'isIPv4MappedAddress' in parsed
+      && parsed.isIPv4MappedAddress()
+    ) return false;
+    return parsed.range() === 'unicast';
+  } catch {
+    return false;
+  }
+}
+
+export function parseWebPushEndpoint(endpointArg: string): URL {
+  if (typeof endpointArg !== 'string' || endpointArg.length === 0 || endpointArg.length > 4096) {
+    throw new WebPushEndpointPolicyError('ENDPOINT_URL_INVALID');
+  }
+  let endpoint: URL;
+  try {
+    endpoint = new URL(endpointArg);
+  } catch {
+    throw new WebPushEndpointPolicyError('ENDPOINT_URL_INVALID');
+  }
+  if (endpoint.protocol !== 'https:') {
+    throw new WebPushEndpointPolicyError('ENDPOINT_SCHEME_INVALID');
+  }
+  if (endpoint.port && endpoint.port !== '443') {
+    throw new WebPushEndpointPolicyError('ENDPOINT_PORT_INVALID');
+  }
+  if (endpoint.username || endpoint.password || !endpoint.hostname) {
+    throw new WebPushEndpointPolicyError('ENDPOINT_AUTHORITY_INVALID');
+  }
+  if (endpoint.hash) {
+    throw new WebPushEndpointPolicyError('ENDPOINT_FRAGMENT_INVALID');
+  }
+  const hostname = endpoint.hostname.startsWith('[') && endpoint.hostname.endsWith(']')
+    ? endpoint.hostname.slice(1, -1)
+    : endpoint.hostname;
+  if (plugins.net.isIP(hostname) !== 0) {
+    throw new WebPushEndpointPolicyError('ENDPOINT_IP_LITERAL_FORBIDDEN');
+  }
+  return endpoint;
+}
+
+export async function resolveWebPushEndpoint(
+  endpointArg: string,
+  lookupArg: TWebPushDnsLookup = defaultDnsLookup,
+): Promise<IWebPushResolvedEndpoint> {
+  const url = parseWebPushEndpoint(endpointArg);
+  const hostname = url.hostname.toLowerCase();
+  const answers = await lookupArg(hostname);
+  if (!Array.isArray(answers) || answers.length === 0) {
+    throw new WebPushEndpointPolicyError('ENDPOINT_DNS_EMPTY');
+  }
+  const normalized = answers.map((answerArg) => ({
+    address: String(answerArg.address || '').trim(),
+    family: plugins.net.isIP(String(answerArg.address || '').trim()),
+  }));
+  if (
+    normalized.some((answerArg) => (
+      (answerArg.family !== 4 && answerArg.family !== 6)
+      || !isGloballyRoutableWebPushAddress(answerArg.address)
+    ))
+  ) {
+    throw new WebPushEndpointPolicyError('ENDPOINT_DNS_UNSAFE');
+  }
+  const unique = Array.from(
+    new Map(normalized.map((answerArg) => [`${answerArg.family}:${answerArg.address}`, answerArg])).values(),
+  );
+  const selected = unique[0] as { address: string; family: 4 | 6 };
+  return {
+    url,
+    hostname,
+    address: selected.address,
+    family: selected.family,
+  };
+}
+
+export function createPinnedWebPushAgent(
+  resolvedArg: IWebPushResolvedEndpoint,
+): InstanceType<typeof plugins.https.Agent> {
+  const lookup: LookupFunction = (hostnameArg, optionsArg, callbackArg) => {
+    if (hostnameArg.toLowerCase() !== resolvedArg.hostname) {
+      const error = new Error('Pinned Web Push agent hostname mismatch') as NodeJS.ErrnoException;
+      error.code = 'EHOSTUNREACH';
+      callbackArg(error, '', 0);
+      return;
+    }
+    if (optionsArg.all) {
+      callbackArg(null, [{
+        address: resolvedArg.address,
+        family: resolvedArg.family,
+      }]);
+      return;
+    }
+    callbackArg(null, resolvedArg.address, resolvedArg.family);
+  };
+  return new plugins.https.Agent({
+    keepAlive: false,
+    maxSockets: 1,
+    maxFreeSockets: 0,
+    lookup,
+  });
+}

package/ts/webpush/index.ts

@@ -0,0 +1,4 @@
+export * from './classes.webpush-crypto.js';
+export * from './classes.webpush-manager.js';
+export * from './classes.webpush-transport.js';
+export * from './helpers.webpush-endpoint.js';

package/ts/webpush/webpush-indexes.ts

@@ -0,0 +1,141 @@
+export type TWebPushIndexCollection =
+  | 'WebPushBindingDoc'
+  | 'WebPushAdmissionDoc'
+  | 'WebPushSpoolDoc';
+
+export interface IWebPushIndexSpecification {
+  collection: TWebPushIndexCollection;
+  name: string;
+  key: Record<string, 1 | -1>;
+  unique?: true;
+  expireAfterSeconds?: number;
+  partialFilterExpression?: Record<string, unknown>;
+}
+
+export const webPushIndexSpecifications: IWebPushIndexSpecification[] = [
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_id_unique',
+    key: { id: 1 },
+    unique: true,
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_owner_unique',
+    key: {
+      ownerGatewayClientType: 1,
+      ownerGatewayClientId: 1,
+      ownerAppInstanceId: 1,
+    },
+    unique: true,
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_credential_unique',
+    key: { 'credential.id': 1 },
+    unique: true,
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_previous_credential_lookup',
+    key: { 'previousCredentials.id': 1 },
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_previous_credential_cleanup',
+    key: { 'previousCredentials.validUntil': 1 },
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_rotation_recovery_cleanup',
+    key: { 'credentialRotationRecovery.expiresAt': 1 },
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_vapid_status_cleanup',
+    key: { 'vapidKeys.status': 1 },
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_vapid_retire_after_cleanup',
+    key: { 'vapidKeys.retireAfter': 1 },
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_disabled_cleanup',
+    key: { enabled: 1, lifecycleGeneration: 1 },
+  },
+  {
+    collection: 'WebPushBindingDoc',
+    name: 'web_push_binding_deleted_cleanup',
+    key: { deletedAt: 1, lifecycleGeneration: 1 },
+  },
+  {
+    collection: 'WebPushAdmissionDoc',
+    name: 'web_push_admission_binding_unique',
+    key: { bindingId: 1, lifecycleGeneration: 1 },
+    unique: true,
+  },
+  {
+    collection: 'WebPushAdmissionDoc',
+    name: 'web_push_admission_ttl',
+    key: { purgeAt: 1 },
+    expireAfterSeconds: 0,
+  },
+  {
+    collection: 'WebPushSpoolDoc',
+    name: 'web_push_spool_id_unique',
+    key: { id: 1 },
+    unique: true,
+  },
+  {
+    collection: 'WebPushSpoolDoc',
+    name: 'web_push_spool_idempotency_unique',
+    key: {
+      bindingId: 1,
+      lifecycleGeneration: 1,
+      credentialId: 1,
+      idempotencyKeyDigest: 1,
+    },
+    unique: true,
+  },
+  {
+    collection: 'WebPushSpoolDoc',
+    name: 'web_push_spool_delivery_scan',
+    key: { state: 1, nextAttemptAt: 1, leaseExpiresAt: 1 },
+  },
+  {
+    collection: 'WebPushSpoolDoc',
+    name: 'web_push_spool_cancellation_scan',
+    key: { bindingId: 1, lifecycleGeneration: 1, subscriptionId: 1, state: 1 },
+  },
+  {
+    collection: 'WebPushSpoolDoc',
+    name: 'web_push_spool_cancelled_lease_scan',
+    key: { state: 1, cancelRequestedAt: 1, leaseExpiresAt: 1, id: 1 },
+  },
+  {
+    collection: 'WebPushSpoolDoc',
+    name: 'web_push_spool_lifecycle_drain_scan',
+    key: { bindingId: 1, lifecycleGeneration: 1, state: 1, leaseExpiresAt: 1 },
+  },
+  {
+    collection: 'WebPushSpoolDoc',
+    name: 'web_push_spool_vapid_retirement_scan',
+    key: { bindingId: 1, lifecycleGeneration: 1, vapidKeyId: 1, state: 1 },
+  },
+  {
+    collection: 'WebPushSpoolDoc',
+    name: 'web_push_spool_terminal_ttl',
+    key: { purgeAt: 1 },
+    expireAfterSeconds: 0,
+  },
+];
+
+export function getWebPushIndexSpecifications(
+  collectionArg: TWebPushIndexCollection,
+): IWebPushIndexSpecification[] {
+  return webPushIndexSpecifications.filter(
+    (specificationArg) => specificationArg.collection === collectionArg,
+  );
+}

package/ts_web/00_commitinfo_data.ts

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

package/readme.plan.md

@@ -1,22 +0,0 @@
-# Platform refactoring program
-
-Status: approved 2026-07-21, derived from that day's incident ledger (deploy-verification crashes, unbounded scans, DNS/IP logic duplication, version-skew scares). Upstream foundations are RELEASED; consumer adoption and the dcrouter-internal refactors are sequenced below — do not start them mid-wave, fold them into the next natural release of each surface.
-
-## Shipped upstream (adopt on next dependency bump)
-
-1. **Typed-request error boundary — already existed.** @api.global/typedrequest ≥ 3.3.2 sanitizes every handler/middleware throw into a structured error envelope (no socket destruction). Action: ensure every deployed consumer (cloudly, dcrouter, coreflow, onebox) resolves ≥ 3.3.2 and remove any local try/catch layers that only re-implement it.
-2. **Canonical IP helpers — @push.rocks/smartnetwork 4.9.0.** `isPublicIpAddress`, `toReverseDnsName` (non-throwing), `expandIpv6`, alongside the existing `getIpVersion`/`isValidIpv4`/`isValidIpv6`. Adoption: dcrouter ts/email/classes.mail-dns-sync.ts drops its private `toReverseDnsName`/`expandIpv6` (and the `Invalid IP address:` throw); cloudly's `isPublicDeploymentAddress` (classes.deploymentoperationmanager.ts) delegates to `isPublicIpAddress` (IPv4 semantics are byte-identical; IPv6 is 2000::/3 minus 2001:db8::/32).
-3. **Cursor pagination as the org default — @push.rocks/smartdata 7.4.0.** `SmartDataDbDoc.getPagedInstances({ filter, sortField, sortDirection, uniqueField, limit ≤ 1000, cursor, withTotal })` — seek pagination with a unique tiebreaker, never materializes the full set. Adoption: OpsConfigEventDoc.findFiltered becomes a thin wrapper; every future list surface uses it. Review rule: a list API without a cursor is a defect.
-4. **Binary provenance — @git.zone/tsrust 1.7.0.** Every built binary gets a JSON trailer (project, version, git commit, target, builtAt, tsrust version); `tsrust inspect <binary>` prints it. Adoption: bump tsrust across the Rust-bridge repos (smartdb, smartproxy, smartmta, smartnetwork, coretraffic, remoteingress) on their next releases; deployment verification can then assert binary identity instead of guessing (see the strings-on-x86 pitfall in smartdb readme.hints.md).
-
-## Sequenced (do NOT start mid-wave)
-
-5. **Ops-handler base class (dcrouter).** 25 handler files carry 11 copies of the requireAuth wrapper and 49 hand-written "manager not initialized" guards. Introduce a base with `registerMethod(name, scope, handlerFn)` doing auth, manager guard, error boundary, and realtime invalidation; migrate handlers opportunistically (new handlers must use it; old ones migrate when touched).
-6. **Composition-root service table (dcrouter).** classes.dcrouter.ts (2,326 lines) has 20 near-identical addService blocks with drift (withRetry presence, error logging). Replace with a declarative registration table; behavior-preserving.
-7. **Mail-detail contract dedup (interfaces + catalog + dcrouter).** IEmailDetail and friends exist twice by convention ("matches @serve.zone/catalog"). Move the contract into @serve.zone/interfaces; catalog and dcrouter consume it. Sequence AFTER the in-flight mail-detail wave (countdown, verdicts, transfer stats) fully lands — one migration wave, no compatibility layer.
-8. **Version-skew hardening (conventions).** (a) Tolerant-reader parsing for persisted operation/evidence/state documents that cross release boundaries; (b) version handshake wherever a live process or socket is reused across upgrades (LocalSmartDb engine reuse — smartdb plan Track 6; gateway-client policyGeneration is the precedent).
-
-## Non-goals
-
-- No big-bang rewrites: every item lands either additive-upstream or inside a surface's next natural release.
-- No compatibility layers (org rule): consumers move to the canonical helpers outright when their wave touches the code.