@ibgib/core-gib 0.1.63 → 0.1.65

package/src/keystone/keystone-service-v1.mts

@@ -1,4 +1,4 @@
-import { extractErrorMsg, mergeMapsOrArrays_Naive } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { extractErrorMsg, mergeMapsOrArrays_Naive, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getIbGibAddr, getIbAndGib } from '@ibgib/ts-gib/dist/helper.mjs';
 import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
 import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
@@ -7,18 +7,24 @@ import { GLOBAL_LOG_A_LOT } from '../core-constants.mjs';
 import {
     KeystoneData_V1, KeystoneIbGib_V1, KeystonePoolConfig, KeystoneClaim,
     KeystoneChallengePool, KeystoneReplenishStrategy, KeystoneRevocationInfo,
-    DelegateKeystoneStatus,
+    DelegateKeystoneStatus, KeystoneClaimType,
+    ClaimDetails_AddPool, ClaimDetails_RemovePool, ClaimDetails_ReplacePool, ClaimDetails_ChangePassword
 } from './keystone-types.mjs';
 import { KeystoneStrategyFactory } from './strategy/keystone-strategy-factory.mjs';
+import { createStandardPoolConfig } from './keystone-config-builder.mjs';
 import {
     POOL_ID_REVOKE, KEYSTONE_VERB_REVOKE, KEYSTONE_VERB_MANAGE,
-    KEYSTONE_CHECKPOINT_FREQUENCY, POOL_ID_MANAGE, KEYSTONE_VERB_SYNC
+    KEYSTONE_CHECKPOINT_FREQUENCY, POOL_ID_MANAGE, KEYSTONE_VERB_SYNC,
+    POOL_ID_CUSTODIAN_MANAGE,
+    KEYSTONE_CONFIG_DEFAULT_SIZE, KEYSTONE_CONFIG_DEFAULT_SEQUENTIAL,
+    KEYSTONE_CONFIG_DEFAULT_RANDOM, KEYSTONE_CONFIG_DEFAULT_BINDING
 } from './keystone-constants.mjs';
 import {
     createKeystoneIbGibImpl, evolvePersistAndRegisterKeystone,
     generateOpaqueChallengeId, resolveTargetPool, selectChallengeIds,
     solveAndReplenish, validateKeystoneTransition,
-    validateGenesisKeystone, validateKeystoneGraph
+    validateGenesisKeystone, validateKeystoneGraph,
+    generatePoolChallenges, rotatePoolChallenges, verifyPoolSecret
 } from './keystone-helpers.mjs';
 import { getLatestAddrs } from '../witness/space/space-helper.mjs';
 import { IbGibSpaceAny } from '../witness/space/space-base-v1.mjs';
@@ -45,12 +51,14 @@ export class KeystoneService_V1 {
         configs,
         metaspace,
         space,
+        isPrimary,
     }: {
         masterSecret: string;
         frameDetails?: any;
         configs: KeystonePoolConfig[];
         metaspace: MetaspaceService;
         space: IbGibSpaceAny;
+        isPrimary?: boolean;
     }): Promise<KeystoneIbGib_V1> {
         const lc = `${this.lc}[${this.genesis.name}]`;
         try {
@@ -59,24 +67,10 @@ export class KeystoneService_V1 {
             const challengePools: KeystoneChallengePool[] = [];
 
             for (const config of configs) {
-                const strategy = KeystoneStrategyFactory.create({ config });
-                const poolSecret = await strategy.derivePoolSecret({ masterSecret });
-                const challenges: { [id: string]: any } = {};
-
-                const targetSize = config.behavior.size;
-                const timestamp = Date.now().toString();
-
-                for (let i = 0; i < targetSize; i++) {
-                    const challengeId = await generateOpaqueChallengeId({
-                        salt: config.salt, timestamp, index: i
-                    });
-
-                    const solution = await strategy.generateSolution({
-                        poolSecret, poolId: config.id, challengeId,
-                    });
-                    const challenge = await strategy.generateChallenge({ solution });
-                    challenges[challengeId] = challenge;
-                }
+                const challenges = await generatePoolChallenges({
+                    config,
+                    masterSecret
+                });
 
                 challengePools.push({
                     id: config.id,
@@ -88,7 +82,12 @@ export class KeystoneService_V1 {
             if (challengePools.length === 0) { throw new Error(`No challenge pools created. (E: 38e538530996940e1f16a8b199995825)`); }
 
             const data: KeystoneData_V1 = { challengePools, proofs: [] };
-            if (frameDetails) { data.frameDetails = frameDetails; }
+            if (frameDetails || isPrimary !== undefined) {
+                data.frameDetails = { ...(frameDetails || {}) };
+                if (isPrimary !== undefined) {
+                    data.frameDetails.isPrimary = isPrimary;
+                }
+            }
             const keystoneIbGib = await createKeystoneIbGibImpl({ data, metaspace, space });
             return keystoneIbGib;
         } catch (error) {
@@ -585,10 +584,10 @@ export class KeystoneService_V1 {
 
             const prevData = latestKeystone.data!;
 
-            // 1. Identify Authority (Resolve Revoke Pool)
+            // 1. Identify Authority (Resolve Revoke Pool by verb)
             const pool = resolveTargetPool({
                 pools: prevData.challengePools,
-                poolId: POOL_ID_REVOKE // Explicitly require the special revoke pool
+                verb: KEYSTONE_VERB_REVOKE
             });
 
             // 2. Construct Claim
@@ -720,13 +719,15 @@ export class KeystoneService_V1 {
 
             if (logalot) { console.log(`${lc} Authorized via pool: ${adminPool.id}`); }
 
-            // 2. Construct the Management Claim
+            // 2. Construct the Management Claim with typed details
             const target = getIbGibAddr({ ibGib: latestKeystone });
             const claim: Partial<KeystoneClaim> = {
                 verb: KEYSTONE_VERB_MANAGE,
                 target, // I am managing myself
-                // Scope creates a cryptographic commitment to WHICH pools are being added
-                scope: JSON.stringify({ add: newPools.map(p => p.id) })
+                details: {
+                    type: KeystoneClaimType.add_pool,
+                    info: { add: newPools.map(p => p.id) } as ClaimDetails_AddPool
+                }
             };
 
             // 3. Calculate Costs
@@ -795,6 +796,128 @@ export class KeystoneService_V1 {
         }
     }
 
+    /**
+     * Structural evolution: Removes challenge pools from the keystone.
+     *
+     * Use Case: Unlinking a custodian or delegate SSO pool.
+     *
+     * Requires the Master Secret to authorize the change via a pool containing
+     * the 'manage' verb (the administrative manage pool).
+     */
+    async removePools({
+        latestKeystone,
+        masterSecret,
+        poolIds,
+        metaspace,
+        space,
+    }: {
+        latestKeystone: KeystoneIbGib_V1;
+        /**
+         * Alice's Master Secret.
+         * Required to solve challenges from the Admin/Manage pool to authorize this change.
+         */
+        masterSecret: string;
+        /**
+         * The IDs of the pools to remove.
+         */
+        poolIds: string[];
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.removePools.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (!latestKeystone.data) { throw new Error(`(UNEXPECTED) latestKeystone.data falsy? (E: 8334c8faed128166a999d428c7805b25)`); }
+            const prevData = latestKeystone.data;
+
+            if (prevData.revocationInfo) { throw new Error(`Keystone has been revoked. Cannot remove pools. (E: 9599f8f51c78d722252ddb2894fdbe25)`); }
+
+            if (poolIds.length === 0) { throw new Error(`No pool IDs provided to remove. (E: 7599f8f51c78d722252ddb2894fdbe25)`); }
+
+            // 1. Identify Authority (Resolve Admin Pool)
+            const adminPool = resolveTargetPool({
+                pools: prevData.challengePools,
+                verb: KEYSTONE_VERB_MANAGE,
+            });
+
+            if (logalot) { console.log(`${lc} Authorized via pool: ${adminPool.id}`); }
+
+            // 2. Construct the Management Claim with typed details
+            const target = getIbGibAddr({ ibGib: latestKeystone });
+            const claim: Partial<KeystoneClaim> = {
+                verb: KEYSTONE_VERB_MANAGE,
+                target,
+                details: {
+                    type: KeystoneClaimType.remove_pool,
+                    info: { remove: poolIds } as ClaimDetails_RemovePool
+                }
+            };
+
+            // 3. Calculate Costs
+            const idsToSolve = await selectChallengeIds({
+                pool: adminPool,
+                targetAddr: target
+            });
+
+            // 4. Pay the Cost (Solve & Replenish)
+            const { proof, nextPools: replenishedExistingPools } = await solveAndReplenish({
+                targetPoolId: adminPool.id,
+                prevPools: prevData.challengePools,
+                masterSecret,
+                challengeIds: idsToSolve,
+                claim,
+            });
+
+            // 5. Mutate Structure (Remove the pools)
+            const removeSet = new Set(poolIds);
+            const finalPools = replenishedExistingPools.filter(p => !removeSet.has(p.id));
+
+            // Verify that we actually removed the expected count of pools
+            if (finalPools.length !== replenishedExistingPools.length - poolIds.length) {
+                const missingIds = poolIds.filter(id => !replenishedExistingPools.some(p => p.id === id));
+                throw new Error(`Cannot remove pool. Pool IDs not found in keystone: ${missingIds.join(', ')} (E: 8a4c2b1d3e5f6a7b8c9d0e1f2a3b4c5e)`);
+            }
+
+            // 6. Construct New Data
+            const n = (prevData.n ?? 0) + 1;
+            let checkpointDetails: any | undefined;
+            if (n % KEYSTONE_CHECKPOINT_FREQUENCY === 0) {
+                const currentFrameView: KeystoneIbGib_V1 = {
+                    ...latestKeystone,
+                    data: { ...prevData, challengePools: finalPools }
+                };
+                checkpointDetails = await this.getAggregateDetails({
+                    latestKeystone: currentFrameView,
+                    metaspace,
+                    space
+                });
+            }
+
+            const newData: KeystoneData_V1 = {
+                challengePools: finalPools,
+                proofs: [proof],
+                checkpointDetails,
+                ...(prevData.delegates ? { delegates: prevData.delegates } : {}),
+            };
+
+            // 7. Commit
+            const newKeystone = await evolvePersistAndRegisterKeystone({
+                prevIbGib: latestKeystone,
+                newData,
+                metaspace,
+                space
+            });
+
+            return newKeystone;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
     /**
      * Consolidates the state of a Keystone identity across its history.
      * Walks back until it hits a checkpoint or genesis.
@@ -854,4 +977,388 @@ export class KeystoneService_V1 {
             throw error;
         }
     }
+
+    /**
+     * Retrieves common aggregated info for a keystone timeline.
+     */
+    async getKeystoneCommonInfo({
+        addr,
+        ibGib,
+        metaspace,
+        space,
+    }: {
+        addr?: string;
+        ibGib?: KeystoneIbGib_V1;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<{
+        name: string;
+        description: string;
+        isPrimary: boolean;
+        aggregateDetails: any;
+        latestFrameDetails: any;
+        n: number;
+        timestamp?: string;
+        timestampMs?: number;
+    } | null> {
+        const lc = `${this.lc}[getKeystoneCommonInfo]`;
+        try {
+            let targetAddr = addr;
+            let targetIbGib: any = ibGib;
+            if (!targetAddr) {
+                if (!targetIbGib) { return null; }
+                targetAddr = getIbGibAddr({ ibGib: targetIbGib });
+            }
+            if (!targetIbGib) {
+                const { ib, gib } = getIbAndGib({ ibGibAddr: targetAddr });
+                targetIbGib = { ib, gib };
+            }
+
+            const resGetLatest = await getLatestAddrs({
+                ibGibs: [targetIbGib],
+                space,
+            });
+
+            if (!resGetLatest.data?.latestAddrsMap) { return null; }
+            const latestAddr = resGetLatest.data.latestAddrsMap[targetAddr] || Object.values(resGetLatest.data.latestAddrsMap)[0];
+            if (!latestAddr) { return null; }
+
+            const resGet = await metaspace.get({ addr: latestAddr, space });
+            const latestKeystone = resGet.ibGibs?.at(0) as KeystoneIbGib_V1;
+            if (!latestKeystone || !latestKeystone.data) { return null; }
+
+            const aggregateDetails = await this.getAggregateDetails({
+                latestKeystone,
+                metaspace,
+                space
+            });
+
+            const name = aggregateDetails?.username || aggregateDetails?.profile?.name || aggregateDetails?.name || '';
+            const description = aggregateDetails?.description || aggregateDetails?.profile?.description || '';
+            const isPrimary = !!aggregateDetails?.isPrimary || !!aggregateDetails?.profile?.isPrimary;
+            const latestFrameDetails = latestKeystone.data.frameDetails || {};
+            const n = latestKeystone.data.n ?? 0;
+            const timestamp = latestFrameDetails?.timestamp || aggregateDetails?.timestamp || '';
+            const timestampMs = latestFrameDetails?.timestampMs || aggregateDetails?.timestampMs || undefined;
+
+            return {
+                name,
+                description,
+                isPrimary,
+                aggregateDetails,
+                latestFrameDetails,
+                n,
+                timestamp,
+                timestampMs
+            };
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            return null;
+        }
+    }
+
+    /**
+     * Replaces a challenge pool (such as manage or custodian-manage) with a new pool,
+     * authorizing the transition via the specified signing pool.
+     * 
+     * @param latestKeystone The current tip frame of the keystone timeline.
+     *   - Visibility: Public (Public Merkle frame, safe for logs/ledger).
+     *   - Generator: Client/Server (Constructed locally and synced).
+     * 
+     * @param newPool The fully constructed new pool to place in the next frame.
+     *   - Visibility: Public (Public configuration and public challenges, safe for ledger).
+     *   - Generator: Client/Server (Generated dynamically by the party proposing the update).
+     * 
+     * @param signingSecret The master secret or derived KDF secret of the pool authorizing the change.
+     *   - Visibility: Private (Confidential secret credential. Must never go over the wire).
+     *   - Generator: Client/Server (Known only to the signing party).
+     * 
+     * @param signingPoolId The ID of the pool used to authorize the transition (defaults to 'manage').
+     *   - Visibility: Public (Non-sensitive configuration string).
+     *   - Generator: Client/Server (From pool configuration).
+     */
+    async replacePool({
+        latestKeystone,
+        newPool,
+        signingSecret,
+        signingPoolId = POOL_ID_MANAGE,
+        frameDetails,
+        metaspace,
+        space,
+    }: {
+        latestKeystone: KeystoneIbGib_V1;
+        newPool: KeystoneChallengePool;
+        signingSecret: string;
+        signingPoolId?: string;
+        frameDetails?: any;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.replacePool.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... replacing pool: ${newPool.id}`); }
+
+            if (!latestKeystone.data) { throw new Error(`(UNEXPECTED) latestKeystone.data falsy? (E: 1334c8faed128166a999d428c7805b25)`); }
+            const prevData = latestKeystone.data;
+
+            if (prevData.revocationInfo) { throw new Error(`Keystone has been revoked. Cannot replace pool. (E: 2599f8f51c78d722252ddb2894fdbe25)`); }
+
+            // 1. Identify Authority (Resolve Signing Pool)
+            const prevPools = prevData.challengePools;
+            const signingPool = prevPools.find(p => p.id === signingPoolId);
+            if (!signingPool) {
+                throw new Error(`Signing pool not found: ${signingPoolId} (E: 3599f8f51c78d722252ddb2894fdbe25)`);
+            }
+
+            // 2. Construct the Management Claim with typed details
+            const target = getIbGibAddr({ ibGib: latestKeystone });
+            const claim: Partial<KeystoneClaim> = {
+                verb: KEYSTONE_VERB_MANAGE,
+                target,
+                details: {
+                    type: KeystoneClaimType.replace_pool,
+                    info: { replace: newPool.id } as ClaimDetails_ReplacePool
+                }
+            };
+
+            // 3. Calculate Costs
+            const idsToSolve = await selectChallengeIds({
+                pool: signingPool,
+                targetAddr: target
+            });
+
+            // 4. Pay the Cost (Solve & Replenish)
+            const { proof, nextPools } = await solveAndReplenish({
+                targetPoolId: signingPoolId,
+                prevPools,
+                masterSecret: signingSecret,
+                challengeIds: idsToSolve,
+                claim,
+            });
+
+            // 5. Replace target pool in nextPools
+            const targetIdx = nextPools.findIndex(p => p.id === newPool.id);
+            if (targetIdx === -1) {
+                throw new Error(`Target pool to replace '${newPool.id}' not found in keystone challenge pools.`);
+            }
+            nextPools[targetIdx] = newPool;
+
+            // 6. Construct New Data
+            const n = (prevData.n ?? 0) + 1;
+            let checkpointDetails: any | undefined;
+            if (n % KEYSTONE_CHECKPOINT_FREQUENCY === 0) {
+                const currentFrameView: KeystoneIbGib_V1 = {
+                    ...latestKeystone,
+                    data: { ...prevData, frameDetails }
+                };
+                checkpointDetails = await this.getAggregateDetails({
+                    latestKeystone: currentFrameView,
+                    metaspace,
+                    space
+                });
+            }
+
+            const newData: KeystoneData_V1 = {
+                challengePools: nextPools,
+                proofs: [proof],
+                frameDetails,
+                checkpointDetails,
+                ...(prevData.delegates ? { delegates: prevData.delegates } : {}),
+            };
+
+            // 7. Commit
+            const newKeystone = await evolvePersistAndRegisterKeystone({
+                prevIbGib: latestKeystone,
+                newData,
+                metaspace,
+                space
+            });
+
+            return newKeystone;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Evolve the keystone by rotating the primary user manage pool (`manage`) to a new master secret (passphrase).
+     * This creates a new frame signed by the specified `signingPoolId` using `signingSecret`.
+     * 
+     * Supports recovery (signing via `custodian-manage` using the custodian secret) and normal rotation 
+     * (signing via `manage` using the old password).
+     * 
+     * @param latestKeystone The current tip frame of the keystone.
+     *   - Visibility: Public (Public Merkle frame, safe for ledger).
+     *   - Generator: Client/Server (Constructed locally and synced).
+     * 
+     * @param newMasterSecret The new passphrase/master secret to set for the user's primary pools.
+     *   - Visibility: Private (Confidential secret credential. Must never go over the wire).
+     *   - Generator: Client (From user input in settings).
+     * 
+     * @param signingSecret The secret of the pool authorizing this change (either old passphrase or derived custodian secret).
+     *   - Visibility: Private (Confidential secret. Must never go over the wire).
+     *   - Generator: Client/Server (Known only to the signing party).
+     * 
+     * @param signingPoolId The ID of the pool used to authorize the rotation (defaults to 'manage').
+     *   - Visibility: Public (Non-sensitive ID string).
+     *   - Generator: Client/Server (From pool configuration).
+     */
+    async changePassword({
+        latestKeystone,
+        newMasterSecret,
+        signingSecret,
+        signingPoolId = POOL_ID_MANAGE,
+        poolIds,
+        frameDetails,
+        metaspace,
+        space,
+    }: {
+        latestKeystone: KeystoneIbGib_V1;
+        newMasterSecret: string;
+        signingSecret: string;
+        signingPoolId?: string;
+        poolIds?: string[];
+        frameDetails?: any;
+        metaspace: MetaspaceService;
+        space: IbGibSpaceAny;
+    }): Promise<KeystoneIbGib_V1> {
+        const lc = `${this.lc}[${this.changePassword.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+            
+            if (!latestKeystone.data) { throw new Error(`latestKeystone.data falsy`); }
+            if (latestKeystone.data.revocationInfo) { throw new Error(`Keystone has been revoked. Cannot change password. (E: 8599f8f51c78d722252ddb2894fdbe25)`); }
+
+            const prevPools = latestKeystone.data.challengePools;
+            const signingPool = prevPools.find(p => p.id === signingPoolId);
+            if (!signingPool) {
+                throw new Error(`Signing pool not found: ${signingPoolId} (E: 3599f8f51c78d722252ddb2894fdbe25)`);
+            }
+
+            // 1. Resolve target pools to rotate
+            let targets: KeystoneChallengePool[] = [];
+            if (poolIds && poolIds.length > 0) {
+                for (const id of poolIds) {
+                    const found = prevPools.find(p => p.id === id);
+                    if (!found) {
+                        throw new Error(`Target pool to rotate not found: ${id} (E: 4599f8f51c78d722252ddb2894fdbe25)`);
+                    }
+                    targets.push(found);
+                }
+            } else {
+                targets = prevPools.filter(p => !p.isForeign);
+                if (targets.length === 0) {
+                    throw new Error(`No non-foreign pools found to rotate. (E: 5599f8f51c78d722252ddb2894fdbe25)`);
+                }
+            }
+
+            // 2. Rotate the target pools
+            const rotatedPools: KeystoneChallengePool[] = [];
+            for (const targetPool of targets) {
+                const rotated = await rotatePoolChallenges({
+                    prevPool: targetPool,
+                    newMasterSecret
+                });
+                rotatedPools.push(rotated);
+            }
+
+            // 3. Construct Management Claim with typed details
+            const target = getIbGibAddr({ ibGib: latestKeystone });
+            const claim: Partial<KeystoneClaim> = {
+                verb: KEYSTONE_VERB_MANAGE,
+                target,
+                details: {
+                    type: KeystoneClaimType.change_password,
+                    info: { change: rotatedPools.map(p => p.id) } as ClaimDetails_ChangePassword
+                }
+            };
+
+            // 4. Calculate Costs
+            const idsToSolve = await selectChallengeIds({
+                pool: signingPool,
+                targetAddr: target
+            });
+
+            // 5. Pay the Cost (Solve & Replenish)
+            const { proof, nextPools } = await solveAndReplenish({
+                targetPoolId: signingPoolId,
+                prevPools,
+                masterSecret: signingSecret,
+                challengeIds: idsToSolve,
+                claim
+            });
+
+            // 6. Swap the rotated pools in nextPools
+            for (const rotated of rotatedPools) {
+                const idx = nextPools.findIndex(p => p.id === rotated.id);
+                if (idx === -1) {
+                    throw new Error(`Rotated pool ${rotated.id} not found in next pools list. (E: 6599f8f51c78d722252ddb2894fdbe25)`);
+                }
+                nextPools[idx] = rotated;
+            }
+
+            // 7. Construct New Data
+            const n = (latestKeystone.data.n ?? 0) + 1;
+            let checkpointDetails: any | undefined;
+            if (n % KEYSTONE_CHECKPOINT_FREQUENCY === 0) {
+                const currentFrameView: KeystoneIbGib_V1 = {
+                    ...latestKeystone,
+                    data: { ...latestKeystone.data, challengePools: nextPools }
+                };
+                checkpointDetails = await this.getAggregateDetails({
+                    latestKeystone: currentFrameView,
+                    metaspace,
+                    space
+                });
+            }
+
+            const newData: KeystoneData_V1 = {
+                challengePools: nextPools,
+                proofs: [proof],
+                frameDetails,
+                checkpointDetails,
+                ...(latestKeystone.data.delegates ? { delegates: latestKeystone.data.delegates } : {}),
+            };
+
+            // 8. Commit
+            return await evolvePersistAndRegisterKeystone({
+                prevIbGib: latestKeystone,
+                newData,
+                metaspace,
+                space
+            });
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        }
+    }
+
+    /**
+     * Verifies if a candidate signing secret (passphrase) is correct for a specific challenge pool.
+     * Does not mutate any state.
+     */
+    async verifySigningSecret({
+        keystoneIbGib,
+        signingSecret,
+        poolId
+    }: {
+        keystoneIbGib: KeystoneIbGib_V1;
+        signingSecret: string;
+        poolId: string;
+    }): Promise<boolean> {
+        const lc = `${this.lc}[${this.verifySigningSecret.name}]`;
+        try {
+            if (!keystoneIbGib.data) return false;
+            const pool = keystoneIbGib.data.challengePools.find(p => p.id === poolId);
+            if (!pool) return false;
+
+            return await verifyPoolSecret({ pool, signingSecret });
+        } catch (error) {
+            console.warn(`${lc} Exception during verification: ${extractErrorMsg(error)}`);
+            return false;
+        }
+    }
 }