@oxyhq/core 12.10.6 → 12.11.1

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 {