@oxy.so/core 1.0.0

package/dist/types/session/accountDialogController.d.ts

@@ -0,0 +1,648 @@
+/**
+ * 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`.
+ */
+import type { DeviceDirectory } from '@oxy.so/contracts';
+import type { OxyServices } from '../OxyServices';
+import type { SessionLoginResponse, MinimalUserData } from '../models/session';
+import type { SessionClient } from './SessionClient';
+import { type SocketIOFactory } from './socketLoader';
+import { type DeviceContext } from './deviceDirectory';
+import { type CommonsDeliveryPlatform, type CommonsDeliveryRoute } from '../utils/commonsDelivery';
+/** The dialog's top-level view. */
+export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add' | 'signup';
+/**
+ * Whether Commons is installed on this device, as resolved by the injected
+ * `canOpenApp` probe:
+ *   - `'unknown'` — not yet probed, OR no probe was injected (web — there is
+ *     no API to ask a browser whether a custom URL scheme is registered, so
+ *     this stays `'unknown'` forever there and the QR view renders
+ *     unconditionally, no gating).
+ *   - `'checking'` — the probe is in flight.
+ *   - `'available'` / `'unavailable'` — the probe's resolved terminal answer
+ *     (native only). A probe error is treated as `'unavailable'` (fail-closed).
+ */
+export type CommonsAvailability = 'unknown' | 'checking' | 'available' | 'unavailable';
+/**
+ * Lifecycle phase of the "Sign in with Oxy" device flow — the RESOURCE state
+ * (is there a live request, a claim in flight, a terminal outcome), as opposed
+ * to {@link SignInProgress}, which is what the user is told.
+ *
+ * `'completed'` is terminal-but-successful: the session was claimed and
+ * committed, nothing is in flight, and the surface may show "Identity
+ * confirmed" before it goes away. It is cleared back to `'idle'` the moment the
+ * dialog moves to another view (a new intention), so a later sign-in entry can
+ * never inherit the previous flow's terminal state.
+ */
+export type SignInFlowPhase = 'idle' | 'starting' | 'waiting' | 'authorized' | 'completed' | 'error';
+/**
+ * Ordered, non-sensitive progress of the active request — the ONE thing the
+ * sign-in surface renders its status line from (issue #691, Phase 5).
+ *
+ * Every step is DERIVED from a real fact the controller observed; there is no
+ * optimistic sequence and no timer that advances it. The mapping the UI is
+ * expected to render (copy lives in the UI layer, never here):
+ *
+ * | value                  | shown as                       | advanced by |
+ * |------------------------|--------------------------------|-------------|
+ * | `idle`                 | (nothing)                      | no live request, or a terminal error |
+ * | `preparing`            | "Preparing request"            | the request is being created / its route is still being resolved |
+ * | `awaiting-approval`    | route-specific waiting copy    | the primary route is known (`qr` → the QR itself, `open-commons` → "Continue in Commons") |
+ * | `delivered-to-commons` | "Check Commons on your phone"  | the server confirmed a push to ≥1 known Commons install (`await-push`, or `pushSentAt`) |
+ * | `opened-in-commons`    | "Opened in Commons"            | the approver reported `openedAt` |
+ * | `confirming-identity`  | "Confirming identity"          | the request reported `authorized`; the claim/commit is running |
+ * | `identity-confirmed`   | "Identity confirmed"           | the session was claimed and committed |
+ *
+ * `opened-in-commons` and `delivered-to-commons` are PROGRESS only — neither is
+ * evidence of an approval. Only `authorized` moves the flow forward.
+ */
+export type SignInProgress = 'idle' | 'preparing' | 'awaiting-approval' | 'delivered-to-commons' | 'opened-in-commons' | 'confirming-identity' | 'identity-confirmed';
+/**
+ * Minimal structural handle over a popup `Window` — just enough for the
+ * cross-origin passkey hub flow ({@link AccountDialogController.startPasskeyHubSignIn}):
+ * navigate it once the device-flow session's `authorizeCode` is known, detect
+ * the user closing it early (`closed`), and close it programmatically on
+ * completion/failure. Satisfied directly by `window.open()`'s return value on
+ * web; native has no popup concept and never injects an opener.
+ */
+export interface PopupWindowHandle {
+    readonly closed: boolean;
+    close(): void;
+    location: {
+        href: string;
+    };
+}
+/**
+ * State of the "Sign in with Oxy" (shared-key / QR) device flow.
+ *
+ * Everything here is safe to render. The flow's SECRET credential (the
+ * device-flow `sessionToken`) is deliberately absent — it never leaves the
+ * controller's private field, so no surface, log, or serialized snapshot can
+ * leak it.
+ */
+export interface SignInFlowState {
+    phase: SignInFlowPhase;
+    /**
+     * The PUBLIC, single-use authorize code (safe to display), or `null`. NOT the
+     * secret `sessionToken` — the approver resolves the app identity from this.
+     */
+    authorizeCode: string | null;
+    /**
+     * The structured deep-link / QR payload (`oxycommons://approve?...`) to render
+     * as a QR (cross-device) and open as a deep link (same-device), or `null`.
+     */
+    qrPayload: string | null;
+    /** Server-authoritative expiry (epoch ms), or `null`. */
+    expiresAt: number | null;
+    /** Human-readable error for the retry UI, or `null`. */
+    error: string | null;
+    /**
+     * The ONE primary delivery route the controller chose for this request
+     * ({@link selectCommonsDelivery}), or `null` while it is still being resolved.
+     *
+     * There is no chain: exactly one route is primary, and the UI renders exactly
+     * one action for it. Alternatives stay behind a "Having trouble?" affordance
+     * that the UI reveals on its own terms — see {@link routeFailed}.
+     */
+    route: CommonsDeliveryRoute | null;
+    /**
+     * `true` when the chosen primary route could NOT be carried out on this
+     * device — today only `'open-commons'` can fail this way (no URL opener was
+     * injected, or opening the verified Commons link threw). It is the signal the
+     * UI needs to reveal its alternatives; the controller never cascades to
+     * another route by itself.
+     *
+     * A push that reached zero installations is NOT a failure: no capable Commons
+     * install is a normal outcome that simply resolves the primary route to
+     * `'qr'`.
+     */
+    routeFailed: boolean;
+    /**
+     * Server-reported ISO-8601 timestamp of when the request was pushed to a
+     * known Commons installation, or `null`. Progress only — never evidence of an
+     * approval. Monotone: once observed it is never cleared by a later, emptier
+     * poll response.
+     */
+    pushSentAt: string | null;
+    /**
+     * Server-reported ISO-8601 timestamp of when the approval route was OPENED in
+     * Commons, or `null`. Progress only — never evidence of an approval. Monotone,
+     * like {@link pushSentAt}.
+     */
+    openedAt: string | null;
+    /**
+     * The derived, ordered progress the surface renders. Always computed from the
+     * facts above by {@link deriveSignInProgress} — never assigned directly, so it
+     * cannot drift from them or run ahead of a real signal.
+     */
+    progress: SignInProgress;
+}
+/** Immutable snapshot consumed by `useSyncExternalStore`. */
+export interface AccountDialogSnapshot {
+    /** The current view. */
+    view: AccountDialogView;
+    /**
+     * The server-authoritative device directory — principals and the contexts
+     * each may act as (ADR 0002) — or `null` before the first read.
+     *
+     * The ONE read model a switcher renders. The flat list this replaced was
+     * keyed by account id, so on a device holding two people it could show one
+     * route to a shared organization and never both.
+     */
+    directory: DeviceDirectory | null;
+    /** The active `principal acting as account` pair, actor and subject apart. */
+    activeContext: DeviceContext | null;
+    /** `true` while the first directory read is in flight with nothing to show. */
+    loading: boolean;
+    /** A human-readable directory error, or `null`. */
+    error: string | null;
+    /** The `contextId` of an in-flight activation, or `null`. */
+    activatingContextId: string | null;
+    /** The `contextId` of an in-flight context removal, or `null`. */
+    removingContextId: string | null;
+    /** The `principalId` of an in-flight principal removal, or `null`. */
+    removingPrincipalId: string | null;
+    /** The "Sign in with Oxy" device-flow state. */
+    signIn: SignInFlowState;
+    /** Whether Commons is installed on this device. See {@link CommonsAvailability}. */
+    commonsAvailability: CommonsAvailability;
+}
+/** Construction options for {@link AccountDialogController}. */
+export interface AccountDialogControllerOptions {
+    /** The API client. Source of graph accounts, profiles, and the sign-in methods. */
+    oxyServices: OxyServices;
+    /** The device-first session authority. Source of device rows + the switch path. */
+    sessionClient: SessionClient;
+    /**
+     * The RP's registered OAuth client id (ApplicationCredential publicKey).
+     * Required for the QR handoff (`startCommonsSignIn`); when absent, `showQr`
+     * fails with a clear configuration error instead of creating a session the
+     * server would reject.
+     */
+    clientId?: string | null;
+    /**
+     * Commit a freshly-authorized SIGN-IN session (device flow / shared identity)
+     * into the host's session set — device-first registration + durable persist +
+     * profile hydration. The consumer supplies its provider's commit path
+     * (`useOxy().handleWebSession` / the auth-sdk equivalent). Called AFTER the SDK
+     * has planted the access token. When omitted the controller falls back to
+     * `SessionClient.registerAndActivate` (registration + activation only — no
+     * provider-side durable persist/hydration).
+     *
+     * Sign-in is the only thing that commits a session here. An account SWITCH
+     * used to mint one too, on first entry into a graph account; activation mints
+     * the delegated session SERVER-side and hands back a bearer, so there is no
+     * second commit funnel to keep in step with this one.
+     */
+    commitSession?: (session: SessionLoginResponse) => Promise<void>;
+    /** Notified after a completed sign-in (bearer planted + session committed). */
+    onSignedIn?: (user: MinimalUserData) => void;
+    /**
+     * QR device-flow FALLBACK poll interval in ms (default 12000). The primary
+     * approval signal is the `/auth-session` socket's `auth_update` event (instant);
+     * this slow poll is only the safety net for when the socket can't connect.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Optional injected `socket.io-client` factory, primarily for tests. Without
+     * one, the optional transport loads only when QR sign-in starts. The flow subscribes to the
+     * `/auth-session` namespace for an INSTANT `auth_update` wake instead of relying
+     * on the slow fallback poll. If the package is unavailable, the controller
+     * silently degrades to poll-only.
+     */
+    socketFactory?: SocketIOFactory;
+    /**
+     * Optional URL opener. When provided, the controller invokes it to deep-link
+     * the Commons app for the QR handoff (web: `location.assign`; native:
+     * `Linking.openURL`). Headless core never touches `window`/`Linking` itself.
+     */
+    openUrl?: (url: string) => void;
+    /**
+     * Optional "can this app open this URL scheme?" probe, symmetric to
+     * {@link openUrl}. When provided, `showQr` uses it to detect an installed
+     * Commons (`oxycommons://`) and, if present, deep-links straight into its
+     * approve screen via {@link openUrl} — while KEEPING the QR/polling active as
+     * the fallback. Injected by the provider (native: `Linking.canOpenURL`; web:
+     * absent/false). Headless core never touches `Linking` itself; when absent
+     * `showQr` behaves exactly as before (render QR only).
+     */
+    canOpenApp?: (url: string) => Promise<boolean>;
+    /**
+     * Open a new, empty popup window SYNCHRONOUSLY (before any `await`) so the
+     * browser attributes it to the click gesture that triggered it, returning a
+     * handle to navigate once the device-flow session is known — or `null` if
+     * the popup was blocked. Injected by the provider (web only:
+     * `window.open('', ...)`; absent on native, where the hub-popup flow does
+     * not apply). Used by {@link AccountDialogController.startPasskeyHubSignIn}.
+     */
+    openPopup?: () => PopupWindowHandle | null;
+    /**
+     * Base origin of the auth.oxy.so passkey hub (defaults to
+     * `https://auth.${CENTRAL_IDP_APEX}`). Overridable for local/staging testing.
+     */
+    hubBaseUrl?: string;
+    /**
+     * Which surface the sign-in is initiated from — a FACT supplied by the
+     * consumer, because only the consumer can classify its own environment
+     * (native → `'mobile'`; web → `'mobile'` for a mobile browser, `'desktop'`
+     * otherwise). Headless core never sniffs a user agent or a platform global.
+     *
+     * Feeds {@link selectCommonsDelivery} verbatim. Defaults to `'unknown'`,
+     * which is a first-class value there: an unclassified surface never opts into
+     * the deep-link route, because a custom-scheme navigation that does not
+     * resolve is a dead end with no automatic way back.
+     */
+    platform?: CommonsDeliveryPlatform;
+}
+type SnapshotListener = (snapshot: AccountDialogSnapshot) => void;
+export declare class AccountDialogController {
+    private readonly oxyServices;
+    private readonly sessionClient;
+    private readonly clientId;
+    private readonly commitSession?;
+    private readonly onSignedIn?;
+    private readonly pollIntervalMs;
+    private readonly openUrl?;
+    private readonly canOpenApp?;
+    private readonly socketFactory?;
+    private readonly openPopup?;
+    private readonly hubBaseUrl;
+    private readonly platform;
+    private readonly listeners;
+    private view;
+    private loading;
+    private error;
+    private activatingContextId;
+    private removingContextId;
+    private removingPrincipalId;
+    private signIn;
+    private commonsAvailability;
+    /** The secret device-flow token of the active QR flow (never surfaced). */
+    private signInToken;
+    private pollTimer;
+    /**
+     * 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.
+     */
+    private authSessionSocket;
+    /**
+     * 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.
+     */
+    private pollInFlight;
+    /** The popup opened by {@link startPasskeyHubSignIn}, or `null`. */
+    private activePopup;
+    /** Watches {@link activePopup}'s `closed` state; see {@link watchPopup}. */
+    private popupWatchTimer;
+    private unsubscribeSession;
+    private unsubscribeTokens;
+    /** Last-observed SDK auth readiness (a planted bearer). Drives the fetch edge. */
+    private authed;
+    private started;
+    private refreshSeq;
+    private snapshot;
+    constructor(options: AccountDialogControllerOptions);
+    /** Returns the current immutable snapshot (stable reference between changes). */
+    getSnapshot(): AccountDialogSnapshot;
+    /** Subscribe to snapshot changes. Returns an unsubscribe function. */
+    subscribe(listener: SnapshotListener): () => void;
+    /**
+     * 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(): void;
+    /**
+     * Stop driving the dialog: unsubscribe from `SessionClient` and tear down the
+     * active sign-in flow (timers). Idempotent.
+     */
+    destroy(): void;
+    /**
+     * 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.
+     */
+    private isAuthenticated;
+    /**
+     * 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).
+     */
+    private reconcileAuth;
+    /** Set the dialog view directly. */
+    setView(view: AccountDialogView): void;
+    /** Switch to the "add account" view (the sign-in entry chooser). */
+    add(): void;
+    /** Switch to the "create account" view (passkey / Commons signup entry). */
+    startSignup(): void;
+    /**
+     * 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.
+     */
+    refresh(): Promise<void>;
+    /**
+     * 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.
+     */
+    activateContext(contextId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    signOutContext(contextId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    signOutPrincipal(principalId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    signInWithOxy(): Promise<void>;
+    /**
+     * 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`.
+     */
+    showQr(): Promise<void>;
+    /**
+     * 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.
+     */
+    startPasskeyHubSignIn(): Promise<void>;
+    /**
+     * 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.
+     */
+    private startDeviceFlowSession;
+    /**
+     * 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.
+     */
+    private resolveDeliveryRoute;
+    /**
+     * 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.
+     */
+    private isAwaitingApproval;
+    /**
+     * 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.
+     */
+    private deliverToKnownCommons;
+    /**
+     * 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.
+     */
+    private openCommonsLink;
+    /**
+     * 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.
+     */
+    private watchPopup;
+    private clearPopupWatchTimer;
+    /** Tear down the popup watch timer and close the popup, if any. Idempotent. */
+    private closeActivePopup;
+    /**
+     * 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.
+     */
+    private resolveCommonsAvailability;
+    /**
+     * 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(): void;
+    /**
+     * 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.
+     */
+    private withdrawRequest;
+    private scheduleNextPoll;
+    /**
+     * 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`.
+     */
+    private pollOnce;
+    /**
+     * 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.
+     */
+    private recordDeliveryProgress;
+    private claimAndComplete;
+    /**
+     * 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.
+     */
+    private completeSignIn;
+    /**
+     * 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).
+     */
+    private commitAuthorizedSession;
+    private failSignIn;
+    private clearPollTimer;
+    /**
+     * 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.
+     */
+    private openAuthSessionSocket;
+    /** Tear down the `/auth-session` socket, if any. Idempotent. */
+    private closeAuthSessionSocket;
+    /**
+     * 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.
+     */
+    private setSignIn;
+    /** Update a subset of the device-flow facts, re-deriving `progress`. */
+    private patchSignIn;
+    private computeSnapshot;
+    /** Recompute the snapshot and notify subscribers. */
+    private emit;
+}
+/** Factory mirroring `createSessionClient`, for ergonomic wiring by consumers. */
+export declare function createAccountDialogController(options: AccountDialogControllerOptions): AccountDialogController;
+export {};