@ibgib/web-gib 0.0.59 → 0.0.60

package/src/ui/component/identity/add-device/add-device.mts

@@ -13,6 +13,8 @@ import { KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT, KEYSTONE_USERNAME_REGEXP } f
 import { deriveDelegateSecret } from "@ibgib/core-gib/dist/keystone/strategy/hash-reveal-v1/hash-reveal-v1.mjs";
 import { getTimelinesGroupedByTjp, getTjpAddr, toDto } from "@ibgib/core-gib/dist/common/other/ibgib-helper.mjs";
 import { updateSpecialIndex } from "@ibgib/core-gib/dist/timeline/timeline-api.mjs";
+import { validateEmail } from "@ibgib/core-gib/dist/keystone/keystone-helpers.mjs";
+import { FlatIbGibGraph } from "@ibgib/core-gib/dist/common/other/graph-types.mjs";
 
 import { getApiBridge } from "../../../../api/ibgib-api-bridge.mjs";
 import { getGlobalMetaspace_waitIfNeeded } from "../../../../helpers.mjs";
@@ -25,6 +27,9 @@ import { getComponentCtorArg } from "../../../../app-bootstrap/init-orchestratio
 import {
     EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, EVENT_IBGIB_UI_MESSAGE
 } from "../../../ui-constants.mjs";
+import { generateDefaultDeviceTag } from "../../../../util/device-helper.mjs";
+import { executeSsoOAuthPopup } from "../../../../identity/sso-popup-helper.mjs";
+import { deriveLocalCustodianDelegateSecret } from "../../../../identity/custodian-delegate-helper.mjs";
 
 export const ADD_DEVICE_COMPONENT_NAME = 'ibgib-add-device';
 
@@ -65,11 +70,20 @@ export class AddDeviceComponentMeta extends IbGibDynamicComponentMetaBase {
 interface AddDeviceElements extends ElementsBase {
     containerEl: HTMLDivElement;
     titleEl: HTMLHeadingElement;
+    subtitleEl: HTMLParagraphElement;
+    surfaceEntryEl: HTMLDivElement;
+    btnGoogleSso: HTMLButtonElement;
+    btnGithubSso: HTMLButtonElement;
     inputIdentifier: HTMLInputElement;
+    btnContinueEmail: HTMLButtonElement;
+    sectionCodeVerification: HTMLDivElement;
+    inputCode: HTMLInputElement;
+    btnVerifyCode: HTMLButtonElement;
+    sectionSovereignPassword: HTMLDivElement;
+    inputPassword: HTMLInputElement;
+    btnAuthorizePassword: HTMLButtonElement;
     inputDeviceTag: HTMLInputElement;
-    inputPassphrase: HTMLInputElement;
     checkboxMakeActive: HTMLInputElement;
-    btnAddDeviceEl: HTMLButtonElement;
     statusArea: HTMLDivElement;
     statusText: HTMLParagraphElement;
     resultAreaEl: HTMLDivElement;
@@ -85,6 +99,12 @@ export class AddDeviceComponentInstance
 
     protected lc: string = `[AddDeviceComponentInstance]`;
 
+    // Staged state across progressive surfaces
+    private _stagedEmail?: string;
+    private _stagedPrimaryTjpAddr?: string;
+    private _stagedPrimaryKeystone?: KeystoneIbGib_V1;
+    private _stagedPrimaryGraph?: FlatIbGibGraph;
+
     constructor() {
         super();
     }
@@ -94,21 +114,37 @@ export class AddDeviceComponentInstance
     }
 
     override async created(): Promise<void> {
-        this.elements = {} as AddDeviceElements;
-
-        this.elements.containerEl = this.shadowRoot!.getElementById('container') as HTMLDivElement;
-        this.elements.titleEl = this.shadowRoot!.getElementById('title') as HTMLHeadingElement;
-        this.elements.inputIdentifier = this.shadowRoot!.getElementById('input-identifier') as HTMLInputElement;
-        this.elements.inputDeviceTag = (this.shadowRoot!.getElementById('input-device-tag') || this.shadowRoot!.getElementById('input-device-name')) as HTMLInputElement;
-        this.elements.inputPassphrase = this.shadowRoot!.getElementById('input-passphrase') as HTMLInputElement;
-        this.elements.checkboxMakeActive = this.shadowRoot!.getElementById('checkbox-make-active') as HTMLInputElement;
-        this.elements.btnAddDeviceEl = this.shadowRoot!.getElementById('btn-add-device') as HTMLButtonElement;
-        this.elements.statusArea = this.shadowRoot!.getElementById('status-area') as HTMLDivElement;
-        this.elements.statusText = this.shadowRoot!.getElementById('status-text') as HTMLParagraphElement;
-        this.elements.resultAreaEl = this.shadowRoot!.getElementById('result-area') as HTMLDivElement;
-        this.elements.delegateAddrEl = this.shadowRoot!.getElementById('delegate-addr') as HTMLElement;
-
-        this.elements.contentEl = this.elements.containerEl;
+        const shadow = this.shadowRoot!;
+        const elements: AddDeviceElements = {} as AddDeviceElements;
+
+        elements.containerEl = shadow.getElementById('container') as HTMLDivElement;
+        elements.titleEl = shadow.getElementById('title') as HTMLHeadingElement;
+        elements.subtitleEl = shadow.getElementById('subtitle') as HTMLParagraphElement;
+        elements.surfaceEntryEl = shadow.getElementById('surface-entry') as HTMLDivElement;
+        elements.btnGoogleSso = shadow.getElementById('btn-google-sso') as HTMLButtonElement;
+        elements.btnGithubSso = shadow.getElementById('btn-github-sso') as HTMLButtonElement;
+        elements.inputIdentifier = shadow.getElementById('input-identifier') as HTMLInputElement;
+        elements.btnContinueEmail = shadow.getElementById('btn-continue-email') as HTMLButtonElement;
+        elements.sectionCodeVerification = shadow.getElementById('section-code-verification') as HTMLDivElement;
+        elements.inputCode = shadow.getElementById('input-code') as HTMLInputElement;
+        elements.btnVerifyCode = shadow.getElementById('btn-verify-code') as HTMLButtonElement;
+        elements.sectionSovereignPassword = shadow.getElementById('section-sovereign-password') as HTMLDivElement;
+        elements.inputPassword = shadow.getElementById('input-password') as HTMLInputElement;
+        elements.btnAuthorizePassword = shadow.getElementById('btn-authorize-password') as HTMLButtonElement;
+        elements.inputDeviceTag = shadow.getElementById('input-device-tag') as HTMLInputElement;
+        elements.checkboxMakeActive = shadow.getElementById('checkbox-make-active') as HTMLInputElement;
+        elements.statusArea = shadow.getElementById('status-area') as HTMLDivElement;
+        elements.statusText = shadow.getElementById('status-text') as HTMLParagraphElement;
+        elements.resultAreaEl = shadow.getElementById('result-area') as HTMLDivElement;
+        elements.delegateAddrEl = shadow.getElementById('delegate-addr') as HTMLElement;
+        elements.contentEl = elements.containerEl;
+
+        this.elements = elements;
+
+        // Auto-generate clean, friendly default device tag
+        if (elements.inputDeviceTag && !elements.inputDeviceTag.value) {
+            elements.inputDeviceTag.value = generateDefaultDeviceTag();
+        }
 
         this.initHandlers();
         await this.renderUI();
@@ -119,7 +155,12 @@ export class AddDeviceComponentInstance
     }
 
     private initHandlers() {
-        this.elements!.btnAddDeviceEl.addEventListener('click', () => this.handleAddDevice());
+        const elements = this.elements!;
+        elements.btnGoogleSso?.addEventListener('click', () => this.handleSsoClick('google'));
+        elements.btnGithubSso?.addEventListener('click', () => this.handleSsoClick('github'));
+        elements.btnContinueEmail?.addEventListener('click', () => this.handleContinueEmail());
+        elements.btnVerifyCode?.addEventListener('click', () => this.handleVerifyCode());
+        elements.btnAuthorizePassword?.addEventListener('click', () => this.handleAuthorizePassword());
 
         this.shadowRoot!.getElementById('btn-switch-create-account')?.addEventListener('click', (e) => {
             e.preventDefault();
@@ -130,158 +171,432 @@ export class AddDeviceComponentInstance
             }));
         });
 
-        this.elements!.inputIdentifier.addEventListener('input', () => {
-            this.elements!.inputIdentifier.classList.remove('invalid');
+        elements.inputIdentifier?.addEventListener('input', () => {
+            elements.inputIdentifier.classList.remove('invalid');
+        });
+        elements.inputCode?.addEventListener('input', () => {
+            elements.inputCode.classList.remove('invalid');
         });
-        this.elements!.inputDeviceTag.addEventListener('input', () => {
-            this.elements!.inputDeviceTag.classList.remove('invalid');
+        elements.inputPassword?.addEventListener('input', () => {
+            elements.inputPassword.classList.remove('invalid');
         });
-        this.elements!.inputPassphrase.addEventListener('input', () => {
-            this.elements!.inputPassphrase.classList.remove('invalid');
+        elements.inputDeviceTag?.addEventListener('input', () => {
+            elements.inputDeviceTag.classList.remove('invalid');
         });
     }
 
-    private setButtonLoading(isLoading: boolean) {
-        if (this.elements?.btnAddDeviceEl) {
-            this.elements.btnAddDeviceEl.disabled = isLoading;
-            this.elements.btnAddDeviceEl.textContent = isLoading ? 'Pairing...' : 'Pair & Add Device';
+    private getDeviceTag(): string {
+        const elements = this.elements!;
+        const raw = elements.inputDeviceTag?.value?.trim();
+        if (raw && KEYSTONE_USERNAME_REGEXP.test(raw)) {
+            return raw;
         }
+        const generated = generateDefaultDeviceTag();
+        if (elements.inputDeviceTag) {
+            elements.inputDeviceTag.value = generated;
+        }
+        return generated;
     }
 
-    /**
-     * Executes the Phase 1 Add-Device pairing orchestration flow.
-     */
-    protected async handleAddDevice() {
-        const lc = `${this.lc}[${this.handleAddDevice.name}]`;
+    // =========================================================================
+    // Flow 1: OAuth2 SSO Sign In (Google / GitHub)
+    // =========================================================================
+
+    protected async handleSsoClick(providerId: 'google' | 'github') {
+        const lc = `${this.lc}[${this.handleSsoClick.name}]`;
+        const providerName = providerId === 'google' ? 'Google' : 'GitHub';
+
+        this.setStatus(`Opening ${providerName} sign-in window...`, 'info');
+        this.showBusy({
+            isBusy: true,
+            title: 'Sign In via SSO',
+            msg: `Opening ${providerName} authorization window...\nPlease complete sign-in in the popup window.`,
+            animationEmoji: '🌐'
+        });
+
         try {
-            const humanEyeDelay = 500;
-            this.setStatus("Initializing device pairing...", "info");
-
-            const identifier = this.elements!.inputIdentifier.value.trim();
-            this.elements!.inputIdentifier.value = identifier;
-            if (!identifier) {
-                this.elements!.inputIdentifier.classList.add('invalid');
-                this.setStatus("Please enter a registered email.", "error");
+            const resPopup = await executeSsoOAuthPopup({ providerId });
+            if (!resPopup.success || !resPopup.code) {
+                this.setStatus(resPopup.message || `${providerName} sign-in cancelled.`, 'error');
                 return;
             }
 
-            const deviceTag = this.elements!.inputDeviceTag.value.trim();
-            this.elements!.inputDeviceTag.value = deviceTag;
-            if (!deviceTag || !KEYSTONE_USERNAME_REGEXP.test(deviceTag)) {
-                this.elements!.inputDeviceTag.classList.add('invalid');
-                this.setStatus("Please enter a valid Device Name (e.g. 'work-laptop').", "error");
+            this.setStatus(`Validating ${providerName} authorization...`, 'info');
+            this.showBusy({
+                isBusy: true,
+                title: 'Exchanging SSO Code...',
+                msg: `Validating ${providerName} authorization with 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 masterSecret = this.elements!.inputPassphrase.value.trim();
-            this.elements!.inputPassphrase.value = masterSecret;
-            if (!masterSecret) {
-                this.elements!.inputPassphrase.classList.add('invalid');
-                this.setStatus("Please enter your master passphrase.", "error");
+            const { primaryTjpAddr, custodianReqs, primaryKeystone } = resLogin;
+            const email = resLogin.userInfo?.email || '';
+            const username = email ? email.split('@')[0] : 'user';
+
+            await this.completeCustodialDelegateOnboarding({
+                primaryTjpAddr,
+                custodianReqs,
+                fallbackPrimaryKeystone: primaryKeystone,
+                fallbackPrimaryGraph: resLogin.primaryGraph,
+                email,
+                username,
+            });
+
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} SSO login error: ${emsg}`, error);
+            this.setStatus(`Error: ${emsg}`, 'error');
+        } finally {
+            this.showBusy({ isBusy: false });
+        }
+    }
+
+    // =========================================================================
+    // Flow 2: Email Sign In (2FA OTP Gate)
+    // =========================================================================
+
+    protected async handleContinueEmail() {
+        const lc = `${this.lc}[${this.handleContinueEmail.name}]`;
+        const elements = this.elements!;
+        const email = elements.inputIdentifier?.value?.trim();
+        if (!email || !validateEmail(email)) {
+            elements.inputIdentifier.classList.add('invalid');
+            this.setStatus('Please enter a valid email address.', 'error');
+            return;
+        }
+
+        elements.btnContinueEmail.disabled = true;
+        elements.btnContinueEmail.textContent = 'Checking...';
+        this.setStatus('Checking identity on server...', 'info');
+        this.showBusy({
+            isBusy: true,
+            title: 'Locating Identity...',
+            msg: 'Locating account on server...',
+            animationEmoji: '🔍'
+        });
+
+        try {
+            // 1. Look up primary identity keystone for this email
+            const resLookup = await getApiBridge().lookupPrimaryKeystone({ identifier: email });
+            if (!resLookup.success || !resLookup.tjpAddr) {
+                this.setStatus('No account found for this email address. Please click "Create Account" below.', 'error');
                 return;
             }
 
-            this.setButtonLoading(true);
+            this._stagedEmail = email;
+            this._stagedPrimaryTjpAddr = resLookup.tjpAddr;
+
+            // 2. Dispatch 6-digit verification code to email
+            this.setStatus('Dispatching 6-digit verification code...', 'info');
             this.showBusy({
                 isBusy: true,
-                title: 'Locating Identity...',
-                msg: 'Searching for primary identity...',
-                animationEmoji: '🔍'
+                title: 'Sending Code...',
+                msg: 'Dispatching 6-digit verification code to your email...',
+                animationEmoji: '✉️'
             });
 
-            const metaspace = await getGlobalMetaspace_waitIfNeeded();
-            const space = await metaspace.getLocalUserSpace({});
-            if (!space) { throw new Error("No default space found in metaspace."); }
+            const resCode = await getApiBridge().postVerificationCode({
+                email,
+                primaryTjpAddr: this._stagedPrimaryTjpAddr
+            });
+            if (!resCode.success) {
+                this.setStatus(resCode.message || 'Failed to dispatch verification code.', 'error');
+                return;
+            }
 
+            // 3. Transition UI to 6-digit PIN input prompt
+            elements.sectionCodeVerification.classList.remove('hidden');
+            elements.sectionCodeVerification.scrollIntoView({ behavior: 'smooth' });
+            this.setStatus(`Verification code sent to ${email}! Enter the 6-digit code above to continue.`, 'info');
+            elements.inputCode?.focus();
 
-            // 1a. First attempt to locate primary identity keystone locally in space
-            const keystonesIndex = await metaspace.getSpecialIbGib({
-                type: "keystones",
-                space,
-                initialize: true,
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`, error);
+            this.setStatus(`Error: ${emsg}`, 'error');
+        } finally {
+            elements.btnContinueEmail.disabled = false;
+            elements.btnContinueEmail.textContent = 'Continue with Email';
+            this.showBusy({ isBusy: false });
+        }
+    }
+
+    protected async handleVerifyCode() {
+        const lc = `${this.lc}[${this.handleVerifyCode.name}]`;
+        const elements = this.elements!;
+        const code = elements.inputCode?.value?.trim();
+        const email = this._stagedEmail;
+        const primaryTjpAddr = this._stagedPrimaryTjpAddr;
+
+        if (!email || !primaryTjpAddr) {
+            this.setStatus('Please enter your email and request a code first.', 'error');
+            return;
+        }
+
+        if (!code || code.length !== 6) {
+            elements.inputCode.classList.add('invalid');
+            this.setStatus('Please enter a 6-digit verification code.', 'error');
+            return;
+        }
+
+        elements.btnVerifyCode.disabled = true;
+        elements.btnVerifyCode.textContent = 'Verifying...';
+        this.setStatus('Verifying 6-digit code...', 'info');
+        this.showBusy({
+            isBusy: true,
+            title: 'Verifying Code...',
+            msg: 'Validating verification code with server...',
+            animationEmoji: '🔐'
+        });
+
+        try {
+            // First, attempt Custodian Genesis / Sign-In resolution
+            const resGenesis = await getApiBridge().postCustodianGenesis({ email, code });
+
+            if (resGenesis.success && resGenesis.primaryTjpAddr && resGenesis.custodianReqs) {
+                // -------------------------------------------------------------
+                // Path A: Custodial Account (100% Passwordless)
+                // -------------------------------------------------------------
+                const { primaryTjpAddr, custodianReqs, primaryKeystone, primaryGraph } = resGenesis;
+                const username = email ? email.split('@')[0] : 'user';
+
+                await this.completeCustodialDelegateOnboarding({
+                    primaryTjpAddr,
+                    custodianReqs,
+                    fallbackPrimaryKeystone: primaryKeystone,
+                    fallbackPrimaryGraph: primaryGraph,
+                    email,
+                    username,
+                });
+                return;
+            }
+
+            // -----------------------------------------------------------------
+            // Path B: Sovereign Account (Fetch Verified Graph, Reveal Password Prompt)
+            // -----------------------------------------------------------------
+            const resVerify = await getApiBridge().postVerifyCode({ email, primaryTjpAddr, code });
+            if (!resVerify.success) {
+                this.setStatus(resVerify.message || 'Verification failed. Please check the code.', 'error');
+                return;
+            }
+
+            this.setStatus('Retrieving identity graph from server...', 'info');
+            this.showBusy({
+                isBusy: true,
+                title: 'Loading Identity Graph...',
+                msg: 'Fetching cryptographic identity timeline from server...',
+                animationEmoji: '📥'
             });
-            const registeredAddrs: string[] = keystonesIndex?.rel8ns?.keystone ?? [];
-
-            let primaryKeystone: KeystoneIbGib_V1 | undefined;
-            for (const addr of registeredAddrs) {
-                const res = await metaspace.get({ addrs: [addr], space });
-                const found = res?.ibGibs?.[0] as KeystoneIbGib_V1 | undefined;
-                if (found && found.data) {
-                    const username = found.data.frameDetails?.username ?? '';
-                    const emails = found.data.emails ?? found.data.frameDetails?.emails ?? [];
-                    if (username.toLowerCase() === identifier.toLowerCase() || emails.some((e: string) => e.toLowerCase() === identifier.toLowerCase())) {
-                        primaryKeystone = found;
-                        break;
-                    }
-                }
+
+            const resGraph = await getApiBridge().getKeystoneGraph(primaryTjpAddr);
+            if (!resGraph.success || !resGraph.graph) {
+                this.setStatus('Failed to retrieve identity graph from server.', 'error');
+                return;
             }
 
-            // 1b. If not found locally, query server identity index
-            if (!primaryKeystone) {
-                this.setStatus("Locating identity on server...", "info");
-                const resLookup = await getApiBridge().lookupPrimaryKeystone({ identifier });
-                if (resLookup.success && resLookup.primaryKeystoneIbGib) {
-                    const fetchedKeystone = resLookup.primaryKeystoneIbGib as KeystoneIbGib_V1;
-                    const domainAddr = resLookup.tjpAddr || getIbGibAddr({ ibGib: fetchedKeystone });
-
-                    // Fetch full domain graph from server so local space has all historical keystone frames
-                    const resGraph = await getApiBridge().getKeystoneGraph(domainAddr);
-                    if (resGraph.success && resGraph.graph) {
-                        const graphIbGibs = Object.values(resGraph.graph);
-                        await metaspace.put({ ibGibs: graphIbGibs, space });
-
-                        // Order timelines by TJP and register each frame in ascending order
-                        const timelinesMap = getTimelinesGroupedByTjp({ ibGibs: graphIbGibs });
-                        for (const tjpKey of Object.keys(timelinesMap)) {
-                            const timeline = timelinesMap[tjpKey];
-                            for (const frame of timeline) {
-                                await metaspace.registerNewIbGib({ ibGib: frame, space });
-                            }
-                        }
-
-                        // Set primaryKeystone to the latest frame in the domain timeline
-                        const domainTimeline = timelinesMap[domainAddr] || timelinesMap[Object.keys(timelinesMap)[0]];
-                        if (domainTimeline && domainTimeline.length > 0) {
-                            primaryKeystone = domainTimeline[domainTimeline.length - 1] as KeystoneIbGib_V1;
-                        } else {
-                            primaryKeystone = fetchedKeystone;
-                        }
-                    } else {
-                        await metaspace.put({ ibGibs: [fetchedKeystone], space });
-                        await metaspace.registerNewIbGib({ ibGib: fetchedKeystone, space });
-                        primaryKeystone = fetchedKeystone;
+            this._stagedPrimaryGraph = resGraph.graph;
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (space) {
+                const graphIbGibs = Object.values(resGraph.graph);
+                await metaspace.put({ ibGibs: graphIbGibs, space });
+                const timelinesMap = getTimelinesGroupedByTjp({ ibGibs: graphIbGibs });
+                for (const tjpKey of Object.keys(timelinesMap)) {
+                    for (const frame of timelinesMap[tjpKey]) {
+                        await metaspace.registerNewIbGib({ ibGib: frame, space });
                     }
                 }
+                const domainTimeline = timelinesMap[primaryTjpAddr] || timelinesMap[Object.keys(timelinesMap)[0]];
+                if (domainTimeline && domainTimeline.length > 0) {
+                    this._stagedPrimaryKeystone = domainTimeline[domainTimeline.length - 1] as KeystoneIbGib_V1;
+                }
             }
 
-            if (!primaryKeystone) {
-                const msg = `No registered identity found for '${identifier}'. Please check your username/email or create a new account.`;
-                console.error(`${lc} ${msg}`);
-                this.setStatus(msg, "error");
-                this.showBusy({ isBusy: false });
-                this.setButtonLoading(false);
+            // Hide OTP section, reveal Sovereign Master Password prompt
+            elements.sectionCodeVerification.classList.add('hidden');
+            elements.sectionSovereignPassword.classList.remove('hidden');
+            elements.sectionSovereignPassword.scrollIntoView({ behavior: 'smooth' });
+            this.setStatus('2FA verified! Please enter your master password to authorize this device.', 'info');
+            elements.inputPassword?.focus();
+
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`, error);
+            this.setStatus(`Error: ${emsg}`, 'error');
+        } finally {
+            elements.btnVerifyCode.disabled = false;
+            elements.btnVerifyCode.textContent = 'Verify Code';
+            this.showBusy({ isBusy: false });
+        }
+    }
+
+    // =========================================================================
+    // DRY Custodial Delegation Helper (Shared by SSO & Email OTP)
+    // =========================================================================
+
+    private async completeCustodialDelegateOnboarding({
+        primaryTjpAddr,
+        custodianReqs,
+        fallbackPrimaryKeystone,
+        fallbackPrimaryGraph,
+        email,
+        username,
+    }: {
+        primaryTjpAddr: string;
+        custodianReqs: any;
+        fallbackPrimaryKeystone?: any;
+        fallbackPrimaryGraph?: FlatIbGibGraph;
+        email: string;
+        username?: string;
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.completeCustodialDelegateOnboarding.name}]`;
+        const deviceTag = this.getDeviceTag();
+
+        this.setStatus('Deriving local device delegate keys...', 'info');
+        this.showBusy({
+            isBusy: true,
+            title: 'Creating Sync Delegate...',
+            msg: `Generating cryptographic sync delegate keys for ${deviceTag}...`,
+            animationEmoji: '🔑'
+        });
+
+        const delegateSecret = await deriveLocalCustodianDelegateSecret({ primaryTjpAddr });
+        const userAlias = 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(`${userAlias}-sync-${deviceTag}`)
+            .withDescription(`Sync Delegate for ${userAlias} on ${deviceTag}`)
+            .withDetails({
+                client: 'space-gib-web',
+                role: 'sync-delegate',
+                deviceTag,
+                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 getApiBridge().postCustodianRegisterDelegate({ delegateKeystone });
+        if (!resRegister.success) {
+            this.setStatus(resRegister.message || 'Custodian delegate registration failed.', 'error');
+            return;
+        }
+
+        // Finalize onboarding into local space & special index
+        await this.finalizeDeviceOnboarding({
+            primaryKeystone: resRegister.evolvedPrimaryKeystone || fallbackPrimaryKeystone,
+            primaryGraph: resRegister.primaryGraph || fallbackPrimaryGraph,
+            delegateKeystone,
+            primaryTjpAddr,
+            delegateSecret,
+            makeActive: this.elements?.checkboxMakeActive?.checked ?? true
+        });
+    }
+
+    // =========================================================================
+    // Flow 3: Sovereign Master Password Unlock & Local Evolution
+    // =========================================================================
+
+    protected async handleAuthorizePassword() {
+        const lc = `${this.lc}[${this.handleAuthorizePassword.name}]`;
+        const elements = this.elements!;
+        const masterSecret = elements.inputPassword?.value?.trim();
+        const primaryKeystone = this._stagedPrimaryKeystone;
+        const primaryTjpAddr = this._stagedPrimaryTjpAddr;
+
+        if (!masterSecret) {
+            elements.inputPassword.classList.add('invalid');
+            this.setStatus('Please enter your master password.', 'error');
+            return;
+        }
+
+        if (!primaryKeystone || !primaryTjpAddr) {
+            this.setStatus('Missing staged primary identity context. Please restart sign-in.', 'error');
+            return;
+        }
+
+        elements.btnAuthorizePassword.disabled = true;
+        elements.btnAuthorizePassword.textContent = 'Authorizing...';
+        this.setStatus('Verifying master password locally...', 'info');
+        this.showBusy({
+            isBusy: true,
+            title: 'Verifying Password...',
+            msg: 'Verifying cryptographic password locally in browser...',
+            animationEmoji: '🔐'
+        });
+
+        try {
+            const keystoneService = new KeystoneService_V1();
+            const isValid = await keystoneService.verifySigningSecret({
+                keystoneIbGib: primaryKeystone,
+                signingSecret: masterSecret,
+                poolId: 'manage'
+            });
+
+            if (!isValid) {
+                elements.inputPassword.classList.add('invalid');
+                this.setStatus('Incorrect master password. Please try again.', 'error');
                 return;
             }
 
-            const primaryUsername = primaryKeystone.data?.frameDetails?.username ?? 'user';
+            const deviceTag = this.getDeviceTag();
+            const primaryUsername = primaryKeystone.data?.frameDetails?.username || 'user';
 
-            // 2. Generate local device delegate keystone
-            this.setStatus("Generating local device delegate...", "info");
+            this.setStatus(`Generating local sync delegate for ${deviceTag}...`, 'info');
             this.showBusy({
                 isBusy: true,
                 title: 'Generating Keys...',
-                msg: 'Generating cryptographic delegate keys for this device...',
+                msg: `Generating cryptographic delegate keys for ${deviceTag}...`,
                 animationEmoji: '🔑'
             });
 
-            const primaryTjpAddr = getTjpAddr({ ibGib: primaryKeystone, defaultIfNone: 'incomingAddr' });
-            if (!primaryTjpAddr) { throw new Error(`(UNEXPECTED) primaryTjpAddr falsy? couldn't get tjpAddr from primaryKeystone? (E: bc8cc8678e1ce4194ab02646160fde26)`); }
             const delegateSecret = await deriveDelegateSecret({ masterSecret });
-            const syncProfileName = process.env.KEYSTONE_PROFILE_SOVEREIGN_SYNC;
-            if (!syncProfileName || !syncProfileName.trim()) {
+            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: 8f9e0a1b2c3d4e5f67890123456789ab)');
             }
-            const delegateBuilder = KeystoneProfileBuilder.buildKeystone(syncProfileName.trim() as any)
+
+            const delegateBuilder = KeystoneProfileBuilder.buildKeystone(sovereignSyncProfileName.trim() as any)
                 .withUsername(`${primaryUsername}-sync-${deviceTag}`)
                 .withDescription(`Sync Delegate for ${primaryUsername} on ${deviceTag}`)
                 .withDetails({
@@ -290,113 +605,181 @@ export class AddDeviceComponentInstance
                     deviceTag,
                     primaryTjpAddr,
                 });
+
             const delegateConfigs = await delegateBuilder.compileConfigs();
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (!space) { throw new Error('No default space found in metaspace.'); }
 
-            const keystoneService = new KeystoneService_V1();
             const delegateKeystone = await keystoneService.genesis({
                 masterSecret: delegateSecret,
                 configs: delegateConfigs,
                 metaspace,
                 space,
-                frameDetails: delegateBuilder.getFrameDetails()
+                frameDetails: delegateBuilder.getFrameDetails(),
+                isPrimary: false
             });
 
-            const delegateAddr = getIbGibAddr({ ibGib: delegateKeystone });
-            console.log(`${lc} Local device delegate generated: ${delegateAddr}`);
-            await delay(humanEyeDelay);
-
-            // 3. Evolve parent primary keystone to register delegate
-            this.setStatus("Registering device on primary identity...", "info");
+            this.setStatus('Evolving primary identity to register delegate...', 'info');
             this.showBusy({
                 isBusy: true,
                 title: 'Registering Device...',
-                msg: 'Updating primary identity with new device delegate...',
-                animationEmoji: '📝'
+                msg: 'Evolving primary identity to register new device delegate...',
+                animationEmoji: '⚙️'
             });
 
-            const evolvedPrimaryKeystone = await keystoneService.registerDelegate({
+            const evolvedParentKeystone = await keystoneService.registerDelegate({
                 parentKeystone: primaryKeystone,
                 delegateKeystone,
                 masterSecret,
+                allowedVerbs: [KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT],
                 metaspace,
                 space,
-                allowedVerbs: [KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT],
-                deviceName: deviceTag,
+                deviceName: deviceTag
             });
 
-            const evolvedPrimaryAddr = getIbGibAddr({ ibGib: evolvedPrimaryKeystone });
-            console.log(`${lc} Primary identity evolved with delegate: ${evolvedPrimaryAddr}`);
-            await delay(humanEyeDelay);
-
-            // 4. Post evolved primary keystone + delegate to server
-            this.setStatus("Syncing device pairing to server...", "info");
+            this.setStatus('Publishing evolved identity to server...', 'info');
             this.showBusy({
                 isBusy: true,
                 title: 'Syncing to Server...',
-                msg: 'Posting device pairing to server sync node...',
-                animationEmoji: '🔄'
+                msg: 'Publishing evolved identity and delegate to server...',
+                animationEmoji: '⚡'
             });
 
-            // const domainAddr = primaryTjpAddr ? getIbGibAddr({ ibGib: primaryKeystone }) : getIbGibAddr({ ibGib: primaryKeystone });
-
             const resEvolve = await getApiBridge().putEvolveKeystone({
                 domainAddr: primaryTjpAddr,
-                keystoneIbGib: evolvedPrimaryKeystone,
+                keystoneIbGib: evolvedParentKeystone,
                 relatedKeystoneIbGibs: [delegateKeystone]
             });
-
             if (!resEvolve.success) {
-                const msg = `Server rejected device pairing: ${resEvolve.message}`;
-                console.error(`${lc} ${msg}`);
-                this.setStatus(msg, "error");
-                this.showBusy({ isBusy: false });
-                this.setButtonLoading(false);
-                return;
+                console.warn(`${lc} Warning syncing delegate evolution to server: ${resEvolve.message}`);
             }
 
-            // 5. Update local keystones index
-            this.showBusy({
-                isBusy: true,
-                title: 'Updating Local Indexes...',
-                msg: 'Registering new device in local index...',
-                animationEmoji: '💾'
+            await this.finalizeDeviceOnboarding({
+                primaryKeystone: evolvedParentKeystone,
+                primaryGraph: this._stagedPrimaryGraph,
+                delegateKeystone,
+                primaryTjpAddr,
+                masterSecret,
+                delegateSecret,
+                makeActive: elements.checkboxMakeActive?.checked ?? true
             });
 
-            await updateSpecialIndex({
-                type: "keystones",
-                rel8nInfos: [
-                    {
-                        rel8nName: "keystone",
-                        ibGibs: [
-                            toDto({ ibGib: evolvedPrimaryKeystone }),
-                            toDto({ ibGib: delegateKeystone })
-                        ],
-                    },
-                ],
-                metaspace,
-                space,
-            });
+        } catch (error) {
+            const emsg = extractErrorMsg(error);
+            console.error(`${lc} ${emsg}`, error);
+            this.setStatus(`Error: ${emsg}`, 'error');
+        } finally {
+            elements.btnAuthorizePassword.disabled = false;
+            elements.btnAuthorizePassword.textContent = 'Authorize & Pair Device';
+            this.showBusy({ isBusy: false });
+        }
+    }
 
-            // 6. Set as active identity if checked
-            if (this.elements!.checkboxMakeActive.checked) {
-                window.dispatchEvent(new CustomEvent(EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, {
-                    detail: { activeIdentityAddr: evolvedPrimaryAddr },
-                    bubbles: true,
-                    composed: true
-                }));
+    // =========================================================================
+    // Finalize Device Onboarding & Navigation
+    // =========================================================================
+
+    private async finalizeDeviceOnboarding({
+        primaryKeystone,
+        primaryGraph,
+        delegateKeystone,
+        primaryTjpAddr,
+        masterSecret,
+        delegateSecret,
+        makeActive = true,
+    }: {
+        primaryKeystone?: any;
+        primaryGraph?: FlatIbGibGraph;
+        delegateKeystone: any;
+        primaryTjpAddr: string;
+        masterSecret?: string;
+        delegateSecret?: string;
+        makeActive?: boolean;
+    }): Promise<void> {
+        const lc = `${this.lc}[${this.finalizeDeviceOnboarding.name}]`;
+        const humanEyeDelay = 500;
+
+        const metaspace = await getGlobalMetaspace_waitIfNeeded();
+        if (!metaspace) { throw new Error('Metaspace not found'); }
+        const space = await metaspace.getLocalUserSpace({});
+        if (!space) { throw new Error('Local user space not found'); }
+
+        // 1. Put primary frames and delegate into local space
+        if (primaryGraph) {
+            const graphIbGibs = Object.values(primaryGraph) as IbGib_V1[];
+            await metaspace.put({ ibGibs: graphIbGibs, space });
+            const timelinesMap = getTimelinesGroupedByTjp({ ibGibs: graphIbGibs });
+            for (const tjpKey of Object.keys(timelinesMap)) {
+                for (const frame of timelinesMap[tjpKey]) {
+                    await metaspace.registerNewIbGib({ ibGib: frame, space });
+                }
             }
+        } else if (primaryKeystone) {
+            await metaspace.put({ ibGibs: [primaryKeystone], space });
+            await metaspace.registerNewIbGib({ ibGib: primaryKeystone, space });
+        }
 
-            this.showBusy({ isBusy: false });
-            this.setButtonLoading(false);
-            this.elements!.delegateAddrEl.innerText = delegateAddr;
-            this.elements!.resultAreaEl.classList.remove('collapsed');
-            this.setStatus("Device successfully paired!", "success");
+        await metaspace.put({ ibGibs: [delegateKeystone], space });
+        await metaspace.registerNewIbGib({ ibGib: delegateKeystone, space });
 
-        } catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`, error);
-            this.setStatus(`Pairing failed: ${extractErrorMsg(error)}`, "error");
-            this.showBusy({ isBusy: false });
-            this.setButtonLoading(false);
+        // 2. Register in keystones special index
+        const ibGibsToRegister: IbGib_V1[] = [toDto({ ibGib: delegateKeystone })!];
+        if (primaryKeystone) {
+            ibGibsToRegister.unshift(toDto({ ibGib: primaryKeystone })!);
         }
+
+        await updateSpecialIndex({
+            type: 'keystones',
+            rel8nInfos: [{ rel8nName: 'keystone', ibGibs: ibGibsToRegister }],
+            metaspace,
+            space
+        });
+
+        // 3. Make active if checked
+        if (makeActive) {
+            window.dispatchEvent(new CustomEvent(EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, {
+                detail: { activeIdentityAddr: primaryTjpAddr },
+                bubbles: true,
+                composed: true
+            }));
+        }
+
+        // 4. Update UI results
+        const delegateAddr = getIbGibAddr({ ibGib: delegateKeystone });
+        if (this.elements?.delegateAddrEl) {
+            this.elements.delegateAddrEl.textContent = delegateAddr;
+        }
+        if (this.elements?.resultAreaEl) {
+            this.elements.resultAreaEl.classList.remove('collapsed');
+        }
+
+        const successMsg = 'Device paired and identity activated successfully!';
+        this.setStatus(successMsg, 'success');
+        this.showBusy({
+            isBusy: true,
+            title: 'Success!',
+            msg: successMsg,
+            animationEmoji: '✅'
+        });
+
+        await delay(humanEyeDelay);
+
+        // 5. Navigate to 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 });
+    }
+
+    protected override async renderUI(): Promise<void> {
+        // No complex rendering needed
+    }
+
+    override async handleContextUpdated(): Promise<void> {
+        await this.renderUI();
     }
 }