@ibgib/core-gib 0.1.8 → 0.1.10

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

@@ -2,19 +2,17 @@ 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 { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { clone, hash } 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';
-// import { MetaspaceService, } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
-// import { Metaspace_Innerspace } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-innerspace/metaspace-innerspace.mjs';
-// import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
 import { KeystoneStrategyFactory } from './strategy/keystone-strategy-factory.mjs';
-import { KeystoneClaim, KeystoneIbGib_V1, KeystonePoolConfig_HashV1 } from './keystone-types.mjs';
+import { KeystoneChallengePool, KeystoneClaim, KeystoneIbGib_V1, KeystonePoolConfig_HashV1 } from './keystone-types.mjs';
 import { createRevocationPoolConfig, createStandardPoolConfig } from './keystone-config-builder.mjs';
-import { POOL_ID_DEFAULT, POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE } from './keystone-constants.mjs';
+import { POOL_ID_DEFAULT, POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_VERB_MANAGE } from './keystone-constants.mjs';
 import { KeystoneService_V1 } from './keystone-service-v1.mjs';
+import { addToBindingMap } from './keystone-helpers.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -202,7 +200,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Derivation Logic', async () => {
 
-        await ifWeMight(sir, 'derivePoolSecret with same inputs returns same output', async () => {
+        await ifWe(sir, 'derivePoolSecret with same inputs returns same output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -212,7 +210,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secret length').isGonnaBeTruthy();
         });
 
-        await ifWeMight(sir, 'derivePoolSecret with different master secret returns different output', async () => {
+        await ifWe(sir, 'derivePoolSecret with different master secret returns different output', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
 
             const secretA = await strategy.derivePoolSecret({ masterSecret });
@@ -221,7 +219,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, secretA).asTo('secrets differ').not.willEqual(secretB);
         });
 
-        await ifWeMight(sir, 'derivePoolSecret with different salt returns different output', async () => {
+        await ifWe(sir, 'derivePoolSecret with different salt returns different output', async () => {
             // Modify salt in a copy of config
             const configB = { ...config, salt: "OtherPool" };
             const strategyA = KeystoneStrategyFactory.create({ config });
@@ -236,7 +234,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
 
     await respecfully(sir, 'Challenge/Solution Logic', async () => {
 
-        await ifWeMight(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
+        await ifWe(sir, 'generateSolution -> generateChallenge -> validateSolution loop works', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "a3ff7843552870fc28bef2b"; // arbitrary random challengeId
@@ -255,7 +253,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('valid pair should pass').isGonnaBeTrue();
         });
 
-        await ifWeMight(sir, 'validateSolution fails for mismatched values', async () => {
+        await ifWe(sir, 'validateSolution fails for mismatched values', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
             const challengeId = "8c994f3ed598f150e25513"; // arbitrary random challengeId
@@ -271,7 +269,7 @@ await respecfully(sir, 'Suite A: Strategy Vectors (HashRevealV1)', async () => {
             iReckon(sir, isValid).asTo('tampered solution should fail').isGonnaBeFalse();
         });
 
-        await ifWeMight(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
+        await ifWe(sir, 'validateSolution fails for mismatched challenge hashes', async () => {
             const strategy = KeystoneStrategyFactory.create({ config });
             const poolSecret = await strategy.derivePoolSecret({ masterSecret });
 
@@ -312,7 +310,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Genesis', async () => {
-        await ifWeMight(sir, 'creates a valid genesis frame and persists it', async () => {
+        await ifWe(sir, 'creates a valid genesis frame and persists it', async () => {
             const config = createStandardPoolConfig(POOL_ID_DEFAULT);
 
             genesisKeystone = await service.genesis({
@@ -340,7 +338,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Signing (Evolution)', async () => {
-        await ifWeMight(sir, 'evolves the keystone with a valid proof', async () => {
+        await ifWe(sir, 'evolves the keystone with a valid proof', async () => {
             const claim: Partial<KeystoneClaim> = {
                 target: "comment 123^gib",
                 verb: "post"
@@ -370,7 +368,7 @@ await respecfully(sir, 'Suite B: Service Lifecycle', async () => {
     });
 
     await respecfully(sir, 'Validation', async () => {
-        await ifWeMight(sir, 'validates the genesis->signed transition', async () => {
+        await ifWe(sir, 'validates the genesis->signed transition', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: signedKeystone,
@@ -413,7 +411,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Wrong Secret (Forgery)', async () => {
-        await ifWeMight(sir, 'prevents creation of forged frames', async () => {
+        await ifWe(sir, 'prevents creation of forged frames', async () => {
             const claim: Partial<KeystoneClaim> = { target: "comment 123^gib", verb: "post" };
 
             let errorCaught = false;
@@ -442,7 +440,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
     });
 
     await respecfully(sir, 'Policy Violation (Restricted Verbs)', async () => {
-        await ifWeMight(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
+        await ifWe(sir, 'throws error if signing forbidden verb with restricted pool', async () => {
             // Create a specific restricted pool config manually
             const restrictedPoolId = "read_only_pool";
             const restrictedConfig = createStandardPoolConfig(restrictedPoolId);
@@ -483,7 +481,7 @@ await respecfully(sir, 'Suite C: Security Vectors', async () => {
 // SUITE D: REVOCATION
 // ===========================================================================
 
-await respecfullyDear(sir, 'Suite D: Revocation', async () => {
+await respecfully(sir, 'Suite D: Revocation', async () => {
 
     const service = new KeystoneService_V1();
     const masterSecret = "AliceSecret_RevokeTest";
@@ -511,7 +509,7 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
     await respecfully(sir, 'Revoke Lifecycle', async () => {
         let revokedKeystone: KeystoneIbGib_V1;
 
-        await ifWeMight(sir, 'successfully creates a revocation frame', async () => {
+        await ifWe(sir, 'successfully creates a revocation frame', async () => {
             revokedKeystone = await service.revoke({
                 latestKeystone: genesisKeystone,
                 masterSecret,
@@ -529,7 +527,7 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, data.revocationInfo!.proof.claim.verb).willEqual(KEYSTONE_VERB_REVOKE);
         });
 
-        await ifWeMight(sir, 'validates the revocation frame', async () => {
+        await ifWe(sir, 'validates the revocation frame', async () => {
             const errors = await service.validate({
                 prevIbGib: genesisKeystone,
                 currentIbGib: revokedKeystone!,
@@ -540,7 +538,7 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
             iReckon(sir, errors.length).asTo('no validation errors').willEqual(0);
         });
 
-        await ifWeMight(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
+        await ifWe(sir, 'consumed the revocation pool (Scorched Earth)', async () => {
             const data = revokedKeystone!.data!;
             const revokePool = data.challengePools.find(p => p.id === POOL_ID_REVOKE);
 
@@ -553,3 +551,468 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
         });
     });
 });
+
+// ===========================================================================
+// SUITE E: STRUCTURAL EVOLUTION (addPools)
+// ===========================================================================
+
+await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
+
+    const service = new KeystoneService_V1();
+    const aliceSecret = "Alice_Master_Key";
+    const bobSecret = "Bob_Foreign_Key";
+
+    let mockSpace: MockIbGibSpace;
+    let mockMetaspace: any;
+    let aliceKeystone: KeystoneIbGib_V1;
+
+    // Helper to generate a "Foreign" pool (e.g. from Bob)
+    const createForeignPool = async (id: string, verbs: string[] = []): Promise<KeystoneChallengePool> => {
+        const config = createStandardPoolConfig(id);
+        config.allowedVerbs = verbs;
+
+        // We use the factory manually here to simulate Bob doing this offline
+        const strategy = KeystoneStrategyFactory.create({ config });
+        const poolSecret = await strategy.derivePoolSecret({ masterSecret: bobSecret });
+        const challenges: { [id: string]: any } = {};
+        const bindingMap: { [char: string]: string[] } = {};
+
+        for (let i = 0; i < 10; i++) {
+            // Manually replicate ID gen for test
+            const raw = await hash({ s: `${config.salt}${Date.now()}${i}` });
+            const challengeId = raw.substring(0, 16);
+
+            const solution = await strategy.generateSolution({
+                poolSecret, poolId: config.salt, challengeId,
+            });
+            const challenge = await strategy.generateChallenge({ solution });
+            challenges[challengeId] = challenge;
+            addToBindingMap(bindingMap, challengeId);
+        }
+
+        return {
+            id,
+            config,
+            challenges,
+            bindingMap,
+            isForeign: true,
+            metadata: { owner: 'Bob' }
+        };
+    };
+
+    firstOfAll(sir, async () => {
+        mockSpace = new MockIbGibSpace();
+        mockMetaspace = new MockMetaspaceService(mockSpace);
+
+        // Alice Genesis: Standard pool (allows all verbs, including 'manage')
+        const config = createStandardPoolConfig(POOL_ID_DEFAULT);
+        aliceKeystone = await service.genesis({
+            masterSecret: aliceSecret,
+            configs: [config],
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+    });
+
+    await respecfully(sir, 'Happy Path', async () => {
+        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
+            const bobPool = await createForeignPool("pool_bob", ["post"]);
+
+            const updatedKeystone = await service.addPools({
+                latestKeystone: aliceKeystone,
+                masterSecret: aliceSecret,
+                newPools: [bobPool],
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            // 1. Verify new state
+            iReckon(sir, updatedKeystone).isGonnaBeTruthy();
+            const pools = updatedKeystone.data!.challengePools;
+            iReckon(sir, pools.length).asTo('pool count increased').willEqual(2);
+
+            const foundBob = pools.find(p => p.id === "pool_bob");
+            iReckon(sir, foundBob).asTo('bob pool exists').isGonnaBeTruthy();
+            iReckon(sir, foundBob!.isForeign).asTo('isForeign flag').isGonnaBeTrue();
+
+            // 2. Verify Proof
+            const proof = updatedKeystone.data!.proofs[0];
+            iReckon(sir, proof.claim.verb).asTo('proof verb').willEqual("manage");
+            // Alice signed this using HER pool (default), not Bob's
+            iReckon(sir, proof.solutions[0].poolId).willEqual(POOL_ID_DEFAULT);
+
+            // 3. Verify Validity
+            const errors = await service.validate({
+                prevIbGib: aliceKeystone,
+                currentIbGib: updatedKeystone,
+            });
+            iReckon(sir, errors.length).asTo('validation passed').willEqual(0);
+
+            // Update local ref for next tests
+            aliceKeystone = updatedKeystone;
+        });
+    });
+
+    await respecfully(sir, 'Permissions & Logic', async () => {
+        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
+            // 1. Create a restricted keystone
+            const restrictedConfig = createStandardPoolConfig("read_only");
+            restrictedConfig.allowedVerbs = ['read']; // No 'manage'
+
+            const restrictedKeystone = await service.genesis({
+                masterSecret: aliceSecret,
+                configs: [restrictedConfig],
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            const newPool = await createForeignPool("pool_test");
+            let errorCaught = false;
+
+            try {
+                await service.addPools({
+                    latestKeystone: restrictedKeystone,
+                    masterSecret: aliceSecret,
+                    newPools: [newPool],
+                    metaspace: mockMetaspace,
+                    space: mockSpace as any,
+                });
+            } catch (e: any) {
+                errorCaught = true;
+                // Should fail in resolveTargetPool or addPools logic
+                // console.log("Caught expected error:", e.message);
+            }
+
+            iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
+        });
+
+        await ifWe(sir, 'fails on ID collision', async () => {
+            // Try to add "pool_bob" again (it was added in Happy Path)
+            const duplicatePool = await createForeignPool("pool_bob");
+
+            let errorCaught = false;
+            try {
+                await service.addPools({
+                    latestKeystone: aliceKeystone, // This already has pool_bob
+                    masterSecret: aliceSecret,
+                    newPools: [duplicatePool],
+                    metaspace: mockMetaspace,
+                    space: mockSpace as any,
+                });
+            } catch (e: any) {
+                errorCaught = true;
+                iReckon(sir, e.message).includes("ID collision");
+            }
+
+            iReckon(sir, errorCaught).asTo('collision detected').isGonnaBeTrue();
+        });
+    });
+});
+
+// ===========================================================================
+// SUITE E: STRUCTURAL EVOLUTION (addPools)
+// ===========================================================================
+
+await respecfully(sir, 'Suite E: Structural Evolution (addPools)', async () => {
+
+    const service = new KeystoneService_V1();
+    const aliceSecret = "Alice_Master_Key";
+    const bobSecret = "Bob_Foreign_Key";
+
+    let mockSpace: MockIbGibSpace;
+    let mockMetaspace: any;
+    let aliceKeystone: KeystoneIbGib_V1;
+
+    // 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);
+        config.allowedVerbs = verbs;
+
+        // We use the factory manually here to simulate Bob doing this on his own machine
+        const strategy = KeystoneStrategyFactory.create({ config });
+        const poolSecret = await strategy.derivePoolSecret({ masterSecret: bobSecret });
+        const challenges: { [id: string]: any } = {};
+        const bindingMap: { [char: string]: string[] } = {};
+
+        // Generate a small set of challenges
+        for (let i = 0; i < 10; i++) {
+            const raw = await hash({ s: `${config.salt}${Date.now()}${i}` });
+            const challengeId = raw.substring(0, 16);
+
+            const solution = await strategy.generateSolution({
+                poolSecret, poolId: config.salt, challengeId,
+            });
+            const challenge = await strategy.generateChallenge({ solution });
+            challenges[challengeId] = challenge;
+            addToBindingMap(bindingMap, challengeId);
+        }
+
+        return {
+            id,
+            config,
+            challenges,
+            bindingMap,
+            isForeign: true,
+            metadata: { owner: 'Bob', role: 'Delegate' }
+        };
+    };
+
+    firstOfAll(sir, async () => {
+        mockSpace = new MockIbGibSpace();
+        mockMetaspace = new MockMetaspaceService(mockSpace);
+
+        // Alice Genesis: Standard pool (allows all verbs, including 'manage')
+        const config = createStandardPoolConfig(POOL_ID_DEFAULT);
+        aliceKeystone = await service.genesis({
+            masterSecret: aliceSecret,
+            configs: [config],
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+    });
+
+    await respecfully(sir, 'Happy Path', async () => {
+        await ifWe(sir, 'authorizes and adds a foreign pool', async () => {
+            const bobPool = await createForeignPool("pool_bob", ["post"]);
+
+            const updatedKeystone = await service.addPools({
+                latestKeystone: aliceKeystone,
+                masterSecret: aliceSecret,
+                newPools: [bobPool],
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            // 1. Verify new state
+            iReckon(sir, updatedKeystone).isGonnaBeTruthy();
+            const pools = updatedKeystone.data!.challengePools;
+            iReckon(sir, pools.length).asTo('pool count increased').willEqual(2);
+
+            const foundBob = pools.find(p => p.id === "pool_bob");
+            iReckon(sir, foundBob).asTo('bob pool exists').isGonnaBeTruthy();
+            iReckon(sir, foundBob!.isForeign).asTo('isForeign flag').isGonnaBeTrue();
+
+            // 2. Verify Proof
+            const proof = updatedKeystone.data!.proofs[0];
+            iReckon(sir, proof.claim.verb).asTo('proof verb').willEqual(KEYSTONE_VERB_MANAGE);
+            // Alice signed this using HER pool (default), not Bob's
+            iReckon(sir, proof.solutions[0].poolId).willEqual(POOL_ID_DEFAULT);
+
+            // 3. Verify Validity
+            const errors = await service.validate({
+                prevIbGib: aliceKeystone,
+                currentIbGib: updatedKeystone,
+            });
+            iReckon(sir, errors.length).asTo('validation passed').willEqual(0);
+
+            // Update local ref for next tests
+            aliceKeystone = updatedKeystone;
+        });
+    });
+
+    await respecfully(sir, 'Permissions & Logic', async () => {
+        await ifWe(sir, 'fails if no pool allows "manage" verb', async () => {
+            // 1. Create a restricted keystone (read-only)
+            const restrictedConfig = createStandardPoolConfig("read_only");
+            restrictedConfig.allowedVerbs = ['read']; // No 'manage'
+
+            const restrictedKeystone = await service.genesis({
+                masterSecret: aliceSecret,
+                configs: [restrictedConfig],
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            const newPool = await createForeignPool("pool_test");
+            let errorCaught = false;
+
+            try {
+                await service.addPools({
+                    latestKeystone: restrictedKeystone,
+                    masterSecret: aliceSecret,
+                    newPools: [newPool],
+                    metaspace: mockMetaspace,
+                    space: mockSpace as any,
+                });
+            } catch (e: any) {
+                errorCaught = true;
+                // Optional: Check error message
+                // iReckon(sir, e.message).includes("No local pool found with 'manage'");
+            }
+
+            iReckon(sir, errorCaught).asTo('permission denied').isGonnaBeTrue();
+        });
+
+        await ifWe(sir, 'fails on ID collision', async () => {
+            // Try to add "pool_bob" again (it was added in Happy Path)
+            const duplicatePool = await createForeignPool("pool_bob");
+
+            let errorCaught = false;
+            try {
+                await service.addPools({
+                    latestKeystone: aliceKeystone, // This already has pool_bob
+                    masterSecret: aliceSecret,
+                    newPools: [duplicatePool],
+                    metaspace: mockMetaspace,
+                    space: mockSpace as any,
+                });
+            } catch (e: any) {
+                errorCaught = true;
+                iReckon(sir, e.message).includes("collision");
+            }
+
+            iReckon(sir, errorCaught).asTo('collision detected').isGonnaBeTrue();
+        });
+    });
+});
+
+// ===========================================================================
+// SUITE F: DEEP INSPECTION (Granularity & Serialization)
+// ===========================================================================
+
+await respecfully(sir, 'Suite F: Deep Inspection', async () => {
+
+    const service = new KeystoneService_V1();
+    const aliceSecret = "Alice_Deep_Inspect";
+    const salt = "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(salt) as KeystonePoolConfig_HashV1;
+    // 2 FIFO + 2 Random = 4 Total per sign
+    hybridConfig.behavior.selectSequentially = 2;
+    hybridConfig.behavior.selectRandomly = 2;
+    hybridConfig.behavior.size = 20; // Small enough to track, large enough to be random
+
+    firstOfAll(sir, async () => {
+        mockSpace = new MockIbGibSpace();
+        mockMetaspace = new MockMetaspaceService(mockSpace);
+
+        genesisKeystone = await service.genesis({
+            masterSecret: aliceSecret,
+            configs: [hybridConfig],
+            metaspace: mockMetaspace,
+            space: mockSpace as any,
+        });
+    });
+
+    await respecfully(sir, 'Proof Granularity & Math', async () => {
+
+        await ifWe(sir, 'generates exactly the expected number of solutions', async () => {
+            signedKeystone = await service.sign({
+                latestKeystone: genesisKeystone,
+                masterSecret: aliceSecret,
+                claim: { verb: "post", target: "data^gib" },
+                metaspace: mockMetaspace,
+                space: mockSpace as any,
+            });
+
+            const proofs = signedKeystone.data!.proofs;
+            iReckon(sir, proofs.length).asTo('proof count').willEqual(1);
+
+            const solutions = proofs[0].solutions;
+            // 2 Sequential + 2 Random = 4
+            iReckon(sir, solutions.length).asTo('solution count').willEqual(4);
+        });
+
+        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)!;
+
+            // 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.
+
+            for (const solution of proof.solutions) {
+                // 1. Find the challenge in the *Previous* frame (Genesis)
+                const challenge = poolSnapshot.challenges[solution.challengeId];
+
+                if (!challenge) {
+                    throw new Error(`Test Failure: Solution references ID ${solution.challengeId} which was not in Genesis pool.`);
+                }
+
+                // 2. Re-implement HashReveal V1 verification logic locally in the test
+                // Hash(Salt + Value + Salt)
+                // Note: rounds=1 in standard config
+                const indexSalt = solution.challengeId;
+                const calculatedHash = await hash({
+                    s: `${indexSalt}${solution.value}${indexSalt}`,
+                    algorithm: 'SHA-256'
+                });
+
+                // 3. Assert
+                iReckon(sir, calculatedHash).asTo(`Manual hash verification for ${solution.challengeId}`).willEqual(challenge.hash);
+            }
+        });
+
+        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)!;
+
+            // The first N keys in the pool should be the FIFO targets.
+            // Assumption: Object.keys returns insertion order (Standard in modern JS engines)
+            const allIds = Object.keys(poolSnapshot.challenges);
+            const expectedFifoIds = allIds.slice(0, 2);
+
+            const solvedIds = proof.solutions.map(s => s.challengeId);
+
+            // Check that our solution list *includes* the expected FIFO IDs
+            const hasFirst = solvedIds.includes(expectedFifoIds[0]);
+            const hasSecond = solvedIds.includes(expectedFifoIds[1]);
+
+            iReckon(sir, hasFirst).asTo(`Solution includes 1st FIFO ID (${expectedFifoIds[0]})`).isGonnaBeTrue();
+            iReckon(sir, hasSecond).asTo(`Solution includes 2nd FIFO ID (${expectedFifoIds[1]})`).isGonnaBeTrue();
+        });
+    });
+
+    await respecfully(sir, 'DTO & Serialization', async () => {
+
+        await ifWe(sir, 'survives a clone/JSON-cycle without corruption', async () => {
+            // 1. Create a DTO (simulate network transmission/storage)
+            // 'clone' does a JSON stringify/parse under the hood (usually) or structured clone.
+            const dto = clone(signedKeystone);
+
+            // 2. Structural checks
+            iReckon(sir, dto).asTo('dto exists').isGonnaBeTruthy();
+            iReckon(sir, dto.data).asTo('dto data').isGonnaBeTruthy();
+            iReckon(sir, dto.data!.proofs).asTo('dto proofs').isGonnaBeTruthy();
+
+            // 3. Functional check: Can the service validate this DTO?
+            // This ensures no prototypes or hidden properties were lost that the service depends on.
+            const errors = await service.validate({
+                prevIbGib: genesisKeystone,
+                currentIbGib: dto, // Passing the DTO, not the original object
+            });
+
+            iReckon(sir, errors.length).asTo('DTO validation errors').willEqual(0);
+        });
+
+        await ifWe(sir, 'ensures data contains no functions or circular refs', async () => {
+            // A crude but effective test: ensure JSON.stringify doesn't throw
+            // and the result is equal to the object (if we parsed it back).
+
+            const jsonStr = JSON.stringify(signedKeystone);
+            const parsed = JSON.parse(jsonStr);
+
+            // Compare specific deep fields
+            const originalSolution = signedKeystone.data!.proofs[0].solutions[0].value;
+            const parsedSolution = parsed.data.proofs[0].solutions[0].value;
+
+            iReckon(sir, parsedSolution).asTo('deep property survives stringify').willEqual(originalSolution);
+
+            // Ensure no extra properties were lost
+            // FIX: JSON.stringify removes keys with 'undefined' values. 
+            // We must filter the original keys to match this behavior for a fair comparison.
+            const origKeys = Object.keys(signedKeystone.data!)
+                .filter(k => (signedKeystone.data as any)[k] !== undefined);
+
+            const parsedKeys = Object.keys(parsed.data);
+            iReckon(sir, parsedKeys.length).asTo('key count matches').willEqual(origKeys.length);
+        });
+
+    });
+});

package/src/keystone/keystone-types.mts

@@ -217,6 +217,30 @@ export interface KeystoneChallengePool {
      * Note: A single ID may appear in multiple buckets (Coverage Strategy).
      */
     bindingMap: { [hexChar: string]: string[] };
+
+    /**
+     * If true, this pool's secrets are NOT derived from the Keystone's 
+     * primary Master Secret. They are held by an external entity.
+     * 
+     * ## intent
+     * 
+     * The driving use case for this is signing in with a server "super node"
+     * and giving that node the ability to sign on behalf of the user. This is a
+     * common pattern in SSO-type workflows.
+     */
+    isForeign?: boolean;
+
+    /**
+     * Arbitrary metadata for the wallet/user to identify the pool.
+     * e.g. { delegate: "PrimaryServer", purpose: "SSO" }
+     * 
+     * ## intent
+     * 
+     * The driving use case for this is signing in with a server "super node"
+     * and giving that node the ability to sign on behalf of the user. This is a
+     * common pattern in SSO-type workflows.
+     */
+    metadata?: any;
 }
 
 /**

package/src/sync/sync-constants.mts

@@ -0,0 +1,24 @@
+export const SYNC_ATOM = "sync";
+
+/**
+ * Protocol version string for V1.
+ */
+export const SYNC_PROTOCOL_V1 = "sync 1.0.0";
+
+export const SYNC_STAGE_INIT = "init";
+export const SYNC_STAGE_REQUEST = "request";
+export const SYNC_STAGE_DELTA = "delta";
+export const SYNC_STAGE_COMMIT = "commit";
+
+export type SyncStage =
+    | typeof SYNC_STAGE_INIT
+    | typeof SYNC_STAGE_REQUEST
+    | typeof SYNC_STAGE_DELTA
+    | typeof SYNC_STAGE_COMMIT;
+
+export const SyncStage = {
+    init: SYNC_STAGE_INIT,
+    request: SYNC_STAGE_REQUEST,
+    delta: SYNC_STAGE_DELTA,
+    commit: SYNC_STAGE_COMMIT,
+} as const;