@serfab/cadre-core 0.9.0 → 0.10.0

package/src/membership-connection-gater.ts

@@ -0,0 +1,204 @@
+/**
+ * Control-network inbound connection gate (defense-in-depth).
+ *
+ * Layer 2 of the membership enforcement chain: the PRIMARY gates are per-stream
+ * — every sensitive sereus control protocol rejects a peer that fails the
+ * voucher-anchored membership check (wake and strand-addr via
+ * `CadreNode.isAuthorizedMember`; the Optimystic control-DB protocols via the
+ * materialized-snapshot gate `CadreNode.authorizeInboundControlStream`), and
+ * the replicated rows an outsider *can* still write are disbelieved at read
+ * time. This module adds the opportunistic connection-level layer on top: a
+ * peer this node can positively determine is NOT authorized is refused at the
+ * encrypted-connection checkpoint, before any protocol negotiation, so a
+ * known-nothing outsider is never even in the conversation.
+ *
+ * ## The stranger allowlist (the ONE place it is defined)
+ *
+ * A libp2p connection gater decides per CONNECTION, before protocols are
+ * negotiated, so "allow seed, deny repo" cannot be expressed here — instead the
+ * policy admits a connection whenever a legitimate stranger interaction could be
+ * riding it, and the per-stream gates take over. The complete set of protocols a
+ * NOT-yet-authorized peer may legitimately speak on a control node is:
+ *
+ *  - `/sereus/seed/1.0.0` ({@link SEED_PROTOCOL}) — enrollment seed delivery.
+ *    An owner dials a brand-new node to seed it (the new node has no members
+ *    yet, so its gate is inert), and an invited phone dials the owner before it
+ *    is authorized (admitted via the enrollment window `CadreNode.createInvite`
+ *    opens). The handler's own trust decision is the anchored seed-trust policy.
+ *  - `/sereus/formation/1.0.0` ({@link FORMATION_PROTOCOL}) — cross-party
+ *    strand formation via open invitations. Stranger-facing BY DESIGN: the
+ *    initiator is another party, and its token is only checkable inside the
+ *    protocol. The exemption is therefore keyed on EXPECTATION of a stranger,
+ *    not capability to serve one: stranger denial is suspended only while this
+ *    node has at least one UNEXPIRED, NOT-FULLY-CONSUMED open invitation
+ *    outstanding (`StrandSolicitationService.hasOutstandingInvitation` — the
+ *    tokens this process minted or published, plus any still-redeemable
+ *    `FormationInvite` row the usage recorder can see). Merely registering the
+ *    responder (`CadreNode.initializeStrandSolicitation`) does NOT suspend it,
+ *    so an app that registers eagerly at node bring-up keeps a live gate. The
+ *    handler's own trust decision remains the per-token check, which is
+ *    strictly finer than this one: a peer admitted here can still be rejected
+ *    in-protocol for a bogus or spent token.
+ *
+ * There is one further connection-level carve-out, which is NOT a protocol
+ * exemption and needs no stranger window:
+ *
+ *  - **Announced delegate peers** (`delegate-admission.ts`). A member's strand
+ *    node runs as a separate libp2p identity whose peerId no sibling can
+ *    recompute, so a relay-running control node would deny its circuit-relay
+ *    reservation. Before starting a strand node, a member's control node
+ *    announces that peerId over the already-authenticated strand-addr RPC, and
+ *    the receiver holds a short-lived grant for it
+ *    (`CadreNode.grantDelegateAdmission`). The grant admits the CONNECTION and
+ *    nothing else — a reservation needs no stream — and is deliberately
+ *    invisible to the per-stream gate below, so a delegate still gets refused
+ *    on every members-only protocol.
+ *
+ * Everything else a control node handles — the Optimystic control-DB protocols
+ * (`/optimystic/control-<party>/{repo,cluster,sync,block-transfer}/…`), wake
+ * (`/sereus/strand-wake/1.0.0`), and strand-addr (`/sereus/strand-addr/1.0.0`)
+ * — is members-only, and every one of them enforces that per-stream. Wake and
+ * strand-addr check `isAuthorizedMember` inside their handlers; the four
+ * control-DB protocols are gated by the fail-closed
+ * `CadreNode.authorizeInboundControlStream` (wired as libp2p's
+ * `authorizeInboundStream` upstream hook), which judges each inbound stream
+ * against the MATERIALIZED authorized-peer snapshot — synchronous and
+ * in-memory, because a live DB read from inside the gate would deadlock into
+ * mutual denial. The two layers complement, not duplicate: this connection
+ * gate is fail-open over a live DB read (deny only on positive proof of an
+ * outsider), the stream gate is fail-closed over the snapshot and has NO
+ * stranger carve-outs — an enrollment window admits a stranger's connection
+ * for seed delivery, yet its repo streams are still refused.
+ *
+ * ## Fail-open, deliberately
+ *
+ * This layer only ever denies on a POSITIVE determination of "unauthorized
+ * outsider while no stranger path is open". Any error, missing dependency, or
+ * ambiguous state admits the connection and defers to the fail-closed stream
+ * gates — a DB hiccup must not partition a legitimate cadre.
+ */
+
+import debug from 'debug';
+import type { ConnectionGater, PeerId, MultiaddrConnection } from '@libp2p/interface';
+import { SEED_PROTOCOL } from './seed-bootstrap.js';
+import { FORMATION_PROTOCOL } from './strand-formation-protocol.js';
+
+const log = debug('sereus:cadre:connection-gater');
+
+/**
+ * The protocols a not-yet-authorized peer may legitimately speak on a control
+ * node (see the module doc above for why each is open and where its own trust
+ * decision lives). Exported as the single reference point so the allowlist
+ * cannot silently drift across modules.
+ */
+export const STRANGER_OPEN_PROTOCOLS: readonly string[] = [SEED_PROTOCOL, FORMATION_PROTOCOL];
+
+/**
+ * How long `CadreNode.createInvite` holds the inbound gate open for strangers
+ * when the invite carries no explicit expiry: the invitee must dial in before
+ * it is authorized, and an expiry-less invite gives the gate no bound of its
+ * own. Redeeming after this window still works once the owner re-mints (or the
+ * caller re-opens the window via `CadreNode.openEnrollmentWindow`).
+ */
+export const DEFAULT_ENROLLMENT_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * Deadline for one admission decision, after which the connection is ADMITTED.
+ *
+ * libp2p awaits `denyInboundEncryptedConnection` inside the inbound upgrade
+ * WITHOUT racing its inbound-upgrade timeout signal (unlike the pre-encryption
+ * `denyInboundConnection` hook), so a decision that never settles wedges that
+ * upgrade forever — the connection-manager's inbound-upgrade slot is taken by
+ * `acceptIncomingConnection` and released in the `finally` that never runs. The
+ * real policy reads the control DB (`listAuthorizedMembers`), which can pull
+ * over the network, so "never settles" is reachable. Bounding it here keeps the
+ * fail-open contract honest: a slow decision admits rather than silently
+ * failing closed (or not at all).
+ */
+export const ADMISSION_DECISION_TIMEOUT_MS = 2_000;
+
+/**
+ * The admission decision the gate defers to — implemented by
+ * `CadreNode.admitInboundControlConnection` (enrollment windows, anchor state,
+ * bootstrap infra, the authorized-member set). Kept injectable so the gater's
+ * composition/fail-open behavior is unit-testable without a full node.
+ */
+export interface InboundAdmissionPolicy {
+  /** Should an inbound encrypted connection from this peer be admitted? */
+  admitInbound(remotePeerId: string): Promise<boolean> | boolean;
+}
+
+/**
+ * Build the control node's connection gater: the caller-supplied gater (if any)
+ * with membership admission composed onto `denyInboundEncryptedConnection` —
+ * the earliest checkpoint where the remote's authenticated PeerId is known.
+ *
+ * Composition semantics: every hook of `base` is preserved as-is; on the
+ * inbound-encrypted hook a deny from EITHER the base gater or the admission
+ * policy denies. A policy error — or a decision slower than
+ * `decisionTimeoutMs` — admits (fail-open, see module doc); the base gater's
+ * verdict is still honored first.
+ *
+ * NOTE: `base` is spread, so a gater passed as a CLASS INSTANCE would lose its
+ * prototype methods; every caller in this repo (and libp2p's own default)
+ * supplies a plain object. If a class-based gater ever shows up, delegate
+ * per-hook instead of spreading.
+ *
+ * Deny timing, as observed by the denied dialer: noise negotiates the muxer in
+ * the security handshake's early data, so the DIALER's upgrade may complete
+ * (its `dial()` resolves) before this receiver-side hook runs. The deny then
+ * aborts the receiver's upgrade — the receiver never registers the connection
+ * and never creates its muxer, so no protocol can ever be negotiated — and the
+ * dialer sees its "open" connection close moments later.
+ *
+ * Control node only: strand cohort nodes legitimately connect cross-party
+ * peers, so `CadreNode` threads the raw configured gater to them unchanged.
+ */
+export function createMembershipConnectionGater(
+  policy: InboundAdmissionPolicy,
+  base?: ConnectionGater,
+  decisionTimeoutMs: number = ADMISSION_DECISION_TIMEOUT_MS
+): ConnectionGater {
+  return {
+    ...base,
+    denyInboundEncryptedConnection: async (peerId: PeerId, maConn: MultiaddrConnection): Promise<boolean> => {
+      if (await base?.denyInboundEncryptedConnection?.(peerId, maConn)) {
+        return true;
+      }
+      const remotePeerId = peerId.toString();
+      try {
+        return !(await admitWithinDeadline(policy, remotePeerId, decisionTimeoutMs));
+      } catch (error) {
+        log('admitInbound threw for %s — admitting (fail-open; stream gates decide): %o', remotePeerId, error);
+        return false;
+      }
+    }
+  };
+}
+
+/**
+ * Run the admission decision under {@link ADMISSION_DECISION_TIMEOUT_MS},
+ * resolving to "admit" if it has not settled in time (see that constant for why
+ * an unbounded await is not safe here). The timer is always cleared so a decided
+ * connection never holds the event loop open.
+ */
+async function admitWithinDeadline(
+  policy: InboundAdmissionPolicy,
+  remotePeerId: string,
+  timeoutMs: number
+): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve(policy.admitInbound(remotePeerId)),
+      new Promise<boolean>((resolve) => {
+        timer = setTimeout(() => {
+          log('admitInbound exceeded %dms for %s — admitting (fail-open; stream gates decide)', timeoutMs, remotePeerId);
+          resolve(true);
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/node-local-snapshot.ts

@@ -0,0 +1,260 @@
+/**
+ * Shared machinery for the node's **node-local** records — the small,
+ * NEVER-replicated, per-party sets a node keeps for itself and never sources
+ * from shared group state:
+ *
+ *  - the trusted-owner anchor (`trusted-owner-store.ts`),
+ *  - the cold-start bootstrap-peer store (`bootstrap-peer-store.ts`).
+ *
+ * Both are the same mechanism with a different payload: a
+ * `{ version, partyId, <entries> }` envelope, snapshot-written whole on every
+ * change, loaded under one fail-safe-but-not-fail-silent policy. The only part
+ * that differs per platform is WHERE the bytes are kept — Node writes a file,
+ * a browser writes IndexedDB, React Native writes SecureStore or its LevelDB
+ * KV, NativeScript writes SQLite. That difference is the whole of
+ * {@link DurableSlot}, which the embedding app supplies; everything else lives
+ * here.
+ *
+ * This module is cross-platform (no `node:` imports), so it is safe in the
+ * package's default entry — the Node-only `FileDurableSlot`
+ * (`file-durable-slot.ts`) is what stays behind the `*-store-file` subpaths.
+ */
+import debug from 'debug';
+
+const log = debug('sereus:cadre:node-local-snapshot');
+
+/**
+ * A single durable text slot, supplied by the embedding app. The only
+ * platform-specific part of a persistent node-local store.
+ */
+export interface DurableSlot {
+	/**
+	 * The slot's persisted text, or `undefined` when it was never written.
+	 *
+	 * MUST throw (not return `undefined`) when the slot exists but cannot be
+	 * read. That distinction is load-bearing: `undefined` means "cold start,
+	 * nothing was ever here", and callers snapshot-write the whole record, so a
+	 * failed read reported as `undefined` silently converts a recoverable error
+	 * (permissions, a blocked database upgrade, an I/O fault) into destruction
+	 * of a still-intact record on the next save.
+	 */
+	load(): Promise<string | undefined>;
+	/**
+	 * Durably replace the slot's text. Callers snapshot-write the whole record,
+	 * so an implementation never needs to merge.
+	 */
+	save(text: string): Promise<void>;
+}
+
+/** Envelope version. Guards future migrations; an unknown version loads empty. */
+const ENVELOPE_VERSION = 1;
+
+/**
+ * What one unusable entry means for its siblings — the single intentional
+ * difference between the two records:
+ *
+ *  - `'discard-all'` (the trusted-owner anchor): a record that cannot be read
+ *    in full is not an anchor. Trusting a *subset* of the keys a file claims is
+ *    a silent, security-relevant downgrade, so the whole record is discarded
+ *    and the node trusts no one until re-seeded out of band.
+ *  - `'drop-entry'` (the bootstrap-peer store): the record is a best-effort
+ *    retry list and nothing in it is trust-bearing, so one junk entry must not
+ *    discard a stranded node's only remaining way back into its party.
+ */
+export type UnusableEntryPolicy = 'discard-all' | 'drop-entry';
+
+/** What a particular node-local record persists, and how it validates it. */
+export interface NodeLocalSnapshotSpec<E> {
+	/** Human name of the record, used in load errors and logs. */
+	readonly label: string;
+	/** Envelope property holding the `key -> entry` record (`owners`, `peers`). */
+	readonly payloadKey: string;
+	/** See {@link UnusableEntryPolicy}. */
+	readonly unusableEntry: UnusableEntryPolicy;
+	/**
+	 * Validate one persisted entry, returning the value to hold in memory
+	 * (copied, so later mutation of the parsed JSON cannot reach it) or
+	 * `undefined` when the entry is unusable.
+	 */
+	readonly acceptEntry: (key: string, entry: unknown) => E | undefined;
+}
+
+/**
+ * A loaded node-local record over a {@link DurableSlot}: an in-memory
+ * `key -> entry` map plus a serialised full-snapshot write chain.
+ *
+ * NOTE: writes are serialised in-process only. Two processes (or two browser
+ * tabs) sharing ONE slot for ONE party would each snapshot-write their own
+ * view, so the loser's entries are dropped. Fine for every backend today —
+ * each node gets its own directory / origin database — but a single slot
+ * backing two concurrent nodes of one party needs a lock or a merge-on-write,
+ * not a snapshot replace.
+ */
+export class NodeLocalSnapshot<E> {
+	/**
+	 * Serialises persists: every {@link put} snapshot-writes the full entry set,
+	 * so chaining writes keeps them ordered and the last landed snapshot
+	 * complete.
+	 */
+	private writeChain: Promise<void> = Promise.resolve();
+
+	private constructor(
+		private readonly slot: DurableSlot,
+		readonly partyId: string,
+		private readonly spec: NodeLocalSnapshotSpec<E>,
+		private readonly entries: Map<string, E>
+	) {}
+
+	/**
+	 * Load (or cold-start) the party's record from `slot`. Failure policy, per
+	 * the trust model of the anchor this was first written for: only a real,
+	 * well-formed, matching-party record yields entries.
+	 *
+	 * A *decidable* non-record — slot never written, unparsable JSON, unknown
+	 * envelope shape, `partyId` mismatch (a slot reused for a different party
+	 * must not leak into this one) — yields an EMPTY record, the safe direction:
+	 * the node holds nothing until it is re-seeded, rather than acting on stale
+	 * or foreign state.
+	 *
+	 * A slot that is *present but unreadable* ({@link DurableSlot.load} threw)
+	 * is NOT decidable and **throws** instead — mirroring `FileKeyStore.get`.
+	 * Loading empty there would both hide a real misconfiguration and let the
+	 * next {@link put} snapshot-write silently destroy a still-intact record.
+	 */
+	static async open<E>(
+		slot: DurableSlot,
+		partyId: string,
+		spec: NodeLocalSnapshotSpec<E>
+	): Promise<NodeLocalSnapshot<E>> {
+		return new NodeLocalSnapshot(slot, partyId, spec, await loadEntries(slot, partyId, spec));
+	}
+
+	has(key: string): boolean {
+		return this.entries.has(key);
+	}
+
+	/** Fresh copy of the keys — a snapshot decoupled from later {@link put} calls. */
+	keySnapshot(): Set<string> {
+		return new Set(this.entries.keys());
+	}
+
+	/**
+	 * Fresh copy of the `key -> entry` map — a snapshot decoupled from later
+	 * {@link put} calls. The entries themselves need no copy: {@link put}
+	 * REPLACES an entry rather than mutating it in place.
+	 */
+	entrySnapshot(): Map<string, E> {
+		return new Map(this.entries);
+	}
+
+	/**
+	 * Add or replace an entry: the in-memory map updates SYNCHRONOUSLY (so a
+	 * synchronous caller may consult the store the moment this returns), then
+	 * the full snapshot is persisted. A persist failure rejects the returned
+	 * promise but leaves the entry in memory — this session's decision stands,
+	 * and any later successful {@link put} re-lands the complete set.
+	 */
+	put(key: string, entry: E): Promise<void> {
+		this.entries.set(key, entry);
+		const persist = this.writeChain.then(() => this.persistSnapshot());
+		// The chain itself must survive a failed persist (the next put retries the
+		// full snapshot); the caller still observes the rejection via `persist`.
+		this.writeChain = persist.catch((error) => {
+			log('%s: persist failed for party %s: %o', this.spec.label, this.partyId, error);
+		});
+		return persist;
+	}
+
+	private async persistSnapshot(): Promise<void> {
+		const envelope: Record<string, unknown> = {
+			version: ENVELOPE_VERSION,
+			partyId: this.partyId,
+			[this.spec.payloadKey]: Object.fromEntries(this.entries),
+		};
+		await this.slot.save(JSON.stringify(envelope, null, '\t'));
+	}
+}
+
+/** Read + validate the slot's text into the initial entry map (see {@link NodeLocalSnapshot.open}). */
+async function loadEntries<E>(
+	slot: DurableSlot,
+	partyId: string,
+	spec: NodeLocalSnapshotSpec<E>
+): Promise<Map<string, E>> {
+	const entries = new Map<string, E>();
+	let text: string | undefined;
+	try {
+		text = await slot.load();
+	} catch (error) {
+		// Present but unreadable: the one non-decidable case, and the one that must
+		// not cold-start empty (see NodeLocalSnapshot.open). The slot's own text is
+		// folded into the message, not left only on `cause`: the operator-facing
+		// print sites (e.g. `cadre-cli start`) log `error.message` alone, and the
+		// slot is what knows the platform detail worth acting on (which file, which
+		// database).
+		throw new Error(
+			`failed to read the ${spec.label} for party ${partyId}: ${error instanceof Error ? error.message : String(error)}`,
+			{ cause: error }
+		);
+	}
+	if (text === undefined) return entries;
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		log('%s: corrupt slot for party %s (cold start): %o', spec.label, partyId, error);
+		return entries;
+	}
+
+	const payload = envelopePayload(parsed, partyId, spec.payloadKey);
+	if (!payload) {
+		log('%s: slot for party %s has an unknown shape or a foreign partyId (cold start)', spec.label, partyId);
+		return entries;
+	}
+
+	for (const [key, raw] of Object.entries(payload)) {
+		const entry = spec.acceptEntry(key, raw);
+		if (entry === undefined) {
+			if (spec.unusableEntry === 'discard-all') {
+				log('%s: unusable entry for %s discards the whole record (party %s, cold start)', spec.label, key, partyId);
+				return new Map();
+			}
+			log('%s: dropping unusable entry for %s (party %s)', spec.label, key, partyId);
+			continue;
+		}
+		entries.set(key, entry);
+	}
+	log('%s: loaded %d entr(ies) for party %s', spec.label, entries.size, partyId);
+	return entries;
+}
+
+/**
+ * The envelope's `key -> entry` record, or undefined on any envelope mismatch —
+ * wrong version, wrong (or absent) `partyId`, missing or non-record payload.
+ * Individual entries are judged separately by
+ * {@link NodeLocalSnapshotSpec.acceptEntry}, because one bad entry does not
+ * always mean a bad record.
+ */
+function envelopePayload(
+	value: unknown,
+	partyId: string,
+	payloadKey: string
+): Record<string, unknown> | undefined {
+	if (!isRecord(value)) return undefined;
+	// A non-string partyId cannot equal the requested one, so this covers both
+	// "malformed partyId" and "another party's record".
+	if (value.version !== ENVELOPE_VERSION || value.partyId !== partyId) return undefined;
+	const payload = value[payloadKey];
+	return isRecord(payload) ? payload : undefined;
+}
+
+/**
+ * A plain JSON object usable as a `key -> value` record. Arrays are excluded
+ * explicitly: they are `typeof 'object'`, so an array payload would otherwise
+ * reach `acceptEntry` once per numeric index — the entries all get rejected in
+ * the end, but by accident rather than by decision, and noisily.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}