@oxyhq/core 12.10.5 → 12.11.0

package/src/boot/sessionColdBoot.ts

@@ -15,18 +15,45 @@
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   3. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
+ *   3. `shared-key-signin` (native, ACCOUNT mode) — re-mint from the
+ *      shared-keychain identity — OR `identity-key-signin` (IDENTITY mode) —
+ *      re-mint from THIS device's primary identity key.
  *   4. Signed out.
  *
+ * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
+ *   - `account` (default) — the device's ACTIVE account owns the session. Every
+ *     Oxy app but the identity vault boots this way; behaviour is unchanged.
+ *   - `identity` — the owner of the local PRIMARY identity key owns the session,
+ *     permanently, regardless of which account the device is switched to. Each
+ *     step above is bound to the persisted identity pin, and the shared-keychain
+ *     lane is replaced by the primary-key one (the shared slot is a CROSS-APP
+ *     slot that may hold a different identity).
+ *
  * ESM-safe (no `require()`); no react/react-native/expo imports.
  */
 import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/coldBoot';
 import { isNative as detectNative } from '../utils/platform';
 import { logger } from '../logger';
+import { computeIdentityTag } from '../utils/cacheKey';
 import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh';
+import {
+  establishIdentitySession,
+  resolveIdentityPin,
+  type IdentityBinding,
+} from '../session/identitySession';
+import type { IdentityPin } from '../session/identityPin';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore } from '../session/authStateStore';
 
+/**
+ * Who owns the session this boot resolves.
+ *
+ * - `account` — the device's active account (every ordinary Oxy app).
+ * - `identity` — the owner of the device's primary identity key (the identity
+ *   vault). Requires {@link RunSessionColdBootOptions.identity}.
+ */
+export type SessionMode = 'account' | 'identity';
+
 /** The winning session shape a cold-boot step reports. */
 export interface DeviceBootSession {
   sessionId: string;
@@ -72,6 +99,23 @@ export interface RunSessionColdBootOptions {
    * so a flaky probe can never falsely skip a real sign-in.
    */
   isOffline?: () => boolean;
+  /**
+   * Who owns the resolved session. Defaults to `'account'` — the device's active
+   * account — which is the behaviour every ordinary Oxy app has today and which
+   * this option leaves byte-for-byte unchanged.
+   *
+   * `'identity'` binds the boot to the owner of this device's PRIMARY identity
+   * key and REQUIRES {@link identity}. When it is missing the boot refuses to
+   * run any lane (an identity-bound client silently falling back to the device's
+   * active account is precisely the bug this mode exists to prevent) and
+   * resolves signed out.
+   */
+  sessionMode?: SessionMode;
+  /**
+   * The identity binding (pin store + key/signature access) used by
+   * `sessionMode: 'identity'`. Ignored in `'account'` mode.
+   */
+  identity?: IdentityBinding;
 }
 
 /**
@@ -85,6 +129,19 @@ export async function runSessionColdBoot(
   const { oxy, store } = opts;
   const isNative = opts.platform?.isNative ?? detectNative();
 
+  // Non-null ONLY in identity mode; every `!== null` test below therefore reads
+  // as "is this boot identity-bound?" while also narrowing the binding.
+  const identityBinding = opts.sessionMode === 'identity' ? opts.identity ?? null : null;
+  if (opts.sessionMode === 'identity' && identityBinding === null) {
+    logger.error(
+      'runSessionColdBoot: sessionMode "identity" requires an `identity` binding — refusing to run any lane (an identity-bound client must never adopt the device active account)',
+      undefined,
+      { component: 'sessionColdBoot', method: 'runSessionColdBoot' },
+    );
+    await opts.onSignedOut?.('error');
+    return { kind: 'unauthenticated' };
+  }
+
   // Best-effort connectivity gate for the NETWORK steps only. A missing hint or
   // any non-`true` verdict means "assume online" — never falsely skip a real
   // sign-in on an ambiguous probe.
@@ -94,6 +151,23 @@ export async function runSessionColdBoot(
   // bundler re-evaluation.
   let signedOutReason: SignedOutReason = 'no_session';
 
+  // Boot-local memo for the identity pin. Resolved lazily INSIDE a step so the
+  // (local, but storage-backed) read is covered by `overallDeadlineMs`, and
+  // resolved at most once per boot so two steps cannot disagree. Always `null`
+  // in account mode.
+  let pinResolved = false;
+  let cachedPin: IdentityPin | null = null;
+  const getIdentityPin = async (): Promise<IdentityPin | null> => {
+    if (identityBinding === null) {
+      return null;
+    }
+    if (!pinResolved) {
+      cachedPin = await resolveIdentityPin(identityBinding);
+      pinResolved = true;
+    }
+    return cachedPin;
+  };
+
   const steps: Array<ColdBootStep<DeviceBootSession>> = [];
 
   // 1. warm-token-plant (web + native) — the fastest path. When the persisted
@@ -122,6 +196,21 @@ export async function runSessionColdBoot(
       if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now() + TOKEN_REFRESH_LEAD_MS) {
         return { kind: 'skip' };
       }
+      if (identityBinding !== null) {
+        // Identity-bound: a persisted token is only acceptable when it belongs to
+        // the PINNED account. Both the token's own claim (`computeIdentityTag`,
+        // the same derivation `SessionClient.applyState` uses) and the owning
+        // session identity must match — a token planted for another account by an
+        // earlier account-mode write is exactly the durable drift this gate stops.
+        const pin = await getIdentityPin();
+        if (
+          pin === null ||
+          persisted.userId !== pin.accountId ||
+          computeIdentityTag(persisted.accessToken) !== pin.accountId
+        ) {
+          return { kind: 'skip' };
+        }
+      }
       oxy.setTokens(persisted.accessToken);
       return {
         kind: 'session',
@@ -148,7 +237,16 @@ export async function runSessionColdBoot(
     // a doomed mint cannot burn the overall deadline before routing settles.
     enabled: () => !isOffline(),
     run: async () => {
-      const result = await refreshDeviceSecretArm({ oxy, store });
+      const pin = await getIdentityPin();
+      if (identityBinding !== null && pin === null) {
+        // Identity-bound with no verified pin (never written, or cleared because
+        // the local key changed/vanished). An UNPINNED mint would adopt whichever
+        // account the device is currently switched to — the exact drift this mode
+        // exists to prevent. Fall through to `identity-key-signin`, which
+        // re-derives the account from the local key and rewrites the pin.
+        return { kind: 'skip' };
+      }
+      const result = await refreshDeviceSecretArm({ oxy, store, pin });
       switch (result.status) {
         case 'ok':
           // The arm persisted the rotated secret and planted the token.
@@ -186,6 +284,15 @@ export async function runSessionColdBoot(
             { component: 'sessionColdBoot', method: 'device-secret-mint' },
           );
           return { kind: 'skip' };
+        case 'account-not-on-device':
+          // Pinned mint rejected: the pinned account is no longer a live account
+          // of this device session. The secret is healthy — keep it untouched and
+          // let `identity-key-signin` re-establish from the local key.
+          logger.debug(
+            'pinned device-secret mint rejected (account_not_on_device) — keeping secret, re-establishing from the identity key',
+            { component: 'sessionColdBoot', method: 'device-secret-mint' },
+          );
+          return { kind: 'skip' };
         case 'transient':
           // Network / 5xx: keep the secret; a later attempt can succeed.
           logger.debug(
@@ -199,42 +306,81 @@ export async function runSessionColdBoot(
     },
   });
 
-  // 3. shared-key-signin (native) — re-mint from the shared identity. Native
-  //    AND online: it is a network step (challenge + verify round-trips), so it
-  //    is gated by the same offline hint as the mint lane. `{ retry: false }`
-  //    keeps the two round-trips as single attempts — the refresh scheduler /
-  //    401 lane own later retries — so this step cannot multiply boot latency.
-  steps.push({
-    id: 'shared-key-signin',
-    enabled: () => isNative && !isOffline(),
-    run: async () => {
-      const session = await oxy.signInWithSharedIdentity({ requestOptions: { retry: false } });
-      if (!session?.accessToken) {
-        return { kind: 'skip' };
-      }
-      // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
-      // boot can use the faster device-secret-mint lane (sockets + tab-focus
-      // re-mint depend on the credential being in the store).
-      if (session.deviceId && session.deviceSecret) {
-        await store.save({
-          sessionId: session.sessionId,
-          userId: session.user.id,
-          deviceId: session.deviceId,
-          deviceSecret: session.deviceSecret,
-          accessToken: session.accessToken,
-          expiresAt: session.expiresAt,
+  if (identityBinding !== null) {
+    // 3-identity. identity-key-signin — re-mint from THIS device's PRIMARY
+    //    identity key (`getPublicKey` → challenge → sign → verify). It REPLACES
+    //    `shared-key-signin`, which reads the CROSS-APP shared keychain slot and
+    //    may therefore hold a different identity than the device's primary — the
+    //    one thing an identity-bound client must never adopt. The server resolves
+    //    the account from the verified signer, so the winning session is
+    //    identity-authoritative and the pin is (re)written from it.
+    //
+    //    Online-gated like every network step; `{ retry: false }` keeps the two
+    //    round-trips single attempts (the refresh scheduler / 401 lane own later
+    //    retries) so this step cannot multiply boot latency. On web
+    //    `KeyManager.getPublicKey()` resolves to `null`, so it skips.
+    steps.push({
+      id: 'identity-key-signin',
+      enabled: () => !isOffline(),
+      run: async () => {
+        const established = await establishIdentitySession({
+          oxy,
+          store,
+          binding: identityBinding,
+          requestOptions: { retry: false },
         });
-      }
-      return {
-        kind: 'session',
-        session: {
-          sessionId: session.sessionId,
-          userId: session.user.id,
-          accessToken: session.accessToken,
-        },
-      };
-    },
-  });
+        const accessToken = established?.session.accessToken;
+        if (!established || !accessToken) {
+          return { kind: 'skip' };
+        }
+        return {
+          kind: 'session',
+          session: {
+            sessionId: established.session.sessionId,
+            userId: established.session.user.id,
+            accessToken,
+          },
+        };
+      },
+    });
+  } else {
+    // 3. shared-key-signin (native) — re-mint from the shared identity. Native
+    //    AND online: it is a network step (challenge + verify round-trips), so it
+    //    is gated by the same offline hint as the mint lane. `{ retry: false }`
+    //    keeps the two round-trips as single attempts — the refresh scheduler /
+    //    401 lane own later retries — so this step cannot multiply boot latency.
+    steps.push({
+      id: 'shared-key-signin',
+      enabled: () => isNative && !isOffline(),
+      run: async () => {
+        const session = await oxy.signInWithSharedIdentity({ requestOptions: { retry: false } });
+        if (!session?.accessToken) {
+          return { kind: 'skip' };
+        }
+        // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
+        // boot can use the faster device-secret-mint lane (sockets + tab-focus
+        // re-mint depend on the credential being in the store).
+        if (session.deviceId && session.deviceSecret) {
+          await store.save({
+            sessionId: session.sessionId,
+            userId: session.user.id,
+            deviceId: session.deviceId,
+            deviceSecret: session.deviceSecret,
+            accessToken: session.accessToken,
+            expiresAt: session.expiresAt,
+          });
+        }
+        return {
+          kind: 'session',
+          session: {
+            sessionId: session.sessionId,
+            userId: session.user.id,
+            accessToken: session.accessToken,
+          },
+        };
+      },
+    });
+  }
 
   const outcome = await runColdBoot<DeviceBootSession>({
     steps,

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

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "لا تملك Commons؟ احصل على التطبيق لتسجيل الدخول بمعرّف Oxy الخاص بك.",
     "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/src/i18n/locales/ca-ES.json

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "No tens Commons? Descarrega l'app per iniciar sessió amb el teu Oxy ID.",
     "showQrAnyway": "Tinc Commons en un altre dispositiu",
     "switchWhileSignedInAs": "Canvia de compte, amb la sessió iniciada com a {{name}}",
-    "manageOnDevice": "Gestionar comptes en aquest dispositiu"
+    "manageOnDevice": "Gestionar comptes en aquest dispositiu",
+    "continueWithOxy": "Continua amb Oxy",
+    "havingTrouble": "Algun problema?",
+    "progress": {
+      "preparing": "Preparant la sol·licitud",
+      "awaitingApproval": "Esperant l'aprovació",
+      "scanWithCommons": "Escaneja amb Commons al teu mòbil",
+      "continueInCommons": "Continua a Commons",
+      "checkCommons": "Revisa Commons al teu mòbil",
+      "openedInCommons": "Obert a Commons",
+      "confirming": "Confirmant la identitat",
+      "confirmed": "Identitat confirmada"
+    }
   },
   "common": {
     "actions": {

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

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "Kein Commons? Holen Sie sich die App, um sich mit Ihrer Oxy-ID anzumelden.",
     "showQrAnyway": "Ich habe Commons auf einem anderen Gerät",
     "switchWhileSignedInAs": "Konto wechseln, angemeldet als {{name}}",
-    "manageOnDevice": "Konten auf diesem Gerät verwalten"
+    "manageOnDevice": "Konten auf diesem Gerät verwalten",
+    "continueWithOxy": "Mit Oxy fortfahren",
+    "havingTrouble": "Gibt es ein Problem?",
+    "progress": {
+      "preparing": "Anfrage wird vorbereitet",
+      "awaitingApproval": "Warten auf Freigabe",
+      "scanWithCommons": "Scannen Sie mit Commons auf Ihrem Telefon",
+      "continueInCommons": "In Commons fortfahren",
+      "checkCommons": "Prüfen Sie Commons auf Ihrem Telefon",
+      "openedInCommons": "In Commons geöffnet",
+      "confirming": "Identität wird bestätigt",
+      "confirmed": "Identität bestätigt"
+    }
   },
   "common": {
     "actions": {

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

@@ -412,9 +412,6 @@
     },
     "label": "Account switcher",
     "searchPlaceholder": "Search accounts",
-    "scanTitle": "Scan to sign in",
-    "scanSubtitle": "Open the Oxy app on your phone and scan this code",
-    "scanWithOxy": "Scan with the Oxy app to continue",
     "scanQr": "Scan QR code",
     "qrHeadline": "Sign in with your Oxy identity",
     "signInWithOxy": "Sign in with Oxy",
@@ -424,7 +421,19 @@
     "commonsNotInstalled": "Don't have Commons? Get the app to sign in with your Oxy ID.",
     "showQrAnyway": "I have Commons on another device",
     "switchWhileSignedInAs": "Switch account, signed in as {{name}}",
-    "manageOnDevice": "Manage accounts on this device"
+    "manageOnDevice": "Manage accounts on this device",
+    "continueWithOxy": "Continue with Oxy",
+    "havingTrouble": "Having trouble?",
+    "progress": {
+      "preparing": "Preparing request",
+      "awaitingApproval": "Waiting for approval",
+      "scanWithCommons": "Scan with Commons on your phone",
+      "continueInCommons": "Continue in Commons",
+      "checkCommons": "Check Commons on your phone",
+      "openedInCommons": "Opened in Commons",
+      "confirming": "Confirming identity",
+      "confirmed": "Identity confirmed"
+    }
   },
   "reputation": {
     "faq": {

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

@@ -652,9 +652,6 @@
     },
     "label": "Selector de cuentas",
     "searchPlaceholder": "Buscar cuentas",
-    "scanTitle": "Escanea para iniciar sesión",
-    "scanSubtitle": "Abre la app de Oxy en tu móvil y escanea este código",
-    "scanWithOxy": "Escanea con la app de Oxy para continuar",
     "scanQr": "Escanear código QR",
     "qrHeadline": "Inicia sesión con tu identidad de Oxy",
     "signInWithOxy": "Inicia sesión con Oxy",
@@ -664,7 +661,19 @@
     "commonsNotInstalled": "¿No tienes Commons? Descarga la app para iniciar sesión con tu Oxy ID.",
     "showQrAnyway": "Tengo Commons en otro dispositivo",
     "switchWhileSignedInAs": "Cambiar de cuenta, con la sesión iniciada como {{name}}",
-    "manageOnDevice": "Gestionar cuentas en este dispositivo"
+    "manageOnDevice": "Gestionar cuentas en este dispositivo",
+    "continueWithOxy": "Continuar con Oxy",
+    "havingTrouble": "¿Algún problema?",
+    "progress": {
+      "preparing": "Preparando la solicitud",
+      "awaitingApproval": "Esperando la aprobación",
+      "scanWithCommons": "Escanea con Commons en tu móvil",
+      "continueInCommons": "Continúa en Commons",
+      "checkCommons": "Revisa Commons en tu móvil",
+      "openedInCommons": "Abierto en Commons",
+      "confirming": "Confirmando identidad",
+      "confirmed": "Identidad confirmada"
+    }
   },
   "feedback": {
     "type": {

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

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "Pas de Commons ? Téléchargez l'app pour vous connecter avec votre Oxy ID.",
     "showQrAnyway": "J'ai Commons sur un autre appareil",
     "switchWhileSignedInAs": "Changer de compte, connecté en tant que {{name}}",
-    "manageOnDevice": "Gérer les comptes sur cet appareil"
+    "manageOnDevice": "Gérer les comptes sur cet appareil",
+    "continueWithOxy": "Continuer avec Oxy",
+    "havingTrouble": "Un problème ?",
+    "progress": {
+      "preparing": "Préparation de la demande",
+      "awaitingApproval": "En attente d'approbation",
+      "scanWithCommons": "Scannez avec Commons sur votre téléphone",
+      "continueInCommons": "Continuez dans Commons",
+      "checkCommons": "Consultez Commons sur votre téléphone",
+      "openedInCommons": "Ouvert dans Commons",
+      "confirming": "Confirmation de l'identité",
+      "confirmed": "Identité confirmée"
+    }
   },
   "common": {
     "actions": {

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

@@ -124,7 +124,19 @@
     "commonsNotInstalled": "Non hai Commons? Scarica l'app per accedere con il tuo Oxy ID.",
     "showQrAnyway": "Ho Commons su un altro dispositivo",
     "switchWhileSignedInAs": "Cambia account, connesso come {{name}}",
-    "manageOnDevice": "Gestisci account su questo dispositivo"
+    "manageOnDevice": "Gestisci account su questo dispositivo",
+    "continueWithOxy": "Continua con Oxy",
+    "havingTrouble": "Problemi?",
+    "progress": {
+      "preparing": "Preparazione della richiesta",
+      "awaitingApproval": "In attesa di approvazione",
+      "scanWithCommons": "Scansiona con Commons sul tuo telefono",
+      "continueInCommons": "Continua in Commons",
+      "checkCommons": "Controlla Commons sul tuo telefono",
+      "openedInCommons": "Aperto in Commons",
+      "confirming": "Conferma dell'identità in corso",
+      "confirmed": "Identità confermata"
+    }
   },
   "common": {
     "actions": {

package/src/i18n/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/src/i18n/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/src/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/src/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/src/index.ts

@@ -41,14 +41,33 @@ export {
   getCommonsApprovalBlockingReason,
   parseCommonsApprovalExpiresAt,
 } from './utils/commonsApproval';
+// 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';
+export type {
+    CommonsDeliveryFacts,
+    CommonsDeliveryPlatform,
+    CommonsDeliveryRoute,
+} from './utils/commonsDelivery';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 // "Sign in with Oxy" — handoff (Workstream C)
 export type {
     CommonsSignInHandle,
     CommonsSignInStatus,
+    CommonsSignInPurpose,
+    CommonsOAuthContext,
     CommonsApprovalInfo,
+    CommonsApprovalSubjectAccount,
     CommonsSignInActionResult,
+    CommonsDenyReason,
+    CommonsOAuthFinalizeResult,
+    CommonsDeliveryResult,
 } from './mixins/OxyServices.auth';
+// Push-token registration (Expo push tokens — never raw APNs/FCM device tokens).
+export type {
+    PushTokenPlatform,
+    RegisterPushTokenInput,
+} from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type {
     ContactDiscoveryMatch,
@@ -581,10 +600,12 @@ export {
     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,
@@ -666,6 +687,7 @@ export type {
     PopupWindowHandle,
     SignInFlowPhase,
     SignInFlowState,
+    SignInProgress,
 } from './session/accountDialogController';
 
 // ---------------------------------------------------------------------------
@@ -687,6 +709,32 @@ export type {
     NativeKeyValueStorage,
 } from './session/authStateStore';
 
+// 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';
+export type { IdentityPin, IdentityPinStore } from './session/identityPin';
+export {
+    resolveIdentityPin,
+    establishIdentitySession,
+} from './session/identitySession';
+export type {
+    IdentityBinding,
+    IdentityRequestOptions,
+    EstablishedIdentitySession,
+} from './session/identitySession';
+// 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';
+
 export {
     refreshPersistedSession,
     refreshDeviceSecretArm,
@@ -700,6 +748,7 @@ export type { RefreshDeps, TokenRefreshSchedulerHandle, DeviceSecretMintOutcome
 export { runSessionColdBoot } from './boot/sessionColdBoot';
 export type {
     RunSessionColdBootOptions,
+    SessionMode,
     SignedOutReason,
     DeviceBootSession,
 } from './boot/sessionColdBoot';