@serfab/cadre-core 0.7.1 → 0.8.1

package/dist/peer-record.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 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 declare const DEFAULT_PEER_RECORD_MAX_AGE_MS: number;
+/**
+ * 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 declare const DEFAULT_PEER_RECORD_HEARTBEAT_MS: number;
+/**
+ * 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 declare function peerRecordSignedPayload(peerId: string, multiaddr: string, updatedAt: number): 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 `authorityKeyFromLibp2p`)
+ */
+export declare function signPeerRecord(fields: {
+    peerId: string;
+    publicKey: string;
+    addrs: string[];
+    updatedAt: number;
+}, privateKeyB64: string): PeerAddressRecord;
+/**
+ * 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 declare function verifyPeerRecordSignature(record: PeerAddressRecord): boolean;
+/**
+ * Freshness predicate: true when `updatedAt` is a positive stamp within
+ * `maxAgeMs` of `now`. A non-positive `updatedAt` (never self-published) is
+ * never fresh.
+ */
+export declare function isPeerRecordFresh(updatedAt: number, maxAgeMs: number, now: number): boolean;
+/** True if `addr` is a `/p2p-circuit` signaling/relay multiaddr. */
+export declare function isSignalingAddr(addr: string): boolean;
+/**
+ * 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 declare function orderSignalingFirst(addrs: string[]): string[];
+/**
+ * Default resolve trust gate: trust any peer that has a `CadrePeer` row.
+ *
+ * A row only exists because an authority signed its `AuthorizedInsert`, so row
+ * presence already means "authority-vouched member". This is the seam where a
+ * stricter policy (trust circle, pinned keys) plugs in — see
+ * {@link PeerResolveTrustPolicy}.
+ */
+export declare function currentMemberTrustPolicy(): PeerResolveTrustPolicy;

package/dist/peer-record.js

@@ -0,0 +1,117 @@
+/**
+ * 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';
+/**
+ * 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, multiaddr, updatedAt) {
+    const joined = `${peerId}|${multiaddr}|${updatedAt}`;
+    return digest([joined], 'sha256', 'base64url');
+}
+/**
+ * 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 `authorityKeyFromLibp2p`)
+ */
+export function signPeerRecord(fields, privateKeyB64) {
+    const payloadDigest = peerRecordSignedPayload(fields.peerId, fields.addrs.join(','), fields.updatedAt);
+    const sig = sign(payloadDigest, privateKeyB64, 'ed25519', 'base64url', 'base64url', 'base64url');
+    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) {
+    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, maxAgeMs, now) {
+    if (!(updatedAt > 0)) {
+        return false;
+    }
+    return now - updatedAt <= maxAgeMs;
+}
+/** True if `addr` is a `/p2p-circuit` signaling/relay multiaddr. */
+export function isSignalingAddr(addr) {
+    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) {
+    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 authority signed its `AuthorizedInsert`, so row
+ * presence already means "authority-vouched member". This is the seam where a
+ * stricter policy (trust circle, pinned keys) plugs in — see
+ * {@link PeerResolveTrustPolicy}.
+ */
+export function currentMemberTrustPolicy() {
+    return {
+        evaluate() {
+            return true;
+        },
+    };
+}
+//# sourceMappingURL=peer-record.js.map

package/dist/peer-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-record.js","sourceRoot":"","sources":["../src/peer-record.ts"],"names":[],"mappings":"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"}

package/dist/push-credentials.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 } from './types.js';
+/** Marker substituted for every secret field by {@link redactPushCredentials}. */
+export declare 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 declare function validatePushCredentials(push: PushCredentials): string[];
+/**
+ * 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 declare function redactPushCredentials(push: PushCredentials): Record<string, unknown>;

package/dist/push-credentials.js

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+/** 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) {
+    const errors = [];
+    if (push.fcm)
+        errors.push(...validateFcm(push.fcm));
+    if (push.apns)
+        errors.push(...validateApns(push.apns));
+    return errors;
+}
+function validateFcm(fcm) {
+    return missingFields('fcm', fcm, [
+        'projectId',
+        'clientEmail',
+        'privateKey',
+    ]);
+}
+function validateApns(apns) {
+    return missingFields('apns', apns, [
+        'keyId',
+        'teamId',
+        'bundleId',
+        'privateKey',
+    ]);
+}
+/** Names the required fields of `platform` that are missing or blank. */
+function missingFields(platform, obj, required) {
+    return required
+        .filter((f) => typeof obj[f] !== 'string' || obj[f].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) {
+    const out = {};
+    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;
+}
+//# sourceMappingURL=push-credentials.js.map

package/dist/push-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-credentials.js","sourceRoot":"","sources":["../src/push-credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,kFAAkF;AAClF,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAqB;IAC3D,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,IAAI,CAAC,GAAG;QAAE,MAAM,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,IAAI,IAAI,CAAC,IAAI;QAAE,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,WAAW,CAAC,GAAmB;IACtC,OAAO,aAAa,CAAC,KAAK,EAAE,GAAyC,EAAE;QACrE,WAAW;QACX,aAAa;QACb,YAAY;KACb,CAAC,CAAC;AACL,CAAC;AAED,SAAS,YAAY,CAAC,IAAqB;IACzC,OAAO,aAAa,CAAC,MAAM,EAAE,IAA0C,EAAE;QACvE,OAAO;QACP,QAAQ;QACR,UAAU;QACV,YAAY;KACb,CAAC,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,SAAS,aAAa,CAAC,QAAgB,EAAE,GAA4B,EAAE,QAAkB;IACvF,OAAO,QAAQ;SACZ,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAK,GAAG,CAAC,CAAC,CAAY,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC;SACnF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,QAAQ,IAAI,CAAC,uBAAuB,QAAQ,8BAA8B,CAAC,CAAC;AACpG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAqB;IACzD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,GAAG,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvG,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,GAAG,CAAC,IAAI,GAAG;YACT,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;YACtB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM;YACxB,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ;YAC5B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnF,UAAU,EAAE,QAAQ;SACrB,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;QAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IACpE,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;QAAE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IACpE,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/push-fanout.d.ts

@@ -0,0 +1,137 @@
+/**
+ * push-fanout.ts — the server-side push-wake **trigger policy + fan-out**.
+ *
+ * The delivery half (`push-notifier.ts`) knows *how* to send one strand-wake to
+ * one device; this module owns *who* to wake and *when*. On strand activity it
+ * enumerates the cadre's hibernating mobile members, prefers a direct
+ * control-network `pushWake`, falls back to FCM/APNs platform push only when the
+ * direct dial cannot reach the (suspended) peer, and dedups/cooldowns per
+ * `(peer, strand)` so a chatty strand cannot spam wakes.
+ *
+ * It owns no transport and no DB access: every node primitive (member
+ * enumeration, participation check, direct dial, token resolve, stale-token
+ * expiry) and the `PushNotifier` are injected, so the whole policy is unit-tested
+ * with fakes and never throws to its trigger (a dropped wake is recoverable — the
+ * hibernation check-in wake is the backstop).
+ *
+ * Cross-platform-clean by construction: it imports only the `PushNotifier`
+ * *type* (erased at emit) and the dependency-free `STRAND_WAKE_TYPE` value, so it
+ * carries no `node:http2`/`node:crypto` edge. The Node-only notifier is built by
+ * `CadreNode` (via a guarded dynamic import) and injected here.
+ */
+import type { StrandInstance, WakeAck, DeviceTokenRecord } from './types.js';
+import type { PushNotifier } from './push-notifier.js';
+/** Default per-`(peer, strand)` minimum gap between wakes. */
+export declare const DEFAULT_PUSH_COOLDOWN_MS: number;
+/** Default per-strand burst-coalescing window. */
+export declare const DEFAULT_PUSH_DEBOUNCE_MS = 10000;
+/** A cadre member as returned by {@link CadreNode.listMembers}. */
+export interface FanoutMember {
+    peerId: string;
+    multiaddr: string | null;
+}
+/**
+ * Everything {@link PushFanoutService} needs, injected so the policy is pure and
+ * testable. The node-bound implementations live on {@link CadreNode}; the
+ * `notifier` is a {@link PushNotifier} built from `config.push`.
+ */
+export interface PushFanoutOptions {
+    /** Enumerate the cadre's `CadrePeer` membership (every party node). */
+    listMembers: () => Promise<FanoutMember[]>;
+    /**
+     * The local strand instance for `strandId`, or `undefined` when this node does
+     * not participate — the participation gate (never push for a strand we cannot
+     * vouch for).
+     */
+    getStrand: (strandId: string) => StrandInstance | undefined;
+    /** This node's own peerId, excluded from every fan-out (never wake self). */
+    selfPeerId: () => string | undefined;
+    /**
+     * Direct control-network push-wake. Resolves to a {@link WakeAck} when the dial
+     * REACHED the peer (whatever the peer then decided); REJECTS only on a
+     * dial/transport failure (no dialable address / timeout ⇒ the phone is
+     * suspended), which is what triggers the platform-push fallback.
+     */
+    pushWake: (peerId: string, strandId: string, reason?: string) => Promise<WakeAck>;
+    /** Resolve a peer's FCM/APNs token; `null` ⇒ not a registered mobile peer. */
+    resolveDeviceToken: (peerId: string) => Promise<DeviceTokenRecord | null>;
+    /**
+     * Expire a peer's stale `DeviceToken` after a platform reports it unregistered.
+     * Authority nodes delete the row; non-authority nodes only log (the in-memory
+     * dead-token set below is what actually stops re-pushing this process).
+     */
+    expireDeviceToken: (peerId: string) => Promise<void>;
+    /** Platform-push delivery seam (FCM/APNs router). */
+    notifier: PushNotifier;
+    /** Monotonic clock (epoch ms); injectable for deterministic cooldown/debounce tests. */
+    now?: () => number;
+    /** Per-`(peer, strand)` minimum gap. Default {@link DEFAULT_PUSH_COOLDOWN_MS}. */
+    cooldownMs?: number;
+    /** Per-strand burst coalescing. Default {@link DEFAULT_PUSH_DEBOUNCE_MS}. */
+    debounceMs?: number;
+}
+/**
+ * Server-side push-wake fan-out (see module header). One per participating
+ * {@link CadreNode}, constructed only when push credentials are configured.
+ */
+export declare class PushFanoutService {
+    private readonly deps;
+    private readonly now;
+    private readonly cooldownMs;
+    private readonly debounceMs;
+    /** Per-strand leading-edge debounce: last fan-out start time (epoch ms). */
+    private readonly lastFanoutAt;
+    /** Per-strand in-flight pass, so two near-simultaneous triggers coalesce into one. */
+    private readonly inFlight;
+    /** Per-`(peer, strand)` last-wake time (epoch ms); the anti-spam cooldown. */
+    private readonly cooldownAt;
+    /**
+     * Peers whose `DeviceToken` a platform reported unregistered. Consulted before
+     * every resolve→send so we stop pushing to a dead token. In-memory and
+     * acceptably lossy: a restart re-learns staleness on the next failed send.
+     */
+    private readonly deadTokens;
+    constructor(options: PushFanoutOptions);
+    /**
+     * Fan a wake out to the cadre's hibernating mobile members for a strand that
+     * just saw activity. Best-effort: never throws to the trigger (the check-in
+     * wake is the backstop). No-ops when this node does not participate in the
+     * strand, when the strand was already fanned out within `debounceMs`, or — by
+     * joining — when a pass for the strand is already in flight.
+     *
+     * @param strandId - the strand whose activity should wake hibernating peers.
+     * @param reason - free-form cause hint carried in the wake (default `activity`).
+     */
+    notify(strandId: string, reason?: string): Promise<void>;
+    /** Release the notifier's transport resources (e.g. the APNs HTTP/2 session). */
+    close(): Promise<void>;
+    /**
+     * One fan-out pass: enumerate members, drop self and any peer still cooling
+     * down for this strand, and wake the survivors concurrently. Each
+     * {@link wakePeer} is self-contained (never rejects), so one peer's failure
+     * never aborts the others.
+     */
+    private runFanout;
+    /**
+     * Wake one candidate: try the direct control-network dial first, falling back
+     * to a platform push only when the dial cannot reach the (suspended) peer.
+     *
+     * A resolved {@link WakeAck} means the control path REACHED the peer — even an
+     * ack with `accepted:false` (the receiver declined, e.g. non-member/unknown
+     * strand) counts as reached, so we do NOT also send a platform push (that would
+     * double-wake). Only a dial/transport REJECTION means the phone is suspended
+     * and unreachable over the control network, which is the one case that falls
+     * through to FCM/APNs.
+     */
+    private wakePeer;
+    /**
+     * Deliver a platform push (FCM/APNs) to a suspended peer. Skips a peer with a
+     * known-dead token, no-ops for a non-mobile peer (`resolveDeviceToken` → null),
+     * and — on an `unregistered` send — marks the token dead and expires the row.
+     */
+    private platformPush;
+    /** Whether `peerId` was woken for `strandId` within `cooldownMs`. */
+    private isCoolingDown;
+    /** Arm the per-`(peer, strand)` cooldown at the current clock time. */
+    private markCooldown;
+}

package/dist/push-fanout.js

@@ -0,0 +1,197 @@
+/**
+ * push-fanout.ts — the server-side push-wake **trigger policy + fan-out**.
+ *
+ * The delivery half (`push-notifier.ts`) knows *how* to send one strand-wake to
+ * one device; this module owns *who* to wake and *when*. On strand activity it
+ * enumerates the cadre's hibernating mobile members, prefers a direct
+ * control-network `pushWake`, falls back to FCM/APNs platform push only when the
+ * direct dial cannot reach the (suspended) peer, and dedups/cooldowns per
+ * `(peer, strand)` so a chatty strand cannot spam wakes.
+ *
+ * It owns no transport and no DB access: every node primitive (member
+ * enumeration, participation check, direct dial, token resolve, stale-token
+ * expiry) and the `PushNotifier` are injected, so the whole policy is unit-tested
+ * with fakes and never throws to its trigger (a dropped wake is recoverable — the
+ * hibernation check-in wake is the backstop).
+ *
+ * Cross-platform-clean by construction: it imports only the `PushNotifier`
+ * *type* (erased at emit) and the dependency-free `STRAND_WAKE_TYPE` value, so it
+ * carries no `node:http2`/`node:crypto` edge. The Node-only notifier is built by
+ * `CadreNode` (via a guarded dynamic import) and injected here.
+ */
+import debug from 'debug';
+import { STRAND_WAKE_TYPE } from './strand-wake-payload.js';
+const log = debug('sereus:cadre:push-fanout');
+/** Default per-`(peer, strand)` minimum gap between wakes. */
+export const DEFAULT_PUSH_COOLDOWN_MS = 5 * 60000;
+/** Default per-strand burst-coalescing window. */
+export const DEFAULT_PUSH_DEBOUNCE_MS = 10000;
+/**
+ * Server-side push-wake fan-out (see module header). One per participating
+ * {@link CadreNode}, constructed only when push credentials are configured.
+ */
+export class PushFanoutService {
+    constructor(options) {
+        /** Per-strand leading-edge debounce: last fan-out start time (epoch ms). */
+        this.lastFanoutAt = new Map();
+        /** Per-strand in-flight pass, so two near-simultaneous triggers coalesce into one. */
+        this.inFlight = new Map();
+        /** Per-`(peer, strand)` last-wake time (epoch ms); the anti-spam cooldown. */
+        this.cooldownAt = new Map();
+        /**
+         * Peers whose `DeviceToken` a platform reported unregistered. Consulted before
+         * every resolve→send so we stop pushing to a dead token. In-memory and
+         * acceptably lossy: a restart re-learns staleness on the next failed send.
+         */
+        this.deadTokens = new Set();
+        this.deps = options;
+        this.now = options.now ?? (() => Date.now());
+        this.cooldownMs = options.cooldownMs ?? DEFAULT_PUSH_COOLDOWN_MS;
+        this.debounceMs = options.debounceMs ?? DEFAULT_PUSH_DEBOUNCE_MS;
+    }
+    /**
+     * Fan a wake out to the cadre's hibernating mobile members for a strand that
+     * just saw activity. Best-effort: never throws to the trigger (the check-in
+     * wake is the backstop). No-ops when this node does not participate in the
+     * strand, when the strand was already fanned out within `debounceMs`, or — by
+     * joining — when a pass for the strand is already in flight.
+     *
+     * @param strandId - the strand whose activity should wake hibernating peers.
+     * @param reason - free-form cause hint carried in the wake (default `activity`).
+     */
+    async notify(strandId, reason = 'activity') {
+        try {
+            // 1. Participation gate — never push for a strand we do not participate in.
+            if (!this.deps.getStrand(strandId)) {
+                log('notify: not participating in strand %s; no-op', strandId);
+                return;
+            }
+            // Concurrent trigger coalescing: a second near-simultaneous notify joins the
+            // in-flight pass rather than enumerating + sending again (mirrors
+            // CadreNode.serviceWakePromises). The stored promise is guarded (see below),
+            // so a joiner that adopts it via `return inflight` never observes a rejection
+            // — the "never throws to the trigger" guarantee holds on the join path too
+            // (a rejection here would otherwise escape this try/catch, since the returned
+            // promise settles in the caller's `void notify(...)` context).
+            const inflight = this.inFlight.get(strandId);
+            if (inflight) {
+                log('notify: joining in-flight fan-out for strand %s', strandId);
+                return inflight;
+            }
+            // 2. Per-strand debounce — coalesce bursts after a pass has completed.
+            const now = this.now();
+            const last = this.lastFanoutAt.get(strandId);
+            if (last !== undefined && now - last < this.debounceMs) {
+                log('notify: debounced fan-out for strand %s', strandId);
+                return;
+            }
+            this.lastFanoutAt.set(strandId, now);
+            // Guard the pass so neither the originator nor a concurrent joiner can see a
+            // rejection (e.g. listMembers throwing on a control-DB hiccup): a dropped
+            // fan-out is recoverable via the check-in wake backstop.
+            const op = this.runFanout(strandId, reason).catch((error) => {
+                log('notify: fan-out pass for strand %s failed (best-effort): %o', strandId, error);
+            });
+            this.inFlight.set(strandId, op);
+            try {
+                await op;
+            }
+            finally {
+                this.inFlight.delete(strandId);
+            }
+        }
+        catch (error) {
+            // The trigger must never see a throw — failures are logged best-effort.
+            log('notify: fan-out for strand %s failed (best-effort): %o', strandId, error);
+        }
+    }
+    /** Release the notifier's transport resources (e.g. the APNs HTTP/2 session). */
+    async close() {
+        await this.deps.notifier.close();
+    }
+    /**
+     * One fan-out pass: enumerate members, drop self and any peer still cooling
+     * down for this strand, and wake the survivors concurrently. Each
+     * {@link wakePeer} is self-contained (never rejects), so one peer's failure
+     * never aborts the others.
+     */
+    async runFanout(strandId, reason) {
+        const members = await this.deps.listMembers();
+        const self = this.deps.selfPeerId();
+        const targets = members.filter((m) => m.peerId !== self && !this.isCoolingDown(m.peerId, strandId));
+        log('fanout: strand %s — %d candidate(s) after self/cooldown filter', strandId, targets.length);
+        await Promise.all(targets.map((m) => this.wakePeer(m.peerId, strandId, reason)));
+    }
+    /**
+     * Wake one candidate: try the direct control-network dial first, falling back
+     * to a platform push only when the dial cannot reach the (suspended) peer.
+     *
+     * A resolved {@link WakeAck} means the control path REACHED the peer — even an
+     * ack with `accepted:false` (the receiver declined, e.g. non-member/unknown
+     * strand) counts as reached, so we do NOT also send a platform push (that would
+     * double-wake). Only a dial/transport REJECTION means the phone is suspended
+     * and unreachable over the control network, which is the one case that falls
+     * through to FCM/APNs.
+     */
+    async wakePeer(peerId, strandId, reason) {
+        // A wake of either kind is now being attempted → arm the cooldown up front.
+        this.markCooldown(peerId, strandId);
+        try {
+            const ack = await this.deps.pushWake(peerId, strandId, reason);
+            log('wakePeer: direct pushWake reached %s for strand %s (accepted=%s); no platform fallback', peerId, strandId, ack.accepted);
+            return;
+        }
+        catch (error) {
+            // Dial/transport failure ⇒ suspended phone ⇒ fall through to platform push.
+            log('wakePeer: direct pushWake could not reach %s; trying platform push: %o', peerId, error);
+        }
+        try {
+            await this.platformPush(peerId, strandId, reason);
+        }
+        catch (error) {
+            log('wakePeer: platform push for %s failed (best-effort): %o', peerId, error);
+        }
+    }
+    /**
+     * Deliver a platform push (FCM/APNs) to a suspended peer. Skips a peer with a
+     * known-dead token, no-ops for a non-mobile peer (`resolveDeviceToken` → null),
+     * and — on an `unregistered` send — marks the token dead and expires the row.
+     */
+    async platformPush(peerId, strandId, reason) {
+        if (this.deadTokens.has(peerId)) {
+            log('platformPush: %s has a known-stale token; skipping resolve→send', peerId);
+            return;
+        }
+        const record = await this.deps.resolveDeviceToken(peerId);
+        if (!record) {
+            log('platformPush: %s is not a registered mobile peer; no platform push', peerId);
+            return;
+        }
+        const result = await this.deps.notifier.send({
+            token: record.token,
+            platform: record.platform,
+            payload: { type: STRAND_WAKE_TYPE, strandId, reason },
+        });
+        if (!result.ok && result.unregistered) {
+            // Permanently-invalid token: stop pushing to it this process (the set), and
+            // expire the row (authority delete; non-authority logs re-registration).
+            this.deadTokens.add(peerId);
+            await this.deps.expireDeviceToken(peerId);
+            log('platformPush: expired stale token for %s (platform=%s)', peerId, record.platform);
+        }
+    }
+    /** Whether `peerId` was woken for `strandId` within `cooldownMs`. */
+    isCoolingDown(peerId, strandId) {
+        const last = this.cooldownAt.get(cooldownKey(peerId, strandId));
+        return last !== undefined && this.now() - last < this.cooldownMs;
+    }
+    /** Arm the per-`(peer, strand)` cooldown at the current clock time. */
+    markCooldown(peerId, strandId) {
+        this.cooldownAt.set(cooldownKey(peerId, strandId), this.now());
+    }
+}
+/** Composite key for the per-`(peer, strand)` cooldown map. */
+function cooldownKey(peerId, strandId) {
+    return `${peerId}${strandId}`;
+}
+//# sourceMappingURL=push-fanout.js.map