@ibgib/core-gib 0.1.4 → 0.1.8

package/dist/keystone/keystone-config-builder.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-config-builder.mjs","sourceRoot":"","sources":["../../src/keystone/keystone-config-builder.mts"],"names":[],"mappings":"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"}

package/dist/keystone/keystone-constants.d.mts

@@ -0,0 +1,36 @@
+export declare const KEYSTONE_ATOM = "keystone";
+/**
+ * @see {@link KeystoneVerb.REVOKE}
+ */
+export declare const KEYSTONE_VERB_REVOKE = "revoke";
+/**
+ * @see {@link KeystoneVerb.MANAGE}
+ */
+export declare const KEYSTONE_VERB_MANAGE = "manage";
+export type KeystoneVerb = typeof KEYSTONE_VERB_REVOKE | typeof KEYSTONE_VERB_MANAGE;
+/**
+ * Verbs that describe actions that can be authorized by a Keystone.
+ */
+export declare const KeystoneVerb: {
+    /**
+     * The specific ibGib address for the 'revoke' verb.
+     * Used in Claims to indicate the Keystone should be considered dead.
+     */
+    REVOKE: "revoke";
+    /**
+     * The meta-verb used to authorize structural changes to the Keystone,
+     * specifically adding or removing challenge pools.
+     *
+     * "Root access" to the identity.
+     */
+    MANAGE: "manage";
+};
+export declare const KEYSTONE_VERB_VALID_VALUES: ("revoke" | "manage")[];
+export declare function isKeystoneVerb(value: string): value is KeystoneVerb;
+/**
+ * Standard pool IDs can be conventionally named after their primary verb.
+ */
+export declare const POOL_ID_REVOKE = "revoke";
+export declare const POOL_ID_MANAGE = "manage";
+export declare const POOL_ID_DEFAULT = "default";
+//# sourceMappingURL=keystone-constants.d.mts.map

package/dist/keystone/keystone-constants.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-constants.d.mts","sourceRoot":"","sources":["../../src/keystone/keystone-constants.mts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,aAAa,CAAC;AAGxC;;GAEG;AACH,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAC7C;;GAEG;AACH,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAC7C,MAAM,MAAM,YAAY,GAClB,OAAO,oBAAoB,GAC3B,OAAO,oBAAoB,CAAC;AAElC;;GAEG;AACH,eAAO,MAAM,YAAY;IACrB;;;OAGG;;IAEH;;;;;OAKG;;CAEoC,CAAC;AAC5C,eAAO,MAAM,0BAA0B,yBAA8B,CAAC;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAEnE;AAGD;;GAEG;AACH,eAAO,MAAM,cAAc,WAAuB,CAAC;AACnD,eAAO,MAAM,cAAc,WAAuB,CAAC;AACnD,eAAO,MAAM,eAAe,YAAY,CAAC"}

package/dist/keystone/keystone-constants.mjs

@@ -0,0 +1,39 @@
+export const KEYSTONE_ATOM = "keystone";
+// #region KeystoneVerb enum
+/**
+ * @see {@link KeystoneVerb.REVOKE}
+ */
+export const KEYSTONE_VERB_REVOKE = "revoke";
+/**
+ * @see {@link KeystoneVerb.MANAGE}
+ */
+export const KEYSTONE_VERB_MANAGE = "manage";
+/**
+ * Verbs that describe actions that can be authorized by a Keystone.
+ */
+export const KeystoneVerb = {
+    /**
+     * The specific ibGib address for the 'revoke' verb.
+     * Used in Claims to indicate the Keystone should be considered dead.
+     */
+    REVOKE: KEYSTONE_VERB_REVOKE,
+    /**
+     * The meta-verb used to authorize structural changes to the Keystone,
+     * specifically adding or removing challenge pools.
+     *
+     * "Root access" to the identity.
+     */
+    MANAGE: KEYSTONE_VERB_MANAGE,
+};
+export const KEYSTONE_VERB_VALID_VALUES = Object.values(KeystoneVerb);
+export function isKeystoneVerb(value) {
+    return KEYSTONE_VERB_VALID_VALUES.includes(value);
+}
+// #endregion KeystoneVerb enum
+/**
+ * Standard pool IDs can be conventionally named after their primary verb.
+ */
+export const POOL_ID_REVOKE = KEYSTONE_VERB_REVOKE;
+export const POOL_ID_MANAGE = KEYSTONE_VERB_MANAGE;
+export const POOL_ID_DEFAULT = "default";
+//# sourceMappingURL=keystone-constants.mjs.map

package/dist/keystone/keystone-constants.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-constants.mjs","sourceRoot":"","sources":["../../src/keystone/keystone-constants.mts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AAExC,4BAA4B;AAC5B;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAC7C;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAK7C;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IACxB;;;OAGG;IACH,MAAM,EAAE,oBAAoB;IAC5B;;;;;OAKG;IACH,MAAM,EAAE,oBAAoB;CACW,CAAC;AAC5C,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AACtE,MAAM,UAAU,cAAc,CAAC,KAAa;IACxC,OAAO,0BAA0B,CAAC,QAAQ,CAAC,KAAqB,CAAC,CAAC;AACtE,CAAC;AACD,+BAA+B;AAE/B;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,CAAC;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,oBAAoB,CAAC;AACnD,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC"}

package/dist/keystone/keystone-helpers.d.mts

@@ -0,0 +1,117 @@
+import { Ib } from "@ibgib/ts-gib/dist/types.mjs";
+import { KeystoneData_V1, KeystoneIbGib_V1, KeystoneIbInfo_V1, KeystoneChallengePool, DeterministicResult, KeystoneProof, KeystonePoolConfig } from "./keystone-types.mjs";
+/**
+ * space-delimited keystone ib containing select keystone metadata.
+ *
+ * NOTE: This must match {@link parseKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export declare function getKeystoneIb({ keystoneData, }: {
+    keystoneData: KeystoneData_V1;
+}): Promise<Ib>;
+/**
+ * NOTE: This must match {@link getKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export declare function parseKeystoneIb({ ib, }: {
+    ib: Ib;
+}): Promise<KeystoneIbInfo_V1>;
+/**
+ * The Policy Engine.
+ * Calculates exactly which challenges MUST be consumed based on config and demands.
+ * Enforces STRICT DISTINCTNESS (No double-dipping).
+ */
+export declare function getDeterministicRequirements({ pool, requiredChallengeIds, targetAddr }: {
+    pool: KeystoneChallengePool;
+    requiredChallengeIds?: string[];
+    targetAddr?: string;
+}): DeterministicResult;
+/**
+ * Helper to update the Binding Map when adding new Challenge IDs.
+ * Uses "Implicit Bucketing" (ID start char) but can be extended for full coverage.
+ */
+export declare function addToBindingMap(map: {
+    [char: string]: string[];
+}, challengeId: string): void;
+/**
+ * Helper to clean up Binding Map when removing IDs.
+ */
+export declare function removeFromBindingMap(map: {
+    [char: string]: string[];
+}, challengeId: string): void;
+/**
+ * Selects the specific pool to use for an operation based on ID, filter criteria, or verb authorization.
+ *
+ * @returns The matching KeystoneChallengePool
+ * @throws If no pool matches or if multiple pools match but one was expected.
+ */
+export declare function resolveTargetPool({ pools, poolId, poolFilter, verb, }: {
+    pools: KeystoneChallengePool[];
+    /**
+     * Explicit ID of the pool to use.
+     */
+    poolId?: string;
+    /**
+     * Optional predicate to find a pool.
+     * Useful for finding delegates via metadata.
+     */
+    poolFilter?: (pool: KeystoneChallengePool) => boolean;
+    /**
+     * The verb being performed (e.g. 'revoke', 'manage', 'post').
+     * Used for authorization checks and auto-resolution.
+     */
+    verb?: string;
+}): KeystoneChallengePool;
+/**
+ * Calculates the complete list of Challenge IDs to solve for a given operation.
+ * Combines Deterministic requirements (Mandatory/Binding/FIFO) with Stochastic requirements.
+ *
+ * @returns Array of unique challenge IDs.
+ */
+export declare function selectChallengeIds({ pool, targetAddr, requiredChallengeIds, }: {
+    pool: KeystoneChallengePool;
+    /**
+     * The address of the target ibgib (used for binding entropy).
+     */
+    targetAddr?: string;
+    /**
+     * Explicit demands from a verifier.
+     */
+    requiredChallengeIds?: string[];
+}): string[];
+/**
+ * Calculates the NEXT state of the Challenge Pools given a specific consumption event.
+ * Handles TopUp, ReplaceAll, Consume, and ScorchedEarth strategies.
+ *
+ * @returns The new array of KeystoneChallengePools (including the modified one).
+ */
+export declare function applyReplenishmentStrategy({ prevPools, targetPoolId, consumedIds, masterSecret, strategy, config, }: {
+    prevPools: KeystoneChallengePool[];
+    targetPoolId: string;
+    consumedIds: string[];
+    masterSecret: string;
+    /**
+     * The instantiated KeystoneStrategy (e.g. HashRevealV1) used to generate new challenges.
+     */
+    strategy: any;
+    config: KeystonePoolConfig;
+}): Promise<KeystoneChallengePool[]>;
+/**
+ * Validates the transition from Prev -> Curr.
+ * Enforces Cryptography AND Behavioral Policy.
+ *
+ * @returns Array of validation error strings. Empty array means Valid.
+ */
+export declare function validateKeystoneTransition({ currentIbGib, prevIbGib, }: {
+    currentIbGib: KeystoneIbGib_V1;
+    prevIbGib: KeystoneIbGib_V1;
+}): Promise<string[]>;
+/**
+ * Helper to verify a single proof against a specific pool.
+ */
+export declare function verifyProofAgainstPool({ proof, pool, errors, }: {
+    proof: KeystoneProof;
+    pool: KeystoneChallengePool;
+    errors: string[];
+}): Promise<void>;
+//# sourceMappingURL=keystone-helpers.d.mts.map

package/dist/keystone/keystone-helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keystone-helpers.d.mts","sourceRoot":"","sources":["../../src/keystone/keystone-helpers.mts"],"names":[],"mappings":"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"}

package/dist/keystone/keystone-helpers.mjs

@@ -0,0 +1,455 @@
+import { extractErrorMsg, hash, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { getIbAndGib, getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
+import { validateIbGibIntrinsically } from "@ibgib/ts-gib/dist/V1/validate-helper.mjs";
+import { GLOBAL_LOG_A_LOT } from "../core-constants.mjs";
+import { KEYSTONE_ATOM } from "./keystone-constants.mjs";
+import { KeystoneReplenishStrategy, KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES } from "./keystone-types.mjs";
+import { KeystoneStrategyFactory } from "./strategy/keystone-strategy-factory.mjs";
+const logalot = GLOBAL_LOG_A_LOT;
+/**
+ * space-delimited keystone ib containing select keystone metadata.
+ *
+ * NOTE: This must match {@link parseKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export async function getKeystoneIb({ keystoneData, }) {
+    const lc = `[${getKeystoneIb.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: c3022a146faac9730154f34d1439a225)`);
+        }
+        const atom = KEYSTONE_ATOM;
+        const ib = [
+            atom,
+        ].join(' ');
+        return ib;
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+    finally {
+        if (logalot) {
+            console.log(`${lc} complete.`);
+        }
+    }
+}
+/**
+ * NOTE: This must match {@link getKeystoneIb}
+ * @see {@link KeystoneIbInfo_V1}
+ */
+export async function parseKeystoneIb({ ib, }) {
+    const lc = `[${parseKeystoneIb.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 73cb6832984255ed48b2f44db6a21e25)`);
+        }
+        const [atom] = ib.split(' ');
+        if (atom !== KEYSTONE_ATOM) {
+            throw new Error(`invalid keystone ib. atom found in ib (${atom}) does not match keystone atom (${KEYSTONE_ATOM}) (E: 79b3d587824c4271b6e60acc76e0c825)`);
+        }
+        return {
+            atom,
+        };
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+    finally {
+        if (logalot) {
+            console.log(`${lc} complete.`);
+        }
+    }
+}
+/**
+ * The Policy Engine.
+ * Calculates exactly which challenges MUST be consumed based on config and demands.
+ * Enforces STRICT DISTINCTNESS (No double-dipping).
+ */
+export function getDeterministicRequirements({ pool, requiredChallengeIds, targetAddr }) {
+    const behavior = pool.config.behavior;
+    const mandatory = new Set();
+    // Start with all available IDs.
+    // We assume Object.keys respects insertion order (ES2015+), crucial for FIFO.
+    let available = Object.keys(pool.challenges);
+    // ---------------------------------------------------------
+    // 1. Alice's Demands (Explicit Requirements)
+    // ---------------------------------------------------------
+    if (requiredChallengeIds && requiredChallengeIds.length > 0) {
+        for (const id of requiredChallengeIds) {
+            if (!pool.challenges[id]) {
+                throw new Error(`(UNEXPECTED) Required challenge ID not found in pool: ${id} (E: 2c9f8...)`);
+            }
+            // Strict: Consume it.
+            if (!available.includes(id)) {
+                // Should be caught by check above, but handles duplicates in 'demands'
+                continue;
+            }
+            mandatory.add(id);
+        }
+        // Remove from available pool
+        available = available.filter(id => !mandatory.has(id));
+    }
+    // ---------------------------------------------------------
+    // 2. Target Binding (Explicit Buckets)
+    // ---------------------------------------------------------
+    if (behavior.targetBindingChars > 0 && targetAddr) {
+        const { gib } = getIbAndGib({ ibGibAddr: targetAddr });
+        if (gib) {
+            // Get required hex prefixes (e.g. 'a', 'b', 'c', '1')
+            const prefixes = gib.substring(0, behavior.targetBindingChars).toLowerCase();
+            for (const char of prefixes) {
+                // Look in the Explicit Bucket
+                const bucket = pool.bindingMap[char] || [];
+                // Find the first ID in this bucket that is still in 'available'
+                const match = bucket.find(id => available.includes(id));
+                if (!match) {
+                    throw new Error(`Entropy Exhaustion. Cannot satisfy binding for char '${char}'. (E: 8d3a1...)`);
+                }
+                // Strict: Consume it.
+                mandatory.add(match);
+                available = available.filter(id => id !== match);
+            }
+        }
+    }
+    // ---------------------------------------------------------
+    // 3. FIFO (Sequential)
+    // ---------------------------------------------------------
+    if (behavior.selectSequentially > 0) {
+        // Take the first N from the remaining available list
+        if (available.length < behavior.selectSequentially) {
+            console.error(`[getDeterministicRequirements] Entropy Exhaustion! AvailableCount: ${available.length}, Required Seq: ${behavior.selectSequentially}. Available IDs: ${available.join(',')}`);
+            throw new Error(`Entropy Exhaustion. Insufficient challenges for FIFO requirement. (E: 9c2b4...)`);
+        }
+        const fifoIds = available.slice(0, behavior.selectSequentially);
+        fifoIds.forEach(id => mandatory.add(id));
+        // Remove from available
+        available = available.slice(behavior.selectSequentially);
+    }
+    return { mandatoryIds: mandatory, availableIds: available };
+}
+/**
+ * Helper to update the Binding Map when adding new Challenge IDs.
+ * Uses "Implicit Bucketing" (ID start char) but can be extended for full coverage.
+ */
+export function addToBindingMap(map, challengeId) {
+    const firstChar = challengeId.charAt(0).toLowerCase();
+    // Validate it is hex
+    if (/[0-9a-f]/.test(firstChar)) {
+        if (!map[firstChar])
+            map[firstChar] = [];
+        map[firstChar].push(challengeId);
+        // OPTIONAL: Implement Full Coverage Strategy here?
+        // e.g. map[challengeId[1]].push(challengeId) ...
+        // For V1, we stick to Native/Implicit bucket (Index 0).
+    }
+}
+/**
+ * Helper to clean up Binding Map when removing IDs.
+ */
+export function removeFromBindingMap(map, challengeId) {
+    // Since we don't know exactly which buckets an ID is in (if we did multi-bucket),
+    // we strictly should scan all. For V1 Native, we check first char.
+    // SAFE IMPLEMENTATION: Scan all buckets.
+    for (const key of Object.keys(map)) {
+        map[key] = map[key].filter(id => id !== challengeId);
+    }
+}
+/**
+ * Selects the specific pool to use for an operation based on ID, filter criteria, or verb authorization.
+ *
+ * @returns The matching KeystoneChallengePool
+ * @throws If no pool matches or if multiple pools match but one was expected.
+ */
+export function resolveTargetPool({ pools, poolId, poolFilter, verb, }) {
+    const lc = `[resolveTargetPool]`;
+    try {
+        let pool;
+        if (poolId) {
+            // 1. Explicit ID Strategy
+            pool = pools.find(p => p.id === poolId);
+            if (!pool) {
+                throw new Error(`Pool not found with ID: ${poolId} (E: 4a2b17428515c1e82813158581898125)`);
+            }
+        }
+        else if (poolFilter) {
+            // 2. Filter Strategy
+            const matches = pools.filter(poolFilter);
+            if (matches.length === 0) {
+                throw new Error(`No pool matched the provided filter. (E: 5b3c27428515c1e82813158581898125)`);
+            }
+            // For now, we take the first match. In future, might want to be strict about uniqueness.
+            pool = matches[0];
+        }
+        else {
+            // 3. Auto-Resolution by Verb Strategy
+            if (!verb) {
+                throw new Error(`Cannot auto-resolve pool without a verb. (E: 6c4d37428515c1e82813158581898125)`);
+            }
+            // Priority A: Look for Specific Match (Pool explicitly lists this verb)
+            pool = pools.find(p => p.config.allowedVerbs && p.config.allowedVerbs.includes(verb));
+            // Priority B: Look for General/Default (No restrictions / Wildcard)
+            if (!pool) {
+                pool = pools.find(p => !p.config.allowedVerbs || p.config.allowedVerbs.length === 0);
+            }
+            if (!pool) {
+                throw new Error(`No suitable pool found for verb: ${verb} (E: 7d5e47428515c1e82813158581898125)`);
+            }
+        }
+        // 4. Authorization Check (Applies to all strategies if verb is present)
+        if (verb && pool.config.allowedVerbs && pool.config.allowedVerbs.length > 0) {
+            if (!pool.config.allowedVerbs.includes(verb)) {
+                throw new Error(`Pool ${pool.id} is not authorized for verb: ${verb} (E: 8e6f57428515c1e82813158581898125)`);
+            }
+        }
+        return pool;
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+/**
+ * Calculates the complete list of Challenge IDs to solve for a given operation.
+ * Combines Deterministic requirements (Mandatory/Binding/FIFO) with Stochastic requirements.
+ *
+ * @returns Array of unique challenge IDs.
+ */
+export function selectChallengeIds({ pool, targetAddr, requiredChallengeIds, }) {
+    const lc = `[selectChallengeIds]`;
+    try {
+        // 1. Get Deterministic Requirements
+        const { mandatoryIds, availableIds } = getDeterministicRequirements({
+            pool,
+            requiredChallengeIds,
+            targetAddr
+        });
+        // 2. Stochastic Selection
+        const randomCount = pool.config.behavior.selectRandomly;
+        const randomIds = [];
+        if (randomCount > 0) {
+            if (availableIds.length < randomCount) {
+                throw new Error(`Insufficient challenges for random requirement. Need ${randomCount}, have ${availableIds.length} (E: 9f7a67428515c1e82813158581898125)`);
+            }
+            // Shuffle & Pick
+            // Note: simple Math.random sort is sufficient for V1 stochastic selection 
+            // as we are just picking from valid available options.
+            const shuffled = [...availableIds].sort(() => 0.5 - Math.random());
+            randomIds.push(...shuffled.slice(0, randomCount));
+        }
+        // 3. Combine
+        return [...mandatoryIds, ...randomIds];
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+/**
+ * Generates an opaque, collision-resistant ID for a challenge.
+ * atow (2025/12/22) - Hash(Salt + Timestamp + Index)
+ */
+async function generateOpaqueChallengeId({ salt, timestamp, index }) {
+    // Use first 16 chars of hex (64 bits) for brevity + safety.
+    const raw = await hash({ s: `${salt}${timestamp}${index}` });
+    return raw.substring(0, 16);
+}
+/**
+ * Calculates the NEXT state of the Challenge Pools given a specific consumption event.
+ * Handles TopUp, ReplaceAll, Consume, and ScorchedEarth strategies.
+ *
+ * @returns The new array of KeystoneChallengePools (including the modified one).
+ */
+export async function applyReplenishmentStrategy({ prevPools, targetPoolId, consumedIds, masterSecret, strategy, config, }) {
+    const lc = `[applyReplenishmentStrategy]`;
+    try {
+        const newPools = JSON.parse(JSON.stringify(prevPools));
+        const targetIdx = newPools.findIndex((p) => p.id === targetPoolId);
+        if (targetIdx === -1) {
+            throw new Error(`Target pool ${targetPoolId} not found in keystone data. (E: 75200388d22744838634524233772545)`);
+        }
+        const pool = newPools[targetIdx];
+        const poolSecret = await strategy.derivePoolSecret({ masterSecret });
+        const timestamp = Date.now().toString();
+        const strategyType = config.behavior.replenish;
+        // Clean up Binding Map for consumed IDs
+        consumedIds.forEach(id => {
+            if (pool.bindingMap) {
+                removeFromBindingMap(pool.bindingMap, id);
+            }
+        });
+        if (strategyType === KeystoneReplenishStrategy.topUp) {
+            // Remove consumed
+            consumedIds.forEach(id => delete pool.challenges[id]);
+            // Add New
+            for (let i = 0; i < consumedIds.length; i++) {
+                const newId = await generateOpaqueChallengeId({
+                    salt: config.salt, timestamp, index: i
+                });
+                const solution = await strategy.generateSolution({
+                    poolSecret, poolId: pool.id, challengeId: newId
+                });
+                pool.challenges[newId] = await strategy.generateChallenge({ solution });
+                // Update Binding Map
+                if (!pool.bindingMap) {
+                    pool.bindingMap = {};
+                }
+                addToBindingMap(pool.bindingMap, newId);
+            }
+        }
+        else if (strategyType === KeystoneReplenishStrategy.replaceAll) {
+            pool.challenges = {};
+            pool.bindingMap = {};
+            for (let i = 0; i < config.behavior.size; i++) {
+                const newId = await generateOpaqueChallengeId({
+                    salt: config.salt, timestamp, index: i
+                });
+                const solution = await strategy.generateSolution({
+                    poolSecret, poolId: pool.id, challengeId: newId
+                });
+                pool.challenges[newId] = await strategy.generateChallenge({ solution });
+                addToBindingMap(pool.bindingMap, newId);
+            }
+        }
+        else if (strategyType === KeystoneReplenishStrategy.consume) {
+            consumedIds.forEach(id => delete pool.challenges[id]);
+        }
+        else if (strategyType === KeystoneReplenishStrategy.scorchedEarth) {
+            pool.challenges = {};
+            pool.bindingMap = {};
+        }
+        else {
+            throw new Error(`Unknown replenish strategy: ${strategyType}. Valid list: ${pretty(KEYSTONE_REPLENISH_STRATEGY_VALID_VALUES)} (E: 0acf56f1e1486240080e11e8046d0825)`);
+        }
+        return newPools;
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+}
+/**
+ * Validates the transition from Prev -> Curr.
+ * Enforces Cryptography AND Behavioral Policy.
+ *
+ * @returns Array of validation error strings. Empty array means Valid.
+ */
+export async function validateKeystoneTransition({ currentIbGib, prevIbGib, }) {
+    const lc = `[${validateKeystoneTransition.name}]`;
+    const errors = [];
+    try {
+        if (!currentIbGib) {
+            throw new Error(`(UNEXPECTED) currentIbGib falsy? (E: 3c0f02655fa8279e386a079ebb604b25)`);
+        }
+        if (!prevIbGib) {
+            throw new Error(`(UNEXPECTED) prevIbGib falsy? (E: 0d07c812634d839c784f31b8848ba825)`);
+        }
+        // intrinsic validation
+        const validationErrors = await validateIbGibIntrinsically({ ibGib: currentIbGib });
+        if (validationErrors && validationErrors.length > 0) {
+            errors.push(...validationErrors);
+        }
+        const currData = currentIbGib.data;
+        const prevData = prevIbGib.data;
+        for (const proof of currData.proofs) {
+            if (proof.solutions.length === 0) {
+                errors.push(`Proof ${proof.id || 'unknown'} has no solutions.`);
+                continue;
+            }
+            const poolId = proof.solutions[0].poolId;
+            // Standard Verification (Internal Pools Only)
+            // The pool MUST be present in the previous frame.
+            const pool = prevData.challengePools.find(p => p.id === poolId);
+            if (!pool) {
+                errors.push(`Proof references unknown pool: ${poolId}`);
+                continue;
+            }
+            await verifyProofAgainstPool({ proof, pool, errors });
+        } // End proof loop
+        // Revocation Logic checks
+        if (currData.revocationInfo) {
+            const target = currData.revocationInfo.proof.claim.target;
+            const expectedTarget = getIbGibAddr({ ibGib: prevIbGib });
+            if (target !== expectedTarget) {
+                errors.push(`Revocation target mismatch. Expected ${expectedTarget}, got ${target}`);
+            }
+        }
+        return errors;
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error; // System errors still throw
+    }
+    finally {
+        if (logalot) {
+            console.log(`${lc} complete.`);
+        }
+    }
+}
+/**
+ * Helper to verify a single proof against a specific pool.
+ */
+export async function verifyProofAgainstPool({ proof, pool, errors, }) {
+    const lc = `[${verifyProofAgainstPool.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: b8f9b6085888eea2258bf579ecd5e825)`);
+        }
+        // 0. VERB AUTH
+        if (pool.config.allowedVerbs && pool.config.allowedVerbs.length > 0) {
+            if (!proof.claim.verb || !pool.config.allowedVerbs.includes(proof.claim.verb)) {
+                errors.push(`Policy Violation: Pool ${pool.id} used for unauthorized verb ${proof.claim.verb}`);
+            }
+        }
+        // 1. Reconstruct Deterministic Requirements
+        const { mandatoryIds, availableIds } = getDeterministicRequirements({
+            pool,
+            requiredChallengeIds: proof.requiredChallengeIds,
+            targetAddr: proof.claim.target // Not used extensively in V1 logic yet, mainly for logging/context
+        });
+        // 2. Check Mandatory
+        const proofIds = new Set(proof.solutions.map(s => s.challengeId));
+        for (const id of mandatoryIds) {
+            if (!proofIds.has(id)) {
+                errors.push(`Policy Violation: Missing mandatory challenge ${id}`);
+            }
+        }
+        // 3. Stochastic
+        const randomCandidates = [...proofIds].filter(id => !mandatoryIds.has(id));
+        const requiredRandomCount = pool.config.behavior.selectRandomly;
+        if (randomCandidates.length < requiredRandomCount) {
+            errors.push(`Policy Violation: Insufficient random count. Need ${requiredRandomCount}, got ${randomCandidates.length}`);
+        }
+        // 4. Validity (Double Dip / Existence)
+        for (const id of randomCandidates) {
+            if (!availableIds.includes(id)) {
+                errors.push(`Policy Violation: ID ${id} is invalid or double-dipped.`);
+            }
+        }
+        // 5. Crypto
+        const strategy = KeystoneStrategyFactory.create({ config: pool.config });
+        for (const solution of proof.solutions) {
+            const challenge = pool.challenges[solution.challengeId];
+            if (!challenge) {
+                errors.push(`Crypto Violation: Challenge ${solution.challengeId} not found in pool.`);
+            }
+            else {
+                const isValid = await strategy.validateSolution({ solution, challenge });
+                if (!isValid) {
+                    errors.push(`Crypto Violation: Solution for ${solution.challengeId} is invalid.`);
+                }
+            }
+        }
+    }
+    catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    }
+    finally {
+        if (logalot) {
+            console.log(`${lc} complete.`);
+        }
+    }
+}
+//# sourceMappingURL=keystone-helpers.mjs.map