@oxy.so/core 1.9.1 → 1.11.0

package/src/__tests__/inSessionRefresh.test.ts

@@ -233,6 +233,59 @@ describe('HttpService in-session refresh handler', () => {
   });
 });
 
+describe('HttpService.endSession — a sign-out outranks a refresh', () => {
+  it('plants nothing when the session ends while a re-mint is in flight', async () => {
+    const oldToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'old' });
+    const lateToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'late' });
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    http.setTokens(oldToken);
+
+    let finish!: (token: string | null) => void;
+    http.setAuthRefreshHandler(
+      () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        }),
+    );
+    const seen: Array<string | null> = [];
+    http.addTokenChangeListener((token) => seen.push(token));
+
+    const pending = http.refreshAccessToken('preflight');
+    http.endSession();
+    finish(lateToken);
+
+    await expect(pending).resolves.toBeNull();
+    expect(http.getAccessToken()).toBeNull();
+    expect(seen).toEqual([null]);
+  });
+
+  it('abandons only what was in flight: a later re-mint (another tab signed in) still runs', async () => {
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    const fresh = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'fresh' });
+    const handler = jest.fn(async () => fresh);
+    http.setAuthRefreshHandler(handler);
+
+    http.endSession();
+    expect(http.hasSessionEnded()).toBe(true);
+    await expect(http.refreshAccessToken('preflight')).resolves.toBe(fresh);
+    expect(http.getAccessToken()).toBe(fresh);
+    expect(http.hasSessionEnded()).toBe(false);
+  });
+
+  it('is what OxyServices.clearTokens does; a plain HttpService.clearTokens (a mirror) is not', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const before = oxy.httpService.getSessionEpoch();
+    oxy.clearTokens();
+    expect(oxy.httpService.getSessionEpoch()).toBe(before + 1);
+    expect(oxy.httpService.hasSessionEnded()).toBe(true);
+
+    const mirror = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    mirror.clearTokens();
+    expect(mirror.getSessionEpoch()).toBe(0);
+    expect(mirror.hasSessionEnded()).toBe(false);
+  });
+});
+
 describe('OxyServices.getAccessTokenExpiry', () => {
   it('returns the JWT exp (seconds) of the current access token', () => {
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });

package/src/__tests__/linkedClient.test.ts

@@ -208,13 +208,6 @@ describe('OxyServices.createLinkedClient', () => {
       const url = String(input);
       calls.push({ url, init });
 
-      if (url.endsWith('/csrf-token')) {
-        return new Response(JSON.stringify({ csrfToken: 'csrf_1' }), {
-          status: 200,
-          headers: { 'content-type': 'application/json' },
-        });
-      }
-
       if (url.endsWith('/api/queue/current')) {
         queueWriteAttempts += 1;
         if (queueWriteAttempts === 1) {

package/src/boot/__tests__/sessionColdBoot.identity.test.ts

@@ -104,7 +104,7 @@ function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: j
       overrides.requestChallenge
       ?? (async () => ({ challenge: 'chal-1', expiresAt: '2030-01-01T00:00:00.000Z' })),
     verifyChallenge: overrides.verifyChallenge ?? (async () => IDENTITY_SESSION),
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight(), getSessionEpoch: () => 0 },
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }

package/src/boot/__tests__/sessionColdBoot.sharedDevice.test.ts

@@ -79,7 +79,7 @@ function makeOxy(overrides: {
     setTokens,
     mintFromDeviceSecret,
     signInWithSharedIdentity,
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight(), getSessionEpoch: () => 0 },
   } as unknown as OxyServices;
   return { oxy, setTokens, mintFromDeviceSecret, signInWithSharedIdentity };
 }

package/src/boot/__tests__/sessionColdBoot.test.ts

@@ -45,7 +45,7 @@ function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: j
         throw new Error('mintFromDeviceSecret not stubbed');
       }),
     // The device-secret-mint step runs through the client's single-flight.
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight(), getSessionEpoch: () => 0 },
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }

package/src/boot/sessionColdBoot.ts

@@ -326,6 +326,9 @@ export async function runSessionColdBoot(
             { component: 'sessionColdBoot', method: 'device-secret-mint' },
           );
           return { kind: 'skip' };
+        case 'session-ended':
+          // Signed out while the boot was minting; the arm planted nothing.
+          return { kind: 'skip' };
         case 'no-secret':
           return { kind: 'skip' };
       }

package/src/crypto/__tests__/keyManager.deviceBackup.test.ts

@@ -0,0 +1,310 @@
+/**
+ * The device backup (oxy#1388): a copy of the identity held OUTSIDE the app's
+ * keystore, so a wipe of the whole shared-UID Android Keystore — which takes the
+ * primary, the backup slot, the phrase slot and the shared slot together — is
+ * undone silently instead of asking for the recovery phrase.
+ *
+ * The store is an in-memory fake of what Commons registers (Android Block
+ * Store); the keystore wipe is the secure-store mock's keystore death applied to
+ * every keychain service the SDK uses.
+ */
+
+import { setPlatformOS } from '../../utils/platform';
+import type { IdentityDeviceBackupStore } from '../deviceBackup';
+
+jest.mock(
+  'expo-secure-store',
+  () => {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { createSecureStoreMock } = require('./identityMocks');
+    return createSecureStoreMock();
+  },
+  { virtual: true },
+);
+
+jest.mock(
+  'expo-crypto',
+  () => ({
+    __esModule: true,
+    getRandomBytes: (length: number) => {
+      const out = new Uint8Array(length);
+      for (let i = 0; i < length; i++) out[i] = (Math.random() * 256) & 0xff;
+      return out;
+    },
+    digestStringAsync: async () => '0'.repeat(64),
+    CryptoDigestAlgorithm: { SHA256: 'SHA-256' },
+  }),
+  { virtual: true },
+);
+
+jest.mock('@oxy.so/protocol', () => {
+  const actual = jest.requireActual('@oxy.so/protocol');
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { createAsyncStorageMock } = require('./identityMocks');
+  const asyncStorage = createAsyncStorageMock();
+  return {
+    __esModule: true,
+    ...actual,
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadExpoCrypto: async () => require('expo-crypto'),
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadSecureStore: async () => require('expo-secure-store'),
+    loadAsyncStorage: async () => ({ default: asyncStorage }),
+    loadSharedIdentityBridge: async () => null,
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    loadNodeCrypto: async () => require('node:crypto'),
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    getRandomBytesRN: (n: number) => require('expo-crypto').getRandomBytes(n),
+  };
+});
+
+/** Every keychain service the SDK writes under: what one UID keystore wipe kills. */
+const ALL_SERVICES = ['oxy_identity', 'oxy_identity_backup', 'oxy_identity_mnemonic', 'default'];
+const PRIMARY_SVC = 'oxy_identity';
+const V2_PRIV = 'oxy_identity_private_key_v2';
+
+interface SecureStoreTestHandle {
+  __resetStore__: () => void;
+  __getRaw__: (key: string, service?: string) => string | null;
+  __simulateKeystoreDeath__: (service: string) => void;
+}
+
+interface FakeStore extends IdentityDeviceBackupStore {
+  value: string | null;
+  writes: number;
+  failReads: boolean;
+  failWrites: boolean;
+}
+
+function createFakeStore(): FakeStore {
+  const fake: FakeStore = {
+    name: 'fake',
+    value: null,
+    writes: 0,
+    failReads: false,
+    failWrites: false,
+    read: async () => {
+      if (fake.failReads) throw new Error('store unreachable');
+      return fake.value;
+    },
+    write: async (value: string) => {
+      if (fake.failWrites) throw new Error('store write failed');
+      fake.writes += 1;
+      fake.value = value;
+    },
+    clear: async () => {
+      fake.value = null;
+    },
+  };
+  return fake;
+}
+
+describe('KeyManager device backup', () => {
+  let KeyManager: typeof import('../keyManager').KeyManager;
+  let RecoveryPhraseService: typeof import('../recoveryPhrase').RecoveryPhraseService;
+  let clearIdentityMarker: typeof import('../identityMarker').clearIdentityMarker;
+  let ss: SecureStoreTestHandle;
+  let store: FakeStore;
+
+  const resetCaches = () => {
+    const km = KeyManager as unknown as Record<string, unknown>;
+    km.cachedPublicKey = null;
+    km.cachedHasIdentity = null;
+    km.cachedPublicKeyResolved = false;
+    km.cachedSharedPublicKey = null;
+    km.cachedHasSharedIdentity = null;
+  };
+
+  /** What a sibling's `pm clear` does to this app: every keystore-wrapped copy dies. */
+  const wipeUidKeystore = () => {
+    for (const service of ALL_SERVICES) {
+      ss.__simulateKeystoreDeath__(service);
+    }
+    resetCaches();
+  };
+
+  const record = () => (store.value ? JSON.parse(store.value) : null);
+
+  beforeAll(() => {
+    (globalThis as unknown as { navigator: unknown }).navigator = { product: 'ReactNative' };
+  });
+
+  beforeEach(async () => {
+    jest.resetModules();
+    setPlatformOS('android');
+    ss = (await import('expo-secure-store' as string)) as unknown as SecureStoreTestHandle;
+    ss.__resetStore__();
+    KeyManager = (await import('../keyManager')).KeyManager;
+    RecoveryPhraseService = (await import('../recoveryPhrase')).RecoveryPhraseService;
+    clearIdentityMarker = (await import('../identityMarker')).clearIdentityMarker;
+    store = createFakeStore();
+    KeyManager.setDeviceBackupStore(store);
+    resetCaches();
+  });
+
+  describe('backup', () => {
+    it('writes the identity on creation', async () => {
+      const pub = await KeyManager.createIdentity();
+      const priv = await KeyManager.getPrivateKey();
+      expect(record()).toMatchObject({ version: 1, publicKey: pub.toLowerCase(), privateKey: priv });
+      expect(record().mnemonic).toBeUndefined();
+    });
+
+    it('carries the phrase only when it derives the identity', async () => {
+      const pending = await RecoveryPhraseService.derivePendingIdentity();
+      await KeyManager.importKeyPair(pending.privateKey);
+      await KeyManager.storeRecoveryMnemonic(pending.phrase);
+      expect(record().mnemonic).toBe(pending.phrase);
+
+      const other = await RecoveryPhraseService.derivePendingIdentity();
+      await KeyManager.storeRecoveryMnemonic(other.phrase);
+      // A phrase for another identity never reaches the backup.
+      expect(record().mnemonic).toBe(pending.phrase);
+    });
+
+    it('follows a key rotation and drops the old phrase', async () => {
+      const oldId = await RecoveryPhraseService.derivePendingIdentity();
+      await KeyManager.importKeyPair(oldId.privateKey);
+      await KeyManager.storeRecoveryMnemonic(oldId.phrase);
+
+      const newId = await RecoveryPhraseService.derivePendingIdentity();
+      await KeyManager.importKeyPair(newId.privateKey, { overwrite: true });
+      expect(record()).toMatchObject({ publicKey: newId.publicKey.toLowerCase(), privateKey: newId.privateKey });
+      expect(record().mnemonic).toBeUndefined();
+
+      await KeyManager.storeRecoveryMnemonic(newId.phrase);
+      expect(record().mnemonic).toBe(newId.phrase);
+    });
+
+    it('never fails an identity write when the store fails', async () => {
+      store.failWrites = true;
+      const pub = await KeyManager.createIdentity();
+      expect((await KeyManager.getIdentityStatus()).state).toBe('present');
+      expect(pub).toBeTruthy();
+      expect(store.value).toBeNull();
+    });
+
+    it('ensureDeviceBackup backfills a missing backup and repairs a stale one', async () => {
+      store.failWrites = true;
+      const pending = await RecoveryPhraseService.derivePendingIdentity();
+      await KeyManager.importKeyPair(pending.privateKey);
+      await KeyManager.storeRecoveryMnemonic(pending.phrase);
+      expect(store.value).toBeNull();
+
+      store.failWrites = false;
+      expect(await KeyManager.ensureDeviceBackup()).toBe(true);
+      expect(record()).toMatchObject({ publicKey: pending.publicKey.toLowerCase(), mnemonic: pending.phrase });
+
+      // Current already: one read, no write.
+      const writes = store.writes;
+      expect(await KeyManager.ensureDeviceBackup()).toBe(true);
+      expect(store.writes).toBe(writes);
+
+      // Stale (e.g. a rotation whose backup write failed): rewritten.
+      const stale = await KeyManager.generateKeyPair();
+      store.value = JSON.stringify({ ...record(), privateKey: stale.privateKey, publicKey: stale.publicKey });
+      expect(await KeyManager.ensureDeviceBackup()).toBe(true);
+      expect(record().publicKey).toBe(pending.publicKey.toLowerCase());
+    });
+
+    it('ensureDeviceBackup is a no-op without a store or an identity', async () => {
+      expect(await KeyManager.ensureDeviceBackup()).toBe(false);
+      KeyManager.setDeviceBackupStore(null);
+      await KeyManager.createIdentity();
+      expect(await KeyManager.ensureDeviceBackup()).toBe(false);
+    });
+  });
+
+  describe('restore', () => {
+    it('restores silently after a wipe of the whole UID keystore, phrase included', async () => {
+      const pending = await RecoveryPhraseService.derivePendingIdentity();
+      await KeyManager.importKeyPair(pending.privateKey);
+      await KeyManager.storeRecoveryMnemonic(pending.phrase);
+
+      wipeUidKeystore();
+      expect((await KeyManager.getIdentityStatus({ bypassCache: true })).state).toBe('lost');
+
+      const result = await KeyManager.attemptIdentityRecovery();
+      expect(result).toEqual({
+        recovered: true,
+        source: 'device-backup',
+        publicKey: pending.publicKey.toLowerCase(),
+      });
+      resetCaches();
+      expect(await KeyManager.getIdentityStatus()).toEqual({
+        state: 'present',
+        publicKey: pending.publicKey.toLowerCase(),
+      });
+      expect(ss.__getRaw__(V2_PRIV, PRIMARY_SVC)).toBe(pending.privateKey);
+      expect(await KeyManager.getRecoveryMnemonic()).toBe(pending.phrase);
+    });
+
+    it('without a device backup the same wipe still ends at the phrase', async () => {
+      KeyManager.setDeviceBackupStore(null);
+      await KeyManager.createIdentity();
+      wipeUidKeystore();
+      expect(await KeyManager.attemptIdentityRecovery()).toEqual({ recovered: false, reason: 'no-sources' });
+    });
+
+    it('restores when this app lost its own data too (absent: no keys, no marker)', async () => {
+      const pub = await KeyManager.createIdentity();
+      wipeUidKeystore();
+      await clearIdentityMarker();
+      expect((await KeyManager.getIdentityStatus({ bypassCache: true })).state).toBe('absent');
+
+      const result = await KeyManager.attemptIdentityRecovery();
+      expect(result).toEqual({ recovered: true, source: 'device-backup', publicKey: pub.toLowerCase() });
+      resetCaches();
+      expect((await KeyManager.getIdentityStatus()).state).toBe('present');
+    });
+
+    it('never switches to a backup that holds a different account than the marker', async () => {
+      await KeyManager.createIdentity();
+      const other = await KeyManager.generateKeyPair();
+      store.value = JSON.stringify({
+        version: 1,
+        privateKey: other.privateKey,
+        publicKey: other.publicKey,
+        updatedAt: new Date().toISOString(),
+      });
+      wipeUidKeystore();
+
+      expect(await KeyManager.attemptIdentityRecovery()).toEqual({ recovered: false, reason: 'mismatch' });
+      expect(ss.__getRaw__(V2_PRIV, PRIMARY_SVC)).toBeNull();
+    });
+
+    it('ignores a malformed or unhealthy record and an unreachable store', async () => {
+      await KeyManager.createIdentity();
+      wipeUidKeystore();
+
+      store.value = '{"version":1,"privateKey":"zz","publicKey":"00","updatedAt":"x"}';
+      expect(await KeyManager.attemptIdentityRecovery()).toEqual({ recovered: false, reason: 'no-sources' });
+
+      store.value = 'not json';
+      expect(await KeyManager.attemptIdentityRecovery()).toEqual({ recovered: false, reason: 'no-sources' });
+
+      store.failReads = true;
+      expect(await KeyManager.attemptIdentityRecovery()).toEqual({ recovered: false, reason: 'no-sources' });
+    });
+
+    it('a fresh device with no backup stays absent', async () => {
+      expect(await KeyManager.attemptIdentityRecovery()).toEqual({ recovered: false, reason: 'not-lost' });
+    });
+  });
+
+  describe('delete', () => {
+    it('every delete clears the backup, so a deleted identity never comes back', async () => {
+      await KeyManager.createIdentity();
+      expect(store.value).not.toBeNull();
+      await KeyManager.deleteIdentity(true, true, true);
+      expect(store.value).toBeNull();
+      expect(await KeyManager.attemptIdentityRecovery()).toEqual({ recovered: false, reason: 'not-lost' });
+    });
+
+    it('a user-confirmed, non-forced delete clears it too', async () => {
+      await KeyManager.createIdentity();
+      await KeyManager.deleteIdentity(false, false, true);
+      expect(store.value).toBeNull();
+    });
+  });
+});

package/src/crypto/deviceBackup.ts

@@ -0,0 +1,108 @@
+/**
+ * The device backup of the self-custody identity: a copy that lives OUTSIDE this
+ * app's own keystore, so a keystore wipe cannot take it along with the keys.
+ *
+ * Why it exists (OxyHQ/oxy#1388): on Android every Oxy app shares the Linux UID
+ * `so.oxy.shared`, and the Android Keystore is per UID. Clearing the storage of
+ * ANY sibling app (`pm clear`, or Settings › Apps › Storage › Clear storage)
+ * wipes the Keystore of the whole UID. Every copy the SDK keeps in
+ * expo-secure-store (primary, backup slot, phrase slot) and in the androidx
+ * encrypted prefs (the cross-app shared slot) is wrapped by a key in that
+ * Keystore, so they all die together, and until now the only way back was the
+ * recovery phrase.
+ *
+ * `@oxy.so/core` never imports a native module, so the store is injected by the
+ * app that owns the identity ({@link KeyManager.setDeviceBackupStore}). Commons
+ * registers Android Block Store; every other app registers nothing, which keeps
+ * every code path below a no-op for them. The design and the threat model are in
+ * `docs/identity/device-backup.md`.
+ */
+
+/**
+ * Where the device backup is kept. Implementations must hold the value outside
+ * the calling app's keystore (that is the whole point) and must never send it
+ * anywhere Oxy can read it.
+ *
+ * `read` resolves `null` when nothing is stored AND when the store cannot be
+ * reached (no Google Play services, an old binary without the native module):
+ * the caller treats both as "no device backup" and falls back to the phrase.
+ */
+export interface IdentityDeviceBackupStore {
+  /** Short name for logs, e.g. `android-block-store`. Never contains secrets. */
+  readonly name: string;
+  read(): Promise<string | null>;
+  write(value: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+/** The record format. Bump {@link DEVICE_BACKUP_VERSION} on a breaking change. */
+export const DEVICE_BACKUP_VERSION = 1;
+
+export interface DeviceBackupRecord {
+  version: typeof DEVICE_BACKUP_VERSION;
+  /** Canonical lowercase 64-hex secp256k1 private key. */
+  privateKey: string;
+  /** Canonical lowercase public key. */
+  publicKey: string;
+  /**
+   * The BIP-39 phrase, present only when it was verified to derive
+   * {@link publicKey}. Carried so a restored identity can still reveal its
+   * phrase in Settings and create the phrase-keyed Oxy backup; the phrase is
+   * never more powerful than the private key already in the record.
+   */
+  mnemonic?: string;
+  /** ISO-8601 time of the last write. */
+  updatedAt: string;
+}
+
+export function serializeDeviceBackup(record: DeviceBackupRecord): string {
+  const out: DeviceBackupRecord = {
+    version: DEVICE_BACKUP_VERSION,
+    privateKey: record.privateKey,
+    publicKey: record.publicKey,
+    updatedAt: record.updatedAt,
+  };
+  if (record.mnemonic) {
+    out.mnemonic = record.mnemonic;
+  }
+  return JSON.stringify(out);
+}
+
+/**
+ * Parse a stored record, or `null` for anything that is not a well-formed
+ * version-1 record. Checks SHAPE only; the caller still proves the key pair is
+ * healthy (well-formed, public derives from private) before trusting it.
+ */
+export function parseDeviceBackup(raw: string | null | undefined): DeviceBackupRecord | 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 (
+    candidate.version !== DEVICE_BACKUP_VERSION ||
+    typeof candidate.privateKey !== 'string' ||
+    typeof candidate.publicKey !== 'string' ||
+    typeof candidate.updatedAt !== 'string'
+  ) {
+    return null;
+  }
+  const record: DeviceBackupRecord = {
+    version: DEVICE_BACKUP_VERSION,
+    privateKey: candidate.privateKey,
+    publicKey: candidate.publicKey,
+    updatedAt: candidate.updatedAt,
+  };
+  if (typeof candidate.mnemonic === 'string' && candidate.mnemonic.length > 0) {
+    record.mnemonic = candidate.mnemonic;
+  }
+  return record;
+}