@oxyhq/core 20.1.0 → 21.0.0

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": {

package/src/i18n/locales/es-ES.json

@@ -636,13 +636,22 @@
       "remoteSignOutFailed": "Hubo un problema al cerrar sesión en el dispositivo. Inténtalo de nuevo.",
       "noOtherDeviceSessions": "No se encontraron otras sesiones de dispositivo para cerrar.",
       "signOutOthersSuccess": "¡Sesiones cerradas correctamente en los demás dispositivos!",
-      "signOutOthersFailed": "Hubo un problema al cerrar sesión en otros dispositivos. Inténtalo de nuevo."
+      "signOutOthersFailed": "Hubo un problema al cerrar sesión en otros dispositivos. Inténtalo de nuevo.",
+      "contextRemoved": "Se quitó {{account}}",
+      "contextRemoveFailed": "Hubo un problema al quitar esa cuenta. Inténtalo de nuevo.",
+      "principalRemoved": "Se cerró la sesión de {{name}} en este dispositivo",
+      "principalRemoveFailed": "Hubo un problema al cerrar esa sesión. Inténtalo de nuevo.",
+      "activateFailed": "Hubo un problema al cambiar de cuenta. Inténtalo de nuevo."
     },
     "confirms": {
       "remove": "¿Seguro que quieres eliminar a {{displayName}} de este dispositivo? Tendrás que iniciar sesión de nuevo para acceder a esta cuenta.",
       "logoutAll": "¿Seguro que quieres cerrar sesión en todas las cuentas? Esto eliminará todas las cuentas guardadas de este dispositivo.",
       "remoteLogout": "¿Seguro que quieres cerrar sesión en \"{{deviceName}}\"? Esto finalizará la sesión en ese dispositivo.",
-      "logoutOthers": "¿Seguro que quieres cerrar sesión en los otros {{count}} dispositivo(s)? Esto finalizará las sesiones en todos los demás dispositivos excepto en este."
+      "logoutOthers": "¿Seguro que quieres cerrar sesión en los otros {{count}} dispositivo(s)? Esto finalizará las sesiones en todos los demás dispositivos excepto en este.",
+      "removeContextTitle": "¿Quitar esta cuenta?",
+      "removeContext": "¿Dejar de usar {{account}} como {{person}} en este dispositivo? Quien más acceda a {{account}} aquí lo conserva.",
+      "removePrincipalTitle": "¿Cerrar sesión en este dispositivo?",
+      "removePrincipal": "¿Cerrar la sesión de {{name}} en este dispositivo? Se quitan todas las cuentas a las que llega desde aquí. No afecta a nadie más."
     },
     "device": {
       "loadingTitle": "Cargando sesiones de dispositivo...",
@@ -679,6 +688,14 @@
       "openedInCommons": "Abierto en Commons",
       "confirming": "Confirmando identidad",
       "confirmed": "Identidad confirmada"
+    },
+    "context": {
+      "unavailable": "No disponible ahora mismo",
+      "operatedBy": "Gestionada por {{name}}",
+      "remove": "Quitar {{account}} de {{person}}"
+    },
+    "principal": {
+      "signOut": "Cerrar la sesión de {{name}} en este dispositivo"
     }
   },
   "feedback": {

package/src/index.ts

@@ -49,7 +49,11 @@ export type {
     CommonsDeliveryPlatform,
     CommonsDeliveryRoute,
 } from './utils/commonsDelivery';
-export type { ServiceTokenResponse, OAuthUserInfoResponse } from './mixins/OxyServices.auth';
+export type {
+    ServiceTokenResponse,
+    OAuthUserInfoResponse,
+    OAuthTokenExchangeResult,
+} from './mixins/OxyServices.auth';
 // "Sign in with Oxy" — handoff (Workstream C)
 export type {
     CommonsSignInHandle,
@@ -680,26 +684,55 @@ export {
     accountIdsOf,
 } from './session/projectSessionState';
 
-// Unified account-list projection (THE single source of truth for the account
-// chooser: device sign-ins ∪ account graph, deduped by accountId). Pure +
-// I/O-free — the caller hydrates profiles via `getUsersByIds`. Shared by
-// `@oxyhq/services` and auth.oxy.so so the list can't diverge.
-// `isSwitchTargetAccount` is the structural half ("is this kind switchable at
-// all?"); `canSwitchIntoAccount` adds the caller's `account:act_as` permission.
-// Both are exported so surfaces that render `AccountNode`s rather than the
-// projection — the Console workspace switcher, managed-accounts rows — ask the
-// SAME questions instead of testing a kind literal.
+// Pure projections over the device DIRECTORY (`GET /session/device/directory`,
+// ADR 0002) — the read model that keeps the actor (the human who authenticated)
+// and the subject (the account being acted as) apart. The flat
+// `DeviceSessionState` collapses them into one row, so it can neither tell
+// "signed in as an org" from "a person operating that org" nor hold two people
+// reaching the same org on one device.
+// `canActivateContext` is the switchability question — `available` alone, never
+// composed with `onDevice`, which is a different fact in both directions.
+// `projectDevicePrincipals` is the switcher's shape: people, each with what
+// they may become. Grouped rather than flat because the same organization
+// reached through two people is TWO rows under two humans, which a list keyed
+// by account cannot say.
+export {
+    canActivateContext,
+    directoryDisplayName,
+    directoryHandle,
+    projectDevicePrincipals,
+    resolveActiveContext,
+    resolveDeviceContext,
+} from './session/deviceDirectory';
+export type {
+    DeviceContext,
+    DeviceContextActor,
+    DeviceContextSubject,
+    DevicePrincipalGroup,
+} from './session/deviceDirectory';
+
+// The switcher's RENDER model over that projection — names, handles and avatar
+// URLs resolved once. Shared by `@oxyhq/services`' account dialog and the
+// auth.oxy.so chooser so the two cannot drift, the same reason the flat
+// projection lived here before it.
+export { buildSwitcherRows, showsPrincipalHeaders } from './session/deviceSwitcherRows';
+export type {
+    ResolveAvatarUrl,
+    SwitcherContextRow,
+    SwitcherPrincipalRow,
+} from './session/deviceSwitcherRows';
+
+// The switch-target predicates over the account GRAPH — a list of accounts to
+// manage, not the device's list of identities to become (that is the directory
+// above). `isSwitchTargetAccount` is the structural half ("is this kind
+// switchable at all?"); `canSwitchIntoAccount` adds the caller's
+// `account:act_as` permission. Exported so the surfaces that render
+// `AccountNode`s — the Console workspace switcher, managed-accounts rows — ask
+// the SAME questions instead of testing a kind literal.
 export {
     isSwitchTargetAccount,
     canSwitchIntoAccount,
-    projectSwitchableAccounts,
-    switchableAccountIds,
-} from './session/accountProjection';
-export type {
-    SwitchableAccount,
-    SwitchableAccountUser,
-    ProjectSwitchableAccountsInput,
-} from './session/accountProjection';
+} from './session/accountSwitchTargets';
 
 // Headless controller for the unified account dialog. Framework-agnostic
 // state machine + subscribe/getSnapshot store (bind via `useSyncExternalStore`)
@@ -741,6 +774,30 @@ export type {
     NativeKeyValueStorage,
 } from './session/authStateStore';
 
+// The shared NATIVE DeviceSession credential — how several official apps on one
+// device end up on ONE `DeviceSession` and therefore one active context. It is an
+// ordinary rotatable/revocable `deviceId` + `deviceSecret`, deliberately NOT the
+// Commons private identity key: an app that only needs a session must never be
+// handed the key that signs identity approvals.
+export {
+    createSharedMirroringAuthStateStore,
+    decideSharedDeviceJoin,
+    decideSharedDevicePublish,
+    normalizeSharedDeviceSessionRead,
+    publishProvenDeviceCredential,
+    readLocalDeviceCredential,
+} from './session/sharedDeviceCredential';
+export type {
+    SharedDeviceCredential,
+    SharedDeviceCredentialRead,
+    SharedDeviceCredentialStore,
+    SharedDeviceJoinDecision,
+    SharedDeviceJoinSkipReason,
+    SharedDevicePublishDecision,
+    SharedDevicePublishOutcome,
+    SharedDevicePublishSkipReason,
+} from './session/sharedDeviceCredential';
+
 // Identity-bound sessions (the identity vault). The pin is the durable
 // `{publicKey, accountId}` binding between this device's PRIMARY identity key
 // and the account it authenticates as; it is what keeps such a client from

package/src/mixins/OxyServices.auth.ts

@@ -7,7 +7,6 @@ import type { User } from '../models/interfaces';
 import type {
   UserNameResponse,
   LoginResult,
-  LoginSessionResult,
   CommonsDenyReason,
 } from '@oxyhq/contracts';
 import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
@@ -74,6 +73,42 @@ export interface OAuthUserInfoResponse {
   picture?: string;
 }
 
+/**
+ * The session an OAuth authorization-code exchange yields.
+ *
+ * Deliberately NOT `LoginSessionResult`. That type mirrors the API's
+ * `buildSessionAuthResponse`, which every FIRST-PARTY sign-in lane emits, and it
+ * requires `deviceId` because those lanes always join the origin's DeviceSession.
+ * `POST /auth/oauth/token` is the RFC 6749 token endpoint and serves third
+ * parties, whose grant is deliberately ISOLATED: an untrusted application must be
+ * able to receive a session carrying NO DeviceSession credential at all.
+ *
+ * Both device fields are therefore optional here, and a response omitting them is
+ * a well-formed device-less grant rather than a malformed payload. What that
+ * costs the session is spelled out on `exchangeOAuthCode` below.
+ */
+export interface OAuthTokenExchangeResult {
+  sessionId: string;
+  /** ISO-8601 expiry of {@link accessToken}, derived from RFC 6749 `expires_in`. */
+  expiresAt: string;
+  accessToken?: string;
+  /**
+   * The DeviceSession this grant joined, when the server issued one. ABSENT for
+   * an isolated third-party grant — never assume a string.
+   */
+  deviceId?: string;
+  /**
+   * The zero-cookie mint credential for {@link deviceId}. Present only alongside
+   * it; absent for an isolated third-party grant.
+   */
+  deviceSecret?: string;
+  user: {
+    id: string;
+    username?: string;
+    avatar?: string;
+  };
+}
+
 // ===========================================================================
 // "Sign in with Oxy" — cross-device QR / app-to-app handoff (Workstream C)
 // ===========================================================================
@@ -1699,13 +1734,30 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * response this method used before were an Oxy invention no OAuth library
      * could interoperate with; the endpoint no longer accepts them. The method's
      * OWN signature is unchanged, so callers are unaffected.
+     *
+     * `deviceId` + `deviceSecret` are OPTIONAL and their absence is a valid
+     * outcome, not an error. A third-party grant is meant to be isolated from the
+     * browser's shared DeviceSession, so the token endpoint must be free to return
+     * no device credential at all — the guard that used to require the pair made
+     * that omission unshippable, since it turned every third-party sign-in through
+     * the SDK into a silent `exchange-failed`.
+     *
+     * The cost is real and deliberate: a DEVICE-LESS session cannot use the
+     * zero-cookie mint lane (`POST /session/device/token`), because that lane's
+     * whole proof is possession of a `deviceSecret`. Its lifetime is therefore the
+     * access token itself — nothing persists a restore credential, the cold boot's
+     * `device-secret-mint` step reports `no-secret` and skips, and the refresh
+     * scheduler has nothing to re-mint from. When the token expires the session
+     * ends LOUDLY: the 401 lane clears the tokens and the provider resolves signed
+     * out, so the app can run the OAuth flow again. It never degrades into a
+     * session that looks alive and cannot refresh.
      */
     async exchangeOAuthCode(params: {
       code: string;
       clientId: string;
       redirectUri: string;
       codeVerifier: string;
-    }): Promise<LoginSessionResult> {
+    }): Promise<OAuthTokenExchangeResult> {
       try {
         const form = new URLSearchParams({
           grant_type: 'authorization_code',
@@ -1730,7 +1782,9 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         const deviceId = typeof record.deviceId === 'string' ? record.deviceId : undefined;
         const deviceSecret = typeof record.deviceSecret === 'string' ? record.deviceSecret : undefined;
         const userRaw = record.user;
-        if (!sessionId || !deviceId || !deviceSecret || !userRaw || typeof userRaw !== 'object') {
+        // The device pair is NOT part of this guard — see the note above. What is
+        // still mandatory is what identifies the session at all.
+        if (!sessionId || !userRaw || typeof userRaw !== 'object') {
           throw new Error('auth/oauth/token returned an incomplete session payload');
         }
         const userObj = userRaw as Record<string, unknown>;
@@ -1744,12 +1798,20 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         if (accessToken) {
           this.setTokens(accessToken);
         }
+        if (!deviceId || !deviceSecret) {
+          logger.debug(
+            'auth/oauth/token returned no device credential — this session lives only as long as its access token',
+            { component: 'oxy.auth', method: 'exchangeOAuthCode' },
+          );
+        }
         return {
           sessionId,
-          deviceId,
           expiresAt,
           accessToken,
-          deviceSecret,
+          // Omitted rather than set to `undefined` when the server sent no device
+          // credential, so a device-less grant serializes as the absence it is.
+          ...(deviceId ? { deviceId } : {}),
+          ...(deviceSecret ? { deviceSecret } : {}),
           user: {
             id: userId,
             username: typeof userObj.username === 'string' ? userObj.username : undefined,

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

@@ -158,7 +158,40 @@ describe('pre-session public endpoints use skipAuth', () => {
     });
   });
 
-  it('exchangeOAuthCode rejects a response without deviceSecret', async () => {
+  // A third-party grant is meant to be ISOLATED from the browser's shared
+  // DeviceSession, so the token endpoint must be free to return no device
+  // credential. Core used to require the pair, which made that omission
+  // unshippable: every third-party sign-in through the SDK would have collapsed
+  // into a silent `exchange-failed` (issue #954).
+  it('exchangeOAuthCode accepts a device-less grant and still plants the token', async () => {
+    makeRequest.mockResolvedValueOnce({
+      access_token: 'tok',
+      token_type: 'Bearer',
+      expires_in: 900,
+      session_id: 's1',
+      user: { id: 'u1', username: 'alice' },
+    });
+
+    const result = await oxy.exchangeOAuthCode({
+      code: 'code-1',
+      clientId: 'oxy_dk_test',
+      redirectUri: 'https://app.example/callback',
+      codeVerifier: 'verifier',
+    });
+
+    expect(result).toMatchObject({
+      sessionId: 's1',
+      accessToken: 'tok',
+      user: { id: 'u1', username: 'alice' },
+    });
+    // Absent, not `undefined`-valued: a device-less grant carries no device keys
+    // at all, so nothing downstream can read one and persist an empty credential.
+    expect(result).not.toHaveProperty('deviceId');
+    expect(result).not.toHaveProperty('deviceSecret');
+    expect(oxy.getAccessToken()).toBe('tok');
+  });
+
+  it('exchangeOAuthCode accepts a deviceId with no deviceSecret', async () => {
     makeRequest.mockResolvedValueOnce({
       access_token: 'tok',
       token_type: 'Bearer',
@@ -167,6 +200,26 @@ describe('pre-session public endpoints use skipAuth', () => {
       deviceId: 'd1',
       user: { id: 'u1' },
     });
+
+    const result = await oxy.exchangeOAuthCode({
+      code: 'code-1',
+      clientId: 'oxy_dk_test',
+      redirectUri: 'https://app.example/callback',
+      codeVerifier: 'verifier',
+    });
+
+    expect(result).toMatchObject({ sessionId: 's1', deviceId: 'd1' });
+    expect(result).not.toHaveProperty('deviceSecret');
+  });
+
+  // The device pair left the guard; what identifies the session did NOT. Without
+  // these two the whole guard could be deleted and every test above would stay
+  // green — `sessionId` would silently become `undefined` on the returned session.
+  it.each([
+    ['session_id', { access_token: 'tok', expires_in: 900, user: { id: 'u1' } }],
+    ['user', { access_token: 'tok', expires_in: 900, session_id: 's1' }],
+  ])('exchangeOAuthCode still rejects a response missing %s', async (_field, response) => {
+    makeRequest.mockResolvedValueOnce(response);
     await expect(
       oxy.exchangeOAuthCode({
         code: 'code-1',

package/src/models/session.ts

@@ -14,6 +14,17 @@ export interface ClientSession {
    * account-chooser ordering, not for any token-refresh mechanism.
    */
   authuser?: number;
+  /**
+   * The HUMAN operating this account, when it is a delegated session — the
+   * audit actor behind "The Oxy Collective". Absent when the session belongs to
+   * the account itself.
+   *
+   * The flat wire shape has carried it since the multi-account model shipped and
+   * nothing read it, so an operated org rendered exactly like a directly
+   * signed-in one. `SessionClient.getActiveContext()` is the richer answer
+   * (ADR 0002); this is the same fact on the compatibility lane.
+   */
+  operatedByUserId?: string;
 }
 
 export interface StorageKeys {