@ibgib/core-gib 0.1.53 → 0.1.55

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

@@ -1,7 +1,6 @@
 import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
 import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
 
-import { KeystoneIbGib_V1 } from "../../keystone/keystone-types.mjs";
 import { SyncStage } from "../sync-constants.mjs";
 import { SyncMode, } from "../sync-types.mjs";
 import { SyncConflictStrategy, } from "../sync-constants.mjs";
@@ -17,7 +16,7 @@ export interface SyncSagaMessageIb_V1 {
 
 export interface SyncSagaMessageData_V1 extends IbGibData_V1 {
     /**
-     * Unique ID for the synchronization session (saga).
+     * Unique ID for the synchronization saga.
      */
     sagaId: string;
 
@@ -299,7 +298,7 @@ export interface SyncSagaMessageDeltaData_V1 extends SyncSagaMessageData_V1 {
 export interface SyncSagaMessageCommitData_V1 extends SyncSagaMessageData_V1 {
     stage: typeof SyncStage.commit;
     /**
-     * True if the session completed successfully from the sender's perspective.
+     * True if the saga completed successfully from the sender's perspective.
      */
     success: boolean;
     /**

package/src/sync/sync-types.mts

@@ -3,7 +3,6 @@ import { IbGib_V1, IbGibData_V1, IbGibRel8ns_V1 } from "@ibgib/ts-gib/dist/V1/ty
 
 import { SubjectWitness } from "../common/pubsub/subject/subject-types.mjs";
 import { SyncSagaContextIbGib_V1 } from "./sync-saga-context/sync-saga-context-types.mjs";
-import { KeystoneIbGib_V1, } from "../keystone/keystone-types.mjs";
 import { SYNC_ATOM, SYNC_MSG_REL8N_NAME, SyncConflictStrategy, } from "./sync-constants.mjs";
 import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
@@ -125,9 +124,7 @@ export interface SyncSagaInfo {
 
 export interface SyncSagaFrameDependencyGraph {
     sagaIbGib: SyncIbGib_V1;
-    // msgStones: IbGib_V1[];
     msgStones: SyncSagaMessageIbGib_V1[];
-    identities: KeystoneIbGib_V1[];
 }
 
 /**
@@ -160,7 +157,8 @@ export interface SyncIb_V1 {
 
 export interface SyncData_V1 extends IbGibData_V1 {
     /**
-     * Unique ID for this synchronization session.
+     * Unique ID for this sync saga. This should correspond to sagaId.
+     *
      * Corresponds to `uuid` in standard IbGibData.
      */
     uuid: string;
@@ -189,24 +187,6 @@ export interface SyncData_V1 extends IbGibData_V1 {
 }
 
 export interface SyncRel8ns_V1 extends IbGibRel8ns_V1 {
-    /**
-     * Link to the Keystone Identity performing this step.
-     * This MUST point to the specific Keystone Frame that authorizes this sync frame.
-     */
-    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.
-     */
-    sessionKeystone?: IbGibAddr[];
-
     /**
      * The message stone that contains the information about the particular
      * stage of the sync process we are in.

package/src/sync/unused-identity-backup.mts.md

@@ -0,0 +1,311 @@
+I am removing ALL identity/session/identities/keystone-related code from sync
+and starting over, now that I have a clearer idea of the requirements.
+
+This is code that I thought would be reusable with minimal adjustments later.
+
+TODO: I have mangled some of the hits for these terms by adding a space after
+the first letter. After i am done, need to go back through and search for "k
+eystone", "i dentity" "s ession" for these mangled terms.
+
+```typescript
+import { KeystoneIbGib_V1, } from "../keystone/keystone-types.mjs";
+import { KeystoneService_V1 } from '../../keystone/keystone-service-v1.mjs';
+import { validateKeystoneGraph, validateKeystoneTransition } from '../../keystone/keystone-helpers.mjs';
+
+/**
+ * creates a session identity keystone based off of the given args.
+ *
+ * Then, if the {@link primaryIdentity} keystone is provided, this also
+ * **signs** this keystone pointing to the address of the sess
+ */
+public async createSessionIdentity({
+    sagaId,
+    primaryIdentity,
+    nonSessionSecret,
+    metaspace,
+    localSpace,
+}: {
+    /**
+     * unique to any one particular saga.
+     */
+    sagaId: string,
+    /**
+     * optional main identity, e.g., Alice's keystone
+     */
+    primaryIdentity: KeystoneIbGib_V1 | undefined,
+    /**
+     * driving secret behind the sync operation. usually, this will be the
+     * secret corresponding to a primary identity keystone. But this can
+     * also just be a one-time secret just to have more security in the
+     * transmission intrinsically.
+     */
+    nonSessionSecret: string,
+    metaspace: MetaspaceService,
+    localSpace: IbGibSpaceAny,
+}): Promise<{
+    sessionIdentity: KeystoneIbGib_V1,
+    sessionSecret: string,
+    /**
+     * if truthy, this evolved from the incoming {@link primaryIdentity} and
+     * has already persisted/registered in the incoming {@link localSpace}.
+     */
+    newPrimaryIdentity: KeystoneIbGib_V1 | undefined
+}> {
+    const lc = `${this.lc}[${this.createSessionIdentity.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 428392a4ee636b7bd8f7d5d89a87e826)`); }
+
+        if (!nonSessionSecret) { throw new Error(`(UNEXPECTED) nonSessionSecret falsy? This is expected to be truthy by this point. (E: 8ce053fe59825a6678713128953b9d26)`); }
+
+        debugger; // step through create session id
+        const sessionSecret = await this.deriveSessionSecret({
+            sagaId, nonSessionSecret
+        });
+
+        // Generate keystone with two initial pools in two steps.
+        //   1. Create primary pool with genesis method to correspond to the
+        //      sender/sender's secret/identity.
+        //   2. Create a separate pool and add separately because a
+        //      different pw + config is used for the transition pool.
+
+        if (!this.sessionKeystonePoolConfig) { throw new Error(`this.sessionKeystonePoolConfig falsy. createSessionIdentity requires the coordinator to have this config set. (E: d65bb868d5e3e72c585d64d594e2b826)`); }
+        const sessionIdentity_genesis = await this.keystoneSvc.genesis({
+            masterSecret: sessionSecret,
+            configs: [this.sessionKeystonePoolConfig],
+            metaspace,
+            space: localSpace,
+        });
+
+        // #region sanity validation of genesis keystone
+        /**
+         * not necessary but since it's a new design, I'm putting in this
+         * immediate validation just to put it through its paces. (worth the
+         * slight perf hit).
+         */
+        const validationErrors = await validateGenesisKeystone({
+            keystoneIbGib: sessionIdentity_genesis
+        });
+        if (validationErrors && validationErrors.length > 0) { throw new Error(`(UNEXPECTED) the sessionIdentity_genesis that we just created already has validation errors just after creation? errors: ${validationErrors} (E: e9ca08cf0f8858bb1ace8b9fa89f8726)`); }
+        // #endregion sanity validation of genesis keystone
+
+        let newPrimaryIdentity: KeystoneIbGib_V1 | undefined = undefined;
+        if (primaryIdentity) {
+            newPrimaryIdentity = await this.keystoneSvc.sign({
+                latestKeystone: primaryIdentity,
+                poolId: this.sessionKeystonePoolConfig.id,
+                claim: {
+                    verb: KEYSTONE_VERB_SIGN,
+                    target: getIbGibAddr({ ibGib: sessionIdentity_genesis }),
+                },
+                masterSecret: nonSessionSecret,
+                metaspace,
+                space: localSpace,
+                // frameDetails: undefined, // anything to put here?
+                // requiredChallengeIds: undefined, // not relevant I think
+            });
+        }
+
+        // --- IMMEDIATE PERSISTENCE (Audit Trail Rule) ---
+        // The initial session keystone is trusted locally and must be stored
+        // in the durable space immediately so the FSM and validation steps
+        // can use it to sign outgoing contexts.
+        const identityIbGibs: IbGib_V1[] = [
+            sessionIdentity_genesis
+        ];
+        if (newPrimaryIdentity) {
+            identityIbGibs.push(newPrimaryIdentity);
+        }
+
+        // identity ibgibs are single framed without dna, so we only have to
+        // worry about each individual frame (i.e. no dependency graph)
+        await metaspace.put({
+            ibGibs: identityIbGibs,
+            space: localSpace,
+        });
+        for (const identityIbGib of identityIbGibs) {
+            await registerNewIbGib({
+                ibGib: identityIbGib,
+                space: localSpace,
+                fnBroadcast: undefined,
+            });
+        }
+        // ------------------------------------------------
+
+        return {
+            sessionIdentity: sessionIdentity_genesis,
+            sessionSecret,
+            newPrimaryIdentity,
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+    * helper that KDFs the given identitySecret, using {@link sagaId} to do so.
+    *
+    * @returns deterministically derived session secret
+    */
+private async deriveSessionSecret({
+    sagaId,
+    nonSessionSecret,
+}: {
+    sagaId: string,
+    /**
+        * driving secret behind the sync operation. usually, this will be the
+        * secret corresponding to a primary identity keystone. But this can
+        * also just be a one-time secret just to have more security in the
+        * transmission intrinsically.
+        */
+    nonSessionSecret: string,
+}): Promise<string> {
+    const lc = `${this.lc}[${this.deriveSessionSecret.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 0de03f8dcd3e32f1fca244e8f2a8a826)`); }
+
+        // Derive session-specific secret using KDF
+        const sessionSecret = await deriveKey({
+            masterSecret: nonSessionSecret,
+            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.`); }
+    }
+}
+
+
+
+/**
+ * move to sync-peer-helpers.mts as a pure function?
+ */
+export async function authenticateContext({
+    context,
+    space,
+    keystoneSvc,
+}: {
+    context: SyncSagaContextIbGib_V1,
+    space: IbGibSpaceAny,
+    keystoneSvc?: KeystoneService_V1,
+}): Promise<string[]> {
+    const lc = `[${authenticateContext.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 2677a482dfa873dcd1aa04a3031ff826)`); }
+
+        const errors: string[] = [];
+        if (!keystoneSvc) {
+            if (logalot) { console.warn(`${lc} No keystoneSvc provided. Skipping context authentication. (W: d34b8ad93d84a1ba8d8f7facd288826)`); }
+            return errors;
+        }
+
+        // Bill Architecture: We only sign at the context level.
+        // If the context refers to a session keystone, we must have a signedSessionKeystone
+        // as well to verify the most recent turn.
+        const { sessionKeystone: prevKeystoneAddrs } = context.rel8ns || {};
+        const { signedSessionKeystone: currKeystone } = context;
+
+        if (prevKeystoneAddrs && prevKeystoneAddrs.length > 0) {
+            if (!currKeystone) {
+                errors.push(`context.rel8ns.sessionKeystone present but context.signedSessionKeystone falsy. (E: b6e5a8ad93d84260a8d8e7facd288826)`);
+                return errors;
+            }
+
+            // Retrieve the previous keystone frame from space
+            const prevKeystoneAddr = prevKeystoneAddrs[0];
+            const getPrevRes = await getFromSpace({ addr: prevKeystoneAddr, space });
+            if (!getPrevRes.success || !getPrevRes.ibGibs || getPrevRes.ibGibs.length === 0) {
+                errors.push(`couldn't find previous session keystone (${prevKeystoneAddr}) in space (${space.ib}). (E: 7c34b8ad94d84a9ba8cbe7facd288826)`);
+                return errors;
+            }
+            const prevKeystone = getPrevRes.ibGibs[0] as KeystoneIbGib_V1;
+
+            // 1. Validate the transition (API replay of evolution + intrinsic validation)
+            const transitionErrors = await keystoneSvc.validate({
+                currentIbGib: currKeystone,
+                prevIbGib: prevKeystone,
+            });
+            if (transitionErrors.length > 0) {
+                errors.push(`Invalid session keystone transition: ${transitionErrors.join(', ')} (E: d34b8ad95d84b90a8d8ef7facd288826)`);
+            }
+
+            // 2. Verify that the signature in current keystone actually targets this context
+            const contextAddr = getIbGibAddr({ ibGib: context });
+            const proofTargetsThisContext = currKeystone.data?.proofs.some(p => p.claim.target === contextAddr);
+            if (!proofTargetsThisContext) {
+                errors.push(`Session keystone signature does not target the current context ibgib (${contextAddr}). (E: f3e5a8ad96d84c1ba8d8f7facd288826)`);
+            }
+        }
+
+        return errors;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+
+
+// #region this sync peer innerspace sendContextRequest
+
+            // Bill architecture: Keystone identity transportation.
+            // On each turn, the sender must include the current signed session
+            // keystone. If it's the first turn (Init), we include the entire
+            // keystone graph to ensure the receiver has the primary-to-session
+            // authorized link.
+            const identityIbGibs: IbGib_V1[] = [];
+            const { signedSessionKeystone } = context;
+            if (signedSessionKeystone) {
+                if (msg.data.stage === SyncStage.init) {
+                    // transmit full keystone graph on the first handshake
+                    const keystoneGraph = await getDependencyGraph({
+                        ibGib: signedSessionKeystone,
+                        space: localSpace,
+                    });
+                    identityIbGibs.push(...Object.values(keystoneGraph));
+                } else {
+                    // transmit only the latest evolution for subsequent turns
+                    identityIbGibs.push(signedSessionKeystone);
+                }
+            }
+
+// #endregion this sync peer innerspace sendContextRequest
+
+
+// #region SyncSagaContextRel8ns_V1
+
+    /**
+     * The Ephemeral Session Keystone Identity used for this saga. Required for
+     * validating the saga frame and this context.
+     *
+     * WARNING!!!: THIS DOES NOT POINT TO THE CURRENT SESSION KEYSTONE IN
+     * {@link SyncSagaContextIbGib_V1.signedSessionKeystone}. This points to the
+     * PREVIOUS FRAME (immediate past) of that frame. That session keystone
+     * signs with THIS context's frame as its target, so it is logically
+     * impossible because the hash would be different.
+     *
+     * ## notes
+     *
+     * ATOW (02/18/2026), this is a single address that will have a primary pool
+     * for the sender and a delegated pool for the receiver.
+     *
+     * @see {@link SyncSagaContextIbGib_V1.signedSessionKeystone}
+     */
+    sessionKeystone?: IbGibAddr[];
+
+// #endregion SyncSagaContextRel8ns_V1
+
+```

package/src/test/mock-space.mts

@@ -29,7 +29,7 @@
 //             const ibGibs: IbGib_V1[] = [];
 //             for (const addr of addrs) {
 //                 const ig = await this.get({ addr });
-//                 if (ig) ibGibs.push(ig);
+//                 if (ig) { ibGibs.push(ig); }
 //             }
 //             return { ibGibs };
 //         }

package/src/test-helpers.mts

@@ -11,7 +11,6 @@ import { IbGib_V1, IbGibRel8ns_V1, IbGibData_V1 } from '@ibgib/ts-gib/dist/V1/ty
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 
 import { GLOBAL_LOG_A_LOT } from './core-constants.mjs';
-import { KeystoneService_V1 } from './keystone/keystone-service-v1.mjs';
 import { IbGibSpaceAny } from './witness/space/space-base-v1.mjs';
 import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
 import { createTimeline, mut8Timeline, appendToTimeline } from './timeline/timeline-api.mjs';
@@ -126,30 +125,6 @@ export async function createTimelineRootTestHelper<TData extends IbGibData_V1 =
     }
 }
 
-/**
- * Creates a valid, mock Keystone Service for testing purposes.
- * This mocks the identity and signing logic needed for Sync operations.
- */
-export async function getTestKeystoneServiceHelper(): Promise<KeystoneService_V1> {
-    class MockKeystoneService extends KeystoneService_V1 {
-        async getIdentity(): Promise<any> {
-            // Return a dummy identity
-            // We use the Factory directly here to just get *something* that looks like an ibgib
-            const res = await Factory_V1.firstGen({
-                parentIbGib: Factory_V1.primitive({ ib: 'identity' }),
-                ib: 'identity',
-                data: { uuid: await getUUID() },
-                dna: true,
-            });
-            return res.newIbGib;
-        }
-        // Implement other methods as no-ops or simple mocks
-        async sign(args: any): Promise<any> { return args.latestKeystone; /* minimal mock */ }
-        async verify(args: any): Promise<any> { return []; /* no errors */ }
-    }
-    return new MockKeystoneService() as unknown as KeystoneService_V1;
-}
-
 export interface TestIbGibIb {
     /**
      * @example alpha, beta, gamma, etc.
@@ -263,7 +238,7 @@ function getNewTestIb({
     const lc = `[${getNewTestIb.name}]`;
     try {
         if (logalot) { console.log(`${lc} starting... (I: 60aebdb828f72bbfbcbf401e7af09826)`); }
-        if (!atom) throw new Error(`atom required (E: dc041852cdd88d692a8c2168ae4c7626)`);
+        if (!atom) { throw new Error(`atom required (E: dc041852cdd88d692a8c2168ae4c7626)`); }
 
         let ib = [
             atom,