@serfab/cadre-core 0.9.0 → 0.10.0

package/src/delegate-admission.ts

@@ -0,0 +1,302 @@
+/**
+ * Delegate-peer admission grants for a party control node that also runs the
+ * circuit-relay server.
+ *
+ * A strand node runs as its own libp2p instance with its own transport peerId,
+ * derived from the cadre identity key + strandId (`strand-transport-key.ts`).
+ * That derivation uses the member's PRIVATE seed by design, so no third party —
+ * including a co-cadre relay — can recompute it. When a NAT'd member's strand
+ * node tries to reserve a circuit-relay slot on a sibling's control node, the
+ * relay's membership connection gater sees an unknown peerId and denies the
+ * connection, which kills the reservation and fails the strand's
+ * `libp2p.start()` outright.
+ *
+ * The resolution (docs/strands.md → "Relays and admission"): a party control
+ * node running a relay is party-private infrastructure — it relays for its own
+ * party's nodes, including the extra transport identities its members' strand
+ * nodes run as, and for nobody else. The mechanism is a **member-announced
+ * delegate grant**: before a member's control node starts a strand node, it
+ * tells its siblings (over the already-authenticated `/sereus/strand-addr/1.0.0`
+ * RPC) the derived peerId that strand node will use, and the receiver holds a
+ * short-lived, in-memory admission grant for exactly that peerId. The grant is
+ * consulted ONLY by the connection-level gate
+ * (`CadreNode.admitInboundControlConnection`); the fail-closed per-stream gate
+ * (`authorizeInboundControlStream`) never honors it, so a delegate gets the
+ * connection (all a circuit-relay `hop` reservation needs) and nothing more.
+ *
+ * A grant is a delegation of trust to an already-trusted member: the receiver
+ * cannot verify that the announced peerId really is the member's strand node,
+ * so an authorized member can hand CONNECTION-level access to a peerId of its
+ * choosing for up to {@link DELEGATE_GRANT_TTL_MS}. The caps below bound how
+ * far a buggy or compromised member can stretch that.
+ *
+ * The receiver side is {@link DelegateAdmissionStore}. The announcer side keeps
+ * its own throttle state (a "last announced at" map that `CadreNode` owns) and
+ * decides from it, per reconcile pass, which relays are due a re-announce —
+ * {@link dueRelayAnnounces} and {@link pruneStoppedStrandAnnounces} are that
+ * decision, pure and testable, kept here beside the TTL they are derived from.
+ */
+
+import debug from 'debug';
+import { multiaddr } from '@multiformats/multiaddr';
+import { peerIdFromString } from '@libp2p/peer-id';
+
+const log = debug('sereus:cadre:delegate-admission');
+
+/**
+ * How long one announced delegate grant stays valid without a re-announce.
+ * Announcers refresh at half this (`CadreNode`'s reconcile pass), so a live
+ * strand's grant never lapses while its control node can still reach the relay.
+ */
+export const DELEGATE_GRANT_TTL_MS = 30 * 60 * 1000;
+
+/** Cap on live grants per announcing member (soonest-expiry evicted first). */
+export const MAX_DELEGATE_GRANTS_PER_MEMBER = 32;
+
+/** Cap on live grants in total (soonest-expiry evicted first). */
+export const MAX_DELEGATE_GRANTS = 256;
+
+/** One recorded delegate admission grant. */
+interface DelegateGrant {
+  /** The authorized member whose control node announced this delegate. */
+  announcerPeerId: string;
+  /** The strand the delegate serves — diagnostics + per-strand replace semantics. */
+  strandId: string;
+  /** The delegate transport peerId the grant admits. */
+  delegatePeerId: string;
+  /** Epoch ms after which the grant is inert. */
+  expiresAt: number;
+}
+
+/**
+ * Composite map key for the per-(peer, strand) state on both sides: the
+ * receiver's replace-per-(announcer, strand) grant, and the announcer's
+ * per-(target, strand) throttle timestamp.
+ */
+export function peerStrandKey(peerId: string, strandId: string): string {
+  return `${peerId}\n${strandId}`;
+}
+
+/** The `strandId` half of a {@link peerStrandKey}. */
+function strandIdOfKey(key: string): string {
+  return key.slice(key.indexOf('\n') + 1);
+}
+
+/**
+ * In-memory store of delegate admission grants, keyed by (announcer, strandId)
+ * so a re-announce REPLACES the previous delegate peerId rather than
+ * accumulating — a restarted strand cannot leak grants. Expired entries are
+ * pruned lazily on every read/write. Injectable `now` keeps expiry testable
+ * without fake timers.
+ */
+export class DelegateAdmissionStore {
+  private readonly grants = new Map<string, DelegateGrant>();
+  private readonly ttlMs: number;
+
+  constructor(ttlMs: number = DELEGATE_GRANT_TTL_MS) {
+    this.ttlMs = ttlMs;
+  }
+
+  /** Number of live (unexpired at last prune) grants — test/diagnostic surface. */
+  get size(): number {
+    return this.grants.size;
+  }
+
+  /**
+   * Record (or refresh) a grant: `delegatePeerId` acts on behalf of
+   * `announcerPeerId` for `strandId`, valid for the store's TTL from `now`.
+   * Enforces {@link MAX_DELEGATE_GRANTS_PER_MEMBER} and
+   * {@link MAX_DELEGATE_GRANTS}, evicting the soonest-expiry grant first —
+   * biased against the stalest delegation, never against the fresh announce.
+   */
+  grant(announcerPeerId: string, strandId: string, delegatePeerId: string, now: number = Date.now()): void {
+    this.prune(now);
+    const key = peerStrandKey(announcerPeerId, strandId);
+    if (!this.grants.has(key)) {
+      this.evictAtCap(
+        MAX_DELEGATE_GRANTS_PER_MEMBER,
+        (g) => g.announcerPeerId === announcerPeerId
+      );
+      this.evictAtCap(MAX_DELEGATE_GRANTS, () => true);
+    }
+    this.grants.set(key, { announcerPeerId, strandId, delegatePeerId, expiresAt: now + this.ttlMs });
+    log('Delegate grant recorded: %s → %s (strand %s, %d live)', announcerPeerId, delegatePeerId, strandId, this.grants.size);
+  }
+
+  /**
+   * Drop every grant. Called when the owning node stops: grants are scoped to
+   * the session that recorded them, and outliving it would admit delegates
+   * announced against a node that no longer exists.
+   */
+  clear(): void {
+    this.grants.clear();
+  }
+
+  /** Is `remotePeerId` covered by a live grant? Prunes expired entries as it goes. */
+  has(remotePeerId: string, now: number = Date.now()): boolean {
+    this.prune(now);
+    for (const grant of this.grants.values()) {
+      if (grant.delegatePeerId === remotePeerId) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Drop every grant whose expiry has passed. */
+  private prune(now: number): void {
+    for (const [key, grant] of this.grants) {
+      if (grant.expiresAt <= now) {
+        this.grants.delete(key);
+      }
+    }
+  }
+
+  /**
+   * If the grants matching `filter` are at `cap`, evict the soonest-expiry one
+   * among them to make room for the insert the caller is about to do.
+   */
+  private evictAtCap(cap: number, filter: (grant: DelegateGrant) => boolean): void {
+    let count = 0;
+    let victimKey: string | undefined;
+    let victimExpiry = Number.POSITIVE_INFINITY;
+    for (const [key, grant] of this.grants) {
+      if (!filter(grant)) {
+        continue;
+      }
+      count++;
+      if (grant.expiresAt < victimExpiry) {
+        victimExpiry = grant.expiresAt;
+        victimKey = key;
+      }
+    }
+    if (count >= cap && victimKey !== undefined) {
+      const victim = this.grants.get(victimKey)!;
+      this.grants.delete(victimKey);
+      log('Delegate grant cap %d hit — evicted soonest-expiry grant %s → %s (strand %s)',
+        cap, victim.announcerPeerId, victim.delegatePeerId, victim.strandId);
+    }
+  }
+}
+
+/** A circuit relay named by a multiaddr, as an announce target. */
+export interface CircuitRelayTarget {
+  /** The relay's peerId — the `<relay>` in `…/p2p/<relay>/p2p-circuit…`. */
+  relayPeerId: string;
+  /**
+   * The relay's DIRECT dial multiaddr (the prefix before `/p2p-circuit`),
+   * usable as a dial fallback when no connection to the relay is open yet.
+   */
+  relayAddr: string;
+}
+
+/**
+ * Extract the circuit relays named by a multiaddr list — for each
+ * `…/p2p/<relay>/p2p-circuit…` entry, the relay's peerId and its direct dial
+ * prefix. A bare `/p2p-circuit` (no relay named), a non-circuit addr, an
+ * unparsable addr, and an unparsable relay peerId are all skipped. A trailing
+ * `/p2p/<dst>` after the circuit component names the DESTINATION, never the
+ * relay, and is ignored. Deduplicated by relay peerId (first addr wins).
+ */
+export function extractCircuitRelayTargets(addrs: string[]): CircuitRelayTarget[] {
+  const byRelay = new Map<string, CircuitRelayTarget>();
+  for (const addr of addrs) {
+    const target = circuitRelayTarget(addr);
+    if (target && !byRelay.has(target.relayPeerId)) {
+      byRelay.set(target.relayPeerId, target);
+    }
+  }
+  return [...byRelay.values()];
+}
+
+/**
+ * Of `relays`, the ones whose grant for `strandId` is due a re-announce: never
+ * announced to, or last announced at least half the TTL ago. Half, so a failed
+ * refresh has one more attempt before the grant lapses — a lapsed grant means
+ * the relay denies the strand node's reservation re-dial.
+ *
+ * `announceAt` is the announcer-side "last announced at" map, keyed by
+ * {@link peerStrandKey} on the peer announced TO.
+ */
+export function dueRelayAnnounces(
+  announceAt: ReadonlyMap<string, number>,
+  relays: readonly CircuitRelayTarget[],
+  strandId: string,
+  now: number,
+  ttlMs: number = DELEGATE_GRANT_TTL_MS
+): CircuitRelayTarget[] {
+  return relays.filter(
+    (relay) => now - (announceAt.get(peerStrandKey(relay.relayPeerId, strandId)) ?? 0) >= ttlMs / 2
+  );
+}
+
+/**
+ * Drop `announceAt` entries whose strand is no longer running — a stopped
+ * strand needs no refresh, and without this the map grows for the node's
+ * lifetime. Mutates in place.
+ */
+export function pruneStoppedStrandAnnounces(
+  announceAt: Map<string, number>,
+  runningStrandIds: ReadonlySet<string>
+): void {
+  for (const key of announceAt.keys()) {
+    if (!runningStrandIds.has(strandIdOfKey(key))) {
+      announceAt.delete(key);
+    }
+  }
+}
+
+/**
+ * The circuit relay named by `addr`, throwing when `addr` is unparsable or names
+ * no relay. The throwing form exists for CONFIG-facing callers (`relay-addrs.ts`),
+ * where a typo must fail loudly rather than cost the node its reachability;
+ * {@link extractCircuitRelayTargets} reads runtime-discovered addrs instead and
+ * logs-and-skips.
+ */
+export function circuitRelayTargetOrThrow(addr: string): CircuitRelayTarget {
+  const target = parseCircuitRelayTarget(addr);
+  if (!target) {
+    throw new Error(`Multiaddr names no circuit relay (expected …/p2p/<relayPeerId>/p2p-circuit): ${addr}`);
+  }
+  return target;
+}
+
+/**
+ * The circuit relay named by `addr`; null when `addr` is well-formed but simply
+ * names no relay (a direct listen addr, a bare `/p2p-circuit`), and THROWS when
+ * `addr` is malformed (unparsable multiaddr, garbage relay peerId). The two
+ * callers want opposite things from the first case and the same thing from the
+ * second, so the distinction lives here rather than in either of them.
+ */
+function parseCircuitRelayTarget(addr: string): CircuitRelayTarget | null {
+  const ma = multiaddr(addr);
+  const components = ma.getComponents();
+  const circuitIdx = components.findIndex((c) => c.name === 'p2p-circuit');
+  if (circuitIdx < 1) {
+    return null;
+  }
+  const relay = components[circuitIdx - 1];
+  if (relay.name !== 'p2p' || !relay.value) {
+    return null;
+  }
+  peerIdFromString(relay.value); // validate; throws on garbage
+  return {
+    relayPeerId: relay.value,
+    relayAddr: ma.decapsulate('/p2p-circuit').toString()
+  };
+}
+
+/**
+ * One-addr body of {@link extractCircuitRelayTargets}; null when `addr` names no
+ * relay. Only a MALFORMED addr logs — the addr lists this reads (a node's live
+ * multiaddrs, its configured listen addrs) are mostly direct addrs, and calling
+ * each of those "unparsable" is both wrong and per-announce noise.
+ */
+function circuitRelayTarget(addr: string): CircuitRelayTarget | null {
+  try {
+    return parseCircuitRelayTarget(addr);
+  } catch (err) {
+    log('Skipping unparsable relay addr %s: %o', addr, err);
+    return null;
+  }
+}

package/src/device-token.ts

@@ -4,20 +4,20 @@
  * another peer's row.
  *
  * Modeled directly on {@link peerRecordSignedPayload} (peer-record.ts): 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 is reconstructable inside the `DeviceToken.AuthorizedUpdate` SQL
- * constraint from the row's own columns:
+ * 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 even with an opaque platform token. It
+ * is intentionally NOT JSON-canonicalized (deterministic across node/browser/RN,
+ * no key ordering) and is reconstructable inside the `DeviceToken.AuthorizedUpdate`
+ * SQL constraint from the row's own columns:
  *
- *   digest(new.PeerId || '|' || new.Platform || '|' || new.Token || '|'
- *          || cast(new.UpdatedAt as text))
+ *   digest('CadreControl.DeviceToken', 'publish',
+ *          new.PeerId, new.Platform, new.Token, cast(new.UpdatedAt as text))
  *
  * Keep {@link deviceTokenSignedPayload} and that constraint byte-for-byte in sync.
- * The `'|'` delimiter is safe: a base58btc PeerId, a fixed `'fcm'`/`'apns'` platform
- * string, and a base-10 integer never contain it. The opaque platform token is the
- * last variable-length field before the integer stamp, so even a token containing a
- * `'|'` cannot create a collision with a different field split.
+ * 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.
  *
  * Unlike a peer-address record, a device-token record carries NO public key: the
  * signature is verified against the `CadrePeer.PublicKey` bound to the same PeerId
@@ -26,6 +26,7 @@
  */
 
 import { digest, sign, verify } from '@optimystic/quereus-plugin-crypto';
+import { controlAuthorizationFields } from './control-authorization.js';
 import type { DeviceTokenRecord, PushPlatform } from './types.js';
 
 /**
@@ -34,8 +35,12 @@ import type { DeviceTokenRecord, PushPlatform } from './types.js';
  * base64url output of a single `digest(...)`, which round-trips cleanly.
  */
 export function deviceTokenSignedPayload(record: Omit<DeviceTokenRecord, 'sig'>): string {
-  const joined = `${record.peerId}|${record.platform}|${record.token}|${record.updatedAt}`;
-  return digest([joined], 'sha256', 'base64url') as string;
+  const fields = controlAuthorizationFields(
+    'CadreControl.DeviceToken',
+    'publish',
+    [record.peerId, record.platform, record.token, String(record.updatedAt)]
+  );
+  return digest(fields, 'sha256', 'base64url') as string;
 }
 
 /**

package/src/ed25519-key.ts

@@ -1,69 +1,134 @@
-import { toString as uint8ArrayToString } from 'uint8arrays';
-import { getPublicKey } from '@optimystic/quereus-plugin-crypto';
-import type { PrivateKey } from '@libp2p/interface';
-
-/**
- * An Ed25519 keypair expressed in the base64url form that
- * `@optimystic/quereus-plugin-crypto` (`sign`/`verify`/`getPublicKey`) consumes.
- * Generic bridge type — reused for owner keys, member keys, and any other
- * seed→public keypair the control/strand databases sign with.
- */
-export interface Ed25519KeyPair {
-  /** 32-byte Ed25519 seed, base64url-encoded — the crypto-plugin private key. */
-  privateKeyB64: string;
-  /** 32-byte Ed25519 public key, base64url-encoded. */
-  publicKeyB64: string;
-}
-
-/**
- * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
- * control- and strand-database signing constraints.
- *
- * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
- * seed (the actual scalar source), the last 32 are the public key — see
- * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
- * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
- * derives the public key from it with standard Ed25519. The two derivations
- * agree, so the node's peer identity and its signing key are one keypair:
- * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
- *
- * @param privateKey - The node's libp2p Ed25519 private key.
- * @returns The base64url seed/public-key pair for signing operations.
- * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
- */
-export function ed25519KeyPairFromLibp2p(privateKey: PrivateKey): Ed25519KeyPair {
-  if (privateKey.type !== 'Ed25519') {
-    throw new Error(`ed25519KeyPairFromLibp2p requires an Ed25519 key, got ${privateKey.type}`);
-  }
-
-  const raw = privateKey.raw;
-  if (raw.length !== 64) {
-    throw new Error(`Expected a 64-byte Ed25519 raw private key (seed||public), got ${raw.length} bytes`);
-  }
-
-  const seed = raw.subarray(0, 32);
-  const publicKeyRaw = privateKey.publicKey.raw;
-  if (publicKeyRaw.length !== 32) {
-    throw new Error(`Expected a 32-byte Ed25519 public key, got ${publicKeyRaw.length} bytes`);
-  }
-
-  return {
-    privateKeyB64: uint8ArrayToString(seed, 'base64url'),
-    publicKeyB64: uint8ArrayToString(publicKeyRaw, 'base64url'),
-  };
-}
-
-/**
- * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
- * — the same derivation the seed-bootstrap signer uses internally
- * (`SeedBootstrapService` constructor). Use this to enroll a standalone
- * (non-libp2p) key into the control DB before minting an invite, when the
- * key is *not* the node's peer identity (so `ed25519KeyPairFromLibp2p`,
- * which needs a libp2p key object, does not apply).
- *
- * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
- * @returns The base64url-encoded Ed25519 public key.
- */
-export function ed25519PublicKeyFromPrivate(privateKeyB64: string): string {
-  return getPublicKey(privateKeyB64, 'ed25519', 'base64url', 'base64url') as string;
-}
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { getPublicKey } from '@optimystic/quereus-plugin-crypto';
+import type { PrivateKey } from '@libp2p/interface';
+
+/**
+ * An Ed25519 keypair expressed in the base64url form that
+ * `@optimystic/quereus-plugin-crypto` (`sign`/`verify`/`getPublicKey`) consumes.
+ * Generic bridge type — reused for owner keys, member keys, and any other
+ * seed→public keypair the control/strand databases sign with.
+ */
+export interface Ed25519KeyPair {
+  /** 32-byte Ed25519 seed, base64url-encoded — the crypto-plugin private key. */
+  privateKeyB64: string;
+  /** 32-byte Ed25519 public key, base64url-encoded. */
+  publicKeyB64: string;
+}
+
+/**
+ * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
+ * control- and strand-database signing constraints.
+ *
+ * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
+ * seed (the actual scalar source), the last 32 are the public key — see
+ * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
+ * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
+ * derives the public key from it with standard Ed25519. The two derivations
+ * agree, so the node's peer identity and its signing key are one keypair:
+ * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
+ *
+ * @param privateKey - The node's libp2p Ed25519 private key.
+ * @returns The base64url seed/public-key pair for signing operations.
+ * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
+ */
+export function ed25519KeyPairFromLibp2p(privateKey: PrivateKey): Ed25519KeyPair {
+  if (privateKey.type !== 'Ed25519') {
+    throw new Error(`ed25519KeyPairFromLibp2p requires an Ed25519 key, got ${privateKey.type}`);
+  }
+
+  const raw = privateKey.raw;
+  if (raw.length !== 64) {
+    throw new Error(`Expected a 64-byte Ed25519 raw private key (seed||public), got ${raw.length} bytes`);
+  }
+
+  const seed = raw.subarray(0, 32);
+  const publicKeyRaw = privateKey.publicKey.raw;
+  if (publicKeyRaw.length !== 32) {
+    throw new Error(`Expected a 32-byte Ed25519 public key, got ${publicKeyRaw.length} bytes`);
+  }
+
+  return {
+    privateKeyB64: uint8ArrayToString(seed, 'base64url'),
+    publicKeyB64: uint8ArrayToString(publicKeyRaw, 'base64url'),
+  };
+}
+
+/**
+ * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
+ * — the same derivation the seed-bootstrap signer uses internally
+ * (`SeedBootstrapService` constructor). Use this to enroll a standalone
+ * (non-libp2p) key into the control DB before minting an invite, when the
+ * key is *not* the node's peer identity (so `ed25519KeyPairFromLibp2p`,
+ * which needs a libp2p key object, does not apply).
+ *
+ * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
+ * @returns The base64url-encoded Ed25519 public key.
+ */
+export function ed25519PublicKeyFromPrivate(privateKeyB64: string): string {
+  return getPublicKey(privateKeyB64, 'ed25519', 'base64url', 'base64url') as string;
+}
+
+/** Longest rejected key value echoed back in an error — a real key is 43 base64url chars. */
+const REJECTED_VALUE_ECHO_LIMIT = 64;
+
+/**
+ * Render a rejected value for an error message, capped: owner keys now reach this check
+ * from remote-supplied fields (a `CadreInvite`'s `ownerKeys`, a donation request's
+ * `ownerKeys`), so an unbounded echo would let a peer turn one junk string into a
+ * megabyte of log line.
+ */
+function describeRejected(value: string): string {
+  return value.length <= REJECTED_VALUE_ECHO_LIMIT
+    ? value
+    : `${value.slice(0, REJECTED_VALUE_ECHO_LIMIT)}… (${value.length} chars)`;
+}
+
+/**
+ * Reject a value that isn't shaped like a base64url-encoded 32-byte Ed25519 public key
+ * before it reaches the control database, where a malformed key would otherwise sit
+ * indistinguishable from a real one until some later, unrelated signature check fails.
+ *
+ * Trims first, reusing the blank-value message for an empty result so that case keeps its
+ * existing wording instead of a confusing base64url error. Every rejection names the offending
+ * value (capped, see {@link describeRejected}) — with several keys in one batch, the message is
+ * the only thing that says WHICH one. Does not check the decoded bytes
+ * are a valid point on the Ed25519 curve — a well-formed-but-off-curve key still fails
+ * signature verification later exactly like any other wrong key.
+ *
+ * **This rule is restated once outside this package**, in `validateOwnerKey`
+ * (`packages/cadre-provider/src/server/owner-key-validation.ts`): cadre-provider declares no
+ * `workspace:` dependencies and validates `POST /containers` pins over `uint8arrays`
+ * directly. Change the rule here and change it there — the copies are kept in step by
+ * hand, since neither package can import the other's. Each side pins its own copy to the
+ * same accept/reject table (`test/ed25519-key.spec.ts` here,
+ * `create-container-owner-keys.test.ts` there), so a change fails the suite of the
+ * package it was made in and lands the editor on this pointer.
+ *
+ * @param value - Candidate base64url-encoded Ed25519 public key.
+ * @param label - Human-readable name of the field, used in error messages.
+ * @returns The trimmed value, so callers write the same bytes they validated.
+ */
+export function requireEd25519PublicKeyB64(value: string, label: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`A ${label} is required (received an empty or whitespace-only value)`);
+  }
+
+  let decoded: Uint8Array;
+  try {
+    decoded = uint8ArrayFromString(trimmed, 'base64url');
+  } catch (error) {
+    throw new Error(
+      `A ${label} must be a base64url-encoded Ed25519 public key (could not decode "${describeRejected(trimmed)}" as base64url)`,
+      { cause: error },
+    );
+  }
+
+  if (decoded.length !== 32) {
+    throw new Error(
+      `A ${label} must be a base64url-encoded 32-byte Ed25519 public key ("${describeRejected(trimmed)}" decoded to ${decoded.length} bytes)`,
+    );
+  }
+
+  return trimmed;
+}

package/src/file-durable-slot.ts

@@ -0,0 +1,61 @@
+/**
+ * Node-only {@link DurableSlot} backend: one JSON file per party under `dir`,
+ * at `<dir>/<name>.<encoded partyId>.json` (0600, atomically replaced on every
+ * save), so one directory can hold the same node-local record for several
+ * parties without cross-party leakage.
+ *
+ * This is the whole platform-specific part of the file-backed node-local
+ * stores (`trusted-owner-store-file.ts`, `bootstrap-peer-store-file.ts`); the
+ * load policy, envelope and write chain are cross-platform in
+ * `node-local-snapshot.ts`. Like its two importers, this module imports
+ * `node:fs/promises`, so it is kept OUT of the package's cross-platform
+ * default entry and is not itself an exported subpath.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { encodeFileSafeComponent, isNotFound, writeFileAtomically } from './fs-atomic.js';
+import type { DurableSlot } from './node-local-snapshot.js';
+
+export class FileDurableSlot implements DurableSlot {
+	/** Filename-safe form of the party id, shared by the record and temp paths. */
+	private readonly encodedParty: string;
+
+	constructor(
+		private readonly dir: string,
+		private readonly name: string,
+		partyId: string
+	) {
+		this.encodedParty = encodeFileSafeComponent(partyId);
+	}
+
+	/**
+	 * The record's bytes as text. An absent file (ENOENT — including an absent
+	 * directory) is `undefined`, a cold start. Every other read failure
+	 * (EACCES, EISDIR, EIO, …) THROWS, per {@link DurableSlot.load}: the caller
+	 * must not mistake an unreadable file for an empty one and snapshot-write
+	 * over it.
+	 */
+	async load(): Promise<string | undefined> {
+		try {
+			return (await readFile(this.filePath())).toString('utf8');
+		} catch (error) {
+			if (isNotFound(error)) return undefined;
+			throw new Error(`FileDurableSlot: ${this.filePath()} is present but unreadable`, { cause: error });
+		}
+	}
+
+	async save(text: string): Promise<void> {
+		await writeFileAtomically(this.dir, this.tempPath(), this.filePath(), new TextEncoder().encode(text));
+	}
+
+	private filePath(): string {
+		return join(this.dir, `${this.name}.${this.encodedParty}.json`);
+	}
+
+	/** Sibling temp path for the atomic replace (random component: collide-free). */
+	private tempPath(): string {
+		const unique = randomBytes(6).toString('hex');
+		return join(this.dir, `${this.name}.${this.encodedParty}.${unique}.tmp`);
+	}
+}