@oxyhq/core 20.1.0 → 21.0.0

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

@@ -0,0 +1,223 @@
+/**
+ * `deviceSwitcherRows` — the switcher's render model.
+ *
+ * Pure, so it is tested without a render. The cases that matter are the ones
+ * where a plausible shortcut and the correct answer disagree: naming a row by
+ * recomposing a name the server deliberately did not compose, marking a row
+ * active by comparing account ids on a device where two people reach one
+ * account, and deciding switchability from anything other than `available`.
+ */
+
+import type { DeviceDirectory } from '@oxyhq/contracts';
+import { projectDevicePrincipals } from '../deviceDirectory';
+import { buildSwitcherRows, showsPrincipalHeaders } from '../deviceSwitcherRows';
+
+const avatarUrl = (avatar: string | null | undefined): string | undefined =>
+  avatar ? `https://cdn/${avatar}` : undefined;
+
+/** Nate and Alice, both able to act as `org`. Nate is enumerated first. */
+function sharedDirectory(activeContextId: string | null): DeviceDirectory {
+  return {
+    deviceId: 'device-1',
+    revision: 4,
+    activeContextId,
+    updatedAt: 1_720_000_000_000,
+    principals: [
+      {
+        id: 'p-nate',
+        userId: 'nate',
+        authuser: 0,
+        user: {
+          id: 'nate',
+          username: 'nate',
+          name: { displayName: 'Nate I.' },
+          avatar: 'av-nate',
+          color: 'purple',
+        },
+        contexts: [
+          {
+            id: 'ctx-nate',
+            accountId: 'nate',
+            kind: 'personal',
+            relationship: 'self',
+            account: {
+              id: 'nate',
+              username: 'nate',
+              name: { displayName: 'Nate I.' },
+              avatar: 'av-nate',
+              color: 'purple',
+            },
+            onDevice: true,
+            available: true,
+            active: activeContextId === 'ctx-nate',
+            lastUsedAt: null,
+          },
+          {
+            id: 'ctx-nate-org',
+            accountId: 'org',
+            kind: 'organization',
+            relationship: 'owner',
+            account: { id: 'org', username: 'oxy', avatar: null, color: 'amber' },
+            onDevice: true,
+            available: true,
+            active: activeContextId === 'ctx-nate-org',
+            lastUsedAt: null,
+          },
+        ],
+      },
+      {
+        id: 'p-alice',
+        userId: 'alice',
+        authuser: 1,
+        user: { id: 'alice', username: 'alice' },
+        contexts: [
+          {
+            id: 'ctx-alice-org',
+            accountId: 'org',
+            kind: 'organization',
+            relationship: 'member',
+            account: { id: 'org', username: 'oxy', avatar: null, color: 'amber' },
+            // A live delegated session under a principal whose own session died:
+            // on the device, and still not activatable.
+            onDevice: true,
+            available: false,
+            active: activeContextId === 'ctx-alice-org',
+            lastUsedAt: null,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+const rowsFor = (directory: DeviceDirectory, activeContextId: string | null) =>
+  buildSwitcherRows(projectDevicePrincipals(directory), activeContextId, avatarUrl, 'en-US');
+
+describe('buildSwitcherRows', () => {
+  it('renders the same account under both people, as two rows with two ids', () => {
+    const rows = rowsFor(sharedDirectory('ctx-nate'), 'ctx-nate');
+
+    const orgRows = rows.flatMap((row) => row.contexts.filter((c) => c.accountId === 'org'));
+    expect(orgRows.map((c) => c.contextId)).toEqual(['ctx-nate-org', 'ctx-alice-org']);
+    expect(rows.map((row) => row.principalId)).toEqual(['p-nate', 'p-alice']);
+  });
+
+  it('marks active by CONTEXT id, so one of two routes to an account lights up', () => {
+    const rows = rowsFor(sharedDirectory('ctx-nate-org'), 'ctx-nate-org');
+
+    const orgRows = rows.flatMap((row) => row.contexts.filter((c) => c.accountId === 'org'));
+    // Comparing on `accountId` would light BOTH of these, i.e. claim the device
+    // is signed in as one account through two different people at once.
+    expect(orgRows.map((c) => c.isActive)).toEqual([true, false]);
+  });
+
+  it('takes switchability from `available` alone', () => {
+    const rows = rowsFor(sharedDirectory('ctx-nate'), 'ctx-nate');
+
+    const alice = rows[1].contexts[0];
+    expect(alice.canActivate).toBe(false);
+    // `available || onDevice` would offer this row: the delegated session is
+    // alive, so `onDevice` is true, and the server still answers 403 because the
+    // principal's own session is gone.
+    const nateOrg = rows[0].contexts[1];
+    expect(nateOrg.canActivate).toBe(true);
+  });
+
+  it('names a row by displayName, then handle — never a recomposed name', () => {
+    const rows = rowsFor(sharedDirectory('ctx-nate'), 'ctx-nate');
+
+    expect(rows[0].displayName).toBe('Nate I.');
+    // `org` has no `displayName`: the handle, not a synthesized one.
+    expect(rows[0].contexts[1].displayName).toBe('oxy');
+    expect(rows[0].contexts[1].handle).toBe('oxy');
+  });
+
+  it('resolves avatar file ids through the caller-supplied resolver', () => {
+    const rows = rowsFor(sharedDirectory('ctx-nate'), 'ctx-nate');
+
+    expect(rows[0].avatarUrl).toBe('https://cdn/av-nate');
+    // A null avatar resolves to nothing, never to a URL with an empty id in it.
+    expect(rows[0].contexts[1].avatarUrl).toBeUndefined();
+  });
+
+  /**
+   * Issue #961. The row model dropped the accent when the switcher moved onto
+   * the directory, so every non-active row fell back to the ambient theme accent
+   * and a device holding two people drew them identically.
+   */
+  it('carries each account’s own accent, per row', () => {
+    const rows = rowsFor(sharedDirectory('ctx-nate'), 'ctx-nate');
+
+    expect(rows[0].color).toBe('purple');
+    expect(rows[0].contexts[0].color).toBe('purple');
+    // The SUBJECT's colour, not the person's: this row is Nate acting as the
+    // organization, and it is the organization being drawn.
+    expect(rows[0].contexts[1].color).toBe('amber');
+  });
+
+  it('answers null for an account with no colour, so the renderer uses the theme accent', () => {
+    const rows = rowsFor(sharedDirectory('ctx-nate'), 'ctx-nate');
+
+    // Alice's profile carries no `color` at all — absent must reach the renderer
+    // as null, never as `undefined` it has to re-guess the meaning of.
+    expect(rows[1].color).toBeNull();
+  });
+
+  it('flags delegation by comparing the pair, not by reading the relationship word', () => {
+    const rows = rowsFor(sharedDirectory('ctx-nate'), 'ctx-nate');
+
+    expect(rows[0].contexts[0].isDelegated).toBe(false);
+    expect(rows[0].contexts[1].isDelegated).toBe(true);
+  });
+
+  it('marks the person the active context belongs to, and only them', () => {
+    expect(rowsFor(sharedDirectory('ctx-alice-org'), 'ctx-alice-org').map((r) => r.isActive)).toEqual([
+      false,
+      true,
+    ]);
+    expect(rowsFor(sharedDirectory('ctx-nate-org'), 'ctx-nate-org').map((r) => r.isActive)).toEqual([
+      true,
+      false,
+    ]);
+  });
+});
+
+describe('showsPrincipalHeaders', () => {
+  const person = (id: string, contextIds: string[]) => ({
+    principalId: id,
+    displayName: id,
+    handle: id,
+    avatarUrl: undefined,
+    color: null,
+    isActive: false,
+    contexts: contextIds.map((contextId) => ({
+      contextId,
+      accountId: contextId,
+      displayName: contextId,
+      handle: contextId,
+      avatarUrl: undefined,
+      color: null,
+      isActive: false,
+      isDelegated: false,
+      canActivate: true,
+    })),
+  });
+
+  it('stays off while every person holds exactly one account', () => {
+    // Both of these are the flat list again: every row already IS a person, so a
+    // header would print each name twice.
+    expect(showsPrincipalHeaders([person('a', ['ctx-a'])])).toBe(false);
+    expect(showsPrincipalHeaders([person('a', ['ctx-a']), person('b', ['ctx-b'])])).toBe(false);
+  });
+
+  it('turns on as soon as one person holds two', () => {
+    expect(showsPrincipalHeaders([person('a', ['ctx-a', 'ctx-a-org'])])).toBe(true);
+    expect(
+      showsPrincipalHeaders([person('a', ['ctx-a', 'ctx-a-org']), person('b', ['ctx-b'])]),
+    ).toBe(true);
+  });
+
+  it('is off for an empty device', () => {
+    expect(showsPrincipalHeaders([])).toBe(false);
+  });
+});

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

@@ -86,3 +86,20 @@ describe('projections — pinned', () => {
     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]);
+  });
+});

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

@@ -0,0 +1,300 @@
+/**
+ * The shared native DeviceSession credential — the decision rules that separate
+ * "this device already has a session" from "this device could not be read".
+ *
+ * Every case here is written against the one failure this module exists to make
+ * unreachable: a secure store that is LOCKED or BROKEN looking like a secure
+ * store that is EMPTY. The empty answer authorises a write into the slot; the
+ * failed answer must authorise nothing. Several assertions below are the only
+ * thing standing between that misreading and a live shared session being
+ * overwritten, so they are written to fail loudly rather than shrink quietly.
+ */
+import { createMemoryAuthStateStore, type AuthStateStore, type PersistedAuthState } from '../authStateStore';
+import {
+  createSharedMirroringAuthStateStore,
+  decideSharedDeviceJoin,
+  decideSharedDevicePublish,
+  normalizeSharedDeviceSessionRead,
+  publishProvenDeviceCredential,
+  readLocalDeviceCredential,
+  type SharedDeviceCredential,
+  type SharedDeviceCredentialRead,
+  type SharedDeviceCredentialStore,
+} from '../sharedDeviceCredential';
+
+const CRED: SharedDeviceCredential = { deviceId: 'dev-shared', deviceSecret: 'ds-shared' };
+const OTHER: SharedDeviceCredential = { deviceId: 'dev-other', deviceSecret: 'ds-other' };
+
+const PRESENT: SharedDeviceCredentialRead = { state: 'present', credential: CRED };
+const ABSENT: SharedDeviceCredentialRead = { state: 'absent' };
+const UNAVAILABLE: SharedDeviceCredentialRead = { state: 'unavailable', cause: new Error('keychain locked') };
+const UNSUPPORTED: SharedDeviceCredentialRead = { state: 'unsupported' };
+
+/** Every read state, so a new one cannot be added without deciding what it means. */
+const ALL_READS: SharedDeviceCredentialRead[] = [PRESENT, ABSENT, UNAVAILABLE, UNSUPPORTED];
+
+function localWith(credential: SharedDeviceCredential | null): PersistedAuthState {
+  return {
+    sessionId: 'sess-local',
+    userId: 'user-local',
+    ...(credential ? { deviceId: credential.deviceId, deviceSecret: credential.deviceSecret } : {}),
+  };
+}
+
+/** An in-memory {@link SharedDeviceCredentialStore} with scripted read behaviour. */
+function makeSharedStore(initial: SharedDeviceCredentialRead) {
+  let current = initial;
+  const publish = jest.fn(async (credential: SharedDeviceCredential) => {
+    current = { state: 'present', credential };
+    return true;
+  });
+  const clear = jest.fn(async () => {
+    current = { state: 'absent' };
+  });
+  const store: SharedDeviceCredentialStore = {
+    read: async () => current,
+    publish,
+    clear,
+  };
+  return { store, publish, clear, peek: () => current };
+}
+
+describe('readLocalDeviceCredential', () => {
+  test('requires BOTH halves of the mint credential', () => {
+    expect(readLocalDeviceCredential(null)).toBeNull();
+    expect(readLocalDeviceCredential({ sessionId: 's', userId: 'u' })).toBeNull();
+    expect(readLocalDeviceCredential({ sessionId: 's', userId: 'u', deviceId: 'd' })).toBeNull();
+    expect(readLocalDeviceCredential({ sessionId: 's', userId: 'u', deviceSecret: 'x' })).toBeNull();
+    expect(readLocalDeviceCredential(localWith(CRED))).toEqual(CRED);
+  });
+});
+
+describe('normalizeSharedDeviceSessionRead', () => {
+  test('narrows a well-formed present payload', () => {
+    expect(
+      normalizeSharedDeviceSessionRead({ status: 'present', deviceId: 'dev-x', deviceSecret: 'ds-x' }),
+    ).toEqual({ state: 'present', credential: { deviceId: 'dev-x', deviceSecret: 'ds-x' } });
+  });
+
+  test('narrows an explicit absent payload', () => {
+    expect(normalizeSharedDeviceSessionRead({ status: 'absent' })).toEqual({ state: 'absent' });
+  });
+
+  test.each([
+    ['null', null],
+    ['undefined', undefined],
+    ['a string', 'absent'],
+    ['a number', 0],
+    ['an empty object', {}],
+    ['an unknown status', { status: 'maybe' }],
+    ['present with no deviceId', { status: 'present', deviceSecret: 'ds-x' }],
+    ['present with no deviceSecret', { status: 'present', deviceId: 'dev-x' }],
+    ['present with an empty deviceSecret', { status: 'present', deviceId: 'dev-x', deviceSecret: '' }],
+    ['present with a non-string deviceId', { status: 'present', deviceId: 7, deviceSecret: 'ds-x' }],
+    ['an explicit unavailable', { status: 'unavailable', reason: 'keystore' }],
+  ])('reports %s as unavailable, never absent', (_label, raw) => {
+    const read = normalizeSharedDeviceSessionRead(raw);
+    // `unavailable` and `absent` are the pair that must never be confused: the
+    // second one authorises a write into the slot.
+    expect(read.state).toBe('unavailable');
+  });
+});
+
+describe('decideSharedDeviceJoin', () => {
+  test('adopts when the slot holds a credential and this app has none', () => {
+    expect(decideSharedDeviceJoin(localWith(null), PRESENT)).toEqual({ action: 'adopt', credential: CRED });
+    expect(decideSharedDeviceJoin(null, PRESENT)).toEqual({ action: 'adopt', credential: CRED });
+  });
+
+  test('NEVER adopts when the slot could not be read', () => {
+    // The keystore-unavailable case. Adopting nothing is right; the danger is a
+    // caller downstream reading this as "fresh device".
+    expect(decideSharedDeviceJoin(localWith(null), UNAVAILABLE)).toEqual({
+      action: 'skip',
+      reason: 'shared-unreadable',
+    });
+  });
+
+  test('reports an unsupported slot distinctly from an unreadable one', () => {
+    // Same behaviour, different diagnosis: no shared transport in this build is
+    // normal, an unreadable one is not.
+    expect(decideSharedDeviceJoin(localWith(null), UNSUPPORTED)).toEqual({
+      action: 'skip',
+      reason: 'shared-unsupported',
+    });
+  });
+
+  test('skips an empty slot', () => {
+    expect(decideSharedDeviceJoin(localWith(null), ABSENT)).toEqual({ action: 'skip', reason: 'shared-empty' });
+  });
+
+  test('never moves an app that already holds its own credential — in ANY slot state', () => {
+    // "No user is signed out merely because one app updates first" holds by
+    // construction: whatever the slot says, an app with a working credential of
+    // its own is left exactly where it is. Including when the slot holds a
+    // DIFFERENT device session.
+    for (const read of ALL_READS) {
+      expect(decideSharedDeviceJoin(localWith(OTHER), read)).toEqual({
+        action: 'skip',
+        reason: 'local-credential-present',
+      });
+    }
+    expect(ALL_READS).toHaveLength(4);
+  });
+});
+
+describe('decideSharedDevicePublish', () => {
+  test('seeds an empty slot with a proven credential', () => {
+    expect(decideSharedDevicePublish(CRED, ABSENT)).toEqual({ action: 'publish' });
+  });
+
+  test('NEVER writes over a slot it could not read', () => {
+    // The destructive direction. An unreadable slot may hold another principal's
+    // live session; writing on the strength of a failed read is how it is lost.
+    expect(decideSharedDevicePublish(CRED, UNAVAILABLE)).toEqual({
+      action: 'skip',
+      reason: 'shared-unreadable',
+    });
+  });
+
+  test('does not write when there is no slot at all', () => {
+    expect(decideSharedDevicePublish(CRED, UNSUPPORTED)).toEqual({
+      action: 'skip',
+      reason: 'shared-unsupported',
+    });
+  });
+
+  test('refreshes the secret for the SAME device session', () => {
+    const rotated = { deviceId: CRED.deviceId, deviceSecret: 'ds-rotated' };
+    expect(decideSharedDevicePublish(rotated, PRESENT)).toEqual({ action: 'publish' });
+  });
+
+  test('is a no-op when the slot already holds exactly this credential', () => {
+    expect(decideSharedDevicePublish(CRED, PRESENT)).toEqual({ action: 'skip', reason: 'already-current' });
+  });
+
+  test('leaves a slot owned by a DIFFERENT device session alone', () => {
+    // Overwriting would silently migrate every other app on this device onto our
+    // session at their next cold boot. That is a user-visible change of identity,
+    // not something a background persist decides.
+    expect(decideSharedDevicePublish(OTHER, PRESENT)).toEqual({
+      action: 'skip',
+      reason: 'owned-by-another-device',
+    });
+  });
+});
+
+describe('publishProvenDeviceCredential', () => {
+  test('writes into an empty slot', async () => {
+    const shared = makeSharedStore(ABSENT);
+    await expect(publishProvenDeviceCredential({ shared: shared.store, credential: CRED })).resolves.toEqual({
+      status: 'published',
+    });
+    expect(shared.publish).toHaveBeenCalledWith(CRED);
+    expect(shared.peek()).toEqual(PRESENT);
+  });
+
+  test('does not call publish at all when the slot is unreadable', async () => {
+    const shared = makeSharedStore(UNAVAILABLE);
+    await expect(publishProvenDeviceCredential({ shared: shared.store, credential: CRED })).resolves.toEqual({
+      status: 'skipped',
+      reason: 'shared-unreadable',
+    });
+    expect(shared.publish).not.toHaveBeenCalled();
+  });
+
+  test('reports an unverified write as a failure rather than a success', async () => {
+    const shared: SharedDeviceCredentialStore = {
+      read: async () => ABSENT,
+      // The contract is read-back-verified; a store that could not confirm the
+      // bytes landed must say so, or a fresh install joins with a phantom.
+      publish: async () => false,
+      clear: async () => undefined,
+    };
+    await expect(publishProvenDeviceCredential({ shared, credential: CRED })).resolves.toEqual({
+      status: 'publish-failed',
+    });
+  });
+});
+
+describe('createSharedMirroringAuthStateStore', () => {
+  function harness(initial: SharedDeviceCredentialRead = ABSENT) {
+    const local = createMemoryAuthStateStore();
+    const shared = makeSharedStore(initial);
+    return { local, shared, store: createSharedMirroringAuthStateStore({ local, shared: shared.store }) };
+  }
+
+  test('mirrors a saved credential into the shared slot', async () => {
+    const h = harness();
+    await expect(h.store.save(localWith(CRED))).resolves.toBe(true);
+    expect(h.shared.publish).toHaveBeenCalledWith(CRED);
+    expect(await h.local.load()).toEqual(localWith(CRED));
+  });
+
+  test('does not re-write the slot when the credential has not changed', async () => {
+    const h = harness();
+    await h.store.save(localWith(CRED));
+    await h.store.save({ ...localWith(CRED), accessToken: 'warm', expiresAt: 'later' });
+    await h.store.save({ ...localWith(CRED), accessToken: 'warmer', expiresAt: 'later-still' });
+    expect(h.shared.publish).toHaveBeenCalledTimes(1);
+  });
+
+  test('mirrors again once the credential really changes', async () => {
+    const h = harness();
+    await h.store.save(localWith(CRED));
+    await h.store.save(localWith({ deviceId: CRED.deviceId, deviceSecret: 'ds-rotated' }));
+    expect(h.shared.publish).toHaveBeenCalledTimes(2);
+  });
+
+  test('saves nothing to the slot when the state carries no credential', async () => {
+    const h = harness();
+    await h.store.save({ sessionId: 's', userId: 'u' });
+    expect(h.shared.publish).not.toHaveBeenCalled();
+  });
+
+  test('reports the LOCAL durability verdict, not the mirror outcome', async () => {
+    // The caller's contract is about the durable local write — a lane persisting
+    // a rotated secret treats `false` as fatal. A best-effort mirror must never
+    // be able to flip that answer in either direction.
+    const failingLocal: AuthStateStore = {
+      load: async () => null,
+      save: async () => false,
+      clear: async () => undefined,
+    };
+    const shared = makeSharedStore(ABSENT);
+    const store = createSharedMirroringAuthStateStore({ local: failingLocal, shared: shared.store });
+    await expect(store.save(localWith(CRED))).resolves.toBe(false);
+    expect(shared.publish).toHaveBeenCalledWith(CRED);
+  });
+
+  test('a throwing shared store cannot fail a successful local write', async () => {
+    const shared: SharedDeviceCredentialStore = {
+      read: async () => {
+        throw new Error('binder died');
+      },
+      publish: async () => true,
+      clear: async () => undefined,
+    };
+    const store = createSharedMirroringAuthStateStore({ local: createMemoryAuthStateStore(), shared });
+    await expect(store.save(localWith(CRED))).resolves.toBe(true);
+  });
+
+  test('signing out of THIS app does not clear the device-wide slot', async () => {
+    // Other apps may still be signed in on that credential, and once the server
+    // session is gone the credential mints `no_active_session` for everyone
+    // anyway. This app's sign-out is not authority over the join point.
+    const h = harness();
+    await h.store.save(localWith(CRED));
+    await h.store.clear();
+    expect(h.shared.clear).not.toHaveBeenCalled();
+    expect(h.shared.peek()).toEqual(PRESENT);
+    expect(await h.local.load()).toBeNull();
+  });
+
+  test('load is a pass-through and never adopts', async () => {
+    // Adoption is an explicit cold-boot step. A storage primitive must not be
+    // able to change who the app is signed in as.
+    const h = harness(PRESENT);
+    expect(await h.store.load()).toBeNull();
+  });
+});