@serfab/cadre-core 0.9.0 → 0.11.0

package/src/peer-record.ts

@@ -1,146 +1,164 @@
-/**
- * Peer-address record helpers: the single source of truth for the bytes a node
- * signs when publishing its own `CadrePeer` row and re-verifies when resolving
- * another peer's row.
- *
- * The signed payload is a single SHA-256 digest of a delimited string of the
- * authenticated fields. It is intentionally NOT JSON-canonicalized: a delimited
- * digest is trivially deterministic across node/browser/RN (plain string concat
- * + sha256, no key ordering) and — crucially — is reconstructable inside the
- * `CadrePeer.AuthorizedUpdate` SQL constraint from the row's own columns:
- *
- *   digest(new.PeerId || '|' || new.Multiaddr || '|' || cast(new.UpdatedAt as text))
- *
- * Keep {@link peerRecordSignedPayload} and that constraint byte-for-byte in
- * sync. The `'|'` delimiter is safe: a base58btc PeerId, a multiaddr (which uses
- * `/`), and a base-10 integer never contain it.
- *
- * `publicKey` is deliberately excluded from the payload — it is the key the
- * signature is verified *with* (so a signature already commits to exactly one
- * key), and its binding to `peerId` is checked separately at resolve time.
- */
-
-import { digest, sign, verify } from '@optimystic/quereus-plugin-crypto';
-import type { PeerAddressRecord, PeerResolveTrustPolicy } from './types.js';
-
-/**
- * Default freshness ceiling for resolved peer-address records (15 minutes).
- * A record older than this is treated as stale and filtered out, so a resolver
- * never hands back a dead relay reservation. The publish path re-stamps at
- * roughly half this interval (see {@link DEFAULT_PEER_RECORD_HEARTBEAT_MS}).
- */
-export const DEFAULT_PEER_RECORD_MAX_AGE_MS = 15 * 60 * 1000;
-
-/**
- * TTL heartbeat interval for re-publishing the self record — half the freshness
- * ceiling, so a record is refreshed well before it can go stale.
- */
-export const DEFAULT_PEER_RECORD_HEARTBEAT_MS = DEFAULT_PEER_RECORD_MAX_AGE_MS / 2;
-
-/** The signaling/relay prefix a WebRTC (or any relayed) dial path consumes. */
-const SIGNALING_PREFIX = '/p2p-circuit';
-
-/**
- * Build the base64url SHA-256 digest that the self-signature covers. Mirrors the
- * `CadrePeer.AuthorizedUpdate` constraint exactly; both sides take the default
- * base64url output of a single `digest(...)`, which round-trips cleanly (unlike
- * concatenating several base64url digests).
- *
- * @param peerId - base58btc libp2p peer id (the row key)
- * @param multiaddr - the comma-joined `Multiaddr` string EXACTLY as stored
- * @param updatedAt - epoch-ms freshness stamp
- */
-export function peerRecordSignedPayload(peerId: string, multiaddr: string, updatedAt: number): string {
-  const joined = `${peerId}|${multiaddr}|${updatedAt}`;
-  return digest([joined], 'sha256', 'base64url') as string;
-}
-
-/**
- * Sign a peer-address record with the ed25519 private key behind its `peerId`.
- * Returns a fully-populated {@link PeerAddressRecord} (the `addrs` order is
- * preserved and is the order signed over).
- *
- * @param fields - the record fields to sign (signaling addr first by convention)
- * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
- */
-export function signPeerRecord(
-  fields: { peerId: string; publicKey: string; addrs: string[]; updatedAt: number },
-  privateKeyB64: string
-): PeerAddressRecord {
-  const payloadDigest = peerRecordSignedPayload(fields.peerId, fields.addrs.join(','), fields.updatedAt);
-  const sig = sign(
-    payloadDigest,
-    privateKeyB64,
-    'ed25519',
-    'base64url',
-    'base64url',
-    'base64url'
-  ) as string;
-  return { peerId: fields.peerId, publicKey: fields.publicKey, addrs: [...fields.addrs], updatedAt: fields.updatedAt, sig };
-}
-
-/**
- * Verify a record's self-signature against its own `publicKey`. Reconstructs the
- * signed bytes from the record exactly as {@link signPeerRecord} produced them.
- * Returns false on a missing key/sig or any verification failure.
- */
-export function verifyPeerRecordSignature(record: PeerAddressRecord): boolean {
-  if (!record.publicKey || !record.sig) {
-    return false;
-  }
-  const payloadDigest = peerRecordSignedPayload(record.peerId, record.addrs.join(','), record.updatedAt);
-  return verify(
-    payloadDigest,
-    record.sig,
-    record.publicKey,
-    'ed25519',
-    'base64url',
-    'base64url',
-    'base64url'
-  );
-}
-
-/**
- * Freshness predicate: true when `updatedAt` is a positive stamp within
- * `maxAgeMs` of `now`. A non-positive `updatedAt` (never self-published) is
- * never fresh.
- */
-export function isPeerRecordFresh(updatedAt: number, maxAgeMs: number, now: number): boolean {
-  if (!(updatedAt > 0)) {
-    return false;
-  }
-  return now - updatedAt <= maxAgeMs;
-}
-
-/** True if `addr` is a `/p2p-circuit` signaling/relay multiaddr. */
-export function isSignalingAddr(addr: string): boolean {
-  return addr.includes(SIGNALING_PREFIX);
-}
-
-/**
- * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
- * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate
- * the input and must not be used before signature verification (verification
- * uses the original on-record order).
- */
-export function orderSignalingFirst(addrs: string[]): string[] {
-  const signaling = addrs.filter(isSignalingAddr);
-  const rest = addrs.filter(a => !isSignalingAddr(a));
-  return [...signaling, ...rest];
-}
-
-/**
- * Default resolve trust gate: trust any peer that has a `CadrePeer` row.
- *
- * A row only exists because an owner signed its `AuthorizedInsert`, so row
- * presence already means "owner-vouched member". This is the seam where a
- * stricter policy (trust circle, pinned keys) plugs in — see
- * {@link PeerResolveTrustPolicy}.
- */
-export function currentMemberTrustPolicy(): PeerResolveTrustPolicy {
-  return {
-    evaluate() {
-      return true;
-    },
-  };
-}
+/**
+ * Peer-address record helpers: the single source of truth for the bytes a node
+ * signs when publishing its own `CadrePeer` row and re-verifies when resolving
+ * another peer's row.
+ *
+ * The signed payload is a single SHA-256 digest over the shared domain-tagged
+ * field vector (see control-authorization.ts) — the crypto plugin's injective
+ * multi-field encoding, so no field split is ambiguous. It is intentionally NOT
+ * JSON-canonicalized (deterministic across node/browser/RN, no key ordering)
+ * and — crucially — is reconstructable inside the `CadrePeer.AuthorizedUpdate`
+ * SQL constraint from the row's own columns:
+ *
+ *   digest('CadreControl.CadrePeer', 'publish',
+ *          new.PeerId, new.Multiaddr, cast(new.UpdatedAt as text))
+ *
+ * Keep {@link peerRecordSignedPayload} and that constraint byte-for-byte in
+ * sync. The `'publish'` action tag marks this as a peer's SELF-signed record
+ * (signed with the peer's own key, not an owner key) and keeps it disjoint from
+ * every owner-signed digest.
+ *
+ * `publicKey` is deliberately excluded from the payload — it is the key the
+ * signature is verified *with* (so a signature already commits to exactly one
+ * key), and its binding to `peerId` is checked separately at resolve time.
+ */
+
+import type { Multiaddr } from '@multiformats/multiaddr';
+import { digest, sign, verify } from '@optimystic/quereus-plugin-crypto';
+import { controlAuthorizationFields } from './control-authorization.js';
+import type { PeerAddressRecord, PeerResolveTrustPolicy } from './types.js';
+
+/**
+ * Default freshness ceiling for resolved peer-address records (15 minutes).
+ * A record older than this is treated as stale and filtered out, so a resolver
+ * never hands back a dead relay reservation. The publish path re-stamps at
+ * roughly half this interval (see {@link DEFAULT_PEER_RECORD_HEARTBEAT_MS}).
+ */
+export const DEFAULT_PEER_RECORD_MAX_AGE_MS = 15 * 60 * 1000;
+
+/**
+ * TTL heartbeat interval for re-publishing the self record — half the freshness
+ * ceiling, so a record is refreshed well before it can go stale.
+ */
+export const DEFAULT_PEER_RECORD_HEARTBEAT_MS = DEFAULT_PEER_RECORD_MAX_AGE_MS / 2;
+
+/** The signaling/relay prefix a WebRTC (or any relayed) dial path consumes. */
+const SIGNALING_PREFIX = '/p2p-circuit';
+
+/**
+ * Build the base64url SHA-256 digest that the self-signature covers. Mirrors the
+ * `CadrePeer.AuthorizedUpdate` constraint exactly; both sides take the default
+ * base64url output of a single `digest(...)`, which round-trips cleanly (unlike
+ * concatenating several base64url digests).
+ *
+ * @param peerId - base58btc libp2p peer id (the row key)
+ * @param multiaddr - the comma-joined `Multiaddr` string EXACTLY as stored
+ * @param updatedAt - epoch-ms freshness stamp
+ */
+export function peerRecordSignedPayload(peerId: string, multiaddr: string, updatedAt: number): string {
+  const fields = controlAuthorizationFields('CadreControl.CadrePeer', 'publish', [peerId, multiaddr, String(updatedAt)]);
+  return digest(fields, 'sha256', 'base64url') as string;
+}
+
+/**
+ * Sign a peer-address record with the ed25519 private key behind its `peerId`.
+ * Returns a fully-populated {@link PeerAddressRecord} (the `addrs` order is
+ * preserved and is the order signed over).
+ *
+ * @param fields - the record fields to sign (signaling addr first by convention)
+ * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
+ */
+export function signPeerRecord(
+  fields: { peerId: string; publicKey: string; addrs: string[]; updatedAt: number },
+  privateKeyB64: string
+): PeerAddressRecord {
+  const payloadDigest = peerRecordSignedPayload(fields.peerId, fields.addrs.join(','), fields.updatedAt);
+  const sig = sign(
+    payloadDigest,
+    privateKeyB64,
+    'ed25519',
+    'base64url',
+    'base64url',
+    'base64url'
+  ) as string;
+  return { peerId: fields.peerId, publicKey: fields.publicKey, addrs: [...fields.addrs], updatedAt: fields.updatedAt, sig };
+}
+
+/**
+ * Verify a record's self-signature against its own `publicKey`. Reconstructs the
+ * signed bytes from the record exactly as {@link signPeerRecord} produced them.
+ * Returns false on a missing key/sig or any verification failure.
+ */
+export function verifyPeerRecordSignature(record: PeerAddressRecord): boolean {
+  if (!record.publicKey || !record.sig) {
+    return false;
+  }
+  const payloadDigest = peerRecordSignedPayload(record.peerId, record.addrs.join(','), record.updatedAt);
+  return verify(
+    payloadDigest,
+    record.sig,
+    record.publicKey,
+    'ed25519',
+    'base64url',
+    'base64url',
+    'base64url'
+  );
+}
+
+/**
+ * Freshness predicate: true when `updatedAt` is a positive stamp within
+ * `maxAgeMs` of `now`. A non-positive `updatedAt` (never self-published) is
+ * never fresh.
+ */
+export function isPeerRecordFresh(updatedAt: number, maxAgeMs: number, now: number): boolean {
+  if (!(updatedAt > 0)) {
+    return false;
+  }
+  return now - updatedAt <= maxAgeMs;
+}
+
+/** True if `addr` is a `/p2p-circuit` signaling/relay multiaddr. */
+export function isSignalingAddr(addr: string): boolean {
+  return addr.includes(SIGNALING_PREFIX);
+}
+
+/**
+ * The peer id a multiaddr terminates in, or `null` when it names none.
+ *
+ * The LAST `/p2p/` component is the dial target: a circuit address
+ * (`…/p2p/<relay>/p2p-circuit/p2p/<target>`) names the relay first and the peer
+ * being reached last. Replaces the deprecated `Multiaddr.getPeerId()`, which
+ * cannot express that distinction.
+ */
+export function trailingPeerId(addr: Multiaddr): string | null {
+  const p2p = addr.getComponents().filter((c) => c.name === 'p2p');
+  return p2p.length > 0 ? (p2p[p2p.length - 1].value ?? null) : null;
+}
+
+/**
+ * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
+ * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate
+ * the input and must not be used before signature verification (verification
+ * uses the original on-record order).
+ */
+export function orderSignalingFirst(addrs: string[]): string[] {
+  const signaling = addrs.filter(isSignalingAddr);
+  const rest = addrs.filter(a => !isSignalingAddr(a));
+  return [...signaling, ...rest];
+}
+
+/**
+ * Default resolve trust gate: trust any peer that has a `CadrePeer` row.
+ *
+ * A row only exists because an owner signed its `AuthorizedInsert`, so row
+ * presence already means "owner-vouched member". This is the seam where a
+ * stricter policy (trust circle, pinned keys) plugs in — see
+ * {@link PeerResolveTrustPolicy}.
+ */
+export function currentMemberTrustPolicy(): PeerResolveTrustPolicy {
+  return {
+    evaluate() {
+      return true;
+    },
+  };
+}

package/src/push-credentials.ts

@@ -1,84 +1,84 @@
-/**
- * push-credentials.ts — pure validation + log-redaction for {@link PushCredentials}.
- *
- * The platform-push credentials a deployment provisions (`cadre-host` from its
- * secret store, `cadre-provider` from per-tenant config) are written into a
- * spawned node's config under `CadreNodeConfig.push`. This module is the
- * dependency-free seam those provisioners share to (a) reject a *partial* set
- * before it reaches a node — a present platform block must carry all its required
- * fields, or it fails fast at provisioning rather than at first push — and (b)
- * produce a log-safe view that never leaks a private key.
- *
- * It imports only the *types* (erased at emit), so it pulls no node:crypto /
- * node:http2 edge — a provisioner can import these functions without dragging in
- * the FCM/APNs senders.
- */
-
-import type { PushCredentials, FcmCredentials, ApnsCredentials } from './types.js';
-
-/** Marker substituted for every secret field by {@link redactPushCredentials}. */
-export const REDACTED = '[redacted]';
-
-/**
- * Validate a resolved push-credential bundle, returning human-readable errors
- * (empty ⇒ valid). Each platform block is optional, but a *present* block must
- * carry every required field — a partial set (e.g. APNs `keyId` without
- * `privateKey`) is a misconfiguration that must surface at provisioning time, not
- * silently at the first wake. A bundle with neither platform is valid (push is
- * opt-in); callers that require at least one platform check that separately.
- */
-export function validatePushCredentials(push: PushCredentials): string[] {
-  const errors: string[] = [];
-  if (push.fcm) errors.push(...validateFcm(push.fcm));
-  if (push.apns) errors.push(...validateApns(push.apns));
-  return errors;
-}
-
-function validateFcm(fcm: FcmCredentials): string[] {
-  return missingFields('fcm', fcm as unknown as Record<string, unknown>, [
-    'projectId',
-    'clientEmail',
-    'privateKey',
-  ]);
-}
-
-function validateApns(apns: ApnsCredentials): string[] {
-  return missingFields('apns', apns as unknown as Record<string, unknown>, [
-    'keyId',
-    'teamId',
-    'bundleId',
-    'privateKey',
-  ]);
-}
-
-/** Names the required fields of `platform` that are missing or blank. */
-function missingFields(platform: string, obj: Record<string, unknown>, required: string[]): string[] {
-  return required
-    .filter((f) => typeof obj[f] !== 'string' || (obj[f] as string).trim().length === 0)
-    .map((f) => `push.${platform}.${f} is required when a ${platform} credential block is present`);
-}
-
-/**
- * Return a log-safe shallow copy of a push bundle with every private key replaced
- * by {@link REDACTED}. Use this for ANY debug/log line that touches push config —
- * `privateKey` fields are secrets and must never reach a log sink (the same rule
- * the startup/seed tokens follow).
- */
-export function redactPushCredentials(push: PushCredentials): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  if (push.fcm) {
-    out.fcm = { projectId: push.fcm.projectId, clientEmail: push.fcm.clientEmail, privateKey: REDACTED };
-  }
-  if (push.apns) {
-    out.apns = {
-      keyId: push.apns.keyId,
-      teamId: push.apns.teamId,
-      bundleId: push.apns.bundleId,
-      ...(push.apns.production !== undefined ? { production: push.apns.production } : {}),
-      privateKey: REDACTED,
-    };
-  }
-  if (push.cooldownMs !== undefined) out.cooldownMs = push.cooldownMs;
-  if (push.debounceMs !== undefined) out.debounceMs = push.debounceMs;
-  return out;
-}
+/**
+ * push-credentials.ts — pure validation + log-redaction for {@link PushCredentials}.
+ *
+ * The platform-push credentials a deployment provisions (`cadre-host` from its
+ * secret store, `cadre-provider` from per-tenant config) are written into a
+ * spawned node's config under `CadreNodeConfig.push`. This module is the
+ * dependency-free seam those provisioners share to (a) reject a *partial* set
+ * before it reaches a node — a present platform block must carry all its required
+ * fields, or it fails fast at provisioning rather than at first push — and (b)
+ * produce a log-safe view that never leaks a private key.
+ *
+ * It imports only the *types* (erased at emit), so it pulls no node:crypto /
+ * node:http2 edge — a provisioner can import these functions without dragging in
+ * the FCM/APNs senders.
+ */
+
+import type { PushCredentials, FcmCredentials, ApnsCredentials } from './types.js';
+
+/** Marker substituted for every secret field by {@link redactPushCredentials}. */
+export const REDACTED = '[redacted]';
+
+/**
+ * Validate a resolved push-credential bundle, returning human-readable errors
+ * (empty ⇒ valid). Each platform block is optional, but a *present* block must
+ * carry every required field — a partial set (e.g. APNs `keyId` without
+ * `privateKey`) is a misconfiguration that must surface at provisioning time, not
+ * silently at the first wake. A bundle with neither platform is valid (push is
+ * opt-in); callers that require at least one platform check that separately.
+ */
+export function validatePushCredentials(push: PushCredentials): string[] {
+  const errors: string[] = [];
+  if (push.fcm) errors.push(...validateFcm(push.fcm));
+  if (push.apns) errors.push(...validateApns(push.apns));
+  return errors;
+}
+
+function validateFcm(fcm: FcmCredentials): string[] {
+  return missingFields('fcm', fcm as unknown as Record<string, unknown>, [
+    'projectId',
+    'clientEmail',
+    'privateKey',
+  ]);
+}
+
+function validateApns(apns: ApnsCredentials): string[] {
+  return missingFields('apns', apns as unknown as Record<string, unknown>, [
+    'keyId',
+    'teamId',
+    'bundleId',
+    'privateKey',
+  ]);
+}
+
+/** Names the required fields of `platform` that are missing or blank. */
+function missingFields(platform: string, obj: Record<string, unknown>, required: string[]): string[] {
+  return required
+    .filter((f) => typeof obj[f] !== 'string' || (obj[f] as string).trim().length === 0)
+    .map((f) => `push.${platform}.${f} is required when a ${platform} credential block is present`);
+}
+
+/**
+ * Return a log-safe shallow copy of a push bundle with every private key replaced
+ * by {@link REDACTED}. Use this for ANY debug/log line that touches push config —
+ * `privateKey` fields are secrets and must never reach a log sink (the same rule
+ * the startup/seed tokens follow).
+ */
+export function redactPushCredentials(push: PushCredentials): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (push.fcm) {
+    out.fcm = { projectId: push.fcm.projectId, clientEmail: push.fcm.clientEmail, privateKey: REDACTED };
+  }
+  if (push.apns) {
+    out.apns = {
+      keyId: push.apns.keyId,
+      teamId: push.apns.teamId,
+      bundleId: push.apns.bundleId,
+      ...(push.apns.production !== undefined ? { production: push.apns.production } : {}),
+      privateKey: REDACTED,
+    };
+  }
+  if (push.cooldownMs !== undefined) out.cooldownMs = push.cooldownMs;
+  if (push.debounceMs !== undefined) out.debounceMs = push.debounceMs;
+  return out;
+}

package/src/push-node.ts

@@ -1,64 +1,64 @@
-/**
- * push-node.ts — Node-only subpath entry for platform push **construction**.
- *
- * Import from the dedicated subpath, never the package root:
- *
- * ```ts
- * import { createPushNotifier } from '@serfab/cadre-core/push-node';
- * ```
- *
- * The FCM/APNs implementations reach for `node:crypto` / `node:http2`, so they
- * are quarantined here — unreachable from the cross-platform `./index.js` graph
- * (same isolation pattern as `./key-store-file`). A React Native / browser entry
- * never resolves this path, so the Node builtins never reach a bundler that
- * cannot satisfy them. The core references only the {@link PushNotifier}
- * *interface* (`push-notifier.ts`) and a Node host injects the instance built
- * here into `CadreNodeConfig.push.notifier`.
- */
-
-import type { PushCredentials, PushPlatform } from './types.js';
-import type { PushMessage, PushNotifier, PushSendResult } from './push-notifier.js';
-import { createFcmPushNotifier, type FcmPushDeps } from './push-notifier-fcm.js';
-import { createApnsPushNotifier, type ApnsPushDeps } from './push-notifier-apns.js';
-
-/**
- * Per-platform transport/clock/log seams, injected by tests. Defaults are the
- * real implementations (global `fetch` for FCM, a `node:http2` session for APNs).
- */
-export interface PushNotifierDeps {
-  fcm?: FcmPushDeps;
-  apns?: ApnsPushDeps;
-}
-
-/**
- * Build a {@link PushNotifier} router over the configured credentials. Only the
- * platforms whose credentials are present get a backing implementation; a `send`
- * for an unconfigured platform returns a best-effort `no <platform> credentials`
- * failure rather than throwing.
- */
-export function createPushNotifier(creds: PushCredentials, deps: PushNotifierDeps = {}): PushNotifier {
-  const fcm = creds.fcm ? createFcmPushNotifier(creds.fcm, deps.fcm) : undefined;
-  const apns = creds.apns ? createApnsPushNotifier(creds.apns, deps.apns) : undefined;
-
-  async function send(msg: PushMessage): Promise<PushSendResult> {
-    if (msg.platform === 'fcm') return fcm ? fcm.send(msg) : noCreds('fcm');
-    if (msg.platform === 'apns') return apns ? apns.send(msg) : noCreds('apns');
-    return { ok: false, unregistered: false, error: `unknown platform ${String(msg.platform)}` };
-  }
-
-  async function close(): Promise<void> {
-    await Promise.all([fcm?.close(), apns?.close()]);
-  }
-
-  return { send, close };
-}
-
-/** Best-effort no-op result for a platform with no configured credentials. */
-function noCreds(platform: PushPlatform): PushSendResult {
-  return { ok: false, unregistered: false, error: `no ${platform} credentials` };
-}
-
-// Per-platform builders + their injected-dep types, for a host that wants a
-// single-platform notifier or to inject a fake transport directly.
-export { createFcmPushNotifier, createApnsPushNotifier };
-export type { FcmPushDeps, ApnsPushDeps };
+/**
+ * push-node.ts — Node-only subpath entry for platform push **construction**.
+ *
+ * Import from the dedicated subpath, never the package root:
+ *
+ * ```ts
+ * import { createPushNotifier } from '@serfab/cadre-core/push-node';
+ * ```
+ *
+ * The FCM/APNs implementations reach for `node:crypto` / `node:http2`, so they
+ * are quarantined here — unreachable from the cross-platform `./index.js` graph
+ * (same isolation pattern as `./key-store-file`). A React Native / browser entry
+ * never resolves this path, so the Node builtins never reach a bundler that
+ * cannot satisfy them. The core references only the {@link PushNotifier}
+ * *interface* (`push-notifier.ts`) and a Node host injects the instance built
+ * here into `CadreNodeConfig.push.notifier`.
+ */
+
+import type { PushCredentials, PushPlatform } from './types.js';
+import type { PushMessage, PushNotifier, PushSendResult } from './push-notifier.js';
+import { createFcmPushNotifier, type FcmPushDeps } from './push-notifier-fcm.js';
+import { createApnsPushNotifier, type ApnsPushDeps } from './push-notifier-apns.js';
+
+/**
+ * Per-platform transport/clock/log seams, injected by tests. Defaults are the
+ * real implementations (global `fetch` for FCM, a `node:http2` session for APNs).
+ */
+export interface PushNotifierDeps {
+  fcm?: FcmPushDeps;
+  apns?: ApnsPushDeps;
+}
+
+/**
+ * Build a {@link PushNotifier} router over the configured credentials. Only the
+ * platforms whose credentials are present get a backing implementation; a `send`
+ * for an unconfigured platform returns a best-effort `no <platform> credentials`
+ * failure rather than throwing.
+ */
+export function createPushNotifier(creds: PushCredentials, deps: PushNotifierDeps = {}): PushNotifier {
+  const fcm = creds.fcm ? createFcmPushNotifier(creds.fcm, deps.fcm) : undefined;
+  const apns = creds.apns ? createApnsPushNotifier(creds.apns, deps.apns) : undefined;
+
+  async function send(msg: PushMessage): Promise<PushSendResult> {
+    if (msg.platform === 'fcm') return fcm ? fcm.send(msg) : noCreds('fcm');
+    if (msg.platform === 'apns') return apns ? apns.send(msg) : noCreds('apns');
+    return { ok: false, unregistered: false, error: `unknown platform ${String(msg.platform)}` };
+  }
+
+  async function close(): Promise<void> {
+    await Promise.all([fcm?.close(), apns?.close()]);
+  }
+
+  return { send, close };
+}
+
+/** Best-effort no-op result for a platform with no configured credentials. */
+function noCreds(platform: PushPlatform): PushSendResult {
+  return { ok: false, unregistered: false, error: `no ${platform} credentials` };
+}
+
+// Per-platform builders + their injected-dep types, for a host that wants a
+// single-platform notifier or to inject a fake transport directly.
+export { createFcmPushNotifier, createApnsPushNotifier };
+export type { FcmPushDeps, ApnsPushDeps };