@ibgib/core-gib 0.1.43 → 0.1.45

package/src/keystone/kdf/kdf-types.mts

@@ -0,0 +1,58 @@
+import { HashAlgorithm } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { KdfStrategy } from './kdf-constants.mjs';
+
+/**
+ * Base options for all KDF strategies
+ */
+export interface KdfOptionsBase {
+    /**
+     * Name of the KDF strategy to use
+     */
+    strategy: KdfStrategy;
+}
+
+/**
+ * Options for recursive-salt-wrap KDF strategy
+ *
+ * Derives key by recursively applying: Hash(salt + current + salt) for N rounds
+ */
+export interface KdfOptions_RecursiveSaltWrap extends KdfOptionsBase {
+    strategy: typeof import('./kdf-constants.mjs').KDF_STRATEGY_RECURSIVE_SALT_WRAP;
+
+    /**
+     * Salt value to wrap around the secret during each iteration
+     */
+    salt: string;
+
+    /**
+     * Number of hash iterations for key stretching
+     */
+    rounds: number;
+
+    /**
+     * Hash algorithm to use (default: SHA-256)
+     */
+    algorithm?: HashAlgorithm;
+}
+
+/**
+ * Union of all KDF option types
+ */
+export type KdfOptions =
+    | KdfOptions_RecursiveSaltWrap
+    ;
+
+/**
+ * Parameters for deriving a key using KDF
+ */
+export interface DeriveKeyParams {
+    /**
+     * The initial secret/password to derive from
+     */
+    masterSecret: string;
+
+    /**
+     * KDF options specifying strategy and strategy-specific parameters
+     */
+    kdfOpts: KdfOptions;
+}

package/src/keystone/keystone-config-builder.mts

@@ -1,11 +1,13 @@
+import { extractErrorMsg, HashAlgorithm } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
 import {
-    KeystonePoolConfig,
-    KeystonePoolConfig_HashV1,
-    KeystonePoolBehavior,
-    KeystoneReplenishStrategy,
-    KeystonePoolConfigBase
+    KeystonePoolConfig, KeystonePoolConfig_HashV1, KeystonePoolBehavior,
+    KeystoneReplenishStrategy, KeystonePoolConfigBase, KeystoneChallengeType,
 } from './keystone-types.mjs';
-import { POOL_ID_DEFAULT, POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE } from './keystone-constants.mjs';
+import { POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_CONFIG_DEFAULT_SIZE, KEYSTONE_CONFIG_DEFAULT_BINDING, KEYSTONE_CONFIG_DEFAULT_REPLENISH_STRATEGY, KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL, KEYSTONE_CONFIG_DEFAULT_RANDOM, KEYSTONE_CONFIG_DEFAULT_SIZE_HIGHSECURITY, KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL_HIGHSECURITY, KEYSTONE_CONFIG_DEFAULT_RANDOM_HIGHSECURITY, KEYSTONE_CONFIG_DEFAULT_BINDING_HIGHSECURITY, KEYSTONE_CONFIG_DEFAULT_REPLENISH_STRATEGY_HIGHSECURITY, KeystoneVerb, KEYSTONE_CONFIG_DEFAULT_HASH_ALGORITHM, KEYSTONE_CONFIG_DEFAULT_HASH_ROUNDS, KEYSTONE_CONFIG_DEFAULT_HASH_ALGORITHM_HIGHSECURITY, KEYSTONE_CONFIG_DEFAULT_HASH_ROUNDS_HIGHSECURITY } from './keystone-constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
 
 /**
  * Abstract Base Builder.
@@ -14,17 +16,25 @@ import { POOL_ID_DEFAULT, POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE } from './keyston
  * @template TConfig The concrete config type being built.
  */
 export abstract class KeystoneConfigBuilderBase<TConfig extends KeystonePoolConfigBase> {
-    protected _salt: string = 'default';
-    protected _size: number = 100;
-    protected _replenish: KeystoneReplenishStrategy = 'top-up';
-    protected _seq: number = 0;
-    protected _rand: number = 0;
+    protected _id: string | undefined;
+    protected _salt: string | undefined;
+    protected _size: number | undefined;
+    protected _replenish: KeystoneReplenishStrategy | undefined;
+    protected _seq: number | undefined;
+    protected _rand: number | undefined;
     protected _verbs: string[] = [];
-    protected _targetBinding: number = 0; // Default 0
+    protected _targetBinding: number | undefined;
 
+    /**
+     * Sets the unique id for this pool.
+     */
+    withId(id: string): this {
+        this._id = id;
+        return this;
+    }
 
     /**
-     * Sets the unique salt/ID for this pool.
+     * Sets the unique salt for this pool.
      */
     withSalt(salt: string): this {
         this._salt = salt;
@@ -71,7 +81,7 @@ export abstract class KeystoneConfigBuilderBase<TConfig extends KeystonePoolConf
     /**
      * Configures the pool to use Hybrid (Both FIFO and Random) selection.
      */
-    withHybrid(seqCount: number, randCount: number): this {
+    withHybrid({ seqCount, randCount }: { seqCount: number, randCount: number }): this {
         this._seq = seqCount;
         this._rand = randCount;
         return this;
@@ -90,6 +100,11 @@ export abstract class KeystoneConfigBuilderBase<TConfig extends KeystonePoolConf
      * Helper for subclasses.
      */
     protected buildBehavior(): KeystonePoolBehavior {
+        if (this._size === undefined) { throw new Error(`size required (E: 68320865d9adb8477836485b20b08826)`); }
+        if (this._replenish === undefined) { throw new Error(`replenish strategy required (E: 9f8798d1a568763a282e53c89185b826)`); }
+        if (this._seq === undefined) { throw new Error(`sequential required (E: e0da08a24e9790d0a8c1a9322f8eb826)`); }
+        if (this._rand === undefined) { throw new Error(`selectRandomly required (E: 7721d84d1a8b7d020d0ab33c3f811426)`); }
+        if (this._targetBinding === undefined) { throw new Error(`targetBinding required (E: 9add64d7e8e8cba01d901727a8e9b826)`); }
         return {
             size: this._size,
             replenish: this._replenish,
@@ -108,14 +123,14 @@ export abstract class KeystoneConfigBuilderBase<TConfig extends KeystonePoolConf
         return this;
     }
 
-    protected buildBase(): KeystonePoolConfigBase {
-        // Helper to keep the concrete build() clean
-        return {
-            type: 'hash-reveal-v1', // This is overridden by concrete/interface usually, but needed for base shape
-            salt: this._salt,
-            allowedVerbs: this._verbs
-        } as any;
-    }
+    // protected buildBase(): KeystonePoolConfigBase {
+    //     // Helper to keep the concrete build() clean
+    //     return {
+    //         type: KeystoneChallengeType.hash_reveal_v1, // This is overridden by concrete/interface usually, but needed for base shape
+    //         salt: this._salt,
+    //         allowedVerbs: this._verbs
+    //     } as any;
+    // }
 
     abstract build(): TConfig;
 }
@@ -124,28 +139,56 @@ export abstract class KeystoneConfigBuilderBase<TConfig extends KeystonePoolConf
  * Concrete Builder for Hash-Reveal V1 Strategy.
  */
 export class KeystoneConfigBuilder_HashV1 extends KeystoneConfigBuilderBase<KeystonePoolConfig_HashV1> {
-    private _algo: 'SHA-256' | 'SHA-512' = 'SHA-256';
-    private _rounds: number = 1;
+    protected lc: string = `[${KeystoneConfigBuilder_HashV1}]`;
+    private _algo: HashAlgorithm | undefined;
+    private _rounds: number | undefined;
 
     /**
      * Sets the hashing strength.
      */
-    withHash(algo: 'SHA-256' | 'SHA-512', rounds: number = 1): this {
-        this._algo = algo;
-        this._rounds = rounds;
-        return this;
+    withHash({ algo, rounds }: { algo: HashAlgorithm, rounds: number }): this {
+        const lc = `${this.lc}[${this.withHash.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 15d1b3bd2e98bba33fc6c78228755826)`); }
+
+            this._algo = algo;
+            this._rounds = rounds;
+            return this;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
     }
 
     build(): KeystonePoolConfig_HashV1 {
-        return {
-            id: this._salt, // Using salt as the unique ID for the pool config
-            type: 'hash-reveal-v1',
-            salt: this._salt,
-            allowedVerbs: this._verbs, // <--- Mapped here
-            behavior: this.buildBehavior(),
-            algo: this._algo,
-            rounds: this._rounds,
-        };
+        const lc = `${this.lc}[${this.build.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 5df568c63c4993bb98df0a319ee16826)`); }
+
+            if (!this._id) { throw new Error(`id required (E: b50d082adf38bcbf463552f80d2c3226)`); }
+            if (!this._salt) { throw new Error(`salt required (E: b0f1926657b8d7d3a88fb9385ead5826)`); }
+            if (!this._algo) { throw new Error(`algorithm required (E: cff228f9898fd6383ef752088dae6826)`); }
+            if (this._rounds === undefined) { throw new Error(`rounds required (E: eb72580f3b014cda18cba3e399683c26)`); }
+
+            const result: KeystonePoolConfig_HashV1 = {
+                id: this._id,
+                type: KeystoneChallengeType.hash_reveal_v1,
+                salt: this._salt,
+                allowedVerbs: this._verbs,
+                behavior: this.buildBehavior(),
+                algo: this._algo,
+                rounds: this._rounds,
+            };
+
+            return result;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
     }
 }
 
@@ -166,22 +209,102 @@ export class KeystoneConfig {
 // FACTORY FUNCTIONS (Presets)
 // ===========================================================================
 
-export function createStandardPoolConfig(salt: string = POOL_ID_DEFAULT): KeystonePoolConfig {
+interface KeystoneConfigFactoryOptions_Standard {
+    /**
+     * id for pool that this config pertains to
+     */
+    id: string;
+    /**
+     * should be a unique string
+     */
+    salt: string;
+    /**
+     * number of challenges in the pool
+     * @see {@link KeystonePoolConfig}
+     */
+    size?: number;
+    /**
+     * number of sequential challenges required for solution per action
+     */
+    sequential?: number;
+    /**
+     * number of random challenges required for solution per action
+     */
+    random?: number;
+    /**
+     * number of target binding characters required for solution per action
+     * @see {@link KeystonePoolBehavior.targetBindingChars}
+     */
+    targetBinding?: number;
+    /**
+     * @see {@link KeystonePoolBehavior.replenish}
+     */
+    replenishStrategy?: KeystoneReplenishStrategy;
+    /**
+     * verbs for the pool
+     */
+    verbs?: string[];
+    hashAlgorithm?: HashAlgorithm;
+    hashRounds?: number;
+}
+
+export function createStandardPoolConfig(opts: KeystoneConfigFactoryOptions_Standard): KeystonePoolConfig {
+    let {
+        salt, id, size, sequential, random, targetBinding, replenishStrategy,
+        verbs, hashAlgorithm, hashRounds,
+    } = opts;
     return KeystoneConfig.hash()
+        .withId(id)
         .withSalt(salt)
-        .withSize(100)
-        .withHybrid(2, 2)
-        .withReplenishStrategy('top-up')
+        .withSize(size ?? KEYSTONE_CONFIG_DEFAULT_SIZE)
+        .withHybrid({
+            seqCount: sequential ?? KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL,
+            randCount: random ?? KEYSTONE_CONFIG_DEFAULT_RANDOM,
+        })
+        .withTargetBinding(targetBinding ?? KEYSTONE_CONFIG_DEFAULT_BINDING)
+        .withReplenishStrategy(replenishStrategy ?? KEYSTONE_CONFIG_DEFAULT_REPLENISH_STRATEGY)
+        .withHash({
+            algo: hashAlgorithm ?? KEYSTONE_CONFIG_DEFAULT_HASH_ALGORITHM,
+            rounds: hashRounds ?? KEYSTONE_CONFIG_DEFAULT_HASH_ROUNDS
+        })
+        .forVerbs(verbs ?? [])
         .build();
 }
 
-export function createRevocationPoolConfig(salt: string = POOL_ID_REVOKE): KeystonePoolConfig {
+export function createHighSecurityPoolConfig(opts: KeystoneConfigFactoryOptions_Standard): KeystonePoolConfig {
+    let {
+        salt, id, size, sequential, random, targetBinding, replenishStrategy,
+        verbs, hashAlgorithm, hashRounds,
+    } = opts;
     return KeystoneConfig.hash()
+        .withId(id)
         .withSalt(salt)
-        .withHash('SHA-256', 10)
-        .withSize(500)
-        .withHybrid(10, 10)
-        .withReplenishStrategy(KeystoneReplenishStrategy.scorchedEarth)
-        .forVerbs([KEYSTONE_VERB_REVOKE])
+        .withSize(size ?? KEYSTONE_CONFIG_DEFAULT_SIZE_HIGHSECURITY)
+        .withHybrid({
+            seqCount: sequential ?? KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL_HIGHSECURITY,
+            randCount: random ?? KEYSTONE_CONFIG_DEFAULT_RANDOM_HIGHSECURITY,
+        })
+        .withTargetBinding(targetBinding ?? KEYSTONE_CONFIG_DEFAULT_BINDING_HIGHSECURITY)
+        .withReplenishStrategy(replenishStrategy ?? KEYSTONE_CONFIG_DEFAULT_REPLENISH_STRATEGY_HIGHSECURITY)
+        .withHash({
+            algo: hashAlgorithm ?? KEYSTONE_CONFIG_DEFAULT_HASH_ALGORITHM_HIGHSECURITY,
+            rounds: hashRounds ?? KEYSTONE_CONFIG_DEFAULT_HASH_ROUNDS_HIGHSECURITY
+        })
+        .forVerbs(verbs ?? [])
         .build();
 }
+
+export function createManagePoolConfig(opts: KeystoneConfigFactoryOptions_Standard): KeystonePoolConfig {
+    return createHighSecurityPoolConfig({
+        ...opts,
+        verbs: [KeystoneVerb.MANAGE],
+    });
+}
+
+export function createRevocationPoolConfig(opts: KeystoneConfigFactoryOptions_Standard): KeystonePoolConfig {
+    return createHighSecurityPoolConfig({
+        ...opts,
+        verbs: [KeystoneVerb.REVOKE],
+        replenishStrategy: KeystoneReplenishStrategy.deleteAll,
+    });
+}

package/src/keystone/keystone-config-builder.respec.mts

@@ -5,9 +5,9 @@ const maam = `[${import.meta.url}]`, sir = maam;
 import { } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
-import { KeystonePoolConfig_HashV1 } from './keystone-types.mjs';
+import { KEYSTONE_REPLENISH_STRATEGY_DELETE_ALL, KeystoneChallengeType, KeystonePoolConfig_HashV1, KeystoneReplenishStrategy } from './keystone-types.mjs';
 import { createRevocationPoolConfig, createStandardPoolConfig } from './keystone-config-builder.mjs';
-import { KEYSTONE_VERB_REVOKE, } from './keystone-constants.mjs';
+import { KEYSTONE_CONFIG_DEFAULT_RANDOM, KEYSTONE_CONFIG_DEFAULT_REPLENISH_STRATEGY, KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL, KEYSTONE_CONFIG_DEFAULT_SIZE, KEYSTONE_CONFIG_DEFAULT_SIZE_HIGHSECURITY, KEYSTONE_VERB_REVOKE, POOL_ID_REVOKE, } from './keystone-constants.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -15,32 +15,39 @@ const logalot = GLOBAL_LOG_A_LOT;
 await respecfully(sir, 'Config Builders', async () => {
 
     await ifWe(sir, 'createStandardPoolConfig defaults are correct', async () => {
-        const config = createStandardPoolConfig("test_salt") as KeystonePoolConfig_HashV1;
+        const id = "test_id";
+        const salt = "test_salt";
+        const config = createStandardPoolConfig({ id, salt }) as KeystonePoolConfig_HashV1;
 
-        iReckon(sir, config.salt).willEqual("test_salt");
-        iReckon(sir, config.id).willEqual("test_salt");
-        iReckon(sir, config.type).willEqual("hash-reveal-v1");
+        iReckon(sir, config.id).willEqual(id);
+        iReckon(sir, config.salt).willEqual(salt);
+        iReckon(sir, config.type).willEqual(KeystoneChallengeType.hash_reveal_v1);
 
         // Behavior check
         const b = config.behavior;
-        iReckon(sir, b.size).willEqual(100);
-        iReckon(sir, b.selectSequentially).willEqual(2);
-        iReckon(sir, b.selectRandomly).willEqual(2);
-        iReckon(sir, b.replenish).willEqual("top-up");
+        iReckon(sir, b.size).willEqual(KEYSTONE_CONFIG_DEFAULT_SIZE);
+        iReckon(sir, b.selectSequentially).willEqual(KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL);
+        iReckon(sir, b.selectRandomly).willEqual(KEYSTONE_CONFIG_DEFAULT_RANDOM);
+        iReckon(sir, b.replenish).willEqual(KEYSTONE_CONFIG_DEFAULT_REPLENISH_STRATEGY);
 
         // Verbs should be empty/undefined (permissive)
         iReckon(sir, config.allowedVerbs.length).willEqual(0);
     });
 
     await ifWe(sir, 'createRevocationPoolConfig defaults are correct', async () => {
-        const config = createRevocationPoolConfig("revoke_salt") as KeystonePoolConfig_HashV1;
+        const salt = "revoke_salt";
+        const config = createRevocationPoolConfig({
+            id: POOL_ID_REVOKE,
+            salt,
+        }) as KeystonePoolConfig_HashV1;
 
-        iReckon(sir, config.salt).willEqual("revoke_salt");
+        iReckon(sir, config.id).willEqual(POOL_ID_REVOKE);
+        iReckon(sir, config.salt).willEqual(salt);
 
         // Behavior check
         const b = config.behavior;
-        iReckon(sir, b.size).willEqual(500); // Higher security
-        iReckon(sir, b.replenish).willEqual("scorched-earth");
+        iReckon(sir, b.size).willEqual(KEYSTONE_CONFIG_DEFAULT_SIZE_HIGHSECURITY); // Higher security
+        iReckon(sir, b.replenish).willEqual(KeystoneReplenishStrategy.deleteAll);
 
         // Verbs should be restricted
         iReckon(sir, config.allowedVerbs).includes(KEYSTONE_VERB_REVOKE);

package/src/keystone/keystone-constants.mts

@@ -1,3 +1,6 @@
+import { HashAlgorithm } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { KeystoneReplenishStrategy } from "./keystone-types.mjs";
+
 export const KEYSTONE_ATOM = "keystone";
 
 // #region KeystoneVerb enum
@@ -25,9 +28,9 @@ export const KeystoneVerb = {
     /**
      * The meta-verb used to authorize structural changes to the Keystone,
      * specifically adding or removing challenge pools.
-     * 
+     *
      * "Root access" to the identity.
-     * 
+     *
      * Basically, this is the verb for the "admin" pool.
      */
     MANAGE: KEYSTONE_VERB_MANAGE,
@@ -44,3 +47,19 @@ export function isKeystoneVerb(value: string): value is KeystoneVerb {
 export const POOL_ID_REVOKE = KEYSTONE_VERB_REVOKE;
 export const POOL_ID_MANAGE = KEYSTONE_VERB_MANAGE;
 export const POOL_ID_DEFAULT = "default";
+
+export const KEYSTONE_CONFIG_DEFAULT_SIZE = 200;
+export const KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL = 2;
+export const KEYSTONE_CONFIG_DEFAULT_RANDOM = 2;
+export const KEYSTONE_CONFIG_DEFAULT_BINDING = 5;
+export const KEYSTONE_CONFIG_DEFAULT_REPLENISH_STRATEGY = KeystoneReplenishStrategy.topUp;
+export const KEYSTONE_CONFIG_DEFAULT_HASH_ALGORITHM = HashAlgorithm.sha_256;
+export const KEYSTONE_CONFIG_DEFAULT_HASH_ROUNDS = 1;
+
+export const KEYSTONE_CONFIG_DEFAULT_SIZE_HIGHSECURITY = 2000;
+export const KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL_HIGHSECURITY = 5;
+export const KEYSTONE_CONFIG_DEFAULT_RANDOM_HIGHSECURITY = 5;
+export const KEYSTONE_CONFIG_DEFAULT_BINDING_HIGHSECURITY = 16;
+export const KEYSTONE_CONFIG_DEFAULT_REPLENISH_STRATEGY_HIGHSECURITY = KeystoneReplenishStrategy.replaceAll;
+export const KEYSTONE_CONFIG_DEFAULT_HASH_ALGORITHM_HIGHSECURITY = HashAlgorithm.sha_256;
+export const KEYSTONE_CONFIG_DEFAULT_HASH_ROUNDS_HIGHSECURITY = 10;

package/src/keystone/keystone-helpers.mts

@@ -1,4 +1,5 @@
 import { extractErrorMsg, hash, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { GIB } from "@ibgib/ts-gib/dist/V1/constants.mjs";
 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";
@@ -8,10 +9,17 @@ 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, KeystoneClaim, KeystoneSolution } from "./keystone-types.mjs";
+import {
+    KeystoneData_V1, KeystoneIbGib_V1, KeystoneIb_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";
+import { getDependencyGraph } from "../common/other/graph-helper.mjs";
+import { getTimelinesGroupedByTjp, splitPerTjpAndOrDna } from "../common/other/ibgib-helper.mjs";
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -19,7 +27,7 @@ const logalot = GLOBAL_LOG_A_LOT;
  * space-delimited keystone ib containing select keystone metadata.
  *
  * NOTE: This must match {@link parseKeystoneIb}
- * @see {@link KeystoneIbInfo_V1}
+ * @see {@link KeystoneIb_V1}
  */
 export async function getKeystoneIb({
     keystoneData,
@@ -47,13 +55,13 @@ export async function getKeystoneIb({
 
 /**
  * NOTE: This must match {@link getKeystoneIb}
- * @see {@link KeystoneIbInfo_V1}
+ * @see {@link KeystoneIb_V1}
  */
 export async function parseKeystoneIb({
     ib,
 }: {
     ib: Ib,
-}): Promise<KeystoneIbInfo_V1> {
+}): Promise<KeystoneIb_V1> {
     const lc = `[${parseKeystoneIb.name}]`;
     try {
         if (logalot) { console.log(`${lc} starting... (I: 73cb6832984255ed48b2f44db6a21e25)`); }
@@ -123,7 +131,9 @@ export function getDeterministicRequirements({
         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();
+            const prefixes = gib !== GIB ?
+                gib.substring(0, behavior.targetBindingChars).toLowerCase() :
+                'abc'; // arbitrary for primitive binding target ibgib
 
             for (const char of prefixes) {
                 // Look in the Explicit Bucket
@@ -200,7 +210,7 @@ export function removeFromBindingMap(
 
 /**
  * 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.
  */
@@ -216,7 +226,7 @@ export function resolveTargetPool({
      */
     poolId?: string;
     /**
-     * Optional predicate to find a pool. 
+     * Optional predicate to find a pool.
      * Useful for finding delegates via metadata.
      */
     poolFilter?: (pool: KeystoneChallengePool) => boolean;
@@ -276,7 +286,7 @@ export function resolveTargetPool({
 /**
  * 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({
@@ -312,7 +322,7 @@ export function selectChallengeIds({
                 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 
+            // 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));
@@ -347,7 +357,7 @@ export async function generateOpaqueChallengeId({
 /**
  * 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({
@@ -420,7 +430,7 @@ export async function applyReplenishmentStrategy({
             }
         } else if (strategyType === KeystoneReplenishStrategy.consume) {
             consumedIds.forEach(id => delete pool.challenges[id]);
-        } else if (strategyType === KeystoneReplenishStrategy.scorchedEarth) {
+        } else if (strategyType === KeystoneReplenishStrategy.deleteAll) {
             pool.challenges = {};
             pool.bindingMap = {};
         } else {
@@ -441,7 +451,7 @@ export async function applyReplenishmentStrategy({
  * 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({
@@ -512,7 +522,7 @@ export async function solveAndReplenish({
 /**
  * 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({
@@ -525,7 +535,9 @@ export async function validateKeystoneTransition({
     const lc = `[${validateKeystoneTransition.name}]`;
     const errors: string[] = [];
     try {
-        if (!currentIbGib) { throw new Error(`(UNEXPECTED) currentIbGib falsy? (E: 3c0f02655fa8279e386a079ebb604b25)`); }
+        if (!currentIbGib) {
+            throw new Error(`(UNEXPECTED) currentIbGib falsy? (E: 3c0f02655fa8279e386a079ebb604b25)`);
+        }
         if (!prevIbGib) { throw new Error(`(UNEXPECTED) prevIbGib falsy? (E: 0d07c812634d839c784f31b8848ba825)`); }
 
         // intrinsic validation
@@ -777,4 +789,78 @@ export async function createKeystoneIbGibImpl({
     } finally {
         if (logalot) { console.log(`${lc} complete.`); }
     }
+}
+
+export async function validateKeystoneGraph({
+    keystoneIbGib,
+    space,
+}: {
+    keystoneIbGib: KeystoneIbGib_V1,
+    space: IbGibSpaceAny,
+}): Promise<string[]> {
+    const lc = `[${validateKeystoneGraph.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 22e1ca1d5a08a3f90b7fe9da95df7b26)`); }
+
+        // maybe too defensive but...
+        if (!keystoneIbGib) { throw new Error(`(UNEXPECTED) keystoneIbGib falsy? (E: 26482871d529fff6e8899c5d8a6c3826)`); }
+
+        const errors: string[] = [];
+
+        const dependencyGraph = await getDependencyGraph({
+            ibGib: keystoneIbGib,
+            space,
+        });
+
+        const depIbGibs = Object.values(dependencyGraph);
+        const { mapWithTjp_NoDna, mapWithTjp_YesDna, mapWithoutTjps, } =
+            splitPerTjpAndOrDna({ ibGibs: depIbGibs });
+
+
+        // there should be no DNA
+        if (Object.keys(mapWithTjp_YesDna).length > 0) {
+            errors.push(`${lc} DNA found. Keystones should NOT have DNA. (E: a3ec7827c4284cdea61c2372c0615826)`);
+        }
+
+        // is there a tjp? I think there is, so mapWithoutTjps should also be
+        // empty
+        if (Object.keys(mapWithoutTjps).length > 0) {
+            errors.push(`${lc} Non-tjp ibgibs found? Keystones are expected to have tjps. (E: a3ec7827c4284cdea61c2372c0615826)`);
+        }
+
+        if (Object.keys(mapWithTjp_NoDna).length > 0) {
+            // happy path here. These should be the keystone ibgibs. we will put
+            // them in order, then do validation on the transitions. We will
+            // also check other graph-scoped integrity of keystones (like do
+            // certain properties match among ALL keystones, etc.)
+
+            const keystoneIbGibs_unordered = Object.values(mapWithTjp_NoDna);
+
+            const orderedKeystonesMap = getTimelinesGroupedByTjp({ ibGibs: keystoneIbGibs_unordered });
+            const keys = Object.keys(orderedKeystonesMap);
+            if (keys.length === 0) {
+                throw new Error(`(UNEXPECTED) orderedKeystonesMap empty? (E: d437b80bef58e83a034b28af46278726)`);
+            } else if (keys.length > 0) {
+                // keys.length > 0
+                throw new Error(`(UNEXPECTED) more than one timeline in keystone graph? ATOW (02/19/2026) we are expecting only a single timeline. (E: 66085b14e3887a59c872afd240511f26)`);
+            }
+            // happy path: exactly one timeline
+            const keystoneTjpAddr = keys[0];
+            const keystoneIbGibs_ordered = orderedKeystonesMap[keystoneTjpAddr];
+
+        } else {
+            // one of the other errors regarding mapWithTjp_YesDna or
+            // mapWithoutTjps will exist at this point, so we don't need to add
+            // any more errors.
+            if (errors.length === 0) { throw new Error(`(UNEXPECTED) mapWithTjp_NoDna empty (which is an error) but errors.length === 0? If we get here, we expect one of the other errors to have been populated. (E: 7bca2866b6f8fca318923de8c88e8826)`); }
+        }
+
+        return errors;
+
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
 }