@ibgib/core-gib 0.1.54 → 0.1.57

package/src/keystone/keystone-service-v1.respec.mts

@@ -2,7 +2,7 @@ import {
     respecfully, iReckon, ifWe, firstOfAll, firstOfEach, lastOfAll, lastOfEach, respecfullyDear, ifWeMight
 } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
 const maam = `[${import.meta.url}]`, sir = maam;
-import { clone, hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { clone, hash, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
 import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
 
@@ -17,79 +17,6 @@ import { addToBindingMap } from './keystone-helpers.mjs';
 const logalot = GLOBAL_LOG_A_LOT;
 
 
-// /**
-//  * not sure where to put this, but we probably will want to reuse this in the
-//  * future (assuming it works)
-//  * @returns metaspace service reference
-//  */
-// async function getNewInitializedInMemoryMetaspaceForTesting({
-//     defaultSpaceName,
-// }: {
-//     defaultSpaceName: string,
-// }): Promise<MetaspaceService> {
-//     const lc = `[${getNewInitializedInMemoryMetaspaceForTesting.name}]`;
-//     try {
-//         if (logalot) { console.log(`${lc} starting... (I: 766d7596addcb73f4820586469233b25)`); }
-
-//         let metaspace = new Metaspace_Innerspace(/*cacheSvc*/undefined);
-//         if (logalot) { console.log(`${lc} creating metaspace complete. initializing... (I: 61b74d62e8832c9fa853e4b8c4c2d825)`); }
-//         getGibInfo()
-
-//         await metaspace.initialize({
-//             spaceName: defaultSpaceName,
-//             /**
-//              * passing in undefined will use the defaults. probably will need to
-//              * adjust this for testing purposes, but let's see what happens with
-//              * this first.
-//              */
-//             metaspaceFactory: {
-//                 fnDtoToSpace: async () => {
-//                     if (!currentSpace) { currentSpace = new IbGibTestSpace(); }
-//                     return currentSpace;
-//                 },
-//                 fnZeroSpaceFactory: () => {
-//                     if (!currentZeroSpace) { currentZeroSpace = new IbGibTestSpace(); }
-//                     return currentZeroSpace;
-//                 },
-//                 fnDefaultLocalSpaceFactory: async () => {
-//                     if (!currentSpace) { currentSpace = new IbGibTestSpace(); }
-//                     return currentSpace;
-//                 },
-
-//                 // export type DtoToSpaceFunction = (spaceDto: IbGib_V1) => Promise<IbGibSpaceAny>;
-//                 // export type ZeroSpaceFactoryFunction = () => IbGibSpaceAny;
-//                 // export type LocalSpaceFactoryFunction = (opts: CreateLocalSpaceOptions) => Promise<IbGibSpaceAny | undefined>;
-//             },
-//             getFnAlert: () => { return async ({ title, msg }) => console.log(title, msg) },
-//             getFnPrompt: () => {
-//                 return async ({ title, msg }) => {
-//                     // if this is needed, we might set up some way for testing
-//                     // to prepare either a queue of prompts or some kind of map or getter
-//                     // and put it on the metaspace itself
-//                     throw new Error(`not implemented (E: c7ef688a02f8cb74487260f9274ac825)`);
-//                     // promptForText({ title, msg, confirm: false });
-//                 }
-//             },
-//             getFnPromptPassword: () => {
-//                 return async () => {
-//                     // similar to getFnPrompt, if we need a _different_
-//                     // password, we might set up some way for testing to prepare
-//                     // either a queue of passwords or some kind of map or getter
-//                     // and put it on the metaspace itself
-//                     return 'password';
-//                     // promptForSecret({ confirm: true })
-//                 }
-//             },
-//         });
-//         return metaspace;
-//     } catch (error) {
-//         console.error(`${lc} ${extractErrorMsg(error)}`);
-//         throw error;
-//     } finally {
-//         if (logalot) { console.log(`${lc} complete.`); }
-//     }
-// }
-
 /**
  * A simple in-memory map acting as a Space.
  * Pure Storage. No Indexing logic.
@@ -115,8 +42,8 @@ class MockIbGibSpace {
             const addrs = arg.data.ibGibAddrs || [];
             const ibGibs: IbGib_V1[] = [];
             for (const addr of addrs) {
-                const ig = await this.get({ addr });
-                if (ig) ibGibs.push(ig);
+                const x = await this.get({ addr });
+                if (x) { ibGibs.push(x); }
             }
             return { ibGibs };
         }
@@ -190,13 +117,14 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     // Setup generic variables
     const masterSecret = "TestSecret_12345";
-    const salt = "TestPool";
+    const poolId = "TestPool";
     let config: KeystonePoolConfig_HashV1;
 
     firstOfAll(sir, async () => {
         // Use our standard builder to get a valid config object
+        const salt = (await getUUID()).substring(0, 16);
         config = createStandardPoolConfig({
-            id: salt,
+            id: poolId,
             salt,
         }) as KeystonePoolConfig_HashV1;
     });
@@ -243,7 +171,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             const challengeId = "a3ff7843552870fc28bef2b"; // arbitrary random challengeId
 
             // 1. Generate Solution
-            const solution = await strategy.generateSolution({ poolSecret, poolId: salt, challengeId });
+            const solution = await strategy.generateSolution({ poolSecret, poolId: config.id, challengeId });
             iReckon(sir, solution.value).asTo('solution value exists').isGonnaBeTruthy();
             iReckon(sir, solution.challengeId).asTo('id matches').willEqual(challengeId);
 
@@ -262,7 +190,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             const challengeId = "8c994f3ed598f150e25513"; // arbitrary random challengeId
 
             // Generate real pair
-            const solution = await strategy.generateSolution({ poolSecret, poolId: salt, challengeId });
+            const solution = await strategy.generateSolution({ poolSecret, poolId: config.id, challengeId });
             const challenge = await strategy.generateChallenge({ solution });
 
             // Tamper with solution value
@@ -278,11 +206,11 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
             // Generate pair A
             const challengeId_A = "416c38cfd6ee63dbf8d4e5ef36"; // arbitrary random challengeId
-            const solutionA = await strategy.generateSolution({ poolSecret, poolId: salt, challengeId: challengeId_A });
+            const solutionA = await strategy.generateSolution({ poolSecret, poolId: config.id, challengeId: challengeId_A });
 
             // Generate pair B
             const challengeId_B = "c487ef6b7878fae798c3"; // arbitrary random challengeId
-            const solutionB = await strategy.generateSolution({ poolSecret, poolId: salt, challengeId: challengeId_B });
+            const solutionB = await strategy.generateSolution({ poolSecret, poolId: config.id, challengeId: challengeId_B });
             const challengeB = await strategy.generateChallenge({ solution: solutionB });
 
             // Check A against B
@@ -314,9 +242,10 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
 
     await respecfully(sir, 'Genesis', async () => {
         await ifWe(sir, 'creates a valid genesis frame and persists it', async () => {
+            const salt = (await getUUID()).substring(0, 16);
             const config = createStandardPoolConfig({
                 id: POOL_ID_DEFAULT,
-                salt: POOL_ID_DEFAULT,
+                salt,
             });
 
             genesisKeystone = await service.genesis({
@@ -406,9 +335,10 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
         mockMetaspace = new MockMetaspaceService(mockSpace);
 
         // Setup Alice's Identity
+        const salt = (await getUUID()).substring(0, 16);
         const config = createStandardPoolConfig({
             id: POOL_ID_DEFAULT,
-            salt: POOL_ID_DEFAULT,
+            salt,
             targetBinding: 0,
             size: 10,
         });
@@ -509,13 +439,15 @@ await respecfully(sir, 'Suite D: Revocation', async () => {
         mockMetaspace = new MockMetaspaceService(mockSpace);
 
         // Setup Identity WITH a Revocation Pool
+        const stdSalt = (await getUUID()).substring(0, 16);
+        const revokeSalt = (await getUUID()).substring(0, 16);
         const stdConfig = createStandardPoolConfig({
             id: POOL_ID_DEFAULT,
-            salt: POOL_ID_DEFAULT,
+            salt: stdSalt,
         });
         const revokeConfig = createRevocationPoolConfig({
             id: POOL_ID_REVOKE,
-            salt: POOL_ID_REVOKE,
+            salt: revokeSalt,
         }); // Special Config
 
         genesisKeystone = await service.genesis({
@@ -588,7 +520,8 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
 
     // Helper to generate a "Foreign" pool (e.g. from Bob)
     const createForeignPool = async (id: string, verbs: string[] = []): Promise<KeystoneChallengePool> => {
-        const config = createStandardPoolConfig({ id, salt: id });
+        const salt = (await getUUID()).substring(0, 16);
+        const config = createStandardPoolConfig({ id, salt });
         config.allowedVerbs = verbs;
 
         // We use the factory manually here to simulate Bob doing this offline
@@ -625,7 +558,8 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
         mockMetaspace = new MockMetaspaceService(mockSpace);
 
         // Alice Genesis: Standard pool (allows all verbs, including 'manage')
-        const config = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: POOL_ID_DEFAULT });
+        const salt = (await getUUID()).substring(0, 16);
+        const config = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt });
         aliceKeystone = await service.genesis({
             masterSecret: aliceSecret,
             configs: [config],
@@ -746,7 +680,8 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
 
     // Helper to simulate Bob creating a pool "offline" to give to Alice
     const createForeignPool = async (id: string, verbs: string[] = []): Promise<KeystoneChallengePool> => {
-        const config = createStandardPoolConfig({ id, salt: id });
+        const salt = (await getUUID()).substring(0, 16);
+        const config = createStandardPoolConfig({ id, salt });
         config.allowedVerbs = verbs;
 
         // We use the factory manually here to simulate Bob doing this on his own machine
@@ -783,9 +718,10 @@ await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
         mockMetaspace = new MockMetaspaceService(mockSpace);
 
         // Alice Genesis: Standard pool (allows all verbs, including 'manage')
+        const salt = (await getUUID()).substring(0, 16);
         const config = createStandardPoolConfig({
             id: POOL_ID_DEFAULT,
-            salt: POOL_ID_DEFAULT,
+            salt,
         });
         aliceKeystone = await service.genesis({
             masterSecret: aliceSecret,
@@ -899,27 +835,27 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
 
     const service = new KeystoneService_V1();
     const aliceSecret = "Alice_Deep_Inspect";
-    const salt = "granularity_pool";
+    const poolId = "granularity_pool";
 
     let mockSpace: MockIbGibSpace;
     let mockMetaspace: any;
     let genesisKeystone: KeystoneIbGib_V1;
-
     let signedKeystone: KeystoneIbGib_V1;
-
-    // We use a specific hybrid config to test exact selection logic
-    const hybridConfig = createStandardPoolConfig({
-        id: salt,
-        salt,
-        // 2 FIFO + 2 Random = 4 Total per sign
-        sequential: 2, random: 2, targetBinding: 0,
-        size: 20, // Small enough to track, large enough to be random
-    }) as KeystonePoolConfig_HashV1;
+    let hybridConfig: KeystonePoolConfig_HashV1;
 
     firstOfAll(sir, async () => {
         mockSpace = new MockIbGibSpace();
         mockMetaspace = new MockMetaspaceService(mockSpace);
 
+        const salt = (await getUUID()).substring(0, 16);
+        hybridConfig = createStandardPoolConfig({
+            id: poolId,
+            salt,
+            // 2 FIFO + 2 Random = 4 Total per sign
+            sequential: 2, random: 2, targetBinding: 0,
+            size: 20, // Small enough to track, large enough to be random
+        }) as KeystonePoolConfig_HashV1;
+
         genesisKeystone = await service.genesis({
             masterSecret: aliceSecret,
             configs: [hybridConfig],
@@ -949,7 +885,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
 
         await ifWe(sir, 'verifies the math manually (White-box Crypto Check)', async () => {
             const proof = signedKeystone.data!.proofs[0];
-            const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === salt)!;
+            const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === poolId)!;
 
             // We iterate every solution in the proof and MANUALLY verify the hash relationship
             // bypassing the Service's validation logic to ensure the raw math holds up.
@@ -978,7 +914,7 @@ await respecfully(sir, 'Suite F: Deep Inspection', async () => {
 
         await ifWe(sir, 'verifies FIFO logic (Deterministic Selection)', async () => {
             const proof = signedKeystone.data!.proofs[0];
-            const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === salt)!;
+            const poolSnapshot = genesisKeystone.data!.challengePools.find(p => p.id === poolId)!;
 
             // The first N keys in the pool should be the FIFO targets.
             // Assumption: Object.keys returns insertion order (Standard in modern JS engines)

package/src/keystone/keystone-types.mts

@@ -349,6 +349,12 @@ export interface KeystoneData_V1 extends IbGibData_V1 {
      * to the next frame's data during evolution.
      */
     frameDetails?: any;
+
+    /**
+     * Aggregated state of the Keystone identity up to this frame.
+     * Acts as a snapshot to avoid walking the entire timeline.
+     */
+    checkpointDetails?: any;
 }
 
 export interface KeystoneRel8ns_V1 extends IbGibRel8ns_V1 {

package/src/sync/README.md

@@ -20,7 +20,6 @@ Init -> Ack -> Delta(s) -> Conflict/Commit via "ping pong" exchange.
 
 1.  **Init**: Sender initiates sync.
     * Creates the `SyncSagaIbGib_V1` with an `Init` msg frame containing knowledge about domain ibgibs to sync.
-    * Optionally creates session keystone based off of Sender's primary keystone.
     * Wraps the saga ibgib in a `SyncSagaContextIbGib_V1` and passes to the `SyncPeer_V1`.
 2.  **Ack**: Receiver gets incoming `SyncSagaContextIbGib_V1` and passes to its `SyncSagaCoordinator`.
     * Handles the `Init` frame, comparing knowledge with Receiver's own status of each timeline/stone in domain ibgibs.
@@ -34,44 +33,11 @@ Init -> Ack -> Delta(s) -> Conflict/Commit via "ping pong" exchange.
       * `SyncPeer_V1.payloadIbGibsDomainReceived$` is an observable for the actual domain payload ibgibs transmitted.
       * So the a node sends domain payloads out in bulk to the `SyncPeer_V1`, receives the return saga ibgib with a manifest, but may have to wait for the observable to complete to actually process the ibgibs.
     * `Delta` frame can include `requests` (e.g., asking for missing conflict history).
-    * Once no deltas required, `Delta` frame sets `proposeCommit` flag. If the other has nothing to add, the session transitions to `Commit`.
+    * Once no deltas required, `Delta` frame sets `proposeCommit` flag. If the other has nothing to add, the saga transitions to `Commit`.
 4.  **Commit**: When receive `Delta` frame with `proposeCommit`,  should trigger the receiver of this to start its commit. If that is successful, it should return a `Commit` frame, which signals the commit was successful on their end. When this `Commit` frame is received, this end should not perform its own commit.
     * For local-only syncs, the `SyncPeer_V1` implementation is responsible for moving verified `ibGibs` from the temporary saga space to the durable/persistent domain space.
 *   From each endpoint's POV, the cleanup should remove the temp spaces used, in addition to any other required transaction cleanup (like closing any connections).
 
-### Session Identity (`useSessionIdentity`)
-
-The sync protocol can optionally generate an ephemeral Keystone Identity for the duration of the saga.
-
-**Purpose**: To allow secure, signed exchanges even if the Node doesn't have a long-lived identity, or to isolate the sync session security from master identity.
-
-**Current Status**:
-*   ✅ Session keystone creation implemented ([getSessionIdentity()](file:./sync-saga-coordinator.mts#L328-L362))
-*   ✅ Keystone passed via Init message ([initData.identity](file:./sync-saga-message/sync-saga-message-types.mts#L75))
-*   ⚠️ **Signature generation/verification: NOT yet implemented**
-*   ⚠️ **Per-frame proof creation: NOT yet implemented**
-
-**Usage**:
-```typescript
-const { done } = await coordinator.sync({
-  peer,
-  domainIbGibs: [timeline],
-  localSpace,
-  metaspace,
-  useSessionIdentity: true, // Default, but currently non-functional
-});
-```
-
-> [!CAUTION]
-> **🚧 Session identity is NOT working yet.** Tests explicitly set `useSessionIdentity: false` to avoid failures. See [sync-innerspace-dest-ahead-withid.respec.mts](file:./sync-innerspace-dest-ahead-withid.respec.mts) for the failing test case.
-
-**Authentication/Authorization Hooks**:
-
-Validation occurs in [SyncPeer_V1.witness()](file:./sync-peer/sync-peer-v1.mts#L129-L219):
-1. `validateContextAndSagaFrame()` - Intrinsic validation
-2. `authenticateContext()` - Verify identity (stub)
-3. `authorizeContext()` - Check permissions (stub)
-
 ### Conflict Resolution via Grafting
 
 > [!IMPORTANT]
@@ -110,58 +76,6 @@ See [graft-info-helpers.mts](file:./graft-info/graft-info-helpers.mts) for imple
 
 **Why**: Ensures atomic sync - either all data validates and commits, or none does.
 
-
-## 🔒 Security Considerations
-
-> [!WARNING]
-> Session identity is **currently non-functional**. The mitigations below describe the intended security model.
-
-### Attack Vectors & Mitigations
-
-| Attack Vector | Description | Mitigation |
-|---------------|-------------|------------|
-| **MITM Replay** | Attacker replays captured saga frames | • Frame signatures include timestamp<br>• Freshness checks reject old frames<br>• Challenge depletion prevents reuse<br>• sagaId deduplication |
-| **Session Fixation** | Attacker pre-generates session keystone | • Session secret derived via KDF (strategy in keystone metadata)<br>• `sessionSecret = KDF(masterSecret, sagaId, strategy)` |
-| **Identity Spoofing** | Impersonation via fake session keystone | • Session keystone includes `derivedFrom` master address<br>• Receiver validates master keystone is known/trusted |
-| **Challenge Grinding** | Brute-force challenge solutions for target binding | • Hash pre-imaging computationally infeasible<br>• Stochastic selection adds randomness |
-| **DoS (Pool Exhaustion)** | Excessive syncs deplete challenge pools | • Top-up replenishment refills challenges<br>• Rate limiting per identity<br>• Pool separation for critical ops |
-| **Saga Hijacking** | Mid-flight frame injection | • All frames signed with session keystone<br>• `past` rel8n creates tamper-evident chain |
-
-### Cryptographic Primitives
-
-*   **Hash Function**: SHA-256 (content addressing, challenge generation)
-*   **Proof System**: Hash-reveal protocol (`hash-reveal-v1`)
-*   **Binding**: Target address → hex bucket → challenge selection
-*   **Entropy**: Stochastic challenge selection (anti-grinding)
-
-### Trust Model
-
-**Session Keystones**:
-- Ephemeral identity per sync saga
-- Derived from master keystone + `sagaId`
-- Validates via proof-of-work (solving challenges)
-- Post-hoc audit trail: master can prove session authorship
-
-**Propagation**:
-- Sync does NOT rely on global PKI or certificate authorities
-- Trust propagates through sync sessions (Alice syncs with Bob → Bob witnesses Alice's keystone)
-- Revocation propagates same way (Alice revokes → syncs revocation to Bob → Bob sees revoked timeline)
-
-**Threat Boundaries**:
-- ✅ Protects against: MITM replay, impersonation, frame tampering
-- ⚠️ Does NOT protect against: Compromised endpoint (live memory access during active session)
-- ⚠️ Master secrets: Raw secrets should NOT stored; keystones master secrets to keystones should be derived secrets via key stretching passwords. raw secret files of course can drive these passwords and must be protected
-- ⚠️ Transport security: Use TLS for network layer encryption (ibgib protocol provides authentication/integrity, not confidentiality)
-
-### Best Practices
-
-1. **Master Secret Protection**: Store master secrets in secure enclaves/keychains
-2. **Session Lifetime**: Limit saga duration, revoke sessions post-completion
-3. **Rate Limiting**: Implement per-identity sync rate limits
-4. **Freshness**: Reject frames older than 60 seconds
-5. **Audit Logs**: Persist saga timelines for post-hoc validation (saga timelines are ibgibs, so integrity is built-in via content addressing)
-6. **TLS**: Always use TLS for network transport (defense-in-depth)
-
 ## 📚 Documentation
 *   **[Architecture](./docs/architecture.md)**: Detailed design of the Saga Protocol, State Machine, and Smart Diff logic.
 *   **[Testing & Verification](./docs/testing.md)**: Test strategy, verification matrix, and comprehensive testing guidelines.
@@ -174,3 +88,4 @@ See [graft-info-helpers.mts](file:./graft-info/graft-info-helpers.mts) for imple
 
 ## Verification
 We rely on rigorous In-Memory Simulation (`InnerSpace`) to verify complex graph scenarios. See **[Verification](./docs/verification.md)** for the full status.
+

package/src/sync/docs/architecture.md

@@ -21,7 +21,7 @@ The `SyncSagaCoordinator` drives a Finite State Machine (FSM) via the `handleSag
 ### 2.1 The Ping-Pong Flow
 
 1.  **Start (Initiator)**:
-    *   Initiator (Alice) calls `startSaga`.
+    *   Initiator (Alice) calls `sync`.
     *   Generates `Init` frame containing her `KnowledgeMap` and `Mode` (Push/Pull/Sync).
     *   Sends `Init` to Bob.
 
@@ -42,7 +42,7 @@ The `SyncSagaCoordinator` drives a Finite State Machine (FSM) via the `handleSag
 
 4.  **Convergence (`handleDeltaFrame`)**:
     *   Bob receives `Delta`.
-    *   **Verifies**: Checks content-address hashes (`ib` vs `gib`). ⚠️ Keystone signature verification pending.
+    *   **Verifies**: Checks content-address hashes.
     *   **Merges**: Puts data into his local space.
     *   Bob sends `Commit` frame.
 
@@ -55,7 +55,7 @@ The `SyncSagaCoordinator` drives a Finite State Machine (FSM) via the `handleSag
 ### 3.1 SyncSagaMessage
 All frames are `SyncIbGib`s carrying specific data payloads.
 
-*   `sagaId`: Unique UUID for the session.
+*   `sagaId`: Unique UUID for the duration of this exchange.
 *   `stage`: `init` | `ack` | `delta` | `commit` | `conflict`.
 *   `knowledgeMap`: `{ [tjpAddr]: [tipAddr, ...ancestors] }`.
 
@@ -65,5 +65,26 @@ The protocol supports two types of data:
 *   **Stones (Constants)**: Immutable data without a history (e.g., Code lists, Configs). Syncing involves simple existence checks.
 
 ## 4. Security & Identity
-*   **Session Keystone**: Each Saga can optionally generate an ephemeral identity to sign frames, linked to a master identity. ⚠️ **Currently non-functional** - see [README Session Identity section](file:../README.md#session-identity-usesessionidentity) for status.
-*   **Trust Chain**: Each frame points to the previous one (`past` rel8n), creating a hash-linked chain of custody.
+
+See [Security](./security.md) documentation.
+
+> [!WARNING]
+> ## 5. Sync Storage & Persistence Rules (Critical Security)
+>
+> Knowing **when** to put **what** ibgib frames into **which** space is a high-priority security concern. The sync algorithm must balance maintaining a robust audit trail with protecting durable spaces from unauthorized pollution. Always follow these rules:
+>
+> ### Rule 1: Saga/Control Audit Trail (Immediate Persistence)
+> We need an audit trail of the sync saga itself (including context and authentication info).
+> * The initial session keystone (or any valid evolution performed locally) and saga control ibgibs are trusted because *we* just generated them.
+> * Persist these immediately in the **local durable space** (and possibly the local temporary space if needed for transit) so they are available for validation and auditing.
+>
+> ### Rule 2: Domain IbGibs (Deferred Persistence)
+> We do NOT persist *any* domain ibgibs (e.g., user payloads) into the durable space before the `commit` phase of the sync process.
+> * Domain ibgibs must be routed to the **tempSpace** during the `delta` or `ack` phases.
+> * The `commit` phase acts as the transaction boundary. By waiting for the commit, we avoid polluting durable spaces on error, preventing the need for complex rollbacks.
+>
+> ### Rule 3: Validate First, Store Second
+> We never chance storing intrinsically invalid ibgibs.
+> * **First step:** Intrinsically validate ibgibs (hashes, basic structure).
+> * **Second step:** Perform AuthN/AuthZ checks (using the session keystone).
+> * **Final step:** Once verified, saga "control" ibgibs (which only contain "soft" links to domain ibgibs) can be safely persisted to durable spaces.

package/src/sync/docs/security.md

@@ -0,0 +1,176 @@
+# Ibgib Sync Security
+
+We use ibgib's unique Merkle-DAG-based protocol and innovative "keystone" construct (see keystone [README.md](../../keystone/README.md) and other [docs](../../keystone/docs/)) to maximize security while minimizing surface area (code).
+
+## Core Concepts
+
+* **Domain Keystone (I)**: The primary, long-lived identity keystone representing the data owner (e.g., Alice). This dictates high-level access and is registered with a domain provider (e.g., Space-Gib as an initial reference implementation).
+* **Session Keystone (S)**: An ephemeral, short-lived keystone generated locally by the Sender explicitly for a single sync session.
+* **Target Domain (X)**: The specific ibgib timeline or payload that is the subject of the sync.
+* **Sovereign Broker (Receiver)**: The domain provider acts as a passive, high-integrity validator. It does not generate or sign sync frames with its own session identity; it relies entirely on the Sender's cryptographic proofs to authorize actions. While we may treat the provider as "honest" practically, it is ultimately a sovereign entity over its data, and its "honesty" is driven by long-term self-interest.
+
+## Development Nuances & Implementation TODOs
+
+This section serves as a working scratchpad to capture specific code-level nuances, terminology standardization, and pending tasks before jumping into implementation.
+
+### ✅ Agreed: Secret Naming — `senderSecret` & `sessionSecret`
+
+* **`senderSecret`**: The master secret corresponding to `senderIdentity`. Drives the KDF to produce the session secret. Replaces the old `nonSessionSecret` / `identitySecret` / `domainSecret` names.
+* **`sessionSecret`**: Deterministically derived via `KDF(senderSecret, sagaId)`. Ephemeral and saga-specific. Used only within `establishSessionIdentity` to create the session keystone genesis.
+* *Rationale*: `sender` pairs naturally with `senderIdentity`; `session` pairs naturally with `sessionIdentity`.
+
+### ✅ Agreed: Identity Naming — `senderIdentity` & `sessionIdentity`
+
+* **`senderIdentity`**: The long-lived Domain Keystone (I) representing the Sender (Alice). Optional — a sync can run with just a `domainSecret` and no named identity.
+  * Using `senderIdentity` (not `domainIdentity` or `primaryIdentity`) because "domain" becomes ambiguous when Bob eventually has his own domain identity in a future symmetric model.
+* **`sessionIdentity`**: The ephemeral keystone (S) generated per-saga. Used consistently as both:
+  * A **param/property name** (e.g., `peer.sessionIdentity`, `createSessionIdentity()`).
+  * A **rel8n name** on both the sync saga ibgib and the context ibgib (e.g., `syncSagaIbGib.rel8ns.sessionIdentity`, `contextIbGib.rel8ns.sessionIdentity`).
+
+### ✅ Agreed: Identity Hard-linking Strategy
+
+* **Sync Saga Frame** (`ibgib.data`, soft-link):
+  * `data` should record identity details as soft references (addresses in `ibgib.data`, not hard-linked `ibgib.rel8ns`):
+    * `senderIdentity` TJP addr.
+    * The exact `senderIdentity` frame addr that signed/authorized the session (i.e., the new frame post-`establishSessionIdentity`).
+    * `sessionIdentity` TJP addr.
+  * No hard-link (`rel8ns`) to `sessionIdentity` from the sync saga ibgib.
+* **Context IbGib** (`ibgib.rel8ns`, hard-link):
+  * `rel8ns.sessionIdentity` hard-links to the **previous** session keystone frame (the frame *before* the current signing step). This is the "point forward, sign backward" pattern: the signed (evolved) keystone's claim targets *this context's addr*, so the context can only reference the *prior* frame.
+  * The `signedSessionKeystone` property on the context carries the **newly evolved** frame (the current turn's signature).
+  * **No transition pool**: The prior symmetric "transition pool" (for the receiver's signing turn) is eliminated. Only the Sender signs.
+  * **Sovereign Broker response**: The Receiver includes the *same, unevolved* `sessionIdentity` addr in its response context's `rel8ns.sessionIdentity` — it does not evolve the keystone.
+
+### ✅ Agreed: Session Keystone Pool Configuration
+
+The session keystone has **two dedicated pools**, each with a matching `poolId` and `verb`:
+
+* **`connect` pool** (`poolId: "connect"`, `verb: "connect"`):
+  * Used exclusively during `peer.connect()` — the in-band WebSocket challenge/response handshake.
+  * The receiver issues challenges from this pool; the sender solves them to prove possession of S.
+* **`sync` pool** (`poolId: "sync"`, `verb: "sync"`):
+  * Used to sign each outgoing context frame during the sync ping-pong (Init, Ack, Delta, Commit turns).
+  * Pool separation is intentional — the `connect` handshake and per-turn signing are distinct operations with distinct lifetimes.
+* [ ] Add `"connect"` and `"sync"` verbs to `keystone-constants.mts`.
+* [ ] Create standard pool config factories for both in [`keystone-config-builder.mts`](../../keystone/keystone-config-builder.mts).
+
+Note: The `senderIdentity` Domain Keystone also uses the `"sync"` verb in its claim when it signs/authorizes the session keystone genesis during `establishSessionIdentity`.
+
+### ✅ Agreed: `establishSessionIdentity` — Pre-Connect Phase
+
+A new `establishSessionIdentity` method on the sync peer base class is the **mandatory first step** before `connect`. It encapsulates:
+
+1. **Generate session keystone**: `sessionIdentity` genesis (S^Stjp) is created locally from `KDF(senderSecret, sagaId)`. The genesis includes metadata about `senderIdentity` TJP and the target domain.
+2. **Sign `senderIdentity`**: The Sender signs their own `senderIdentity` keystone with a `sync` claim targeting `S^Stjp`. The result (`newSenderIdentity`) is the evolved sender frame that proves delegation. The name `newSenderIdentity` is **only** used within `establishSessionIdentity` and its helper — after this method returns, it becomes the active `senderIdentity`.
+3. **Post to domain provider**: Both `newSenderIdentity` and `sessionIdentity` genesis are transmitted to the Receiver via a pre-connect API call (cf. `putEvolveKeystone` in `dev-tools.mts`).
+4. **Receiver validates**: The Receiver independently loads the **latest known tip** of `I^Itjp` from its own registry (never trusting `newSenderIdentity.rel8ns.past`). It validates the evolution and, if authorized, stores both keystones in the domain.
+5. **After this point**: `senderIdentity` IS the new frame. The session keystone takes over authorization for all subsequent sync turns.
+
+### ✅ Agreed: Per-Turn Transmission Protocol
+
+* **Sender → Receiver (each turn)**: Only the **current evolved frame of `sessionIdentity`** (S) is transmitted. `senderIdentity` is never re-transmitted after `establishSessionIdentity`.
+* **Receiver validation (each turn)**: The Receiver independently loads the latest `senderIdentity` tip from its domain registry, finds the `S^Stjp` addr from the `sync` claim within it, loads the known session keystone graph, and validates the incoming evolved S frame against it.
+  * This is possible on every turn because `establishSessionIdentity` guarantees the domain and `I^Itjp` already exist on the Receiver.
+* **Receiver → Sender (each turn)**: The Receiver's response context echoes the same (unevolved) `sessionIdentity` addr — it never produces a new keystone evolution.
+
+### 🔲 Pending: `authenticateContext` Placement
+
+The receiver-side validation that runs on each incoming context has two steps:
+1. **Transition validity**: Replay the session keystone evolution — verify `data.n` is sequential, challenge solutions are valid, pool not exhausted, etc.
+2. **Target binding**: Verify that the incoming `signedSessionIdentity`'s proof actually targets *this* context's exact address (`proof.claim.target === contextAddr`).
+
+**Open**: Where does this code live?
+* **On the sync peer** (e.g., as `peer.authenticateContext(...)`): the peer already knows its local durable space, which is needed to load the latest `senderIdentity` tip. This makes the tip-lookup natural.
+* **As a pure helper function** (`sync-peer-helpers.mts`): would need the durable space passed as a parameter (plus whatever else the tip-lookup requires).
+
+The peer placement is currently preferred since it co-locates the space knowledge with the validation logic. Finalize during implementation.
+
+### ✅ Agreed: `KeystoneService_V1` — No Injection Needed
+
+`KeystoneService_V1` is stateless. It can be `new`-ed on demand wherever validation or signing is needed. There is no need to pass it as a constructor parameter or inject it into `authenticateContext` or any related helper. Just instantiate inline.
+
+### ✅ Agreed: Context Property — `signedSessionIdentity`
+
+The context ibgib carries the newly evolved `sessionIdentity` frame in a property named **`signedSessionIdentity`** (replacing the old `signedSessionKeystone`).
+
+Context ibgib now has a clean, consistent pair:
+* `rel8ns.sessionIdentity` → addr of the **previous** frame (before signing this turn)
+* `signedSessionIdentity` → the **newly evolved** frame (current turn's cryptographic proof)
+
+
+
+## High Level Authorization Flow
+
+1. [ ] **`establishSessionIdentity`** *(new pre-connect phase)*:
+   [ ] * Sender locally generates `sessionIdentity` (S) and signs `senderIdentity` (I → I1) with a `sync` claim targeting `S^Stjp`.
+   [ ] * Both keystones are posted to the domain provider. Receiver validates the evolution against its own known tip of `I^Itjp` and stores them if authorized.
+2. [ ] **`peer.connect()`** *(transport handshake)*:
+   [ ] * Sender opens the transport channel (e.g., WebSocket).
+   [ ] * Receiver issues challenges from S's **`connect` pool**.
+   [ ] * Sender solves and returns proof-of-possession. Session is authorized.
+3. [ ] **Asymmetric Sync (Ping-Pong)**:
+   [ ] * Sender signs all outgoing contexts (Init, Ack, Delta, Commit) using S's **`sync` pool**, evolving S each turn.
+   [ ] * Only the latest evolved S frame is transmitted per turn — never `senderIdentity`.
+   [ ] * Receiver validates by independently loading `I^Itjp`, tracing to `S^Stjp`, and verifying the incoming frame.
+   [ ] * Receiver responds with unsigned contexts (same S addr echoed, no new evolution).
+
+
+## Attack Vectors & Mitigations
+
+| Attack Vector | Description | Mitigation |
+|---------------|-------------|------------|
+| **MITM Replay** | Attacker replays captured saga frames | • Frame signatures include timestamp<br>• Freshness checks reject old frames<br>• Challenge depletion prevents reuse<br>• sagaId deduplication |
+| **Session Fixation** | Attacker pre-generates session keystone | • Session secret derived via KDF (strategy in keystone metadata)<br>• `sessionSecret = KDF(masterSecret, sagaId, strategy)` |
+| **Identity Spoofing** | Impersonation via fake session keystone | • Session keystone includes `derivedFrom` master address<br>• Receiver validates master keystone is known/trusted |
+| **Challenge Grinding** | Brute-force challenge solutions for target binding | • Hash pre-imaging computationally infeasible<br>• Stochastic selection adds randomness |
+| **DoS (Pool Exhaustion)** | Excessive syncs deplete challenge pools | • Top-up replenishment refills challenges<br>• Rate limiting per identity<br>• Pool separation for critical ops |
+| **Saga Hijacking** | Mid-flight frame injection | • All frames signed with session keystone<br>• `past` rel8n creates tamper-evident chain |
+
+## Trust Model
+
+**Asymmetric Identity (Domain-Based Authorization)**:
+- **Sender Signs**: The Sender is responsible for cryptographically signing all requests using their ephemeral Session Keystone.
+- **Receiver Validates**: The Receiver acts strictly as an "Honest Broker". It validates the Sender's proofs and domain boundaries but does not maintain or sign a symmetric session identity.
+- **Delegated Authority**: Trust is explicitly delegated from a Domain Keystone (I) to a Session Keystone (S) via a `sync` claim evolution.
+
+**Session Keystones**:
+- Ephemeral identity per sync saga.
+- Secret derived via `KDF(senderSecret, sagaId)`.
+- Contains two isolated pools: `connect` (for transport handshake) and `sync` (for per-turn frame signing).
+- Validates via proof-of-work (solving challenges from the appropriate pool).
+
+**Propagation**:
+- Sync does NOT rely on global PKI or certificate authorities.
+- Trust propagates through sync sessions (Alice syncs with Bob &rarr; Bob witnesses Alice's keystone).
+- Revocation propagates same way (Alice revokes → syncs revocation to Bob → Bob sees revoked timeline)
+
+**Threat Boundaries**:
+- ✅ Protects against: MITM replay, impersonation, frame tampering
+- ⚠️ Does NOT protect against: Compromised endpoint (live memory access during active session)
+- ⚠️ Master secrets: Raw secrets should NOT stored; keystones master secrets to keystones should be derived secrets via key stretching passwords. raw secret files of course can drive these passwords and must be protected
+- ⚠️ Transport security: Use TLS for network layer encryption (ibgib protocol provides authentication/integrity, not confidentiality)
+
+## Best Practices
+
+1. **Master Secret Protection**: Store master secrets in secure enclaves/keychains
+2. **Session Lifetime**: Limit saga duration, revoke sessions post-completion
+3. **Rate Limiting**: Implement per-identity sync rate limits
+4. **Freshness**: Reject frames older than 60 seconds
+5. **Audit Logs**: Persist saga timelines for post-hoc validation (saga timelines are ibgibs, so integrity is built-in via content addressing)
+6. **TLS**: Always use TLS for network transport (defense-in-depth)
+
+## ❓ Open Questions
+
+### Payload Scope Validation: Can the Protocol Police What ibGibs Are Transmitted?
+
+**Question**: During a sync session authorized by session substone S (itself authorized by domain keystone I with `claim.target = S^Stjp` and sync subject `X^X10.Xtjp`), should the server validate that all Delta payload ibgibs are genuinely related to X's timeline? Or is it sufficient that they arrive under a valid substone?
+
+**Context**: The substone's `frameDetails` records both the parent identity `I^Itjp` and the sync subject `X^X10.Xtjp`. In theory the server could walk the dependency graph of each incoming Delta payload and confirm every ibgib is either:
+- A control ibgib (sync saga, context, substone frames), or
+- Part of the dependency graph rooted at some frame of X's timeline (`X^Xtjp`)
+
+**Problem**: This check may not be enforceable at the protocol layer. A client who controls the keystone (has the master secret) could always evolve X's timeline to hard-link any arbitrary ibgib, and that ibgib would then pass the "is in X's dependency graph" check. So the constraint can be trivially bypassed by the legitimate key-holder, making it only useful against *illegitimate* actors — who are already blocked by the keystone proof requirement.
+
+**Current position**: This is likely a **higher-layer business rule** rather than a sync protocol concern. The sync protocol's job is to ensure the session is cryptographically authorized (via keystone proofs). What is stored under an authorized session is the domain owner's responsibility. Enforcement of content policies (e.g., "only ibgibs of type X are allowed") belongs in the server's `authorizeContext` hook, not in the core sync coordinator.
+
+**Tracked in**: `space-gib.sync-walkthrough.md`