@serfab/cadre-core 1.3.0 → 1.4.0

package/README.md

@@ -236,9 +236,11 @@ A **scope key** is what the factory receives. It is the strand id for each stran
 which holds one party's own records and must not be shared between parties. Every key is
 opaque and already safe as a file, directory or database name (always within
 `[A-Za-z0-9._-]`): use it verbatim, do not parse it. `isControlStorageScope(scope)` tells
-the two kinds apart. Caveat, until `bug-strand-scope-key-charset-unenforced` lands: the
-charset is enforced for the control key but only *conventional* for a strand id, which
-reaches the factory verbatim even when the strand row replicated in from another node.
+the two kinds apart. The control key holds the charset by base64url encoding; a strand
+id holds it by check — `assertStrandScopeKey` runs on every strand launch, so a strand
+whose row replicated in from another node with an unusable id is refused rather than
+handed to the factory, and on `publishStrand`, so this node never writes such an id into
+the party's control database to begin with.
 
 Available storage implementations:
 | Package | Environment | Description |

package/dist/cadre-node.d.ts

@@ -279,8 +279,10 @@ export declare class CadreNode implements SAppIdLookup {
      * dead entry behind; recovery today is a fresh invitation.
      *
      * NOTE: entries are kept for the node's lifetime, including across a
-     * {@link stopStrand} — a stopped strand may be rediscovered by the watcher and must
-     * still get its seed. Each strand's list is capped at `MAX_STRAND_ADDRS`, but the
+     * {@link stopStrand} — a stopped strand may be claimed again with {@link addStrand}
+     * (the watcher itself will not re-offer it: the stop suppresses the id for the rest of
+     * the session) and must still get its seed. Each strand's list is capped at
+     * `MAX_STRAND_ADDRS`, but the
      * number of KEYS is bounded only by the strands this node has ever formed as an
      * initiator (not by time); if a node ever forms strands at scale, evict on
      * `unpublishStrand` or cap the map.
@@ -732,6 +734,12 @@ export declare class CadreNode implements SAppIdLookup {
      * derivation from it (`db-p2p` namespaces all of the node's protocol ids as
      * `/optimystic/<networkName>/...`), so the node options and the block-transfer
      * protocol prefix the control backfill dials can never drift apart.
+     *
+     * NOTE: the party id goes in UNENCODED here, unlike in `controlStorageScope`. Safe
+     * today because a party id is locally configured rather than replicated in, and both
+     * ends of a connection derive this string identically — an odd party id yields an odd
+     * but consistent protocol id, not a mismatch or an escaped name. If a party id ever
+     * arrives from the network, encode it here as the storage scope key already does.
      */
     private controlNetworkName;
     /**
@@ -1862,17 +1870,17 @@ export declare class CadreNode implements SAppIdLookup {
      *
      * A rejected call leaves nothing running but DOES leave the sApp config
      * registered, deliberately: both an explicit retry and the {@link StrandWatcher}'s
-     * automatic relaunch need it. That background relaunch covers only a strand the
-     * WATCHER launched: it forgets a row whose `onStrandAdded` threw and re-attempts it
-     * on a later poll (each failure re-emitting `strand:error`) until it succeeds. A
-     * strand claimed here after it was DISCOVERED gets no such retry — the watcher
-     * already recorded it in its `knownStrands` when it offered it as
-     * `strand:discovered`, and no later poll re-offers a strand it knows. This call has
-     * also already dropped it from {@link getDiscoveredStrands}, so a failed claim
-     * leaves the strand dormant until the caller retries or the node restarts (see
-     * `backlog/bug-discovered-strand-lost-when-claim-fails`).
-     * {@link detachStrand} (reached via {@link stopStrand}) is what abandons a strand
-     * for good.
+     * automatic relaunch need it. A failed launch here hands the strand back to that
+     * relaunch — `StrandWatcher.forgetStrand` drops the id from the watcher's
+     * `knownStrands` and records the backoff, so a later poll re-attempts it on the same
+     * `pollInterval * 2^(failures-1)` ladder a watcher-driven failure gets. Because the
+     * config stays registered, the retry takes `handleStrandAdded`'s auto-launch branch:
+     * what the app sees is `strand:error` per failed retry and `strand:started` when one
+     * succeeds, never a second `strand:discovered`. {@link detachStrand} (reached via
+     * {@link stopStrand}) is what abandons a strand for good, and its stop suppresses the
+     * strand in the watcher so this retry cannot resurrect it — a call to THIS method lifts
+     * that suppression again, since an explicit claim is a deliberate reversal of the
+     * deliberate stop.
      */
     addStrand(config: StrandConfig): Promise<StrandInstance>;
     /**
@@ -1945,7 +1953,8 @@ export declare class CadreNode implements SAppIdLookup {
      * @returns The live `Strand` row — the one just inserted, or the matching one already
      *   there. A closed strand's caller should carry THIS row's `MemberPrivateKey` forward:
      *   on a repeat it is the stored key, not the argument.
-     * @throws if the node is not started, exposes no owner signing key, the id is blank, a
+     * @throws if the node is not started, exposes no owner signing key, the id is blank or
+     *   unusable as a storage scope key (`InvalidStrandIdError` — see `storage-scope.ts`), a
      *   row with the same id holds different content, or the control DB rejects the
      *   (unauthorized) insert.
      */
@@ -2465,11 +2474,11 @@ export declare class CadreNode implements SAppIdLookup {
      * Stop a strand on THIS node only: untrack it from hibernation, drop its sApp config,
      * stop the local instance, and emit `strand:stopped`. The shared `Strand` row is left
      * intact, so on the next node RESTART the strand is rediscovered and surfaces as
-     * `strand:discovered` again — not on the next watcher poll, which never re-offers a
-     * strand it has already seen (`StrandWatcher.knownStrands` retains the id for the life
-     * of the process). The stop also drops the strand from {@link getDiscoveredStrands},
-     * so a drain cannot undo a deliberate stop. Party-wide removal is
-     * {@link unpublishStrand}.
+     * `strand:discovered` again — but never again in THIS session: the stop suppresses the
+     * id in the watcher (`StrandWatcher.suppressStrand`) and drops it from
+     * {@link getDiscoveredStrands}, so neither a later poll nor a drain can undo a
+     * deliberate stop. Only an explicit {@link addStrand} does, which is the caller
+     * reversing its own decision. Party-wide removal is {@link unpublishStrand}.
      */
     stopStrand(strandId: string): Promise<void>;
     /**
@@ -2490,6 +2499,10 @@ export declare class CadreNode implements SAppIdLookup {
      * readings are the intended one: `handleStrandRemoved` arrives because the control row
      * is gone, and an explicit {@link stopStrand} is a deliberate abandonment — neither
      * strand may be re-offered to a later `getDiscoveredStrands()` drain.
+     *
+     * The watcher-level suppression that makes a stop permanent is deliberately NOT here,
+     * only in {@link stopStrand}: the two callers diverge on it. A vanished control row
+     * that reappears is a fresh strand and must be offered again.
      */
     private detachStrand;
     /**

package/dist/cadre-node.js

@@ -4,11 +4,11 @@ import { peerIdFromString, peerIdFromPrivateKey } from '@libp2p/peer-id';
 import { createLibp2pNode } from '@optimystic/db-p2p';
 import { wrapStorageWithCache, disposeStorageCache } from '@serfab/quereus-plugin-sereus';
 import { multiaddr } from '@multiformats/multiaddr';
-import { controlClusterPolicy, CONTROL_REPLICATION_BREADTH, DEFAULT_CHECKIN_WINDOW_MS } from './types.js';
+import { controlClusterPolicy, CONTROL_REPLICATION_BREADTH, DEFAULT_CHECKIN_WINDOW_MS, DEFAULT_CONNECTION_MONITOR } from './types.js';
 import { sign } from '@optimystic/quereus-plugin-crypto';
 import { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, requireEd25519PublicKeyB64 } from './ed25519-key.js';
 import { strandTransportKey } from './strand-transport-key.js';
-import { controlStorageScope } from './storage-scope.js';
+import { assertScopeKeyCharset, assertStrandScopeKey, controlStorageScope, InvalidStrandIdError, isValidStrandScopeKey } from './storage-scope.js';
 import { generateStrandMemberKey, strandMemberKeyPair } from './strand-member-key.js';
 import { assertNotPreSplitStrand, issueInvite, PreSplitStrandIdentityError } from './strand-membership-writer.js';
 import { MEMBERSHIP_INVITE_TTL_MS } from './strand-formation-manager.js';
@@ -394,8 +394,10 @@ export class CadreNode {
          * dead entry behind; recovery today is a fresh invitation.
          *
          * NOTE: entries are kept for the node's lifetime, including across a
-         * {@link stopStrand} — a stopped strand may be rediscovered by the watcher and must
-         * still get its seed. Each strand's list is capped at `MAX_STRAND_ADDRS`, but the
+         * {@link stopStrand} — a stopped strand may be claimed again with {@link addStrand}
+         * (the watcher itself will not re-offer it: the stop suppresses the id for the rest of
+         * the session) and must still get its seed. Each strand's list is capped at
+         * `MAX_STRAND_ADDRS`, but the
          * number of KEYS is bounded only by the strands this node has ever formed as an
          * initiator (not by time); if a node ever forms strands at scale, evict on
          * `unpublishStrand` or cap the map.
@@ -1184,6 +1186,12 @@ export class CadreNode {
      * derivation from it (`db-p2p` namespaces all of the node's protocol ids as
      * `/optimystic/<networkName>/...`), so the node options and the block-transfer
      * protocol prefix the control backfill dials can never drift apart.
+     *
+     * NOTE: the party id goes in UNENCODED here, unlike in `controlStorageScope`. Safe
+     * today because a party id is locally configured rather than replicated in, and both
+     * ends of a connection derive this string identically — an odd party id yields an odd
+     * but consistent protocol id, not a mismatch or an escaped name. If a party id ever
+     * arrives from the network, encode it here as the storage scope key already does.
      */
     controlNetworkName() {
         return `control-${this.config.controlNetwork.partyId}`;
@@ -1293,6 +1301,11 @@ export class CadreNode {
         // party's records, so two parties on one device must not land in one store.
         // Same key as the cache label, which also makes the shared pool's `stats()` readable.
         const scope = controlStorageScope(this.config.controlNetwork.partyId);
+        // The second seam that hands a scope key to an embedder's provider; the first
+        // (`StrandInstanceManager.startStrand`) asserts the stricter strand rule. Holds by
+        // construction today — base64url is inside the charset — so this guards a future
+        // edit to `controlStorageScope`, not a reachable input.
+        assertScopeKeyCharset(scope);
         const resolved = typeof provider === 'function' ? provider(scope) : provider;
         this.controlStorage = wrapStorageWithCache(resolved, scope);
         return this.controlStorage;
@@ -1388,6 +1401,11 @@ export class CadreNode {
             ...(identityKey && { privateKey: identityKey }),
             ...(network?.transports && { transports: network.transports }),
             ...(network?.noiseCrypto && { noiseCrypto: network.noiseCrypto }),
+            // Always present, unlike the conditional spreads around it: an absent
+            // `connectionMonitor` would leave libp2p's 5s ping deadline, which drops a peer
+            // whose event loop is saturated by pure-JS Noise crypto. A configured value
+            // replaces the default whole (see DEFAULT_CONNECTION_MONITOR).
+            connectionMonitor: network?.connectionMonitor ?? DEFAULT_CONNECTION_MONITOR,
             // `{ wsPort }` when a listen entry names WebSocket, otherwise `{}` — and always
             // `{}` when `network.transports` is set, since the embedder owns transport policy
             // then. Spread NEXT to `transports` because the two answer the same question.
@@ -3670,6 +3688,23 @@ export class CadreNode {
     }
     async handleStrandAdded(strand) {
         log('Handling strand added from control network: %s', strand.Id);
+        // A replicated row carries whatever id the founding node wrote, and the id becomes a
+        // storage scope key and a libp2p protocol prefix. Checked FIRST — above the
+        // discovery branch below — so a malformed id is never offered to the hosting app as
+        // a strand it could join; that app's `addStrand` could only fail on it.
+        //
+        // Suppressed rather than retried: the id is a property of the row, so every later
+        // attempt fails identically, and without this the watcher's ladder would re-emit
+        // `strand:error` every five minutes for the life of the process. The throw still
+        // matters — the watcher's catch runs `forgetStrand`, dropping the id from
+        // `knownStrands`, so its removed-strand loop never detaches a strand that never ran.
+        if (!isValidStrandScopeKey(strand.Id)) {
+            const error = new InvalidStrandIdError(strand.Id);
+            log('Refusing strand %s: %s', strand.Id, error.message);
+            this.emit('strand:error', { strandId: strand.Id, error });
+            this.strandWatcher?.suppressStrand(strand.Id);
+            throw error;
+        }
         // Check if we have sApp config for this strand
         const sAppConfig = this.sAppConfigs.get(strand.Id);
         if (!sAppConfig) {
@@ -3681,10 +3716,12 @@ export class CadreNode {
             // already present) keeps auto-starting below, unchanged.
             //
             // Recorded BEFORE the emit so a handler that synchronously drains
-            // `getDiscoveredStrands()` sees this strand too. The watcher never offers
-            // the same strand twice (its `knownStrands` retains the id for the life of
-            // the process), so this map — not the event — is what a late subscriber
-            // reads. See the `strand:discovered` doc in types.ts.
+            // `getDiscoveredStrands()` sees this strand too. The watcher does not offer the
+            // same strand twice — its `knownStrands` retains the id, and the one thing that
+            // un-retains it (a failed `addStrand`, via `StrandWatcher.forgetStrand`) leaves the
+            // sApp config registered, so the retry takes the auto-launch branch below rather
+            // than this one. So this map — not the event — is what a late subscriber reads.
+            // See the `strand:discovered` doc in types.ts.
             this.discoveredStrands.set(strand.Id, strand);
             this.emit('strand:discovered', { strandId: strand.Id, strand });
             return;
@@ -4084,23 +4121,26 @@ export class CadreNode {
      *
      * A rejected call leaves nothing running but DOES leave the sApp config
      * registered, deliberately: both an explicit retry and the {@link StrandWatcher}'s
-     * automatic relaunch need it. That background relaunch covers only a strand the
-     * WATCHER launched: it forgets a row whose `onStrandAdded` threw and re-attempts it
-     * on a later poll (each failure re-emitting `strand:error`) until it succeeds. A
-     * strand claimed here after it was DISCOVERED gets no such retry — the watcher
-     * already recorded it in its `knownStrands` when it offered it as
-     * `strand:discovered`, and no later poll re-offers a strand it knows. This call has
-     * also already dropped it from {@link getDiscoveredStrands}, so a failed claim
-     * leaves the strand dormant until the caller retries or the node restarts (see
-     * `backlog/bug-discovered-strand-lost-when-claim-fails`).
-     * {@link detachStrand} (reached via {@link stopStrand}) is what abandons a strand
-     * for good.
+     * automatic relaunch need it. A failed launch here hands the strand back to that
+     * relaunch — `StrandWatcher.forgetStrand` drops the id from the watcher's
+     * `knownStrands` and records the backoff, so a later poll re-attempts it on the same
+     * `pollInterval * 2^(failures-1)` ladder a watcher-driven failure gets. Because the
+     * config stays registered, the retry takes `handleStrandAdded`'s auto-launch branch:
+     * what the app sees is `strand:error` per failed retry and `strand:started` when one
+     * succeeds, never a second `strand:discovered`. {@link detachStrand} (reached via
+     * {@link stopStrand}) is what abandons a strand for good, and its stop suppresses the
+     * strand in the watcher so this retry cannot resurrect it — a call to THIS method lifts
+     * that suppression again, since an explicit claim is a deliberate reversal of the
+     * deliberate stop.
      */
     async addStrand(config) {
         if (!this._running) {
             throw new Error('CadreNode not running');
         }
         const { strandRow, sAppConfig, founder, partyMemberPrivateKey } = config;
+        // Before anything is recorded: an unusable id must not leave a registered sApp
+        // config behind, and must not lift a suppression this node set deliberately.
+        assertStrandScopeKey(strandRow.Id);
         if (partyMemberPrivateKey !== undefined && strandRow.Type !== 'c') {
             // Only a closed strand seats a Member/Manager, so an open launch would drop this
             // key silently. Refuse instead: the caller has confused the party identity key
@@ -4113,13 +4153,41 @@ export class CadreNode {
         // unclaimed backlog — a later `getDiscoveredStrands()` drain must not re-offer it.
         this.sAppConfigs.set(strandRow.Id, sAppConfig);
         this.discoveredStrands.delete(strandRow.Id);
+        // A claim also overrides any earlier `stopStrand` of this id: the watcher must track
+        // the strand again, or a party-wide removal would never stop it here.
+        this.strandWatcher?.unsuppressStrand(strandRow.Id);
         log('Registered sAppConfig for strand %s (sApp: %s, founder: %s)', strandRow.Id, sAppConfig.id, founder ?? 'derived');
         // An unset `founder` is DERIVED from the row inside launchStrand (this node founds
         // iff the row's FounderOwnerKey is its own owner key); an explicit flag wins — the
         // formation/responder flows pass one deliberately, since their consent-seated rows
         // carry a null column. See StrandConfig.founder. Same rule for the explicit
         // partyMemberPrivateKey: it wins over the StrandPartyKey control-row read.
-        const instance = await this.launchStrand(strandRow, sAppConfig, founder, partyMemberPrivateKey);
+        // Only the launch is wrapped, NOT the first-sync wait below: a wait that times out
+        // rejects with the retryable StrandAwaitingFirstSyncError and deliberately leaves the
+        // instance running, so there is nothing to re-offer and forgetting it would only have
+        // the watcher re-enter a launch for a strand that is already up.
+        let instance;
+        try {
+            instance = await this.launchStrand(strandRow, sAppConfig, founder, partyMemberPrivateKey);
+        }
+        catch (error) {
+            // Hand the strand back to the watcher's retry ladder. Harmless on the founder path
+            // (`foundStrand` → `publishStrand` + this call), where the watcher may never have
+            // offered the strand: the `knownStrands` delete is a no-op and the recorded backoff
+            // only delays the watcher's own first attempt by one poll interval, which is what
+            // should happen right after an attempt that just failed.
+            //
+            // NOTE: the retry relaunches from the CONTROL row plus the registered config, not
+            // from the row and arguments passed here — so a caller that enriched either (a
+            // synthetic `MemberPrivateKey`, an explicit `founder` or `partyMemberPrivateKey`)
+            // is retried with less than it asked for. Inert today: founder-ness re-derives from
+            // `FounderOwnerKey`, the party key re-reads from `StrandPartyKey`, and the row's
+            // shared `MemberPrivateKey` is read only by the founder bootstrap. If a joiner
+            // launch ever starts depending on that key, gate this hand-back on the passed row
+            // matching the control one.
+            this.strandWatcher?.forgetStrand(strandRow.Id);
+            throw error;
+        }
         // The first-sync write gate: a JOINING machine's database is withheld until it has
         // received the strand's Header from another member, because a write before that
         // forks every table it touches (see strand-first-sync-gate.ts). Waiting here is what
@@ -4208,7 +4276,8 @@ export class CadreNode {
      * @returns The live `Strand` row — the one just inserted, or the matching one already
      *   there. A closed strand's caller should carry THIS row's `MemberPrivateKey` forward:
      *   on a repeat it is the stored key, not the argument.
-     * @throws if the node is not started, exposes no owner signing key, the id is blank, a
+     * @throws if the node is not started, exposes no owner signing key, the id is blank or
+     *   unusable as a storage scope key (`InvalidStrandIdError` — see `storage-scope.ts`), a
      *   row with the same id holds different content, or the control DB rejects the
      *   (unauthorized) insert.
      */
@@ -4217,6 +4286,11 @@ export class CadreNode {
         // Trim/reject here so the id that lands matches the one unpublishStrand looks up: it
         // trims too, and an untrimmed row would be unreachable by the same string.
         const trimmed = requireNonBlank(strandId, 'strand id');
+        // Refuse an unusable id HERE, not only at launch. `addStrand` already asserts, but it
+        // runs after this row is written, and this row replicates: an id no node can turn into
+        // a storage scope key would otherwise reach the whole party's control database and be
+        // declined once per member. Asserted after the trim so the id checked is the id stored.
+        assertStrandScopeKey(trimmed);
         // FounderOwnerKey records THIS machine as the row's publisher (the schema pins it to
         // the signing owner), which is what later lets a relaunch derive founder-ness.
         const desired = {
@@ -4457,13 +4531,20 @@ export class CadreNode {
         // one never cleared).
         await this.strandManager.clearOwnMemberPeerBinding(trimmed);
         // Converge locally now rather than waiting up to a poll interval. The watcher fires
-        // onStrandRemoved for a strand it tracked; the explicit stop below covers a node whose
-        // strandFilter never admitted this strand (the watcher never knew it, so it will never
-        // fire). StrandInstanceManager.stopStrand no-ops on an unknown id, so the two paths
-        // cannot double-stop into an error.
+        // onStrandRemoved for a strand it tracked; the explicit teardown below covers a node
+        // whose strandFilter never admitted this strand (the watcher never knew it, so it will
+        // never fire). StrandInstanceManager.stopStrand no-ops on an unknown id, so the two
+        // paths cannot double-stop into an error.
+        //
+        // detachStrand, NOT stopStrand: this is a party-wide removal, not a local abandonment
+        // of a strand that still exists, so it must not SUPPRESS the id in the watcher. The
+        // row is already gone — there is nothing to suppress — and an id re-published before
+        // the next poll's suppression cleanup would then never be offered again this session.
+        // (Same reasoning as handleStrandRemoved, which also avoids stopStrand's `_running`
+        // guard; here the guard is already satisfied by requireOwnerSigningKey above.)
         await this.strandWatcher?.forcePoll();
         if (this.strandManager.getInstance(trimmed)) {
-            await this.stopStrand(trimmed);
+            await this.detachStrand(trimmed);
         }
         log('Unpublished strand %s from control DB under owner %s', trimmed, signingKey.publicKeyB64);
     }
@@ -5313,16 +5394,20 @@ export class CadreNode {
      * Stop a strand on THIS node only: untrack it from hibernation, drop its sApp config,
      * stop the local instance, and emit `strand:stopped`. The shared `Strand` row is left
      * intact, so on the next node RESTART the strand is rediscovered and surfaces as
-     * `strand:discovered` again — not on the next watcher poll, which never re-offers a
-     * strand it has already seen (`StrandWatcher.knownStrands` retains the id for the life
-     * of the process). The stop also drops the strand from {@link getDiscoveredStrands},
-     * so a drain cannot undo a deliberate stop. Party-wide removal is
-     * {@link unpublishStrand}.
+     * `strand:discovered` again — but never again in THIS session: the stop suppresses the
+     * id in the watcher (`StrandWatcher.suppressStrand`) and drops it from
+     * {@link getDiscoveredStrands}, so neither a later poll nor a drain can undo a
+     * deliberate stop. Only an explicit {@link addStrand} does, which is the caller
+     * reversing its own decision. Party-wide removal is {@link unpublishStrand}.
      */
     async stopStrand(strandId) {
         if (!this._running) {
             throw new Error('CadreNode not running');
         }
+        // Suppressed HERE and not in detachStrand: the other caller of that method is
+        // `handleStrandRemoved`, which arrives precisely because the control row is gone, and
+        // a row that later reappears is a fresh strand that should be offered again.
+        this.strandWatcher?.suppressStrand(strandId);
         await this.detachStrand(strandId);
     }
     /**
@@ -5343,6 +5428,10 @@ export class CadreNode {
      * readings are the intended one: `handleStrandRemoved` arrives because the control row
      * is gone, and an explicit {@link stopStrand} is a deliberate abandonment — neither
      * strand may be re-offered to a later `getDiscoveredStrands()` drain.
+     *
+     * The watcher-level suppression that makes a stop permanent is deliberately NOT here,
+     * only in {@link stopStrand}: the two callers diverge on it. A vanished control row
+     * that reappears is a fresh strand and must be offered again.
      */
     async detachStrand(strandId) {
         this.hibernationManager.untrackStrand(strandId);