@ibgib/core-gib 0.1.8 → 0.1.10

package/src/keystone/keystone-helpers.mts

@@ -2,10 +2,13 @@ import { extractErrorMsg, hash, pretty } from "@ibgib/helper-gib/dist/helpers/ut
 import { Ib, TransformResult } from "@ibgib/ts-gib/dist/types.mjs";
 import { getIbAndGib, getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
 import { validateIbGibIntrinsically } from "@ibgib/ts-gib/dist/V1/validate-helper.mjs";
+import { mut8 } from "@ibgib/ts-gib/dist/V1/transforms/mut8.mjs";
+import { Factory_V1 } from "@ibgib/ts-gib/dist/V1/factory.mjs";
+import { getGib } from "@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs";
 
 import { GLOBAL_LOG_A_LOT } from "../core-constants.mjs";
 import { KEYSTONE_ATOM } from "./keystone-constants.mjs";
-import { KeystoneData_V1, KeystoneIbGib_V1, KeystoneIbInfo_V1, KeystoneChallengePool, DeterministicResult, KeystoneProof, KeystonePoolConfig, KeystoneReplenishStrategy, KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES } from "./keystone-types.mjs";
+import { KeystoneData_V1, KeystoneIbGib_V1, KeystoneIbInfo_V1, KeystoneChallengePool, DeterministicResult, KeystoneProof, KeystonePoolConfig, KeystoneReplenishStrategy, KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES, KeystoneClaim, KeystoneSolution } from "./keystone-types.mjs";
 import { MetaspaceService } from "../witness/space/metaspace/metaspace-types.mjs";
 import { IbGibSpaceAny } from "../witness/space/space-base-v1.mjs";
 import { KeystoneStrategyFactory } from "./strategy/keystone-strategy-factory.mjs";
@@ -327,7 +330,7 @@ export function selectChallengeIds({
  * Generates an opaque, collision-resistant ID for a challenge.
  * atow (2025/12/22) - Hash(Salt + Timestamp + Index)
  */
-async function generateOpaqueChallengeId({
+export async function generateOpaqueChallengeId({
     salt,
     timestamp,
     index
@@ -431,6 +434,81 @@ export async function applyReplenishmentStrategy({
     }
 }
 
+/**
+ * High-level orchestration helper.
+ * 1. Instantiates Strategy.
+ * 2. Derives Secret.
+ * 3. Solves Challenges (Generates Solutions).
+ * 4. Replenishes Pool (Calculates the next state of ALL pools).
+ * 5. Constructs Proof.
+ * 
+ * @returns The resulting Proof and the full list of Next Pools.
+ */
+export async function solveAndReplenish({
+    targetPoolId,
+    prevPools,
+    masterSecret,
+    challengeIds,
+    claim,
+    requiredChallengeIds,
+}: {
+    /**
+     * The ID of the pool to use for signing.
+     */
+    targetPoolId: string;
+    /**
+     * The full list of pools from the previous Keystone frame.
+     * Required to reconstruct the full state for the next frame.
+     */
+    prevPools: KeystoneChallengePool[];
+    masterSecret: string;
+    challengeIds: string[];
+    claim: Partial<KeystoneClaim>;
+    requiredChallengeIds?: string[];
+}): Promise<{ proof: KeystoneProof, nextPools: KeystoneChallengePool[] }> {
+    const lc = `[solveAndReplenish]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... poolId: ${targetPoolId}, ids: ${challengeIds.length}`); }
+
+        const pool = prevPools.find(p => p.id === targetPoolId);
+        if (!pool) { throw new Error(`Target pool not found: ${targetPoolId} (E: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6)`); }
+
+        const strategy = KeystoneStrategyFactory.create({ config: pool.config });
+        const poolSecret = await strategy.derivePoolSecret({ masterSecret });
+        const solutions: KeystoneSolution[] = [];
+
+        // 1. Solve
+        for (const id of challengeIds) {
+            const solution = await strategy.generateSolution({
+                poolSecret, poolId: pool.id, challengeId: id,
+            });
+            solutions.push(solution);
+        }
+
+        // 2. Construct Proof
+        const proof: KeystoneProof = {
+            claim,
+            solutions,
+            requiredChallengeIds: (requiredChallengeIds && requiredChallengeIds.length > 0) ? requiredChallengeIds : undefined
+        };
+
+        // 3. Replenish
+        const nextPools = await applyReplenishmentStrategy({
+            prevPools,
+            targetPoolId: pool.id,
+            consumedIds: challengeIds,
+            masterSecret,
+            strategy,
+            config: pool.config
+        });
+
+        return { proof, nextPools };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+
 /**
  * Validates the transition from Prev -> Curr.
  * Enforces Cryptography AND Behavioral Policy.
@@ -569,3 +647,134 @@ export async function verifyProofAgainstPool({
         if (logalot) { console.log(`${lc} complete.`); }
     }
 }
+
+export async function evolvePersistAndRegisterKeystone({
+    prevIbGib,
+    newData,
+    metaspace,
+    space,
+}: {
+    prevIbGib: KeystoneIbGib_V1,
+    newData: KeystoneData_V1
+    metaspace: MetaspaceService,
+    space: IbGibSpaceAny,
+}): Promise<KeystoneIbGib_V1> {
+    const lc = `[${evolvePersistAndRegisterKeystone.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 8b10e8920f08b7842803665834cf8925)`); }
+
+        if (!prevIbGib.data) { throw new Error(`(UNEXPECTED) prevIbGib.data falsy? (E: 5e84875bf992c585b979e6c8ed5bf225)`); }
+        if (prevIbGib.data.revocationInfo) { throw new Error(`Keystone has already been revoked (prevIbGib.data.revocationInfo truthy), so we cannot evolve the keystone. Keystone addr: ${getIbGibAddr({ ibGib: prevIbGib })} (E: 45d7f846556829de6b2a701838c3f825)`); }
+
+        const prevData = prevIbGib.data;
+        /**
+         * we want to completely replace these keys, so we will remove them
+         * from the data. This occurs first in the underlying mut8
+         * transform.
+         * @see {@link mut8}
+         */
+        let dataToRemove: Partial<KeystoneData_V1> | undefined = {}
+        if (prevData.proofs) { dataToRemove.proofs = []; }
+        if (prevData.challengePools) { dataToRemove.challengePools = []; }
+        if (prevData.frameDetails) { dataToRemove.frameDetails = {}; }
+        if (Object.keys(dataToRemove).length === 0) { dataToRemove = undefined; }
+
+        const resMut8 = await mut8({
+            src: prevIbGib,
+            dataToRemove,
+            dataToAddOrPatch: newData,
+            // dna: false, // explicitly set to false just to show
+            nCounter: true,
+        });
+
+        if (!!resMut8.intermediateIbGibs) { throw new Error(`(UNEXPECTED) resMut8.intermediateIbGibs truthy? I'm not sure if we expect there to be intermediateIbGibs, but I feel like we shouldn't. Pretty sure we shouldn't, definitely don't *want* them. (E: ba40d55d7c2d36d438c413886f148625)`); }
+        if (!!resMut8.dnas) { throw new Error(`(UNEXPECTED) resMut8.dnas truthy? We do not want dnas with keystones. (E: 49470513d018f97d28024f4e82da3b25)`); }
+
+
+        const newKeystoneIbGib = resMut8.newIbGib as KeystoneIbGib_V1;
+
+        // run validation here
+        const errors = await validateKeystoneTransition({
+            currentIbGib: newKeystoneIbGib,
+            prevIbGib,
+        });
+        if (errors.length > 0) {
+            console.error(`${lc} Validation Failed:\n${errors.join('\n')}`);
+            throw new Error(`(UNEXPECTED) invalid keystone after we just evolved it? Errors: ${errors.join('; ')} (E: ae2c58406c1db7687879dfb89fc1f825)`);
+        }
+
+        // save and register
+        await metaspace.put({ ibGib: newKeystoneIbGib, space, });
+        await metaspace.registerNewIbGib({ ibGib: newKeystoneIbGib, space, });
+
+        return newKeystoneIbGib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * Creates a new keystone ibgib that has no dna and no past.
+ */
+export async function createKeystoneIbGibImpl({
+    data,
+    metaspace,
+    space,
+}: {
+    data: KeystoneData_V1,
+    metaspace: MetaspaceService,
+    space?: IbGibSpaceAny,
+}): Promise<KeystoneIbGib_V1> {
+    const lc = `[${createKeystoneIbGibImpl.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 5e32389700e9899e788cbefacef7c825)`); }
+
+        space ??= await metaspace.getLocalUserSpace({ lock: false });
+        if (!space) { throw new Error(`(UNEXPECTED) space was falsy and we couldn't get default local user space from metaspace? (E: 9a6498cf16a8801f19ec376749742225)`); }
+
+        // create the actual keystoneIbGib
+        const resFirstGen = await Factory_V1.firstGen({
+            parentIbGib: Factory_V1.primitive({ ib: KEYSTONE_ATOM }),
+            ib: await getKeystoneIb({ keystoneData: data }),
+            data,
+            dna: false,
+            nCounter: true,
+            tjp: {
+                timestamp: true,
+                uuid: true,
+            },
+        }) as TransformResult<KeystoneIbGib_V1>;
+        const keystoneIbGib = resFirstGen.newIbGib;
+
+        if (!keystoneIbGib.data) { throw new Error(`(UNEXPECTED) keystoneIbGib.data falsy? We expect the data to be populated with real keystone data. (E: 38a358facdb89d16d81d48c8520d3d25)`); }
+        if (!keystoneIbGib.rel8ns) { throw new Error(`(UNEXPECTED) keystoneIbGib.rel8ns falsy? we expect the rel8ns to have ancestor and past. (E: 20cb7723dc33ae1ef808fe76d1bf4b25)`); }
+        if (!keystoneIbGib.rel8ns.past || keystoneIbGib.rel8ns.past.length === 0) {
+            throw new Error(`(UNEXPECTED) keystoneIbGib.rel8ns.past falsy or empty? we expect the firstGen call to generate an interstitial ibgib that we will splice out. (E: 0fd8388d045ab9f37834c27d67e78825)`);
+        }
+
+        // reset n
+        keystoneIbGib.data.n = 0;
+        // reset tjp
+        keystoneIbGib.data.isTjp = true;
+        delete keystoneIbGib.rel8ns.tjp;
+        // reset past
+        delete keystoneIbGib.rel8ns.past;
+
+        // recalculate gib
+        keystoneIbGib.gib = await getGib({ ibGib: keystoneIbGib });
+
+        // save and register
+        await metaspace.put({ ibGib: keystoneIbGib, space, });
+        await metaspace.registerNewIbGib({ ibGib: keystoneIbGib, space, });
+
+        return keystoneIbGib;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}