@ibgib/core-gib 0.1.55 → 0.1.58

package/dist/sync/sync-peer/sync-peer-websocket-sender/sync-peer-websocket-sender-v1.mjs

@@ -0,0 +1,282 @@
+/**
+ * @module sync-peer-websocket-sender-v1
+ */
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { KeystoneService_V1 } from '../../../keystone/keystone-service-v1.mjs';
+import { KeystoneStrategyFactory } from '../../../keystone/strategy/keystone-strategy-factory.mjs';
+import { deriveSessionSecret } from '../../sync-helpers.mjs';
+import { SyncPeer_V1 } from '../sync-peer-v1.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../../core-constants.mjs';
+import { SESSION_KEYSTONE_POLICY, getConnectChallenge } from '../sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs';
+const logalot = GLOBAL_LOG_A_LOT || true;
+/**
+ * WebSocket Sender Peer implementation running in browser/native environment.
+ */
+export class SyncPeerWebSocketSender_V1 extends SyncPeer_V1 {
+    lc = `[${SyncPeerWebSocketSender_V1.name}]`;
+    get classname() {
+        return SyncPeerWebSocketSender_V1.name;
+    }
+    get isSocketOpen() {
+        return this.ws !== undefined && this.ws.readyState === WebSocket.OPEN;
+    }
+    ws;
+    activeResolve;
+    activeReject;
+    constructor(initialData, initialRel8ns) {
+        super(initialData, initialRel8ns);
+    }
+    async preConnectCheck(opts) {
+        const lc = `${this.lc}[${this.preConnectCheck.name}]`;
+        if (!this.data?.wsUrl) {
+            throw new Error(`Missing wsUrl in peer data (E: a3b2c1d0e9f8e7d6c5b4a3f2e1d0c910)`);
+        }
+        if (!this.data?.httpEvolveUrl) {
+            throw new Error(`Missing httpEvolveUrl in peer data (E: a3b2c1d0e9f8e7d6c5b4a3f2e1d0c911)`);
+        }
+    }
+    /**
+     * Submits the evolved master identity (I1) and new session keystone (S) to the server's HTTP registry.
+     */
+    async postEstablishToReceiver({ newSenderIdentity, sessionIdentity, }) {
+        const lc = `${this.lc}[${this.postEstablishToReceiver.name}]`;
+        try {
+            if (logalot) {
+                console.log(`${lc} posting evolved keystones to ${this.data.httpEvolveUrl}...`);
+            }
+            if (!this.data) {
+                throw new Error(`(UNEXPECTED) this.data falsy? (E: d642e8a9af18b532c87c6f581aa53b26)`);
+            }
+            if (!this.data.httpEvolveUrl) {
+                throw new Error(`(UNEXPECTED) this.data.httpEvolveUrl falsy? (E: 8589ddbb155914d85c09658881da2c26)`);
+            }
+            const response = await fetch(this.data.httpEvolveUrl, {
+                method: 'PUT',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    keystoneIbGib: newSenderIdentity,
+                    relatedIbGibs: [sessionIdentity]
+                }),
+            });
+            if (!response.ok) {
+                const data = await response.json().catch(() => ({}));
+                const errorMsg = data.message || data.error || 'Unknown error';
+                throw new Error(`HTTP ${response.status} evolution post rejected. errorMsg: ${errorMsg} (E: e8a478291b88d05c68cf6b385684b826)`);
+            }
+            if (logalot) {
+                console.log(`${lc} evolve post accepted by server.`);
+            }
+        }
+        catch (error) {
+            console.error(`${lc} establish post failed: ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+    /**
+     * Establishes the stateful WebSocket connection and performs the multi-turn cryptographic challenge connect.
+     */
+    async connectImpl(opts) {
+        const lc = `${this.lc}[${this.connectImpl.name}]`;
+        try {
+            if (logalot) {
+                console.log(`${lc} starting...`);
+            }
+            const { senderIdentity, fnSenderSecret, sagaId, localMetaspace, localSpace } = this.opts;
+            if (!senderIdentity || !fnSenderSecret || !sagaId) {
+                throw new Error(`Missing identity parameters in peer options (E: ed49b6711ac82efcdb42b8a28c5b6826)`);
+            }
+            // 1. Solve upfront pre-filter solution
+            const senderSecret = await fnSenderSecret();
+            const sessionSecret = await deriveSessionSecret({ senderSecret, sagaId });
+            // Fetch session identity S that establishSessionIdentity just created
+            const sAddr_tjp = getIbGibAddr({ ibGib: senderIdentity }); // wait, S's past contains I
+            // Actually, we can get the S keystone that was returned by establishSessionIdentity.
+            // Let's resolve S from the sender localSpace using its target claim or the targetAddrs
+            const sAddr = getIbGibAddr({ ibGib: senderIdentity.rel8ns?.past ? senderIdentity : senderIdentity }); // stub: get the actual generated S
+            // To make sure we have the exact session identity S, we can query localSpace.
+            // Since we know the sagaId, we can walk or locate it.
+            // But wait, the coordinator calls establishSessionIdentity first, which returns the created S keystone!
+            // Let's store a reference to the sessionIdentity S on this class during establish, or lookup from localSpace.
+            // Wait, does the coordinator let the peer store S? No, but let's query the latest keystone in localSpace.
+            const senderIdentityLatestAddr = await localMetaspace.getLatestAddr({ ibGib: senderIdentity, space: localSpace });
+            if (!senderIdentityLatestAddr) {
+                throw new Error(`senderIdentityLatestAddr falsy. we should have a latest addr that is different than the sender identity at this point (done in the peer establish phase) (E: 225607318bef485d7821f82de97b6826)`);
+            }
+            const resGet = await localMetaspace.get({ addrs: [senderIdentityLatestAddr], space: localSpace });
+            const I_tip = resGet.ibGibs?.[0];
+            // const targetSAddr = I_tip?.rel8ns?.past?.[0] ?? I_tip?.data?.proofs?.[0]?.claim?.target;
+            const targetSAddr = I_tip.data.proofs.at(0)?.claim.target;
+            if (!targetSAddr) {
+                throw new Error(`Could not locate session keystone target from identity (E: 5ec4882f7e5e4c33fbd00ab8b3166726)`);
+            }
+            const resGetS = await localMetaspace.get({ addrs: [targetSAddr], space: localSpace });
+            const sessionS = resGetS.ibGibs?.[0];
+            if (!sessionS) {
+                throw new Error(`Session keystone not found in local space: ${targetSAddr} (E: 9ba818e6622808bb4ae749be31f80b26)`);
+            }
+            // Solve dynamic upfront picket-fence challenge
+            const connectPool = (sessionS.data?.challengePools ?? [])
+                .find(p => p.id === SESSION_KEYSTONE_POLICY.CONNECT_POOL.ID);
+            if (!connectPool) {
+                throw new Error(`Session keystone missing connect pool (E: f50968afca04b6d38ec19824ea201826)`);
+            }
+            const { challengeId } = getConnectChallenge(sessionS);
+            const strategy = KeystoneStrategyFactory.create({ config: connectPool.config });
+            const poolSecret = await strategy.derivePoolSecret({ masterSecret: sessionSecret });
+            const solution = await strategy.generateSolution({
+                poolSecret,
+                poolId: SESSION_KEYSTONE_POLICY.CONNECT_POOL.ID,
+                challengeId
+            });
+            // 2. Open WebSocket connection
+            const wsUrl = `${this.data.wsUrl}?sAddr=${encodeURIComponent(targetSAddr)}&solution=${encodeURIComponent(solution.value)}`;
+            if (logalot) {
+                console.log(`${lc} connecting to WebSocket: ${wsUrl}`);
+            }
+            const ws = new WebSocket(wsUrl);
+            this.ws = ws;
+            return new Promise((resolve, reject) => {
+                let isResolved = false;
+                ws.addEventListener('open', () => {
+                    if (logalot) {
+                        console.log(`${lc} WebSocket opened. Awaiting challenge...`);
+                    }
+                });
+                ws.addEventListener('message', async (ev) => {
+                    try {
+                        const msg = JSON.parse(ev.data);
+                        if (logalot) {
+                            console.log(`${lc} received frame: ${msg.type}`);
+                        }
+                        if (msg.type === 'auth-challenge-init') {
+                            ws.send(JSON.stringify({
+                                type: 'auth-init',
+                                sAddr: targetSAddr
+                            }));
+                        }
+                        else if (msg.type === 'auth-challenge') {
+                            const { challengeUuid, demandedIds } = msg;
+                            if (logalot) {
+                                console.log(`${lc} solving demanded challenges: ${demandedIds.join(', ')}`);
+                            }
+                            const keystoneService = new KeystoneService_V1();
+                            const proofFrame = await keystoneService.sign({
+                                latestKeystone: sessionS,
+                                masterSecret: sessionSecret,
+                                poolId: SESSION_KEYSTONE_POLICY.CONNECT_POOL.ID,
+                                requiredChallengeIds: demandedIds,
+                                claim: {
+                                    verb: SESSION_KEYSTONE_POLICY.CONNECT_POOL.VERB,
+                                    target: challengeUuid
+                                },
+                                metaspace: localMetaspace,
+                                space: localSpace
+                            });
+                            ws.send(JSON.stringify({
+                                type: 'auth-proof',
+                                proofFrame
+                            }));
+                        }
+                        else if (msg.type === 'auth-ok') {
+                            if (logalot) {
+                                console.log(`${lc} WebSocket connect SUCCESS!`);
+                            }
+                            isResolved = true;
+                            // Setup persistent runtime listeners
+                            ws.removeEventListener('message', (() => { }));
+                            ws.addEventListener('message', (event) => this.handleRuntimeMessage(event));
+                            resolve();
+                        }
+                        else if (msg.type === 'auth-fail') {
+                            reject(new Error(`Connect failed: ${msg.message}`));
+                        }
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                });
+                ws.addEventListener('close', (event) => {
+                    if (!isResolved) {
+                        reject(new Error(`WebSocket closed before connect completed (code: ${event.code})`));
+                    }
+                });
+                ws.addEventListener('error', (err) => {
+                    if (!isResolved) {
+                        reject(new Error(`WebSocket connection error`));
+                    }
+                });
+            });
+        }
+        catch (error) {
+            console.error(`${lc} connect failed: ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+    /**
+     * Handles synchronizing messages and evolved context frames during active transaction turns.
+     */
+    handleRuntimeMessage(event) {
+        const lc = `${this.lc}[${this.handleRuntimeMessage.name}]`;
+        try {
+            const msg = JSON.parse(event.data);
+            if (logalot) {
+                console.log(`${lc} received runtime frame: ${msg.type}`);
+            }
+            if (msg.type === 'sync-frame-response') {
+                if (this.activeResolve) {
+                    const responseContext = msg.context;
+                    const resolve = this.activeResolve;
+                    this.activeResolve = undefined;
+                    this.activeReject = undefined;
+                    resolve(responseContext);
+                }
+            }
+            else if (msg.type === 'domain-payload') {
+                const payload = msg.ibGib;
+                this.payloadIbGibsDomainReceived$.next(payload);
+            }
+        }
+        catch (error) {
+            console.error(`${lc} failed parsing runtime frame: ${extractErrorMsg(error)}`);
+            if (this.activeReject) {
+                this.activeReject(error);
+            }
+        }
+    }
+    /**
+     * Serializes the transaction context and payload down the active WebSocket connection.
+     */
+    async sendContextRequest(context) {
+        const lc = `${this.lc}[${this.sendContextRequest.name}]`;
+        try {
+            if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+                throw new Error(`WebSocket is not connected or open (E: a3b2c1d0e9f8e7d6c5b4a3f2e1d0c915)`);
+            }
+            // 1. Push any outgoing payload domain ibgibs down the pipe
+            const domainPayloads = context.payloadIbGibsDomain ?? [];
+            for (const ibGib of domainPayloads) {
+                this.ws.send(JSON.stringify({
+                    type: 'domain-payload',
+                    ibGib
+                }));
+            }
+            // 2. Transmit the synchronizing transaction context
+            return new Promise((resolve, reject) => {
+                this.activeResolve = resolve;
+                this.activeReject = reject;
+                this.ws.send(JSON.stringify({
+                    type: 'sync-frame',
+                    context
+                }));
+            });
+        }
+        catch (error) {
+            console.error(`${lc} sendContextRequest failed: ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=sync-peer-websocket-sender-v1.mjs.map

package/dist/sync/sync-peer/sync-peer-websocket-sender/sync-peer-websocket-sender-v1.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-peer-websocket-sender-v1.mjs","sourceRoot":"","sources":["../../../../src/sync/sync-peer/sync-peer-websocket-sender/sync-peer-websocket-sender-v1.mts"],"names":[],"mappings":"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"}

package/dist/sync/sync-saga-coordinator.d.mts

@@ -5,6 +5,8 @@ import { SyncConflictStrategy } from "./sync-constants.mjs";
 import { SyncSagaInfo } from "./sync-types.mjs";
 import { SyncPeerWitness } from "./sync-peer/sync-peer-types.mjs";
 import { SyncSagaContextIbGib_V1 } from "./sync-saga-context/sync-saga-context-types.mjs";
+import { KeystoneIbGib_V1 } from "../keystone/keystone-types.mjs";
+import { KeystonePoolConfig } from "../keystone/keystone-types.mjs";
 /**
  * Orchestrates the synchronization process between two spaces (Source and Destination).
  *
@@ -21,6 +23,22 @@ import { SyncSagaContextIbGib_V1 } from "./sync-saga-context/sync-saga-context-t
 export declare class SyncSagaCoordinator {
     private lc;
     constructor();
+    /**
+     * Default pool config for the session keystone's `connect` pool.
+     * Consumed exactly once per saga during `peer.connect()`.
+     * Uses `deleteAll` replenish strategy — after the handshake, the pool is gone.
+     *
+     * Override in subclasses or pass custom config via opts to change security parameters.
+     */
+    protected defaultSessionConnectPoolConfig(): KeystonePoolConfig;
+    /**
+     * Default pool config for the session keystone's per-turn `sync` pool.
+     * Used on each outgoing context frame (Init, Delta, Commit).
+     * Uses `topUp` replenish strategy to stay active throughout the saga.
+     *
+     * Override in subclasses or pass custom config via opts to change security parameters.
+     */
+    protected defaultSessionSyncPoolConfig(): KeystonePoolConfig;
     /**
      * Executes a synchronization saga using the Symmetric Sync Protocol.
      *
@@ -28,7 +46,7 @@ export declare class SyncSagaCoordinator {
      * **Execution Context**: **Sender (Local)**.
      * This method is the entry point for starting a sync saga.
      */
-    sync({ peer, domainIbGibs, conflictStrategy, metaspace, localSpace, }: {
+    sync({ peer, domainIbGibs, senderIdentity, fnSenderSecret, conflictStrategy, metaspace, localSpace, }: {
         /**
          * The peer we are syncing with.
          */
@@ -40,6 +58,22 @@ export declare class SyncSagaCoordinator {
          * These should all exist in {@link localSpace}
          */
         domainIbGibs: IbGib_V1[];
+        /**
+         * If present, this is the primary identity of the sender, i.e., who is
+         * initiating the sync.
+         *
+         * This should be the most recent frame (tip) of the senderIdentity's
+         * timeline.
+         *
+         * NOTE: {@link fnSenderSecret} must be truthy if this is truthy, and vice versa.
+         */
+        senderIdentity?: KeystoneIbGib_V1;
+        /**
+         * secret corresponding to {@link senderIdentity}.
+         *
+         * NOTE: {@link senderIdentity} must be truthy if this is truthy, and vice versa.
+         */
+        fnSenderSecret?: () => Promise<string>;
         /**
          * The space containing the {@link domainIbGibs} we want to sync. If
          * sync is successful, any updates to timelines will be stored here.

package/dist/sync/sync-saga-coordinator.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-saga-coordinator.d.mts","sourceRoot":"","sources":["../../src/sync/sync-saga-coordinator.mts"],"names":[],"mappings":"AAaA,OAAO,EAAE,QAAQ,EAAG,MAAM,iCAAiC,CAAC;AAI5D,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAClF,OAAO,EAEH,oBAAoB,EAEvB,MAAM,sBAAsB,CAAC;AAqB9B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAA0B,uBAAuB,EAA6B,MAAM,iDAAiD,CAAC;AAoB7I;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;IAC5B,OAAO,CAAC,EAAE,CAA2C;;IAMrD;;;;;;OAMG;IACU,IAAI,CAAC,EACd,IAAI,EACJ,YAAY,EACZ,gBAA6C,EAC7C,SAAS,EACT,UAAU,GACb,EAAE;QACC;;WAEG;QACH,IAAI,EAAE,eAAe,CAAC;QACtB;;;;;WAKG;QACH,YAAY,EAAE,QAAQ,EAAE,CAAC;QACzB;;;WAGG;QACH,UAAU,EAAE,aAAa,CAAC;QAC1B;;WAEG;QACH,SAAS,EAAE,gBAAgB,CAAC;QAC5B;;;;;WAKG;QACH,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;KAC3C,GAAG,OAAO,CAAC,YAAY,CAAC;IAkFzB;;;;;;;;;;OAUG;IACU,YAAY,CAAC,EACtB,WAAW,EACX,OAAO,EACP,WAAW,EACX,SAAS,GACZ,EAAE;QACC,WAAW,EAAE,uBAAuB,CAAC;QACrC;;WAEG;QACH,OAAO,EAAE,aAAa,CAAC;QACvB;;WAEG;QACH,WAAW,EAAE,aAAa,CAAC;QAC3B,SAAS,EAAE,gBAAgB,CAAC;KAC/B,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC;IAwD3C;;;;;;;;;;;;;;OAcG;YACW,eAAe;IA6M7B;;;;;;;;;;OAUG;YACW,qBAAqB;IA2FnC;;;OAGG;IACU,eAAe,CAAC,EACzB,KAAK,EACL,SAAS,EACT,YAAY,EACZ,QAAQ,GACX,EAAE;QACC,KAAK,EAAE,aAAa,CAAC;QACrB,SAAS,EAAE,gBAAgB,CAAC;QAC5B,YAAY,CAAC,EAAE,QAAQ,EAAE,CAAC;QAC1B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,GAAG,OAAO,CAAC;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;YAoD/B,mBAAmB;IAqCjC;;;;;;;;OAQG;YACW,eAAe;IAyE7B;;;;;OAKG;YACW,qBAAqB;IAgEnC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;YACW,yBAAyB;IA6FvC;;;;;;;;;;;OAWG;YACW,eAAe;IAuV7B;;;;;;;;;;;;;;OAcG;YACW,cAAc;IAmR5B;;;;;;;;;;;;OAYG;YACW,gBAAgB;IAuW9B;;OAEG;YACW,kBAAkB;YAgQlB,iBAAiB;YAqDjB,iBAAiB;YAmFjB,kBAAkB;YAmClB,4BAA4B;IAiE1C;;OAEG;YACW,mBAAmB;YA8GnB,2BAA2B;IAoCzC,OAAO,CAAC,0BAA0B;CA+DrC"}
+{"version":3,"file":"sync-saga-coordinator.d.mts","sourceRoot":"","sources":["../../src/sync/sync-saga-coordinator.mts"],"names":[],"mappings":"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"}

package/dist/sync/sync-saga-coordinator.mjs

@@ -21,6 +21,9 @@ import { graftTimelines, } from "./graft-info/graft-info-helpers.mjs";
 import { GRAFT_INFO_REL8N_NAME } from "./graft-info/graft-info-constants.mjs";
 import { validateIbGibIntrinsically } from "@ibgib/ts-gib/dist/V1/validate-helper.mjs";
 import { SYNC_SAGA_CONTEXT_ATOM } from "./sync-saga-context/sync-saga-context-constants.mjs";
+import { createStandardPoolConfig } from "../keystone/keystone-config-builder.mjs";
+import { POOL_ID_CONNECT, POOL_ID_SYNC, KEYSTONE_VERB_CONNECT, KEYSTONE_VERB_SYNC } from "../keystone/keystone-constants.mjs";
+import { KeystoneReplenishStrategy } from "../keystone/keystone-types.mjs";
 const logalot = GLOBAL_LOG_A_LOT;
 const logalotControlDomain = false;
 const lcControlDomain = '[ControlDomain]';
@@ -41,6 +44,44 @@ export class SyncSagaCoordinator {
     lc = `[${SyncSagaCoordinator.name}]`;
     constructor() {
     }
+    /**
+     * Default pool config for the session keystone's `connect` pool.
+     * Consumed exactly once per saga during `peer.connect()`.
+     * Uses `deleteAll` replenish strategy — after the handshake, the pool is gone.
+     *
+     * Override in subclasses or pass custom config via opts to change security parameters.
+     */
+    defaultSessionConnectPoolConfig() {
+        return createStandardPoolConfig({
+            id: POOL_ID_CONNECT,
+            salt: `session-connect-${Date.now()}`,
+            verbs: [KEYSTONE_VERB_CONNECT],
+            size: 20,
+            sequential: 2,
+            random: 2,
+            targetBinding: 0,
+            replenishStrategy: KeystoneReplenishStrategy.deleteAll,
+        });
+    }
+    /**
+     * Default pool config for the session keystone's per-turn `sync` pool.
+     * Used on each outgoing context frame (Init, Delta, Commit).
+     * Uses `topUp` replenish strategy to stay active throughout the saga.
+     *
+     * Override in subclasses or pass custom config via opts to change security parameters.
+     */
+    defaultSessionSyncPoolConfig() {
+        return createStandardPoolConfig({
+            id: POOL_ID_SYNC,
+            salt: `session-sync-${Date.now()}`,
+            verbs: [KEYSTONE_VERB_SYNC],
+            size: 200,
+            sequential: 3,
+            random: 3,
+            targetBinding: 3,
+            replenishStrategy: KeystoneReplenishStrategy.topUp,
+        });
+    }
     /**
      * Executes a synchronization saga using the Symmetric Sync Protocol.
      *
@@ -48,7 +89,7 @@ export class SyncSagaCoordinator {
      * **Execution Context**: **Sender (Local)**.
      * This method is the entry point for starting a sync saga.
      */
-    async sync({ peer, domainIbGibs, conflictStrategy = SyncConflictStrategy.abort, metaspace, localSpace, }) {
+    async sync({ peer, domainIbGibs, senderIdentity, fnSenderSecret, conflictStrategy = SyncConflictStrategy.abort, metaspace, localSpace, }) {
         const lc = `${this.lc}[${this.sync.name}]`;
         if (logalot) {
             console.log(`${lc} starting...`);
@@ -57,6 +98,14 @@ export class SyncSagaCoordinator {
             debugger;
             throw new Error(`${lc} source (or localSpace) required (E: 25df3761f7686a1099a552f83c95d326)`);
         }
+        if (senderIdentity || fnSenderSecret) {
+            if (!senderIdentity) {
+                throw new Error(`(UNEXPECTED) senderIdentity falsy but fnSenderSecret truthy? if either is used, both must be truthy. (E: e366628a4919c7d727d2cbd8e5b75e26)`);
+            }
+            if (!fnSenderSecret) {
+                throw new Error(`(UNEXPECTED) fnSenderSecret falsy but senderIdentity truthy? if either is used, both must be truthy. (E: 7d55ce37ae482fec48e3398158161926)`);
+            }
+        }
         // 1. SETUP SAGA METADATA
         const sagaId = await getUUID();
         // Setup Observable & Promise
@@ -92,6 +141,18 @@ export class SyncSagaCoordinator {
         // Async execution wrapper
         (async () => {
             try {
+                const targetAddrs = domainIbGibs ? domainIbGibs.map(domain => getIbGibAddr({ ibGib: domain })) : undefined;
+                // Attach saga-scoped identity opts to peer now that sagaId is known.
+                peer.setOptionalOpts({
+                    sagaId,
+                    senderIdentity,
+                    fnSenderSecret,
+                    sessionConnectPoolConfig: this.defaultSessionConnectPoolConfig(),
+                    sessionSyncPoolConfig: this.defaultSessionSyncPoolConfig(),
+                    targetAddrs,
+                });
+                // ESTABLISH SESSION IDENTITY (pre-connect, if identity provided)
+                const sessionIdentity = await peer.establishSessionIdentity();
                 // CONNECT PEER (if needed)
                 await peer.connect({ sagaId });
                 // CREATE INITIAL FRAME (Stage.init)