@oxyhq/core 12.1.1 → 12.2.1

package/dist/types/index.d.ts

@@ -99,7 +99,7 @@ export { deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountId
 export { projectSwitchableAccounts, switchableAccountIds, } from './session/accountProjection';
 export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
-export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, SignInFlowPhase, SignInFlowState, } from './session/accountDialogController';
+export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFlowPhase, SignInFlowState, } from './session/accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
 export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';

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

@@ -24,6 +24,12 @@
  *   - `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
@@ -51,6 +57,21 @@ export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add' | 'signup';
 export type CommonsAvailability = 'unknown' | 'checking' | 'available' | 'unavailable';
 /** Lifecycle phase of the "Sign in with Oxy" device flow. */
 export type SignInFlowPhase = 'idle' | 'starting' | 'waiting' | 'authorized' | 'error';
+/**
+ * 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. */
 export interface SignInFlowState {
     phase: SignInFlowPhase;
@@ -166,6 +187,20 @@ export interface AccountDialogControllerOptions {
      * `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;
 }
 type SnapshotListener = (snapshot: AccountDialogSnapshot) => void;
 export declare class AccountDialogController {
@@ -180,6 +215,8 @@ export declare class AccountDialogController {
     private readonly openUrl?;
     private readonly canOpenApp?;
     private readonly socketFactory?;
+    private readonly openPopup?;
+    private readonly hubBaseUrl;
     private readonly listeners;
     private view;
     private graph;
@@ -204,6 +241,10 @@ export declare class AccountDialogController {
      * 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. */
@@ -303,6 +344,45 @@ export declare class AccountDialogController {
      * 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`).
+     */
+    private startDeviceFlowSession;
+    /**
+     * 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,
@@ -323,7 +403,7 @@ export declare class AccountDialogController {
      * fallback stays live regardless of the outcome here.
      */
     private deepLinkIntoCommonsIfAvailable;
-    /** Tear down the active sign-in device flow (timers + socket + token) and reset to idle. */
+    /** Tear down the active sign-in device flow (timers + socket + popup + token) and reset to idle. */
     cancelSignIn(): void;
     private scheduleNextPoll;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.1.1",
+  "version": "12.2.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -117,7 +117,7 @@
     "invariant": "^2.2.4",
     "jwt-decode": "^4.0.0",
     "socket.io-client": "^4.8.1",
-    "tldts": "^7.4.5",
+    "tldts": "^7.4.8",
     "zod": "^3.25.64"
   },
   "peerDependencies": {
@@ -147,10 +147,10 @@
     "@types/elliptic": "^6.4.18",
     "@types/express": "^4.17.21",
     "@types/invariant": "^2.2.34",
-    "@types/node": "^20.19.9",
+    "@types/node": "^20.19.43",
     "expo-crypto": "~56.0.3",
     "expo-secure-store": "~56.0.4",
-    "express": "^4.21.2",
+    "express": "^4.22.2",
     "express-rate-limit": "^7.5.0",
     "release-it": "^19.0.6",
     "typescript": "^5.9.2"

package/src/i18n/locales/ar-SA.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "أنشئ حسابك",
+    "subtitle": "هوية واحدة لكل النظام البيئي.",
     "commonsHeadline": "أنشئ هويتك في Commons",
     "commonsExplainer": "‏Commons هي هوية Oxy الخاصة بك بحفظ ذاتي كامل — تطبيق واحد يعمل في كل مكان.",
     "createInCommons": "أنشئ هويتك في Commons",
@@ -61,7 +63,8 @@
     "usernameAvailable": "متاح",
     "usernameTaken": "اسم المستخدم هذا مستخدم بالفعل",
     "backToSignInLink": "لديك حساب بالفعل؟ سجّل الدخول",
-    "notAvailableHere": "‏إنشاء الحساب غير متاح في هذا التطبيق بعد — أنشئ هويتك باستخدام Commons، أو تفضّل بزيارة oxy.so للتسجيل باستخدام مفتاح مرور.",
+    "hubExplainer": "أنشئ هوية Oxy الخاصة بك في نافذة آمنة، ثم عد إلى هنا مباشرة.",
+    "continueInWindow": "المتابعة في نافذة جديدة",
     "welcome": {
       "title": "مرحبًا بك في Oxy!",
       "subtitle": "أنشئ حسابك في خطوات قليلة",

package/src/i18n/locales/ca-ES.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Crea el teu compte",
+    "subtitle": "Una identitat per a tot l'ecosistema.",
     "commonsHeadline": "Crea la teva identitat a Commons",
     "commonsExplainer": "Commons és la teva identitat d'Oxy amb autocustòdia completa: una app que funciona a tot arreu.",
     "createInCommons": "Crea la teva identitat a Commons",
@@ -61,7 +63,8 @@
     "usernameAvailable": "Disponible",
     "usernameTaken": "Aquest nom d'usuari ja està en ús",
     "backToSignInLink": "Ja tens compte? Inicia sessió",
-    "notAvailableHere": "La creació de comptes encara no està disponible en aquesta app: crea la teva identitat amb Commons o visita oxy.so per registrar-te amb una clau d'accés.",
+    "hubExplainer": "Crea la teva Oxy ID en una finestra segura i torna de seguida.",
+    "continueInWindow": "Continua en una finestra nova",
     "welcome": {
       "title": "Benvingut a Oxy!",
       "subtitle": "Crea el teu compte en pocs passos",

package/src/i18n/locales/de-DE.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Erstellen Sie Ihr Konto",
+    "subtitle": "Eine Identität für das gesamte Ökosystem.",
     "commonsHeadline": "Erstellen Sie Ihre Identität in Commons",
     "commonsExplainer": "Commons ist Ihre vollständig selbstverwaltete Oxy-Identität – eine App, überall einsetzbar.",
     "createInCommons": "Erstellen Sie Ihre Identität in Commons",
@@ -61,7 +63,8 @@
     "usernameAvailable": "Verfügbar",
     "usernameTaken": "Dieser Benutzername ist bereits vergeben",
     "backToSignInLink": "Sie haben bereits ein Konto? Anmelden",
-    "notAvailableHere": "Die Kontoerstellung ist in dieser App noch nicht verfügbar – erstellen Sie Ihre Identität mit Commons oder besuchen Sie oxy.so, um sich mit einem Passkey zu registrieren.",
+    "hubExplainer": "Erstellen Sie Ihre Oxy-ID in einem sicheren Fenster und kehren Sie dann direkt zurück.",
+    "continueInWindow": "In einem neuen Fenster fortfahren",
     "welcome": {
       "title": "Willkommen bei Oxy!",
       "subtitle": "Erstellen Sie Ihr Konto in nur wenigen Schritten",

package/src/i18n/locales/en-US.json

@@ -57,6 +57,8 @@
     }
   },
   "signup": {
+    "title": "Create your account",
+    "subtitle": "One identity for the whole ecosystem.",
     "commonsHeadline": "Create your identity in Commons",
     "commonsExplainer": "Commons is your full self-custody Oxy identity — one app, works everywhere.",
     "createInCommons": "Create your identity in Commons",
@@ -68,7 +70,8 @@
     "usernameAvailable": "Available",
     "usernameTaken": "This username is taken",
     "backToSignInLink": "Already have an account? Sign in",
-    "notAvailableHere": "Account creation isn't available in this app yet — create your identity with Commons, or visit oxy.so to sign up with a passkey.",
+    "hubExplainer": "Create your Oxy ID in a secure window, then come right back.",
+    "continueInWindow": "Continue in a new window",
     "welcome": {
       "title": "Welcome to Oxy!",
       "subtitle": "Let's create your account in just a few steps",

package/src/i18n/locales/es-ES.json

@@ -57,6 +57,8 @@
     }
   },
   "signup": {
+    "title": "Crea tu cuenta",
+    "subtitle": "Una identidad para todo el ecosistema.",
     "commonsHeadline": "Crea tu identidad en Commons",
     "commonsExplainer": "Commons es tu identidad de Oxy con autocustodia completa: una app que funciona en todas partes.",
     "createInCommons": "Crea tu identidad en Commons",
@@ -68,7 +70,8 @@
     "usernameAvailable": "Disponible",
     "usernameTaken": "Este usuario ya está en uso",
     "backToSignInLink": "¿Ya tienes cuenta? Inicia sesión",
-    "notAvailableHere": "La creación de cuentas aún no está disponible en esta app: crea tu identidad con Commons o visita oxy.so para registrarte con una clave de acceso.",
+    "hubExplainer": "Crea tu Oxy ID en una ventana segura y vuelve enseguida.",
+    "continueInWindow": "Continuar en una ventana nueva",
     "welcome": {
       "title": "¡Te damos la bienvenida a Oxy!",
       "subtitle": "Crea tu cuenta en pocos pasos",

package/src/i18n/locales/fr-FR.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Créez votre compte",
+    "subtitle": "Une seule identité pour tout l'écosystème.",
     "commonsHeadline": "Créez votre identité dans Commons",
     "commonsExplainer": "Commons est votre identité Oxy en autoconservation complète : une seule app, partout.",
     "createInCommons": "Créez votre identité dans Commons",
@@ -61,7 +63,8 @@
     "usernameAvailable": "Disponible",
     "usernameTaken": "Ce nom d'utilisateur est déjà pris",
     "backToSignInLink": "Vous avez déjà un compte ? Connectez-vous",
-    "notAvailableHere": "La création de compte n'est pas encore disponible dans cette app — créez votre identité avec Commons, ou rendez-vous sur oxy.so pour vous inscrire avec une clé d'accès.",
+    "hubExplainer": "Créez votre Oxy ID dans une fenêtre sécurisée, puis revenez directement.",
+    "continueInWindow": "Continuer dans une nouvelle fenêtre",
     "welcome": {
       "title": "Bienvenue sur Oxy !",
       "subtitle": "Créez votre compte en quelques étapes",

package/src/i18n/locales/it-IT.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Crea il tuo account",
+    "subtitle": "Un'unica identità per tutto l'ecosistema.",
     "commonsHeadline": "Crea la tua identità in Commons",
     "commonsExplainer": "Commons è la tua identità Oxy in piena autocustodia: un'unica app, ovunque.",
     "createInCommons": "Crea la tua identità in Commons",
@@ -61,7 +63,8 @@
     "usernameAvailable": "Disponibile",
     "usernameTaken": "Questo nome utente è già in uso",
     "backToSignInLink": "Hai già un account? Accedi",
-    "notAvailableHere": "La creazione dell'account non è ancora disponibile in questa app: crea la tua identità con Commons oppure visita oxy.so per registrarti con una passkey.",
+    "hubExplainer": "Crea il tuo Oxy ID in una finestra sicura, poi torna subito qui.",
+    "continueInWindow": "Continua in una nuova finestra",
     "welcome": {
       "title": "Benvenuto su Oxy!",
       "subtitle": "Crea il tuo account in pochi passaggi",

package/src/i18n/locales/ja-JP.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "アカウントを作成",
+    "subtitle": "エコシステム全体で使える1つのアイデンティティ。",
     "commonsHeadline": "Commonsであなたのアイデンティティを作成",
     "commonsExplainer": "Commonsは完全に自己管理できるあなたのOxy IDです。1つのアプリでどこでも使えます。",
     "createInCommons": "Commonsであなたのアイデンティティを作成",
@@ -61,7 +63,8 @@
     "usernameAvailable": "利用可能",
     "usernameTaken": "このユーザー名は既に使用されています",
     "backToSignInLink": "すでにアカウントをお持ちですか？サインイン",
-    "notAvailableHere": "このアプリではまだアカウントを作成できません。Commonsでアイデンティティを作成するか、oxy.soにアクセスしてパスキーで登録してください。",
+    "hubExplainer": "安全なウィンドウでOxy IDを作成し、すぐに戻ってきてください。",
+    "continueInWindow": "新しいウィンドウで続ける",
     "welcome": {
       "title": "Oxyへようこそ！",
       "subtitle": "数ステップでアカウントを作成",

package/src/i18n/locales/ko-KR.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "계정 만들기",
+    "subtitle": "생태계 전체를 위한 하나의 아이덴티티.",
     "commonsHeadline": "Commons에서 나의 아이덴티티 만들기",
     "commonsExplainer": "Commons는 완전한 자기 보관 방식의 Oxy 아이덴티티입니다. 하나의 앱으로 어디서나 사용하세요.",
     "createInCommons": "Commons에서 나의 아이덴티티 만들기",
@@ -61,7 +63,8 @@
     "usernameAvailable": "사용 가능",
     "usernameTaken": "이미 사용 중인 사용자 이름입니다",
     "backToSignInLink": "이미 계정이 있으신가요? 로그인",
-    "notAvailableHere": "이 앱에서는 아직 계정을 만들 수 없습니다. Commons로 아이덴티티를 만들거나 oxy.so에서 패스키로 가입하세요.",
+    "hubExplainer": "안전한 창에서 Oxy ID를 만든 후 바로 돌아오세요.",
+    "continueInWindow": "새 창에서 계속하기",
     "welcome": {
       "title": "Oxy에 오신 것을 환영합니다!",
       "subtitle": "몇 단계만으로 계정을 만드세요",

package/src/i18n/locales/pt-PT.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "Crie a sua conta",
+    "subtitle": "Uma identidade para todo o ecossistema.",
     "commonsHeadline": "Crie a sua identidade no Commons",
     "commonsExplainer": "O Commons é a sua identidade Oxy com autocustódia total: uma app que funciona em todo o lado.",
     "createInCommons": "Crie a sua identidade no Commons",
@@ -61,7 +63,8 @@
     "usernameAvailable": "Disponível",
     "usernameTaken": "Este nome de utilizador já está em uso",
     "backToSignInLink": "Já tem uma conta? Inicie sessão",
-    "notAvailableHere": "A criação de conta ainda não está disponível nesta app: crie a sua identidade com o Commons ou visite oxy.so para se registar com uma chave de acesso.",
+    "hubExplainer": "Crie a sua Oxy ID numa janela segura e volte de seguida.",
+    "continueInWindow": "Continuar numa nova janela",
     "welcome": {
       "title": "Bem-vindo ao Oxy!",
       "subtitle": "Crie a sua conta em poucos passos",

package/src/i18n/locales/zh-CN.json

@@ -50,6 +50,8 @@
     }
   },
   "signup": {
+    "title": "创建您的账户",
+    "subtitle": "一个身份，畅行整个生态系统。",
     "commonsHeadline": "在 Commons 中创建您的身份",
     "commonsExplainer": "Commons 是您完全自主保管的 Oxy 身份——一个应用，随处可用。",
     "createInCommons": "在 Commons 中创建您的身份",
@@ -61,7 +63,8 @@
     "usernameAvailable": "可用",
     "usernameTaken": "该用户名已被占用",
     "backToSignInLink": "已有账户？登录",
-    "notAvailableHere": "此应用暂不支持创建账户——请使用 Commons 创建您的身份，或访问 oxy.so 使用通行密钥注册。",
+    "hubExplainer": "在安全窗口中创建您的 Oxy ID，然后立即返回。",
+    "continueInWindow": "在新窗口中继续",
     "welcome": {
       "title": "欢迎使用Oxy！",
       "subtitle": "只需几步即可创建您的账户",

package/src/index.ts

@@ -624,6 +624,7 @@ export type {
     AccountDialogSnapshot,
     AccountDialogView,
     CommonsAvailability,
+    PopupWindowHandle,
     SignInFlowPhase,
     SignInFlowState,
 } from './session/accountDialogController';

package/src/session/__tests__/accountDialogController.test.ts

@@ -126,7 +126,13 @@ interface Harness {
   onSignedIn: jest.Mock;
 }
 
-function makeHarness(over: Partial<{ clientId: string | null }> = {}): Harness {
+function makeHarness(
+  over: Partial<{
+    clientId: string | null;
+    openPopup: () => import('../accountDialogController').PopupWindowHandle | null;
+    hubBaseUrl: string;
+  }> = {},
+): Harness {
   const oxy = makeOxy();
   const sc = new TestSessionClient(host());
   const commitSession = jest.fn().mockResolvedValue(undefined);
@@ -138,6 +144,8 @@ function makeHarness(over: Partial<{ clientId: string | null }> = {}): Harness {
     commitSession,
     onSignedIn,
     pollIntervalMs: 1000,
+    openPopup: over.openPopup,
+    hubBaseUrl: over.hubBaseUrl,
   });
   return { controller, oxy, sc, commitSession, onSignedIn };
 }
@@ -641,6 +649,130 @@ describe('AccountDialogController — sign in with Oxy', () => {
   });
 });
 
+/** A controllable fake `PopupWindowHandle` for `startPasskeyHubSignIn` tests. */
+function fakePopup(): import('../accountDialogController').PopupWindowHandle & { setClosed: () => void } {
+  let closed = false;
+  return {
+    get closed() {
+      return closed;
+    },
+    close: jest.fn(() => {
+      closed = true;
+    }),
+    location: { href: '' },
+    setClosed: () => {
+      closed = true;
+    },
+  };
+}
+
+describe('AccountDialogController — startPasskeyHubSignIn (b2 passkey hub popup)', () => {
+  it('opens the popup synchronously, then navigates it to the hub URL with the authorizeCode once the session exists', async () => {
+    const popup = fakePopup();
+    const openPopup = jest.fn(() => popup);
+    const { controller, oxy } = makeHarness({ openPopup, hubBaseUrl: 'https://auth.oxy.so' });
+    oxy.startCommonsSignIn.mockResolvedValue({
+      sessionToken: 'secret-tok',
+      authorizeCode: 'AUTH-CODE',
+      qrPayload: 'oxycommons://approve?v=1&code=AUTH-CODE',
+      expiresAt: Date.now() + 300_000,
+      status: 'pending',
+    });
+
+    await controller.startPasskeyHubSignIn();
+
+    expect(openPopup).toHaveBeenCalledTimes(1);
+    expect(popup.location.href).toBe('https://auth.oxy.so/hub-passkey?code=AUTH-CODE');
+    // Same underlying device-flow session showQr would create — the QR view
+    // still renders as a fallback/alternative alongside the popup.
+    const snap = controller.getSnapshot();
+    expect(snap.view).toBe('qr');
+    expect(snap.signIn.phase).toBe('waiting');
+    expect(snap.signIn.authorizeCode).toBe('AUTH-CODE');
+    controller.cancelSignIn();
+  });
+
+  it('falls back to the plain QR flow (no navigation) when the popup is blocked', async () => {
+    const openPopup = jest.fn(() => null);
+    const { controller, oxy } = makeHarness({ openPopup });
+    oxy.startCommonsSignIn.mockResolvedValue({
+      sessionToken: 'secret-tok',
+      authorizeCode: 'AUTH-CODE',
+      qrPayload: 'oxycommons://approve?v=1&code=AUTH-CODE',
+      expiresAt: Date.now() + 300_000,
+      status: 'pending',
+    });
+
+    await controller.startPasskeyHubSignIn();
+
+    expect(oxy.startCommonsSignIn).toHaveBeenCalledWith({ clientId: 'oxy_dk_test' });
+    const snap = controller.getSnapshot();
+    expect(snap.view).toBe('qr');
+    expect(snap.signIn.phase).toBe('waiting');
+    expect(snap.signIn.qrPayload).toBe('oxycommons://approve?v=1&code=AUTH-CODE');
+    controller.cancelSignIn();
+  });
+
+  it('closes the popup without navigating it when device-flow session creation fails', async () => {
+    const popup = fakePopup();
+    const openPopup = jest.fn(() => popup);
+    const { controller, oxy } = makeHarness({ openPopup });
+    oxy.startCommonsSignIn.mockRejectedValue(new Error('network down'));
+
+    await controller.startPasskeyHubSignIn();
+
+    expect(popup.close).toHaveBeenCalledTimes(1);
+    expect(popup.location.href).toBe('');
+    expect(controller.getSnapshot().signIn.phase).toBe('error');
+  });
+
+  it('surfaces "cancelled" and closes the popup watcher when the user closes the popup before authorizing', async () => {
+    jest.useFakeTimers();
+    try {
+      const popup = fakePopup();
+      const openPopup = jest.fn(() => popup);
+      const { controller, oxy } = makeHarness({ openPopup });
+      oxy.startCommonsSignIn.mockResolvedValue({
+        sessionToken: 'secret-tok',
+        authorizeCode: 'AUTH-CODE',
+        qrPayload: 'oxycommons://approve?v=1&code=AUTH-CODE',
+        expiresAt: Date.now() + 300_000,
+        status: 'pending',
+      });
+      oxy.pollCommonsSignIn.mockResolvedValue({ authorized: false, status: 'pending' });
+
+      await controller.startPasskeyHubSignIn();
+      expect(controller.getSnapshot().signIn.phase).toBe('waiting');
+
+      popup.setClosed();
+      await jest.advanceTimersByTimeAsync(1000); // the 1s popup-close watchdog tick
+
+      const snap = controller.getSnapshot();
+      expect(snap.signIn.phase).toBe('error');
+      expect(snap.signIn.error).toMatch(/cancelled/i);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('closes the popup again (never navigates it) when clientId is missing', async () => {
+    const popup = fakePopup();
+    const openPopup = jest.fn(() => popup);
+    const { controller, oxy } = makeHarness({ clientId: null, openPopup });
+
+    await controller.startPasskeyHubSignIn();
+
+    // openPopup is invoked unconditionally (before the clientId check, since it
+    // must run synchronously) — but the popup must be closed again rather than
+    // navigated, since the flow can't proceed without a clientId.
+    expect(oxy.startCommonsSignIn).not.toHaveBeenCalled();
+    expect(popup.close).toHaveBeenCalledTimes(1);
+    expect(popup.location.href).toBe('');
+    expect(controller.getSnapshot().signIn.phase).toBe('error');
+    expect(controller.getSnapshot().signIn.error).toMatch(/clientId/);
+  });
+});
+
 describe('AccountDialogController — Commons availability (canOpenApp)', () => {
   const START_HANDLE = {
     sessionToken: 'secret-tok',