@serfab/cadre-core 1.3.0 → 1.5.0

package/src/seed-bootstrap.ts

@@ -811,7 +811,8 @@ export class SeedBootstrapService {
     // (`dialPeerAddrs`), so an owner whose first address never answers neither
     // stalls seed application nor goes undialed at its other addresses.
     // NOTE: `handleSeedStream` acks only after this loop, so an unreachable owner
-    // can hold the ack for up to `dialBudget.totalMs` (30 s) each, past a sender's
+    // can hold the ack for up to `dialBudget.totalMs` each — 32 s at the default declared link
+    // round trip, more on a host that declared a slower one (`link-budget.ts`) — past a sender's
     // 10 s `seedDeliverTimeoutMs`; the seed is still applied. If senders start
     // reporting accepted seeds as timed out, ack before dialing.
     const selfPeerId = this.libp2pNode.peerId?.toString();

package/src/storage-scope.ts

@@ -1,78 +1,163 @@
-/**
- * storage-scope.ts — the scope keys `CadreNodeConfig.storage.provider` is called with.
- *
- * A provider is a factory cadre-core invokes once per **scope**: once for the control
- * database and once for each strand. A strand's scope key is its strand id; the control
- * database's scope key is what this module mints.
- *
- * WHY THE CONTROL SCOPE CARRIES THE PARTY ID. The control database holds the party's
- * own records — its strands, owner keys, peers, invitations, revocations. Two parties
- * on one device must therefore not share one control store, or a node started for
- * party B reads party A's rows as if party A had written them for B. Every other
- * party-scoped store in this codebase already knows this: `PersistentTrustedOwnerStore`,
- * `PersistentBootstrapPeerStore` and `PersistentEnrolledMachineStore` each take a
- * `partyId` and fail closed on a mismatch. Putting the party id in the key here means
- * no embedder has to know it belongs there, and none can get it wrong.
- *
- * WHY IT IS ENCODED. A party id is arbitrary text — nothing in cadre-core validates
- * its shape, and the React Native reference app lets a user type one into Settings.
- * Scope keys reach real namespaces unescaped: cadre-cli builds `${config.path}/${scope}`,
- * React Native a LevelDB filename, the browser an IndexedDB database name. A party id
- * containing `/` or `..` would escape the CLI's storage directory. Base64url keeps every
- * key inside `[A-Za-z0-9._-]` — the charset embedders already rely on, and the same
- * encoding the React Native app's `secureStoreKeySegment` uses on a party id for the
- * same reason.
- *
- * THE STRAND ARM OF THAT CHARSET RULE IS NOT YET ENFORCED. The strand scope key is
- * `StrandRow.Id`, and the ids cadre-core itself mints are `strand-<digits>-<base36>`
- * / `strand-<hex>`, which satisfy the charset. But a strand row replicated into the
- * control database by another node in the party carries whatever id THAT node wrote,
- * and nothing validates its shape before `resolveStrandStorage` hands it to the
- * provider. See `tickets/backlog/bug-strand-scope-key-charset-unenforced`.
- */
-
-import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
-
-/**
- * Prefix marking a scope key as a control database rather than a strand.
- *
- * Not exported: `controlStorageScope` mints these keys and `isControlStorageScope`
- * recognizes them, which is the whole surface a caller needs.
- */
-const CONTROL_SCOPE_PREFIX = 'control-';
-
-/**
- * The storage scope key for a party's control database.
- *
- * Returns `control-` followed by the base64url encoding of `partyId`'s UTF-8 bytes,
- * so the whole key stays within `[A-Za-z0-9._-]` and is safe to use directly as a
- * file name, directory name or database name. See the module comment for why the
- * encoding is load-bearing rather than decorative.
- *
- * To read a party id back off a device — from, say, a LevelDB file named
- * `sereus-control-MTExMTExMTEtMjIyMi00MzMzLTg0NDQtNTU1NTU1NTU1NTU1` — in a browser or
- * Node console, with no dependency on this package:
- * ```js
- * const b64 = key.slice('control-'.length).replace(/-/g, '+').replace(/_/g, '/');
- * new TextDecoder().decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)))
- * ```
- * The `TextDecoder` step is not optional: `atob` alone yields one character per BYTE,
- * so a party id with any non-ASCII character in it decodes to mojibake.
- */
-export function controlStorageScope(partyId: string): string {
-	return CONTROL_SCOPE_PREFIX + uint8ArrayToString(uint8ArrayFromString(partyId, 'utf8'), 'base64url');
-}
-
-/**
- * Whether a scope key names a control database rather than a strand.
- *
- * A prefix test. Safe as one against the strand ids cadre-core mints, which are
- * `strand-`-prefixed (`strand-formation-manager.ts`, `strand-solicitation.ts`,
- * `control-formation-recorder.ts`) and so can never collide. It is NOT a security
- * boundary: a strand id replicated in from another node is unvalidated text that
- * could begin `control-`, which is one more reason to close the gap the module
- * comment names.
- */
-export function isControlStorageScope(scope: string): boolean {
-	return scope.startsWith(CONTROL_SCOPE_PREFIX);
-}
+/**
+ * storage-scope.ts — the scope keys `CadreNodeConfig.storage.provider` is called with.
+ *
+ * A provider is a factory cadre-core invokes once per **scope**: once for the control
+ * database and once for each strand. A strand's scope key is its strand id; the control
+ * database's scope key is what this module mints.
+ *
+ * WHY THE CONTROL SCOPE CARRIES THE PARTY ID. The control database holds the party's
+ * own records — its strands, owner keys, peers, invitations, revocations. Two parties
+ * on one device must therefore not share one control store, or a node started for
+ * party B reads party A's rows as if party A had written them for B. Every other
+ * party-scoped store in this codebase already knows this: `PersistentTrustedOwnerStore`,
+ * `PersistentBootstrapPeerStore` and `PersistentEnrolledMachineStore` each take a
+ * `partyId` and fail closed on a mismatch. Putting the party id in the key here means
+ * no embedder has to know it belongs there, and none can get it wrong.
+ *
+ * WHY IT IS ENCODED. A party id is arbitrary text — nothing in cadre-core validates
+ * its shape, and the React Native reference app lets a user type one into Settings.
+ * Scope keys reach real namespaces unescaped: cadre-cli builds `${config.path}/${scope}`,
+ * React Native a LevelDB filename, the browser an IndexedDB database name. A party id
+ * containing `/` or `..` would escape the CLI's storage directory. Base64url keeps every
+ * key inside `[A-Za-z0-9._-]` — the charset embedders already rely on, and the same
+ * encoding the React Native app's `secureStoreKeySegment` uses on a party id for the
+ * same reason.
+ *
+ * THE STRAND ARM OF THAT CHARSET RULE IS ENFORCED HERE. A strand's scope key is
+ * `StrandRow.Id`, and a strand row replicated into the control database by another
+ * node in the party carries whatever id THAT node wrote. `assertStrandScopeKey`
+ * (below) is the check that makes the charset true of strand keys too; it runs
+ * unconditionally at the top of `StrandInstanceManager.startStrand`, so no strand id
+ * reaches an embedder's provider — or a libp2p protocol prefix — unvalidated. Ids
+ * cadre-core mints come from `strand-id.ts`, which is built on the same predicate.
+ */
+
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+
+/**
+ * Prefix marking a scope key as a control database rather than a strand.
+ *
+ * Not exported: `controlStorageScope` mints these keys and `isControlStorageScope`
+ * recognizes them, which is the whole surface a caller needs.
+ */
+const CONTROL_SCOPE_PREFIX = 'control-';
+
+/**
+ * The storage scope key for a party's control database.
+ *
+ * Returns `control-` followed by the base64url encoding of `partyId`'s UTF-8 bytes,
+ * so the whole key stays within `[A-Za-z0-9._-]` and is safe to use directly as a
+ * file name, directory name or database name. See the module comment for why the
+ * encoding is load-bearing rather than decorative.
+ *
+ * To read a party id back off a device — from, say, a LevelDB file named
+ * `sereus-control-MTExMTExMTEtMjIyMi00MzMzLTg0NDQtNTU1NTU1NTU1NTU1` — in a browser or
+ * Node console, with no dependency on this package:
+ * ```js
+ * const b64 = key.slice('control-'.length).replace(/-/g, '+').replace(/_/g, '/');
+ * new TextDecoder().decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)))
+ * ```
+ * The `TextDecoder` step is not optional: `atob` alone yields one character per BYTE,
+ * so a party id with any non-ASCII character in it decodes to mojibake.
+ */
+export function controlStorageScope(partyId: string): string {
+	return CONTROL_SCOPE_PREFIX + uint8ArrayToString(uint8ArrayFromString(partyId, 'utf8'), 'base64url');
+}
+
+/**
+ * Whether a scope key names a control database rather than a strand.
+ *
+ * A prefix test, and a sound one: a strand scope key can never begin `control-`,
+ * because {@link isValidStrandScopeKey} rejects that prefix and
+ * {@link assertStrandScopeKey} runs on every strand launch.
+ */
+export function isControlStorageScope(scope: string): boolean {
+	return scope.startsWith(CONTROL_SCOPE_PREFIX);
+}
+
+/**
+ * The longest strand scope key accepted.
+ *
+ * The longest id cadre-core mints is 39 characters (`strand-` plus the 32 hex
+ * characters of `randomBytes(128, 'hex')` — 128 BITS, so 16 bytes), so this leaves
+ * ample room while keeping a key clear of the 255-BYTE limit every mainstream
+ * filesystem puts on one path component. The charset is ASCII, so characters and
+ * bytes are the same count here.
+ */
+const MAX_STRAND_SCOPE_KEY_LENGTH = 128;
+
+/** The charset every scope key stays within — see the module comment. */
+const SCOPE_KEY_CHARSET = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Whether a strand id is usable as a storage scope key and as a libp2p network name.
+ *
+ * A strand id is not minted locally in the general case — a strand row replicates in
+ * from another node in the party carrying whatever id THAT node wrote — and both
+ * places it lands turn it straight into a name: the embedder's storage provider
+ * (a directory under cadre-cli's storage path, a LevelDB filename, an IndexedDB
+ * database name) and the strand node's protocol prefix `/optimystic/strand-<id>`.
+ *
+ * Valid means all of:
+ * - non-empty, and at most {@link MAX_STRAND_SCOPE_KEY_LENGTH} characters;
+ * - within `[A-Za-z0-9._-]`, so no separator, drive letter, NUL or non-ASCII text;
+ * - not `.` or `..`, which the charset admits but every filesystem reads as a
+ *   directory rather than a name;
+ * - not `control-`-prefixed, which would let a strand's store masquerade as a
+ *   party's control database (see {@link isControlStorageScope}).
+ */
+export function isValidStrandScopeKey(strandId: string): boolean {
+	return strandId.length > 0
+		&& strandId.length <= MAX_STRAND_SCOPE_KEY_LENGTH
+		&& SCOPE_KEY_CHARSET.test(strandId)
+		&& strandId !== '.'
+		&& strandId !== '..'
+		&& !isControlStorageScope(strandId);
+}
+
+/**
+ * Thrown when a strand id cannot be used as a storage scope key or network name.
+ *
+ * NOT retryable: the id is a property of the strand row, so every later attempt on
+ * the same row fails identically. Callers that poll — `CadreNode.handleStrandAdded`
+ * via `StrandWatcher` — suppress the strand rather than scheduling a retry.
+ */
+export class InvalidStrandIdError extends Error {
+	readonly strandId: string;
+
+	constructor(strandId: string) {
+		super(
+			`Strand id ${JSON.stringify(strandId)} cannot be used as a storage scope key: ` +
+			`a strand id must be 1-${MAX_STRAND_SCOPE_KEY_LENGTH} characters within [A-Za-z0-9._-], ` +
+			"must not be '.' or '..', and must not begin 'control-'. " +
+			'This strand was created by a node that does not mint conforming ids; it cannot be ' +
+			'started here, because the id becomes a file, directory or database name.'
+		);
+		this.name = 'InvalidStrandIdError';
+		this.strandId = strandId;
+	}
+}
+
+/** {@link isValidStrandScopeKey} as an assertion, throwing {@link InvalidStrandIdError}. */
+export function assertStrandScopeKey(strandId: string): void {
+	if (!isValidStrandScopeKey(strandId)) {
+		throw new InvalidStrandIdError(strandId);
+	}
+}
+
+/**
+ * The charset half of the rule on its own, for the CONTROL key.
+ *
+ * {@link assertStrandScopeKey} cannot serve here: it rejects the `control-` prefix by
+ * design. Asserted at the seam that calls the provider (`CadreNode.resolveControlStorage`)
+ * rather than inside {@link controlStorageScope}, so the guarantee belongs to the call
+ * that hands a key out and not to one particular way of minting one.
+ */
+export function assertScopeKeyCharset(scope: string): void {
+	if (!SCOPE_KEY_CHARSET.test(scope)) {
+		throw new Error(
+			`Storage scope key ${JSON.stringify(scope)} leaves the [A-Za-z0-9._-] charset ` +
+			'embedders rely on to use it directly as a file, directory or database name.'
+		);
+	}
+}

package/src/strand-first-sync-gate.ts

@@ -64,12 +64,42 @@ export const DEFAULT_STRAND_FIRST_SYNC_POLL_MS = 500;
 
 /**
  * How long `CadreNode.addStrand` waits for a joining machine's first sync before rejecting
- * with {@link StrandAwaitingFirstSyncError}. Measured: over a direct connection the
- * joiner reads the founder's rows about 1.3 s after `addStrand` would previously have
- * resolved; a relayed path is slower, and a phone that just redeemed an invitation has the
- * host reachable moments ago, so 30 s is generous without leaving an app hanging.
+ * with {@link StrandAwaitingFirstSyncError}.
+ *
+ * Measured over a DIRECT connection (2026-09-16): the joiner reads the founder's rows about
+ * 1.3 s after `addStrand` would previously have resolved. That is still the fast case, and it
+ * is not what this budget has to cover.
+ *
+ * Measured over a RELAYED SLOW LINK (2026-09-26): one Windows developer machine, two
+ * relay-only `CadreNode`s (`listenAddrs: []`) on a shared loopback dedicated relay, with a
+ * 900 ms one-way per-frame outbound delay applied to every websocket by
+ * `integration-tests/src/harness/ws-latency.ts` in `pipelined` mode — frames stay overlapped
+ * in flight, so the figure is latency and bandwidth stays unlimited; the harness's other mode
+ * (`serial`) is a per-socket frame-rate cap and its delays are NOT comparable
+ * (`docs/testing.md` → "Link latency"). A round trip therefore costs about
+ * 1.8 s. Time from `addStrand` to writable, for a machine holding nothing of the strand yet:
+ * 23, 27, 31 and 41 s over four runs at optimystic's 1000 ms cohort read deadline, and 35, 42
+ * and 46 s over three runs at a 5000 ms one. **The second band is the one in force**: sereus
+ * declares 5000 ms (`COHORT_READ_DEADLINE_MS`, `quereus-plugin-sereus/src/cluster-size.ts`),
+ * because 1000 ms is shorter than one round trip on that link and leaves every cohort read with
+ * no answer to corroborate against. Widening that deadline makes a consult against a peer that
+ * cannot answer cost longer, and this phase runs several of those — which is why the two bands
+ * are both recorded here, and why a change to either number has to be weighed against the
+ * other. 120 s clears the worst sample of the band in force by about 2.6x. The previous 30 s
+ * default sat INSIDE the first band, so roughly half of those joins were rejected as "not
+ * writable yet" while the sync was progressing normally and went on to complete.
+ *
+ * NOTE: accepted tradeoff — what 120 s costs. This wait is what an app's `addStrand` sits in
+ * before it is told "not yet", so a strand none of whose members is reachable at all takes two
+ * minutes to report instead of thirty seconds. The slow report was weighed against refusing
+ * joins that were working, and the refusal is the worse failure. The cost is bounded — the
+ * rejection is retryable, the strand stays launched and keeps probing, and `strand:writable`
+ * fires the moment the sync lands, so an app that listens for the event rather than awaiting
+ * the call is unaffected either way. Revisit if the gate ever learns whether ANY other member
+ * is connected: "no peer at all" could then be reported at once and this budget would only
+ * ever be spent on a sync that is actually in progress.
  */
-export const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 30_000;
+export const DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS = 120_000;
 
 /** Embedder-facing tuning for the gate, threaded from `CadreNodeConfig.strandFirstSync`. */
 export interface StrandFirstSyncConfig {
@@ -242,8 +272,7 @@ export class StrandFirstSyncGate {
   private async probe(): Promise<void> {
     if (this.stopped || this.opened || this.probing) return;
     this.probing = true;
-    const held = await strandFirstSyncComplete(this.deps.database.getDatabase(), this.deps.label)
-      .finally(() => { this.probing = false; });
+    const held = await this.probeHeld();
     // Re-check after the await: a release or a force-open may have landed mid-read.
     if (this.stopped || this.opened) return;
     if (!held) {
@@ -255,4 +284,23 @@ export class StrandFirstSyncGate {
     log('[%s] first-sync gate opened: Strand.Header and every App table read from a peer', this.deps.label);
     this.deps.onHeaderHeld();
   }
+
+  /**
+   * One probe's answer, with a throw from OUTSIDE {@link strandFirstSyncComplete}'s own read
+   * guards — the `App` schema lookup, or `getDatabase()` itself — reported as "not yet" like
+   * any failing read. The loop is scheduled from `void this.probe()`, so an escaping rejection
+   * would be unhandled AND leave nothing scheduled: the strand would stay gated for the whole
+   * `timeoutMs` and never recover, which is the one failure this gate must not have.
+   */
+  private async probeHeld(): Promise<boolean> {
+    try {
+      return await strandFirstSyncComplete(this.deps.database.getDatabase(), this.deps.label);
+    } catch (error) {
+      log('[%s] first-sync probe threw (treated as not yet synced): %s', this.deps.label,
+        error instanceof Error ? error.message : String(error));
+      return false;
+    } finally {
+      this.probing = false;
+    }
+  }
 }