@oxyhq/core 12.10.6 → 12.11.0

package/dist/esm/mixins/OxyServices.notifications.js

@@ -0,0 +1,60 @@
+/**
+ * Shape of an Expo push token: `ExponentPushToken[…]` (what
+ * `getExpoPushTokenAsync()` returns today) or the equivalent `ExpoPushToken[…]`
+ * spelling. Deliberately plain ASCII — `@oxyhq/core` ships to Hermes, where
+ * Unicode property escapes throw at runtime.
+ */
+const EXPO_PUSH_TOKEN_PATTERN = /^Expo(nent)?PushToken\[[^[\]\s]+\]$/;
+export function OxyServicesNotificationsMixin(Base) {
+    return class extends Base {
+        /**
+         * Register this installation's **Expo** push token for the authenticated
+         * identity (`POST /notifications/push-token`, bearer required).
+         *
+         * Idempotent server-side: re-registering the same token for the same
+         * identity refreshes the existing row rather than creating a duplicate, so
+         * callers can safely re-register on every cold boot.
+         *
+         * @throws When `expoPushToken` is not an Expo push token — a raw APNs/FCM
+         *   device token fails here rather than becoming a silently undeliverable
+         *   registration.
+         */
+        async registerPushToken(input) {
+            try {
+                if (!EXPO_PUSH_TOKEN_PATTERN.test(input.expoPushToken)) {
+                    throw new Error('registerPushToken expects an Expo push token ("ExponentPushToken[...]", from getExpoPushTokenAsync). ' +
+                        'A raw APNs/FCM device token from getDevicePushTokenAsync cannot be delivered to.');
+                }
+                await this.makeRequest('POST', '/notifications/push-token', {
+                    token: input.expoPushToken,
+                    platform: input.platform,
+                    // Omitted entirely when absent so the body stays exactly what the
+                    // endpoint has always received (the server reads presence).
+                    ...(input.deviceId ? { deviceId: input.deviceId } : {}),
+                    ...(input.clientId ? { clientId: input.clientId } : {}),
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Retire an **Expo** push token for the authenticated identity
+         * (`DELETE /notifications/push-token`, bearer required).
+         *
+         * Call it when the user turns notifications off, when the vault identity is
+         * replaced, and on sign-out — otherwise the installation keeps receiving
+         * approval requests for an identity it no longer holds.
+         *
+         * @param expoPushToken - The exact token previously registered.
+         */
+        async unregisterPushToken(expoPushToken) {
+            try {
+                await this.makeRequest('DELETE', '/notifications/push-token', { token: expoPushToken }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/index.js

@@ -24,6 +24,7 @@ import { OxyServicesUtilityMixin } from './OxyServices.utility.js';
 import { OxyServicesFeaturesMixin } from './OxyServices.features.js';
 import { OxyServicesTopicsMixin } from './OxyServices.topics.js';
 import { OxyServicesContactsMixin } from './OxyServices.contacts.js';
+import { OxyServicesNotificationsMixin } from './OxyServices.notifications.js';
 import { OxyServicesAppDataMixin } from './OxyServices.appData.js';
 import { OxyServicesCivicMixin } from './OxyServices.civic.js';
 import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
@@ -71,6 +72,10 @@ const MIXIN_PIPELINE = [
     OxyServicesFeaturesMixin,
     OxyServicesTopicsMixin,
     OxyServicesContactsMixin,
+    // Push-token registration: the one SDK-owned register/unregister pair every
+    // Oxy app uses, and what lets a "Sign in with Oxy" request be delivered to a
+    // known Commons installation instead of falling back to a QR.
+    OxyServicesNotificationsMixin,
     OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServicesCivicMixin,

package/dist/esm/session/SessionClient.js

@@ -30,6 +30,15 @@ export class SessionClient {
     getState() {
         return this.state;
     }
+    /**
+     * The account this client's bearer is pinned to, or `null` when it follows the
+     * device's active account (the default). Resolvers are expected to be a plain
+     * synchronous read of already-resolved state (see
+     * {@link SessionClientOptions.getPinnedAccountId}).
+     */
+    pinnedAccountId() {
+        return this.options.getPinnedAccountId?.() ?? null;
+    }
     subscribe(listener) {
         this.listeners.add(listener);
         return () => {
@@ -118,15 +127,26 @@ export class SessionClient {
         }
         const previousState = this.state;
         this.state = next;
+        const pinnedAccountId = this.pinnedAccountId();
         // Plant the sync-supplied active token (it is for `next.activeAccountId`)
         // now — before the notify below — so the bearer matches the new active
         // account when subscribers observe it. Guarded on difference to avoid a
         // redundant token-change notification on an unchanged token (bootstrap
-        // restate).
-        if (activeToken && next.activeAccountId !== null && activeToken !== this.host.getAccessToken()) {
+        // restate). An identity-bound client only accepts it when the active account
+        // IS its pinned account — otherwise the token belongs to somebody else's
+        // switch and must never displace the pinned bearer.
+        if (activeToken &&
+            next.activeAccountId !== null &&
+            (pinnedAccountId === null || next.activeAccountId === pinnedAccountId) &&
+            activeToken !== this.host.getAccessToken()) {
             this.host.setTokens(activeToken);
         }
-        const transport = this.options.transport;
+        // The transport's entire job is converging the bearer on `activeAccountId`,
+        // which is precisely what an identity-bound client must not do: its token is
+        // minted for the pinned account by the cold boot / re-mint lane. Bypass it
+        // while pinned (also removing the mint-before-notify gate, which exists only
+        // to keep the bearer and the ACTIVE account in step).
+        const transport = pinnedAccountId === null ? this.options.transport : null;
         const activeAccountId = next.activeAccountId;
         // Mint before notifying when the bearer does not already belong to the new
         // active account: no bearer at all, an opaque bearer, OR a bearer for a
@@ -198,12 +218,15 @@ export class SessionClient {
         // socket push): `applyState` no-ops without planting, but the token still
         // needs planting. Guard on the sync's active account STILL being the current
         // active account so a stale response cannot adopt a token for an account a
-        // newer state already switched away from.
+        // newer state already switched away from — and, when pinned, on that account
+        // being the PINNED one (same rule as the applied path in `applyState`).
+        const pinnedAccountId = this.pinnedAccountId();
         if (!applied &&
             sync.activeToken &&
             this.state &&
             sync.state.activeAccountId !== null &&
             sync.state.activeAccountId === this.state.activeAccountId &&
+            (pinnedAccountId === null || sync.state.activeAccountId === pinnedAccountId) &&
             sync.activeToken.accessToken !== this.host.getAccessToken()) {
             this.host.setTokens(sync.activeToken.accessToken);
         }
@@ -237,12 +260,19 @@ export class SessionClient {
      * sign-in. This adds, then switches to the target so the UI lands on the
      * account the user just authenticated.
      *
+     * An identity-bound (pinned) client only ADDS: its own session is minted for
+     * the pinned account explicitly, so switching the device would gratuitously
+     * re-elect the active account under every OTHER app on this device — a
+     * mutation a pinned client must never make.
+     *
      * @param accountId - The signed-in account id (e.g. `session.user.id`). When
      *   omitted, falls back to the host's current-account ref. If neither
      *   resolves, the add still applies and no switch is performed.
      */
     async registerAndActivate(accountId) {
         await this.addCurrentAccount();
+        if (this.pinnedAccountId() !== null)
+            return;
         const target = accountId ?? this.host.getCurrentAccountId();
         if (target && this.state?.activeAccountId !== target) {
             await this.switchAccount(target);
@@ -346,6 +376,12 @@ export class SessionClient {
             const applied = this.applyState(payload, 'push');
             if (!applied)
                 return;
+            // An identity-bound client tracks the pushed state but NEVER chases the
+            // device's active account: re-fetching here would only pull an
+            // `activeToken` for somebody else's switch, which the plant guards would
+            // then discard. Skip the round-trip entirely.
+            if (this.pinnedAccountId() !== null)
+                return;
             // A push changed the active account on another device/tab — re-fetch state
             // to plant the access token for the newly-active account. When this tab is
             // still signed out, applyState mints via ensureActiveToken first; bootstrap

package/dist/esm/session/accountDialogController.js

@@ -21,6 +21,17 @@
  *   - 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.
@@ -47,6 +58,37 @@ import { logger } from '../logger/index.js';
 import { extractErrorStatus } from '../utils/errorUtils.js';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
 import { projectSwitchableAccounts, switchableAccountIds, } from './accountProjection.js';
+import { pushTargetsFromDelivery, selectCommonsDelivery, } from '../utils/commonsDelivery.js';
+/**
+ * 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
@@ -62,12 +104,30 @@ const AUTH_SESSION_NAMESPACE = '/auth-session';
  * itself is the flow's `qrPayload`.
  */
 const COMMONS_APP_SCHEME = 'oxycommons://';
-const IDLE_SIGN_IN = {
+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);
@@ -124,6 +184,7 @@ export class AccountDialogController {
         this.socketFactory = options.socketFactory;
         this.openPopup = options.openPopup;
         this.hubBaseUrl = options.hubBaseUrl ?? `https://auth.${CENTRAL_IDP_APEX}`;
+        this.platform = options.platform ?? 'unknown';
         this.snapshot = this.computeSnapshot();
     }
     // =========================================================================
@@ -253,6 +314,13 @@ export class AccountDialogController {
         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). */
@@ -436,7 +504,7 @@ export class AccountDialogController {
      */
     async signInWithOxy() {
         this.setView('qr');
-        this.setSignIn({ ...IDLE_SIGN_IN, phase: 'starting' });
+        this.setSignIn({ ...IDLE_SIGN_IN_FACTS, phase: 'starting' });
         try {
             const session = await this.oxyServices.signInWithSharedIdentity();
             if (session) {
@@ -460,7 +528,7 @@ export class AccountDialogController {
     async showQr() {
         this.cancelSignIn();
         this.setView('qr');
-        await this.startDeviceFlowSession();
+        await this.startDeviceFlowSession({ deliver: true });
     }
     /**
      * Web-only: "Sign in with a passkey" on a non-Oxy origin cannot run the
@@ -486,10 +554,16 @@ export class AccountDialogController {
         this.setView('qr');
         const popup = this.openPopup?.() ?? null;
         if (!popup) {
-            await this.startDeviceFlowSession();
+            await this.startDeviceFlowSession({ deliver: true });
             return;
         }
-        const handle = await this.startDeviceFlowSession();
+        // 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;
@@ -511,42 +585,148 @@ export class AccountDialogController {
      * 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() {
+    async startDeviceFlowSession(opts) {
         if (!this.clientId) {
-            this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: 'This app is not configured for sign-in (missing 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, phase: 'starting' });
+        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,
-                error: null,
+                // 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);
-            // Same-device convenience: if Commons is confirmed installed (native
-            // only — stays `'unknown'` on web, where this never opens anything),
-            // deep-link straight into its approve screen with the same
-            // `oxycommons://approve?...` payload the QR encodes. The QR + polling
-            // stay live as the fallback, so a user who dismisses the app-open still
-            // completes the sign-in by scanning.
-            void this.deepLinkIntoCommonsIfAvailable(handle.qrPayload);
+            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, phase: 'error', error: errorMessage(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 = 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 pushTargetsFromDelivery(result);
+        }
+        catch (error) {
+            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.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
@@ -561,7 +741,12 @@ export class AccountDialogController {
                 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);
     }
@@ -614,32 +799,43 @@ export class AccountDialogController {
         this.emit();
     }
     /**
-     * When Commons is confirmed installed, deep-link straight into its approve
-     * screen via the injected `openUrl` with the same `oxycommons://approve?...`
-     * payload the QR encodes. Best-effort and non-blocking — the QR/polling
-     * fallback stays live regardless of the outcome here.
+     * 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.
      */
-    async deepLinkIntoCommonsIfAvailable(qrPayload) {
-        if (!this.openUrl)
-            return;
-        if (this.commonsAvailability === 'unknown' || this.commonsAvailability === 'checking') {
-            // The eager `start()` probe hasn't resolved yet (or was never run, e.g.
-            // `showQr` called without a prior `start()`) — resolve it now rather
-            // than skipping the deep link.
-            await this.resolveCommonsAvailability();
-        }
-        if (this.commonsAvailability === 'available') {
-            this.openUrl(qrPayload);
-        }
-    }
-    /** Tear down the active sign-in device flow (timers + socket + popup + token) and reset to idle. */
     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);
+            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.debug('[AccountDialogController] request withdrawal failed', { component: 'AccountDialogController' }, error);
         }
     }
     // =========================================================================
@@ -673,6 +869,18 @@ export class AccountDialogController {
                 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);
@@ -699,8 +907,23 @@ export class AccountDialogController {
             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.setSignIn({ ...this.signIn, phase: 'authorized' });
+        this.patchSignIn({ phase: 'authorized' });
         let claimed;
         try {
             claimed = await this.oxyServices.claimSessionByToken(sessionToken);
@@ -746,7 +969,9 @@ export class AccountDialogController {
         this.clearPollTimer();
         this.closeAuthSessionSocket();
         this.closeActivePopup();
-        this.signIn = IDLE_SIGN_IN;
+        // 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);
@@ -779,7 +1004,7 @@ export class AccountDialogController {
         this.closeAuthSessionSocket();
         this.closeActivePopup();
         this.signInToken = null;
-        this.setSignIn({ ...IDLE_SIGN_IN, phase: 'error', error: message });
+        this.setSignIn({ ...IDLE_SIGN_IN_FACTS, phase: 'error', error: message });
     }
     clearPollTimer() {
         if (this.pollTimer !== null) {
@@ -861,10 +1086,32 @@ export class AccountDialogController {
     // =========================================================================
     // Snapshot plumbing
     // =========================================================================
-    setSignIn(next) {
-        this.signIn = next;
+    /**
+     * 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 state = this.sessionClient.getState();
         return {