@ibgib/web-gib 0.0.59 → 0.0.61

package/dist/ui/component/identity/add-device/add-device.mjs

@@ -4,16 +4,19 @@ import commonComponentStylesCss from "../../common-component-styles.css";
 import { delay, extractErrorMsg, } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
 import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
 import { KeystoneService_V1 } from "@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs";
-import { KeystoneProfileBuilder } from "@ibgib/core-gib/dist/keystone/policy/keystone-profile-builder.mjs";
-import { KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT, KEYSTONE_USERNAME_REGEXP } 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";
-import { getTimelinesGroupedByTjp, getTjpAddr, toDto } from "@ibgib/core-gib/dist/common/other/ibgib-helper.mjs";
+import { KEYSTONE_USERNAME_REGEXP, KEYSTONE_VERB_SYNC, KEYSTONE_VERB_CONNECT } from "@ibgib/core-gib/dist/keystone/keystone-constants.mjs";
+import { deriveDelegateSecret, createSyncDelegateKeystone } from "@ibgib/core-gib/dist/keystone/delegate/delegate-helpers.mjs";
+import { getTimelinesGroupedByTjp, 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 { getApiBridge } from "../../../../api/ibgib-api-bridge.mjs";
 import { getGlobalMetaspace_waitIfNeeded } from "../../../../helpers.mjs";
 import { IbGibDynamicComponentMetaBase, IbGibFormInstanceBase, } from "../../ibgib-dynamic-component-bases.mjs";
 import { getComponentCtorArg } from "../../../../app-bootstrap/init-orchestration.mjs";
 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 { getOrCreateDeviceDelegateSecret, setDeviceDelegateSecret } from "../../../../identity/device-delegate-helper.mjs";
 export const ADD_DEVICE_COMPONENT_NAME = 'ibgib-add-device';
 /**
  * Metadata for the Add Device / Pairing component.
@@ -44,6 +47,11 @@ export class AddDeviceComponentMeta extends IbGibDynamicComponentMetaBase {
  */
 export class AddDeviceComponentInstance extends IbGibFormInstanceBase {
     lc = `[AddDeviceComponentInstance]`;
+    // Staged state across progressive surfaces
+    _stagedEmail;
+    _stagedPrimaryTjpAddr;
+    _stagedPrimaryKeystone;
+    _stagedPrimaryGraph;
     constructor() {
         super();
     }
@@ -51,19 +59,34 @@ export class AddDeviceComponentInstance extends IbGibFormInstanceBase {
         await super.initialize(opts);
     }
     async created() {
-        this.elements = {};
-        this.elements.containerEl = this.shadowRoot.getElementById('container');
-        this.elements.titleEl = this.shadowRoot.getElementById('title');
-        this.elements.inputIdentifier = this.shadowRoot.getElementById('input-identifier');
-        this.elements.inputDeviceTag = (this.shadowRoot.getElementById('input-device-tag') || this.shadowRoot.getElementById('input-device-name'));
-        this.elements.inputPassphrase = this.shadowRoot.getElementById('input-passphrase');
-        this.elements.checkboxMakeActive = this.shadowRoot.getElementById('checkbox-make-active');
-        this.elements.btnAddDeviceEl = this.shadowRoot.getElementById('btn-add-device');
-        this.elements.statusArea = this.shadowRoot.getElementById('status-area');
-        this.elements.statusText = this.shadowRoot.getElementById('status-text');
-        this.elements.resultAreaEl = this.shadowRoot.getElementById('result-area');
-        this.elements.delegateAddrEl = this.shadowRoot.getElementById('delegate-addr');
-        this.elements.contentEl = this.elements.containerEl;
+        const shadow = this.shadowRoot;
+        const elements = {};
+        elements.containerEl = shadow.getElementById('container');
+        elements.titleEl = shadow.getElementById('title');
+        elements.subtitleEl = shadow.getElementById('subtitle');
+        elements.surfaceEntryEl = shadow.getElementById('surface-entry');
+        elements.btnGoogleSso = shadow.getElementById('btn-google-sso');
+        elements.btnGithubSso = shadow.getElementById('btn-github-sso');
+        elements.inputIdentifier = shadow.getElementById('input-identifier');
+        elements.btnContinueEmail = shadow.getElementById('btn-continue-email');
+        elements.sectionCodeVerification = shadow.getElementById('section-code-verification');
+        elements.inputCode = shadow.getElementById('input-code');
+        elements.btnVerifyCode = shadow.getElementById('btn-verify-code');
+        elements.sectionSovereignPassword = shadow.getElementById('section-sovereign-password');
+        elements.inputPassword = shadow.getElementById('input-password');
+        elements.btnAuthorizePassword = shadow.getElementById('btn-authorize-password');
+        elements.inputDeviceTag = shadow.getElementById('input-device-tag');
+        elements.checkboxMakeActive = shadow.getElementById('checkbox-make-active');
+        elements.statusArea = shadow.getElementById('status-area');
+        elements.statusText = shadow.getElementById('status-text');
+        elements.resultAreaEl = shadow.getElementById('result-area');
+        elements.delegateAddrEl = shadow.getElementById('delegate-addr');
+        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();
     }
@@ -71,7 +94,12 @@ export class AddDeviceComponentInstance extends IbGibFormInstanceBase {
         // cleanup if needed
     }
     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();
             window.dispatchEvent(new CustomEvent(EVENT_IBGIB_UI_MESSAGE, {
@@ -80,249 +108,512 @@ export class AddDeviceComponentInstance extends IbGibFormInstanceBase {
                 composed: true
             }));
         });
-        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');
         });
     }
-    setButtonLoading(isLoading) {
-        if (this.elements?.btnAddDeviceEl) {
-            this.elements.btnAddDeviceEl.disabled = isLoading;
-            this.elements.btnAddDeviceEl.textContent = isLoading ? 'Pairing...' : 'Pair & Add Device';
+    getDeviceTag() {
+        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.
-     */
-    async handleAddDevice() {
-        const lc = `${this.lc}[${this.handleAddDevice.name}]`;
+    // =========================================================================
+    // Flow 1: OAuth2 SSO Sign In (Google / GitHub)
+    // =========================================================================
+    async handleSsoClick(providerId) {
+        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)
+    // =========================================================================
+    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;
             }
-            // 1a. First attempt to locate primary identity keystone locally in space
-            const keystonesIndex = await metaspace.getSpecialIbGib({
-                type: "keystones",
-                space,
-                initialize: true,
+            // 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();
+        }
+        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 });
+        }
+    }
+    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 = keystonesIndex?.rel8ns?.keystone ?? [];
-            let primaryKeystone;
-            for (const addr of registeredAddrs) {
-                const res = await metaspace.get({ addrs: [addr], space });
-                const found = res?.ibGibs?.[0];
-                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) => 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;
-                    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];
-                        }
-                        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];
+                }
             }
-            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)
+    // =========================================================================
+    async completeCustodialDelegateOnboarding({ primaryTjpAddr, custodianReqs, fallbackPrimaryKeystone, fallbackPrimaryGraph, email, username, }) {
+        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 metaspace = await getGlobalMetaspace_waitIfNeeded();
+        const space = await metaspace.getLocalUserSpace({ lock: false });
+        if (!space) {
+            this.setStatus('Could not access local user space.', 'error');
+            return;
+        }
+        const delegateSecret = await getOrCreateDeviceDelegateSecret({ primaryTjpAddr, deviceTag });
+        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 delegateKeystone = await createSyncDelegateKeystone({
+            profileName: custodianSyncProfileName.trim(),
+            username: userAlias,
+            deviceTag,
+            primaryTjpAddr,
+            delegateSecret,
+            custodianReqs,
+            additionalFrameDetails: { client: 'space-gib-web' },
+            metaspace,
+            space,
+        });
+        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
+    // =========================================================================
+    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';
-            // 2. Generate local device delegate keystone
-            this.setStatus("Generating local device delegate...", "info");
+            const deviceTag = this.getDeviceTag();
+            const primaryUsername = primaryKeystone.data?.frameDetails?.username || 'user';
+            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 metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (!space) {
+                throw new Error('No default space found in metaspace.');
             }
             const delegateSecret = await deriveDelegateSecret({ masterSecret });
-            const syncProfileName = process.env.KEYSTONE_PROFILE_SOVEREIGN_SYNC;
-            if (!syncProfileName || !syncProfileName.trim()) {
+            await setDeviceDelegateSecret({ primaryTjpAddr, delegateSecret });
+            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())
-                .withUsername(`${primaryUsername}-sync-${deviceTag}`)
-                .withDescription(`Sync Delegate for ${primaryUsername} on ${deviceTag}`)
-                .withDetails({
-                client: 'space-gib-web',
-                role: 'sync-delegate',
+            const delegateKeystone = await createSyncDelegateKeystone({
+                profileName: sovereignSyncProfileName.trim(),
+                username: primaryUsername,
                 deviceTag,
                 primaryTjpAddr,
-            });
-            const delegateConfigs = await delegateBuilder.compileConfigs();
-            const keystoneService = new KeystoneService_V1();
-            const delegateKeystone = await keystoneService.genesis({
-                masterSecret: delegateSecret,
-                configs: delegateConfigs,
+                delegateSecret,
+                additionalFrameDetails: { client: 'space-gib-web' },
                 metaspace,
                 space,
-                frameDetails: delegateBuilder.getFrameDetails()
             });
-            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 updateSpecialIndex({
-                type: "keystones",
-                rel8nInfos: [
-                    {
-                        rel8nName: "keystone",
-                        ibGibs: [
-                            toDto({ ibGib: evolvedPrimaryKeystone }),
-                            toDto({ ibGib: delegateKeystone })
-                        ],
-                    },
-                ],
-                metaspace,
-                space,
+            await this.finalizeDeviceOnboarding({
+                primaryKeystone: evolvedParentKeystone,
+                primaryGraph: this._stagedPrimaryGraph,
+                delegateKeystone,
+                primaryTjpAddr,
+                masterSecret,
+                delegateSecret,
+                makeActive: elements.checkboxMakeActive?.checked ?? true
             });
-            // 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
-                }));
-            }
-            this.showBusy({ isBusy: false });
-            this.setButtonLoading(false);
-            this.elements.delegateAddrEl.innerText = delegateAddr;
-            this.elements.resultAreaEl.classList.remove('collapsed');
-            this.setStatus("Device successfully paired!", "success");
         }
         catch (error) {
-            console.error(`${lc} ${extractErrorMsg(error)}`, error);
-            this.setStatus(`Pairing failed: ${extractErrorMsg(error)}`, "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 });
-            this.setButtonLoading(false);
         }
     }
+    // =========================================================================
+    // Finalize Device Onboarding & Navigation
+    // =========================================================================
+    async finalizeDeviceOnboarding({ primaryKeystone, primaryGraph, delegateKeystone, primaryTjpAddr, masterSecret, delegateSecret, makeActive = true, }) {
+        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);
+            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 });
+        }
+        await metaspace.put({ ibGibs: [delegateKeystone], space });
+        await metaspace.registerNewIbGib({ ibGib: delegateKeystone, space });
+        // 2. Register in keystones special index
+        const ibGibsToRegister = [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);
+        // 4.5 Sanitize password input fields from DOM
+        if (this.elements?.inputPassword) {
+            this.elements.inputPassword.value = '';
+        }
+        // 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 });
+    }
+    async renderUI() {
+        // No complex rendering needed
+    }
+    async handleContextUpdated() {
+        await this.renderUI();
+    }
 }
 //# sourceMappingURL=add-device.mjs.map