@oxyhq/core 12.10.5 → 12.11.0

package/dist/esm/i18n/locales/locales/ja-JP.json

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "Commonsがありませんか？アプリを入手してOxy IDでサインインしましょう。",
     "showQrAnyway": "別のデバイスにCommonsがあります",
     "switchWhileSignedInAs": "アカウントを切り替え（{{name}} としてログイン中）",
-    "manageOnDevice": "このデバイスのアカウントを管理"
+    "manageOnDevice": "このデバイスのアカウントを管理",
+    "continueWithOxy": "Oxyで続ける",
+    "havingTrouble": "うまくいきませんか？",
+    "progress": {
+      "preparing": "リクエストを準備しています",
+      "awaitingApproval": "承認を待っています",
+      "scanWithCommons": "スマートフォンのCommonsでスキャンしてください",
+      "continueInCommons": "Commonsで続けてください",
+      "checkCommons": "スマートフォンのCommonsを確認してください",
+      "openedInCommons": "Commonsで開きました",
+      "confirming": "本人確認をしています",
+      "confirmed": "本人確認が完了しました"
+    }
   },
   "common": {
     "actions": {

package/dist/esm/i18n/locales/locales/ko-KR.json

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "Commons가 없으신가요? 앱을 다운로드하여 Oxy ID로 로그인하세요.",
     "showQrAnyway": "다른 기기에 Commons가 있습니다",
     "switchWhileSignedInAs": "계정 전환, {{name}}(으)로 로그인됨",
-    "manageOnDevice": "이 기기의 계정 관리"
+    "manageOnDevice": "이 기기의 계정 관리",
+    "continueWithOxy": "Oxy로 계속하기",
+    "havingTrouble": "문제가 있으신가요?",
+    "progress": {
+      "preparing": "요청 준비 중",
+      "awaitingApproval": "승인 대기 중",
+      "scanWithCommons": "휴대폰의 Commons로 스캔하세요",
+      "continueInCommons": "Commons에서 계속하세요",
+      "checkCommons": "휴대폰에서 Commons를 확인하세요",
+      "openedInCommons": "Commons에서 열림",
+      "confirming": "신원 확인 중",
+      "confirmed": "신원 확인 완료"
+    }
   },
   "common": {
     "actions": {

package/dist/esm/i18n/locales/locales/pt-PT.json

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "Não tem o Commons? Obtenha a app para iniciar sessão com o seu Oxy ID.",
     "showQrAnyway": "Tenho o Commons noutro dispositivo",
     "switchWhileSignedInAs": "Mudar de conta, com sessão iniciada como {{name}}",
-    "manageOnDevice": "Gerir contas neste dispositivo"
+    "manageOnDevice": "Gerir contas neste dispositivo",
+    "continueWithOxy": "Continuar com Oxy",
+    "havingTrouble": "Algum problema?",
+    "progress": {
+      "preparing": "A preparar o pedido",
+      "awaitingApproval": "A aguardar aprovação",
+      "scanWithCommons": "Digitalize com o Commons no seu telemóvel",
+      "continueInCommons": "Continue no Commons",
+      "checkCommons": "Verifique o Commons no seu telemóvel",
+      "openedInCommons": "Aberto no Commons",
+      "confirming": "A confirmar a identidade",
+      "confirmed": "Identidade confirmada"
+    }
   },
   "common": {
     "actions": {

package/dist/esm/i18n/locales/locales/zh-CN.json

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "没有 Commons？获取应用以使用您的 Oxy ID 登录。",
     "showQrAnyway": "我在另一台设备上有 Commons",
     "switchWhileSignedInAs": "切换账号，当前登录为 {{name}}",
-    "manageOnDevice": "管理此设备上的账号"
+    "manageOnDevice": "管理此设备上的账号",
+    "continueWithOxy": "使用 Oxy 继续",
+    "havingTrouble": "遇到问题？",
+    "progress": {
+      "preparing": "正在准备请求",
+      "awaitingApproval": "正在等待批准",
+      "scanWithCommons": "请用手机上的 Commons 扫描",
+      "continueInCommons": "请在 Commons 中继续",
+      "checkCommons": "请查看手机上的 Commons",
+      "openedInCommons": "已在 Commons 中打开",
+      "confirming": "正在确认身份",
+      "confirmed": "身份已确认"
+    }
   },
   "common": {
     "actions": {

package/dist/esm/i18n/locales/pt-PT.json

@@ -124,7 +124,19 @@
         "commonsNotInstalled": "Não tem o Commons? Obtenha a app para iniciar sessão com o seu Oxy ID.",
         "showQrAnyway": "Tenho o Commons noutro dispositivo",
         "switchWhileSignedInAs": "Mudar de conta, com sessão iniciada como {{name}}",
-        "manageOnDevice": "Gerir contas neste dispositivo"
+        "manageOnDevice": "Gerir contas neste dispositivo",
+        "continueWithOxy": "Continuar com Oxy",
+        "havingTrouble": "Algum problema?",
+        "progress": {
+            "preparing": "A preparar o pedido",
+            "awaitingApproval": "A aguardar aprovação",
+            "scanWithCommons": "Digitalize com o Commons no seu telemóvel",
+            "continueInCommons": "Continue no Commons",
+            "checkCommons": "Verifique o Commons no seu telemóvel",
+            "openedInCommons": "Aberto no Commons",
+            "confirming": "A confirmar a identidade",
+            "confirmed": "Identidade confirmada"
+        }
     },
     "common": {
         "actions": {

package/dist/esm/i18n/locales/zh-CN.json

@@ -124,7 +124,19 @@
         "commonsNotInstalled": "没有 Commons？获取应用以使用您的 Oxy ID 登录。",
         "showQrAnyway": "我在另一台设备上有 Commons",
         "switchWhileSignedInAs": "切换账号，当前登录为 {{name}}",
-        "manageOnDevice": "管理此设备上的账号"
+        "manageOnDevice": "管理此设备上的账号",
+        "continueWithOxy": "使用 Oxy 继续",
+        "havingTrouble": "遇到问题？",
+        "progress": {
+            "preparing": "正在准备请求",
+            "awaitingApproval": "正在等待批准",
+            "scanWithCommons": "请用手机上的 Commons 扫描",
+            "continueInCommons": "请在 Commons 中继续",
+            "checkCommons": "请查看手机上的 Commons",
+            "openedInCommons": "已在 Commons 中打开",
+            "confirming": "正在确认身份",
+            "confirmed": "身份已确认"
+        }
     },
     "common": {
         "actions": {

package/dist/esm/index.js

@@ -28,6 +28,9 @@ export { OXY_CLOUD_URL, oxyClient } from './OxyServices.js';
 // ---------------------------------------------------------------------------
 export { ServiceCredentialMismatchError, } from './mixins/OxyServices.auth.js';
 export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from './utils/commonsApproval.js';
+// Automatic "Sign in with Oxy" delivery selection — ONE pure decision that maps
+// the caller's facts onto exactly one primary route (open Commons / await push / QR).
+export { selectCommonsDelivery, pushTargetsFromDelivery, commonsDeliveryPlatform } from './utils/commonsDelivery.js';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData.js';
 // ---------------------------------------------------------------------------
 // User identity and handles
@@ -145,7 +148,7 @@ export { runColdBoot } from './utils/coldBoot.js';
 // OAuth 2.0 Authorization Code + PKCE helpers ("Sign in with Oxy" third party).
 // Standard OAuth against auth.oxy.so/authorize — no FedCM/cookies/SSO bounce.
 // ---------------------------------------------------------------------------
-export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce.js';
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce.js';
 export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins.js';
 export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync.js';
 // ---------------------------------------------------------------------------
@@ -180,6 +183,16 @@ export { AccountDialogController, createAccountDialogController, } from './sessi
 // via `POST /session/device/token`.
 // ---------------------------------------------------------------------------
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore.js';
+// Identity-bound sessions (the identity vault). The pin is the durable
+// `{publicKey, accountId}` binding between this device's PRIMARY identity key
+// and the account it authenticates as; it is what keeps such a client from
+// following the device's mutable `activeAccountId`.
+export { createWebIdentityPinStore, createNativeIdentityPinStore, createMemoryIdentityPinStore, identityPinMatches, IDENTITY_PIN_STORAGE_KEY, } from './session/identityPin.js';
+export { resolveIdentityPin, establishIdentitySession, } from './session/identitySession.js';
+// The typed `401 account_not_on_device` from a PINNED device-secret mint: the
+// pinned account left this device's session set, so the caller re-establishes
+// the identity session instead of dropping a healthy device credential.
+export { AccountNotOnDeviceError } from './mixins/OxyServices.deviceBoot.js';
 export { refreshPersistedSession, refreshDeviceSecretArm, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh.js';
 export { runSessionColdBoot } from './boot/sessionColdBoot.js';
 // API response contracts (request/response Zod schemas + inferred types) live in

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

@@ -12,6 +12,61 @@ import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/use
  * returned `expiresAt` is authoritative; this is only the client-proposed value.
  */
 const COMMONS_SIGN_IN_EXPIRY_MS = 5 * 60 * 1000;
+/**
+ * @internal Narrow an untrusted `requesterLabel` from the approve-info response.
+ *
+ * Returns the trimmed label only when the server sent a real, non-empty string;
+ * everything else — absent (an API that predates the field), `null` (a native
+ * requester the server could not describe), or a non-string — degrades to
+ * `null`, so the approval UI drops the line instead of rendering a blank or a
+ * coerced value under the app it is about to authorize.
+ */
+function parseCommonsRequesterLabel(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const label = value.trim();
+    return label.length > 0 ? label : null;
+}
+/**
+ * @internal Narrow an untrusted `subjectAccount` from the approve-info response.
+ *
+ * Returns `null` unless the value is an object carrying a non-empty string `id`
+ * AND `username` — the two fields the approval UI needs to name the delegated
+ * account. A half-populated object is rejected whole rather than rendered with
+ * blanks, and `displayName` is only carried through when it is a string.
+ */
+function parseCommonsSubjectAccount(value) {
+    if (value === null || typeof value !== 'object') {
+        return null;
+    }
+    const raw = value;
+    const { id, username, displayName } = raw;
+    if (typeof id !== 'string' || !id || typeof username !== 'string' || !username) {
+        return null;
+    }
+    return {
+        id,
+        username,
+        ...(typeof displayName === 'string' ? { displayName } : {}),
+    };
+}
+/**
+ * @internal Narrow an untrusted delivery-progress timestamp from the status
+ * response.
+ *
+ * Returns the ISO-8601 string unchanged when it is a real, parseable instant,
+ * and `null` for everything else — absent (an older API that has no delivery
+ * progress at all), empty, non-string, or unparseable. Progress is advisory, so
+ * degrading to "no progress yet" is always safe; surfacing a garbage timestamp
+ * to the waiting UI is not.
+ */
+function parseCommonsProgressTimestamp(value) {
+    if (typeof value !== 'string' || !value) {
+        return null;
+    }
+    return Number.isFinite(Date.parse(value)) ? value : null;
+}
 /**
  * Sentinel error raised when getServiceToken() is called with a known apiKey
  * but a non-matching secret. Indicates either credential drift in the caller
@@ -459,11 +514,16 @@ export function OxyServicesAuthMixin(Base) {
         //   A. Same-device shared-keychain SSO (`signInWithSharedIdentity`): a
         //      sibling native app silently mints its own session from the shared
         //      identity key. No user interaction.
-        //   B. QR / app-to-app handoff: a relying party (`startCommonsSignIn` +
-        //      `pollCommonsSignIn` + the existing `claimSessionByToken`) and the
-        //      approver / Commons (`getCommonsApprovalInfo` + `approveCommonsSignIn`
-        //      / `denyCommonsSignIn`). The approver signs with its PRIMARY local
-        //      key; the RP never sees the private key.
+        //   B. QR / app-to-app / popup / push handoff: a relying party
+        //      (`startCommonsSignIn` + `pollCommonsSignIn`, finalized with either
+        //      `claimSessionByToken` or `finalizeCommonsOAuth`) and the approver /
+        //      Commons (`getCommonsApprovalInfo` + `approveCommonsSignIn` /
+        //      `denyCommonsSignIn`). The approver signs with its PRIMARY local key;
+        //      the RP never sees the private key.
+        //
+        //      ONE request serves every delivery surface. The delivery surface is
+        //      not part of the model: only the request's purpose is, and it is fixed
+        //      at creation by whether an OAuth binding was attached.
         // =======================================================================
         /**
          * MECHANISM A — same-device shared-keychain SSO.
@@ -514,12 +574,23 @@ export function OxyServicesAuthMixin(Base) {
          * returns the server-issued public `authorizeCode` + ready-to-render
          * `qrPayload`. Render the QR (web) / open the deep-link (same-device); the
          * approver resolves the code and authorizes. Then poll with
-         * {@link pollCommonsSignIn} and, on `authorized`, exchange the
-         * `sessionToken` via the existing `claimSessionByToken`.
+         * {@link pollCommonsSignIn} and finalize.
+         *
+         * ONE request serves every delivery surface, and how it finalizes is decided
+         * here by whether an OAuth binding is attached:
+         *   - no `oauth` (the default): a `device_sign_in` request — on `authorized`,
+         *     exchange the `sessionToken` via the existing `claimSessionByToken`.
+         *   - with `oauth`: an `oauth_authorization` request — on `authorized`, call
+         *     {@link finalizeCommonsOAuth} with the same `sessionToken` to mint the
+         *     single-use authorization code, then exchange it with PKCE.
          *
          * @param params.clientId - The RP's registered OAuth client id
          *   (ApplicationCredential publicKey); required so the server can resolve the
          *   requesting application's identity.
+         * @param params.oauth - Optional OAuth binding ({@link CommonsOAuthContext}).
+         *   Carries only the redirect URI, the PKCE S256 challenge, the requested
+         *   scope, and an optional delegated `subjectAccountId` — never the PKCE
+         *   verifier, the OAuth `state`, or any token.
          */
         async startCommonsSignIn(params) {
             try {
@@ -528,7 +599,15 @@ export function OxyServicesAuthMixin(Base) {
                 // QR. Reuses the platform-safe random generator.
                 const sessionToken = await SignatureService.generateChallenge();
                 const expiresAt = Date.now() + COMMONS_SIGN_IN_EXPIRY_MS;
-                const res = await this.makeRequest('POST', '/auth/session/create', { sessionToken, expiresAt, clientId: params.clientId }, 
+                const res = await this.makeRequest('POST', '/auth/session/create', {
+                    sessionToken,
+                    expiresAt,
+                    clientId: params.clientId,
+                    // Omitted entirely when absent so the device-sign-in body stays
+                    // exactly what it has always been (the server reads presence, not a
+                    // null, to decide the request's purpose).
+                    ...(params.oauth ? { oauth: params.oauth } : {}),
+                }, 
                 // Public/pre-session (no bearer): skip the preflight so a stale
                 // near-expiry token cannot re-enter refreshAccessToken while the
                 // refresh handler is already in flight (self-await hang).
@@ -549,18 +628,162 @@ export function OxyServicesAuthMixin(Base) {
          * MECHANISM B (relying party) — poll a device-flow session for approval.
          *
          * Backstop for the auth socket. On `authorized` (with a `sessionId`), the
-         * caller exchanges the secret `sessionToken` via the existing
-         * `claimSessionByToken` to mint the first access token.
+         * caller finalizes: `claimSessionByToken` for a `device_sign_in` request,
+         * {@link finalizeCommonsOAuth} for an `oauth_authorization` one.
+         *
+         * Every field is narrowed fail-safe. `authorized` counts only as a literal
+         * `true`, the identifiers only as non-empty strings, and the delivery
+         * progress timestamps degrade to `null` when absent or unparseable — so a
+         * partial or older-API payload can advance the waiting UI at most, never
+         * make it believe a request was approved.
          *
          * @param sessionToken - The secret token from {@link startCommonsSignIn}.
          */
         async pollCommonsSignIn(sessionToken) {
             try {
-                return await this.makeRequest('GET', `/auth/session/status/${encodeURIComponent(sessionToken)}`, undefined, 
+                const res = await this.makeRequest('GET', `/auth/session/status/${encodeURIComponent(sessionToken)}`, undefined, 
                 // Public/pre-session (no bearer): a preflight here is wrong per se and,
                 // if ever reached while a refresh is pending, would re-enter
                 // refreshAccessToken and await the very promise it runs inside.
                 { cache: false, retry: false, skipAuth: true });
+                if (res === null || typeof res !== 'object') {
+                    throw new Error('auth/session/status returned an unexpected response shape');
+                }
+                const { authorized, sessionId, publicKey, status, purpose, pushSentAt, openedAt } = res;
+                return {
+                    authorized: authorized === true,
+                    ...(typeof sessionId === 'string' && sessionId ? { sessionId } : {}),
+                    ...(typeof publicKey === 'string' && publicKey ? { publicKey } : {}),
+                    ...(typeof status === 'string' && status ? { status } : {}),
+                    purpose: purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in',
+                    pushSentAt: parseCommonsProgressTimestamp(pushSentAt),
+                    openedAt: parseCommonsProgressTimestamp(openedAt),
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (relying party) — ask Oxy to DELIVER a pending sign-in request
+         * to the identity's known Commons installations.
+         *
+         * This is the automatic half of "one intention, one primary action": rather
+         * than offering the user a menu of transports, the caller asks for delivery
+         * and lets the answer pick the route. Pass the returned `targets` to
+         * `selectCommonsDelivery` (`utils/commonsDelivery`) — `targets: 0` means no
+         * capable Commons installation is registered, which is a NORMAL outcome that
+         * resolves to the QR route, not an error to surface.
+         *
+         * **Requires a bearer.** Delivery is only allowed when Oxy already knows the
+         * intended identity from a trusted authenticated context — a request that
+         * merely carries a username or email typed into an unauthenticated browser
+         * must never be able to ring somebody's phone.
+         *
+         * The push it sends carries only `{ type, approvalUrl }` where the URL holds
+         * the public `authorizeCode` — no display data, no secrets. Commons resolves
+         * everything it shows from `getCommonsApprovalInfo`.
+         *
+         * @param authorizeCode - The public code from {@link startCommonsSignIn}.
+         */
+        async deliverCommonsSignIn(authorizeCode) {
+            try {
+                const res = await this.makeRequest('POST', `/auth/session/deliver/${encodeURIComponent(authorizeCode)}`, undefined, 
+                // Bearer REQUIRED (unlike its public siblings): the identity to
+                // deliver to comes from the authenticated caller, never the code.
+                { cache: false });
+                if (res === null || typeof res !== 'object') {
+                    throw new Error('auth/session/deliver returned an unexpected response shape');
+                }
+                const { delivered, targets } = res;
+                // Both fields drive the route choice, so a partial payload is rejected
+                // outright rather than defaulted into a route the server never chose.
+                if (typeof delivered !== 'boolean' ||
+                    typeof targets !== 'number' ||
+                    !Number.isInteger(targets) ||
+                    targets < 0) {
+                    throw new Error('auth/session/deliver returned an incomplete delivery result');
+                }
+                return { delivered, targets };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (approver / Commons) — report that the approval route was
+         * OPENED, so the waiting relying party can show "Opened in Commons".
+         *
+         * Progress only. It is idempotent, applies to a `pending` request alone, and
+         * records a timestamp (`openedAt`) — it never approves, authorizes, or
+         * advances the authorization state machine. Public, like the other approver
+         * handles: the approver has only the public `authorizeCode` at this point
+         * and has not yet signed anything.
+         *
+         * Best-effort by nature — a failure here costs the user only a progress
+         * line, so callers are free to ignore a rejection and continue to the
+         * approval screen.
+         *
+         * @param authorizeCode - The public code scanned from the QR / deep-link / push.
+         */
+        async markCommonsApprovalOpened(authorizeCode) {
+            try {
+                await this.makeRequest('POST', `/auth/session/opened/${encodeURIComponent(authorizeCode)}`, undefined, 
+                // Public (no bearer) — skip the preflight, exactly like approve-info.
+                { cache: false, skipAuth: true });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * MECHANISM B (relying party) — finalize an APPROVED, OAuth-bound request
+         * into a single-use OAuth authorization code.
+         *
+         * The OAuth counterpart of `claimSessionByToken`: same secret credential,
+         * same single-use semantics, different output. Call it once the request the
+         * RP started with an `oauth` binding reports `authorized`; the server
+         * atomically mints exactly ONE `AuthCode` bound to the redirect URI, PKCE
+         * challenge, scopes, approving identity, and any delegated subject account
+         * the request was created with. A second call cannot mint another code.
+         *
+         * The result is an authorization CODE, never a token — the caller completes
+         * the flow with the ordinary PKCE exchange (`exchangeOAuthCode`) using the
+         * `codeVerifier` it never sent anywhere. Nothing here is exposed to the
+         * popup: the code travels back through the registered callback, and the
+         * main window owns the verifier.
+         *
+         * Like `claimSessionByToken`, this needs no Authorization header — the
+         * high-entropy SECRET `sessionToken` IS the credential. Never pass the
+         * public `authorizeCode` here; it is the approver's handle, not the
+         * initiator's. Every server-side failure (wrong/expired/already-finalized
+         * request, non-OAuth purpose, missing permission for the delegated account)
+         * surfaces as one generic error, so nothing about the request's state can be
+         * probed from outside.
+         *
+         * @param sessionToken - The secret token from {@link startCommonsSignIn}.
+         */
+        async finalizeCommonsOAuth(sessionToken) {
+            try {
+                const res = await this.makeRequest('POST', `/auth/session/finalize/${encodeURIComponent(sessionToken)}`, undefined, 
+                // Body-authenticated by the path's secret token (no bearer) — skip the
+                // preflight, exactly like the device-flow claim.
+                { cache: false, skipAuth: true });
+                if (res === null || typeof res !== 'object') {
+                    throw new Error('auth/session/finalize returned an unexpected response shape');
+                }
+                const { code, redirectUri, expiresIn } = res;
+                // All three fields are load-bearing for the exchange that follows, so a
+                // partial payload is rejected outright rather than returned half-parsed.
+                if (typeof code !== 'string' ||
+                    !code ||
+                    typeof redirectUri !== 'string' ||
+                    !redirectUri ||
+                    typeof expiresIn !== 'number' ||
+                    !Number.isFinite(expiresIn)) {
+                    throw new Error('auth/session/finalize returned an incomplete authorization code');
+                }
+                return { code, redirectUri, expiresIn };
             }
             catch (error) {
                 throw this.handleError(error);
@@ -570,9 +793,10 @@ export function OxyServicesAuthMixin(Base) {
          * MECHANISM B (approver / Commons) — resolve the TRUSTED identity of a
          * sign-in request from its public `authorizeCode`.
          *
-         * The returned `application` is resolved server-side and is the only safe
-         * thing to display in the approval UI — NEVER trust the app/name/origin
-         * strings carried in the QR payload. Public (no auth required).
+         * The returned `application` and `subjectAccount` are resolved server-side
+         * and are the only safe things to display in the approval UI — NEVER trust
+         * the app/name/origin strings carried in the QR payload. Public (no auth
+         * required).
          *
          * @param authorizeCode - The public code scanned from the QR / deep-link.
          */
@@ -590,6 +814,17 @@ export function OxyServicesAuthMixin(Base) {
                     // missing or non-boolean value (older server, malformed response)
                     // coerces to `false` so a stale server can never imply trust.
                     originVerified: raw.originVerified === true,
+                    // Same discipline: a missing/blank/non-string label degrades to null
+                    // (an older API, or a native requester with no browser to describe),
+                    // and the approver simply omits the "where from" line.
+                    requesterLabel: parseCommonsRequesterLabel(raw.requesterLabel),
+                    // Same discipline: only the literal OAuth purpose opts into OAuth
+                    // finalization. Anything else — including a server that predates this
+                    // field — is the plain device sign-in it has always been.
+                    purpose: raw.purpose === 'oauth_authorization' ? 'oauth_authorization' : 'device_sign_in',
+                    // A missing/partial delegated account degrades to "no delegation"
+                    // rather than a half-rendered "will act as" line.
+                    subjectAccount: parseCommonsSubjectAccount(raw.subjectAccount),
                     expiresAt: raw.expiresAt,
                     status: raw.status,
                 };
@@ -641,10 +876,15 @@ export function OxyServicesAuthMixin(Base) {
          * device-flow session so the RP stops waiting.
          *
          * @param authorizeCode - The public code being denied.
+         * @param reason - Optional closed-set reason ({@link CommonsDenyReason}).
+         *   Pass `'not_me'` ONLY when the user actually reported the request as one
+         *   they did not start — the server records it as a suspicious denial rather
+         *   than an ordinary cancel. Omitting it sends the exact body this endpoint
+         *   has always received.
          */
-        async denyCommonsSignIn(authorizeCode) {
+        async denyCommonsSignIn(authorizeCode, reason) {
             try {
-                return await this.makeRequest('POST', `/auth/session/deny/${encodeURIComponent(authorizeCode)}`, undefined, 
+                return await this.makeRequest('POST', `/auth/session/deny/${encodeURIComponent(authorizeCode)}`, reason ? { reason } : undefined, 
                 // Public (no auth required) — skip the bearer preflight.
                 { cache: false, skipAuth: true });
             }
@@ -907,7 +1147,7 @@ export function OxyServicesAuthMixin(Base) {
                 const deviceId = (record.deviceId ?? record.device_id);
                 const deviceSecret = (record.deviceSecret ?? record.device_secret);
                 const userRaw = record.user;
-                if (!sessionId || !deviceId || !userRaw || typeof userRaw !== 'object') {
+                if (!sessionId || !deviceId || !deviceSecret || !userRaw || typeof userRaw !== 'object') {
                     throw new Error('auth/oauth/token returned an incomplete session payload');
                 }
                 const userObj = userRaw;

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

@@ -14,6 +14,40 @@
  * primitive can be reused from either without double-planting.
  */
 import { deviceTokenMintResponseSchema, deviceHubTicketIssueResponseSchema, deviceHubTicketRedeemResponseSchema, safeParseContract, } from '@oxyhq/contracts';
+/**
+ * The server's `401 account_not_on_device` for a PINNED mint: the requested
+ * `accountId` is not (or is no longer) a live account of this device session.
+ *
+ * Distinguished from every other mint 401 because the remedy is different: the
+ * device secret is FINE — it is the identity binding that went stale (the
+ * account was signed out on this device, or revoked). An identity-bound caller
+ * must re-establish its session from the local key rather than drop/clear the
+ * device credential.
+ */
+export class AccountNotOnDeviceError extends Error {
+    constructor(accountId, cause) {
+        super(`account_not_on_device: ${accountId} is not a live account of this device session`);
+        this.accountId = accountId;
+        this.cause = cause;
+        this.name = 'AccountNotOnDeviceError';
+        /** HTTP status of the originating response; mirrors the ApiError shape. */
+        this.status = 401;
+    }
+}
+/**
+ * Structural (never `instanceof`) read of a normalized mint error: the thrown
+ * value may be a plain ApiError-shaped object or come from another realm.
+ */
+function isAccountNotOnDevice(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const { status, message } = error;
+    if (status !== 401) {
+        return false;
+    }
+    return typeof message === 'string' && message.includes('account_not_on_device');
+}
 export function OxyServicesDeviceBootMixin(Base) {
     return class extends Base {
         /**
@@ -37,11 +71,22 @@ export function OxyServicesDeviceBootMixin(Base) {
          * boot's worst-case time-to-route. A transient failure surfaces once and the
          * scheduler/401 path retries it later.
          *
+         * `options.accountId` PINS the mint to one account of the device instead of
+         * whichever account is currently active. It exists for identity-bound
+         * clients (Commons), whose authenticated user is fixed by a local
+         * cryptographic key and must never follow an account switch made by another
+         * app on the same device. The server never mutates `activeAccountId` for a
+         * pinned mint — the returned `state` still reports the device's true active
+         * account — and rejects a non-member/dead account with
+         * `401 account_not_on_device`, surfaced here as {@link AccountNotOnDeviceError}.
+         *
+         * @throws {AccountNotOnDeviceError} when a pinned mint's account is not on the device.
          * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
          */
-        async mintFromDeviceSecret(deviceId, deviceSecret) {
+        async mintFromDeviceSecret(deviceId, deviceSecret, options) {
+            const accountId = options?.accountId;
             try {
-                const res = await this.makeRequest('POST', '/session/device/token', { deviceId, deviceSecret }, 
+                const res = await this.makeRequest('POST', '/session/device/token', { deviceId, deviceSecret, ...(accountId ? { accountId } : {}) }, 
                 // `bypassQueue`: this mint is the control-plane call the auth lane
                 // depends on — it must run even when every RequestQueue slot is parked
                 // awaiting it, or the whole client deadlocks. See RequestOptions.bypassQueue.
@@ -53,7 +98,11 @@ export function OxyServicesDeviceBootMixin(Base) {
                 return parsed;
             }
             catch (error) {
-                throw this.handleError(error);
+                const normalized = this.handleError(error);
+                if (accountId && isAccountNotOnDevice(normalized)) {
+                    throw new AccountNotOnDeviceError(accountId, normalized);
+                }
+                throw normalized;
             }
         }
         /** Mint a one-time hub sync ticket (bearer required). */