@ibgib/core-gib 0.1.42 → 0.1.44

package/dist/test/mock-space.mjs

@@ -1,79 +1,74 @@
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-/**
- * A simple in-memory map acting as a Space.
- * Pure Storage. No Indexing logic.
- *
- * Copied/Adapted from Keystone Respecs.
- */
-export class MockIbGibSpace {
-    name;
-    store = new Map();
-    constructor(name = "mock_space") {
-        this.name = name;
-    }
-    async put({ ibGib }) {
-        const addr = getIbGibAddr({ ibGib });
-        this.store.set(addr, JSON.parse(JSON.stringify(ibGib))); // Deep copy
-    }
-    async get({ addr }) {
-        const data = this.store.get(addr);
-        return data ? JSON.parse(JSON.stringify(data)) : null;
-    }
-    async witness(arg) {
-        const cmd = arg.data?.cmd;
-        if (cmd === 'get') {
-            const addrs = arg.data.ibGibAddrs || [];
-            const ibGibs = [];
-            for (const addr of addrs) {
-                const ig = await this.get({ addr });
-                if (ig)
-                    ibGibs.push(ig);
-            }
-            return { ibGibs };
-        }
-        if (cmd === 'put') {
-            const ibGibs = arg.ibGibs || [];
-            for (const ibGib of ibGibs) {
-                await this.put({ ibGib });
-            }
-            return { ibGibs: [] }; // Return empty result or whatever witness expects
-        }
-        return undefined;
-    }
-}
-/**
- * A partial mock of Metaspace.
- */
-export class MockMetaspaceService {
-    space;
-    /**
-     * Map of TJP Gib (Timeline ID) -> Latest IbGib Addr (Head)
-     */
-    timelineHeads = new Map();
-    constructor(space) {
-        this.space = space;
-    }
-    async getLocalUserSpace({ lock }) {
-        return this.space;
-    }
-    async put(args) {
-        const target = args.space || this.space;
-        return target.put(args);
-    }
-    async registerNewIbGib(args) {
-        const { ibGib } = args;
-        const targetSpace = args.space || this.space;
-        // 1. Ensure it is stored
-        await targetSpace.put({ ibGib });
-        // 2. Extract TJP
-        const gib = ibGib.gib || '';
-        let tjpGib = gib;
-        if (gib.includes('.')) {
-            const parts = gib.split('.');
-            tjpGib = parts.slice(1).join('.');
-        }
-        const addr = getIbGibAddr({ ibGib });
-        this.timelineHeads.set(tjpGib, addr);
-    }
-}
+// import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+// import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+export {};
+// /**
+//  * A simple in-memory map acting as a Space.
+//  * Pure Storage. No Indexing logic.
+//  *
+//  * Copied/Adapted from Keystone Respecs.
+//  */
+// export class MockIbGibSpace {
+//     store = new Map<string, IbGib_V1>();
+//     constructor(public name: string = "mock_space") { }
+//     async put({ ibGib }: { ibGib: IbGib_V1 }): Promise<void> {
+//         const addr = getIbGibAddr({ ibGib });
+//         this.store.set(addr, JSON.parse(JSON.stringify(ibGib))); // Deep copy
+//     }
+//     async get({ addr }: { addr: string }): Promise<IbGib_V1 | null> {
+//         const data = this.store.get(addr);
+//         return data ? JSON.parse(JSON.stringify(data)) : null;
+//     }
+//     async witness(arg: any): Promise<any> {
+//         const cmd = arg.data?.cmd;
+//         if (cmd === 'get') {
+//             const addrs = arg.data.ibGibAddrs || [];
+//             const ibGibs: IbGib_V1[] = [];
+//             for (const addr of addrs) {
+//                 const ig = await this.get({ addr });
+//                 if (ig) ibGibs.push(ig);
+//             }
+//             return { ibGibs };
+//         }
+//         if (cmd === 'put') {
+//             const ibGibs = arg.ibGibs || [];
+//             for (const ibGib of ibGibs) {
+//                 await this.put({ ibGib });
+//             }
+//             return { ibGibs: [] }; // Return empty result or whatever witness expects
+//         }
+//         return undefined;
+//     }
+// }
+// /**
+//  * A partial mock of Metaspace.
+//  */
+// export class MockMetaspaceService {
+//     /**
+//      * Map of TJP Gib (Timeline ID) -> Latest IbGib Addr (Head)
+//      */
+//     timelineHeads = new Map<string, string>();
+//     constructor(public space: MockIbGibSpace) { }
+//     async getLocalUserSpace({ lock }: { lock: boolean }): Promise<MockIbGibSpace> {
+//         return this.space;
+//     }
+//     async put(args: any): Promise<void> {
+//         const target = args.space || this.space;
+//         return target.put(args);
+//     }
+//     async registerNewIbGib(args: { ibGib: IbGib_V1, space?: any }): Promise<void> {
+//         const { ibGib } = args;
+//         const targetSpace = args.space || this.space;
+//         // 1. Ensure it is stored
+//         await targetSpace.put({ ibGib });
+//         // 2. Extract TJP
+//         const gib = ibGib.gib || '';
+//         let tjpGib = gib;
+//         if (gib.includes('.')) {
+//             const parts = gib.split('.');
+//             tjpGib = parts.slice(1).join('.');
+//         }
+//         const addr = getIbGibAddr({ ibGib });
+//         this.timelineHeads.set(tjpGib, addr);
+//     }
+// }
 //# sourceMappingURL=mock-space.mjs.map

package/dist/test/mock-space.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mock-space.mjs","sourceRoot":"","sources":["../../src/test/mock-space.mts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAGJ;IAFnB,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEpC,YAAmB,OAAe,YAAY;QAA3B,SAAI,GAAJ,IAAI,CAAuB;IAAI,CAAC;IAEnD,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,EAAuB;QACpC,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY;IACzE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAoB;QAChC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAQ;QAClB,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC;QAC1B,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YAChB,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;YACxC,MAAM,MAAM,GAAe,EAAE,CAAC;YAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACvB,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;gBACpC,IAAI,EAAE;oBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC5B,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,CAAC;QACtB,CAAC;QACD,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;YAChC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBACzB,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YAC9B,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,kDAAkD;QAC7E,CAAC;QACD,OAAO,SAAS,CAAC;IACrB,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,OAAO,oBAAoB;IAOV;IALnB;;OAEG;IACH,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,YAAmB,KAAqB;QAArB,UAAK,GAAL,KAAK,CAAgB;IAAI,CAAC;IAE7C,KAAK,CAAC,iBAAiB,CAAC,EAAE,IAAI,EAAqB;QAC/C,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAS;QACf,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC;QACxC,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,IAAsC;QACzD,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;QACvB,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC;QAE7C,yBAAyB;QACzB,MAAM,WAAW,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAEjC,iBAAiB;QACjB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC;QAC5B,IAAI,MAAM,GAAG,GAAG,CAAC;QACjB,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,MAAM,IAAI,GAAG,YAAY,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;CACJ"}
+{"version":3,"file":"mock-space.mjs","sourceRoot":"","sources":["../../src/test/mock-space.mts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,gEAAgE;;AAEhE,MAAM;AACN,+CAA+C;AAC/C,sCAAsC;AACtC,KAAK;AACL,2CAA2C;AAC3C,MAAM;AACN,gCAAgC;AAChC,2CAA2C;AAE3C,0DAA0D;AAE1D,iEAAiE;AACjE,gDAAgD;AAChD,gFAAgF;AAChF,QAAQ;AAER,wEAAwE;AACxE,6CAA6C;AAC7C,iEAAiE;AACjE,QAAQ;AAER,8CAA8C;AAC9C,qCAAqC;AACrC,+BAA+B;AAC/B,uDAAuD;AACvD,6CAA6C;AAC7C,0CAA0C;AAC1C,uDAAuD;AACvD,2CAA2C;AAC3C,gBAAgB;AAChB,iCAAiC;AACjC,YAAY;AACZ,+BAA+B;AAC/B,+CAA+C;AAC/C,4CAA4C;AAC5C,6CAA6C;AAC7C,gBAAgB;AAChB,wFAAwF;AACxF,YAAY;AACZ,4BAA4B;AAC5B,QAAQ;AACR,IAAI;AAEJ,MAAM;AACN,kCAAkC;AAClC,MAAM;AACN,sCAAsC;AAEtC,UAAU;AACV,kEAAkE;AAClE,UAAU;AACV,iDAAiD;AAEjD,oDAAoD;AAEpD,sFAAsF;AACtF,6BAA6B;AAC7B,QAAQ;AAER,4CAA4C;AAC5C,mDAAmD;AACnD,mCAAmC;AACnC,QAAQ;AAER,sFAAsF;AACtF,kCAAkC;AAClC,wDAAwD;AAExD,oCAAoC;AACpC,4CAA4C;AAE5C,4BAA4B;AAC5B,uCAAuC;AACvC,4BAA4B;AAC5B,mCAAmC;AACnC,4CAA4C;AAC5C,iDAAiD;AACjD,YAAY;AACZ,gDAAgD;AAChD,gDAAgD;AAChD,QAAQ;AACR,IAAI"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/core-gib",
-  "version": "0.1.42",
+  "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

@@ -16,5 +16,124 @@ Validation in this system is **Auditability**: to verify an identity (e.g., "Is
 3.  **Hash-based**: Uses hash pre-imaging for quantum resistance (`hash-reveal-v1`).
 4.  **Merkle Graphs**: Efficient communication by only transmitting missing graph nodes.
 
+## Challenge Pools
+
+Keystones organize challenges into **pools** with specific purposes:
+
+*   **Default Pool**: General-purpose signing operations
+*   **Revoke Pool**: Permanent identity termination (one-time use, `verb: revoke`)
+*   **Manage Pool**: Structural changes like adding pools (`verb: manage`)
+*   **Foreign Pools**: Delegation to external identities (SSO-like workflows)
+
+Each pool configuration specifies:
+*   **`poolId`**: Unique identifier within the keystone
+*   **`verb`**: Auto-routes operations (e.g., `revoke`, `manage`, `login`)
+*   **`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
+
+### Genesis (Create Identity)
+
+```typescript
+const keystone = await keystoneService.genesis({
+  masterSecret: "user-password",
+  configs: [
+    { poolId: 'default', challengeCount: 100, replenishStrategy: KeystoneReplenishStrategy.topUp },
+    { poolId: 'revoke', verb: 'revoke', challengeCount: 10, replenishStrategy: KeystoneReplenishStrategy.deleteAll }
+  ],
+  metaspace,
+  space
+});
+```
+
+### Sign a Claim
+
+```typescript
+const signedKeystone = await keystoneService.sign({
+  latestKeystone: keystone,
+  claim: { action: 'login', timestamp: Date.now() },
+  masterSecret: "user-password",
+  poolId: 'default', // or use verb-based auto-routing
+  metaspace,
+  space
+});
+```
+
+### Revoke Identity
+
+```typescript
+await keystoneService.revoke({
+  latestKeystone: keystone,
+  reason: "Device compromised",
+  masterSecret: "user-password",
+  metaspace,
+  space
+});
+```
+
+## Delegation via Foreign Pools
+
+> [!IMPORTANT]
+> **🔑 Foreign pools enable delegation** - Alice can grant Bob signing authority for specific operations.
+
+Alice can delegate signing authority to Bob by adding his challenge pool:
+
+```typescript
+const aliceWithBobPool = await keystoneService.addPools({
+  latestKeystone: aliceKeystone,
+  newPoolConfigs: [
+    {
+      poolId: 'bob-sso',
+      verb: 'login',
+      foreignServerUrl: 'https://bob-server.com',
+      challengeCount: 50
+    }
+  ],
+  masterSecret: aliceSecret,
+  metaspace,
+  space
+});
+```
+
+Now Bob can sign login claims on Alice's behalf, but only for operations using the `login` verb.
+
+**Trust Model**:
+- Alice validates Bob's pool **shape** when adding (via `validateChallengePool`)
+- Bob never transmits his secrets
+- Communication secured via TLS
+- Bob can validate his pool section when Alice evolves keystone
+
+## Validation
+
+To verify a keystone timeline:
+
+1. **Replay** from genesis to current frame
+2. **Verify** each proof's hash pre-images match challenges
+3. **Validate** challenge selection matches policy engine rules
+4. **Check** revocation status (if revoked, identity cannot evolve)
+
+Validation helpers:
+*   `validateEvolution()`: Verifies transition from previous to current frame
+*   `validateKeystoneTimeline()`: Replays entire timeline from genesis
+
+## Integration with Sync
+
+Keystones integrate with the sync protocol to provide **session identity**:
+
+*   **Session Keystones**: Ephemeral identities created per sync saga
+*   **Saga Binding**: Session keystone salted with `sagaId`
+*   **Signature Frames**: Each saga frame can be signed with session identity
+
+> [!CAUTION]
+> **🚧 Session identity integration is NOT yet functional.** See [sync README](file:../sync/README.md#session-identity-usesessionidentity) for current status.
+
 ## Implementation
+
 The v1 implementation creates a pure TypeScript, isomorphic, hash-based identity system. It is designed to be "Non-Evil" and "Graph-Native".
+
+**Key Files**:
+*   [keystone-service-v1.mts](file:./keystone-service-v1.mts): Core service implementation
+*   [keystone-types.mts](file:./keystone-types.mts): TypeScript type definitions
+*   [keystone-helpers.mts](file:./keystone-helpers.mts): Utility functions

package/src/keystone/docs/architecture.md

@@ -14,6 +14,33 @@
 *   **Challenge Pool**: A collection of puzzles stored in each Keystone Frame.
 *   **Constraint/Policy Engine**: Logic that determines *which* challenges must be solved to authorize a specific action (Binding, FIFO, Stochastic).
 
+### Foreign Pools (Delegation)
+
+> [!IMPORTANT]
+> **🔀 Keystones support delegation** by embedding challenges from external identities.
+
+**Mechanism**:
+*   **Use Case**: Alice adds Bob's challenge pool to her keystone
+*   **Validation**: Alice validates Bob's pool **shape** when adding (via `validateChallengePool`)
+*   **Signing**: Bob can sign claims on Alice's behalf (limited by `verb` field)
+*   **Trust Model**:
+    - Bob never transmits secrets across network
+    - Communication secured via TLS
+    - Bob can validate his pool section when Alice evolves keystone
+*   **SSO Pattern**: Enables Single Sign-On workflows without shared secrets
+
+**Configuration**:
+```typescript
+{
+  poolId: 'bob-sso',
+  verb: 'login',
+  foreignServerUrl: 'https://bob-server.com',
+  challengeCount: 50
+}
+```
+
+See [KeystoneService_V1.addPools()](file:../keystone-service-v1.mts) for implementation.
+
 ## 3. Policy Engine (Selection & Mitigation)
 
 To prevent replay attacks by Man-in-the-Middle (MITM) actors, the challenges required to sign a frame are selected via a multi-layered pipeline:
@@ -45,7 +72,11 @@ Inputs: `LatestKeystone`, `Claim`, `MasterSecret`.
 1.  **Auto-Routing**: Selects pool based on Verb (e.g., 'revoke').
 2.  **Selection**: Runs Policy Engine.
 3.  **Solving**: Generates solutions.
-4.  **Replenishment**: Adds new challenges (Top-Up) or burns them.
+4.  **Replenishment**: Adds new challenges based on pool's `replenishStrategy`:
+    *   **`'top-up'`**: Refills consumed challenges (default, reusable identity)
+    *   **`'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;
+}