@ibgib/core-gib 0.1.8 → 0.1.9

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;
 
@@ -553,3 +551,462 @@ await respecfullyDear(sir, 'Suite D: Revocation', async () => {
         });
     });
 });
+
+// ===========================================================================
+// SUITE E: STRUCTURAL EVOLUTION (addPools)
+// ===========================================================================
+
+await respecfullyDear(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 ifWeMight(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 ifWeMight(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 ifWeMight(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 respecfullyDear(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 ifWeMight(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 ifWeMight(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 ifWeMight(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 respecfullyDear(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;
+
+    // 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 () => {
+        let signedKeystone: KeystoneIbGib_V1;
+
+        await ifWeMight(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 ifWeMight(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 ifWeMight(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 ifWeMight(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 ifWeMight(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 (rudimentary check)
+    //         const origKeys = Object.keys(signedKeystone.data!);
+    //         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;
 }
 
 /**