@serfab/cadre-core 0.7.1 → 0.8.1

package/dist/strand-formation-protocol.js

@@ -0,0 +1,279 @@
+/**
+ * Native cadre-core strand-formation transport.
+ *
+ * Mirrors the non-deprecated `seed-bootstrap.ts` protocol service: a dedicated
+ * libp2p protocol id, length-prefixed JSON frames, and small single-purpose
+ * session helpers. It replaces the deprecated `@serfab/strand-proto` transport,
+ * carrying the caller's REAL invitation token + disclosure and BOTH parties'
+ * real cadre peer addresses end-to-end (no `{ partyId: sessionId }` / `cadre-*.local`
+ * placeholders), and validating the responder's result on the initiator side.
+ *
+ * Provisioning flow (`responderCreates`, 2 messages): the responder provisions (or, for
+ * provision-then-record, resolves + records consent against) the strand and returns the
+ * result on approval.
+ *
+ * Cadre-disclosure timing (see docs/strand-proto.md "Security & Privacy"): the
+ * responder reveals its own party id + cadre addresses — and, for a closed strand
+ * returned via provision-then-record, that strand's membership key — ONLY after the
+ * token and disclosure validate; a rejection discloses none of them.
+ */
+import debug from 'debug';
+import { multiaddr } from '@multiformats/multiaddr';
+import { writeFrame, withTimeout } from './control-stream.js';
+const log = debug('sereus:cadre:formation-proto');
+/** Protocol id for the native formation transport (parallel to `/sereus/seed/1.0.0`). */
+export const FORMATION_PROTOCOL = '/sereus/formation/1.0.0';
+/** Maximum formation message size (1MB). */
+const MAX_FORMATION_MSG_SIZE = 1024 * 1024;
+/** Default whole-session timeout (ms). */
+const DEFAULT_SESSION_TIMEOUT_MS = 30000;
+/** Default per-step (single read/write) timeout (ms). */
+const DEFAULT_STEP_TIMEOUT_MS = 5000;
+/** Default cap on concurrent inbound formation sessions. */
+const DEFAULT_MAX_CONCURRENT_SESSIONS = 100;
+// ── Stream framing helpers ───────────────────────────────────────────────────
+/**
+ * Reads length-prefixed JSON frames from a libp2p stream one frame at a time.
+ *
+ * Unlike seed delivery (which reads a stream to EOF then parses once), formation
+ * is request/response on a single live stream, so reading must stop at each frame
+ * boundary. The reader buffers across chunk boundaries and retains any overflow
+ * (a following frame coalesced into the same chunk) for the next read.
+ */
+class FrameReader {
+    constructor(stream, maxLength = MAX_FORMATION_MSG_SIZE) {
+        this.buffer = new Uint8Array(0);
+        this.iterator = stream[Symbol.asyncIterator]();
+        this.maxLength = maxLength;
+    }
+    append(chunk) {
+        const next = new Uint8Array(this.buffer.length + chunk.length);
+        next.set(this.buffer, 0);
+        next.set(chunk, this.buffer.length);
+        this.buffer = next;
+    }
+    /** Pull chunks until the buffer holds ≥ `need` bytes; false if the stream ended first. */
+    async fill(need) {
+        while (this.buffer.length < need) {
+            const { value, done } = await this.iterator.next();
+            if (done)
+                return false;
+            const bytes = value instanceof Uint8Array
+                ? value
+                : value.subarray();
+            this.append(bytes);
+        }
+        return true;
+    }
+    async read() {
+        if (!(await this.fill(4))) {
+            throw new Error('Formation stream closed before length prefix');
+        }
+        const length = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength).getUint32(0, false);
+        if (length > this.maxLength) {
+            throw new Error(`Formation frame declares length ${length} exceeding max ${this.maxLength}`);
+        }
+        if (!(await this.fill(4 + length))) {
+            throw new Error(`Formation frame declares length ${length} but stream ended early`);
+        }
+        const json = new TextDecoder().decode(this.buffer.subarray(4, 4 + length));
+        this.buffer = this.buffer.subarray(4 + length);
+        return JSON.parse(json);
+    }
+}
+// ── Result validation ────────────────────────────────────────────────────────
+/** Matches the deprecated strand-proto placeholder cadre addrs (`cadre-a-1.local`, …). */
+const PLACEHOLDER_CADRE_ADDR = /^cadre-[ab]-\d+\.local$/;
+/**
+ * Structural check on a `responderCreates` result: the responder must have approved,
+ * disclosed a non-empty real identity + cadre (not the deprecated `cadre-*.local`
+ * placeholders), and returned a strand vouched for by the responder party with a real id.
+ *
+ * `createdBy: 'responder'` means "the responder party vouches for / returns this strand."
+ * Under provision-then-record that strand was minted authority-signed earlier (not created
+ * in-session), but it is still the responder party returning its own strand, so the marker
+ * — and this structural validator — stay unchanged.
+ *
+ * The behavioral floor for the initiator: a responder that returns an arbitrary/empty
+ * `strandId` or omits its disclosed identity is rejected, not silently accepted.
+ */
+export function isValidResponderCreatesResult(response) {
+    if (!response.approved)
+        return false;
+    if (!response.partyId)
+        return false;
+    const addrs = response.cadrePeerAddrs;
+    if (!addrs || addrs.length === 0)
+        return false;
+    if (addrs.some((a) => PLACEHOLDER_CADRE_ADDR.test(a)))
+        return false;
+    const provision = response.provisionResult;
+    if (!provision?.strand?.strandId)
+        return false;
+    if (provision.strand.createdBy !== 'responder')
+        return false;
+    return true;
+}
+/**
+ * Responder side of the native formation protocol. Registers a libp2p handler and
+ * drives each inbound stream through token + disclosure validation, provisioning,
+ * and result delivery — enforcing the cadre-disclosure timing rule (responder cadre
+ * is revealed only after validation; rejections disclose nothing).
+ */
+export class FormationListener {
+    constructor(options) {
+        this.registered = new Set();
+        this.activeSessions = 0;
+        this.sessionCounter = 0;
+        this.options = options;
+        this.sessionTimeoutMs = options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+        this.stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+        this.maxConcurrentSessions = options.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS;
+    }
+    /** Number of in-flight inbound sessions. */
+    get activeCount() {
+        return this.activeSessions;
+    }
+    register(node, protocolId = FORMATION_PROTOCOL) {
+        if (this.registered.has(node)) {
+            log('node already registered');
+            return;
+        }
+        void node.handle(protocolId, async (rawStream, _connection) => {
+            await this.handleStream(rawStream);
+        });
+        this.registered.add(node);
+        log('formation listener registered (%s)', protocolId);
+    }
+    unregister(node, protocolId = FORMATION_PROTOCOL) {
+        if (!this.registered.has(node))
+            return;
+        void node.unhandle(protocolId);
+        this.registered.delete(node);
+        log('formation listener unregistered (%s)', protocolId);
+    }
+    async handleStream(stream) {
+        if (this.activeSessions >= this.maxConcurrentSessions) {
+            const rejection = { approved: false, reason: 'Too many concurrent formation sessions' };
+            try {
+                writeFrame(stream, rejection);
+            }
+            catch { /* best effort */ }
+            try {
+                await stream.close();
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        const id = ++this.sessionCounter;
+        this.activeSessions++;
+        try {
+            await withTimeout(this.sessionTimeoutMs, `Formation session#${id}`, () => this.runSession(id, stream));
+        }
+        catch (err) {
+            log('formation session #%d failed: %o', id, err);
+        }
+        finally {
+            this.activeSessions--;
+            try {
+                await stream.close();
+            }
+            catch { /* ignore */ }
+        }
+    }
+    async runSession(id, stream) {
+        // Track whether ANY frame has been written so the catch below can convert an
+        // unexpected internal error into a non-disclosing rejection ONLY when nothing has
+        // gone out yet. This closes the "stream closed with no result frame" class of bug.
+        let wroteFrame = false;
+        const send = (msg) => {
+            writeFrame(stream, msg);
+            wroteFrame = true;
+        };
+        try {
+            const reader = new FrameReader(stream);
+            const contact = await withTimeout(this.stepTimeoutMs, `Formation await-contact#${id}`, () => reader.read());
+            log('formation session #%d contact: token=%s party=%s', id, contact.token, contact.partyId);
+            const tokenResult = await this.options.validateToken(contact.token);
+            if (!tokenResult.valid) {
+                send({ approved: false, reason: 'Invalid token' });
+                return;
+            }
+            const disclosureOk = await this.options.validateDisclosure(contact.token, contact.disclosure);
+            if (!disclosureOk) {
+                send({ approved: false, reason: 'Invalid disclosure' });
+                return;
+            }
+            const outcome = await this.options.provisionStrand(contact.token, contact.partyId, contact.disclosure);
+            if (!outcome.approved) {
+                // A post-validation rejection still discloses NEITHER identity NOR cadre,
+                // exactly like the token/disclosure rejections above.
+                send({ approved: false, reason: outcome.reason });
+                return;
+            }
+            // Validation + provisioning passed → safe to disclose responder identity/cadre.
+            const identity = this.options.getResponderIdentity();
+            send({
+                approved: true,
+                partyId: identity.partyId,
+                cadrePeerAddrs: identity.cadrePeerAddrs,
+                provisionResult: outcome.result
+            });
+        }
+        catch (err) {
+            // Defense-in-depth: if an unexpected internal error escapes BEFORE any frame was
+            // written (e.g. a future provisionStrand-hook bug), convert it into a non-disclosing
+            // protocol rejection so the initiator sees a clean error instead of a read-error/
+            // timeout. If a frame was already sent, leave the stream as-is and let handleStream
+            // log + close. Re-throw either way so the failure is still recorded — this is a
+            // deliberate, logged conversion, not silent.
+            if (!wroteFrame) {
+                const internalError = { approved: false, reason: 'Internal formation error' };
+                try {
+                    writeFrame(stream, internalError);
+                }
+                catch { /* stream already broken */ }
+            }
+            throw err;
+        }
+    }
+}
+/**
+ * Initiator side of the native formation protocol. Dials the responder, sends the
+ * contact (carrying the real disclosure/token/cadre), validates the responder's
+ * result, and returns the strand the responder provisioned.
+ */
+export async function dialFormation(node, options) {
+    if (options.responderAddrs.length === 0) {
+        throw new Error('No responder addresses available for formation');
+    }
+    const protocolId = options.protocolId ?? FORMATION_PROTOCOL;
+    const sessionTimeoutMs = options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+    const addr = multiaddr(options.responderAddrs[0]);
+    return withTimeout(sessionTimeoutMs, 'Formation dial', async () => {
+        const rawStream = await withTimeout(stepTimeoutMs, 'Formation dial-connect', async () => node.dialProtocol(addr, protocolId));
+        const stream = rawStream;
+        try {
+            const reader = new FrameReader(stream);
+            writeFrame(stream, options.contact);
+            const response = await withTimeout(stepTimeoutMs, 'Formation await-response', () => reader.read());
+            if (!response.approved) {
+                throw new Error(`Formation rejected: ${response.reason ?? 'no reason provided'}`);
+            }
+            const ok = await options.validateResponse(response);
+            if (!ok)
+                throw new Error('Responder result failed validation');
+            if (!response.provisionResult)
+                throw new Error('Missing provision result for responderCreates mode');
+            return response.provisionResult;
+        }
+        finally {
+            try {
+                await stream.close();
+            }
+            catch { /* ignore */ }
+        }
+    });
+}
+//# sourceMappingURL=strand-formation-protocol.js.map

package/dist/strand-formation-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strand-formation-protocol.js","sourceRoot":"","sources":["../src/strand-formation-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGpD,OAAO,EAAsB,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElF,MAAM,GAAG,GAAG,KAAK,CAAC,8BAA8B,CAAC,CAAC;AAElD,yFAAyF;AACzF,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAE5D,4CAA4C;AAC5C,MAAM,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C,0CAA0C;AAC1C,MAAM,0BAA0B,GAAG,KAAM,CAAC;AAC1C,yDAAyD;AACzD,MAAM,uBAAuB,GAAG,IAAK,CAAC;AACtC,4DAA4D;AAC5D,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAqE5C,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,WAAW;IAKf,YAAY,MAAiC,EAAE,SAAS,GAAG,sBAAsB;QAFzE,WAAM,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;QAGjC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAEO,MAAM,CAAC,KAAiB;QAC9B,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,0FAA0F;IAClF,KAAK,CAAC,IAAI,CAAC,IAAY;QAC7B,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;YACjC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnD,IAAI,IAAI;gBAAE,OAAO,KAAK,CAAC;YACvB,MAAM,KAAK,GAAG,KAAK,YAAY,UAAU;gBACvC,CAAC,CAAC,KAAK;gBACP,CAAC,CAAE,KAAoC,CAAC,QAAQ,EAAE,CAAC;YACrD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAClE,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACpH,IAAI,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,mCAAmC,MAAM,kBAAkB,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;QAC/F,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,mCAAmC,MAAM,yBAAyB,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;CACF;AAED,gFAAgF;AAEhF,0FAA0F;AAC1F,MAAM,sBAAsB,GAAG,yBAAyB,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,6BAA6B,CAAC,QAAgC;IAC5E,IAAI,CAAC,QAAQ,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,CAAC,QAAQ,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,KAAK,GAAG,QAAQ,CAAC,cAAc,CAAC;IACtC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACpE,MAAM,SAAS,GAAG,QAAQ,CAAC,eAAe,CAAC;IAC3C,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC/C,IAAI,SAAS,CAAC,MAAM,CAAC,SAAS,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC;AA0BD;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAS5B,YAAY,OAAiC;QAJ5B,eAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACxC,mBAAc,GAAG,CAAC,CAAC;QACnB,mBAAc,GAAG,CAAC,CAAC;QAGzB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;QAC/E,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,uBAAuB,CAAC;QACtE,IAAI,CAAC,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,IAAI,+BAA+B,CAAC;IAChG,CAAC;IAED,4CAA4C;IAC5C,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED,QAAQ,CAAC,IAAY,EAAE,aAAqB,kBAAkB;QAC5D,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,GAAG,CAAC,yBAAyB,CAAC,CAAC;YAC/B,OAAO;QACT,CAAC;QACD,KAAK,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,SAAkB,EAAE,WAAoB,EAAE,EAAE;YAC9E,MAAM,IAAI,CAAC,YAAY,CAAC,SAA0B,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1B,GAAG,CAAC,oCAAoC,EAAE,UAAU,CAAC,CAAC;IACxD,CAAC;IAED,UAAU,CAAC,IAAY,EAAE,aAAqB,kBAAkB;QAC9D,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO;QACvC,KAAK,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAC/B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7B,GAAG,CAAC,sCAAsC,EAAE,UAAU,CAAC,CAAC;IAC1D,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,MAAqB;QAC9C,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,qBAAqB,EAAE,CAAC;YACtD,MAAM,SAAS,GAA2B,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;YAChH,IAAI,CAAC;gBAAC,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;YAClE,IAAI,CAAC;gBAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;YACpD,OAAO;QACT,CAAC;QACD,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC;QACjC,IAAI,CAAC,cAAc,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,IAAI,CAAC,gBAAgB,EAAE,qBAAqB,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;QACzG,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,kCAAkC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QACnD,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,cAAc,EAAE,CAAC;YACtB,IAAI,CAAC;gBAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,EAAU,EAAE,MAAqB;QACxD,6EAA6E;QAC7E,kFAAkF;QAClF,mFAAmF;QACnF,IAAI,UAAU,GAAG,KAAK,CAAC;QACvB,MAAM,IAAI,GAAG,CAAC,GAA2B,EAAQ,EAAE;YACjD,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YACxB,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;YACvC,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,aAAa,EAAE,2BAA2B,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAA2B,CAAC,CAAC;YACrI,GAAG,CAAC,kDAAkD,EAAE,EAAE,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;YAE5F,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACpE,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;gBACvB,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;gBACnD,OAAO;YACT,CAAC;YAED,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YAC9F,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC,CAAC;gBACxD,OAAO;YACT,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YACvG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACtB,0EAA0E;gBAC1E,sDAAsD;gBACtD,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;gBAClD,OAAO;YACT,CAAC;YACD,gFAAgF;YAChF,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC;YACrD,IAAI,CAAC;gBACH,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,cAAc,EAAE,QAAQ,CAAC,cAAc;gBACvC,eAAe,EAAE,OAAO,CAAC,MAAM;aAChC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,iFAAiF;YACjF,qFAAqF;YACrF,kFAAkF;YAClF,oFAAoF;YACpF,gFAAgF;YAChF,6CAA6C;YAC7C,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,MAAM,aAAa,GAA2B,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;gBACtG,IAAI,CAAC;oBAAC,UAAU,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,2BAA2B,CAAC,CAAC;YAClF,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;CACF;AAgBD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY,EAAE,OAA6B;IAC7E,IAAI,OAAO,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,CAAC;IAC5D,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,0BAA0B,CAAC;IAChF,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,uBAAuB,CAAC;IACvE,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAElD,OAAO,WAAW,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,KAAK,IAAI,EAAE;QAChE,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,aAAa,EAAE,wBAAwB,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;QAC9H,MAAM,MAAM,GAAG,SAAqC,CAAC;QACrD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;YACvC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;YAEpC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,aAAa,EAAE,0BAA0B,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAA0B,CAAC,CAAC;YAC3H,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,IAAI,oBAAoB,EAAE,CAAC,CAAC;YACpF,CAAC;YACD,MAAM,EAAE,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YACpD,IAAI,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;YAE/D,IAAI,CAAC,QAAQ,CAAC,eAAe;gBAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;YACrG,OAAO,QAAQ,CAAC,eAAe,CAAC;QAClC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC;gBAAC,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;QACtD,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/strand-instance-manager.d.ts

@@ -12,18 +12,46 @@ export interface StartStrandConfig {
     profile: NodeProfile;
     defaultLatencyHint: LatencyHint;
     privateKey?: PrivateKey;
+    /** Cohort-derived discovery seed (multiaddr strings). Defaults to [] when omitted. */
+    bootstrapNodes?: string[];
     /**
      * Lifecycle mode for this strand; selects the default transactor used by the
-     * StrandDatabase. Defaults to `'networked'` when omitted.
+     * StrandDatabase. When omitted, the StrandDatabase falls back to `'networked'`;
+     * callers (CadreNode) infer it from cohort membership before reaching here.
      */
     mode?: StrandMode;
+    /**
+     * Require a valid author signature on the sApp schema before bring-up.
+     * Defaults to true (fail closed) when omitted; set false only for dev/test
+     * with unsigned demo schemas. Mirrors {@link CadreNodeConfig.requireSignedSchemas}.
+     */
+    requireSignedSchemas?: boolean;
+    /**
+     * Whether this node founds the strand (vs. joins it). Forwarded to the
+     * StrandDatabase so the founder bootstrap (Header, founding Member/Authority)
+     * runs once at bring-up. Joiners leave this unset and write nothing. See
+     * {@link StrandConfig.founder}.
+     */
+    founder?: boolean;
+}
+/**
+ * Volatile inputs re-resolved when resuming a quiesced strand. These may have
+ * changed since the strand first launched — the cohort discovery seed grows as
+ * peers are learned, and cohort membership can push a strand `bootstrap → networked`.
+ */
+export interface ResumeStrandOverrides {
+    /** Freshly-resolved cohort discovery seed (multiaddr strings). */
+    bootstrapNodes?: string[];
+    /** Freshly-resolved lifecycle mode. */
+    mode?: StrandMode;
 }
 /**
  * Get the isolated storage path for a specific strand.
  *
- * @deprecated This function uses Node.js path module which is not available in React Native.
- * Use a storage provider factory function instead, which receives the strandId and can
- * create strand-specific storage paths using platform-appropriate methods.
+ * @deprecated This helper is Node-only and throws in React Native (it assumes a
+ * filesystem layout). Use a storage provider factory function instead, which
+ * receives the strandId and can create strand-specific storage paths using
+ * platform-appropriate methods.
  *
  * @example
  * // Instead of using getStrandStoragePath, use a storage provider factory:
@@ -38,6 +66,12 @@ export declare function getStrandStoragePath(basePath: string, strandId: string)
  */
 export declare class StrandInstanceManager {
     private instances;
+    /**
+     * Retained launch config per strand, captured in `startStrand` and cleared in
+     * `stopStrand`. `resumeStrand` reuses it to rebuild a quiesced strand's runtime
+     * without the caller re-threading storage/network/profile/key/sApp config.
+     */
+    private launchConfigs;
     private stopping;
     constructor();
     /**
@@ -56,6 +90,41 @@ export declare class StrandInstanceManager {
      * Start a new strand instance
      */
     startStrand(config: StartStrandConfig): Promise<StrandInstance>;
+    /**
+     * Build (or rebuild) the libp2p node + StrandDatabase for an instance and
+     * attach them, transitioning it to `active`. Shared by `startStrand` (fresh
+     * launch) and `resumeStrand` (rehydrating a quiesced instance). Reads all
+     * volatile inputs (bootstrapNodes, mode, storage, network, profile,
+     * privateKey, sApp config) from `config`, so the caller controls the
+     * cohort-derived values.
+     */
+    private buildStrandRuntime;
+    /**
+     * Release an instance's strand-network runtime: close the StrandDatabase, then
+     * stop the libp2p node (construction order in reverse), clearing both fields
+     * and zeroing connectedPeers. Tolerant of partially-built state — either handle
+     * may be absent — so it doubles as rollback for a failed `buildStrandRuntime`.
+     * Shared by `quiesceStrand`, `stopStrand`, and that rollback path.
+     */
+    private releaseRuntime;
+    /**
+     * Quiesce a strand: release its strand-network resources (stop the libp2p node,
+     * close the StrandDatabase) while RETAINING the instance record — identity,
+     * sAppInfo, keys, latency hint, metadata — and its launch config so it can be
+     * resumed later. Mechanically this is `stopStrand` minus the instance/config
+     * deletion. The caller sets the post-quiesce status (e.g. `hibernating`).
+     * No-ops when the strand is missing or already quiesced.
+     */
+    quiesceStrand(strandId: string): Promise<void>;
+    /**
+     * Resume a previously-quiesced strand: rebuild its libp2p node + StrandDatabase
+     * from the retained launch config and re-attach them, transitioning it back to
+     * `active`. `overrides` re-applies volatile inputs that may have changed since
+     * launch (cohort `bootstrapNodes`, lifecycle `mode`) and updates the retained
+     * config so a later resume reuses the latest values. Returns the live instance
+     * unchanged if it is already running.
+     */
+    resumeStrand(strandId: string, overrides?: ResumeStrandOverrides): Promise<StrandInstance>;
     /**
      * Stop a strand instance
      */