@ibgib/web-gib 0.0.57 → 0.0.59

package/src/ui/component/identity/keystone-creator/keystone-creator.mts

@@ -11,6 +11,7 @@ import { KeystoneService_V1 } from "@ibgib/core-gib/dist/keystone/keystone-servi
 import { KeystoneProfileBuilder } from "@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs";
 import { updateSpecialIndex, } from "@ibgib/core-gib/dist/timeline/timeline-api.mjs";
 import { toDto, getTjpAddr } from "@ibgib/core-gib/dist/common/other/ibgib-helper.mjs";
+import { FlatIbGibGraph } from "@ibgib/core-gib/dist/common/other/graph-types.mjs";
 import { validateEmail } from "@ibgib/core-gib/dist/keystone/keystone-helpers.mjs";
 import { KEYSTONE_USERNAME_REGEXP, KEYSTONE_DESCRIPTION_REGEXP, KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT } from "@ibgib/core-gib/dist/keystone/keystone-constants.mjs";
 import { deriveDelegateSecret } from "@ibgib/core-gib/dist/keystone/strategy/hash-reveal-v1/hash-reveal-v1.mjs";
@@ -23,8 +24,10 @@ import {
 } from "../../component-types.mjs";
 import { getComponentCtorArg } from "../../../../app-bootstrap/init-orchestration.mjs";
 import { getApiBridge } from "../../../../api/ibgib-api-bridge.mjs";
+import { deriveLocalCustodianDelegateSecret } from "../../../../identity/custodian-delegate-helper.mjs";
+import { executeSsoOAuthPopup } from "../../../../identity/sso-popup-helper.mjs";
 import { EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, EVENT_IBGIB_UI_MESSAGE } from "../../../ui-constants.mjs";
-import { shadowRoot_getElementById } from "../../../../helpers.web.mjs";
+import { alertUser, shadowRoot_getElementById } from "../../../../helpers.web.mjs";
 
 export const KEYSTONE_CREATOR_COMPONENT_NAME = 'ibgib-keystone-creator';
 
@@ -164,6 +167,59 @@ export class KeystoneCreatorComponentInstance
     }
 
     private initHandlers() {
+        // Mode Tab Switching (Quick vs Password-based)
+        const tabQuick = this.shadowRoot?.getElementById('tab-quick') as HTMLButtonElement | null;
+        const tabPassword = this.shadowRoot?.getElementById('tab-password') as HTMLButtonElement | null;
+        const panelQuick = this.shadowRoot?.getElementById('panel-quick') as HTMLDivElement | null;
+        const panelPassword = this.shadowRoot?.getElementById('panel-password') as HTMLDivElement | null;
+        const subtitleQuick = this.shadowRoot?.getElementById('subtitle-quick') as HTMLParagraphElement | null;
+        const subtitlePassword = this.shadowRoot?.getElementById('subtitle-password') as HTMLParagraphElement | null;
+
+        tabQuick?.addEventListener('click', () => {
+            tabQuick.classList.add('active');
+            tabPassword?.classList.remove('active');
+            panelQuick?.classList.remove('hidden');
+            panelPassword?.classList.add('hidden');
+            subtitleQuick?.classList.remove('hidden');
+            subtitlePassword?.classList.add('hidden');
+        });
+
+        tabPassword?.addEventListener('click', () => {
+            tabPassword.classList.add('active');
+            tabQuick?.classList.remove('active');
+            panelPassword?.classList.remove('hidden');
+            panelQuick?.classList.add('hidden');
+            subtitlePassword?.classList.remove('hidden');
+            subtitleQuick?.classList.add('hidden');
+        });
+
+        const btnGoogleSso = this.shadowRoot?.getElementById('btn-google-sso') as HTMLButtonElement | null;
+        btnGoogleSso?.addEventListener('click', () => this.handleSsoClick('google'));
+
+        const btnGithubSso = this.shadowRoot?.getElementById('btn-github-sso') as HTMLButtonElement | null;
+        btnGithubSso?.addEventListener('click', () => this.handleSsoClick('github'));
+
+        // Email Sign-In Info Button
+        const btnEmailInfo = this.shadowRoot?.getElementById('btn-email-info') as HTMLButtonElement | null;
+        btnEmailInfo?.addEventListener('click', (e) => {
+            e.preventDefault();
+            alertUser({
+                title: 'Custom Email Sign-In',
+                msg: 'When you enter your email address, we dispatch a 6-digit one-time verification code to your inbox.\n\nEntering the code creates your cryptographic identity delegate on your device and signs you in seamlessly without needing a password!'
+            });
+        });
+
+        // Quick Email Verification Code Handlers
+        const btnQuickSendCode = this.shadowRoot?.getElementById('btn-quick-send-code') as HTMLButtonElement | null;
+        const inputQuickEmail = this.shadowRoot?.getElementById('input-quick-email') as HTMLInputElement | null;
+        const secQuickOtp = this.shadowRoot?.getElementById('section-quick-otp') as HTMLDivElement | null;
+        const inputQuickOtp = this.shadowRoot?.getElementById('input-quick-otp') as HTMLInputElement | null;
+        const btnQuickVerifyCode = this.shadowRoot?.getElementById('btn-quick-verify-code') as HTMLButtonElement | null;
+
+        btnQuickSendCode?.addEventListener('click', () => this.handleQuickSendCode());
+
+        btnQuickVerifyCode?.addEventListener('click', () => this.handleQuickVerifyCode());
+
         this.elements!.btnGenerateEl.addEventListener('click', () => this.handleGenerate());
 
         this.shadowRoot!.getElementById('btn-switch-sign-in')?.addEventListener('click', (e) => {
@@ -176,16 +232,16 @@ export class KeystoneCreatorComponentInstance
         });
 
         // Clear invalid styling when user inputs text
-        this.elements!.inputUsername.addEventListener('input', () => {
+        this.elements!.inputUsername?.addEventListener('input', () => {
             this.elements!.inputUsername.classList.remove('invalid');
         });
-        this.elements!.inputDescription.addEventListener('input', () => {
+        this.elements!.inputDescription?.addEventListener('input', () => {
             this.elements!.inputDescription.classList.remove('invalid');
         });
-        this.elements!.inputEmail.addEventListener('input', () => {
+        this.elements!.inputEmail?.addEventListener('input', () => {
             this.elements!.inputEmail.classList.remove('invalid');
         });
-        this.elements!.inputSecret.addEventListener('input', () => {
+        this.elements!.inputSecret?.addEventListener('input', () => {
             this.elements!.inputSecret.classList.remove('invalid');
         });
     }
@@ -198,6 +254,292 @@ export class KeystoneCreatorComponentInstance
         }
     }
 
+    /**
+     * Triggered by Google / GitHub SSO buttons.
+     * Opens OAuth popup, exchanges authorization code, builds local delegate keystone,
+     * registers delegate on server, and finalizes onboarding.
+     */
+    protected async handleSsoClick(providerId: 'google' | 'github'): Promise<void> {
+        const lc = `${this.lc}[${this.handleSsoClick.name}]`;
+        const providerName = providerId === 'google' ? 'Google' : providerId === 'github' ? 'GitHub' : providerId;
+
+        this.setStatus(`Opening ${providerName} SSO authorization window...`, 'info');
+        this.showBusy({
+            isBusy: true,
+            title: `Connecting to ${providerName}...`,
+            msg: `Opening ${providerName} SSO authorization window...\nPlease complete authorization in the popup window.`,
+            animationEmoji: '🌐'
+        });
+
+        try {
+            const resPopup = await executeSsoOAuthPopup({ providerId });
+            if (!resPopup.success || !resPopup.code) {
+                this.setStatus(resPopup.message || `${providerName} sign-in cancelled.`, 'error');
+                return;
+            }
+
+            this.setStatus(`Exchanging ${providerName} authorization code...`, 'info');
+            this.showBusy({
+                isBusy: true,
+                title: 'Exchanging SSO Code...',
+                msg: `Validating ${providerName} authorization code with custodian server...`,
+                animationEmoji: '🔐'
+            });
+
+            const apiBridge = getApiBridge();
+            const resLogin = await apiBridge.postSsoLogin({
+                code: resPopup.code,
+                providerId,
+                redirectUri: resPopup.redirectUri!
+            });
+
+            if (!resLogin.success || !resLogin.primaryTjpAddr || !resLogin.custodianReqs) {
+                this.setStatus(resLogin.message || `${providerName} login failed.`, 'error');
+                return;
+            }
+
+            const { primaryTjpAddr, custodianReqs } = resLogin;
+            this.setStatus('Deriving local device delegate keys...', 'info');
+            this.showBusy({
+                isBusy: true,
+                title: 'Creating Sync Delegate...',
+                msg: 'Generating cryptographic sync delegate keys...',
+                animationEmoji: '🔑'
+            });
+
+            const delegateSecret = await deriveLocalCustodianDelegateSecret({ primaryTjpAddr });
+            const email = resLogin.userInfo?.email || '';
+            const username = email ? email.split('@')[0] : 'user';
+            const custodianSyncProfileName = process.env.KEYSTONE_PROFILE_CUSTODIAN_SYNC;
+            if (!custodianSyncProfileName || !custodianSyncProfileName.trim()) {
+                throw new Error('KEYSTONE_PROFILE_CUSTODIAN_SYNC environment variable is missing. Expected valid profile name like "sync-profile.dev" or "sync-profile.prod". (E: 4d5e6f7890123456789abcdef4)');
+            }
+
+            const delegateBuilder = KeystoneProfileBuilder.buildKeystone(custodianSyncProfileName.trim() as any)
+                .withUsername(`${username}-sync`)
+                .withDescription(`Sync Delegate for ${username}`)
+                .withDetails({
+                    client: 'space-gib-web',
+                    role: 'sync-delegate',
+                    primaryTjpAddr,
+                    custodianReqs,
+                });
+
+            const configs = await delegateBuilder.compileConfigs();
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                this.setStatus('Could not access local user space.', 'error');
+                return;
+            }
+
+            const keystoneService = new KeystoneService_V1();
+            const delegateKeystone = await keystoneService.genesis({
+                masterSecret: delegateSecret,
+                configs,
+                metaspace,
+                space,
+                frameDetails: delegateBuilder.getFrameDetails(),
+                isPrimary: false
+            });
+
+            this.setStatus('Registering device delegate with custodian server...', 'info');
+            this.showBusy({
+                isBusy: true,
+                title: 'Registering Delegate...',
+                msg: 'Registering local delegate with custodian server...',
+                animationEmoji: '📝'
+            });
+
+            const resRegister = await apiBridge.postCustodianRegisterDelegate({ delegateKeystone });
+            if (!resRegister.success) {
+                this.setStatus(resRegister.message || 'Custodian delegate registration failed.', 'error');
+                return;
+            }
+
+            // Finalize onboarding: update keystones index, activate identity, and navigate to identity manager
+            await this.finalizeIdentityOnboarding({
+                primaryKeystone: resRegister.evolvedPrimaryKeystone || resLogin.primaryKeystone,
+                primaryGraph: resRegister.primaryGraph || resLogin.primaryGraph,
+                delegateKeystone,
+                primaryTjpAddr,
+                delegateSecret,
+                makeActive: true
+            });
+
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`, error);
+            this.setStatus(`SSO sign-in error: ${emsg}`, 'error');
+        } finally {
+            this.showBusy({ isBusy: false });
+        }
+    }
+
+    /**
+     * Triggered by the "Send 6-Digit Verification Code" button.
+     * Validates quick email input and dispatches a 6-digit OTP code to the user's inbox.
+     */
+    protected async handleQuickSendCode(): Promise<void> {
+        const lc = `${this.lc}[${this.handleQuickSendCode.name}]`;
+        const btnQuickSendCode = this.shadowRoot?.getElementById('btn-quick-send-code') as HTMLButtonElement | null;
+        const inputQuickEmail = this.shadowRoot?.getElementById('input-quick-email') as HTMLInputElement | null;
+        const secQuickOtp = this.shadowRoot?.getElementById('section-quick-otp') as HTMLDivElement | null;
+
+        const email = (inputQuickEmail?.value || '').trim();
+        if (!email || !validateEmail(email)) {
+            this.setStatus("Please enter a valid email address.", "error");
+            return;
+        }
+
+        if (btnQuickSendCode) {
+            btnQuickSendCode.disabled = true;
+            btnQuickSendCode.textContent = "Sending Verification Code...";
+        }
+        this.setStatus("Requesting verification code...", "info");
+
+        try {
+            const resCode = await getApiBridge().postVerificationCode({ email });
+            if (resCode.success) {
+                secQuickOtp?.classList.remove('hidden');
+                this.setStatus("✉️ 6-digit verification code sent to your email!", "success");
+            } else {
+                this.setStatus(resCode.message || "Failed to dispatch verification code.", "error");
+            }
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`);
+            this.setStatus(`Failed to dispatch verification code: ${emsg}`, "error");
+        } finally {
+            if (btnQuickSendCode) {
+                btnQuickSendCode.disabled = false;
+                btnQuickSendCode.textContent = "Send 6-Digit Verification Code";
+            }
+        }
+    }
+
+    /**
+     * Triggered by the "Verify Code" button.
+     * Submits 6-digit OTP code to custodian server, builds local sync delegate keystone,
+     * registers delegate on server, and finalizes onboarding.
+     */
+    protected async handleQuickVerifyCode(): Promise<void> {
+        const lc = `${this.lc}[${this.handleQuickVerifyCode.name}]`;
+        const inputQuickEmail = this.shadowRoot?.getElementById('input-quick-email') as HTMLInputElement | null;
+        const inputQuickOtp = this.shadowRoot?.getElementById('input-quick-otp') as HTMLInputElement | null;
+        const btnQuickVerifyCode = this.shadowRoot?.getElementById('btn-quick-verify-code') as HTMLButtonElement | null;
+
+        const email = (inputQuickEmail?.value || '').trim();
+        const code = (inputQuickOtp?.value || '').trim();
+        if (!code || code.length !== 6 || !/^\d{6}$/.test(code)) {
+            this.setStatus("Please enter a valid 6-digit verification code.", "error");
+            return;
+        }
+
+        if (btnQuickVerifyCode) {
+            btnQuickVerifyCode.disabled = true;
+            btnQuickVerifyCode.textContent = "Verifying...";
+        }
+        this.setStatus("Verifying code & completing onboarding...", "info");
+        this.showBusy({
+            isBusy: true,
+            title: 'Verifying Code...',
+            msg: 'Great! Juust a moment...\n(Validating code, promoting server domain space, other security stuff...)',
+            animationEmoji: '🔐'
+        });
+
+        try {
+            const resGenesis = await getApiBridge().postCustodianGenesis({ email, code });
+            if (!resGenesis.success || !resGenesis.primaryTjpAddr || !resGenesis.custodianReqs) {
+                this.setStatus(resGenesis.message || "Custodian verification failed.", "error");
+                return;
+            }
+
+            const primaryTjpAddr = resGenesis.primaryTjpAddr;
+            const custodianReqs = resGenesis.custodianReqs;
+
+            // Construct local delegate keystone
+            this.setStatus("Constructing local sync delegate...", "info");
+            this.showBusy({
+                isBusy: true,
+                title: 'Creating Sync Delegate...',
+                msg: 'Generating cryptographic sync delegate keys...',
+                animationEmoji: '🔑'
+            });
+
+            const delegateSecret = await deriveLocalCustodianDelegateSecret({ primaryTjpAddr });
+            const username = email ? email.split('@')[0] : 'user';
+            const custodianSyncProfileName = process.env.KEYSTONE_PROFILE_CUSTODIAN_SYNC;
+            if (!custodianSyncProfileName || !custodianSyncProfileName.trim()) {
+                throw new Error('KEYSTONE_PROFILE_CUSTODIAN_SYNC environment variable is missing. Expected valid profile name like "sync-profile.dev" or "sync-profile.prod". (E: 4d5e6f7890123456789abcdef4)');
+            }
+
+            const delegateBuilder = KeystoneProfileBuilder.buildKeystone(custodianSyncProfileName.trim() as any)
+                .withUsername(`${username}-sync`)
+                .withDescription(`Sync Delegate for ${username}`)
+                .withDetails({
+                    client: 'space-gib-web',
+                    role: 'sync-delegate',
+                    primaryTjpAddr,
+                    custodianReqs,
+                });
+
+            const configs = await delegateBuilder.compileConfigs();
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                this.setStatus("Failed to access local user space.", "error");
+                return;
+            }
+
+            const keystoneService = new KeystoneService_V1();
+            const delegateKeystone = await keystoneService.genesis({
+                masterSecret: delegateSecret,
+                configs,
+                metaspace,
+                space,
+                frameDetails: delegateBuilder.getFrameDetails(),
+                isPrimary: false
+            });
+
+            // Register delegate with server
+            this.setStatus("Registering device delegate with custodian server...", "info");
+            this.showBusy({
+                isBusy: true,
+                title: 'Registering Delegate...',
+                msg: 'Registering local delegate with custodian server...',
+                animationEmoji: '📝'
+            });
+
+            const resRegister = await getApiBridge().postCustodianRegisterDelegate({ delegateKeystone });
+            if (!resRegister.success) {
+                this.setStatus(resRegister.message || "Failed to register delegate with custodian server.", "error");
+                return;
+            }
+
+            // Finalize onboarding: update keystones index, activate identity, and navigate to identity manager
+            await this.finalizeIdentityOnboarding({
+                primaryKeystone: resRegister.evolvedPrimaryKeystone || resGenesis.primaryKeystone,
+                primaryGraph: resRegister.primaryGraph || resGenesis.primaryGraph,
+                delegateKeystone,
+                primaryTjpAddr,
+                delegateSecret,
+                makeActive: true
+            });
+
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`, error);
+            this.setStatus(`Error: ${emsg}`, "error");
+        } finally {
+            this.showBusy({ isBusy: false });
+            if (btnQuickVerifyCode) {
+                btnQuickVerifyCode.disabled = false;
+                btnQuickVerifyCode.textContent = "Verify Code";
+            }
+        }
+    }
+
     /**
      * Triggered by the "Generate" button.
      * Orchestrates: Secret -> Local Genesis -> Graph Collection -> Server Sync.
@@ -282,13 +624,14 @@ export class KeystoneCreatorComponentInstance
                 animationEmoji: '⚙️'
             });
 
-            // 1. Prepare Primary/Domain Keystone Configs
-            const isProd = process.env.NODE_ENV === 'production';
-            const requestedProfile = (process.env.KEYSTONE_PROFILE || 'domain').toLowerCase();
-            const profileName = (isProd && requestedProfile === 'test') ? 'domain' : requestedProfile;
-            console.log(`${lc} Using keystone policy profile '${profileName}' (I: 90123456789abcdef0123456789abcde)`);
+            // 1. Prepare Primary Keystone Configs
+            const sovereignPrimaryProfileName = process.env.KEYSTONE_PROFILE_SOVEREIGN_PRIMARY;
+            if (!sovereignPrimaryProfileName || !sovereignPrimaryProfileName.trim()) {
+                throw new Error('KEYSTONE_PROFILE_SOVEREIGN_PRIMARY environment variable is missing. Expected valid profile name like "primary-profile.dev" or "primary-profile.prod". (E: 3c4d5e6f7890123456789abcdef3)');
+            }
+            console.log(`${lc} Using sovereign primary keystone policy profile '${sovereignPrimaryProfileName}' (I: 90123456789abcdef0123456789abcde)`);
 
-            const builder = KeystoneProfileBuilder.buildKeystone(profileName as any)
+            const builder = KeystoneProfileBuilder.buildKeystone(sovereignPrimaryProfileName.trim() as any)
                 .withUsername(username)
                 .withDescription(description);
             if (email) {
@@ -300,10 +643,13 @@ export class KeystoneCreatorComponentInstance
             });
             const configs = await builder.compileConfigs();
 
-            // 2. Get local services
+            // 2. Prepare Metaspace/Space
             const metaspace = await getGlobalMetaspace_waitIfNeeded();
-            const space = await metaspace.getLocalUserSpace({});
-            if (!space) { throw new Error("No default space found in metaspace."); }
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) {
+                this.setStatus("Failed to access local user space.", "error");
+                return;
+            }
 
             // 3. Perform Genesis (Local)
             this.showBusy({
@@ -338,7 +684,12 @@ export class KeystoneCreatorComponentInstance
             });
 
             const delegateSecret = await deriveDelegateSecret({ masterSecret });
-            const delegateBuilder = KeystoneProfileBuilder.buildKeystone(profileName as any)
+            const sovereignSyncProfileName = process.env.KEYSTONE_PROFILE_SOVEREIGN_SYNC;
+            if (!sovereignSyncProfileName || !sovereignSyncProfileName.trim()) {
+                throw new Error('KEYSTONE_PROFILE_SOVEREIGN_SYNC environment variable is missing. Expected valid profile name like "sync-profile.dev" or "sync-profile.prod". (E: 5e6f7890123456789abcdef5)');
+            }
+
+            const delegateBuilder = KeystoneProfileBuilder.buildKeystone(sovereignSyncProfileName.trim() as any)
                 .withUsername(`${username}-sync`)
                 .withDescription(`Sync Delegate for ${username}`)
                 .withDetails({
@@ -385,7 +736,7 @@ export class KeystoneCreatorComponentInstance
             this.showBusy({
                 isBusy: true,
                 title: 'Syncing to Server...',
-                msg: 'Quarantining staging genesis keystone on server...',
+                msg: 'Staging pending genesis keystone on server...',
                 animationEmoji: '🔄'
             });
             const resSync = await getApiBridge().postGenesisKeystone(keystoneIbGib);
@@ -510,69 +861,16 @@ export class KeystoneCreatorComponentInstance
                 }
             }
 
-            // 5. Register with the keystones special index
-            this.showBusy({
-                isBusy: true,
-                title: 'Registering Identity...',
-                msg: 'Server sync succeeded!\nUpdating local identity indexes and scope settings...',
-                animationEmoji: '💾'
-            });
-            await delay(humanEyeDelay); // for human eyes, not needed for functionality
-            await updateSpecialIndex({
-                type: "keystones",
-                rel8nInfos: [
-                    {
-                        rel8nName: "keystone",
-                        ibGibs: [
-                            toDto({ ibGib: evolvedParentKeystoneIbGib }),
-                            toDto({ ibGib: delegateKeystoneIbGib })
-                        ],
-                    },
-                ],
-                metaspace,
-                space,
+            // 5. Finalize onboarding: update keystones index, activate identity, and navigate to identity manager
+            await this.finalizeIdentityOnboarding({
+                primaryKeystone: evolvedParentKeystoneIbGib,
+                delegateKeystone: delegateKeystoneIbGib,
+                primaryTjpAddr: evolvedParentAddr,
+                masterSecret,
+                delegateSecret,
+                makeActive: this.elements!.checkboxMakeActive?.checked ?? true
             });
 
-            // Expose for dev tools
-            (window as any).dev_domainI = evolvedParentKeystoneIbGib;
-            (window as any).dev_domainIMasterSecret = masterSecret;
-            (window as any).dev_syncDelegate = delegateKeystoneIbGib;
-            (window as any).dev_syncDelegateSecret = delegateSecret;
-
-            // 6. Request to make the new identity active if the checkbox is checked
-            const makeActive = this.elements!.checkboxMakeActive?.checked;
-            if (makeActive) {
-                window.dispatchEvent(new CustomEvent(EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, {
-                    detail: { activeIdentityAddr: evolvedParentAddr },
-                    bubbles: true,
-                    composed: true
-                }));
-            }
-
-            // 7. Success
-            const successMsg = "Identity successfully created and activated! Just a sec...";
-            this.showBusy({
-                isBusy: true,
-                title: 'Success!',
-                msg: successMsg,
-                animationEmoji: '✅'
-            });
-            await delay(humanEyeDelay); // for human eyes, not needed for functionality, because we'll redirect
-            await delay(humanEyeDelay); // for human eyes, not needed for functionality, because we'll redirect
-            await delay(humanEyeDelay); // for human eyes, not needed for functionality, because we'll redirect
-            await delay(humanEyeDelay); // for human eyes, not needed for functionality, because we'll redirect
-            this.elements!.keystoneAddrEl.textContent = evolvedParentAddr;
-            this.elements!.statusArea.classList.remove('hidden');
-            this.setStatus(successMsg, "success");
-            console.log(`${lc} ✓ ${successMsg} (I: 3396d8261978d7027895b71e27e9ab26)`);
-
-            // Dispatch UI message to close keystone-creator and show identity-manager
-            window.dispatchEvent(new CustomEvent(EVENT_IBGIB_UI_MESSAGE, {
-                detail: { action: 'show-identity-manager', addr: evolvedParentAddr },
-                bubbles: true,
-                composed: true
-            }));
-
         } catch (error) {
             const emsg = extractErrorMsg(error);
             console.error(`${lc} ${emsg}`, error);
@@ -586,6 +884,138 @@ export class KeystoneCreatorComponentInstance
         }
     }
 
+    /**
+     * DRY helper to register keystones in the local keystones special index,
+     * set the active identity, and navigate to the Identity Manager component.
+     */
+    private async finalizeIdentityOnboarding({
+        primaryKeystone,
+        primaryGraph,
+        delegateKeystone,
+        primaryTjpAddr,
+        masterSecret,
+        delegateSecret,
+        makeActive = true,
+    }: {
+        primaryKeystone?: IbGib_V1;
+        primaryGraph?: FlatIbGibGraph;
+        delegateKeystone: IbGib_V1;
+        primaryTjpAddr: string;
+        masterSecret?: string;
+        delegateSecret?: string;
+        makeActive?: boolean;
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.finalizeIdentityOnboarding.name}]`;
+        const humanEyeDelay = 500;
+
+        const metaspace = await getGlobalMetaspace_waitIfNeeded();
+        if (!metaspace) {
+            throw new Error(`(UNEXPECTED) metaspace falsy? Expected active global metaspace instance. (E: 2e37a8b6fe987449c5d8693a7d4a2827)`);
+        }
+
+        const space = await metaspace.getLocalUserSpace({});
+        if (!space) {
+            throw new Error(`(UNEXPECTED) space falsy? Expected valid default local user space from metaspace. (E: 1e37a8b6fe987449c5d8693a7d4a2826)`);
+        }
+
+        // 0. Persist all frames of primary identity graph into local browser space
+        if (primaryGraph) {
+            const graphIbGibs = Object.values(primaryGraph) as IbGib_V1[];
+            for (const frame of graphIbGibs) {
+                await metaspace.put({ ibGibs: [frame], space });
+                await metaspace.registerNewIbGib({ ibGib: frame, space });
+            }
+        } else if (primaryKeystone) {
+            await metaspace.put({ ibGibs: [primaryKeystone], space });
+            await metaspace.registerNewIbGib({ ibGib: primaryKeystone, space });
+        }
+
+        // 0.5 Verify primary keystone exists in local browser space via getLatestKeystone
+        const keystoneService = new KeystoneService_V1();
+        try {
+            await keystoneService.getLatestKeystone({
+                addr: primaryTjpAddr,
+                metaspace,
+                space
+            });
+        } catch (error) {
+            const emsg = `Primary identity keystone ${primaryTjpAddr} not found in local browser space! Error: ${extractErrorMsg(error)}`;
+            console.error(`${lc} ${emsg} (E: a123456789abcdef0123456789c0001)`);
+            throw new Error(emsg);
+        }
+
+        // 1. Register with the local keystones special index
+        this.showBusy({
+            isBusy: true,
+            title: 'Registering Identity...',
+            msg: 'Updating local identity indexes and scope settings...',
+            animationEmoji: '💾'
+        });
+        const ibGibsToRegister: IbGib_V1[] = [toDto({ ibGib: delegateKeystone })];
+
+        if (!primaryKeystone && !primaryGraph) { throw new Error(`(UNEXPECTED) primaryKeystone and primaryGraph both falsy? We should have gotten this back from the server. (E: e34cd882ac66633c75c53318a3b28826)`); }
+        if (!delegateKeystone) { throw new Error(`(UNEXPECTED) delegateKeystone falsy? We should have made this locally and even registered it with the server. (E: 56b1c396269e15f008b7e298c71bc826)`); }
+
+        if (primaryKeystone) {
+            ibGibsToRegister.unshift(toDto({ ibGib: primaryKeystone }));
+        }
+        await updateSpecialIndex({
+            type: "keystones",
+            rel8nInfos: [
+                {
+                    rel8nName: "keystone",
+                    ibGibs: ibGibsToRegister,
+                },
+            ],
+            metaspace,
+            space,
+        });
+
+        // Expose for dev tools debugging if available
+        if (masterSecret) {
+            (window as any).dev_domainI = primaryKeystone;
+            (window as any).dev_domainIMasterSecret = masterSecret;
+            (window as any).dev_syncDelegate = delegateKeystone;
+            (window as any).dev_syncDelegateSecret = delegateSecret;
+        }
+
+        // 2. Request to make the new identity active
+        if (makeActive) {
+            window.dispatchEvent(new CustomEvent(EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, {
+                detail: { activeIdentityAddr: primaryTjpAddr },
+                bubbles: true,
+                composed: true
+            }));
+        }
+
+        // 3. Display success status
+        const successMsg = "Identity successfully created and activated!";
+        this.showBusy({
+            isBusy: true,
+            title: 'Success!',
+            msg: successMsg,
+            animationEmoji: '✅'
+        });
+        await delay(humanEyeDelay);
+        if (this.elements?.keystoneAddrEl) {
+            this.elements.keystoneAddrEl.textContent = primaryTjpAddr;
+        }
+        if (this.elements?.statusArea) {
+            this.elements.statusArea.classList.remove('hidden');
+        }
+        this.setStatus(successMsg, "success");
+        console.log(`${lc} ✓ ${successMsg}`);
+
+        // 4. Dispatch UI navigation message to close creator and open identity manager
+        window.dispatchEvent(new CustomEvent(EVENT_IBGIB_UI_MESSAGE, {
+            detail: { action: 'show-identity-manager', addr: primaryTjpAddr },
+            bubbles: true,
+            composed: true
+        }));
+
+        this.showBusy({ isBusy: false });
+    }
+
     private setFormDisabled(disabled: boolean): void {
         const root = this.shadowRoot!;
         const inputIds = [