@ibgib/core-gib 0.1.43 → 0.1.44

package/src/sync/sync-saga-coordinator.mts

@@ -16,13 +16,16 @@ import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
 import { GLOBAL_LOG_A_LOT } from "../core-constants.mjs";
 import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
 import { putInSpace, getLatestAddrs, getFromSpace, registerNewIbGib } from "../witness/space/space-helper.mjs";
-import { KeystoneIbGib_V1 } from "../keystone/keystone-types.mjs";
+import { KeystoneIbGib_V1, KeystonePoolConfig_HashV1 } from "../keystone/keystone-types.mjs";
 import { KeystoneService_V1 } from "../keystone/keystone-service-v1.mjs";
+import { deriveKey } from "../keystone/kdf/kdf-helpers.mjs";
+import { KdfStrategy } from "../keystone/kdf/kdf-constants.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
 import {
     SyncStage, SYNC_ATOM, SYNC_MSG_REL8N_NAME, SYNC_SAGA_PAYLOAD_ADDRS_DOMAIN,
     SyncConflictStrategy,
     SYNC_CONFLICT_STRATEGY_VALID_VALUES,
+    DEFAULT_SESSION_IDENTITY_INITIAL_DELEGATE_SECRET,
 } from "./sync-constants.mjs";
 import {
     appendToTimeline, createTimeline, getHistory, getHistoryAddrs, Rel8nInfo, Rel8nRemovalInfo
@@ -60,6 +63,7 @@ import { graftTimelines, } from "./graft-info/graft-info-helpers.mjs";
 import { GRAFT_INFO_REL8N_NAME } from "./graft-info/graft-info-constants.mjs";
 import { GraftInfoIbGib_V1 } from "./graft-info/graft-info-types.mjs";
 import { validateIbGibIntrinsically } from "@ibgib/ts-gib/dist/V1/validate-helper.mjs";
+import { KEYSTONE_VERB_MANAGE } from "../keystone/keystone-constants.mjs";
 
 
 const logalot = GLOBAL_LOG_A_LOT;
@@ -94,18 +98,14 @@ export class SyncSagaCoordinator {
      * @remarks
      * **Execution Context**: **Sender (Local)**.
      * This method is the entry point for starting a sync session.
-     *
-     * @param opts.peer - The remote peer witness to communicate with.
-     * @param opts.localSpace - The local space that will be read from and written to.
-     * @param opts.metaspace - Service for creating temp spaces and managing ibgibs.
-     * @param opts.domainIbGibs - The root ibgibs defining the scope of the sync.
-     * @param opts.useSessionIdentity - (Optional) Whether to create an ephemeral session identity. Default: true.
      */
     public async sync({
         peer,
         domainIbGibs,
         conflictStrategy = SyncConflictStrategy.abort,
         useSessionIdentity = true,
+        identity,
+        identitySecret,
         metaspace,
         localSpace,
     }: {
@@ -121,7 +121,8 @@ export class SyncSagaCoordinator {
          */
         domainIbGibs: IbGib_V1[],
         /**
-         * The space containing the {@link domainIbGibs} we want to sync.
+         * The space containing the {@link domainIbGibs} we want to sync. If
+         * sync is successful, any updates to timelines will be stored here.
          */
         localSpace: IbGibSpaceAny;
         /**
@@ -129,11 +130,17 @@ export class SyncSagaCoordinator {
          */
         metaspace: MetaspaceService;
         /**
-         * The identity authorizing this sync.
+         * The primary (i.e. non-session) identity authorizing this sync.
+         *
+         * If this is truthy, then {@link identitySecret} must also be provided.
          */
         identity?: KeystoneIbGib_V1;
         /**
          * The secret for the identity (to sign the commit).
+         *
+         * If provided, this will drive both signing {@link identity} keystone
+         * (if provided) AND session keystone (if {@link useSessionIdentity} is
+         * true).
          */
         identitySecret?: string;
         /**
@@ -144,8 +151,10 @@ export class SyncSagaCoordinator {
          */
         conflictStrategy?: SyncConflictStrategy;
         /**
-         * If true, creates an ephemeral session identity for the sync process to
-         * secure the sync transaction itself.
+         * If true, creates an ephemeral session identity for the sync process
+         * to secure the sync transaction itself.
+         *
+         * If this is true, {@link identitySecret} must also be provided.
          *
          * @default true
          */
@@ -196,9 +205,13 @@ export class SyncSagaCoordinator {
             try {
 
                 // BOOTSTRAP IDENTITY (Session Keystone)
-                const sessionIdentity = useSessionIdentity
-                    ? await this.getSessionIdentity({ sagaId, metaspace, localSpace })
-                    : undefined;
+                let sessionIdentity: KeystoneIbGib_V1 | undefined = undefined;
+
+                if (useSessionIdentity) {
+                    if (!identitySecret) { throw new Error(`useSessionIdentity is true, but identitySecret is falsy. Must provide a secret if you want to use a session identity. (E: 81915860c4dd3ea4dfd81825fa74c126)`); }
+                    sessionIdentity = await this.getSessionIdentity({ sagaId, identitySecret, metaspace, localSpace });
+                }
+
                 // if (logalot) { console.log(`${lc} sessionIdentity: ${sessionIdentity ? pretty(sessionIdentity) : 'undefined'} (I: abc01872800b3a66b819a05898bba826)`); }
 
                 // CREATE INITIAL FRAME (Stage.init)
@@ -214,6 +227,7 @@ export class SyncSagaCoordinator {
                 await this.executeSagaLoop({
                     initFrame, initDomainGraph,
                     peer,
+                    identitySecret,
                     sessionIdentity,
                     updates$,
                     localSpace,
@@ -266,7 +280,13 @@ export class SyncSagaCoordinator {
          * Local temp space relative to the execution context's POV
          */
         myTempSpace: IbGibSpaceAny,
+        /**
+         * @see {@link sync} `identity` param.
+         */
         identity?: KeystoneIbGib_V1,
+        /**
+         * @see {@link sync} `identitySecret` param.
+         */
         identitySecret?: string,
         metaspace: MetaspaceService,
     }): Promise<SyncSagaContextIbGib_V1 | null> {
@@ -279,7 +299,6 @@ export class SyncSagaCoordinator {
                 mySpace,
                 myTempSpace,
                 identity,
-                identitySecret,
                 metaspace,
             });
 
@@ -325,12 +344,74 @@ export class SyncSagaCoordinator {
         }
     }
 
+    private async getSessionSecret({
+        sagaId,
+        identitySecret,
+    }: {
+        sagaId: string,
+        identitySecret: string,
+    }): Promise<string> {
+        const lc = `${this.lc}[${this.getSessionSecret.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 0de03f8dcd3e32f1fca244e8f2a8a826)`); }
+
+            // Derive session-specific secret using KDF
+            const sessionSecret = await deriveKey({
+                masterSecret: identitySecret,
+                kdfOpts: {
+                    strategy: KdfStrategy.recursive_salt_wrap,
+                    salt: sagaId,
+                    rounds: 10000,
+                    algorithm: 'SHA-256'
+                }
+            });
+
+            return sessionSecret;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    private async getInitialWeakDelegateSessionSecret({
+        sagaId,
+    }: {
+        sagaId: string,
+    }): Promise<string> {
+        const lc = `${this.lc}[${this.getInitialWeakDelegateSessionSecret.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 872ab81a78827b9f2822b78459203226)`); }
+
+            // Create delegate pool bootstrap secret (publicly derivable)
+            const initialDelegateSecret = await deriveKey({
+                masterSecret: DEFAULT_SESSION_IDENTITY_INITIAL_DELEGATE_SECRET, // Weak, publicly derivable secret
+                kdfOpts: {
+                    strategy: KdfStrategy.recursive_salt_wrap,
+                    salt: sagaId,
+                    rounds: 1, // Minimal rounds - this is meant to be weak
+                    algorithm: 'SHA-256'
+                }
+            });
+
+            return initialDelegateSecret;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
     private async getSessionIdentity({
         sagaId,
+        identitySecret,
         metaspace,
         localSpace,
     }: {
         sagaId: string,
+        identitySecret: string,
         metaspace: MetaspaceService,
         localSpace: IbGibSpaceAny,
     }): Promise<KeystoneIbGib_V1> {
@@ -338,20 +419,59 @@ export class SyncSagaCoordinator {
         try {
             if (logalot) { console.log(`${lc} starting... (I: 428392a4ee636b7bd8f7d5d89a87e826)`); }
 
-            const config: any = {
-                id: 'default',
+            if (!identitySecret) { throw new Error(`(UNEXPECTED) identitySecret falsy? This is expected to be truthy by this point. (E: 8ce053fe59825a6678713128953b9d26)`); }
+
+            const sessionSecret = await this.getSessionSecret({ sagaId, identitySecret });
+
+            const init = await this.getInitialWeakDelegateSessionSecret({ sagaId });
+
+
+            // Create TWO pool configs: Primary (strong) + Delegate (weak bootstrap)
+            const primaryPoolConfig: KeystonePoolConfig_HashV1 = {
+                allowedVerbs: [KEYSTONE_VERB_MANAGE],
+                id: 'primary',
+                type: 'hash-reveal-v1',
+                salt: sagaId,
+                behavior: {
+                    size: 100,  // Large pool for many signatures
+                    replenish: 'top-up',
+                    selectSequentially: 2,
+                    selectRandomly: 2,
+                    targetBindingChars: 10
+                },
+                algo: 'SHA-256',
+                rounds: 1
+            };
+
+            const delegatePoolConfig: any = {
+                id: 'delegate',
                 type: 'hash-reveal-v1',
                 salt: sagaId,
-                behavior: { size: 10, replenish: 'top-up', selectSequentially: 1, selectRandomly: 1, targetBindingChars: 0 },
-                algo: 'SHA-256', rounds: 1
+                behavior: {
+                    size: 10,  // Small pool - only for initial handshake
+                    replenish: 'top-up',
+                    selectSequentially: 1,
+                    selectRandomly: 1,
+                    targetBindingChars: 0
+                },
+                algo: 'SHA-256',
+                rounds: 1
             };
+
+            // Generate keystone with DUAL pools. We have to first genesis with
+            // one and then add the other, because we have two distinct
+            // secrets.
             const sessionIdentity = await this.keystone.genesis({
-                masterSecret: sagaId,
-                configs: [config],
+                masterSecret: sessionSecret,
+                configs: [primaryPoolConfig],
                 metaspace,
-                space: localSpace // ✅ FIXED: Use durable space, not temp space
+                space: localSpace
             });
 
+            // TODO: Store delegate pool separate challenges derived from bootstrap secret
+            // This allows receiver to verify/evolve the delegate pool
+            // For now, the keystone genesis with multiple configs handles this
+
             return sessionIdentity;
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
@@ -381,6 +501,7 @@ export class SyncSagaCoordinator {
         initDomainGraph,
         peer,
         sessionIdentity,
+        identitySecret,
         updates$,
         localSpace,
         tempSpace,
@@ -396,6 +517,10 @@ export class SyncSagaCoordinator {
         initDomainGraph: FlatIbGibGraph,
         peer: SyncPeerWitness,
         sessionIdentity?: KeystoneIbGib_V1,
+        /**
+         * if {@link sessionIdentity} provided, this must also be truthy
+         */
+        identitySecret?: string,
         updates$: SubjectWitness<SyncSagaContextIbGib_V1>,
         metaspace: MetaspaceService
         localSpace: IbGibSpaceAny,
@@ -755,7 +880,7 @@ export class SyncSagaCoordinator {
             const sagaFrame = await this.evolveSyncSagaIbGib({
                 msgStones: [initStone],
                 conflictStrategy,
-                sessionIdentity: sessionIdentity,
+                sessionIdentity,
                 metaspace,
                 localSpace,
             });
@@ -873,7 +998,6 @@ export class SyncSagaCoordinator {
         mySpace,
         myTempSpace,
         identity,
-        identitySecret,
         metaspace,
     }: {
         sagaContext: SyncSagaContextIbGib_V1,
@@ -893,7 +1017,6 @@ export class SyncSagaCoordinator {
          */
         myTempSpace: IbGibSpaceAny,
         identity?: KeystoneIbGib_V1,
-        identitySecret?: string,
         metaspace: MetaspaceService,
     }): Promise<HandleSagaResponseContextResult> {
         const lc = `${this.lc}[${this.handleResponseSagaContext.name}]`;
@@ -916,7 +1039,7 @@ export class SyncSagaCoordinator {
                         sagaIbGib,
                         messageData: messageData as SyncSagaMessageInitData_V1,
                         metaspace, mySpace, myTempSpace,
-                        identity, identitySecret
+                        identity,
                     });
                     break;
 
@@ -987,7 +1110,6 @@ export class SyncSagaCoordinator {
         myTempSpace,
         metaspace,
         identity,
-        // identitySecret,
     }: {
         sagaIbGib: SyncIbGib_V1,
         messageData: SyncSagaMessageInitData_V1,
@@ -1004,7 +1126,6 @@ export class SyncSagaCoordinator {
         myTempSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
         identity?: KeystoneIbGib_V1,
-        identitySecret?: string,
     }): Promise<NextSagaFrameInfo> {
         const lc = `${this.lc}[${this.handleInitFrame.name}]`;
         try {
@@ -2530,10 +2651,9 @@ export class SyncSagaCoordinator {
         localSpace: IbGibSpaceAny,
         metaspace: MetaspaceService,
         /**
-         * does NOT evolve the keystone. this should be done by the caller.
-         * (NOT IMPLEMENTED YET ANYWAY)
+         * does NOT evolve the keystone.
          */
-        sessionIdentity?: KeystoneIbGib_V1,
+        sessionIdentity: KeystoneIbGib_V1 | undefined,
     }): Promise<SyncIbGib_V1> {
         const lc = `${this.lc}[${this.evolveSyncSagaIbGib.name}]`;
         try {
@@ -2617,6 +2737,11 @@ export class SyncSagaCoordinator {
                 const rel8ns: SyncRel8ns_V1 = { [SYNC_MSG_REL8N_NAME]: stoneAddrs, };
                 if (identityAddr) { rel8ns.identity = [identityAddr]; }
 
+                // Attach session keystone to saga frame via hard rel8n
+                if (sessionIdentity) {
+                    rel8ns.sessionKeystones = [getIbGibAddr({ ibGib: sessionIdentity })];
+                }
+
                 const resNew = await createTimeline({
                     space: localSpace,
                     metaspace,

package/src/sync/sync-saga-message/sync-saga-message-types.mts

@@ -55,7 +55,7 @@ export interface SyncSagaMessageIbGib_V1 extends IbGib_V1<SyncSagaMessageData_V1
 /**
  * The "Hello" of the sync protocol.
  *
- * Exchanges knowledge maps (what I have) and identity (who I am).
+ * Exchanges knowledge maps (what I have).
  */
 export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1 {
     stage: typeof SyncStage.init;
@@ -68,12 +68,6 @@ export interface SyncSagaMessageInitData_V1 extends SyncSagaMessageData_V1 {
      */
     knowledgeMap: { [tjp: string]: IbGibAddr };
 
-    /**
-     * The Keystone Identity of the sender.
-     * Required for the first handshake or if the receiver doesn't know the sender.
-     */
-    identity?: KeystoneIbGib_V1;
-
     /**
      * What the sender wants to do.
      * e.g. "push" (I have data for you) or "pull" (Give me data).

package/src/sync/sync-types.mts

@@ -195,6 +195,18 @@ export interface SyncRel8ns_V1 extends IbGibRel8ns_V1 {
      */
     identity?: string[];
 
+    /**
+     * Session keystones used for signing saga frames.
+     *
+     * Array contains addresses of keystone evolution chain:
+     * - Index 0: Genesis keystone (dual-pool architecture)
+     * - Index N: Latest evolved keystone after signing operations
+     *
+     * Each sync endpoint retrieves the session keystone from this rel8n
+     * rather than searching spaces. Keystones are stored in durable spaces.
+     */
+    sessionKeystones?: IbGibAddr[];
+
     /**
      * The message stone that contains the information about the particular
      * stage of the sync process we are in.