@ibgib/node-gib 0.0.18 → 0.0.20

package/dist/serve-gib/path-constants.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"path-constants.d.mts","sourceRoot":"","sources":["../../src/serve-gib/path-constants.mts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,UAK9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;IACzB;;OAEG;IACH,MAAM;IAEN;;OAEG;IACH,WAAW;IAEX;;OAEG;IACH,UAAU;IAEV;;OAEG;IACH,QAAQ;IAER;;OAEG;IACH,aAAa;IAEb;;OAEG;IACH,UAAU;IAEV;;OAEG;IACH,eAAe;IAEf;;;;;;;;OAQG;IACH,gBAAgB;IAEhB;;OAEG;IACH,eAAe;IAEf;;OAEG;IACH,oBAAoB;IAEpB;;;;;;;;;;;OAWG;IACH,aAAa;IACb;;OAEG;IACH,OAAO;IACP;;OAEG;IACH,iBAAiB;IACjB;;OAEG;IACH,kBAAkB;IAClB;;OAEG;IACH,mBAAmB;IACnB;;OAEG;IACH,aAAa;IACb;;OAEG;IACH,UAAU;IACV;;OAEG;IACH,uBAAuB;IAEvB;;OAEG;IACH,YAAY;IACZ,iBAAiB;IAEjB;;OAEG;IACH,0BAA0B;IAE1B;;OAEG;IACH,oCAAoC;CACvC,CAAC;AAEF,eAAO,MAAM,uBAAuB,QAA4B,CAAC"}
+{"version":3,"file":"path-constants.d.mts","sourceRoot":"","sources":["../../src/serve-gib/path-constants.mts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,UAK9B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;IACzB;;OAEG;IACH,MAAM;IAEN;;OAEG;IACH,WAAW;IAEX;;OAEG;IACH,UAAU;IAEV;;OAEG;IACH,QAAQ;IAER;;OAEG;IACH,aAAa;IAEb;;OAEG;IACH,UAAU;IAEV;;OAEG;IACH,eAAe;IAEf;;;;;;;;OAQG;IACH,gBAAgB;IAEhB;;OAEG;IACH,eAAe;IAEf;;OAEG;IACH,oBAAoB;IAEpB;;;;;;;;;;;OAWG;IACH,aAAa;IACb;;OAEG;IACH,OAAO;IACP;;OAEG;IACH,iBAAiB;IACjB;;OAEG;IACH,kBAAkB;IAClB;;OAEG;IACH,mBAAmB;IACnB;;OAEG;IACH,aAAa;IACb;;OAEG;IACH,UAAU;IACV;;OAEG;IACH,uBAAuB;IAEvB;;OAEG;IACH,YAAY;IACZ,iBAAiB;IAEjB;;OAEG;IACH,0BAA0B;IAE1B;;OAEG;IACH,oCAAoC;IAEpC;;OAEG;IACH,sCAAsC;CACzC,CAAC;AAEF,eAAO,MAAM,uBAAuB,QAA4B,CAAC"}

package/dist/serve-gib/path-constants.mjs

@@ -119,6 +119,10 @@ export const API_PATH_REGEXES = {
      * /api/identity/custodian/register-delegate
      */
     KEYSTONE_CUSTODIAN_REGISTER_DELEGATE: /^\/api\/identity\/custodian\/register-delegate\/?$/i,
+    /**
+     * /api/identity/custodian/add-master-password
+     */
+    KEYSTONE_CUSTODIAN_ADD_MASTER_PASSWORD: /^\/api\/identity\/custodian\/add-master-password\/?$/i,
 };
 export const VALID_STATIC_PATH_REGEX = /^\/[a-zA-Z0-9\-_\.\/]*$/;
 //# sourceMappingURL=path-constants.mjs.map

package/dist/serve-gib/path-constants.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"path-constants.mjs","sourceRoot":"","sources":["../../src/serve-gib/path-constants.mts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAC9B,MAAM,EAAO,yBAAyB;IACtC,MAAM,EAAO,uBAAuB;IACpC,IAAI,EAAS,gBAAgB;IAC7B,UAAU,EAAG,wCAAwC;CACxD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B;;OAEG;IACH,MAAM,EAAE,oBAAoB;IAE5B;;OAEG;IACH,WAAW,EAAE,oFAAoF;IAEjG;;OAEG;IACH,UAAU,EAAE,6EAA6E;IAEzF;;OAEG;IACH,QAAQ,EAAE,sBAAsB;IAEhC;;OAEG;IACH,aAAa,EAAE,mDAAmD;IAElE;;OAEG;IACH,UAAU,EAAE,mBAAmB;IAE/B;;OAEG;IACH,eAAe,EAAE,2DAA2D;IAE5E;;;;;;;;OAQG;IACH,gBAAgB,EAAE,+BAA+B;IAEjD;;OAEG;IACH,eAAe,EAAE,8BAA8B;IAE/C;;OAEG;IACH,oBAAoB,EAAE,mCAAmC;IAEzD;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,4BAA4B;IAC3C;;OAEG;IACH,OAAO,EAAE,mDAAmD;IAC5D;;OAEG;IACH,iBAAiB,EAAE,iCAAiC;IACpD;;OAEG;IACH,kBAAkB,EAAE,kCAAkC;IACtD;;OAEG;IACH,mBAAmB,EAAE,mCAAmC;IACxD;;OAEG;IACH,aAAa,EAAE,4BAA4B;IAC3C;;OAEG;IACH,UAAU,EAAE,yBAAyB;IACrC;;OAEG;IACH,uBAAuB,EAAE,sCAAsC;IAE/D;;OAEG;IACH,YAAY,EAAE,2BAA2B;IACzC,iBAAiB,EAAE,gCAAgC;IAEnD;;OAEG;IACH,0BAA0B,EAAE,2CAA2C;IAEvE;;OAEG;IACH,oCAAoC,EAAE,qDAAqD;CAC9F,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAyB,CAAC"}
+{"version":3,"file":"path-constants.mjs","sourceRoot":"","sources":["../../src/serve-gib/path-constants.mts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC;AAEpC;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAC9B,MAAM,EAAO,yBAAyB;IACtC,MAAM,EAAO,uBAAuB;IACpC,IAAI,EAAS,gBAAgB;IAC7B,UAAU,EAAG,wCAAwC;CACxD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC5B;;OAEG;IACH,MAAM,EAAE,oBAAoB;IAE5B;;OAEG;IACH,WAAW,EAAE,oFAAoF;IAEjG;;OAEG;IACH,UAAU,EAAE,6EAA6E;IAEzF;;OAEG;IACH,QAAQ,EAAE,sBAAsB;IAEhC;;OAEG;IACH,aAAa,EAAE,mDAAmD;IAElE;;OAEG;IACH,UAAU,EAAE,mBAAmB;IAE/B;;OAEG;IACH,eAAe,EAAE,2DAA2D;IAE5E;;;;;;;;OAQG;IACH,gBAAgB,EAAE,+BAA+B;IAEjD;;OAEG;IACH,eAAe,EAAE,8BAA8B;IAE/C;;OAEG;IACH,oBAAoB,EAAE,mCAAmC;IAEzD;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,4BAA4B;IAC3C;;OAEG;IACH,OAAO,EAAE,mDAAmD;IAC5D;;OAEG;IACH,iBAAiB,EAAE,iCAAiC;IACpD;;OAEG;IACH,kBAAkB,EAAE,kCAAkC;IACtD;;OAEG;IACH,mBAAmB,EAAE,mCAAmC;IACxD;;OAEG;IACH,aAAa,EAAE,4BAA4B;IAC3C;;OAEG;IACH,UAAU,EAAE,yBAAyB;IACrC;;OAEG;IACH,uBAAuB,EAAE,sCAAsC;IAE/D;;OAEG;IACH,YAAY,EAAE,2BAA2B;IACzC,iBAAiB,EAAE,gCAAgC;IAEnD;;OAEG;IACH,0BAA0B,EAAE,2CAA2C;IAEvE;;OAEG;IACH,oCAAoC,EAAE,qDAAqD;IAE3F;;OAEG;IACH,sCAAsC,EAAE,uDAAuD;CAClG,CAAC;AAEF,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAyB,CAAC"}

package/e2e/identity-custodian-lifecycle.e2e.md

@@ -91,3 +91,40 @@ Attempt to re-submit a previously consumed `custodianReqs` payload to `POST /api
 3. Verify rejection outcome:
    - Server rejects the request with **HTTP 409 Conflict**:
      `"Custodian requirements payload has already been used. Nonce single-turn reservation violation."`
+
+
+### Phase 4: Keystone Details Inspection & Sovereign Elevation
+Inspect the identity in `<ibgib-keystone-details>` to verify that capabilities, device badges, and password options adapt dynamically to the custodial state, and add a sovereign master password.
+
+#### Steps
+1. In Browser 1, open `<ibgib-identity-header>` and click the active identity to open `<ibgib-keystone-details>`.
+2. Verify dynamic UI elements:
+   - **Password Card**: Displays **"Add Master Password"** (with New Password and Confirm Password inputs; Current Password is hidden).
+   - **SSO Status Card**: Displays `"Google (Primary Account) ✅"` or provider primary indicator.
+   - **Registered Delegates Table**:
+     - Browser 1's delegate displays the green **"This Device"** badge.
+     - Browser 2's delegate (from Phase 2) displays the blue **"Remote Device"** badge.
+3. Click **View Details** on Browser 2's remote delegate:
+   - Verify modal opens showing remote device metadata without throwing or failing.
+4. In the **Add Master Password** card, enter `<E2E_TEST_NEW_PASSWORD>` in New Password and Confirm Password inputs, and click **Add Master Password**.
+5. Verify outcomes:
+   - Client adds a sovereign `manage` pool via `keystoneService.addPools()`, evolves the primary identity, and syncs to server.
+   - The password card updates dynamically to **"Change Password"** (now displaying Current Password input).
+   - Identity capability transitions from Custodial to **Hybrid**.
+
+
+### Phase 5: Silent Background Sync & Expired Session Renewal ("Sign Back In")
+Verify that daily background sync operations execute silently via stored IndexedDB delegate tokens ($S_D$), and verify that expired sync delegates cleanly pause sync and prompt the user to "Sign Back In".
+
+#### Steps
+1. In Browser 1, click **Check for Updates** and **Update Identity**:
+   - Verify sync succeeds silently in the background without prompting for master passwords.
+2. Simulate delegate expiration / session expiry:
+   - Option A: Clear the stored device delegate secret from IndexedDB (`space_gib_db` -> `space_gib_store` -> delete `ibgib_device_delegate_secret_<primaryTjpAddr>`).
+   - Option B: Test with a short TTL development profile (`sync-profile.dev.json` with `defaultTtlSeconds: 10`) and wait for expiration.
+3. Trigger a sync check or page refresh:
+   - Verify `KeystoneSyncService` detects the expired / missing delegate token and fires `EVENT_IBGIB_IDENTITY_RENEWAL_REQUIRED`.
+   - Verify the UI prompts the user to **"Sign Back In"**.
+4. Re-authenticate via Email OTP (or Google SSO / Master Password):
+   - Verify single-turn re-authentication generates and registers a fresh outward sync delegate ($D_{\text{device}}$).
+   - Verify the new secret ($S_D$) is stored in IndexedDB and silent background sync resumes seamlessly.

package/e2e/identity-sso-lifecycle.e2e.md

@@ -99,18 +99,20 @@ Open Identity Manager on `https://local.ibgib.space`, trigger Google OAuth2 link
 
 
 ### Phase 4: New-Device Google SSO Sign-In (Incognito Mode)
-Open a clean Incognito browser window to `https://local.ibgib.space`, complete Google SSO sign-in, verify that `IdentityIndexService` resolves the primary identity, verifies the `custodian-manage-google` pool, and pairs the new device.
+Open a clean Incognito browser window to `https://local.ibgib.space`, navigate to Sign In, click **Continue with Google**, complete Google SSO authentication, and verify that the client automatically creates the device delegate and signs in without prompting for a password.
 
 #### Steps
 1. Open a fresh **Incognito Window** (ctrl+shift+N) to `https://local.ibgib.space`.
-2. In `<ibgib-identity-header>`, click **Sign In with Google**.
-3. Complete Google OAuth2 popup authentication.
-4. Verify server log processing:
+2. In `<ibgib-identity-header>`, click **Sign In** (which renders the streamlined `<ibgib-add-device>` component).
+3. Click **Continue with Google** (or enter `<E2E_TEST_GMAIL_ADDRESS_ALICE>` and complete 2FA).
+4. Complete Google OAuth2 popup authentication with `<E2E_TEST_GMAIL_ADDRESS_ALICE>`.
+5. Verify server log processing:
    - `[IdentityIndexService]` resolves `<E2E_TEST_GMAIL_ADDRESS_ALICE>` -> `primaryTjpAddr`.
-   - Server loads domain graph, verifies `custodian-manage-google` challenge pool, and issues delegate challenge.
-5. Verify client UI result:
-   - Browser receives delegate response and pairs device seamlessly.
+   - `[SsoLoginHandler]` loads domain graph, verifies `custodian-manage-google` challenge pool, and returns `custodianReqs`.
+6. Verify client UI result:
+   - Browser creates local sync delegate, registers it with the server, and pairs the device seamlessly.
    - Active identity header updates to `alice` with active status badge `🟢`.
+   - Zero password prompts are shown.
 
 
 ### Phase 5: Delegate Device Tagging & Revocation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/node-gib",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Node and server-specific ibGib code, i.e., things that don't run in the browser.",
   "funding": {
     "type": "individual",
@@ -25,8 +25,8 @@
   "license": "ISC",
   "dependencies": {
     "@ibgib/helper-gib": "^0.0.37",
-    "@ibgib/ts-gib": "^0.5.33",
-    "@ibgib/core-gib": "^0.1.73",
+    "@ibgib/ts-gib": "^0.5.34",
+    "@ibgib/core-gib": "^0.1.75",
     "@ibgib/encrypt-gib": "^0.3.1"
   },
   "devDependencies": {

package/src/serve-gib/handlers/api/identity/keystone-custodian-add-master-password.handler.mts

@@ -0,0 +1,245 @@
+/**
+ * @module serve-gib/handlers/api/identity/keystone-custodian-add-master-password.handler
+ *
+ * POST /api/identity/custodian/add-master-password
+ *
+ * Single-turn sovereignty elevation endpoint for purely custodial identities.
+ * Authenticates the user via fresh OAuth code or 6-digit email OTP, validates that
+ * the provided `newManagePool` config matches the existing custodian pool config,
+ * evolves the custodian manage pool into an auxiliary inward custodian pool (e.g. `custodian-manage-google`),
+ * installs the user's new sovereign pool as `manage`, and signs the evolution using the server's custodian secret.
+ */
+
+import { extractErrorMsg, hash } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { getTjpAddr } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { KeystoneChallengePool } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { KEYSTONE_VERB_MANAGE, POOL_ID_MANAGE } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+import { CUSTODIAN_POOL_ID_PREFIX } from '@ibgib/core-gib/dist/keystone/delegate/delegate-constants.mjs';
+import { KeystoneClaim } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { validateEmail } from '@ibgib/core-gib/dist/keystone/keystone-helpers.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { API_PATH_REGEXES } from '../../../path-constants.mjs';
+import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.mjs';
+import { getIdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
+import { normalizeEmail } from '../../../identity-index/identity-index-helpers.mjs';
+import { loadSsoServerConfig } from '../../../../identity/sso/sso-config-helper.mjs';
+import { SsoCustodianService } from '../../../../identity/sso/sso-custodian-service.mjs';
+import { SsoProviderId } from '../../../../identity/sso/sso-types.mjs';
+import { getPendingStagingDir, getPendingTjpHash, verifyPendingCode } from '../../../../email/verify/email-verify-helpers.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT || true;
+
+let custodian: SsoCustodianService | undefined;
+function getCustodian(): SsoCustodianService {
+    if (!custodian) {
+        const config = loadSsoServerConfig();
+        custodian = new SsoCustodianService(config);
+    }
+    return custodian;
+}
+
+export interface CustodianAddMasterPasswordRequestBody {
+    primaryTjpAddr: string;
+    newManagePool: KeystoneChallengePool;
+    providerId?: SsoProviderId;
+    code?: string;
+    redirectUri?: string;
+    email?: string;
+}
+
+export interface CustodianAddMasterPasswordResponseBody {
+    success: boolean;
+    primaryTjpAddr: string;
+    primaryKeystone: any;
+    message?: string;
+}
+
+/**
+ * POST /api/identity/custodian/add-master-password
+ */
+export class KeystoneCustodianAddMasterPasswordHandler extends ServeGibHandlerBase<undefined, undefined> {
+    protected override lc: string = `[${KeystoneCustodianAddMasterPasswordHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.KEYSTONE_CUSTODIAN_ADD_MASTER_PASSWORD;
+
+    protected async handleRouteImpl(
+        reqCtx: RequestContext<undefined, undefined>
+    ): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 8a1b2c3d4e5f67890a1b2c3d4e5f6790)`); }
+
+            if (reqCtx.method !== 'POST') {
+                return this.error(405, 'Method Not Allowed');
+            }
+
+            if (!reqCtx.body) {
+                return this.error(400, 'Request body is empty (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6791)');
+            }
+
+            let body: CustodianAddMasterPasswordRequestBody;
+            try {
+                body = JSON.parse(reqCtx.body);
+            } catch {
+                return this.error(400, 'Request body must be valid JSON (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6792)');
+            }
+
+            const { primaryTjpAddr, newManagePool, providerId, code, redirectUri, email } = body;
+
+            if (!primaryTjpAddr) {
+                return this.error(400, 'primaryTjpAddr is required (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6793)');
+            }
+
+            if (!newManagePool || typeof newManagePool !== 'object' || newManagePool.id !== POOL_ID_MANAGE) {
+                return this.error(400, 'newManagePool is invalid. Must be an object with id "manage" (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6794)');
+            }
+
+            if (!newManagePool.challenges || Object.keys(newManagePool.challenges).length === 0) {
+                return this.error(400, 'newManagePool must contain pre-generated public challenges (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6795)');
+            }
+
+            // 1. Authenticate user credentials via OAuth code or Email OTP
+            let verifiedEmail: string;
+            let effectiveProvider: string = providerId || 'email';
+
+            if (providerId && code && redirectUri) {
+                const service = getCustodian();
+                const userInfo = await service.getOAuthUserInfo(providerId, code, redirectUri);
+                if (!userInfo || !userInfo.email) {
+                    return this.error(401, `Failed to authenticate with SSO provider ${providerId} (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6796)`);
+                }
+                verifiedEmail = normalizeEmail(userInfo.email);
+            } else if (email && code) {
+                if (!validateEmail(email)) {
+                    return this.error(400, 'Invalid email address format (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6797)');
+                }
+                verifiedEmail = normalizeEmail(email);
+
+                const tjpHash = await getPendingTjpHash(primaryTjpAddr);
+                const pendingInfo = reqCtx.dataDir && tjpHash ? await getPendingStagingDir({ dataDir: reqCtx.dataDir, tjpHash }) : undefined;
+
+                if (!pendingInfo || pendingInfo.isExpired) {
+                    return this.error(400, 'Verification record missing or expired. Please request a new verification code. (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6798)');
+                }
+
+                const codeVerifyResult = await verifyPendingCode({
+                    pendingDir: pendingInfo.pendingDir,
+                    code,
+                });
+
+                if (!codeVerifyResult.valid) {
+                    return this.error(401, codeVerifyResult.error || 'Invalid verification code (E: 8a1b2c3d4e5f67890a1b2c3d4e5f6799)');
+                }
+            } else {
+                return this.error(400, 'Authentication credentials required (providerId+code+redirectUri or email+code) (E: 8a1b2c3d4e5f67890a1b2c3d4e5f679a)');
+            }
+
+            // 2. Lookup primary identity and confirm email matches
+            const indexService = getIdentityIndexService();
+            const identityRecord = await indexService.lookupIdentityByEmail({ email: verifiedEmail });
+            if (!identityRecord || identityRecord.primaryTjpAddr !== primaryTjpAddr) {
+                return this.error(403, `Authenticated email ${verifiedEmail} does not match primary identity ${primaryTjpAddr} (E: 8a1b2c3d4e5f67890a1b2c3d4e5f679b)`);
+            }
+
+            // 3. Bootstrap domain metaspace and load latest keystone
+            const metaspace = await bootstrapDomainMetaspace(primaryTjpAddr, reqCtx.dataDir);
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                return this.error(500, `Local domain space not found for identity ${primaryTjpAddr}`);
+            }
+
+            const keystoneService = new KeystoneService_V1();
+            const latestKeystone = await keystoneService.getLatestKeystone({
+                addr: primaryTjpAddr,
+                metaspace,
+                space
+            });
+
+            if (!latestKeystone || !latestKeystone.data) {
+                return this.error(404, `Primary identity keystone not found for address ${primaryTjpAddr}`);
+            }
+
+            // 4. Verify existing custodial manage pool
+            const prevPools = latestKeystone.data.challengePools || [];
+            const existingManagePool = prevPools.find(p => p.id === POOL_ID_MANAGE);
+            if (!existingManagePool) {
+                return this.error(400, 'Primary keystone missing active "manage" pool (E: 8a1b2c3d4e5f67890a1b2c3d4e5f679c)');
+            }
+
+            // Validate new pool config matches existing manage pool config structure
+            if (existingManagePool.config?.type && newManagePool.config?.type !== existingManagePool.config.type) {
+                return this.error(400, `newManagePool type "${newManagePool.config?.type}" does not match required type "${existingManagePool.config.type}" (E: 8a1b2c3d4e5f67890a1b2c3d4e5f679d)`);
+            }
+
+            // 5. Build next pool set:
+            // Convert existing custodian manage pool to auxiliary custodian pool (e.g. custodian-manage-google)
+            // and install user's newManagePool as 'manage'.
+            const custodianPoolId = `${CUSTODIAN_POOL_ID_PREFIX}${effectiveProvider}`;
+            const auxiliaryCustodianPool: KeystoneChallengePool = {
+                ...existingManagePool,
+                id: custodianPoolId,
+            };
+
+            const nextPools: KeystoneChallengePool[] = [];
+            for (const pool of prevPools) {
+                if (pool.id === POOL_ID_MANAGE) {
+                    nextPools.push(newManagePool);
+                    nextPools.push(auxiliaryCustodianPool);
+                } else if (pool.id === custodianPoolId) {
+                    // Skip if already present to prevent duplicate
+                } else {
+                    nextPools.push(pool);
+                }
+            }
+
+            // 6. Sign evolution turn using server's custodian secret
+            const ssoConfig = loadSsoServerConfig();
+            const serverSecret = ssoConfig.ssoServerKdfSecret;
+            const primarySecret = await hash({ s: `${serverSecret}_custodian_${verifiedEmail}` });
+
+            const claim: Partial<KeystoneClaim> = {
+                verb: KEYSTONE_VERB_MANAGE,
+                target: getIbGibAddr({ ibGib: latestKeystone })
+            };
+
+            const evolvedKeystone = await keystoneService.sign({
+                latestKeystone,
+                masterSecret: primarySecret,
+                claim,
+                poolId: POOL_ID_MANAGE,
+                metaspace,
+                space,
+                dataToPatch: {
+                    challengePools: nextPools,
+                    frameDetails: {
+                        action: 'add_master_password',
+                        custodyMode: 'hybrid',
+                        elevatedAt: new Date().toISOString(),
+                    }
+                }
+            });
+
+            // 7. Persist evolved keystone in domain space
+            await metaspace.put({ ibGibs: [evolvedKeystone], space });
+            await metaspace.registerNewIbGib({ ibGib: evolvedKeystone, space });
+
+            const response: CustodianAddMasterPasswordResponseBody = {
+                success: true,
+                primaryTjpAddr,
+                primaryKeystone: evolvedKeystone,
+                message: 'Successfully elevated identity to sovereign master password'
+            };
+
+            return this.ok(response);
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            return this.error(500, `Internal error adding master password: ${extractErrorMsg(error)}`);
+        }
+    }
+}

package/src/serve-gib/handlers/api/identity/keystone-custodian-add-master-password.respec.mts

@@ -0,0 +1,167 @@
+import { existsSync, rmSync } from 'node:fs';
+
+import {
+    respecfully,
+    iReckon,
+    ifWe,
+    ifWeMight
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import { KeystoneCustodianGenesisHandler } from './keystone-custodian-genesis.handler.mjs';
+import { KeystoneCustodianAddMasterPasswordHandler } from './keystone-custodian-add-master-password.handler.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { POOL_ID_MANAGE } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+import { CUSTODIAN_POOL_ID_PREFIX } from '@ibgib/core-gib/dist/keystone/delegate/delegate-constants.mjs';
+import { generatePoolChallenges } from '@ibgib/core-gib/dist/keystone/keystone-helpers.mjs';
+import { getPendingStagingDir, getPendingTjpHash, savePendingCodeRecord, savePendingStagingKeystone } from '../../../../email/verify/email-verify-helpers.mjs';
+import { resetIdentityIndexService } from '../../../identity-index/identity-index-service.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+await respecfully(sir, 'KeystoneCustodianAddMasterPasswordHandler', async () => {
+    const testDataDir = './test-data-custodian-add-password';
+
+    if (existsSync(testDataDir)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+
+    const origDataDir = process.env.DATA_DIR;
+    process.env.DATA_DIR = testDataDir;
+    process.env.KEYSTONE_PROFILE_CUSTODIAN_PRIMARY = 'primary-profile.dev';
+    process.env.SSO_SERVER_KDF_SECRET = 'test-sso-server-kdf-secret-12345';
+    process.env.SESSION_SECRET = 'test-session-secret-12345';
+    resetIdentityIndexService();
+
+    const genesisHandler = new KeystoneCustodianGenesisHandler();
+    const addPasswordHandler = new KeystoneCustodianAddMasterPasswordHandler();
+
+    await ifWe(sir, 'reject request with 400 if required fields are missing', async () => {
+        const reqCtx: any = {
+            method: 'POST',
+            pathname: '/api/identity/custodian/add-master-password',
+            url: new URL('http://localhost/api/identity/custodian/add-master-password'),
+            body: JSON.stringify({}),
+            dataDir: testDataDir
+        };
+
+        const res = await addPasswordHandler.handleRoute(reqCtx);
+        iReckon(sir, res?.status).isGonnaBe(400);
+    });
+
+    await ifWe(sir, 'successfully elevate custodial identity to sovereign master password', async () => {
+        try {
+            const email = 'alice.elevate@example.com';
+            const genesisCode = '123456';
+
+            // 1. Create custodial identity via genesis handler with staged code
+            const genesisStaging = await savePendingStagingKeystone({
+                primaryTjpAddr: `pending:${email}`,
+                emails: [email],
+                dataDir: testDataDir,
+            });
+            await savePendingCodeRecord({
+                pendingDir: genesisStaging.pendingDir,
+                code: genesisCode,
+            });
+
+            const genesisReqCtx: any = {
+                method: 'POST',
+                pathname: '/api/identity/custodian/genesis',
+                url: new URL('http://localhost/api/identity/custodian/genesis'),
+                body: JSON.stringify({ email, username: 'alice', code: genesisCode }),
+                dataDir: testDataDir
+            };
+
+            const genesisRes = await genesisHandler.handleRoute(genesisReqCtx);
+            if (genesisRes?.status !== 201) {
+                console.error(`[DEBUG] genesisRes failed: ${genesisRes?.status}, body:`, JSON.stringify(genesisRes?.body));
+            }
+            iReckon(sir, genesisRes?.status).isGonnaBe(201);
+
+            const genesisBody = typeof genesisRes?.body === 'string' ? JSON.parse(genesisRes?.body) : genesisRes?.body;
+            const primaryTjpAddr = genesisBody.primaryTjpAddr;
+            const initialKeystone = genesisBody.primaryKeystone;
+
+            iReckon(sir, primaryTjpAddr).not.isGonnaBeUndefined();
+            iReckon(sir, initialKeystone).not.isGonnaBeUndefined();
+
+            const initialManagePool = initialKeystone.data.challengePools.find((p: any) => p.id === POOL_ID_MANAGE);
+            iReckon(sir, initialManagePool).not.isGonnaBeUndefined();
+
+            // 2. Generate new sovereign manage challenge pool locally with user's new password
+            const userNewPassword = 'AliceSuperSecretPassphrase2026!';
+            const newChallenges = await generatePoolChallenges({
+                config: initialManagePool.config,
+                masterSecret: userNewPassword,
+            });
+            const newManagePool = {
+                id: POOL_ID_MANAGE,
+                config: initialManagePool.config,
+                challenges: newChallenges,
+            };
+
+            // Stage verification code for the elevation turn
+            const elevateStaging = await savePendingStagingKeystone({
+                primaryTjpAddr,
+                emails: [email],
+                dataDir: testDataDir,
+            });
+            const elevateCode = '654321';
+            await savePendingCodeRecord({
+                pendingDir: elevateStaging.pendingDir,
+                code: elevateCode,
+            });
+
+            // 3. Call add-master-password endpoint
+            const addPasswordReqCtx: any = {
+                method: 'POST',
+                pathname: '/api/identity/custodian/add-master-password',
+                url: new URL('http://localhost/api/identity/custodian/add-master-password'),
+                body: JSON.stringify({
+                    primaryTjpAddr,
+                    email,
+                    code: elevateCode,
+                    newManagePool,
+                }),
+                dataDir: testDataDir
+            };
+
+            const addPasswordRes = await addPasswordHandler.handleRoute(addPasswordReqCtx);
+            if (addPasswordRes?.status !== 200) {
+                console.error(`[DEBUG] addPasswordRes failed with status: ${addPasswordRes?.status}, body:`, addPasswordRes?.body);
+            }
+            iReckon(sir, addPasswordRes?.status).isGonnaBe(200);
+
+            const addPasswordBody = typeof addPasswordRes?.body === 'string' ? JSON.parse(addPasswordRes?.body) : addPasswordRes?.body;
+            iReckon(sir, addPasswordBody.success).isGonnaBeTrue();
+            iReckon(sir, addPasswordBody.primaryTjpAddr).isGonnaBe(primaryTjpAddr);
+
+            const evolvedKeystone = addPasswordBody.primaryKeystone;
+            iReckon(sir, evolvedKeystone).not.isGonnaBeUndefined();
+            iReckon(sir, evolvedKeystone.data.n).isGonnaBe(1);
+            iReckon(sir, evolvedKeystone.data.frameDetails.custodyMode).isGonnaBe('hybrid');
+
+            // Check pools: should contain both 'manage' and 'custodian-manage-email'
+            const poolIds = evolvedKeystone.data.challengePools.map((p: any) => p.id);
+            iReckon(sir, poolIds.includes('manage')).isGonnaBeTrue();
+            iReckon(sir, poolIds.includes(`${CUSTODIAN_POOL_ID_PREFIX}email`)).isGonnaBeTrue();
+
+            // 4. Verify user password solves the evolved manage pool
+            const keystoneService = new KeystoneService_V1();
+            const isUserPasswordValid = await keystoneService.verifySigningSecret({
+                keystoneIbGib: evolvedKeystone,
+                signingSecret: userNewPassword,
+                poolId: POOL_ID_MANAGE,
+            });
+            iReckon(sir, isUserPasswordValid).isGonnaBeTrue();
+        } catch (error) {
+            console.error(`[DEBUG TEST 2 EXCEPTION]`, error);
+            throw error;
+        }
+    });
+
+    if (existsSync(testDataDir)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+    process.env.DATA_DIR = origDataDir;
+});

package/src/serve-gib/handlers/api/identity/keystone-custodian-genesis.handler.mts

@@ -126,9 +126,12 @@ export class KeystoneCustodianGenesisHandler extends ServeGibHandlerBase<undefin
                 const metaspace = await bootstrapDomainMetaspace(primaryTjpAddr, reqCtx.dataDir);
                 const space = await metaspace.getLocalUserSpace({ lock: false });
                 if (space) {
-                    const latestAddr = await metaspace.getLatestAddr({ addr: primaryTjpAddr, space }) ?? primaryTjpAddr;
-                    const getRes = await metaspace.get({ addrs: [latestAddr], space });
-                    primaryKeystone = getRes.ibGibs?.[0];
+                    const keystoneService = new KeystoneService_V1();
+                    primaryKeystone = await keystoneService.getLatestKeystone({
+                        addr: primaryTjpAddr,
+                        metaspace,
+                        space
+                    });
                 }
             } else {
                 // New custodian identity creation

package/src/serve-gib/handlers/api/identity/keystone-custodian-register-delegate.handler.mts

@@ -140,9 +140,11 @@ export class KeystoneCustodianRegisterDelegateHandler extends ServeGibHandlerBas
                 return this.error(500, `Could not load domain space for primary identity ${custodianReqs.primaryTjpAddr}`);
             }
 
-            const latestPrimaryAddr = await metaspace.getLatestAddr({ addr: custodianReqs.primaryTjpAddr, space }) ?? custodianReqs.primaryTjpAddr;
-            const getRes = await metaspace.get({ addrs: [latestPrimaryAddr], space });
-            const parentKeystone = getRes.ibGibs?.[0] as KeystoneIbGib_V1 | undefined;
+            const parentKeystone = await keystoneService.getLatestKeystone({
+                addr: custodianReqs.primaryTjpAddr,
+                metaspace,
+                space
+            });
 
             if (!parentKeystone) {
                 return this.error(404, `Primary identity keystone not found for address ${custodianReqs.primaryTjpAddr}`);

package/src/serve-gib/handlers/api/identity/keystone-custodian-register-delegate.respec.mts

@@ -10,7 +10,7 @@ import { KeystoneCustodianGenesisHandler } from './keystone-custodian-genesis.ha
 import { KeystoneCustodianRegisterDelegateHandler } from './keystone-custodian-register-delegate.handler.mjs';
 import { KeystoneProfileBuilder } from '@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs';
 import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
-import { deriveLocalCustodianDelegateSecret } from '@ibgib/web-gib/dist/identity/custodian-delegate-helper.mjs';
+import { deriveDeviceDelegateSecret } from '@ibgib/core-gib/dist/keystone/delegate/delegate-helpers.mjs';
 import { bootstrapDomainMetaspace } from '../../../bootstrap-helper.mjs';
 
 const sir = `[${import.meta.url}]`;
@@ -58,8 +58,8 @@ await respecfully(sir, 'KeystoneCustodianRegisterDelegateHandler', async () => {
         iReckon(sir, custodianReqs).not.isGonnaBeUndefined();
 
         // Step 2: Build client delegate keystone containing custodianReqs
-        const delegateSecret = await deriveLocalCustodianDelegateSecret({ primaryTjpAddr });
-        const delegateBuilder = KeystoneProfileBuilder.buildKeystone('sync')
+        const delegateSecret = await deriveDeviceDelegateSecret({ primaryTjpAddr, deviceTag: 'phone' });
+        const delegateBuilder = KeystoneProfileBuilder.buildKeystone('sync-profile.dev')
             .withUsername('bob-sync-phone')
             .withDescription('Sync Delegate for bob on phone')
             .withDetails({

package/src/serve-gib/handlers/api/keystone/sso-login.handler.mts

@@ -8,7 +8,7 @@
  * generates a fresh single-turn `CustodianRequirements` payload, and returns it to the client.
  */
 
-import { extractErrorMsg, hash, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { extractErrorMsg, hash, getUUID, getSaferSubstring } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
 import { getTjpAddr } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
 import { KeystoneProfileBuilder } from '@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs';
 import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
@@ -103,7 +103,9 @@ export class SsoLoginHandler extends ServeGibHandlerBase<undefined, undefined> {
             }
 
             const email = userInfo.email.trim().toLowerCase();
-            const username = userInfo.name || email.split('@')[0];
+            const rawSSOName = userInfo.name || '';
+            const username = getSaferSubstring({ text: rawSSOName || email.split('@')[0], length: 62, keepLiterals: ['_', '-'] })
+                ;
 
             // 2. Check if primary identity exists for this email
             const ssoConfig = loadSsoServerConfig();
@@ -122,10 +124,12 @@ export class SsoLoginHandler extends ServeGibHandlerBase<undefined, undefined> {
                 primaryTjpAddr = existingLookup.primaryTjpAddr;
                 const domainMetaspace = await bootstrapDomainMetaspace(primaryTjpAddr, reqCtx.dataDir);
                 const space = await domainMetaspace.getLocalUserSpace({ lock: false });
-
-                const latestPrimaryAddr = await domainMetaspace.getLatestAddr({ addr: primaryTjpAddr, space: space! }) ?? primaryTjpAddr;
-                const getRes = await domainMetaspace.get({ addrs: [latestPrimaryAddr], space: space! });
-                primaryKeystone = getRes.ibGibs?.[0];
+                const keystoneService = new KeystoneService_V1();
+                primaryKeystone = await keystoneService.getLatestKeystone({
+                    addr: primaryTjpAddr,
+                    metaspace: domainMetaspace,
+                    space: space!
+                });
             } else {
                 // First-time custodian identity creation
                 isNewIdentity = true;
@@ -145,6 +149,8 @@ export class SsoLoginHandler extends ServeGibHandlerBase<undefined, undefined> {
                         client: 'space-gib-server',
                         role: 'custodian-primary',
                         custodianProvider: providerId,
+                        custodyMode: 'full',
+                        [`rawSSOName-${providerId}`]: rawSSOName,
                     });
 
                 const configs = await primaryBuilder.compileConfigs();