@oxyhq/core 12.10.6 → 12.11.0

package/src/mixins/__tests__/deviceTokenMintPinned.test.ts

@@ -0,0 +1,113 @@
+/**
+ * `mintFromDeviceSecret` — the pinned (identity-bound) mint.
+ *
+ * The pinned form adds `accountId` to the zero-cookie mint body so an identity
+ * vault gets ITS account's token without the device's `activeAccountId` being
+ * touched. Its one new failure mode — `401 account_not_on_device` — must be
+ * distinguishable from a bad device secret, because the remedies are opposite:
+ * a bad secret is dropped, a stale identity binding is re-established while the
+ * (healthy) secret is kept.
+ */
+import { OxyServices } from '../../OxyServices';
+import { AccountNotOnDeviceError } from '../OxyServices.deviceBoot';
+
+const MINT_RESPONSE = {
+  accessToken: 'access-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  nextDeviceSecret: 'ds-next',
+  state: {
+    deviceId: 'dev-1',
+    accounts: [{ accountId: 'vault-user', sessionId: 'sess-vault', authuser: 0 }],
+    activeAccountId: 'other-user',
+    revision: 3,
+    updatedAt: 1_700_000_000_000,
+  },
+};
+
+describe('OxyServices.mintFromDeviceSecret', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('omits accountId from the body when unpinned', async () => {
+    makeRequestSpy.mockResolvedValue(MINT_RESPONSE);
+
+    await oxy.mintFromDeviceSecret('dev-1', 'ds-1');
+
+    expect(makeRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/session/device/token',
+      { deviceId: 'dev-1', deviceSecret: 'ds-1' },
+      expect.objectContaining({ cache: false, skipAuth: true, retry: false, bypassQueue: true }),
+    );
+  });
+
+  it('sends accountId when pinned', async () => {
+    makeRequestSpy.mockResolvedValue(MINT_RESPONSE);
+
+    const mint = await oxy.mintFromDeviceSecret('dev-1', 'ds-1', { accountId: 'vault-user' });
+
+    expect(makeRequestSpy).toHaveBeenCalledWith(
+      'POST',
+      '/session/device/token',
+      { deviceId: 'dev-1', deviceSecret: 'ds-1', accountId: 'vault-user' },
+      expect.anything(),
+    );
+    // The response still reports the device's TRUE active account — a pinned
+    // mint never mutates it.
+    expect(mint.state.activeAccountId).toBe('other-user');
+  });
+
+  it('maps a 401 account_not_on_device to the typed AccountNotOnDeviceError', async () => {
+    makeRequestSpy.mockRejectedValue(
+      Object.assign(new Error('account_not_on_device'), { status: 401, code: 'UNAUTHORIZED' }),
+    );
+
+    const error = await oxy
+      .mintFromDeviceSecret('dev-1', 'ds-1', { accountId: 'vault-user' })
+      .then(
+        () => null,
+        (thrown: unknown) => thrown,
+      );
+
+    expect(error).toBeInstanceOf(AccountNotOnDeviceError);
+    expect(error).toMatchObject({ name: 'AccountNotOnDeviceError', accountId: 'vault-user', status: 401 });
+  });
+
+  it('leaves every OTHER 401 as an ordinary error (a bad secret is not an identity problem)', async () => {
+    makeRequestSpy.mockRejectedValue(
+      Object.assign(new Error('invalid_device_secret'), { status: 401, code: 'UNAUTHORIZED' }),
+    );
+
+    const error = await oxy
+      .mintFromDeviceSecret('dev-1', 'ds-1', { accountId: 'vault-user' })
+      .then(
+        () => null,
+        (thrown: unknown) => thrown,
+      );
+
+    expect(error).not.toBeInstanceOf(AccountNotOnDeviceError);
+    expect(error).toMatchObject({ message: 'invalid_device_secret', status: 401 });
+  });
+
+  it('does not classify an UNPINNED mint failure as account_not_on_device', async () => {
+    makeRequestSpy.mockRejectedValue(
+      Object.assign(new Error('account_not_on_device'), { status: 401, code: 'UNAUTHORIZED' }),
+    );
+
+    const error = await oxy.mintFromDeviceSecret('dev-1', 'ds-1').then(
+      () => null,
+      (thrown: unknown) => thrown,
+    );
+
+    expect(error).not.toBeInstanceOf(AccountNotOnDeviceError);
+  });
+});

package/src/mixins/__tests__/preSessionSkipAuth.test.ts

@@ -128,6 +128,7 @@ describe('pre-session public endpoints use skipAuth', () => {
     makeRequest.mockResolvedValueOnce({
       sessionId: 's1',
       deviceId: 'd1',
+      deviceSecret: 'ds_secret',
       accessToken: 'tok',
       user: { id: 'u1' },
     });
@@ -149,4 +150,21 @@ describe('pre-session public endpoints use skipAuth', () => {
       expect.objectContaining({ skipAuth: true }),
     );
   });
+
+  it('exchangeOAuthCode rejects a response without deviceSecret', async () => {
+    makeRequest.mockResolvedValueOnce({
+      sessionId: 's1',
+      deviceId: 'd1',
+      accessToken: 'tok',
+      user: { id: 'u1' },
+    });
+    await expect(
+      oxy.exchangeOAuthCode({
+        code: 'code-1',
+        clientId: 'oxy_dk_test',
+        redirectUri: 'https://app.example/callback',
+        codeVerifier: 'verifier',
+      }),
+    ).rejects.toThrow(/incomplete session payload/i);
+  });
 });

package/src/mixins/index.ts

@@ -25,6 +25,7 @@ import { OxyServicesUtilityMixin } from './OxyServices.utility';
 import { OxyServicesFeaturesMixin } from './OxyServices.features';
 import { OxyServicesTopicsMixin } from './OxyServices.topics';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
+import { OxyServicesNotificationsMixin } from './OxyServices.notifications';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
@@ -60,6 +61,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
@@ -126,6 +128,10 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesFeaturesMixin,
     OxyServicesTopicsMixin,
     OxyServicesContactsMixin,
+    // Push-token registration: the one SDK-owned register/unregister pair every
+    // Oxy app uses, and what lets a "Sign in with Oxy" request be delivered to a
+    // known Commons installation instead of falling back to a QR.
+    OxyServicesNotificationsMixin,
     OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServicesCivicMixin,

package/src/session/SessionClient.ts

@@ -79,6 +79,22 @@ export interface SessionClientOptions {
    * absent it falls back to `getSocketIO()`.
    */
   socketFactory?: SocketIOFactory;
+  /**
+   * The PINNED account id for an IDENTITY-BOUND client (the identity vault),
+   * or `null` for every ordinary account-mode client. Read as a function because
+   * the pin is resolved asynchronously at boot and can move when the identity
+   * session is re-established.
+   *
+   * While pinned this client tracks device state TRUTHFULLY — other apps'
+   * accounts and the device's real `activeAccountId` stay visible in `getState()`
+   * — but it NEVER re-binds its bearer to that active account: no `activeToken`
+   * is planted for a non-pinned account (from a sync response or a pushed
+   * `session_state`), the `TokenTransport` (whose entire job is converging on
+   * `activeAccountId`) is bypassed, and a push that switches the device does not
+   * trigger a token re-fetch. The pinned token's lifecycle belongs solely to the
+   * cold boot / re-mint lane, which mints it with an explicit `accountId`.
+   */
+  getPinnedAccountId?: () => string | null;
 }
 
 type StateListener = (state: DeviceSessionState | null) => void;
@@ -122,6 +138,16 @@ export class SessionClient {
     return this.state;
   }
 
+  /**
+   * The account this client's bearer is pinned to, or `null` when it follows the
+   * device's active account (the default). Resolvers are expected to be a plain
+   * synchronous read of already-resolved state (see
+   * {@link SessionClientOptions.getPinnedAccountId}).
+   */
+  private pinnedAccountId(): string | null {
+    return this.options.getPinnedAccountId?.() ?? null;
+  }
+
   subscribe(listener: StateListener): () => void {
     this.listeners.add(listener);
     return () => {
@@ -212,15 +238,28 @@ export class SessionClient {
     }
     const previousState = this.state;
     this.state = next;
+    const pinnedAccountId = this.pinnedAccountId();
     // Plant the sync-supplied active token (it is for `next.activeAccountId`)
     // now — before the notify below — so the bearer matches the new active
     // account when subscribers observe it. Guarded on difference to avoid a
     // redundant token-change notification on an unchanged token (bootstrap
-    // restate).
-    if (activeToken && next.activeAccountId !== null && activeToken !== this.host.getAccessToken()) {
+    // restate). An identity-bound client only accepts it when the active account
+    // IS its pinned account — otherwise the token belongs to somebody else's
+    // switch and must never displace the pinned bearer.
+    if (
+      activeToken &&
+      next.activeAccountId !== null &&
+      (pinnedAccountId === null || next.activeAccountId === pinnedAccountId) &&
+      activeToken !== this.host.getAccessToken()
+    ) {
       this.host.setTokens(activeToken);
     }
-    const transport = this.options.transport;
+    // The transport's entire job is converging the bearer on `activeAccountId`,
+    // which is precisely what an identity-bound client must not do: its token is
+    // minted for the pinned account by the cold boot / re-mint lane. Bypass it
+    // while pinned (also removing the mint-before-notify gate, which exists only
+    // to keep the bearer and the ACTIVE account in step).
+    const transport = pinnedAccountId === null ? this.options.transport : null;
     const activeAccountId = next.activeAccountId;
     // Mint before notifying when the bearer does not already belong to the new
     // active account: no bearer at all, an opaque bearer, OR a bearer for a
@@ -296,13 +335,16 @@ export class SessionClient {
     // socket push): `applyState` no-ops without planting, but the token still
     // needs planting. Guard on the sync's active account STILL being the current
     // active account so a stale response cannot adopt a token for an account a
-    // newer state already switched away from.
+    // newer state already switched away from — and, when pinned, on that account
+    // being the PINNED one (same rule as the applied path in `applyState`).
+    const pinnedAccountId = this.pinnedAccountId();
     if (
       !applied &&
       sync.activeToken &&
       this.state &&
       sync.state.activeAccountId !== null &&
       sync.state.activeAccountId === this.state.activeAccountId &&
+      (pinnedAccountId === null || sync.state.activeAccountId === pinnedAccountId) &&
       sync.activeToken.accessToken !== this.host.getAccessToken()
     ) {
       this.host.setTokens(sync.activeToken.accessToken);
@@ -342,12 +384,18 @@ export class SessionClient {
    * sign-in. This adds, then switches to the target so the UI lands on the
    * account the user just authenticated.
    *
+   * An identity-bound (pinned) client only ADDS: its own session is minted for
+   * the pinned account explicitly, so switching the device would gratuitously
+   * re-elect the active account under every OTHER app on this device — a
+   * mutation a pinned client must never make.
+   *
    * @param accountId - The signed-in account id (e.g. `session.user.id`). When
    *   omitted, falls back to the host's current-account ref. If neither
    *   resolves, the add still applies and no switch is performed.
    */
   async registerAndActivate(accountId?: string): Promise<void> {
     await this.addCurrentAccount();
+    if (this.pinnedAccountId() !== null) return;
     const target = accountId ?? this.host.getCurrentAccountId();
     if (target && this.state?.activeAccountId !== target) {
       await this.switchAccount(target);
@@ -449,6 +497,11 @@ export class SessionClient {
       // empty state here must not erase the durable device credential.
       const applied = this.applyState(payload, 'push');
       if (!applied) return;
+      // An identity-bound client tracks the pushed state but NEVER chases the
+      // device's active account: re-fetching here would only pull an
+      // `activeToken` for somebody else's switch, which the plant guards would
+      // then discard. Skip the round-trip entirely.
+      if (this.pinnedAccountId() !== null) return;
       // A push changed the active account on another device/tab — re-fetch state
       // to plant the access token for the newly-active account. When this tab is
       // still signed out, applyState mints via ensureActiveToken first; bootstrap

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

@@ -0,0 +1,175 @@
+/**
+ * `SessionClient` under an IDENTITY pin.
+ *
+ * The bug this guards: an account switch performed by ANOTHER app on the same
+ * device arrives as a `session_state` push (or as an `activeToken` on a sync
+ * response) and silently re-bound the identity vault's bearer to that account.
+ *
+ * The contract: device state is still tracked TRUTHFULLY (other apps' accounts
+ * and the real `activeAccountId` remain visible in `getState()`), but the bearer
+ * NEVER follows it. The pinned token's lifecycle belongs to the cold boot /
+ * re-mint lane, which mints it with an explicit `accountId`.
+ */
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import { SessionClient, type SessionClientHost, type TokenTransport } from '../SessionClient';
+
+const PINNED = 'vault-user';
+const OTHER = 'other-user';
+
+/** A minimal jwt-decode-able token whose `userId` claim is `accountId`. */
+function jwtFor(accountId: string): string {
+  const payload = Buffer.from(JSON.stringify({ userId: accountId })).toString('base64url');
+  return `h.${payload}.s`;
+}
+
+const stateWith = (revision: number, active: string): DeviceSessionState => ({
+  deviceId: 'dev-1',
+  accounts: [
+    { accountId: PINNED, sessionId: 'sess-vault', authuser: 0 },
+    { accountId: OTHER, sessionId: 'sess-other', authuser: 1 },
+  ],
+  activeAccountId: active,
+  revision,
+  updatedAt: 1_720_000_000_000,
+});
+
+function makeHost(initialToken: string | null): SessionClientHost & { planted: () => string | null } {
+  let planted = initialToken;
+  return {
+    makeRequest: jest.fn(),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => planted,
+    getDeviceCredential: () => null,
+    onTokensChanged: () => () => undefined,
+    setTokens: (token: string) => {
+      planted = token;
+    },
+    getCurrentAccountId: () => PINNED,
+    planted: () => planted,
+  };
+}
+
+/** `applyState` is protected; a tiny subclass exposes it for the unit tests. */
+class TestClient extends SessionClient {
+  public apply(raw: unknown, origin?: 'request' | 'push', activeToken?: string): boolean {
+    return this.applyState(raw, origin, activeToken);
+  }
+}
+
+describe('SessionClient — pinned bearer', () => {
+  // Node's real `BroadcastChannel` (which `postCommitPing` opens) is ref'd and
+  // would keep the Jest event loop alive forever. Feature-detect it away — the
+  // cross-tab wake has its own suite.
+  const realBroadcastChannel = (globalThis as { BroadcastChannel?: unknown }).BroadcastChannel;
+  beforeAll(() => {
+    (globalThis as { BroadcastChannel?: unknown }).BroadcastChannel = undefined;
+  });
+  afterAll(() => {
+    (globalThis as { BroadcastChannel?: unknown }).BroadcastChannel = realBroadcastChannel;
+  });
+
+  it('tracks a pushed switch in state but does NOT change the planted token', () => {
+    const host = makeHost(jwtFor(PINNED));
+    const client = new TestClient(host, { getPinnedAccountId: () => PINNED });
+
+    expect(client.apply(stateWith(1, PINNED), 'push')).toBe(true);
+    // Another app switched the device to `other-user`.
+    expect(client.apply(stateWith(2, OTHER), 'push')).toBe(true);
+
+    // The state is truthful...
+    expect(client.getState()?.activeAccountId).toBe(OTHER);
+    // ...and the bearer is untouched.
+    expect(host.planted()).toBe(jwtFor(PINNED));
+  });
+
+  it('does NOT plant a sync-supplied activeToken for a non-pinned account', () => {
+    const host = makeHost(jwtFor(PINNED));
+    const client = new TestClient(host, { getPinnedAccountId: () => PINNED });
+
+    client.apply(stateWith(3, OTHER), 'request', jwtFor(OTHER));
+
+    expect(host.planted()).toBe(jwtFor(PINNED));
+  });
+
+  it('DOES plant a sync-supplied activeToken when the active account IS the pinned one', () => {
+    const host = makeHost(null);
+    const client = new TestClient(host, { getPinnedAccountId: () => PINNED });
+
+    client.apply(stateWith(4, PINNED), 'request', jwtFor(PINNED));
+
+    expect(host.planted()).toBe(jwtFor(PINNED));
+  });
+
+  it('never invokes the TokenTransport (whose job is converging on activeAccountId)', () => {
+    const host = makeHost(jwtFor(PINNED));
+    const transport: TokenTransport = { ensureActiveToken: jest.fn().mockResolvedValue(undefined) };
+    const client = new TestClient(host, { transport, getPinnedAccountId: () => PINNED });
+
+    client.apply(stateWith(5, OTHER), 'push');
+
+    expect(transport.ensureActiveToken).not.toHaveBeenCalled();
+  });
+
+  it('notifies subscribers synchronously on a foreign switch (no mint-before-notify gate)', () => {
+    const host = makeHost(jwtFor(PINNED));
+    const transport: TokenTransport = { ensureActiveToken: jest.fn().mockResolvedValue(undefined) };
+    const client = new TestClient(host, { transport, getPinnedAccountId: () => PINNED });
+
+    const seen: Array<string | null> = [];
+    client.subscribe((state) => seen.push(state?.activeAccountId ?? null));
+
+    client.apply(stateWith(6, OTHER), 'push');
+
+    expect(seen).toEqual([OTHER]);
+  });
+
+  it('account mode is unchanged: an activeToken for the new active account IS planted', () => {
+    const host = makeHost(jwtFor(PINNED));
+    const client = new TestClient(host);
+
+    client.apply(stateWith(7, OTHER), 'request', jwtFor(OTHER));
+
+    expect(host.planted()).toBe(jwtFor(OTHER));
+  });
+
+  it('registerAndActivate only ADDS while pinned (never re-elects the device active account)', async () => {
+    const host = makeHost(jwtFor(PINNED));
+    const makeRequest = jest.fn().mockResolvedValue({
+      state: stateWith(8, OTHER),
+      activeToken: null,
+    });
+    const client = new SessionClient(
+      { ...host, makeRequest },
+      { getPinnedAccountId: () => PINNED },
+    );
+
+    await client.registerAndActivate(PINNED);
+
+    expect(makeRequest).toHaveBeenCalledTimes(1);
+    expect(makeRequest).toHaveBeenCalledWith('POST', '/session/device/add', undefined, { cache: false });
+    expect(makeRequest).not.toHaveBeenCalledWith(
+      'POST',
+      '/session/device/switch',
+      expect.anything(),
+      expect.anything(),
+    );
+  });
+
+  it('account mode is unchanged: registerAndActivate still switches to the target', async () => {
+    const host = makeHost(jwtFor(PINNED));
+    const makeRequest = jest.fn().mockResolvedValue({
+      state: stateWith(9, OTHER),
+      activeToken: null,
+    });
+    const client = new SessionClient({ ...host, makeRequest });
+
+    await client.registerAndActivate(PINNED);
+
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/session/device/switch',
+      { accountId: PINNED },
+      { cache: false },
+    );
+  });
+});