@oxyhq/core 12.10.5 → 12.11.0

package/src/session/identityPin.ts

@@ -0,0 +1,310 @@
+/**
+ * Identity pin — the durable binding between THIS device's PRIMARY identity key
+ * and the account that key authenticates as.
+ *
+ * An identity-bound client (Commons, the identity vault) must always act as the
+ * owner of the local signing key — permanently. The `DeviceSession` it shares
+ * with every other Oxy app on the same device tracks a MUTABLE `activeAccountId`
+ * that any sibling app can switch; following it silently changes both the user
+ * such a client renders and the bearer it sends. The pin is the client-side
+ * record that breaks that coupling: `{ publicKey, accountId }`, written when an
+ * identity-mode session is established (the only moment both facts are known
+ * first-hand), read on every boot, and reconciled against the live
+ * `KeyManager.getPublicKey()` before it is trusted (see
+ * `resolveIdentityPin` in `identitySession.ts`).
+ *
+ * It holds NO secret — a public key and an account id, both already known to the
+ * server — so it lives in the same per-origin storage as {@link PersistedAuthState}
+ * (`authStateStore.ts`) rather than the keychain, and mirrors that module's
+ * store shape: `load / save / clear`, an in-memory mirror, a read-back-verified
+ * durable write, and graceful degradation when storage is unavailable.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+
+import { logger } from '../logger';
+import type { NativeKeyValueStorage } from './authStateStore';
+
+/**
+ * The persisted identity binding.
+ *
+ * `publicKey` is the device's PRIMARY identity public key (lower-case hex, as
+ * `KeyManager` stores it) — never the cross-app shared-slot key, which may hold
+ * a different identity. `accountId` is the account the server resolved for that
+ * key when the session was established.
+ */
+export interface IdentityPin {
+  publicKey: string;
+  accountId: string;
+}
+
+/**
+ * The storage seam for {@link IdentityPin}. Async throughout so one interface
+ * fits both synchronous web `localStorage` and asynchronous native
+ * SecureStore/AsyncStorage.
+ */
+export interface IdentityPinStore {
+  load(): Promise<IdentityPin | null>;
+  /**
+   * Persist the pin and report whether it durably landed.
+   *
+   * `true` means the value is retained consistent with this store's durability
+   * guarantee (a durable backing whose read-back matched, or a degraded/in-memory
+   * store that held it in memory). `false` means a DURABLE backing was expected
+   * but the write did not land — the in-memory mirror keeps this process pinned,
+   * but the next cold boot will have to re-establish the identity session (which
+   * rewrites the pin) instead of taking the fast pinned-mint lane.
+   */
+  save(pin: IdentityPin): Promise<boolean>;
+  clear(): Promise<void>;
+}
+
+/**
+ * Versioned storage key. Deliberately distinct from the `oxy.auth.*` keys so a
+ * session sign-out (which clears the auth blob) and an identity change (which
+ * clears the pin) can never take each other down.
+ */
+export const IDENTITY_PIN_STORAGE_KEY = 'oxy.identity.pin.v1';
+
+/**
+ * Structural check for a storable identity public key: `KeyManager` only ever
+ * persists secp256k1 hex — compressed (66 chars) or uncompressed (130). A stored
+ * value of any other shape is corrupt, so it is treated as "no pin" (fail
+ * closed) rather than compared. Full curve validation belongs to `KeyManager`;
+ * the pin's real authority is the reconcile against the live local key.
+ */
+function isStorablePublicKey(value: unknown): value is string {
+  if (typeof value !== 'string') {
+    return false;
+  }
+  if (value.length !== 66 && value.length !== 130) {
+    return false;
+  }
+  return /^[0-9a-fA-F]+$/.test(value);
+}
+
+/**
+ * Parse + shape-validate a stored blob. Returns `null` for anything that is not
+ * a well-formed {@link IdentityPin} (absent, malformed JSON, wrong types, junk
+ * public key) so a corrupt entry degrades to "not pinned" rather than throwing —
+ * and, critically, never yields a pin that could bind a client to the wrong
+ * account.
+ */
+function deserialize(raw: string | null): IdentityPin | null {
+  if (!raw) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return null;
+  }
+  const candidate = parsed as Record<string, unknown>;
+  if (!isStorablePublicKey(candidate.publicKey)) {
+    return null;
+  }
+  if (typeof candidate.accountId !== 'string' || candidate.accountId.length === 0) {
+    return null;
+  }
+  return {
+    publicKey: candidate.publicKey.toLowerCase(),
+    accountId: candidate.accountId,
+  };
+}
+
+/**
+ * Serialize a pin, or `null` when the caller handed over a value that would not
+ * survive {@link deserialize} — writing it would produce an entry that silently
+ * reads back as "not pinned".
+ */
+function serialize(pin: IdentityPin): string | null {
+  if (!isStorablePublicKey(pin.publicKey) || pin.accountId.length === 0) {
+    return null;
+  }
+  return JSON.stringify({ publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId });
+}
+
+/**
+ * Whether `pin` still describes the identity currently on this device.
+ *
+ * `publicKey` comparison is case-insensitive (hex). A `null` local key is a
+ * definitive "no identity here" and therefore never a match — the caller clears
+ * the pin rather than binding to an account whose key is gone.
+ */
+export function identityPinMatches(pin: IdentityPin | null, localPublicKey: string | null): boolean {
+  if (!pin || !localPublicKey) {
+    return false;
+  }
+  return pin.publicKey.toLowerCase() === localPublicKey.toLowerCase();
+}
+
+/**
+ * A process-lifetime, in-memory {@link IdentityPinStore}. Used directly for
+ * tests/SSR and as the degraded fallback of the web store.
+ */
+export function createMemoryIdentityPinStore(): IdentityPinStore {
+  let current: IdentityPin | null = null;
+  return {
+    load: async () => current,
+    save: async (pin) => {
+      if (!serialize(pin)) {
+        return false;
+      }
+      // Memory IS this store's durability backing — the write always lands.
+      current = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+      return true;
+    },
+    clear: async () => {
+      current = null;
+    },
+  };
+}
+
+/**
+ * Read the ambient `localStorage`, tolerating the case where merely ACCESSING
+ * `window.localStorage` throws (sandboxed iframe `SecurityError`). Returns
+ * `null` when storage is unavailable.
+ */
+function safeGetLocalStorage(): Storage | null {
+  try {
+    if (typeof globalThis === 'undefined') {
+      return null;
+    }
+    const store = (globalThis as { localStorage?: Storage }).localStorage;
+    return store ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A `localStorage`-backed {@link IdentityPinStore}. Degrades to an in-memory
+ * store when `localStorage` is unreachable, and keeps an in-memory mirror so a
+ * failed persist still pins THIS page's lifetime.
+ */
+export function createWebIdentityPinStore(): IdentityPinStore {
+  const storage = safeGetLocalStorage();
+  if (!storage) {
+    return createMemoryIdentityPinStore();
+  }
+  // `undefined` = never written this session → fall back to storage; any set
+  // value (including `null` after clear) is authoritative.
+  let sessionMirror: IdentityPin | null | undefined;
+  return {
+    load: async () => {
+      if (sessionMirror !== undefined) {
+        return sessionMirror;
+      }
+      try {
+        return deserialize(storage.getItem(IDENTITY_PIN_STORAGE_KEY));
+      } catch {
+        return null;
+      }
+    },
+    save: async (pin) => {
+      const json = serialize(pin);
+      if (!json) {
+        logger.error(
+          '[identityPin] refusing to persist a malformed identity pin',
+          undefined,
+          { component: 'identityPin' },
+        );
+        return false;
+      }
+      sessionMirror = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+      try {
+        storage.setItem(IDENTITY_PIN_STORAGE_KEY, json);
+        if (storage.getItem(IDENTITY_PIN_STORAGE_KEY) === json) {
+          return true;
+        }
+        logger.error(
+          '[identityPin] read-back mismatch after save — the identity pin did not persist; this process stays pinned via the in-memory mirror but the next boot must re-establish the identity session',
+          undefined,
+          { component: 'identityPin' },
+        );
+        return false;
+      } catch (error) {
+        logger.error(
+          '[identityPin] persist threw — the identity pin did not persist; this process stays pinned via the in-memory mirror but the next boot must re-establish the identity session',
+          error,
+          { component: 'identityPin' },
+        );
+        return false;
+      }
+    },
+    clear: async () => {
+      sessionMirror = null;
+      try {
+        storage.removeItem(IDENTITY_PIN_STORAGE_KEY);
+      } catch (error) {
+        logger.debug('[identityPin] clear failed', { component: 'identityPin' }, error);
+      }
+    },
+  };
+}
+
+/**
+ * A native {@link IdentityPinStore} over an injected async key/value store —
+ * the same seam `createNativeAuthStateStore` uses, so `@oxyhq/core` never
+ * imports `expo-secure-store`.
+ */
+export function createNativeIdentityPinStore(storage: NativeKeyValueStorage): IdentityPinStore {
+  let sessionMirror: IdentityPin | null | undefined;
+  return {
+    load: async () => {
+      if (sessionMirror !== undefined) {
+        return sessionMirror;
+      }
+      try {
+        return deserialize(await storage.getItem(IDENTITY_PIN_STORAGE_KEY));
+      } catch {
+        return null;
+      }
+    },
+    save: async (pin) => {
+      const json = serialize(pin);
+      if (!json) {
+        logger.error(
+          '[identityPin] refusing to persist a malformed identity pin',
+          undefined,
+          { component: 'identityPin' },
+        );
+        return false;
+      }
+      sessionMirror = { publicKey: pin.publicKey.toLowerCase(), accountId: pin.accountId };
+      try {
+        await storage.setItem(IDENTITY_PIN_STORAGE_KEY, json);
+        // A native write can resolve WITHOUT throwing yet not land, so a
+        // read-back is the only reliable proof.
+        if ((await storage.getItem(IDENTITY_PIN_STORAGE_KEY)) === json) {
+          return true;
+        }
+        logger.error(
+          '[identityPin] read-back mismatch after save — the identity pin did not persist; this app run stays pinned via the in-memory mirror but the next cold start must re-establish the identity session',
+          undefined,
+          { component: 'identityPin' },
+        );
+        return false;
+      } catch (error) {
+        logger.error(
+          '[identityPin] persist threw — the identity pin did not persist; this app run stays pinned via the in-memory mirror but the next cold start must re-establish the identity session',
+          error,
+          { component: 'identityPin' },
+        );
+        return false;
+      }
+    },
+    clear: async () => {
+      sessionMirror = null;
+      try {
+        await storage.removeItem(IDENTITY_PIN_STORAGE_KEY);
+      } catch (error) {
+        logger.debug('[identityPin] clear failed', { component: 'identityPin' }, error);
+      }
+    },
+  };
+}

package/src/session/identitySession.ts

@@ -0,0 +1,206 @@
+/**
+ * Identity-bound session — pin reconciliation + establishment.
+ *
+ * This is the SDK half of "an identity vault's authenticated user is whoever
+ * owns the local primary key". Two operations, both consumed by the cold boot
+ * (`boot/sessionColdBoot.ts`) and the re-mint lane (`session/refresh.ts`):
+ *
+ *  - {@link resolveIdentityPin} — read the persisted `{publicKey, accountId}`
+ *    pin and reconcile it against the identity currently on this device. A
+ *    definitive mismatch (the key was replaced, or is gone) CLEARS the pin; an
+ *    INDETERMINATE read (keychain locked / storage threw) leaves it untouched.
+ *  - {@link establishIdentitySession} — mint a session from the PRIMARY local
+ *    key (`getPublicKey` → `requestChallenge` → `signChallenge` →
+ *    `verifyChallenge`), persist the resulting device credential, and write the
+ *    pin. This is the identity-mode replacement for the shared-keychain lane,
+ *    which reads the CROSS-APP shared slot and may therefore hold a different
+ *    identity than this device's primary.
+ *
+ * Both take their key/signature functions from an injectable {@link IdentityBinding}
+ * (defaulting to `KeyManager` / `SignatureService`) so the lanes above stay
+ * testable without a keychain.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from './authStateStore';
+import type { SessionLoginResponse } from '../models/session';
+import { KeyManager } from '../crypto/keyManager';
+import { SignatureService, type AuthChallenge } from '../crypto/signatureService';
+import { identityPinMatches, type IdentityPin, type IdentityPinStore } from './identityPin';
+import { logger } from '../logger';
+
+/** Per-call transport overrides forwarded to the challenge/verify round-trips. */
+export interface IdentityRequestOptions {
+  retry?: boolean;
+  timeout?: number;
+}
+
+/**
+ * Everything an identity-bound client needs to resolve and re-establish its
+ * session. `@oxyhq/services` builds one of these (platform-appropriate pin
+ * store) and passes it to the cold boot and the refresh handler.
+ */
+export interface IdentityBinding {
+  /** Where the `{publicKey, accountId}` pin is persisted. */
+  pinStore: IdentityPinStore;
+  /**
+   * Reads this device's PRIMARY identity public key. Defaults to
+   * `KeyManager.getPublicKey()`. NEVER the shared-slot key.
+   */
+  readPublicKey?: () => Promise<string | null>;
+  /**
+   * Signs a server challenge with the PRIMARY local private key. Defaults to
+   * `SignatureService.signChallenge`.
+   */
+  signChallenge?: (challenge: string) => Promise<AuthChallenge>;
+  /** Optional device labels forwarded to `verifyChallenge`. */
+  deviceName?: string;
+  deviceFingerprint?: string;
+}
+
+/** The result of a successful {@link establishIdentitySession}. */
+export interface EstablishedIdentitySession {
+  session: SessionLoginResponse;
+  /** The pin as written: the local key plus the account the server resolved for it. */
+  pin: IdentityPin;
+}
+
+function readPublicKeyOf(binding: IdentityBinding): () => Promise<string | null> {
+  return binding.readPublicKey ?? (() => KeyManager.getPublicKey());
+}
+
+function signChallengeOf(binding: IdentityBinding): (challenge: string) => Promise<AuthChallenge> {
+  return binding.signChallenge ?? ((challenge) => SignatureService.signChallenge(challenge));
+}
+
+/**
+ * Read the persisted pin and reconcile it against the identity on this device.
+ *
+ * Returns the pin ONLY when the local primary public key still matches it — that
+ * is the single condition under which a client may bind its token and its
+ * rendered user to that account.
+ *
+ * Outcomes:
+ *  - no pin stored → `null` (nothing to clear).
+ *  - local key MATCHES → the pin (trusted).
+ *  - local key read succeeded and differs / is absent → the identity was
+ *    replaced or lost: CLEAR the pin and return `null`. Keeping it would pin the
+ *    client to an account it can no longer prove control of.
+ *  - the local key read THREW (keychain locked, storage unavailable) → return
+ *    `null` WITHOUT clearing. A read that produced no verdict is never evidence
+ *    of an identity change (the same rule `KeyManager` applies to its own
+ *    transient errors); the caller falls through to the identity sign-in lane,
+ *    which fails closed on a locked keychain rather than adopting a foreign
+ *    account.
+ */
+export async function resolveIdentityPin(binding: IdentityBinding): Promise<IdentityPin | null> {
+  const pin = await binding.pinStore.load();
+  if (!pin) {
+    return null;
+  }
+
+  let localPublicKey: string | null;
+  try {
+    localPublicKey = await readPublicKeyOf(binding)();
+  } catch (error) {
+    logger.debug(
+      'Identity key read did not produce a verdict — keeping the pin untouched',
+      { component: 'identitySession', method: 'resolveIdentityPin' },
+      error,
+    );
+    return null;
+  }
+
+  if (identityPinMatches(pin, localPublicKey)) {
+    return pin;
+  }
+
+  logger.warn(
+    'Identity pin no longer matches the device identity key — clearing it (the identity was replaced or removed)',
+    { component: 'identitySession', method: 'resolveIdentityPin' },
+  );
+  await binding.pinStore.clear();
+  return null;
+}
+
+/**
+ * Establish a session for the device's PRIMARY identity key and pin it.
+ *
+ * `requestChallenge` → `signChallenge` → `verifyChallenge`; `verifyChallenge`
+ * plants the access token itself. The server resolves the account from the
+ * VERIFIED SIGNER, so the returned session is identity-authoritative — it
+ * ignores the device's `activeAccountId` entirely.
+ *
+ * Side effects on success: the durable device credential is persisted (so the
+ * next boot can take the fast pinned-mint lane) and the pin is written.
+ *
+ * Returns `null` — never throws — for the two "nothing to do" cases: no local
+ * identity (including every web caller, where `KeyManager` has no key), and a
+ * verify that produced no access token. Network/crypto failures propagate so the
+ * caller can classify them.
+ */
+export async function establishIdentitySession(args: {
+  oxy: OxyServices;
+  store: AuthStateStore;
+  binding: IdentityBinding;
+  requestOptions?: IdentityRequestOptions;
+}): Promise<EstablishedIdentitySession | null> {
+  const { oxy, store, binding, requestOptions } = args;
+
+  const publicKey = await readPublicKeyOf(binding)();
+  if (!publicKey) {
+    return null;
+  }
+
+  const { challenge } = await oxy.requestChallenge(publicKey, requestOptions);
+  const signed = await signChallengeOf(binding)(challenge);
+  if (signed.publicKey.toLowerCase() !== publicKey.toLowerCase()) {
+    // The signer disagrees with the key we resolved a challenge for — the
+    // identity changed mid-flight, or a custom signer was misconfigured. Refuse:
+    // verifying under a different key would bind this client to another account.
+    throw new Error('Identity sign-in aborted: the signing key does not match the device identity key');
+  }
+
+  // `signed.challenge` carries the SIGNATURE (mirrors `signChallengeWithSharedKey`).
+  const session = await oxy.verifyChallenge(
+    signed.publicKey,
+    challenge,
+    signed.challenge,
+    signed.timestamp,
+    binding.deviceName,
+    binding.deviceFingerprint,
+    requestOptions,
+  );
+  if (!session?.accessToken) {
+    return null;
+  }
+
+  // Persist the rotating device credential so later boots re-mint through the
+  // fast `POST /session/device/token` lane instead of re-signing a challenge.
+  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,
+    });
+  }
+
+  const pin: IdentityPin = { publicKey: publicKey.toLowerCase(), accountId: session.user.id };
+  // A failed pin persist is NOT fatal: this process is already pinned in memory,
+  // and a later boot without a pin skips the (unpinned) mint lane and re-runs
+  // this exact lane, which rewrites it. Never fail an established session on it.
+  const pinned = await binding.pinStore.save(pin);
+  if (!pinned) {
+    logger.warn(
+      'Identity session established but the pin did not durably persist — the next cold start will re-establish it',
+      { component: 'identitySession', method: 'establishIdentitySession' },
+    );
+  }
+
+  return { session, pin };
+}

package/src/session/projectSessionState.ts

@@ -12,8 +12,30 @@ import type { User } from '../models/interfaces';
  * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
  * from the result before calling `deviceStateToClientSessions` /
  * `activeUserOf`.
+ *
+ * Each projection takes an OPTIONAL `pinnedAccountId`. Omit it (or pass `null`)
+ * and the projection resolves the device's `activeAccountId` exactly as before.
+ * Pass it — an IDENTITY-BOUND client, whose user is fixed by the local identity
+ * key — and the projection resolves THAT account instead, so an account switch
+ * made by another app on the same device changes `state` but never the user this
+ * client renders.
  */
 
+/**
+ * The account a projection should resolve: the pin when one is supplied and
+ * non-empty, else the device's active account. An empty-string pin is treated as
+ * "not pinned" rather than as an account that can never match.
+ */
+function boundAccountIdOf(
+  state: DeviceSessionState,
+  pinnedAccountId?: string | null,
+): string | null {
+  if (typeof pinnedAccountId === 'string' && pinnedAccountId.length > 0) {
+    return pinnedAccountId;
+  }
+  return state.activeAccountId;
+}
+
 /**
  * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
  *
@@ -25,12 +47,18 @@ import type { User } from '../models/interfaces';
  * though `ClientSession` only stores `userId` — a session is still
  * projected for an account whose id is absent from `usersById` (no
  * placeholder user is fabricated).
+ *
+ * `isCurrent` marks the PINNED account when one is supplied, so it can never
+ * disagree with {@link activeSessionIdOf} / {@link activeUserOf} for the same
+ * pin.
  */
 export function deviceStateToClientSessions(
   state: DeviceSessionState,
   usersById: Map<string, User>,
+  pinnedAccountId?: string | null,
 ): ClientSession[] {
   const provisionalTimestamp = new Date(state.updatedAt).toISOString();
+  const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
   return state.accounts.map((account) => ({
     sessionId: account.sessionId,
     deviceId: state.deviceId,
@@ -38,37 +66,57 @@ export function deviceStateToClientSessions(
     expiresAt: provisionalTimestamp,
     lastActive: provisionalTimestamp,
     userId: account.accountId,
-    isCurrent: account.accountId === state.activeAccountId,
+    isCurrent: account.accountId === boundAccountId,
     authuser: account.authuser,
   }));
 }
 
 /**
- * The active account's `sessionId`, or `null` when there is no state or no
- * active account is set.
+ * The bound account's `sessionId`, or `null` when there is no state, no bound
+ * account, or that account has no session on this device.
+ *
+ * A pinned account that is ABSENT from `state.accounts` yields `null` — the
+ * honest signal that this device no longer carries a session for the pinned
+ * identity, which the caller answers by re-establishing the identity session
+ * (never by adopting the device's active account).
  */
-export function activeSessionIdOf(state: DeviceSessionState | null): string | null {
-  if (state === null || state.activeAccountId === null) {
+export function activeSessionIdOf(
+  state: DeviceSessionState | null,
+  pinnedAccountId?: string | null,
+): string | null {
+  if (state === null) {
+    return null;
+  }
+  const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
+  if (boundAccountId === null) {
     return null;
   }
-  const activeAccountId = state.activeAccountId;
-  const activeAccount = state.accounts.find((account) => account.accountId === activeAccountId);
-  return activeAccount?.sessionId ?? null;
+  const boundAccount = state.accounts.find((account) => account.accountId === boundAccountId);
+  return boundAccount?.sessionId ?? null;
 }
 
 /**
- * The active account's `User`, resolved from `usersById`. `null` when there
- * is no state, no active account is set, or the active account id is absent
- * from `usersById`.
+ * The bound account's `User`, resolved from `usersById`. `null` when there is no
+ * state, no bound account, or the bound account id is absent from `usersById`.
+ *
+ * A pinned user is resolved from `usersById` alone — deliberately NOT gated on
+ * device membership — so a transient device-state gap cannot flicker the
+ * identity vault's rendered user. Whether the pinned session still exists on the
+ * device is answered by {@link activeSessionIdOf}.
  */
 export function activeUserOf(
   state: DeviceSessionState | null,
   usersById: Map<string, User>,
+  pinnedAccountId?: string | null,
 ): User | null {
-  if (state === null || state.activeAccountId === null) {
+  if (state === null) {
+    return null;
+  }
+  const boundAccountId = boundAccountIdOf(state, pinnedAccountId);
+  if (boundAccountId === null) {
     return null;
   }
-  return usersById.get(state.activeAccountId) ?? null;
+  return usersById.get(boundAccountId) ?? null;
 }
 
 /**