@oxyhq/core 12.10.5 → 12.11.0

package/src/session/refresh.ts

@@ -24,6 +24,8 @@ import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { OxyServices } from '../OxyServices';
 import type { AuthRefreshHandler, AuthRefreshReason } from '../HttpService';
 import type { AuthStateStore, PersistedAuthState } from './authStateStore';
+import type { IdentityPin } from './identityPin';
+import { establishIdentitySession, resolveIdentityPin, type IdentityBinding } from './identitySession';
 import { isNative } from '../utils/platform';
 import { extractErrorStatus } from '../utils/errorUtils';
 import { logger } from '../logger';
@@ -67,9 +69,19 @@ export interface RefreshDeps {
   /**
    * Whether to fall back to the native shared-keychain re-mint (arm 2) when the
    * persisted secret is absent / rejected. Defaults to `isNative()` — web has no
-   * shared keychain. Exposed for tests.
+   * shared keychain. Exposed for tests. IGNORED when {@link identity} is set: an
+   * identity-bound client must never adopt the CROSS-APP shared slot, which may
+   * hold a different identity than this device's primary key.
    */
   allowSharedKeyFallback?: boolean;
+  /**
+   * Identity-bound (pinned) mode. When present, every re-mint targets the
+   * PINNED account — resolved fresh from the pin store on each call, since a
+   * re-established session can move it — instead of the device's active
+   * account, and arm 2 becomes the PRIMARY-key identity sign-in rather than the
+   * shared-keychain one.
+   */
+  identity?: IdentityBinding;
 }
 
 /**
@@ -82,6 +94,10 @@ export interface RefreshDeps {
  *    diverged (another tab/device rotated it past the grace window).
  *  - `no-session` — 401 `no_active_session`: the device is known but has no live
  *    session (authoritative signed-out).
+ *  - `account-not-on-device` — 401 `account_not_on_device` for a PINNED mint: the
+ *    pinned account is not (or no longer) a live account of this device session.
+ *    The device secret is FINE — it is the identity binding that went stale, so
+ *    the caller must re-establish from the local key, never drop the credential.
  *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
  *  - `persist-failed` — the mint succeeded (the SERVER rotated the secret) but
  *    the rotated `nextDeviceSecret` could NOT be durably persisted. The token is
@@ -93,6 +109,7 @@ export type DeviceSecretMintOutcome =
   | { status: 'no-secret' }
   | { status: 'invalid-secret' }
   | { status: 'no-session' }
+  | { status: 'account-not-on-device' }
   | { status: 'transient' }
   | { status: 'persist-failed' };
 
@@ -116,12 +133,21 @@ export type DeviceSecretMintOutcome =
  * planting. This function performs NO store mutation on failure — the caller
  * applies the drop/clear policy (which differs web vs native) from the returned
  * status.
+ *
+ * `pin` makes the mint IDENTITY-BOUND: the request carries the pinned
+ * `accountId` (so the server mints that account's token without touching
+ * `activeAccountId`), and the persisted `sessionId`/`userId` are resolved from
+ * the PINNED account entry — never from `state.activeAccountId`, whose drift is
+ * exactly what the pin exists to stop.
  */
 export async function refreshDeviceSecretArm(deps: {
   oxy: OxyServices;
   store: AuthStateStore;
+  /** The identity pin, when this client is identity-bound. */
+  pin?: IdentityPin | null;
 }): Promise<DeviceSecretMintOutcome> {
   const { oxy, store } = deps;
+  const pin = deps.pin ?? null;
   return oxy.httpService.runSingleFlightDeviceSecretMint(async () => {
     const persisted = await store.load();
     if (!persisted?.deviceId || !persisted?.deviceSecret) {
@@ -130,7 +156,13 @@ export async function refreshDeviceSecretArm(deps: {
 
     let mint: DeviceTokenMintResponse;
     try {
-      mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
+      // Unpinned callers pass NO third argument at all, so the account-mode call
+      // shape (and therefore the request body) is untouched by this feature.
+      mint = pin
+        ? await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret, {
+            accountId: pin.accountId,
+          })
+        : await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
     } catch (error) {
       if (extractErrorStatus(error) === 401) {
         // Structural read (not `instanceof Error`): the thrown value can be a
@@ -147,19 +179,26 @@ export async function refreshDeviceSecretArm(deps: {
         // ecosystem-wide.
         if (body.includes('invalid_device_secret')) return { status: 'invalid-secret' };
         if (body.includes('no_active_session')) return { status: 'no-session' };
+        // A pinned mint whose account left the device set. The secret is intact —
+        // never classify this as a bad secret, or the caller would drop a healthy
+        // credential over a stale identity binding.
+        if (body.includes('account_not_on_device')) return { status: 'account-not-on-device' };
         return { status: 'transient' };
       }
       return { status: 'transient' };
     }
 
-    const active = mint.state.accounts.find((a) => a.accountId === mint.state.activeAccountId);
+    // The account this session is BOUND to: the pinned one when identity-bound
+    // (the server already minted for it), else the device's active account.
+    const boundAccountId = pin ? pin.accountId : mint.state.activeAccountId;
+    const bound = mint.state.accounts.find((a) => a.accountId === boundAccountId);
     const next: PersistedAuthState = {
       ...persisted,
       deviceId: mint.state.deviceId,
       deviceSecret: mint.nextDeviceSecret,
       accessToken: mint.accessToken,
       expiresAt: mint.expiresAt,
-      ...(active ? { sessionId: active.sessionId, userId: active.accountId } : {}),
+      ...(bound ? { sessionId: bound.sessionId, userId: bound.accountId } : {}),
     };
     // Rotation-in-use anti-loss: persist the NEXT secret and read-back-VERIFY it
     // landed BEFORE planting the token. A failed durable persist must NOT plant.
@@ -188,12 +227,26 @@ export async function refreshDeviceSecretArm(deps: {
  * recovered `{deviceId, deviceSecret, …}` is PERSISTED so the fast device-secret
  * lane is repopulated (mirrors the cold boot's `shared-key-signin` step) — an
  * in-session shared-key recovery must not leave the fast-lane credential empty.
+ *
+ * IDENTITY-BOUND clients (`deps.identity`) run a different arm 2: the
+ * shared-keychain lane is DISABLED (its cross-app slot may hold a different
+ * identity) and replaced by {@link establishIdentitySession}, which re-signs a
+ * challenge with the PRIMARY local key and rewrites the pin. Arm 1 is pinned.
  */
 export async function refreshPersistedSession(deps: RefreshDeps): Promise<string | null> {
   const { oxy, store } = deps;
-  const allowSharedKeyFallback = deps.allowSharedKeyFallback ?? isNative();
+  const identity = deps.identity ?? null;
+  // The shared keychain is never an identity-bound client's recovery path.
+  const allowSharedKeyFallback = identity ? false : (deps.allowSharedKeyFallback ?? isNative());
+  // Resolved per call: a re-established identity session can move the pin, and a
+  // replaced/removed local key clears it (in which case arm 1 must NOT mint —
+  // an unpinned mint would adopt whatever account the device switched to).
+  const pin = identity ? await resolveIdentityPin(identity) : null;
+  if (identity && !pin) {
+    return recoverIdentitySession(oxy, store, identity);
+  }
 
-  const arm1 = await refreshDeviceSecretArm({ oxy, store });
+  const arm1 = await refreshDeviceSecretArm({ oxy, store, pin });
   switch (arm1.status) {
     case 'ok':
       return arm1.token;
@@ -216,11 +269,12 @@ export async function refreshPersistedSession(deps: RefreshDeps): Promise<string
       return null;
     case 'invalid-secret':
     case 'no-session': {
-      // 401: secret diverged or no live session. On a shared-key device drop only
-      // the secret (keep the identity so arm 2 can recover); otherwise (web) the
+      // 401: secret diverged or no live session. When a key-based arm 2 can still
+      // recover (native shared key, or an identity-bound client's own primary
+      // key) drop ONLY the secret and keep the deviceId; otherwise (web) the
       // session is over — clear the store.
       const persisted = await store.load();
-      if (allowSharedKeyFallback) {
+      if (allowSharedKeyFallback || identity) {
         if (persisted) {
           await store.save({ ...persisted, deviceSecret: undefined });
         }
@@ -229,10 +283,22 @@ export async function refreshPersistedSession(deps: RefreshDeps): Promise<string
       }
       break;
     }
+    case 'account-not-on-device':
+      // The pinned account left this device's session set. The secret is healthy —
+      // leave the store untouched and let the identity arm re-establish.
+      logger.debug(
+        'Pinned device-secret mint rejected: the pinned account is no longer on this device — re-establishing from the identity key',
+        { component: 'refresh', method: 'refreshPersistedSession' },
+      );
+      break;
     case 'no-secret':
       break;
   }
 
+  if (identity) {
+    return recoverIdentitySession(oxy, store, identity);
+  }
+
   if (allowSharedKeyFallback) {
     try {
       const session = await oxy.signInWithSharedIdentity();
@@ -262,6 +328,34 @@ export async function refreshPersistedSession(deps: RefreshDeps): Promise<string
   return null;
 }
 
+/**
+ * Arm 2 for an IDENTITY-BOUND client: re-establish the session from the PRIMARY
+ * local key and rewrite the pin (`establishIdentitySession` plants the token and
+ * persists the device credential itself).
+ *
+ * Returns `null` — never throws — when there is no local identity, the verify
+ * yielded no token, or the exchange failed: the caller treats that as "could not
+ * refresh", exactly like the shared-key arm. A locked keychain therefore ends
+ * signed out rather than falling back to the device's active account.
+ */
+async function recoverIdentitySession(
+  oxy: OxyServices,
+  store: AuthStateStore,
+  binding: IdentityBinding,
+): Promise<string | null> {
+  try {
+    const established = await establishIdentitySession({ oxy, store, binding });
+    return established?.session.accessToken ?? null;
+  } catch (error) {
+    logger.debug(
+      'Identity-key re-sign-in failed',
+      { component: 'refresh', method: 'recoverIdentitySession' },
+      error,
+    );
+    return null;
+  }
+}
+
 /**
  * Build the reactive `AuthRefreshHandler` (arm 1 + arm 2). Install it via
  * {@link installAuthRefreshHandler} or directly on

package/src/utils/__tests__/oauthPkce.test.ts

@@ -1,15 +1,19 @@
 import { createHash } from 'node:crypto';
 import {
   buildOAuthAuthorizeUrl,
+  canonicalizeOAuthRedirectUri,
   computeCodeChallenge,
   DEFAULT_OAUTH_SCOPE,
   generateOAuthState,
   generatePkcePair,
   OXY_AUTHORIZE_URL,
+  OXY_OAUTH_REDIRECT_URI_STORAGE_KEY,
   OXY_OAUTH_RETURN_PATH_STORAGE_KEY,
   clearOAuthHandshake,
   consumeOAuthReturnPath,
+  persistOAuthHandshake,
   persistOAuthReturnPath,
+  readOAuthHandshake,
 } from '../oauthPkce';
 
 /** RFC 7636 unreserved subset produced by base64url (no `+`, `/`, `=`). */
@@ -157,6 +161,53 @@ describe('buildOAuthAuthorizeUrl', () => {
   });
 });
 
+describe('canonicalizeOAuthRedirectUri', () => {
+  it('collapses apex URLs to origin only', () => {
+    expect(canonicalizeOAuthRedirectUri('https://app.example/')).toBe('https://app.example');
+    expect(canonicalizeOAuthRedirectUri('https://app.example')).toBe('https://app.example');
+  });
+
+  it('preserves path-qualified redirect URIs', () => {
+    const uri = 'https://app.example/oauth/callback';
+    expect(canonicalizeOAuthRedirectUri(uri)).toBe(uri);
+  });
+});
+
+describe('OAuth handshake persistence', () => {
+  function installSessionStorage(): Map<string, string> {
+    const map = new Map<string, string>();
+    (globalThis as { sessionStorage?: Storage }).sessionStorage = {
+      getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+      setItem: (k: string, v: string) => void map.set(k, v),
+      removeItem: (k: string) => void map.delete(k),
+      clear: () => map.clear(),
+      key: (i: number) => [...map.keys()][i] ?? null,
+      get length() {
+        return map.size;
+      },
+    } as unknown as Storage;
+    return map;
+  }
+
+  afterEach(() => {
+    delete (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  });
+
+  it('round-trips redirect_uri through persist/read/clear', () => {
+    const store = installSessionStorage();
+    const redirectUri = 'https://app.example/oauth/callback';
+    expect(persistOAuthHandshake('state-1', 'verifier-1', redirectUri)).toBe(true);
+    expect(readOAuthHandshake()).toEqual({
+      state: 'state-1',
+      codeVerifier: 'verifier-1',
+      redirectUri,
+    });
+    clearOAuthHandshake();
+    expect(store.get(OXY_OAUTH_REDIRECT_URI_STORAGE_KEY)).toBeUndefined();
+    expect(readOAuthHandshake()).toBeNull();
+  });
+});
+
 describe('OAuth return path', () => {
   /** Minimal sessionStorage stand-in — jsdom is not assumed by this suite. */
   function installSessionStorage(): Map<string, string> {

package/src/utils/commonsDelivery.ts

@@ -0,0 +1,132 @@
+import { getPlatformOS } from './platform';
+
+/**
+ * Automatic "Sign in with Oxy" delivery selection (issue #691, Phase 4).
+ *
+ * The user performs ONE action ("Continue with Oxy"); Oxy — not the user —
+ * decides how the approval request reaches their Commons identity. This module
+ * is that decision, and nothing else: a single pure function mapping the facts
+ * the caller has gathered onto exactly ONE primary route.
+ *
+ * Deliberate design constraints:
+ *
+ *  - **Pure.** No I/O, no platform sniffing, no clock, no globals. Every input
+ *    is passed in by the caller, which is what makes the decision exhaustively
+ *    unit-testable and identical on web, native, and server.
+ *  - **One route, never a chain.** The result is the PRIMARY route only.
+ *    Alternatives stay hidden behind a "Having trouble?" affordance and are
+ *    revealed by the UI only once the primary route fails or is unavailable —
+ *    the SDK never silently cascades from one delivery surface to the next.
+ *  - **Fail-safe to QR.** QR is the route that works with no prior knowledge of
+ *    the device, so every ambiguous or malformed input degrades to it rather
+ *    than to a route that could leave the user staring at a dead end.
+ *
+ * Every route drives the SAME `AuthSession`, resolved from the same public
+ * `authorizeCode`; the route only decides how that code travels.
+ */
+
+/**
+ * The kind of surface the sign-in was initiated from.
+ *
+ * `'unknown'` is a first-class value, not an error: a caller that cannot
+ * confidently classify the surface must say so rather than guess, and an
+ * unknown surface never opts into the deep-link route (a custom-scheme
+ * navigation that does not resolve is a dead end with no automatic way back).
+ */
+export type CommonsDeliveryPlatform = 'mobile' | 'desktop' | 'unknown';
+
+/**
+ * The single primary route chosen for this request.
+ *
+ *  - `'open-commons'` — navigate to the verified Commons app/universal link on
+ *    THIS device and let the user confirm there.
+ *  - `'await-push'` — the request was pushed to a known Commons installation;
+ *    show "Check Commons on your phone" and wait for the authorization.
+ *  - `'qr'` — render the QR carrying the public `authorizeCode` for the user to
+ *    scan with Commons on another device.
+ */
+export type CommonsDeliveryRoute = 'open-commons' | 'await-push' | 'qr';
+
+/**
+ * The facts the caller must gather before asking for a route. All of them are
+ * observations, never decisions — the caller owns the platform detection, the
+ * app-link verification, and the delivery round-trip; this module owns only the
+ * choice between them.
+ */
+export interface CommonsDeliveryFacts {
+  /** Which surface the sign-in was initiated from (see {@link CommonsDeliveryPlatform}). */
+  platform: CommonsDeliveryPlatform;
+  /**
+   * `true` only when a VERIFIED Commons app/universal link can be opened on
+   * this very device (an installed, link-verified Commons). "The user probably
+   * has Commons somewhere" is not this fact — that is what `pushTargets`
+   * expresses.
+   */
+  commonsAvailable: boolean;
+  /**
+   * How many eligible Commons installations the server said it delivered the
+   * request to — the `targets` field of `deliverCommonsSignIn`. Zero is a
+   * NORMAL outcome (no capable Commons install is registered for this
+   * identity), never an error; it simply means push is not a usable route.
+   */
+  pushTargets: number;
+}
+
+/**
+ * Choose the ONE primary delivery route for a "Sign in with Oxy" request.
+ *
+ * Decision order (issue #691, "Automatic delivery selection"):
+ *
+ *  1. Mobile with a verified Commons link available → open Commons directly.
+ *     No push is needed when the identity is already reachable on this device.
+ *  2. At least one eligible Commons installation was pushed to → await the push.
+ *  3. Otherwise → QR.
+ *
+ * A caller that already knows it is on step 1 does not need to call
+ * `deliverCommonsSignIn` at all; every other caller runs the delivery
+ * round-trip first and passes its `targets` in here.
+ *
+ * `pushTargets` is server-derived, so it is validated rather than trusted: a
+ * negative, fractional, non-finite, or otherwise malformed count is treated as
+ * "no targets" and degrades to QR instead of parking the user on a "check your
+ * phone" screen that nothing will ever wake.
+ */
+export function selectCommonsDelivery(facts: CommonsDeliveryFacts): CommonsDeliveryRoute {
+  if (facts.platform === 'mobile' && facts.commonsAvailable) {
+    return 'open-commons';
+  }
+  if (Number.isInteger(facts.pushTargets) && facts.pushTargets >= 1) {
+    return 'await-push';
+  }
+  return 'qr';
+}
+
+/**
+ * Map a `deliverCommonsSignIn` result onto the `pushTargets` fact for
+ * {@link selectCommonsDelivery}. The server reports eligible install *count*
+ * separately from whether any push was accepted — a transport failure can leave
+ * `delivered: false` with `targets > 0`, which must NOT park the user on
+ * "check your phone".
+ */
+export function pushTargetsFromDelivery(result: {
+  delivered: boolean;
+  targets: number;
+}): number {
+  return result.delivered ? result.targets : 0;
+}
+
+/**
+ * Classify the current runtime surface for delivery selection. Callers that
+ * cannot confidently detect the platform should not use this — pass
+ * `'unknown'` explicitly instead.
+ */
+export function commonsDeliveryPlatform(): CommonsDeliveryPlatform {
+  const os = getPlatformOS();
+  if (os === 'ios' || os === 'android') {
+    return 'mobile';
+  }
+  if (os === 'web') {
+    return 'desktop';
+  }
+  return 'unknown';
+}

package/src/utils/oauthPkce.ts

@@ -66,6 +66,18 @@ export interface BuildOAuthAuthorizeUrlParams {
    * (no UI when the IdP hub already has a session + grant).
    */
   prompt?: 'none' | 'login' | 'consent';
+  /**
+   * How the IdP should deliver the authorization response. Omitted (the
+   * default) means the ordinary top-level redirect back to `redirectUri`.
+   *
+   * `web_message` asks the IdP to `postMessage` the result to its opener
+   * instead, so a popup sign-in never navigates the relying party's tab. It is
+   * a REQUEST, not a guarantee: an IdP with no opener still redirects, which is
+   * why the popup transport must handle both outcomes. Only the authorization
+   * code, the `state`, and a typed OAuth error ever cross that channel — never
+   * a token, device secret, or the PKCE verifier, which the opener keeps.
+   */
+  responseMode?: 'web_message';
 }
 
 /**
@@ -192,6 +204,9 @@ export function buildOAuthAuthorizeUrl(params: BuildOAuthAuthorizeUrlParams): st
   if (params.prompt) {
     url.searchParams.set('prompt', params.prompt);
   }
+  if (params.responseMode) {
+    url.searchParams.set('response_mode', params.responseMode);
+  }
 
   return url.toString();
 }
@@ -202,6 +217,9 @@ export const OXY_OAUTH_STATE_STORAGE_KEY = 'oxy_oauth_state';
 /** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
 export const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = 'oxy_oauth_code_verifier';
 
+/** `sessionStorage` key — the exact `redirect_uri` sent on the authorize request. */
+export const OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = 'oxy.oauth_redirect_uri';
+
 /** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
 export const OXY_SILENT_OAUTH_ATTEMPTED_KEY = 'oxy.silent_oauth_attempted';
 
@@ -231,6 +249,25 @@ export function normalizeOAuthRedirectUri(input: string): string {
   }
 }
 
+/**
+ * Collapse `https://app.example/` → `https://app.example` for OAuth binding.
+ * Path-qualified redirect URIs are preserved — matches the API token exchange.
+ */
+export function canonicalizeOAuthRedirectUri(redirectUri: string): string {
+  try {
+    const parsed = new URL(redirectUri);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      return redirectUri;
+    }
+    if (parsed.pathname === '/' && !parsed.search && !parsed.hash) {
+      return parsed.origin;
+    }
+    return redirectUri;
+  } catch {
+    return redirectUri;
+  }
+}
+
 /**
  * Is this a safe same-origin path to restore into the address bar?
  *
@@ -295,12 +332,22 @@ export function consumeOAuthReturnPath(): string | null {
 }
 
 /** Persist the OAuth handshake for a full-page redirect return (web only). */
-export function persistOAuthHandshake(state: string, codeVerifier: string): boolean {
+export function persistOAuthHandshake(
+  state: string,
+  codeVerifier: string,
+  redirectUri?: string,
+): boolean {
   const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
   try {
     if (!store) throw new Error('sessionStorage is unavailable');
     store.setItem(OXY_OAUTH_STATE_STORAGE_KEY, state);
     store.setItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, codeVerifier);
+    if (redirectUri) {
+      store.setItem(
+        OXY_OAUTH_REDIRECT_URI_STORAGE_KEY,
+        canonicalizeOAuthRedirectUri(redirectUri),
+      );
+    }
     return true;
   } catch (error) {
     logger.warn(
@@ -313,13 +360,18 @@ export function persistOAuthHandshake(state: string, codeVerifier: string): bool
 }
 
 /** Read the persisted OAuth handshake, or `null` when absent. */
-export function readOAuthHandshake(): { state: string; codeVerifier: string } | null {
+export function readOAuthHandshake(): {
+  state: string;
+  codeVerifier: string;
+  redirectUri?: string;
+} | null {
   const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
   if (!store) return null;
   const state = store.getItem(OXY_OAUTH_STATE_STORAGE_KEY);
   const codeVerifier = store.getItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
   if (!state || !codeVerifier) return null;
-  return { state, codeVerifier };
+  const redirectUri = store.getItem(OXY_OAUTH_REDIRECT_URI_STORAGE_KEY) ?? undefined;
+  return redirectUri ? { state, codeVerifier, redirectUri } : { state, codeVerifier };
 }
 
 /** Drop persisted OAuth handshake keys after a successful or aborted return. */
@@ -328,6 +380,7 @@ export function clearOAuthHandshake(): void {
   try {
     store?.removeItem(OXY_OAUTH_STATE_STORAGE_KEY);
     store?.removeItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+    store?.removeItem(OXY_OAUTH_REDIRECT_URI_STORAGE_KEY);
     // The return path belongs to this handshake. Leaving it behind would let a
     // later, unrelated navigation in the same tab be redirected by it.
     store?.removeItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY);