@ibgib/core-gib 0.1.43 → 0.1.44

package/dist/sync/sync-types.d.mts

@@ -159,6 +159,17 @@ export interface SyncRel8ns_V1 extends IbGibRel8ns_V1 {
      * This MUST point to the specific Keystone Frame that authorizes this sync frame.
      */
     identity?: string[];
+    /**
+     * Session keystones used for signing saga frames.
+     *
+     * Array contains addresses of keystone evolution chain:
+     * - Index 0: Genesis keystone (dual-pool architecture)
+     * - Index N: Latest evolved keystone after signing operations
+     *
+     * Each sync endpoint retrieves the session keystone from this rel8n
+     * rather than searching spaces. Keystones are stored in durable spaces.
+     */
+    sessionKeystones?: IbGibAddr[];
     /**
      * The message stone that contains the information about the particular
      * stage of the sync process we are in.

package/dist/sync/sync-types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-types.d.mts","sourceRoot":"","sources":["../../src/sync/sync-types.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEzF,OAAO,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,MAAM,iDAAiD,CAAC;AAC1F,OAAO,EAAE,gBAAgB,EAAG,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,oBAAoB,EAAG,MAAM,sBAAsB,CAAC;AAI7F,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAwB,uBAAuB,EAAE,MAAM,iDAAiD,CAAC;AAIhH,eAAO,MAAM,cAAc,SAAS,CAAC;AACrC,eAAO,MAAM,cAAc,SAAS,CAAC;AACrC,eAAO,MAAM,cAAc,SAAS,CAAC;AACrC,MAAM,MAAM,QAAQ,GACd,OAAO,cAAc,GACrB,OAAO,cAAc,GACrB,OAAO,cAAc,CAAC;AAC5B,eAAO,MAAM,QAAQ;;;;CAIsB,CAAC;AAC5C,eAAO,MAAM,sBAAsB,8BAA0B,CAAC;AAC9D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,QAAQ,CAE9D;AAID,eAAO,MAAM,6BAA6B,WAAW,CAAC;AACtD,eAAO,MAAM,+BAA+B,aAAa,CAAC;AAC1D,MAAM,MAAM,mBAAmB,GACzB,OAAO,6BAA6B,GACpC,OAAO,+BAA+B,CACvC;AACL;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;IAC5B;;OAEG;;IAEH;;;;OAIG;;CAE0D,CAAC;AAClE,eAAO,MAAM,mCAAmC,2BAAqC,CAAC;AACtF,wBAAgB,0BAA0B,CAAC,eAAe,EAAE,MAAM,GAAG,eAAe,IAAI,mBAAmB,CAE1G;AAGD,MAAM,WAAW,uBAAuB;IACpC,KAAK,EAAE,YAAY,CAAC;IACpB,mBAAmB,CAAC,EAAE,QAAQ,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,SAAS,CAAC;CAC5B;AACD,MAAM,WAAW,8BAA8B;IAC3C,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,mBAAmB,CAAC,EAAE,KAAK,CAAC;IAC5B,aAAa,CAAC,EAAE,KAAK,CAAC;IACtB,YAAY,EAAE,IAAI,CAAC;CACtB;AACD;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,uBAAuB,GAAG,8BAA8B,CAAC;AAE7D,MAAM,WAAW,oCAAoC;IACjD;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,aAAa,CAAC,EAAE,iBAAiB,CAAC;CACrC;AACD,MAAM,WAAW,qCAAsC,SAAQ,oCAAoC;IAC/F,aAAa,EAAE,iBAAiB,CAAC;CACpC;AACD,MAAM,WAAW,qCAAsC,SAAQ,oCAAoC;IAC/F,QAAQ,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,MAAM,+BAA+B,GAAG,qCAAqC,GAAG,qCAAqC,CAAC;AAE5H,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC,uBAAuB,CAAC,CAAC;IAElD;;OAEG;IACH,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IACzC,SAAS,EAAE,YAAY,CAAC;IAExB,SAAS,EAAE,uBAAuB,EAAE,CAAC;IACrC,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACpC;;OAEG;IACH,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB;;OAEG;IACH,YAAY,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,EAAE,CAAA;KAAE,CAAC;IAC5C;;OAEG;IACH,2BAA2B,EAAE,SAAS,EAAE,CAAC;IACzC;;OAEG;IACH,SAAS,EAAE,cAAc,CAAC;CAC7B;AAGD,MAAM,WAAW,SAAS;IACtB,IAAI,EAAE,OAAO,SAAS,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAY,SAAQ,YAAY;IAC7C;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB;;OAEG;IACH,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;IAExC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,aAAc,SAAQ,cAAc;IACjD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;OAGG;IACH,CAAC,mBAAmB,CAAC,EAAE,SAAS,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,YAAa,SAAQ,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC;CAAI"}
+{"version":3,"file":"sync-types.d.mts","sourceRoot":"","sources":["../../src/sync/sync-types.mts"],"names":[],"mappings":"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"}

package/dist/sync/sync-types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sync-types.mjs","sourceRoot":"","sources":["../../src/sync/sync-types.mts"],"names":[],"mappings":"AAMA,OAAO,EAAa,mBAAmB,GAAyB,MAAM,sBAAsB,CAAC;AAQ7F,mBAAmB;AACnB,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AACrC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AACrC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAKrC,MAAM,CAAC,MAAM,QAAQ,GAAG;IACpB,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,cAAc;CACmB,CAAC;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC9D,MAAM,UAAU,eAAe,CAAC,IAAY;IACxC,OAAO,sBAAsB,CAAC,QAAQ,CAAC,IAAgB,CAAC,CAAC;AAC7D,CAAC;AACD,sBAAsB;AAEtB,8BAA8B;AAC9B,MAAM,CAAC,MAAM,6BAA6B,GAAG,QAAQ,CAAC;AACtD,MAAM,CAAC,MAAM,+BAA+B,GAAG,UAAU,CAAC;AAK1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAC/B;;OAEG;IACH,MAAM,EAAE,6BAA6B;IACrC;;;;OAIG;IACH,QAAQ,EAAE,+BAA+B;CACoB,CAAC;AAClE,MAAM,CAAC,MAAM,mCAAmC,GAAG,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;AACtF,MAAM,UAAU,0BAA0B,CAAC,eAAuB;IAC9D,OAAO,mCAAmC,CAAC,QAAQ,CAAC,eAAsC,CAAC,CAAC;AAChG,CAAC;AAiJD,0CAA0C"}
+{"version":3,"file":"sync-types.mjs","sourceRoot":"","sources":["../../src/sync/sync-types.mts"],"names":[],"mappings":"AAMA,OAAO,EAAa,mBAAmB,GAAyB,MAAM,sBAAsB,CAAC;AAQ7F,mBAAmB;AACnB,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AACrC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AACrC,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAKrC,MAAM,CAAC,MAAM,QAAQ,GAAG;IACpB,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,cAAc;CACmB,CAAC;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC9D,MAAM,UAAU,eAAe,CAAC,IAAY;IACxC,OAAO,sBAAsB,CAAC,QAAQ,CAAC,IAAgB,CAAC,CAAC;AAC7D,CAAC;AACD,sBAAsB;AAEtB,8BAA8B;AAC9B,MAAM,CAAC,MAAM,6BAA6B,GAAG,QAAQ,CAAC;AACtD,MAAM,CAAC,MAAM,+BAA+B,GAAG,UAAU,CAAC;AAK1D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IAC/B;;OAEG;IACH,MAAM,EAAE,6BAA6B;IACrC;;;;OAIG;IACH,QAAQ,EAAE,+BAA+B;CACoB,CAAC;AAClE,MAAM,CAAC,MAAM,mCAAmC,GAAG,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;AACtF,MAAM,UAAU,0BAA0B,CAAC,eAAuB;IAC9D,OAAO,mCAAmC,CAAC,QAAQ,CAAC,eAAsC,CAAC,CAAC;AAChG,CAAC;AA6JD,0CAA0C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/core-gib",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "description": "ibgib core functionality, including base architecture for witnesses, spaces, apps, robbots, etc., as well as shared utility functions. Node v19+ needed for heavily-used isomorphic webcrypto hashing consumed in both node and browsers.",
   "funding": {
     "type": "individual",

package/src/keystone/README.md

@@ -28,7 +28,8 @@ Keystones organize challenges into **pools** with specific purposes:
 Each pool configuration specifies:
 *   **`poolId`**: Unique identifier within the keystone
 *   **`verb`**: Auto-routes operations (e.g., `revoke`, `manage`, `login`)
-*   **`replenishStrategy`**: `'top-up'` (reusable) or `'scorched-earth'` (burn after use)
+*   **`replenishStrategy`**: What to do after using challenges in a pool, e.g.
+    `'top-up'`, `'replace-all'`, `'delete-all'`, etc.
 *   **`challengeCount`**: Number of hash challenges in the pool
 
 ## Basic Usage
@@ -39,8 +40,8 @@ Each pool configuration specifies:
 const keystone = await keystoneService.genesis({
   masterSecret: "user-password",
   configs: [
-    { poolId: 'default', challengeCount: 100, replenishStrategy: 'top-up' },
-    { poolId: 'revoke', verb: 'revoke', challengeCount: 10, replenishStrategy: 'scorched-earth' }
+    { poolId: 'default', challengeCount: 100, replenishStrategy: KeystoneReplenishStrategy.topUp },
+    { poolId: 'revoke', verb: 'revoke', challengeCount: 10, replenishStrategy: KeystoneReplenishStrategy.deleteAll }
   ],
   metaspace,
   space

package/src/keystone/docs/architecture.md

@@ -74,7 +74,9 @@ Inputs: `LatestKeystone`, `Claim`, `MasterSecret`.
 3.  **Solving**: Generates solutions.
 4.  **Replenishment**: Adds new challenges based on pool's `replenishStrategy`:
     *   **`'top-up'`**: Refills consumed challenges (default, reusable identity)
-    *   **`'scorched-earth'`**: Burns challenges permanently (revocation, one-time operations)
+    *   **`'replace-all'`**: Establishes completely new challenges (mitigate long-term pre-image attacks)
+    *   **`'consume'`**: Do not re-add any challenges (limited number of uses)
+    *   **`'delete-all'`**: Removes all challenges permanently (revocation, one-time operations)
 
 ### 5.3 Validate
 Inputs: `PreviousFrame`, `CurrentFrame`.

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

@@ -0,0 +1,34 @@
+/**
+ * KDF Strategy Constants
+ *
+ * Defines available key derivation function strategies.
+ */
+
+// #region KdfStrategy
+export const KDF_STRATEGY_RECURSIVE_SALT_WRAP = 'recursive-salt-wrap';
+export type KdfStrategy =
+    | typeof KDF_STRATEGY_RECURSIVE_SALT_WRAP
+    ;
+
+/**
+ * Available KDF strategies for deriving keys from master secrets.
+ *
+ * - `recursive-salt-wrap`: Hash(salt + current + salt) ^ rounds
+ *   Used by KeystoneStrategy_HashRevealV1 for pool secret derivation
+ */
+export const KdfStrategy = {
+    /**
+     * Recursive salt wrap strategy: Hash(salt + current + salt) ^ rounds
+     *
+     * This is the primary strategy used by keystones for deriving pool secrets
+     * from master secrets with configurable rounds for key stretching.
+     */
+    recursive_salt_wrap: KDF_STRATEGY_RECURSIVE_SALT_WRAP,
+} satisfies { [key: string]: KdfStrategy };
+
+export const KDF_STRATEGY_VALID_VALUES = Object.values(KdfStrategy);
+
+export function isValidKdfStrategy(strategy: string): strategy is KdfStrategy {
+    return KDF_STRATEGY_VALID_VALUES.includes(strategy as KdfStrategy);
+}
+// #endregion KdfStrategy

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

@@ -0,0 +1,105 @@
+import { extractErrorMsg, hash, HashAlgorithm } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../core-constants.mjs';
+import { KDF_STRATEGY_RECURSIVE_SALT_WRAP, KDF_STRATEGY_VALID_VALUES, KdfStrategy } from './kdf-constants.mjs';
+import { DeriveKeyParams, KdfOptions_RecursiveSaltWrap } from './kdf-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Derive a key from a master secret using the specified KDF strategy
+ *
+ * This is the main dispatch function for all KDF operations. It routes to the
+ * appropriate strategy implementation based on `kdfOpts.strategy`.
+ *
+ * @param params - Derivation parameters including master secret and KDF options
+ * @returns Derived key
+ *
+ * @example
+ * ```typescript
+ * const derivedKey = await deriveKey({
+ *     masterSecret: 'my-strong-password',
+ *     kdfOpts: {
+ *         strategy: KdfStrategy.recursiveSaltWrap,
+ *         salt: 'pool-identifier',
+ *         rounds: 10000,
+ *         algorithm: 'SHA-256'
+ *     }
+ * });
+ * ```
+ */
+export async function deriveKey({
+    masterSecret,
+    kdfOpts
+}: DeriveKeyParams): Promise<string> {
+    const lc = `[${deriveKey.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 268e87ec311874ee6822bf459c5a5426)`); }
+
+        const strategy = kdfOpts.strategy;
+
+        switch (strategy) {
+            case KdfStrategy['recursive-salt-wrap']:
+                return await kdf_recursiveSaltWrap({
+                    masterSecret,
+                    salt: kdfOpts.salt,
+                    rounds: kdfOpts.rounds,
+                    algorithm: kdfOpts.algorithm
+                });
+            default:
+                throw new Error(`Unknown KDF strategy: ${strategy}. valid values: ${KDF_STRATEGY_VALID_VALUES.join(', ')} (E: a1b2c3d4e5f6g7h8i9j0)`);
+        }
+
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * Recursive Salt Wrap KDF Strategy
+ *
+ * Derives a key by recursively applying: Hash(salt + current + salt) for N rounds
+ *
+ * This is the strategy used by KeystoneStrategy_HashRevealV1 for deriving pool secrets.
+ *
+ * @param masterSecret - The initial secret/password to derive from
+ * @param salt - Salt value to wrap around the secret
+ * @param rounds - Number of hash iterations (key stretching)
+ * @param algorithm - Hash algorithm to use (default: SHA-256)
+ * @returns Derived key
+ */
+export async function kdf_recursiveSaltWrap({
+    masterSecret,
+    salt,
+    rounds,
+    algorithm = HashAlgorithm.sha_256,
+}: {
+    masterSecret: string;
+    salt: string;
+    rounds: number;
+    algorithm?: HashAlgorithm;
+}): Promise<string> {
+    const lc = `[${kdf_recursiveSaltWrap.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 850868e50aba82ff28c77da8169e4c26)`); }
+
+        let current = masterSecret;
+
+        for (let i = 0; i < rounds; i++) {
+            current = await hash({
+                s: `${salt}${current}${salt}`,
+                algorithm
+            });
+        }
+
+        return current;
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

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);