@serfab/cadre-core 0.7.1 → 0.9.0

package/src/key-store-file.ts

@@ -0,0 +1,203 @@
+/**
+ * Node-only file-backed {@link KeyStore}: one file per slot under a configured
+ * directory, holding the raw key material bytes.
+ *
+ * This module imports `node:fs/promises`, `node:path`, and `node:crypto`, so it
+ * is deliberately kept OUT of the package's cross-platform default entry
+ * (`./index.js`). Import it from the dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileKeyStore } from '@serfab/cadre-core/key-store-file';
+ * ```
+ *
+ * A React Native / browser entry graph never resolves this path, so the
+ * `node:fs` edge never reaches a bundler that cannot satisfy it.
+ */
+import debug from 'debug';
+import { mkdir, readFile, rm, readdir, rename, open } from 'node:fs/promises';
+import type { FileHandle } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import type { KeyId, KeyStore } from './key-store.js';
+import { KeyStoreAccessError } from './key-store.js';
+
+const log = debug('sereus:cadre:key-store-file');
+
+/** Suffix appended to the encoded keyId to form a slot filename. */
+const SLOT_SUFFIX = '.key';
+
+/**
+ * Suffix for the transient file written then atomically renamed over the slot.
+ * Distinct from {@link SLOT_SUFFIX}, so {@link FileKeyStore.list} (which matches
+ * only `.key`) never surfaces an in-flight or crash-orphaned temp file.
+ */
+const TEMP_SUFFIX = '.tmp';
+
+/** Best-effort POSIX permissions (ignored on Windows / unsupported FSes). */
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+
+/**
+ * Percent-encode a keyId into a filesystem-safe filename component. Beyond
+ * `encodeURIComponent` (which already escapes `/`, spaces, and unicode), this
+ * also escapes the unreserved characters `encodeURIComponent` leaves intact but
+ * that are unsafe in filenames on some platforms (notably `*` on Windows) — and
+ * `.` so the `.key` suffix is the only literal dot, making suffix-stripping in
+ * {@link decodeKeyId} unambiguous. {@link decodeKeyId} reverses every escape via
+ * `decodeURIComponent`. The result contains only `A-Za-z0-9-_` and `%XX`.
+ */
+function encodeKeyId(keyId: KeyId): string {
+	return encodeURIComponent(keyId).replace(
+		/[!'()*~.]/g,
+		(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+	);
+}
+
+/**
+ * Reverse {@link encodeKeyId}: strip the slot suffix and percent-decode. Returns
+ * `undefined` for a `.key` filename this store did not write (a foreign file
+ * with an invalid percent-sequence), so {@link FileKeyStore.list} can skip it
+ * rather than letting one undecodable entry throw and break enumeration of every
+ * real slot.
+ */
+function decodeKeyId(fileName: string): KeyId | undefined {
+	const encoded = fileName.slice(0, -SLOT_SUFFIX.length);
+	try {
+		return decodeURIComponent(encoded);
+	} catch (error) {
+		log('FileKeyStore: skipping undecodable slot filename %s: %o', fileName, error);
+		return undefined;
+	}
+}
+
+/** Whether an unknown error is a Node "file/dir not found" (ENOENT). */
+function isNotFound(error: unknown): boolean {
+	return typeof error === 'object' && error !== null
+		&& (error as { code?: unknown }).code === 'ENOENT';
+}
+
+/**
+ * File-backed {@link KeyStore}. Each slot is `<dir>/<encoded keyId>.key`
+ * containing the raw material bytes. The directory is created lazily on first
+ * {@link set}. Suitable for headless Node cadre nodes and tests; for mobile use
+ * a platform secure-enclave backend instead.
+ */
+export class FileKeyStore implements KeyStore {
+	constructor(private readonly dir: string) {}
+
+	private slotPath(keyId: KeyId): string {
+		return join(this.dir, `${encodeKeyId(keyId)}${SLOT_SUFFIX}`);
+	}
+
+	/**
+	 * Sibling path for the temp file written before the atomic rename. The random
+	 * component makes concurrent {@link set}s to the same slot (and crash-orphaned
+	 * leftovers) collide-free; it lives in the same directory as the slot so the
+	 * final {@link rename} stays within one filesystem and is therefore atomic.
+	 */
+	private tempPath(keyId: KeyId): string {
+		const unique = randomBytes(6).toString('hex');
+		return join(this.dir, `${encodeKeyId(keyId)}.${unique}${TEMP_SUFFIX}`);
+	}
+
+	async get(keyId: KeyId): Promise<Uint8Array | undefined> {
+		try {
+			const buf = await readFile(this.slotPath(keyId));
+			// Copy into a plain Uint8Array decoupled from Node's Buffer pool.
+			return new Uint8Array(buf);
+		} catch (error) {
+			// A missing slot is "empty" (undefined), NOT an error — so a
+			// load-or-create caller generates a key rather than mistaking a
+			// permission failure for absence. Any other failure (e.g. EACCES) is
+			// surfaced as access-denied so callers do not clobber an existing key.
+			if (isNotFound(error)) return undefined;
+			throw new KeyStoreAccessError(keyId, `FileKeyStore: failed to read key slot ${keyId}`, { cause: error });
+		}
+	}
+
+	/**
+	 * Crash-atomic write: a concurrent reader sees either the complete previous
+	 * bytes or the complete new bytes, never a torn slot. The new material is
+	 * written to a sibling temp file, fsync'd, then atomically renamed over the
+	 * slot. A failure at any point removes the temp file and leaves the previous
+	 * slot untouched.
+	 */
+	async set(keyId: KeyId, keyMaterial: Uint8Array): Promise<void> {
+		await mkdir(this.dir, { recursive: true, mode: DIR_MODE });
+		await this.writeSlotAtomically(this.tempPath(keyId), this.slotPath(keyId), keyMaterial);
+	}
+
+	/**
+	 * Write material to `tmpPath`, durably land it, then atomically swap it onto
+	 * `finalPath`.
+	 *
+	 * Durability bar: the temp file is fsync'd before the rename so a power loss
+	 * cannot surface a slot whose bytes never reached the platter, and the slot
+	 * directory is fsync'd afterwards (best-effort — see {@link syncDir}) so the
+	 * rename itself survives a crash. On POSIX `rename(2)` replaces atomically;
+	 * Node maps to `MoveFileEx(MOVEFILE_REPLACE_EXISTING)` on Windows, which is
+	 * also atomic — though it can fail with `EPERM`/`EBUSY` if another process
+	 * holds the destination open. That cross-process case is out of scope here
+	 * (the in-process identity path is single-flight); such a failure surfaces
+	 * to the caller with the previous slot left intact.
+	 */
+	private async writeSlotAtomically(tmpPath: string, finalPath: string, keyMaterial: Uint8Array): Promise<void> {
+		// 'wx' creates the temp file exclusively; a name collision (astronomically
+		// unlikely given the random component) fails here before we own anything.
+		const handle = await open(tmpPath, 'wx', FILE_MODE);
+		try {
+			try {
+				await handle.writeFile(keyMaterial);
+				await handle.sync(); // land bytes on disk before the rename exposes them
+			} finally {
+				await handle.close().catch(() => {});
+			}
+			await rename(tmpPath, finalPath);
+		} catch (error) {
+			// Any failure after creation (write, sync, or rename): drop the temp
+			// file so a retry leaves no `.tmp` debris. The slot is only ever
+			// swapped by the atomic rename, so the previous bytes stay intact.
+			await rm(tmpPath, { force: true }).catch(() => {});
+			throw error;
+		}
+		await this.syncDir();
+	}
+
+	/**
+	 * Best-effort fsync of the slot directory so a fresh slot's directory entry is
+	 * durable across power loss. Opening a directory for fsync is not portable
+	 * (unsupported on Windows and some filesystems), and rename atomicity does not
+	 * depend on it — so a failure here is logged and swallowed, never surfaced.
+	 */
+	private async syncDir(): Promise<void> {
+		let dirHandle: FileHandle | undefined;
+		try {
+			dirHandle = await open(this.dir, 'r');
+			await dirHandle.sync();
+		} catch (error) {
+			log('FileKeyStore: directory fsync skipped for %s: %o', this.dir, error);
+		} finally {
+			await dirHandle?.close().catch(() => {});
+		}
+	}
+
+	async delete(keyId: KeyId): Promise<void> {
+		// force:true makes removing an absent slot a no-op (idempotent).
+		await rm(this.slotPath(keyId), { force: true });
+	}
+
+	async list(): Promise<KeyId[]> {
+		let entries: string[];
+		try {
+			entries = await readdir(this.dir);
+		} catch (error) {
+			// An absent directory means no slots yet — not a failure.
+			if (isNotFound(error)) return [];
+			throw new Error('FileKeyStore: failed to list key directory', { cause: error });
+		}
+		return entries
+			.filter((name) => name.endsWith(SLOT_SUFFIX))
+			.map(decodeKeyId)
+			.filter((id): id is KeyId => id !== undefined);
+	}
+}

package/src/key-store.ts

@@ -0,0 +1,99 @@
+/**
+ * Backend-agnostic store for raw private key material.
+ *
+ * Mobile cadre nodes hold sensitive key material at rest: the libp2p
+ * peer/node identity key and (in the single-key reference model) the owner
+ * signing key derived from it. This module defines the seam those keys flow
+ * through so a platform-secure backend (iOS Keychain / Android Keystore) can be
+ * plugged in without `@serfab/cadre-core` taking any platform dependency.
+ *
+ * This file is dependency-free (no node:/RN imports) so it is safe in every
+ * entry graph. The Node reference {@link FileKeyStore} lives in a separate
+ * subpath module (`./key-store-file.js`) so its `node:fs` import never lands in
+ * the cross-platform default entry.
+ */
+
+/** Opaque identifier for a stored key slot (e.g. 'cadre/identity'). */
+export type KeyId = string;
+
+/**
+ * Default slot id for the node identity key. `CadreNode` reads/persists its
+ * libp2p identity here when a {@link KeyStore} is configured without an explicit
+ * `identityKeyId`.
+ */
+export const DEFAULT_IDENTITY_KEY_ID: KeyId = 'cadre/identity';
+
+/**
+ * Backend-agnostic store for raw private key material. Implementations may be
+ * file-based, OS-keyring, or platform secure-enclave backed (iOS Keychain /
+ * Android Keystore). The interface makes no assumption about the backend and
+ * never logs, returns, or throws key material.
+ *
+ * Key material is raw bytes (e.g. libp2p protobuf-serialized private keys).
+ * Text-only backends encode/decode (base64) internally; byte-native backends
+ * (LevelDB) store as-is.
+ */
+export interface KeyStore {
+	/** Resolves to the stored material, or undefined if the slot is empty. */
+	get(keyId: KeyId): Promise<Uint8Array | undefined>;
+
+	/** Writes/overwrites the slot. */
+	set(keyId: KeyId, keyMaterial: Uint8Array): Promise<void>;
+
+	/** Removes the slot. Idempotent — succeeds even if absent. */
+	delete(keyId: KeyId): Promise<void>;
+
+	/** Enumerates the keyIds this store knows about. */
+	list(): Promise<KeyId[]>;
+}
+
+/**
+ * Thrown by {@link KeyStore.get} when access was denied or could not be
+ * satisfied (e.g. a biometric/device-unlock prompt was cancelled or failed).
+ * Distinguishes "access refused" from "slot empty" (which is a plain `undefined`
+ * return). Biometric gating itself is out of scope here, but `get` rejecting
+ * with this error is the contract a gated backend uses, so callers must not
+ * treat it as "no key" (which would trigger key regeneration and silent
+ * identity loss).
+ *
+ * Carries only the {@link keyId} — never key material — so it is safe to log.
+ */
+export class KeyStoreAccessError extends Error {
+	readonly keyId: KeyId;
+
+	constructor(keyId: KeyId, message: string, options?: { cause?: unknown }) {
+		super(message, options);
+		this.name = 'KeyStoreAccessError';
+		this.keyId = keyId;
+	}
+}
+
+/**
+ * In-memory {@link KeyStore} backed by a `Map`. For tests and ephemeral nodes;
+ * nothing is persisted across process restarts. Dependency-free, so it is safe
+ * in every entry graph.
+ *
+ * Material is defensively copied on both {@link set} and {@link get} so a caller
+ * mutating its own buffer cannot alter stored state (and vice versa), matching
+ * the fresh-buffer semantics a file/keyring backend produces.
+ */
+export class InMemoryKeyStore implements KeyStore {
+	private readonly slots = new Map<KeyId, Uint8Array>();
+
+	async get(keyId: KeyId): Promise<Uint8Array | undefined> {
+		const stored = this.slots.get(keyId);
+		return stored ? stored.slice() : undefined;
+	}
+
+	async set(keyId: KeyId, keyMaterial: Uint8Array): Promise<void> {
+		this.slots.set(keyId, keyMaterial.slice());
+	}
+
+	async delete(keyId: KeyId): Promise<void> {
+		this.slots.delete(keyId);
+	}
+
+	async list(): Promise<KeyId[]> {
+		return [...this.slots.keys()];
+	}
+}

package/src/peer-authorization.ts

@@ -0,0 +1,81 @@
+import debug from 'debug';
+import { digest, verify } from '@optimystic/quereus-plugin-crypto';
+
+const log = debug('sereus:cadre:peer-authorization');
+
+/**
+ * Canonical digest an owner signs to authorize a peer.
+ *
+ * This is the exact byte construction {@link SeedBootstrapService.authorizePeer}
+ * signs over when it inserts an authorized `CadrePeer` row:
+ * `digest([peerId], 'sha256', 'base64url')`. Factored into one place so the
+ * producer (owner signing) and the verifier (the offline `cadre enroll
+ * register` check) can never drift apart — change the digest here and both move
+ * together. The SQL mirror is the bare single-field `digest(coalesce(new.PeerId, old.PeerId))`.
+ */
+export function peerAuthorizationDigest(peerId: string): string {
+  return digest([peerId], 'sha256', 'base64url') as string;
+}
+
+/**
+ * Canonical digest an owner signs to VOUCH a `CadrePeer` membership row (insert
+ * and the owner re-touch update). Binds the peer id to the row's single-use
+ * `StampId` nonce, so a captured signed insert cannot be replayed (the `StampId` is
+ * unique) and — because {@link cadrePeerRemoveDigest} scopes a DIFFERENT payload — the
+ * stored voucher (`VouchSig`) cannot be replayed to authorize a delete.
+ *
+ * The SQL mirror is `digest(new.PeerId, new.StampId)` (two TEXT fields), matching the
+ * canonical multi-field framing in control-database.ts:buildAuthorizationMessage.
+ */
+export function cadrePeerVoucherDigest(peerId: string, stampId: string): string {
+  return digest([peerId, stampId], 'sha256', 'base64url') as string;
+}
+
+/**
+ * Canonical digest an owner signs to REMOVE a `CadrePeer` row. Deliberately a
+ * distinct payload from {@link cadrePeerVoucherDigest} (adds the `'remove'` action
+ * tag) so the row's stored voucher — a signature over the voucher digest — can never
+ * satisfy this delete check. The signature is supplied in write context and never
+ * stored, so no reader can replay it; binding the live row's `StampId` also invalidates
+ * any captured remove after a delete+reinsert (the nonce rotates).
+ *
+ * SQL mirror: `digest(old.PeerId, old.StampId, 'remove')`.
+ */
+export function cadrePeerRemoveDigest(peerId: string, stampId: string): string {
+  return digest([peerId, stampId, 'remove'], 'sha256', 'base64url') as string;
+}
+
+/**
+ * Verify that `signature` is a valid owner ed25519 signature over `peerId`'s
+ * authorization digest, using `ownerPublicKey` (base64url).
+ *
+ * This is the mirror of the signing done in
+ * {@link SeedBootstrapService.authorizePeer}: it checks the signature against
+ * {@link peerAuthorizationDigest}. A `true` result means the holder of the
+ * owner private key vouched for this peer ID — it does NOT mean the peer is
+ * registered anywhere.
+ *
+ * Returns a boolean and never throws: malformed base64url, a bad/garbage key, or
+ * any crypto failure resolves to `false` (callers want a verdict, not an
+ * exception). The catch is logged at debug.
+ */
+export function verifyPeerAuthorization(
+  peerId: string,
+  ownerPublicKey: string,
+  signature: string
+): boolean {
+  try {
+    return verify(
+      peerAuthorizationDigest(peerId),
+      signature,
+      ownerPublicKey,
+      'ed25519',
+      'base64url',
+      'base64url',
+      'base64url'
+    );
+  } catch (error) {
+    log('verifyPeerAuthorization failed: %o', error);
+    return false;
+  }
+}

package/src/peer-record.ts

@@ -0,0 +1,146 @@
+/**
+ * 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;
+    },
+  };
+}

package/src/push-credentials.ts

@@ -0,0 +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;
+}