@oxy.so/core 1.0.0

package/dist/cjs/session/accountDialogController.js

@@ -0,0 +1,1131 @@
+"use strict";
+/**
+ * Headless controller for the unified Oxy account dialog.
+ *
+ * A framework-agnostic state machine + subscribe/getSnapshot store (the same
+ * pattern {@link SessionClient} uses — no React, no RN) that both
+ * every `OxyProvider` platform variant (Expo/RN and RN-Web)
+ * bind to via `useSyncExternalStore`, so the account chooser is ONE
+ * implementation across the ecosystem instead of the five drifting copies it
+ * replaces.
+ *
+ * The controller owns:
+ *   - the device DIRECTORY (ADR 0002) — the server-authoritative read model of
+ *     who is on this device and what each of them may act as, read through
+ *     `SessionClient.refreshDirectory()`. It is not assembled here: the client
+ *     holds one caller's account graph and cannot enumerate another principal's,
+ *     so switchability is the server's answer and the controller only reads it;
+ *   - the dialog `view` state machine (`accounts` | `signin` | `qr` | `add` |
+ *     `signup`);
+ *   - `activateContext` (the ADR 0002 switch, keyed on the `principal acting as
+ *     account` pair) and the two removals an account id cannot name —
+ *     `signOutContext` and `signOutPrincipal`;
+ *   - the "Sign in with Oxy" device flow (same-device shared-keychain via
+ *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
+ *     via `startCommonsSignIn` → poll → `claimSessionByToken`);
+ *   - AUTOMATIC delivery selection for that flow (issue #691): the user presses
+ *     ONE primary action and the controller — not the user — picks how the
+ *     request reaches their Commons identity, by gathering the facts
+ *     (`platform`, `commonsAvailability`, and the `targets` a bearer-authorized
+ *     `deliverCommonsSignIn` reached) and handing them to the pure
+ *     `selectCommonsDelivery`. Exactly one route is primary; alternatives are
+ *     never chained behind it, they are state (`signIn.route`,
+ *     `signIn.routeFailed`) the UI reveals on its own terms;
+ *   - honest, non-sensitive PROGRESS for that flow (`signIn.progress`), derived
+ *     only from real signals — the chosen route, `pushSentAt`, `openedAt`,
+ *     `authorized`, and the commit — never from an optimistic timeline;
+ *   - `commonsAvailability` — whether Commons is installed on this device
+ *     (native only, via the injected `canOpenApp` probe), so the QR view can
+ *     offer a "Get Commons" fallback instead of a same-device dead end.
+ *   - `startPasskeyHubSignIn` — on a non-Oxy web origin (where a WebAuthn
+ *     ceremony can't run locally, the RP-ID is bound to oxy.so), open a popup
+ *     at the auth.oxy.so passkey hub instead, scoped to the SAME device-flow
+ *     session `showQr` creates, and complete it via the SAME poll/socket/claim
+ *     engine. Falls back to `showQr`'s plain QR rendering if the popup is
+ *     blocked.
+ *
+ * Sign-in is passkey (WebAuthn) or the Commons QR / shared-keychain handoff —
+ * password, social login, and 2FA were removed ecosystem-wide. Account
+ * creation (`signup` view) is the same two identity backends: a passkey
+ * ceremony on web, or a Commons-created identity.
+ *
+ * The controller owns NO surface PRESENTATION: whether the account dialog is
+ * mounted, visible, or dismissed is the job of the shared surface stack
+ * (`@oxy.so/services` presents the `AccountDialog` surface into `@oxy.so/bloom`'s
+ * stack). This is a headless state machine only — it exposes `setView` /
+ * `add` / `startSignup` (the view axis) and `cancelSignIn` (device-flow
+ * teardown), never an `open` / `close` / `visible`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountDialogController = void 0;
+exports.createAccountDialogController = createAccountDialogController;
+const logger_1 = require("../logger");
+const errorUtils_1 = require("../utils/errorUtils");
+const authWebUrl_1 = require("../utils/authWebUrl");
+const socketLoader_1 = require("./socketLoader");
+const deviceDirectory_1 = require("./deviceDirectory");
+const commonsDelivery_1 = require("../utils/commonsDelivery");
+/**
+ * Derive the surface-facing progress from the flow's real facts. Pure, total,
+ * and the single place the ladder is defined.
+ *
+ * Ordering within `'waiting'` is most-specific-first, so a late-arriving weaker
+ * signal can never pull the display backwards.
+ */
+function deriveSignInProgress(facts) {
+    switch (facts.phase) {
+        case 'idle':
+        case 'error':
+            return 'idle';
+        case 'starting':
+            return 'preparing';
+        case 'authorized':
+            return 'confirming-identity';
+        case 'completed':
+            return 'identity-confirmed';
+        case 'waiting':
+            if (facts.openedAt !== null)
+                return 'opened-in-commons';
+            // `route === 'await-push'` is itself a server-confirmed dispatch (the
+            // route is only chosen when `deliverCommonsSignIn` reported ≥1 target),
+            // so it is a real signal — not an optimistic assumption that a push will
+            // arrive. `pushSentAt` is the same fact re-confirmed by the status poll.
+            if (facts.pushSentAt !== null || facts.route === 'await-push')
+                return 'delivered-to-commons';
+            return facts.route === null ? 'preparing' : 'awaiting-approval';
+    }
+}
+/**
+ * Slow FALLBACK poll cadence for the QR flow. The `/auth-session` socket delivers
+ * the approval instantly via `auth_update`; this poll only covers the case where
+ * the socket can't connect, so it is deliberately slow (was 3000 when polling was
+ * the sole mechanism).
+ */
+const DEFAULT_POLL_INTERVAL_MS = 12000;
+/** Socket.IO namespace the API emits QR-flow approval (`auth_update`) events on. */
+const AUTH_SESSION_NAMESPACE = '/auth-session';
+/**
+ * Commons's custom URL scheme. Probed via the injected `canOpenApp` to detect an
+ * installed Commons on the same device; the `oxycommons://approve?...` deep link
+ * itself is the flow's `qrPayload`.
+ */
+const COMMONS_APP_SCHEME = 'oxycommons://';
+const IDLE_SIGN_IN_FACTS = {
+    phase: 'idle',
+    authorizeCode: null,
+    qrPayload: null,
+    expiresAt: null,
+    error: null,
+    route: null,
+    routeFailed: false,
+    pushSentAt: null,
+    openedAt: null,
+};
+const IDLE_SIGN_IN = {
+    ...IDLE_SIGN_IN_FACTS,
+    progress: deriveSignInProgress(IDLE_SIGN_IN_FACTS),
+};
+/**
+ * Terminal SUCCESS state: the session was claimed and committed. Holds no live
+ * resources and no request handles — only the terminal progress the surface
+ * shows ("Identity confirmed") before it closes.
+ */
+const COMPLETED_SIGN_IN = {
+    ...IDLE_SIGN_IN_FACTS,
+    phase: 'completed',
+    progress: deriveSignInProgress({ ...IDLE_SIGN_IN_FACTS, phase: 'completed' }),
+};
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class AccountDialogController {
+    constructor(options) {
+        this.listeners = new Set();
+        // --- Internal (unprojected) state ---
+        this.view = 'accounts';
+        this.loading = false;
+        this.error = null;
+        this.activatingContextId = null;
+        this.removingContextId = null;
+        this.removingPrincipalId = null;
+        this.signIn = IDLE_SIGN_IN;
+        this.commonsAvailability = 'unknown';
+        // --- Sign-in device-flow bookkeeping ---
+        /** The secret device-flow token of the active QR flow (never surfaced). */
+        this.signInToken = null;
+        this.pollTimer = null;
+        /**
+         * The `/auth-session` socket for the active QR flow, or null (poll-only). Its
+         * `auth_update` event wakes {@link pollOnce} instantly instead of waiting for the
+         * slow fallback timer.
+         */
+        this.authSessionSocket = null;
+        /**
+         * Guards {@link pollOnce} against re-entrancy: the fallback timer and a socket
+         * `auth_update` wake can fire together — without this both could claim the
+         * single-use token concurrently.
+         */
+        this.pollInFlight = false;
+        /** The popup opened by {@link startPasskeyHubSignIn}, or `null`. */
+        this.activePopup = null;
+        /** Watches {@link activePopup}'s `closed` state; see {@link watchPopup}. */
+        this.popupWatchTimer = null;
+        // --- Store plumbing ---
+        this.unsubscribeSession = null;
+        this.unsubscribeTokens = null;
+        /** Last-observed SDK auth readiness (a planted bearer). Drives the fetch edge. */
+        this.authed = false;
+        this.started = false;
+        this.refreshSeq = 0;
+        this.oxyServices = options.oxyServices;
+        this.sessionClient = options.sessionClient;
+        this.clientId = options.clientId ?? null;
+        this.commitSession = options.commitSession;
+        this.onSignedIn = options.onSignedIn;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.openUrl = options.openUrl;
+        this.canOpenApp = options.canOpenApp;
+        this.socketFactory = options.socketFactory;
+        this.openPopup = options.openPopup;
+        this.hubBaseUrl = options.hubBaseUrl ?? `https://auth.${authWebUrl_1.CENTRAL_IDP_APEX}`;
+        this.platform = options.platform ?? 'unknown';
+        this.snapshot = this.computeSnapshot();
+    }
+    // =========================================================================
+    // Store surface (useSyncExternalStore)
+    // =========================================================================
+    /** Returns the current immutable snapshot (stable reference between changes). */
+    getSnapshot() {
+        return this.snapshot;
+    }
+    /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    // =========================================================================
+    // Lifecycle
+    // =========================================================================
+    /**
+     * Begin driving the dialog: subscribe to `SessionClient` state and load the
+     * account list. Idempotent — a second `start()` is a no-op. Pair with
+     * {@link destroy}.
+     */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.authed = this.isAuthenticated();
+        this.unsubscribeSession = this.sessionClient.subscribe(() => {
+            // A device change (switch / sign-out / sibling sign-in) re-reads the
+            // directory inside `SessionClient` before it notifies, so the snapshot
+            // this rebuilds is already the new one — publish it and reconcile the
+            // auth-readiness edge. No profile fetch: the directory carries the display
+            // metadata a row needs.
+            this.emit();
+            this.reconcileAuth();
+        });
+        // The access token is planted AFTER `SessionClient.applyState` fires its
+        // subscription (`applySync` calls `setTokens` only once `applyState`/notify
+        // has returned; `ensureActiveToken` plants it async later), so the
+        // device-state subscription alone cannot observe the signed-out → signed-in
+        // edge. Observe the SDK-canonical readiness signal directly — a change to
+        // `oxyServices.getAccessToken()`, the `hasAccessToken` term of
+        // `OxyContext.canUsePrivateApi`.
+        this.unsubscribeTokens = this.oxyServices.onTokensChanged(() => {
+            this.reconcileAuth();
+        });
+        // Initial projection is device-only. `refresh()` fetches the graph IFF a
+        // bearer is already planted (warm start); when signed out (cold boot before
+        // restore) it re-projects from device state and makes NO private call.
+        void this.refresh();
+        // Eager, cached Commons-availability probe (native only — a no-op when no
+        // `canOpenApp` was injected). It's a cheap local OS check, so by the time a
+        // user actually opens the sign-in entry it has almost always resolved —
+        // `showQr`'s own lazy probe below is only the safety net for the rare race.
+        void this.resolveCommonsAvailability();
+    }
+    /**
+     * Stop driving the dialog: unsubscribe from `SessionClient` and tear down the
+     * active sign-in flow (timers). Idempotent.
+     */
+    destroy() {
+        this.started = false;
+        if (this.unsubscribeSession) {
+            this.unsubscribeSession();
+            this.unsubscribeSession = null;
+        }
+        if (this.unsubscribeTokens) {
+            this.unsubscribeTokens();
+            this.unsubscribeTokens = null;
+        }
+        this.clearPollTimer();
+        this.closeAuthSessionSocket();
+        this.closeActivePopup();
+        this.signInToken = null;
+        this.listeners.clear();
+    }
+    // =========================================================================
+    // Auth readiness (SDK-canonical — mirrors OxyContext.canUsePrivateApi)
+    // =========================================================================
+    /**
+     * Whether a PRIVATE endpoint may be called right now. Mirrors the
+     * `hasAccessToken` term of `OxyContext.canUsePrivateApi`
+     * (`authResolved && isAuthenticated && tokenReady && hasAccessToken`, where
+     * `hasAccessToken = Boolean(oxyServices.getAccessToken())`): a planted bearer
+     * is the only term that decides whether a request carries auth — the other
+     * three are provider render-lifecycle gates with no headless equivalent.
+     *
+     * `listAccounts()` (`GET /accounts`) and `getUsersByIds()`
+     * (`POST /users/by-ids`) are private; calling either before cold-boot restore
+     * plants the token 401s → `HttpService` clears the bearer + emits
+     * `onTokensChanged(null)` → the app signs out. Every graph/profile fetch gates
+     * on this.
+     */
+    isAuthenticated() {
+        return Boolean(this.oxyServices.getAccessToken());
+    }
+    /**
+     * Reconcile the account graph against the current auth-readiness edge. On the
+     * signed-out → signed-in edge fetch the graph ONCE; on signed-in → signed-out
+     * drop it and re-project device-only. A no-op when readiness is unchanged, so
+     * a burst of token events / device pushes cannot restart the fetch — and a
+     * failed `listAccounts()` never flips the edge, so it cannot re-trigger itself
+     * (no retry storm).
+     */
+    reconcileAuth() {
+        const authed = this.isAuthenticated();
+        if (authed === this.authed)
+            return;
+        this.authed = authed;
+        if (authed) {
+            void this.refresh();
+            return;
+        }
+        // Signed out. The directory is bearer-read and `SessionClient` drops the one
+        // it holds when the device empties, so there is nothing to clear here — only
+        // the in-flight bookkeeping, which no longer describes anything.
+        this.error = null;
+        this.loading = false;
+        this.emit();
+    }
+    // =========================================================================
+    // View actions
+    // =========================================================================
+    /** Set the dialog view directly. */
+    setView(view) {
+        if (this.view === view)
+            return;
+        this.view = view;
+        // A `'completed'` flow owns no timers, socket, popup, or token — it is only
+        // the terminal "Identity confirmed" the finished surface showed. Moving to
+        // another view is a NEW intention, so drop it; otherwise a later `add()`
+        // would open on the previous sign-in's terminal state.
+        if (this.signIn.phase === 'completed') {
+            this.signIn = IDLE_SIGN_IN;
+        }
+        this.emit();
+    }
+    /** Switch to the "add account" view (the sign-in entry chooser). */
+    add() {
+        this.setView('add');
+    }
+    /** Switch to the "create account" view (passkey / Commons signup entry). */
+    startSignup() {
+        this.setView('signup');
+    }
+    // =========================================================================
+    // The directory
+    // =========================================================================
+    /**
+     * Re-read `GET /session/device/directory`. Safe to call repeatedly;
+     * concurrent calls are reconciled by a sequence guard so a slow earlier read
+     * never overwrites a newer result.
+     *
+     * This is ONE request. It used to be three — the directory, plus
+     * `listAccounts()` and `getUsersByIds()` to rebuild the same tree client-side
+     * — and the reconstruction was not merely redundant: it enumerated the
+     * CALLER's account graph, which on a device holding two people is one
+     * person's answer presented as the device's.
+     */
+    async refresh() {
+        const seq = ++this.refreshSeq;
+        // Never read the directory while signed out: at cold boot the bearer is not
+        // planted yet, so the call 401s → `HttpService` clears the token and signs
+        // the user out.
+        if (!this.isAuthenticated()) {
+            this.loading = false;
+            this.error = null;
+            this.emit();
+            return;
+        }
+        // Nothing to show yet is the only state worth a spinner; a re-read behind an
+        // already-rendered directory refreshes in place.
+        this.loading = this.sessionClient.getDirectory() === null;
+        this.error = null;
+        this.emit();
+        try {
+            await this.sessionClient.refreshDirectory();
+        }
+        catch (error) {
+            // A 401 is the EXPECTED signed-out edge, not a failure: the bearer was
+            // stale/revoked, so `HttpService` already cleared it and emitted
+            // `onTokensChanged(null)`. Any OTHER error (network, 5xx, malformed) IS
+            // unexpected — surface it, and keep whatever directory is already held so
+            // an outage degrades rather than blanks the switcher.
+            if ((0, errorUtils_1.extractErrorStatus)(error) === 401) {
+                logger_1.logger.debug('[AccountDialogController] directory unauthorized (signed out)', { component: 'AccountDialogController' }, error);
+            }
+            else {
+                this.error = errorMessage(error);
+                logger_1.logger.warn('[AccountDialogController] directory refresh failed', { component: 'AccountDialogController' }, error);
+            }
+        }
+        if (seq !== this.refreshSeq)
+            return; // superseded by a newer refresh
+        this.loading = false;
+        this.emit();
+    }
+    // =========================================================================
+    // Activation and the two removals (ADR 0002)
+    // =========================================================================
+    /**
+     * Activate one `principal acting as account` context — the ADR 0002 switch,
+     * and the one that can express what an account id cannot: WHICH person's
+     * route to a shared organization to become.
+     *
+     * There is no on-device/graph fork. The directory has a row for a context the
+     * principal may act as but has never entered, and `POST /session/device/
+     * activate` reuses or mints the delegated session server-side, so one call
+     * covers both cases.
+     *
+     * A context id is not stable across a removal, so a stale one is an ordinary
+     * outcome rather than a bug: the server answers 404 or 403, heals the row, and
+     * the refresh below re-reads a directory that no longer offers it.
+     */
+    async activateContext(contextId) {
+        if (this.activatingContextId)
+            return false;
+        this.activatingContextId = contextId;
+        this.error = null;
+        this.emit();
+        try {
+            await this.sessionClient.activateContext(contextId);
+            await this.refresh();
+            return true;
+        }
+        catch (error) {
+            this.error = errorMessage(error);
+            return false;
+        }
+        finally {
+            this.activatingContextId = null;
+            this.emit();
+        }
+    }
+    /**
+     * Remove ONE `principal → account` pair, and only that pair.
+     *
+     * Not the account across the device: the same organization reached through a
+     * second person is a different session with a different audit actor, and it
+     * stays. Routing this through `signOut({accountId})` would revoke that second
+     * person's access as a side effect of one person tidying their own list.
+     *
+     * The removed pair is not gone for good while the membership lives — the
+     * server offers it again on the next read, under a NEW id and at an unchanged
+     * revision — so nothing may hold a context id across this call.
+     */
+    async signOutContext(contextId) {
+        if (this.removingContextId || this.removingPrincipalId)
+            return false;
+        this.removingContextId = contextId;
+        this.error = null;
+        this.emit();
+        try {
+            await this.sessionClient.signOutContext(contextId);
+            await this.refresh();
+            return true;
+        }
+        catch (error) {
+            this.error = errorMessage(error);
+            return false;
+        }
+        finally {
+            this.removingContextId = null;
+            this.emit();
+        }
+    }
+    /**
+     * Remove ONE PERSON and every context they reach — and nobody else's,
+     * including when another principal independently operates the same account.
+     *
+     * A separate call from {@link signOutContext} because it is a separate
+     * question, not a loop over the first one: the server removes the principal
+     * and elects a replacement active context in one transition.
+     */
+    async signOutPrincipal(principalId) {
+        if (this.removingContextId || this.removingPrincipalId)
+            return false;
+        this.removingPrincipalId = principalId;
+        this.error = null;
+        this.emit();
+        try {
+            await this.sessionClient.signOutPrincipal(principalId);
+            await this.refresh();
+            return true;
+        }
+        catch (error) {
+            this.error = errorMessage(error);
+            return false;
+        }
+        finally {
+            this.removingPrincipalId = null;
+            this.emit();
+        }
+    }
+    // =========================================================================
+    // Sign in with Oxy (device flow — shared keychain, else cross-device QR)
+    // =========================================================================
+    /**
+     * Start "Sign in with Oxy". Native devices with a shared identity mint a
+     * session silently (`signInWithSharedIdentity`); everything else (web, or a
+     * native device without a shared identity) falls through to the cross-device
+     * QR handoff.
+     */
+    async signInWithOxy() {
+        this.setView('qr');
+        this.setSignIn({ ...IDLE_SIGN_IN_FACTS, phase: 'starting' });
+        try {
+            const session = await this.oxyServices.signInWithSharedIdentity();
+            if (session) {
+                await this.completeSignIn(session, session.user);
+                return;
+            }
+        }
+        catch (error) {
+            // Shared-key mint failed — log and fall through to the QR handoff rather
+            // than dead-ending the sign-in.
+            logger_1.logger.warn('[AccountDialogController] signInWithSharedIdentity failed', { component: 'AccountDialogController' }, error);
+        }
+        await this.showQr();
+    }
+    /**
+     * Begin (or restart) the cross-device QR handoff: create a device-flow
+     * session, surface its `authorizeCode` + `qrPayload`, and poll for approval.
+     * On approval the secret token is exchanged (`claimSessionByToken`) and the
+     * session committed. Requires `clientId`.
+     */
+    async showQr() {
+        this.cancelSignIn();
+        this.setView('qr');
+        await this.startDeviceFlowSession({ deliver: true });
+    }
+    /**
+     * Web-only: "Sign in with a passkey" on a non-Oxy origin cannot run the
+     * WebAuthn ceremony locally — a credential minted with `WEBAUTHN_RP_ID=oxy.so`
+     * can only be asserted from `oxy.so`/a subdomain/loopback, a browser-enforced
+     * boundary `isOxyRpOrigin()` (consumer-side) already gates on. Instead, open
+     * a popup at the auth.oxy.so passkey hub, scoped to the SAME device-flow
+     * session {@link showQr} would create (same `authorizeCode`/`sessionToken`
+     * pair), and let the SAME poll/socket/claim engine complete it once the hub
+     * authorizes the session (`POST /auth/session/authorize-code/:authorizeCode`,
+     * bearer-authed, server-side — this method never sees or transmits the
+     * secret `sessionToken`).
+     *
+     * The popup MUST be opened synchronously, before any `await`, or the
+     * browser's popup blocker loses the click-gesture attribution and silently
+     * blocks it — so {@link openPopup} is invoked as the very first step, before
+     * the device-flow session (which needs an async call) even exists. If the
+     * popup is blocked (or no `openPopup` was injected), this falls back to
+     * `showQr`'s plain QR rendering — no dead end.
+     */
+    async startPasskeyHubSignIn() {
+        this.cancelSignIn();
+        this.setView('qr');
+        const popup = this.openPopup?.() ?? null;
+        if (!popup) {
+            await this.startDeviceFlowSession({ deliver: true });
+            return;
+        }
+        // The hub popup IS the primary surface here, chosen explicitly by the user —
+        // so this flow does NOT run automatic Commons delivery (ringing the user's
+        // phone because they asked for a passkey would be exactly the "menu of
+        // methods" the one-primary-action rule forbids). The underlying request is
+        // the same `AuthSession`, and its Commons route stays the QR the view
+        // renders beneath the popup.
+        const handle = await this.startDeviceFlowSession({ deliver: false });
+        if (!handle) {
+            popup.close();
+            return;
+        }
+        // The user may have closed the popup during the async session creation
+        // above, before any watcher was attached to catch it — guard rather than
+        // navigate a dead window (browsers vary on whether that throws).
+        if (popup.closed) {
+            this.failSignIn('Sign-in was cancelled.');
+            return;
+        }
+        this.activePopup = popup;
+        popup.location.href = `${this.hubBaseUrl}/hub-passkey?code=${encodeURIComponent(handle.authorizeCode)}`;
+        this.watchPopup(popup);
+    }
+    /**
+     * Shared device-flow session creation for both {@link showQr} (renders the
+     * QR) and {@link startPasskeyHubSignIn} (also opens the hub popup) — the
+     * same `startCommonsSignIn` → poll/socket wiring either way. Returns the
+     * handle on success (already reflected in `signIn`), or `null` on failure
+     * (already set as `signIn.error`).
+     *
+     * @param opts.deliver - Whether to run automatic Commons delivery selection
+     *   ({@link resolveDeliveryRoute}). `true` for the normal one-primary-action
+     *   entry; `false` when the caller already owns the primary surface (the
+     *   passkey hub popup), where the request's Commons route is simply the QR.
+     */
+    async startDeviceFlowSession(opts) {
+        if (!this.clientId) {
+            this.setSignIn({ ...IDLE_SIGN_IN_FACTS, phase: 'error', error: 'This app is not configured for sign-in (missing clientId).' });
+            return null;
+        }
+        this.setSignIn({ ...IDLE_SIGN_IN_FACTS, phase: 'starting' });
+        try {
+            const handle = await this.oxyServices.startCommonsSignIn({ clientId: this.clientId });
+            this.signInToken = handle.sessionToken;
+            this.setSignIn({
+                ...IDLE_SIGN_IN_FACTS,
+                phase: 'waiting',
+                authorizeCode: handle.authorizeCode,
+                qrPayload: handle.qrPayload,
+                expiresAt: handle.expiresAt,
+                // No route yet: the surface shows "Preparing request" until the primary
+                // route is resolved below. It is never guessed in the meantime.
+                route: opts.deliver ? null : 'qr',
+            });
+            // Primary path: an instant `auth_update` wake over the `/auth-session`
+            // socket. The poll below is only the fallback for when the socket can't
+            // connect, so it now runs at the slow fallback cadence.
+            this.openAuthSessionSocket(handle.sessionToken);
+            this.scheduleNextPoll(handle.sessionToken);
+            if (opts.deliver) {
+                // Non-blocking on purpose: the QR/authorizeCode are already renderable
+                // and the popup caller can navigate immediately, while the route (a
+                // local probe plus at most one delivery round-trip) resolves behind it.
+                void this.resolveDeliveryRoute(handle);
+            }
+            return handle;
+        }
+        catch (error) {
+            this.setSignIn({ ...IDLE_SIGN_IN_FACTS, phase: 'error', error: errorMessage(error) });
+            return null;
+        }
+    }
+    /**
+     * Choose and carry out the ONE primary delivery route for the active request
+     * (issue #691, "Automatic delivery selection").
+     *
+     * The controller gathers the facts — is a verified Commons link openable on
+     * THIS device, and how many known Commons installations did Oxy actually push
+     * to — and hands them to the pure {@link selectCommonsDelivery}. The selector
+     * owns the decision; this method owns only the observations and the single
+     * action the chosen route implies. It never cascades: a route that yields
+     * nothing resolves to QR *before* a route is chosen, never after.
+     */
+    async resolveDeliveryRoute(handle) {
+        if (!this.isAwaitingApproval(handle.sessionToken))
+            return;
+        // Fact 1 — a VERIFIED Commons link openable on this very device. Native
+        // only; on web `commonsAvailability` stays `'unknown'` (a browser cannot be
+        // asked whether a custom scheme is registered) and this is simply `false`.
+        if (this.canOpenApp &&
+            (this.commonsAvailability === 'unknown' || this.commonsAvailability === 'checking')) {
+            await this.resolveCommonsAvailability();
+            if (!this.isAwaitingApproval(handle.sessionToken))
+                return;
+        }
+        const commonsAvailable = this.commonsAvailability === 'available';
+        // Fact 2 — how many known Commons installations the server pushed to.
+        const pushTargets = await this.deliverToKnownCommons(handle.authorizeCode, commonsAvailable);
+        if (!this.isAwaitingApproval(handle.sessionToken))
+            return;
+        const route = (0, commonsDelivery_1.selectCommonsDelivery)({ platform: this.platform, commonsAvailable, pushTargets });
+        // The only route that has an action to perform on this device — and the only
+        // one that can fail here. `'await-push'` was already dispatched server-side;
+        // `'qr'` is rendered by the surface from `qrPayload`.
+        const routeFailed = route === 'open-commons' ? !this.openCommonsLink(handle.qrPayload) : false;
+        this.patchSignIn({ route, routeFailed });
+    }
+    /**
+     * Whether `sessionToken` is still THE request this surface is waiting on.
+     *
+     * Guards every step of the asynchronous route resolution: a cancelled,
+     * superseded, failed, or already-approved flow must neither open Commons nor
+     * mutate the surface — an approval that lands mid-resolution would otherwise
+     * be followed by a pointless app switch.
+     */
+    isAwaitingApproval(sessionToken) {
+        return this.signInToken === sessionToken && this.signIn.phase === 'waiting';
+    }
+    /**
+     * Ask Oxy to deliver the pending request to the identity's known Commons
+     * installations, returning how many it reached (`0` when delivery is not
+     * applicable, not permitted, or reached nobody).
+     *
+     * Two hard rules, both from the issue:
+     *  - **Never push from an unauthenticated surface.** `deliverCommonsSignIn`
+     *    is bearer-required precisely because a request that merely carries a
+     *    typed-in username must never be able to ring somebody's phone. Without a
+     *    planted bearer the call is not made AT ALL — not made-and-failed.
+     *  - **Zero targets and a failed delivery are the same normal outcome.** Both
+     *    return `0`, which resolves the primary route to QR silently. Neither is
+     *    surfaced as an error: there is nothing the user did wrong and nothing for
+     *    them to fix.
+     */
+    async deliverToKnownCommons(authorizeCode, commonsAvailable) {
+        // Route 1 (mobile with a verified local Commons link) reaches the identity
+        // on this very device — pushing as well would notify a second surface for a
+        // request the user is about to confirm here.
+        if (this.platform === 'mobile' && commonsAvailable)
+            return 0;
+        if (!this.isAuthenticated())
+            return 0;
+        try {
+            const result = await this.oxyServices.deliverCommonsSignIn(authorizeCode);
+            // `delivered: false` with `targets > 0` is a transport failure, not a
+            // reachable install — the shared helper owns that rule so the surface
+            // can never park a user on "check your phone" for a push that failed.
+            return (0, commonsDelivery_1.pushTargetsFromDelivery)(result);
+        }
+        catch (error) {
+            logger_1.logger.debug('[AccountDialogController] Commons delivery unavailable (QR route)', { component: 'AccountDialogController' }, error);
+            return 0;
+        }
+    }
+    /**
+     * Open the verified Commons link for the `'open-commons'` route. Returns
+     * whether the navigation was actually handed off, so a missing opener or a
+     * throwing one becomes an observable `routeFailed` instead of a silent dead
+     * end the user stares at.
+     */
+    openCommonsLink(qrPayload) {
+        if (!this.openUrl)
+            return false;
+        try {
+            this.openUrl(qrPayload);
+            return true;
+        }
+        catch (error) {
+            logger_1.logger.debug('[AccountDialogController] Commons deep link failed', { component: 'AccountDialogController' }, error);
+            return false;
+        }
+    }
+    /**
+     * Poll {@link PopupWindowHandle.closed} so a user who dismisses the hub
+     * popup without completing sign-in gets prompt feedback (there is no DOM
+     * event for a cross-origin popup closing — polling is the only mechanism).
+     * Cleared by {@link closeActivePopup}, which every sign-in exit path already
+     * calls.
+     */
+    watchPopup(popup) {
+        this.clearPopupWatchTimer();
+        this.popupWatchTimer = setInterval(() => {
+            if (!popup.closed)
+                return;
+            this.clearPopupWatchTimer();
+            if (this.signIn.phase === 'starting' || this.signIn.phase === 'waiting') {
+                // Closing the surface cancels the REQUEST too, not just this listener.
+                const pendingCode = this.signIn.authorizeCode;
+                this.failSignIn('Sign-in was cancelled.');
+                if (pendingCode) {
+                    void this.withdrawRequest(pendingCode);
+                }
+            }
+        }, 1000);
+    }
+    clearPopupWatchTimer() {
+        if (this.popupWatchTimer !== null) {
+            clearInterval(this.popupWatchTimer);
+            this.popupWatchTimer = null;
+        }
+    }
+    /** Tear down the popup watch timer and close the popup, if any. Idempotent. */
+    closeActivePopup() {
+        this.clearPopupWatchTimer();
+        const popup = this.activePopup;
+        this.activePopup = null;
+        if (!popup || popup.closed)
+            return;
+        try {
+            popup.close();
+        }
+        catch (error) {
+            logger_1.logger.debug('[AccountDialogController] popup close failed', { component: 'AccountDialogController' }, error);
+        }
+    }
+    /**
+     * Resolve whether Commons is installed on this device via the injected
+     * `canOpenApp` probe, updating {@link commonsAvailability} as durable,
+     * observable snapshot state. Native only — a no-op when `canOpenApp` was
+     * not injected (web), where `commonsAvailability` stays `'unknown'` forever
+     * and the QR view renders unconditionally (no gating).
+     *
+     * Replaces the old `maybeOpenCommons` fire-and-forget probe, whose outcome
+     * was only ever reflected by whether Commons silently opened — a probe
+     * failure or "not installed" answer was swallowed into a debug log with no
+     * way for the UI to react. `commonsAvailability` fixes that.
+     */
+    async resolveCommonsAvailability() {
+        if (!this.canOpenApp)
+            return;
+        this.commonsAvailability = 'checking';
+        this.emit();
+        let available = false;
+        try {
+            available = await this.canOpenApp(COMMONS_APP_SCHEME);
+        }
+        catch (error) {
+            logger_1.logger.debug('[AccountDialogController] Commons availability probe failed', { component: 'AccountDialogController' }, error);
+            available = false; // fail-closed — treat a probe error as "not installed"
+        }
+        this.commonsAvailability = available ? 'available' : 'unavailable';
+        this.emit();
+    }
+    /**
+     * Tear down the active sign-in device flow (timers + socket + popup + token),
+     * WITHDRAW the request server-side, and reset to idle.
+     *
+     * Cancellation has to converge in both directions: the surface closing must
+     * cancel the request, not just stop listening to it. Without the withdrawal a
+     * dismissed QR would stay approvable until it expired, so a later scan of a
+     * stale code could authorize a session nobody is waiting for.
+     */
+    cancelSignIn() {
+        // Capture before the teardown clears it, and only for a request that can
+        // still be approved — a completed/failed flow has nothing to withdraw.
+        const pendingCode = this.signIn.phase === 'starting' || this.signIn.phase === 'waiting'
+            ? this.signIn.authorizeCode
+            : null;
+        this.clearPollTimer();
+        this.closeAuthSessionSocket();
+        this.closeActivePopup();
+        this.signInToken = null;
+        if (this.signIn !== IDLE_SIGN_IN) {
+            this.setSignIn(IDLE_SIGN_IN_FACTS);
+        }
+        if (pendingCode) {
+            void this.withdrawRequest(pendingCode);
+        }
+    }
+    /**
+     * Best-effort server-side withdrawal of a request this surface abandoned
+     * (`POST /auth/session/deny/:authorizeCode`). Fire-and-forget by design: the
+     * local teardown already happened, and a race with an approval that just
+     * landed legitimately rejects here — neither outcome is worth surfacing.
+     */
+    async withdrawRequest(authorizeCode) {
+        try {
+            await this.oxyServices.denyCommonsSignIn(authorizeCode);
+        }
+        catch (error) {
+            logger_1.logger.debug('[AccountDialogController] request withdrawal failed', { component: 'AccountDialogController' }, error);
+        }
+    }
+    // =========================================================================
+    // Internal sign-in helpers
+    // =========================================================================
+    scheduleNextPoll(sessionToken) {
+        this.clearPollTimer();
+        this.pollTimer = setTimeout(() => {
+            void this.pollOnce(sessionToken);
+        }, this.pollIntervalMs);
+    }
+    /**
+     * Run one status check + (on approval) claim. Triggered by the fallback timer
+     * AND by the `/auth-session` socket's `auth_update` wake, so it is guarded
+     * against concurrent entry: whichever fires first claims the single-use token;
+     * the other no-ops. The `auth_update` payload is never trusted — this always
+     * re-checks the authoritative status via `pollCommonsSignIn`.
+     */
+    async pollOnce(sessionToken) {
+        // A superseded / cancelled flow must not act; a poll already running owns the claim.
+        if (this.signInToken !== sessionToken || this.pollInFlight)
+            return;
+        this.pollInFlight = true;
+        try {
+            const expiresAt = this.signIn.expiresAt;
+            if (typeof expiresAt === 'number' && Date.now() > expiresAt) {
+                this.failSignIn('Session expired. Please try again.');
+                return;
+            }
+            try {
+                const status = await this.oxyServices.pollCommonsSignIn(sessionToken);
+                if (this.signInToken !== sessionToken)
+                    return; // cancelled mid-request
+                // Delivery PROGRESS first: it is reported alongside every status, and
+                // recording it before the terminal branches means a poll that also
+                // carries the approval still leaves an honest trail behind it.
+                this.recordDeliveryProgress(status.pushSentAt, status.openedAt);
+                const purpose = status.purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in';
+                if (status.authorized && purpose === 'oauth_authorization') {
+                    // OAuth-bound sessions mint no sessionId on approval — they finalize
+                    // into an authorization code. The account dialog only starts device
+                    // sign-in today; stop rather than poll until expiry.
+                    this.failSignIn('This sign-in flow cannot be completed here. Use the app\'s OAuth sign-in instead.');
+                    return;
+                }
+                if (status.authorized && status.sessionId) {
+                    this.clearPollTimer();
+                    await this.claimAndComplete(status.sessionId, sessionToken);
+                    return;
+                }
+                if (status.status === 'cancelled') {
+                    this.failSignIn('Authorization was denied.');
+                    return;
+                }
+                if (status.status === 'expired') {
+                    this.failSignIn('Session expired. Please try again.');
+                    return;
+                }
+            }
+            catch (error) {
+                // Transient poll error — the next tick retries. Logged, never thrown.
+                logger_1.logger.debug('[AccountDialogController] poll error (will retry)', { component: 'AccountDialogController' }, error);
+            }
+            if (this.signInToken === sessionToken) {
+                this.scheduleNextPoll(sessionToken);
+            }
+        }
+        finally {
+            this.pollInFlight = false;
+        }
+    }
+    /**
+     * Record server-reported delivery progress on the active flow.
+     *
+     * Monotone and additive: a timestamp is only ever adopted, never replaced or
+     * cleared, so an older API build (or a partial payload) that omits a field can
+     * at most fail to advance the surface — it can never walk it backwards.
+     * Emits only on a real change, so a steady poll does not churn the snapshot.
+     */
+    recordDeliveryProgress(pushSentAt, openedAt) {
+        const nextPushSentAt = this.signIn.pushSentAt ?? pushSentAt ?? null;
+        const nextOpenedAt = this.signIn.openedAt ?? openedAt ?? null;
+        if (nextPushSentAt === this.signIn.pushSentAt && nextOpenedAt === this.signIn.openedAt)
+            return;
+        this.patchSignIn({ pushSentAt: nextPushSentAt, openedAt: nextOpenedAt });
+    }
+    async claimAndComplete(sessionId, sessionToken) {
+        this.patchSignIn({ phase: 'authorized' });
+        let claimed;
+        try {
+            claimed = await this.oxyServices.claimSessionByToken(sessionToken);
+        }
+        catch (error) {
+            this.failSignIn(errorMessage(error));
+            return;
+        }
+        if (!claimed?.accessToken || !claimed.user) {
+            this.failSignIn('Authorization succeeded but the session could not be claimed. Please try again.');
+            return;
+        }
+        // `SessionLoginResponse.user` is the minimal session-carried shape; the claim
+        // returns the full `User` (avatar is `string | null | undefined`). Normalize
+        // rather than widening the minimal shape to accept `null`.
+        const minimalUser = {
+            id: claimed.user.id,
+            username: claimed.user.username,
+            name: claimed.user.name,
+            avatar: claimed.user.avatar ?? undefined,
+        };
+        try {
+            await this.completeSignIn({
+                sessionId: claimed.sessionId || sessionId,
+                deviceId: claimed.deviceId ?? '',
+                expiresAt: claimed.expiresAt ?? '',
+                user: minimalUser,
+                accessToken: claimed.accessToken,
+                ...(claimed.deviceSecret ? { deviceSecret: claimed.deviceSecret } : {}),
+            }, minimalUser);
+        }
+        catch (error) {
+            this.failSignIn(errorMessage(error));
+        }
+    }
+    /**
+     * Commit an authorized session, notify, and return to the account list. Shared
+     * by the shared-key, QR, and mint-switch paths so they cannot drift.
+     */
+    async completeSignIn(session, user) {
+        await this.commitAuthorizedSession(session, user);
+        this.signInToken = null;
+        this.clearPollTimer();
+        this.closeAuthSessionSocket();
+        this.closeActivePopup();
+        // Terminal SUCCESS, not idle: the surface gets one honest frame to show
+        // "Identity confirmed" before it closes. Cleared on the next view change.
+        this.signIn = COMPLETED_SIGN_IN;
+        this.view = 'accounts';
+        this.emit();
+        this.onSignedIn?.(user);
+        await this.refresh();
+    }
+    /**
+     * Register a token-planted session into the device set. Prefers the
+     * consumer's commit funnel (durable persist + hydration); falls back to
+     * `SessionClient.registerAndActivate` (registration + activation only).
+     */
+    async commitAuthorizedSession(session, user) {
+        if (this.commitSession) {
+            await this.commitSession(session);
+        }
+        else {
+            await this.sessionClient.registerAndActivate(user.id);
+        }
+    }
+    failSignIn(message) {
+        this.clearPollTimer();
+        this.closeAuthSessionSocket();
+        this.closeActivePopup();
+        this.signInToken = null;
+        this.setSignIn({ ...IDLE_SIGN_IN_FACTS, phase: 'error', error: message });
+    }
+    clearPollTimer() {
+        if (this.pollTimer !== null) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    // =========================================================================
+    // /auth-session socket (instant QR approval wake — replaces 3s polling)
+    // =========================================================================
+    /**
+     * Subscribe the active QR flow to the `/auth-session` namespace so the API's
+     * `auth_update` event wakes {@link pollOnce} the instant the approval lands.
+     *
+     * The join is keyed by the secret `sessionToken` (the server's `auth:<token>`
+     * room, joined by emitting `join`) and re-issued on every (re)connect so it
+     * survives socket drops. `auth_update` is treated as a pure SIGNAL — the payload
+     * is never trusted; `pollOnce` re-checks the authoritative status and claims.
+     *
+     * No-op (poll-only) when the optional socket transport is unavailable. The
+     * namespace needs no auth.
+     */
+    async openAuthSessionSocket(sessionToken) {
+        this.closeAuthSessionSocket();
+        const socketFactory = this.socketFactory ?? (await (0, socketLoader_1.getSocketIO)());
+        if (!socketFactory || this.signInToken !== sessionToken)
+            return;
+        let socket;
+        try {
+            socket = socketFactory(`${this.oxyServices.getBaseURL()}${AUTH_SESSION_NAMESPACE}`, {
+                transports: ['websocket'],
+                autoConnect: true,
+                reconnection: true,
+                reconnectionAttempts: Number.POSITIVE_INFINITY,
+                reconnectionDelay: 1000,
+                reconnectionDelayMax: 10000,
+            });
+        }
+        catch (error) {
+            // Socket unavailable — the fallback poll still completes the flow.
+            logger_1.logger.debug('[AccountDialogController] auth-session socket create failed (poll fallback)', { component: 'AccountDialogController' }, error);
+            return;
+        }
+        const join = () => {
+            if (this.signInToken !== sessionToken)
+                return;
+            try {
+                socket.emit('join', sessionToken);
+            }
+            catch (error) {
+                logger_1.logger.debug('[AccountDialogController] auth-session join failed', { component: 'AccountDialogController' }, error);
+            }
+        };
+        socket.on('connect', join);
+        if (socket.connected)
+            join();
+        socket.on('auth_update', () => {
+            if (this.signInToken !== sessionToken)
+                return;
+            // Pure wake signal — re-check the authoritative status + claim the poll would have.
+            void this.pollOnce(sessionToken);
+        });
+        this.authSessionSocket = socket;
+    }
+    /** Tear down the `/auth-session` socket, if any. Idempotent. */
+    closeAuthSessionSocket() {
+        const socket = this.authSessionSocket;
+        if (!socket)
+            return;
+        this.authSessionSocket = null;
+        try {
+            socket.off('auth_update');
+            socket.off('connect');
+            socket.disconnect();
+        }
+        catch (error) {
+            logger_1.logger.debug('[AccountDialogController] auth-session socket close failed', { component: 'AccountDialogController' }, error);
+        }
+    }
+    // =========================================================================
+    // Snapshot plumbing
+    // =========================================================================
+    /**
+     * Replace the device-flow state from its FACTS, re-deriving `progress`. The
+     * only writer of `this.signIn` besides the two terminal constants — which is
+     * what keeps `progress` impossible to set by hand, and therefore impossible
+     * to advance without a fact behind it.
+     */
+    setSignIn(facts) {
+        this.signIn = { ...facts, progress: deriveSignInProgress(facts) };
+        this.emit();
+    }
+    /** Update a subset of the device-flow facts, re-deriving `progress`. */
+    patchSignIn(patch) {
+        const { phase, authorizeCode, qrPayload, expiresAt, error, route, routeFailed, pushSentAt, openedAt, } = this.signIn;
+        this.setSignIn({
+            phase,
+            authorizeCode,
+            qrPayload,
+            expiresAt,
+            error,
+            route,
+            routeFailed,
+            pushSentAt,
+            openedAt,
+            ...patch,
+        });
+    }
+    computeSnapshot() {
+        const directory = this.sessionClient.getDirectory();
+        return {
+            view: this.view,
+            directory,
+            activeContext: (0, deviceDirectory_1.resolveActiveContext)(directory),
+            loading: this.loading,
+            error: this.error,
+            activatingContextId: this.activatingContextId,
+            removingContextId: this.removingContextId,
+            removingPrincipalId: this.removingPrincipalId,
+            signIn: this.signIn,
+            commonsAvailability: this.commonsAvailability,
+        };
+    }
+    /** Recompute the snapshot and notify subscribers. */
+    emit() {
+        this.snapshot = this.computeSnapshot();
+        for (const listener of this.listeners) {
+            try {
+                listener(this.snapshot);
+            }
+            catch (error) {
+                logger_1.logger.error('[AccountDialogController] subscriber threw', error);
+            }
+        }
+    }
+}
+exports.AccountDialogController = AccountDialogController;
+/** Factory mirroring `createSessionClient`, for ergonomic wiring by consumers. */
+function createAccountDialogController(options) {
+    return new AccountDialogController(options);
+}