@serfab/cadre-core 0.7.1 → 0.8.1

package/dist/strand-formation-manager.js

@@ -1,34 +1,39 @@
 import debug from 'debug';
-import { createBootstrapManager, DEFAULT_PROTOCOL_ID } from '@serfab/strand-proto';
+import { FormationListener, dialFormation, isValidResponderCreatesResult } from './strand-formation-protocol.js';
 const log = debug('sereus:cadre:formation-manager');
 /**
- * StrandFormationManager bridges cadre-core's strand solicitation interfaces
- * with strand-proto's SessionManager for actual protocol handling over libp2p.
+ * StrandFormationManager drives the native cadre-core formation transport
+ * (`strand-formation-protocol.ts`) from cadre-core's strand-solicitation interfaces.
  *
- * It implements SessionHooks by delegating to the existing interfaces:
- * - DisclosureValidator -> validateIdentity
- * - FormationUsageRecorder -> validateToken
- * - StrandProvisioner -> provisionStrand
+ * Responder side: a {@link FormationListener} wires the inbound protocol to
+ * {@link FormationUsageRecorder} (token), {@link DisclosureValidator} (identity),
+ * and {@link StrandProvisioner} (provisioning), disclosing this party's real
+ * identity + cadre only after validation.
+ *
+ * Initiator side: {@link formStrand} dials the responder carrying the real
+ * disclosure/token/cadre, then validates the responder's result via the
+ * {@link FormationResponseValidator} (or a built-in structural check).
  */
 export class StrandFormationManager {
     constructor(options) {
         this.registeredNodes = new Set();
+        this.dialerSessions = 0;
         this.disclosureValidator = options.disclosureValidator;
         this.formationUsageRecorder = options.formationUsageRecorder;
         this.strandProvisioner = options.strandProvisioner;
+        this.formationResponseValidator = options.formationResponseValidator;
         this.partyId = options.partyId;
         this.cadrePeerAddrs = options.cadrePeerAddrs ?? [];
-        // Create SessionHooks that delegate to our interfaces
-        const hooks = this.createSessionHooks();
-        // Create the underlying SessionManager
-        const config = {
-            sessionTimeoutMs: options.config?.sessionTimeoutMs ?? 30000,
-            stepTimeoutMs: options.config?.stepTimeoutMs ?? 5000,
-            maxConcurrentSessions: options.config?.maxConcurrentSessions ?? 100,
-            enableDebugLogging: options.config?.enableDebugLogging ?? false,
-            protocolId: options.config?.protocolId ?? DEFAULT_PROTOCOL_ID
-        };
-        this.sessionManager = createBootstrapManager(hooks, config);
+        this.config = options.config ?? {};
+        this.listener = new FormationListener({
+            validateToken: (token) => this.validateToken(token),
+            validateDisclosure: (token, disclosure) => this.validateDisclosure(token, disclosure),
+            provisionStrand: (token, initiatorPartyId, disclosure) => this.provisionAsResponder(token, initiatorPartyId, disclosure),
+            getResponderIdentity: () => ({ partyId: this.partyId, cadrePeerAddrs: this.cadrePeerAddrs }),
+            sessionTimeoutMs: this.config.sessionTimeoutMs,
+            stepTimeoutMs: this.config.stepTimeoutMs,
+            maxConcurrentSessions: this.config.maxConcurrentSessions
+        });
         log('StrandFormationManager created for party: %s', this.partyId);
     }
     /**
@@ -40,7 +45,7 @@ export class StrandFormationManager {
             log('Node already registered');
             return;
         }
-        this.sessionManager.register(node, protocolId);
+        this.listener.register(node, protocolId ?? this.config.protocolId);
         this.registeredNodes.add(node);
         log('Registered as responder on node');
     }
@@ -51,112 +56,199 @@ export class StrandFormationManager {
         if (!this.registeredNodes.has(node)) {
             return;
         }
-        this.sessionManager.unregister(node, protocolId);
+        this.listener.unregister(node, protocolId ?? this.config.protocolId);
         this.registeredNodes.delete(node);
         log('Unregistered from node');
     }
     /**
-     * Form a strand with a responder via an open invitation.
+     * Form a strand with a responder via an open invitation (initiator side).
      *
-     * This is the initiator-side operation. It:
-     * 1. Converts the OpenInvitation to a BootstrapLink
-     * 2. Calls SessionManager.initiateBootstrap()
-     * 3. Returns the result as a FormStrandResult
+     * Builds a contact message carrying the real token + disclosure + this party's
+     * real cadre addresses, dials the responder over the native protocol, and
+     * validates the responder's result before returning.
      */
     async formStrand(invitation, disclosure, node) {
         log('Forming strand with invitation token: %s', invitation.token);
-        // Convert OpenInvitation to BootstrapLink
-        const link = {
-            responderPeerAddrs: invitation.bootstrap,
+        const contact = {
             token: invitation.token,
-            tokenExpiryUtc: invitation.expiration.toISOString(),
-            mode: 'responderCreates' // Responder provisions the strand
-        };
-        // The disclosure is passed via the identityBundle in the contact message
-        // We store it temporarily so the hooks can access it
-        // Note: strand-proto's DialerSession constructs the contact message internally
-        // We need to extend this to pass the disclosure - for now we use partyId
-        const result = await this.sessionManager.initiateBootstrap(link, node);
-        log('Strand formed: %s', result.strand.strandId);
-        return {
-            memberKey: this.partyId, // The initiator's member key
-            invitePrivateKey: '', // Would come from key generation
-            strandId: result.strand.strandId
+            partyId: disclosure.partyId ?? this.partyId,
+            disclosure,
+            cadrePeerAddrs: this.cadrePeerAddrs
         };
+        this.dialerSessions++;
+        try {
+            const provision = await dialFormation(node, {
+                contact,
+                responderAddrs: invitation.bootstrap,
+                validateResponse: (response) => this.validateResponse(invitation, disclosure, response),
+                sessionTimeoutMs: this.config.sessionTimeoutMs,
+                stepTimeoutMs: this.config.stepTimeoutMs,
+                protocolId: this.config.protocolId
+            });
+            log('Strand formed: %s', provision.strand.strandId);
+            return {
+                memberKey: contact.partyId,
+                invitePrivateKey: '',
+                strandId: provision.strand.strandId,
+                // The host strand's membership key, delivered through the protocol (provision-then-record).
+                // Undefined for an open strand. Kept separate from invitePrivateKey (the initiator's
+                // generated signing key), which is set by the StrandSolicitationService layer.
+                memberPrivateKey: provision.memberPrivateKey
+            };
+        }
+        finally {
+            this.dialerSessions--;
+        }
     }
     /**
      * Get the number of active sessions
      */
     getActiveSessionCounts() {
-        return this.sessionManager.getActiveSessionCounts();
+        return { listeners: this.listener.activeCount, dialers: this.dialerSessions };
+    }
+    // ── Responder-side hooks ─────────────────────────────────────────────────────
+    async validateToken(token) {
+        if (!this.formationUsageRecorder) {
+            // No recorder configured — accept all tokens.
+            return { valid: true };
+        }
+        const tokenCheck = await this.formationUsageRecorder.isTokenValid(token);
+        if (!tokenCheck.valid) {
+            log('Token invalid: %s', token);
+            return { valid: false };
+        }
+        if (await this.formationUsageRecorder.isTokenUsed(token)) {
+            log('Token already used: %s', token);
+            return { valid: false };
+        }
+        return { valid: true };
+    }
+    async validateDisclosure(token, disclosure) {
+        if (!this.disclosureValidator) {
+            // No validator configured — accept all disclosures.
+            return true;
+        }
+        return this.disclosureValidator.validateDisclosure(token, disclosure);
     }
     /**
-     * Create SessionHooks that delegate to our interfaces
+     * Responder-side provisioning. Routes on how the invite resolves
+     * ({@link ResolvedHostStrand}), and can REJECT post-validation by returning a
+     * {@link ResponderProvisionOutcome} with `approved: false` — `runSession` turns that
+     * into a clean, non-disclosing reply instead of a dropped result frame.
+     *
+     * - **bound** (host strand present): provision-then-record — write the single
+     *   `FormationUsage` consent row against the pre-existing strand (record-only) and
+     *   return it + its membership key (a read-gating secret disclosed only here, behind the
+     *   token + disclosure validation `runSession` already enforced).
+     * - **missing** (invite names a host strand absent on this responder, e.g. unconverged):
+     *   reject cleanly + retryably, writing NO usage row — recording usage here would fail the
+     *   deferred `StrandExists` CHECK at commit and drop the frame.
+     * - **unbound** (no binding): the responder-provisions fallback — see {@link provisionUnbound}.
+     *
+     * Defense-in-depth: known provisioning/redeem failures (notably the concurrent
+     * `(Token, UseNumber)` PK collision when two redemptions of one unbound single-use invite
+     * race) are caught and mapped to a logged, retry-suggesting rejection rather than a thrown
+     * insert + a silently-closed stream. The LOG-before-reject keeps this a deliberate
+     * internal-error→protocol-rejection conversion (AGENTS.md: don't eat exceptions silently),
+     * not control-flow-by-exception.
      */
-    createSessionHooks() {
-        return {
-            validateToken: async (token, sessionId) => {
-                log('validateToken: %s (session: %s)', token, sessionId);
-                if (!this.formationUsageRecorder) {
-                    // No recorder configured - accept all tokens
-                    return { mode: 'responderCreates', valid: true };
-                }
-                const tokenCheck = await this.formationUsageRecorder.isTokenValid(token);
-                if (!tokenCheck.valid) {
-                    log('Token invalid: %s', token);
-                    return { mode: 'responderCreates', valid: false };
-                }
-                const isUsed = await this.formationUsageRecorder.isTokenUsed(token);
-                if (isUsed) {
-                    log('Token already used: %s', token);
-                    return { mode: 'responderCreates', valid: false };
-                }
-                return { mode: 'responderCreates', valid: true };
-            },
-            validateIdentity: async (identity, sessionId) => {
-                log('validateIdentity (session: %s)', sessionId);
-                if (!this.disclosureValidator) {
-                    // No validator configured - accept all identities
-                    return true;
-                }
-                // Extract disclosure from identity bundle
-                const disclosure = identity;
-                // We need the token here - it's passed via the contact message
-                // For now, use a placeholder - this will be refined
-                const token = identity?.token ?? '';
-                return this.disclosureValidator.validateDisclosure(token, disclosure);
-            },
-            provisionStrand: async (creator, creatorPartyId, otherPartyId, sessionId) => {
-                log('provisionStrand: creator=%s, other=%s (session: %s)', creatorPartyId, otherPartyId, sessionId);
-                if (!this.strandProvisioner) {
-                    // No provisioner - return a placeholder
-                    const strandId = `strand-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-                    return {
-                        strand: { strandId, createdBy: creator },
+    async provisionAsResponder(token, initiatorPartyId, _disclosure) {
+        const recorder = this.formationUsageRecorder;
+        const resolved = recorder?.resolveStrand
+            ? await recorder.resolveStrand(token)
+            : { kind: 'unbound' };
+        try {
+            switch (resolved.kind) {
+                case 'bound': {
+                    // recorder is guaranteed non-null here: only resolveStrand can yield 'bound'.
+                    await recorder.recordUsage(token, initiatorPartyId, resolved.strandId);
+                    return this.approve({
+                        strand: { strandId: resolved.strandId, createdBy: 'responder' },
+                        memberPrivateKey: resolved.memberPrivateKey ?? undefined,
                         dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
-                    };
+                    });
                 }
-                // Determine initiator/responder keys based on creator
-                const initiatorKey = creator === 'initiator' ? creatorPartyId : otherPartyId;
-                const responderKey = creator === 'responder' ? creatorPartyId : otherPartyId;
-                const result = await this.strandProvisioner.provisionStrand('', // sAppId - would come from invitation
-                initiatorKey, responderKey);
-                return {
-                    strand: { strandId: result.strandId, createdBy: creator },
-                    dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
-                };
-            },
-            validateResponse: async (response, sessionId) => {
-                log('validateResponse (session: %s)', sessionId);
-                // Accept all responses for now
-                return true;
-            },
-            validateDatabaseResult: async (result, sessionId) => {
-                log('validateDatabaseResult (session: %s)', sessionId);
-                // Accept all database results for now
-                return true;
+                case 'missing': {
+                    log('Host strand %s not yet available on this responder; rejecting token %s', resolved.strandId, token);
+                    return { approved: false, reason: 'Host strand not yet available on this responder' };
+                }
+                case 'unbound':
+                    return await this.provisionUnbound(token, initiatorPartyId);
             }
-        };
+        }
+        catch (err) {
+            log('provisionAsResponder failed for token %s: %o', token, err);
+            return { approved: false, reason: 'Formation conflict, retry' };
+        }
+    }
+    /**
+     * Responder-provisions fallback (invite binds no host strand). Precedence:
+     *
+     * 1. `recorder.provisionAndRecord` present (a real DB recorder) → atomic create-strand +
+     *    record-consent, so the unbound redemption is single-use just like the bound path.
+     *    Returns the new strand (+ key, null for an open responder-provisioned strand).
+     * 2. else `strandProvisioner` present → the legacy/mock contract: provision a bare strand,
+     *    NO inline usage write (those callers record usage explicitly via
+     *    `recordFormationComplete`, or assert transport invariants only). Threads the invite's
+     *    REAL `sAppId`.
+     * 3. else → a structural placeholder (no recorder + no provisioner ⇒ no single-use semantics
+     *    exist to enforce).
+     *
+     * Plan tradeoff — option (a) "record usage on the fallback" over (b) "remove the fallback":
+     * (a) closes the single-use hole with a targeted atomic create+record and leaves the
+     * `StrandProvisioner` mock-transport tests untouched; (b) would delete the provisioner
+     * surface and churn ~6 unit + ~6 integration sites for ZERO production benefit (production
+     * — `cadre-web.ts` / `cadre-phone.ts` — always publishes strand-BOUND invites and treats
+     * the responder-provisions placeholder as failure). The broader "should this fallback exist
+     * at all?" question lives in backlog `formation-initiatorcreates-cover-or-remove`.
+     */
+    async provisionUnbound(token, initiatorPartyId) {
+        const recorder = this.formationUsageRecorder;
+        if (recorder?.provisionAndRecord) {
+            const sAppId = await this.resolveInviteSAppId(token);
+            const provisioned = await recorder.provisionAndRecord(token, initiatorPartyId, sAppId);
+            return this.approve({
+                strand: { strandId: provisioned.strandId, createdBy: 'responder' },
+                memberPrivateKey: provisioned.memberPrivateKey ?? undefined,
+                dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
+            });
+        }
+        if (this.strandProvisioner) {
+            const sAppId = await this.resolveInviteSAppId(token);
+            const result = await this.strandProvisioner.provisionStrand(sAppId, initiatorPartyId, this.partyId);
+            return this.approve({
+                strand: { strandId: result.strandId, createdBy: 'responder' },
+                dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
+            });
+        }
+        // No recorder + no provisioner — a structural placeholder the initiator can still validate.
+        const strandId = `strand-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        return this.approve({
+            strand: { strandId, createdBy: 'responder' },
+            dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
+        });
+    }
+    /** Wrap a provision result as an approving {@link ResponderProvisionOutcome}. */
+    approve(result) {
+        return { approved: true, result };
+    }
+    /**
+     * The invite's authoritative `sAppId` for the responder-provisions fallback, read back
+     * from the recorder's `isTokenValid` invitation (the real `FormationInvite.sAppId`).
+     * Empty string when no recorder is wired or the invitation omits it.
+     */
+    async resolveInviteSAppId(token) {
+        if (!this.formationUsageRecorder)
+            return '';
+        const check = await this.formationUsageRecorder.isTokenValid(token);
+        return check.invitation?.sAppId ?? '';
+    }
+    // ── Initiator-side result validation ─────────────────────────────────────────
+    async validateResponse(invitation, disclosure, response) {
+        if (this.formationResponseValidator) {
+            return this.formationResponseValidator.validateResponse({ invitation, disclosure, response });
+        }
+        return isValidResponderCreatesResult(response);
     }
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"strand-formation-manager.js","sourceRoot":"","sources":["../src/strand-formation-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"strand-formation-manager.js","sourceRoot":"","sources":["../src/strand-formation-manager.ts"],"names":[],"mappings":"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"}

package/dist/strand-formation-protocol.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 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 type { Libp2p } from '@libp2p/interface';
+import type { StrandFormationDisclosure } from './types.js';
+/** Protocol id for the native formation transport (parallel to `/sereus/seed/1.0.0`). */
+export declare const FORMATION_PROTOCOL = "/sereus/formation/1.0.0";
+export type FormationParty = 'initiator' | 'responder';
+export interface FormationStrandInfo {
+    strandId: string;
+    createdBy: FormationParty;
+}
+export interface FormationDbConnectionInfo {
+    endpoint: string;
+    credentialsRef: string;
+}
+export interface FormationProvisionResult {
+    strand: FormationStrandInfo;
+    /**
+     * The strand's membership key (closed-strand read-gating secret), delivered to a
+     * validated invitee for provision-then-record formation. Disclosed only AFTER token
+     * + disclosure validation, exactly like the responder identity/cadre — a rejected or
+     * already-used token discloses neither identity nor key. Absent for open strands.
+     */
+    memberPrivateKey?: string;
+    dbConnectionInfo: FormationDbConnectionInfo;
+}
+/**
+ * Outcome of the responder's provisioning hook.
+ *
+ * Distinct from a bare {@link FormationProvisionResult} so the hook can REJECT a
+ * formation AFTER token + disclosure validation — e.g. a bound invite naming a host
+ * strand this responder has not yet converged on, or a concurrent-redemption collision.
+ * Without this channel such cases threw inside provisioning, the stream closed with no
+ * result frame, and the initiator saw a read-error/timeout instead of a clean
+ * `approved: false`. A rejection still discloses NO responder identity/cadre.
+ */
+export type ResponderProvisionOutcome = {
+    approved: true;
+    result: FormationProvisionResult;
+} | {
+    approved: false;
+    reason: string;
+};
+/** Initiator → Responder: carries the real token + disclosure + initiator cadre. */
+export interface FormationContactMessage {
+    /** The real invitation token. */
+    token: string;
+    /** Initiator's member key (peer id). */
+    partyId: string;
+    /** The real disclosure, carried verbatim. */
+    disclosure: StrandFormationDisclosure;
+    /** Initiator's real multiaddrs. */
+    cadrePeerAddrs: string[];
+}
+/** Responder → Initiator: responder identity/cadre disclosed only after validation. */
+export interface FormationResultMessage {
+    approved: boolean;
+    /** Present iff `approved === false`. */
+    reason?: string;
+    /** Responder's real party id (disclosed only after validation). */
+    partyId?: string;
+    /** Responder's real multiaddrs (omitted on rejection). */
+    cadrePeerAddrs?: string[];
+    /** The provisioned strand/db result (always present on approval). */
+    provisionResult?: FormationProvisionResult;
+}
+/**
+ * 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 declare function isValidResponderCreatesResult(response: FormationResultMessage): boolean;
+export interface FormationListenerOptions {
+    /** Validate the invitation token; returns whether it is valid. */
+    validateToken(token: string): Promise<{
+        valid: boolean;
+    }>;
+    /** Validate the initiator's disclosure with the REAL token + disclosure. */
+    validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean>;
+    /**
+     * Provision (or, for provision-then-record, resolve + record consent against) the
+     * strand (`responderCreates`) for the given initiator. The REAL token is threaded
+     * in so the hook can map it to the bound host strand and its membership key.
+     *
+     * Returns a {@link ResponderProvisionOutcome}: the hook may REJECT post-validation
+     * (e.g. an unconverged host strand) and the listener turns that into a clean,
+     * non-disclosing `approved: false` reply rather than dropping the result frame.
+     */
+    provisionStrand(token: string, initiatorPartyId: string, disclosure: StrandFormationDisclosure): Promise<ResponderProvisionOutcome>;
+    /** Responder identity, disclosed only AFTER token + disclosure validation passes. */
+    getResponderIdentity(): {
+        partyId: string;
+        cadrePeerAddrs: string[];
+    };
+    sessionTimeoutMs?: number;
+    stepTimeoutMs?: number;
+    maxConcurrentSessions?: number;
+}
+/**
+ * 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 declare class FormationListener {
+    private readonly options;
+    private readonly sessionTimeoutMs;
+    private readonly stepTimeoutMs;
+    private readonly maxConcurrentSessions;
+    private readonly registered;
+    private activeSessions;
+    private sessionCounter;
+    constructor(options: FormationListenerOptions);
+    /** Number of in-flight inbound sessions. */
+    get activeCount(): number;
+    register(node: Libp2p, protocolId?: string): void;
+    unregister(node: Libp2p, protocolId?: string): void;
+    private handleStream;
+    private runSession;
+}
+export interface FormationDialOptions {
+    /** The contact message to send (real token, partyId, disclosure, initiator cadre). */
+    contact: FormationContactMessage;
+    /** Responder multiaddrs to dial. */
+    responderAddrs: string[];
+    /** Validate the responder's result; a false return aborts the formation. */
+    validateResponse(response: FormationResultMessage): Promise<boolean>;
+    sessionTimeoutMs?: number;
+    stepTimeoutMs?: number;
+    protocolId?: string;
+}
+/**
+ * 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 declare function dialFormation(node: Libp2p, options: FormationDialOptions): Promise<FormationProvisionResult>;