@oxyhq/core 20.1.0 → 21.0.1

package/src/__tests__/httpServiceUnwrapEnvelope.test.ts

@@ -0,0 +1,115 @@
+/**
+ * `HttpService.unwrapResponse` envelope tests — driven through the REAL class
+ * against a stubbed `fetch`, never by calling the private method.
+ *
+ * The convenience unwrap reduces the house `{ data: <payload> }` envelope to its
+ * payload, and in doing so it discards every sibling key. That silently killed
+ * pagination on the account audit trails (`GET /accounts/:id/audit` and
+ * `GET /accounts/:id/billing/audit`, which answer `{ data, count, nextCursor }`):
+ * the caller got a bare array, `getNextPageParam` read `undefined`, and there was
+ * nothing at the call site to show that page 2 could never be requested.
+ *
+ * The three cases below are the whole contract, and each is load-bearing:
+ *
+ *  - a cursor page travels WHOLE (the regression),
+ *  - a `{ data, pagination }` page still travels whole (the behaviour that
+ *    already existed — the positive control for "pages are preserved"),
+ *  - a bare `{ data }` body still unwraps (the control proving the convenience
+ *    every other call site depends on is intact).
+ *
+ * Reverting the fix must redden the first and leave the other two green.
+ */
+
+import { HttpService } from '../HttpService';
+
+/** One entry of an audit page — only the shape matters here. */
+const ENTRY = { source: 'application_credential', eventType: 'created' } as const;
+
+function jsonBody(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('HttpService response-envelope unwrapping', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  /** Drive a real `HttpService.get` against a stubbed wire body. */
+  async function fetchWireBody<T>(body: unknown): Promise<T> {
+    globalThis.fetch = jest.fn(async () => jsonBody(body)) as unknown as typeof fetch;
+    const http = new HttpService({ baseURL: 'http://api.test.invalid' });
+    return http.get<T>('/accounts/acct-1/audit', { cache: false });
+  }
+
+  it('preserves a cursor page whole — `count` and `nextCursor` reach the caller', async () => {
+    const wire = { data: [ENTRY], count: 1, nextCursor: 'CURSOR-XYZ' };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+    // The cursor is the only thing that says where page 2 starts. Asserted on
+    // its own because `toEqual` above would also pass a body that merely
+    // happened to be an array of one entry.
+    expect(page.nextCursor).toBe('CURSOR-XYZ');
+    expect(page.count).toBe(1);
+    expect(page.data).toEqual([ENTRY]);
+  });
+
+  it('preserves the LAST cursor page, where `nextCursor` is null', async () => {
+    // The recognition is by key presence, not truthiness: if the envelope
+    // collapsed into a bare array exactly when the stream ended, every caller
+    // would crash on the final page instead of finishing.
+    const wire = { data: [ENTRY], count: 1, nextCursor: null };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+    expect(page.nextCursor).toBeNull();
+  });
+
+  it('preserves the offset-paginated `{ data, pagination }` envelope (control)', async () => {
+    const wire = {
+      data: [ENTRY],
+      pagination: { total: 1, limit: 50, offset: 0, hasMore: false },
+    };
+
+    const page = await fetchWireBody<typeof wire>(wire);
+
+    expect(page).toEqual(wire);
+  });
+
+  it('still unwraps a bare `{ data }` success envelope to its payload (control)', async () => {
+    const payload = { id: 'acct-1', name: 'Acme' };
+
+    const unwrapped = await fetchWireBody<typeof payload>({ data: payload });
+
+    expect(unwrapped).toEqual(payload);
+  });
+
+  it('still unwraps `{ data, count }`, which a dozen callers type as the bare payload', async () => {
+    // `{ data, count }` is answered by ~15 routes whose Console call sites type
+    // the result `Array<T>`. `count` is `data.length` — recoverable — so this
+    // envelope deliberately does NOT survive, and widening the rule to "any
+    // sibling key" would break every one of those callers at runtime.
+    const entries = [ENTRY, ENTRY];
+
+    const unwrapped = await fetchWireBody<typeof entries>({ data: entries, count: 2 });
+
+    expect(unwrapped).toEqual(entries);
+  });
+
+  it('passes through a body that has no `data` key at all', async () => {
+    // The cursor surfaces already in the SDK (`{ follows, nextCursor }`,
+    // `{ records, nextCursor }`) rely on this lane.
+    const wire = { follows: [{ relationshipId: 'rel-1' }], nextCursor: 'CURSOR-ABC' };
+
+    const passed = await fetchWireBody<typeof wire>(wire);
+
+    expect(passed).toEqual(wire);
+  });
+});

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

@@ -0,0 +1,325 @@
+/**
+ * `shared-device-adopt` — the cold-boot lane that lets a freshly installed
+ * official app join the device's EXISTING session with no QR and, crucially,
+ * with no access to the Commons private identity key.
+ *
+ * What is pinned here:
+ *   - a fresh install adopts the shared credential and mints;
+ *   - an app that already has a credential is never moved (upgrade order cannot
+ *     sign anyone out, in either direction);
+ *   - an UNREADABLE shared slot is not a fresh device — the lane skips and the
+ *     legacy identity-key lane still gets its turn;
+ *   - a failed adoption leaves the local store byte-for-byte as it was;
+ *   - `sessionMode: 'identity'` never runs the lane at all;
+ *   - web never runs it.
+ */
+import type { OxyServices } from '../../OxyServices';
+import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
+import type { SessionLoginResponse } from '../../models/session';
+import { runSessionColdBoot } from '../sessionColdBoot';
+import type { DeviceSecretMintOutcome } from '../../session/refresh';
+import { createMemoryAuthStateStore, type PersistedAuthState } from '../../session/authStateStore';
+import type {
+  SharedDeviceCredentialRead,
+  SharedDeviceCredentialStore,
+} from '../../session/sharedDeviceCredential';
+import { createMemoryIdentityPinStore } from '../../session/identityPin';
+import type { IdentityBinding } from '../../session/identitySession';
+
+const WEB = { isWeb: true, isNative: false };
+const NATIVE = { isWeb: false, isNative: true };
+
+const SHARED_CRED = { deviceId: 'dev-shared', deviceSecret: 'ds-shared' };
+const OWN_CRED = { deviceId: 'dev-own', deviceSecret: 'ds-own' };
+
+const MINT: DeviceTokenMintResponse = {
+  accessToken: 'access-joined',
+  expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+  nextDeviceSecret: SHARED_CRED.deviceSecret,
+  state: {
+    deviceId: SHARED_CRED.deviceId,
+    accounts: [{ accountId: 'user-shared', sessionId: 'sess-shared', authuser: 0 }],
+    activeAccountId: 'user-shared',
+    revision: 9,
+    updatedAt: 1_700_000_000_000,
+  },
+};
+
+/** A real device-secret mint single-flight matching HttpService's. */
+function makeMintSingleFlight(): (mint: () => Promise<DeviceSecretMintOutcome>) => Promise<DeviceSecretMintOutcome> {
+  let inFlight: Promise<DeviceSecretMintOutcome> | null = null;
+  return (mint) => {
+    if (!inFlight) {
+      inFlight = mint().finally(() => {
+        inFlight = null;
+      });
+    }
+    return inFlight;
+  };
+}
+
+/** A 401 error shaped like `HttpService`/`handleError` output for the given body. */
+function mint401(body: string): Error & { status: number } {
+  return Object.assign(new Error(body), { status: 401 });
+}
+
+function makeOxy(overrides: {
+  mintFromDeviceSecret?: OxyServices['mintFromDeviceSecret'];
+  signInWithSharedIdentity?: OxyServices['signInWithSharedIdentity'];
+} = {}) {
+  const setTokens = jest.fn();
+  const mintFromDeviceSecret = jest.fn(
+    overrides.mintFromDeviceSecret ?? (async () => MINT),
+  ) as unknown as OxyServices['mintFromDeviceSecret'];
+  const signInWithSharedIdentity = jest.fn(
+    overrides.signInWithSharedIdentity ?? (async () => null),
+  ) as unknown as OxyServices['signInWithSharedIdentity'];
+  const oxy = {
+    getBaseURL: () => 'https://api.oxy.so',
+    setTokens,
+    mintFromDeviceSecret,
+    signInWithSharedIdentity,
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+  } as unknown as OxyServices;
+  return { oxy, setTokens, mintFromDeviceSecret, signInWithSharedIdentity };
+}
+
+function makeSharedSlot(initial: SharedDeviceCredentialRead) {
+  let current = initial;
+  const read = jest.fn(async () => current);
+  const publish = jest.fn(async () => true);
+  const clear = jest.fn(async () => {
+    current = { state: 'absent' };
+  });
+  const store: SharedDeviceCredentialStore = { read, publish, clear };
+  return { store, read, publish, clear };
+}
+
+/** An identity binding that resolves a local key, for the identity-mode case. */
+function makeIdentityBinding(): IdentityBinding {
+  return {
+    pinStore: createMemoryIdentityPinStore(),
+    getPublicKey: async () => 'pub-identity',
+    signMessage: async () => 'sig-identity',
+  };
+}
+
+describe('cold boot — shared-device-adopt', () => {
+  test('a fresh install adopts the shared credential and mints a session', async () => {
+    const store = createMemoryAuthStateStore();
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy, mintFromDeviceSecret, setTokens } = makeOxy();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'shared-device-adopt' });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith(SHARED_CRED.deviceId, SHARED_CRED.deviceSecret);
+    expect(setTokens).toHaveBeenCalledWith(MINT.accessToken);
+    // The adopted credential is now this app's own, so the next boot takes the
+    // faster `device-secret-mint` lane.
+    expect(await store.load()).toMatchObject({
+      deviceId: SHARED_CRED.deviceId,
+      deviceSecret: SHARED_CRED.deviceSecret,
+      sessionId: 'sess-shared',
+      userId: 'user-shared',
+    });
+  });
+
+  test('the identity key is never touched when the shared credential works', async () => {
+    // The whole point of the separation: an ordinary app joins the device session
+    // without ever asking for the key that signs identity approvals.
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy, signInWithSharedIdentity } = makeOxy();
+
+    await runSessionColdBoot({
+      oxy,
+      store: createMemoryAuthStateStore(),
+      platform: NATIVE,
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+
+  test('an app that already holds its own credential is not moved onto the shared one', async () => {
+    // Upgrade order must not sign anyone out. This app's own session wins.
+    const store = createMemoryAuthStateStore();
+    await store.save({ sessionId: 'sess-own', userId: 'user-own', ...OWN_CRED });
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy, mintFromDeviceSecret } = makeOxy({
+      mintFromDeviceSecret: (async () => ({
+        ...MINT,
+        nextDeviceSecret: OWN_CRED.deviceSecret,
+        state: { ...MINT.state, deviceId: OWN_CRED.deviceId },
+      })) as unknown as OxyServices['mintFromDeviceSecret'],
+    });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'device-secret-mint' });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith(OWN_CRED.deviceId, OWN_CRED.deviceSecret);
+    expect(mintFromDeviceSecret).not.toHaveBeenCalledWith(SHARED_CRED.deviceId, SHARED_CRED.deviceSecret);
+    expect(await store.load()).toMatchObject({ deviceId: OWN_CRED.deviceId });
+  });
+
+  test('an UNREADABLE shared slot is not treated as a fresh device', async () => {
+    // A locked keystore must never authorise anything. The lane skips, the store
+    // is untouched, and the legacy identity lane still gets its turn — which is
+    // what keeps a momentarily-locked device from silently onboarding again.
+    const store = createMemoryAuthStateStore();
+    const slot = makeSharedSlot({ state: 'unavailable', cause: new Error('keystore locked') });
+    const sharedKeySession = {
+      sessionId: 'sess-legacy',
+      user: { id: 'user-legacy' },
+      accessToken: 'access-legacy',
+      expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+      deviceId: 'dev-legacy',
+      deviceSecret: 'ds-legacy',
+    } as unknown as SessionLoginResponse;
+    const { oxy, signInWithSharedIdentity } = makeOxy({
+      signInWithSharedIdentity: (async () => sharedKeySession) as unknown as OxyServices['signInWithSharedIdentity'],
+    });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(slot.publish).not.toHaveBeenCalled();
+    expect(slot.clear).not.toHaveBeenCalled();
+    expect(signInWithSharedIdentity).toHaveBeenCalled();
+    expect(outcome).toMatchObject({ kind: 'session', via: 'shared-key-signin' });
+  });
+
+  test('an empty shared slot falls through to the legacy identity lane', async () => {
+    const slot = makeSharedSlot({ state: 'absent' });
+    const { oxy, signInWithSharedIdentity } = makeOxy();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store: createMemoryAuthStateStore(),
+      platform: NATIVE,
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(signInWithSharedIdentity).toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+  });
+
+  test('a rejected shared credential is reverted locally and cleared from the slot', async () => {
+    // `invalid_device_secret` is the one positive proof that the exact shared
+    // bytes are dead. Reverting keeps this app where it was; clearing the slot is
+    // what stops a dead credential from blocking every future install.
+    const store = createMemoryAuthStateStore();
+    const before: PersistedAuthState = { sessionId: 'sess-stale', userId: 'user-stale' };
+    await store.save(before);
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: (async () => {
+        throw mint401('invalid_device_secret');
+      }) as unknown as OxyServices['mintFromDeviceSecret'],
+    });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(slot.clear).toHaveBeenCalledTimes(1);
+    expect(await store.load()).toEqual(before);
+  });
+
+  test('a transient mint failure reverts without clearing the shared slot', async () => {
+    // A network blip says nothing about the credential. Wiping the device-wide
+    // join point on an ambiguous failure is the deploy-window bug, one layer up.
+    const store = createMemoryAuthStateStore();
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy } = makeOxy({
+      mintFromDeviceSecret: (async () => {
+        throw new Error('network down');
+      }) as unknown as OxyServices['mintFromDeviceSecret'],
+    });
+
+    await runSessionColdBoot({ oxy, store, platform: NATIVE, sharedDeviceCredential: slot.store });
+
+    expect(slot.clear).not.toHaveBeenCalled();
+    expect(await store.load()).toBeNull();
+  });
+
+  test('the lane does not run on web', async () => {
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy, mintFromDeviceSecret } = makeOxy();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store: createMemoryAuthStateStore(),
+      platform: WEB,
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(slot.read).not.toHaveBeenCalled();
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+  });
+
+  test('the lane does not run when the device reports itself offline', async () => {
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy } = makeOxy();
+
+    await runSessionColdBoot({
+      oxy,
+      store: createMemoryAuthStateStore(),
+      platform: NATIVE,
+      isOffline: () => true,
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(slot.read).not.toHaveBeenCalled();
+  });
+
+  test('identity mode never reads the shared slot', async () => {
+    // The slot belongs to whichever principal signed in on this device. An
+    // identity-bound client resolves its session from the local key alone —
+    // adopting a device credential is the drift that mode exists to prevent.
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy } = makeOxy();
+
+    await runSessionColdBoot({
+      oxy,
+      store: createMemoryAuthStateStore(),
+      platform: NATIVE,
+      sessionMode: 'identity',
+      identity: makeIdentityBinding(),
+      sharedDeviceCredential: slot.store,
+    });
+
+    expect(slot.read).not.toHaveBeenCalled();
+    expect(slot.publish).not.toHaveBeenCalled();
+  });
+
+  test('omitting the slot leaves the boot chain exactly as it was', async () => {
+    const slot = makeSharedSlot({ state: 'present', credential: SHARED_CRED });
+    const { oxy, signInWithSharedIdentity } = makeOxy();
+
+    const outcome = await runSessionColdBoot({ oxy, store: createMemoryAuthStateStore(), platform: NATIVE });
+
+    expect(slot.read).not.toHaveBeenCalled();
+    expect(signInWithSharedIdentity).toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+  });
+});

package/src/boot/sessionColdBoot.ts

@@ -15,10 +15,17 @@
  *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
  *      with a single bearer-less POST to `/session/device/token` (no cookie, no
  *      navigation) and rotate the secret in-use.
- *   3. `shared-key-signin` (native, ACCOUNT mode) — re-mint from the
- *      shared-keychain identity — OR `identity-key-signin` (IDENTITY mode) —
- *      re-mint from THIS device's primary identity key.
- *   4. Signed out.
+ *   3. `shared-device-adopt` (native, ACCOUNT mode) — this app has no credential
+ *      of its own but a sibling official app already put one in the shared native
+ *      slot: adopt it and mint. This is how a newly installed official app joins
+ *      the device's existing session WITHOUT another QR and without ever touching
+ *      the Commons private key.
+ *   4. `shared-key-signin` (native, ACCOUNT mode) — the legacy lane: re-mint by
+ *      signing with the shared-keychain IDENTITY key. Retained as a recovery /
+ *      compatibility path for devices whose apps have not yet published a shared
+ *      device credential — OR `identity-key-signin` (IDENTITY mode) — re-mint
+ *      from THIS device's primary identity key.
+ *   5. Signed out.
  *
  * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
  *   - `account` (default) — the device's ACTIVE account owns the session. Every
@@ -42,8 +49,12 @@ import {
   type IdentityBinding,
 } from '../session/identitySession';
 import type { IdentityPin } from '../session/identityPin';
+import {
+  decideSharedDeviceJoin,
+  type SharedDeviceCredentialStore,
+} from '../session/sharedDeviceCredential';
 import type { OxyServices } from '../OxyServices';
-import type { AuthStateStore } from '../session/authStateStore';
+import type { AuthStateStore, PersistedAuthState } from '../session/authStateStore';
 
 /**
  * Who owns the session this boot resolves.
@@ -116,6 +127,18 @@ export interface RunSessionColdBootOptions {
    * `sessionMode: 'identity'`. Ignored in `'account'` mode.
    */
   identity?: IdentityBinding;
+  /**
+   * The cross-app native slot holding this device's shared DeviceSession
+   * credential, enabling the `shared-device-adopt` lane. Supplied by
+   * `@oxyhq/services` on native; absent on web, where each origin is its own
+   * device by design.
+   *
+   * IGNORED in `sessionMode: 'identity'`. The shared slot belongs to whichever
+   * principal signed in on this device; an identity-bound client must resolve
+   * its session from the local key alone, and adopting a device credential is
+   * exactly the drift that mode exists to prevent.
+   */
+  sharedDeviceCredential?: SharedDeviceCredentialStore;
 }
 
 /**
@@ -342,10 +365,111 @@ export async function runSessionColdBoot(
         };
       },
     });
-  } else {
-    // 3. shared-key-signin (native) — re-mint from the shared identity. Native
-    //    AND online: it is a network step (challenge + verify round-trips), so it
-    //    is gated by the same offline hint as the mint lane. `{ retry: false }`
+  } else if (opts.sharedDeviceCredential) {
+    // 3. shared-device-adopt (native, ACCOUNT mode) — join the device's existing
+    //    session through the shared native credential slot.
+    //
+    //    This is the lane that separates identity from session transport. What it
+    //    reads is an ordinary, individually revocable `deviceId` + `deviceSecret`
+    //    put there by a sibling official app — never the Commons private key. It
+    //    is what lets a freshly installed official app land signed in with no QR,
+    //    and it is why an ordinary app never needs identity-key access at all.
+    //
+    //    `decideSharedDeviceJoin` gates it: an app that already holds its own
+    //    credential is never moved, and an UNREADABLE slot is never mistaken for
+    //    an empty one. The lane therefore cannot sign anyone out, in either
+    //    upgrade order.
+    const sharedSlot = opts.sharedDeviceCredential;
+    steps.push({
+      id: 'shared-device-adopt',
+      // The adoption itself is local, but it is only worth committing alongside
+      // a mint that proves the credential — so the whole lane is online-gated
+      // like every other network step.
+      enabled: () => isNative && !isOffline(),
+      run: async () => {
+        const before = await store.load();
+        const decision = decideSharedDeviceJoin(before, await sharedSlot.read());
+        if (decision.action === 'skip') {
+          logger.debug(
+            `shared device credential not adopted (${decision.reason})`,
+            { component: 'sessionColdBoot', method: 'shared-device-adopt' },
+          );
+          return { kind: 'skip' };
+        }
+
+        // Restore the store to exactly what it held before this lane touched it.
+        // A credential we adopted and could not prove must not be left behind for
+        // the next boot's mint lane to keep retrying.
+        const revert = async (): Promise<void> => {
+          if (before) {
+            await store.save(before);
+          } else {
+            await store.clear();
+          }
+        };
+
+        const adopted: PersistedAuthState = {
+          // The mint fills both in from the device's live state; carrying the
+          // previous session's ids into a different device session would be a
+          // lie for however long the mint takes.
+          sessionId: '',
+          userId: '',
+          deviceId: decision.credential.deviceId,
+          deviceSecret: decision.credential.deviceSecret,
+        };
+        if (!(await store.save(adopted))) {
+          logger.error(
+            'adopted the shared device credential but it could not be durably persisted — reverting',
+            undefined,
+            { component: 'sessionColdBoot', method: 'shared-device-adopt' },
+          );
+          await revert();
+          return { kind: 'skip' };
+        }
+
+        const result = await refreshDeviceSecretArm({ oxy, store, pin: null });
+        if (result.status === 'ok') {
+          return {
+            kind: 'session',
+            session: {
+              sessionId: result.sessionId,
+              userId: result.userId,
+              accessToken: result.token,
+            },
+          };
+        }
+
+        if (result.status === 'invalid-secret') {
+          // The one place we hold POSITIVE proof that the exact bytes in the
+          // shared slot are dead — the server rejected them by name. Clearing it
+          // signs nobody out (a credential the server does not recognise cannot
+          // be minting for anyone) and it is what stops a dead credential from
+          // blocking every future install: a stale slot owned by a different
+          // `deviceId` is otherwise never overwritten, by design.
+          await sharedSlot.clear();
+        } else if (result.status === 'no-session') {
+          signedOutReason = 'no_session';
+        }
+        await revert();
+        return { kind: 'skip' };
+      },
+    });
+  }
+
+  if (identityBinding === null) {
+    // 4. shared-key-signin (native) — the RECOVERY / COMPATIBILITY lane: sign a
+    //    challenge with the shared-keychain IDENTITY key to re-mint a session.
+    //
+    //    It runs LAST on purpose. Using the self-custody key to obtain an ordinary
+    //    session is the over-sharing #937 sets out to end, so it is now reachable
+    //    only on a device where no sibling app has published a shared device
+    //    credential yet — an install that predates this lane, or one where the
+    //    shared slot is unreadable. Its own `store.save` below feeds the shared
+    //    slot through the mirroring store, so the FIRST boot that takes this lane
+    //    is also the last one that needs to: every later app joins by credential.
+    //
+    //    Native AND online: it is a network step (challenge + verify round-trips),
+    //    so it is gated by the same offline hint as the mint lane. `{ retry: false }`
     //    keeps the two round-trips as single attempts — the refresh scheduler /
     //    401 lane own later retries — so this step cannot multiply boot latency.
     steps.push({

package/src/i18n/locales/en-US.json

@@ -396,13 +396,22 @@
       "remoteSignOutFailed": "There was a problem signing out from the device. Please try again.",
       "noOtherDeviceSessions": "No other device sessions found to sign out from.",
       "signOutOthersSuccess": "Signed out from all other devices successfully!",
-      "signOutOthersFailed": "There was a problem signing out from other devices. Please try again."
+      "signOutOthersFailed": "There was a problem signing out from other devices. Please try again.",
+      "contextRemoved": "Removed {{account}}",
+      "contextRemoveFailed": "There was a problem removing that account. Please try again.",
+      "principalRemoved": "Signed {{name}} out of this device",
+      "principalRemoveFailed": "There was a problem signing that person out. Please try again.",
+      "activateFailed": "There was a problem switching accounts. Please try again."
     },
     "confirms": {
       "remove": "Are you sure you want to remove {{displayName}} from this device? You'll need to sign in again to access this account.",
       "logoutAll": "Are you sure you want to sign out of all accounts? This will remove all saved accounts from this device.",
       "remoteLogout": "Are you sure you want to sign out from \"{{deviceName}}\"? This will end the session on that device.",
-      "logoutOthers": "Are you sure you want to sign out from all {{count}} other device(s)? This will end sessions on all other devices except this one."
+      "logoutOthers": "Are you sure you want to sign out from all {{count}} other device(s)? This will end sessions on all other devices except this one.",
+      "removeContextTitle": "Remove this account?",
+      "removeContext": "Stop {{person}} acting as {{account}} on this device? Anyone else who reaches {{account}} here keeps their access.",
+      "removePrincipalTitle": "Sign out of this device?",
+      "removePrincipal": "Sign {{name}} out of this device? Every account they reach here is removed. Nobody else is affected."
     },
     "device": {
       "loadingTitle": "Loading device sessions...",
@@ -439,6 +448,14 @@
       "openedInCommons": "Opened in Commons",
       "confirming": "Confirming identity",
       "confirmed": "Identity confirmed"
+    },
+    "context": {
+      "unavailable": "Unavailable right now",
+      "operatedBy": "Operated by {{name}}",
+      "remove": "Remove {{account}} from {{person}}"
+    },
+    "principal": {
+      "signOut": "Sign {{name}} out of this device"
     }
   },
   "reputation": {
@@ -2119,8 +2136,13 @@
       "filesWrite": "Upload and modify your files",
       "filesDelete": "Delete your files",
       "webhooksReceive": "Receive webhooks",
-      "chatCompletions": "Use AI chat on your behalf",
-      "modelsRead": "List available AI models",
+      "inferenceInvoke": "Run AI requests on your behalf",
+      "inferenceModelsRead": "List available AI models",
+      "inferenceUsageRead": "Read its AI usage and costs",
+      "inferenceRoutingRead": "Read how AI requests are routed",
+      "inferenceRoutingWrite": "Change how AI requests are routed",
+      "inferenceProvidersRead": "Read its connected AI providers",
+      "inferenceProvidersWrite": "Manage its connected AI providers",
       "federationWrite": "Act across federated services"
     },
     "account": {