@ibgib/core-gib 0.1.65 → 0.1.66

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

@@ -31,6 +31,7 @@ import { IbGibSpaceAny } from '../witness/space/space-base-v1.mjs';
 import { MetaspaceService } from '../witness/space/metaspace/metaspace-types.mjs';
 import { FlatIbGibGraph } from '../common/other/graph-types.mjs';
 import { getTjpAddr } from '../common/other/ibgib-helper.mjs';
+import { deriveDelegateSecret } from './strategy/hash-reveal-v1/hash-reveal-v1.mjs';
 
 const logalot = GLOBAL_LOG_A_LOT;
 
@@ -1060,19 +1061,19 @@ export class KeystoneService_V1 {
     /**
      * 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).
@@ -1186,28 +1187,17 @@ export class KeystoneService_V1 {
     /**
      * 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).
+     *
+     * Supports recovery (signing via `custodian-manage` using the custodian secret) and normal rotation
+     * (signing via `manage` using the old password). **I DONT THINK THIS IS POSSIBLE. WE WOULD NEED CUSTODIAN MANAGE POOLS ON ALL THE DELEGATES AS WELL**
+     *
+     * @param signingSecret
+     *
+     * @param signingPoolId
      */
     async changePassword({
-        latestKeystone,
+        keystoneIbGib,
+        keystoneAddr,
         newMasterSecret,
         signingSecret,
         signingPoolId = POOL_ID_MANAGE,
@@ -1216,21 +1206,82 @@ export class KeystoneService_V1 {
         metaspace,
         space,
     }: {
-        latestKeystone: KeystoneIbGib_V1;
+        /**
+         * The keystone IBGIB whose password we are changing. Does NOT have to
+         * be the tip, as we will get the latest keystone in the implementation
+         * of this function.
+         * - Visibility: Public (Public Merkle frame, safe for ledger).
+         * - Generator: Client/Server (Constructed locally and synced).
+         *
+         * NOTE: You can provide {@link keystoneIbGib} or {@link keystoneAddr},
+         * but either way the latest keystone ibgib will be gotten first.
+         */
+        keystoneIbGib?: KeystoneIbGib_V1;
+        /**
+         * The keystone ADDRESS whose password we are changing. Does NOT have to
+         * be the tip, as we will get the latest keystone in the implementation
+         * of this function.
+         * - Visibility: Public (Public Merkle frame, safe for ledger).
+         * - Generator: Client/Server (Constructed locally and synced).
+         *
+         * NOTE: You can provide {@link keystoneIbGib} or {@link keystoneAddr},
+         * but either way the latest keystone ibgib will be gotten first.
+         */
+        keystoneAddr?: IbGibAddr;
+        /**
+         * 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).
+         */
         newMasterSecret: string;
+        /**
+         * The secret of the pool authorizing this change (either old passphrase
+         * or derived custodian secret).
+         * - Visibility: Private (Confidential secret. Never over the wire).
+         * - Generator: Client/Server (Known only to the signing party).
+         */
         signingSecret: string;
+        /**
+         * The ID of the pool used to authorize the rotation. Defaults to
+         * "manage" for user password changes, or if rotating custodian, should
+         * be the custodian's corresponding manage pool.
+         * - Visibility: Public (Non-sensitive ID string).
+         * - Generator: Client/Server (From pool configuration).
+         */
         signingPoolId?: string;
+        /**
+         * If provided, password will only be changed for these pools.
+         * NOTE: **delegate passwords will NOT be changed if poolIds are
+         *       explicitly provided.**
+         */
         poolIds?: string[];
         frameDetails?: any;
         metaspace: MetaspaceService;
         space: IbGibSpaceAny;
-    }): Promise<KeystoneIbGib_V1> {
+    }): Promise<{ newKeystone: KeystoneIbGib_V1, newDelegates?: 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)`); }
+            if (logalot) { console.log(`${lc} starting... (I: 9e3ff83ebd74511f9dad784a1020d926)`); }
+
+            if (!keystoneIbGib && !keystoneAddr) { throw new Error(`Either keystoneIbGib or keystoneAddr required. (E: d1b8c8cb75f2c022284e69b8c30af826)`); }
+            if (keystoneIbGib && keystoneAddr) {
+                // double check addr matches ibgib
+                const checkAddr = getIbGibAddr({ ibGib: keystoneIbGib });
+                if (checkAddr !== keystoneAddr) { throw new Error(`(UNEXPECTED) both keystoneIbGib (addr: ${checkAddr}) and keystoneAddr (${keystoneAddr}) provided, but the addrs are unequal? Note that only one is required for this function, but if both are provided the addrs must match exactly. (E: c5574f7e353a48b0bba94a1862af4e26)`); }
+            }
+
+            keystoneAddr ??= getIbGibAddr({ ibGib: keystoneIbGib });
+
+            const latestKeystone = await this.getLatestKeystone({
+                addr: keystoneAddr,
+                metaspace,
+                space,
+            });
+
+            if (!latestKeystone.data) { throw new Error(`latestKeystone.data falsy (E: 22e498eb8308a33e68b812d8d3905826)`); }
+            if (latestKeystone.data.revocationInfo) { throw new Error(`Keystone has been revoked. Cannot change password. (E: 726298617e8508b3c83b5e985a03e826)`); }
+
 
             const prevPools = latestKeystone.data.challengePools;
             const signingPool = prevPools.find(p => p.id === signingPoolId);
@@ -1320,19 +1371,48 @@ export class KeystoneService_V1 {
                 proofs: [proof],
                 frameDetails,
                 checkpointDetails,
-                ...(latestKeystone.data.delegates ? { delegates: latestKeystone.data.delegates } : {}),
+                ...(latestKeystone.data.delegates ? { delegates: latestKeystone.data.delegates } : undefined),
             };
 
             // 8. Commit
-            return await evolvePersistAndRegisterKeystone({
+            const newKeystoneIbGib = await evolvePersistAndRegisterKeystone({
                 prevIbGib: latestKeystone,
                 newData,
                 metaspace,
                 space
             });
+
+            // update delegates' passwords also, **BUT ONLY IF NOT DOING
+            // SPECIFIC POOLS**.
+            const newDelegates: KeystoneIbGib_V1[] = [];
+            if ((poolIds ?? []).length === 0) {
+                const delegateSigningSecret = await deriveDelegateSecret({ masterSecret: signingSecret });
+                const delegateNewMasterSecret = await deriveDelegateSecret({ masterSecret: newMasterSecret });
+                const delegateTjpAddrs = Object.keys(latestKeystone.data.delegates ?? {});
+                for (const delegateTjpAddr of delegateTjpAddrs) {
+                    const { newKeystone: newDelegate, newDelegates: newDelegatesSecondOrder } = await this.changePassword({
+                        keystoneAddr: delegateTjpAddr,
+                        metaspace,
+                        space,
+                        newMasterSecret: delegateNewMasterSecret,
+                        signingSecret: delegateSigningSecret,
+                        signingPoolId,
+                        poolIds: undefined,
+                        frameDetails,
+                    });
+                    if (newDelegatesSecondOrder && newDelegatesSecondOrder.length > 0) {
+                        throw new Error(`(UNEXPECTED) Delegate keystone has its own delegate(s)? ATOW (07/20/2026) second order delegates are not supported. (E: de45a7b7d9b8f61f6e58158269acba26)`);
+                    }
+                    newDelegates.push(newDelegate);
+                }
+            }
+
+            return { newKeystone: newKeystoneIbGib, newDelegates: newDelegates.length > 0 ? newDelegates : undefined };
         } catch (error) {
             console.error(`${lc} ${extractErrorMsg(error)}`);
             throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
         }
     }