@oxy.so/core 1.0.0

package/src/session/__tests__/identityPin.test.ts

@@ -0,0 +1,131 @@
+/**
+ * The identity pin store — the durable `{publicKey, accountId}` binding an
+ * identity-bound client (the identity vault) uses instead of the device's
+ * mutable `activeAccountId`.
+ *
+ * The load-bearing property is FAIL-CLOSED validation: anything that is not a
+ * well-formed pin must read back as "not pinned", because a half-trusted pin
+ * would bind the client to the wrong account.
+ */
+import {
+  createMemoryIdentityPinStore,
+  createNativeIdentityPinStore,
+  identityPinMatches,
+  IDENTITY_PIN_STORAGE_KEY,
+  type IdentityPin,
+} from '../identityPin';
+import type { NativeKeyValueStorage } from '../authStateStore';
+
+/** A syntactically valid compressed secp256k1 public key (66 hex chars). */
+const PUBLIC_KEY = `02${'a'.repeat(64)}`;
+const PIN: IdentityPin = { publicKey: PUBLIC_KEY, accountId: 'acct-1' };
+
+/** An in-memory `NativeKeyValueStorage` with the raw map exposed for assertions. */
+function makeNativeStorage(): NativeKeyValueStorage & { raw: Map<string, string> } {
+  const raw = new Map<string, string>();
+  return {
+    raw,
+    getItem: async (key) => raw.get(key) ?? null,
+    setItem: async (key, value) => {
+      raw.set(key, value);
+    },
+    removeItem: async (key) => {
+      raw.delete(key);
+    },
+  };
+}
+
+describe('identityPinMatches', () => {
+  it('matches case-insensitively (hex)', () => {
+    expect(identityPinMatches(PIN, PUBLIC_KEY.toUpperCase())).toBe(true);
+  });
+
+  it('does NOT match a different key', () => {
+    expect(identityPinMatches(PIN, `03${'b'.repeat(64)}`)).toBe(false);
+  });
+
+  it('does NOT match when the local key is absent (a definitive "identity gone")', () => {
+    expect(identityPinMatches(PIN, null)).toBe(false);
+  });
+
+  it('does NOT match when there is no pin', () => {
+    expect(identityPinMatches(null, PUBLIC_KEY)).toBe(false);
+  });
+});
+
+describe('createMemoryIdentityPinStore', () => {
+  it('round-trips a pin and clears it', async () => {
+    const store = createMemoryIdentityPinStore();
+    expect(await store.load()).toBeNull();
+    expect(await store.save(PIN)).toBe(true);
+    expect(await store.load()).toEqual(PIN);
+    await store.clear();
+    expect(await store.load()).toBeNull();
+  });
+
+  it('normalizes the stored public key to lower case', async () => {
+    const store = createMemoryIdentityPinStore();
+    await store.save({ publicKey: PUBLIC_KEY.toUpperCase(), accountId: 'acct-1' });
+    expect((await store.load())?.publicKey).toBe(PUBLIC_KEY);
+  });
+
+  it('refuses to store a malformed pin', async () => {
+    const store = createMemoryIdentityPinStore();
+    expect(await store.save({ publicKey: 'not-a-key', accountId: 'acct-1' })).toBe(false);
+    expect(await store.save({ publicKey: PUBLIC_KEY, accountId: '' })).toBe(false);
+    expect(await store.load()).toBeNull();
+  });
+});
+
+describe('createNativeIdentityPinStore', () => {
+  it('persists under the versioned key and reads it back', async () => {
+    const storage = makeNativeStorage();
+    const store = createNativeIdentityPinStore(storage);
+
+    expect(await store.save(PIN)).toBe(true);
+    expect(storage.raw.get(IDENTITY_PIN_STORAGE_KEY)).toBe(
+      JSON.stringify({ publicKey: PUBLIC_KEY, accountId: 'acct-1' }),
+    );
+    // Fresh store instance → reads from storage, not the in-memory mirror.
+    expect(await createNativeIdentityPinStore(storage).load()).toEqual(PIN);
+  });
+
+  it.each([
+    ['malformed JSON', 'not json'],
+    ['a non-object', '"a string"'],
+    ['a junk public key', JSON.stringify({ publicKey: 'zz', accountId: 'acct-1' })],
+    ['a wrong-length public key', JSON.stringify({ publicKey: 'ab', accountId: 'acct-1' })],
+    ['an empty accountId', JSON.stringify({ publicKey: PUBLIC_KEY, accountId: '' })],
+    ['a missing accountId', JSON.stringify({ publicKey: PUBLIC_KEY })],
+  ])('reads back "not pinned" for %s', async (_label, raw) => {
+    const storage = makeNativeStorage();
+    storage.raw.set(IDENTITY_PIN_STORAGE_KEY, raw);
+    expect(await createNativeIdentityPinStore(storage).load()).toBeNull();
+  });
+
+  it('reports a failed durable write while keeping this run pinned in memory', async () => {
+    const storage = makeNativeStorage();
+    // A write that resolves WITHOUT throwing yet does not land (the Android
+    // SecureStore failure mode) — only the read-back catches it.
+    const store = createNativeIdentityPinStore({
+      ...storage,
+      setItem: async () => undefined,
+    });
+
+    expect(await store.save(PIN)).toBe(false);
+    // The in-memory mirror still pins this app run.
+    expect(await store.load()).toEqual(PIN);
+    expect(storage.raw.get(IDENTITY_PIN_STORAGE_KEY)).toBeUndefined();
+  });
+
+  it('degrades to "not pinned" when a read throws', async () => {
+    const store = createNativeIdentityPinStore({
+      getItem: async () => {
+        throw new Error('keychain locked');
+      },
+      setItem: async () => undefined,
+      removeItem: async () => undefined,
+    });
+    expect(await store.load()).toBeNull();
+  });
+});

package/src/session/__tests__/identitySession.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Identity-bound session helpers.
+ *
+ * `resolveIdentityPin` is the trust gate: a pin is only honoured while the
+ * device still holds the key that produced it. `establishIdentitySession` is the
+ * primary-key sign-in the identity vault used to run in app code, now owned by
+ * the SDK.
+ */
+import type { OxyServices } from '../../OxyServices';
+import type { SessionLoginResponse } from '../../models/session';
+import type { AuthChallenge } from '../../crypto/signatureService';
+import { createMemoryAuthStateStore } from '../authStateStore';
+import { createMemoryIdentityPinStore, type IdentityPin } from '../identityPin';
+import {
+  establishIdentitySession,
+  resolveIdentityPin,
+  type IdentityBinding,
+} from '../identitySession';
+
+const PUBLIC_KEY = `02${'a'.repeat(64)}`;
+const OTHER_PUBLIC_KEY = `03${'b'.repeat(64)}`;
+const PIN: IdentityPin = { publicKey: PUBLIC_KEY, accountId: 'acct-1' };
+
+const SESSION: SessionLoginResponse = {
+  sessionId: 'sess-identity',
+  deviceId: 'dev-identity',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  accessToken: 'access-identity',
+  deviceSecret: 'ds-identity',
+  user: { id: 'acct-1', username: 'vault', name: {} },
+};
+
+interface OxyOverrides {
+  requestChallenge?: OxyServices['requestChallenge'];
+  verifyChallenge?: OxyServices['verifyChallenge'];
+}
+
+function makeOxy(overrides: OxyOverrides = {}): OxyServices {
+  return {
+    requestChallenge:
+      overrides.requestChallenge
+      ?? (async () => ({ challenge: 'chal-1', expiresAt: '2030-01-01T00:00:00.000Z' })),
+    verifyChallenge: overrides.verifyChallenge ?? (async () => SESSION),
+  } as unknown as OxyServices;
+}
+
+function signWith(publicKey: string): (challenge: string) => Promise<AuthChallenge> {
+  return async (challenge) => ({ challenge: `sig(${challenge})`, publicKey, timestamp: 1_700_000_000_000 });
+}
+
+describe('resolveIdentityPin', () => {
+  it('returns null when nothing is pinned', async () => {
+    const binding: IdentityBinding = {
+      pinStore: createMemoryIdentityPinStore(),
+      readPublicKey: async () => PUBLIC_KEY,
+    };
+    expect(await resolveIdentityPin(binding)).toBeNull();
+  });
+
+  it('returns the pin when the local key still matches', async () => {
+    const pinStore = createMemoryIdentityPinStore();
+    await pinStore.save(PIN);
+    expect(await resolveIdentityPin({ pinStore, readPublicKey: async () => PUBLIC_KEY })).toEqual(PIN);
+  });
+
+  it('CLEARS the pin when the local key was replaced', async () => {
+    const pinStore = createMemoryIdentityPinStore();
+    await pinStore.save(PIN);
+
+    expect(await resolveIdentityPin({ pinStore, readPublicKey: async () => OTHER_PUBLIC_KEY })).toBeNull();
+    expect(await pinStore.load()).toBeNull();
+  });
+
+  it('CLEARS the pin when the identity is gone (definitive empty read)', async () => {
+    const pinStore = createMemoryIdentityPinStore();
+    await pinStore.save(PIN);
+
+    expect(await resolveIdentityPin({ pinStore, readPublicKey: async () => null })).toBeNull();
+    expect(await pinStore.load()).toBeNull();
+  });
+
+  it('KEEPS the pin when the key read threw (locked keychain is not an identity change)', async () => {
+    const pinStore = createMemoryIdentityPinStore();
+    await pinStore.save(PIN);
+
+    const resolved = await resolveIdentityPin({
+      pinStore,
+      readPublicKey: async () => {
+        throw new Error('IdentityUnavailable');
+      },
+    });
+
+    // Unresolved for this boot...
+    expect(resolved).toBeNull();
+    // ...but the binding survives for the next attempt.
+    expect(await pinStore.load()).toEqual(PIN);
+  });
+});
+
+describe('establishIdentitySession', () => {
+  it('signs with the PRIMARY key, persists the device credential, and writes the pin', async () => {
+    const store = createMemoryAuthStateStore();
+    const pinStore = createMemoryIdentityPinStore();
+    const requestChallenge = jest.fn(async () => ({
+      challenge: 'chal-1',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+    }));
+    const verifyChallenge = jest.fn(async () => SESSION);
+    const oxy = makeOxy({ requestChallenge, verifyChallenge });
+
+    const established = await establishIdentitySession({
+      oxy,
+      store,
+      binding: {
+        pinStore,
+        readPublicKey: async () => PUBLIC_KEY,
+        signChallenge: signWith(PUBLIC_KEY),
+        deviceName: 'Vault',
+      },
+      requestOptions: { retry: false },
+    });
+
+    expect(requestChallenge).toHaveBeenCalledWith(PUBLIC_KEY, { retry: false });
+    expect(verifyChallenge).toHaveBeenCalledWith(
+      PUBLIC_KEY,
+      'chal-1',
+      'sig(chal-1)',
+      1_700_000_000_000,
+      'Vault',
+      undefined,
+      { retry: false },
+    );
+    expect(established?.pin).toEqual(PIN);
+    expect(await pinStore.load()).toEqual(PIN);
+    expect(await store.load()).toMatchObject({
+      sessionId: 'sess-identity',
+      userId: 'acct-1',
+      deviceId: 'dev-identity',
+      deviceSecret: 'ds-identity',
+      accessToken: 'access-identity',
+    });
+  });
+
+  it('returns null (never throws) when the device holds no identity — the web case', async () => {
+    const pinStore = createMemoryIdentityPinStore();
+    const requestChallenge = jest.fn(async () => ({ challenge: 'c', expiresAt: 'e' }));
+
+    const established = await establishIdentitySession({
+      oxy: makeOxy({ requestChallenge }),
+      store: createMemoryAuthStateStore(),
+      binding: { pinStore, readPublicKey: async () => null },
+    });
+
+    expect(established).toBeNull();
+    expect(requestChallenge).not.toHaveBeenCalled();
+    expect(await pinStore.load()).toBeNull();
+  });
+
+  it('refuses to verify when the signer disagrees with the device identity key', async () => {
+    const pinStore = createMemoryIdentityPinStore();
+    const verifyChallenge = jest.fn(async () => SESSION);
+
+    await expect(
+      establishIdentitySession({
+        oxy: makeOxy({ verifyChallenge }),
+        store: createMemoryAuthStateStore(),
+        binding: {
+          pinStore,
+          readPublicKey: async () => PUBLIC_KEY,
+          signChallenge: signWith(OTHER_PUBLIC_KEY),
+        },
+      }),
+    ).rejects.toThrow(/signing key does not match/);
+
+    expect(verifyChallenge).not.toHaveBeenCalled();
+    expect(await pinStore.load()).toBeNull();
+  });
+
+  it('keeps the established session when the pin write fails (re-established next boot)', async () => {
+    const pinStore = {
+      load: async () => null,
+      save: async () => false,
+      clear: async () => undefined,
+    };
+
+    const established = await establishIdentitySession({
+      oxy: makeOxy(),
+      store: createMemoryAuthStateStore(),
+      binding: { pinStore, readPublicKey: async () => PUBLIC_KEY, signChallenge: signWith(PUBLIC_KEY) },
+    });
+
+    expect(established?.session.accessToken).toBe('access-identity');
+  });
+});

package/src/session/__tests__/projectSessionState.test.ts

@@ -0,0 +1,105 @@
+/**
+ * `DeviceSessionState` projections, with and without an identity pin.
+ *
+ * Without a pin the projections resolve the device's `activeAccountId` exactly
+ * as they always have. With one they resolve the PINNED account, so an account
+ * switch made by another app on the same device changes `state` but never the
+ * user an identity-bound client renders.
+ */
+import type { DeviceSessionState } from '@oxy.so/contracts';
+import type { User } from '../../models/interfaces';
+import {
+  accountIdsOf,
+  activeSessionIdOf,
+  activeUserOf,
+  deviceStateToClientSessions,
+} from '../projectSessionState';
+
+const PINNED = 'vault-user';
+const OTHER = 'other-user';
+
+const STATE: DeviceSessionState = {
+  deviceId: 'dev-1',
+  accounts: [
+    { accountId: PINNED, sessionId: 'sess-vault', authuser: 0 },
+    { accountId: OTHER, sessionId: 'sess-other', authuser: 1 },
+  ],
+  // Another app switched the device away from the pinned account.
+  activeAccountId: OTHER,
+  revision: 4,
+  updatedAt: 1_720_000_000_000,
+};
+
+const user = (id: string): User => ({ id, username: id, name: {} });
+const USERS = new Map<string, User>([
+  [PINNED, user(PINNED)],
+  [OTHER, user(OTHER)],
+]);
+
+describe('projections — unpinned (unchanged behaviour)', () => {
+  it('resolves the device active account', () => {
+    expect(activeSessionIdOf(STATE)).toBe('sess-other');
+    expect(activeUserOf(STATE, USERS)?.id).toBe(OTHER);
+    expect(deviceStateToClientSessions(STATE, USERS).map((s) => s.isCurrent)).toEqual([false, true]);
+  });
+
+  it('returns null for a null state or no active account', () => {
+    expect(activeSessionIdOf(null)).toBeNull();
+    expect(activeUserOf(null, USERS)).toBeNull();
+    expect(activeSessionIdOf({ ...STATE, activeAccountId: null })).toBeNull();
+    expect(activeUserOf({ ...STATE, activeAccountId: null }, USERS)).toBeNull();
+    expect(accountIdsOf(null)).toEqual([]);
+  });
+
+  it('treats an empty-string pin as "not pinned"', () => {
+    expect(activeSessionIdOf(STATE, '')).toBe('sess-other');
+    expect(activeUserOf(STATE, USERS, '')?.id).toBe(OTHER);
+  });
+});
+
+describe('projections — pinned', () => {
+  it('resolves the PINNED account, not the device active one', () => {
+    expect(activeSessionIdOf(STATE, PINNED)).toBe('sess-vault');
+    expect(activeUserOf(STATE, USERS, PINNED)?.id).toBe(PINNED);
+  });
+
+  it('marks the pinned account as `isCurrent` so the session list cannot disagree', () => {
+    expect(deviceStateToClientSessions(STATE, USERS, PINNED).map((s) => s.isCurrent)).toEqual([
+      true,
+      false,
+    ]);
+  });
+
+  it('reports NO session id when the pinned account is absent from the device', () => {
+    const withoutPinned: DeviceSessionState = {
+      ...STATE,
+      accounts: [{ accountId: OTHER, sessionId: 'sess-other', authuser: 0 }],
+    };
+    // The honest signal the caller answers by re-establishing the identity
+    // session — never by silently adopting `other-user`.
+    expect(activeSessionIdOf(withoutPinned, PINNED)).toBeNull();
+    // The rendered user does not flicker to the other account while that happens.
+    expect(activeUserOf(withoutPinned, USERS, PINNED)?.id).toBe(PINNED);
+  });
+
+  it('still enumerates every account id (profile hydration is unaffected)', () => {
+    expect(accountIdsOf(STATE)).toEqual([PINNED, OTHER]);
+  });
+});
+
+describe('the operator behind a delegated session', () => {
+  it('carries operatedByUserId through instead of dropping it', () => {
+    const operated: DeviceSessionState = {
+      ...STATE,
+      accounts: [
+        { accountId: PINNED, sessionId: 'sess-vault', authuser: 0 },
+        { accountId: OTHER, sessionId: 'sess-other', authuser: 1, operatedByUserId: PINNED },
+      ],
+    };
+
+    const sessions = deviceStateToClientSessions(operated, USERS);
+
+    // The delegated row names the human behind it; the direct one has nobody.
+    expect(sessions.map((session) => session.operatedByUserId)).toEqual([undefined, PINNED]);
+  });
+});