@oxyhq/core 20.0.0 → 21.0.0

package/src/mixins/index.ts

@@ -17,6 +17,7 @@ import { OxyServicesReputationMixin } from './OxyServices.reputation';
 import { OxyServicesAssetsMixin } from './OxyServices.assets';
 import { OxyServicesAccountsMixin } from './OxyServices.accounts';
 import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps';
+import { OxyServicesStoreMixin } from './OxyServices.store';
 import { OxyServicesLocationMixin } from './OxyServices.location';
 import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
 import { OxyServicesDevicesMixin } from './OxyServices.devices';
@@ -28,6 +29,7 @@ import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesNotificationsMixin } from './OxyServices.notifications';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
+import { OxyServicesChainsMixin } from './OxyServices.chains';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
@@ -55,6 +57,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>>
@@ -65,6 +68,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>>
@@ -123,6 +127,10 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // OAuth-consent surface (public app identity + connected-app grants). Kept
     // separate from account ownership.
     OxyServicesConnectedAppsMixin,
+    // The app store: the public storefront, the reviews on it, and the listing a
+    // publisher edits. A module OVER the platform — turn it off and OAuth still
+    // works — so it is its own surface rather than more of `accounts`.
+    OxyServicesStoreMixin,
     OxyServicesLocationMixin,
     OxyServicesAnalyticsMixin,
     OxyServicesDevicesMixin,
@@ -137,6 +145,7 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServicesCivicMixin,
+    OxyServicesChainsMixin,
     // User nodes / decentralization (Fase 5): register/read/revoke/manage the
     // caller's personal data node + ingest hint.
     OxyServicesNodesMixin,

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 {

package/src/server/__tests__/rateLimit.test.ts

@@ -125,6 +125,53 @@ describe('@oxyhq/core/server rate limiter', () => {
     expect(req.observedKey).toBe('user:validated-user');
   });
 
+  it('does not clobber an identity a preceding middleware already resolved', () => {
+    // The limiter mutates the SHARED `req`, so the unconditional
+    // `req.userId = null` that `oxy.auth({ optional: true })` writes for every
+    // request it cannot authenticate is not merely a bucketing detail — it
+    // erases the identity for every handler downstream of the limiter too.
+    // The resolver must therefore skip entirely when a user is already present.
+    // This handler stands in for that erasure.
+    const clobberingAuth = jest.fn(
+      (req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+        req.userId = null;
+        req.user = null;
+        req.sessionId = null;
+        next();
+      },
+    );
+    const oxy = makeOxy(clobberingAuth as unknown as RequestHandler);
+    const req = makeRequest({
+      userId: 'resolved-by-the-app',
+      user: { id: 'resolved-by-the-app' },
+      sessionId: 'app-session',
+    });
+
+    createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+
+    expect(req.userId).toBe('resolved-by-the-app');
+    expect(req.user).toEqual({ id: 'resolved-by-the-app' });
+    expect(req.sessionId).toBe('app-session');
+    expect(req.observedKey).toBe('user:resolved-by-the-app');
+    expect(clobberingAuth).not.toHaveBeenCalled();
+  });
+
+  it('still resolves the session when no identity is present yet', () => {
+    const authHandler = jest.fn((req: RateLimitTestRequest, _res: Response, next: NextFunction) => {
+      req.userId = 'resolved-by-oxy';
+      req.user = { id: 'resolved-by-oxy' };
+      req.sessionId = 'oxy-session';
+      next();
+    });
+    const oxy = makeOxy(authHandler as unknown as RequestHandler);
+    const req = makeRequest();
+
+    createOxyRateLimit(oxy)(req, {} as Response, jest.fn());
+
+    expect(authHandler).toHaveBeenCalledTimes(1);
+    expect(req.observedKey).toBe('user:resolved-by-oxy');
+  });
+
   it('continues through the anonymous limiter if optional auth returns an error', () => {
     const oxy = makeOxy((_req: Request, _res: Response, next: NextFunction) => {
       next(new Error('token rejected'));

package/src/server/rateLimit.ts

@@ -3,6 +3,7 @@ import { isIPv4, isIPv6 } from 'node:net';
 import type { Request, RequestHandler } from 'express';
 import rateLimit, { type Store } from 'express-rate-limit';
 import type { OxyServices } from '../OxyServices';
+import { createOptionalOxyAuth } from './auth';
 
 /**
  * Server-only rate limiting for Oxy backends.
@@ -25,8 +26,9 @@ import type { OxyServices } from '../OxyServices';
  * WHAT IT PROVIDES
  * ----------------
  * `createOxyRateLimit(oxy, options)` returns a SINGLE composed middleware that:
- *   1. Resolves the user via `oxy.auth({ optional: true })` (idempotent — it
- *      skips re-verification if a prior middleware already set `req.user`).
+ *   1. Resolves the user via `createOptionalOxyAuth` (idempotent — it skips
+ *      resolution entirely if a prior middleware already resolved a user, so
+ *      the limiter can never erase an identity it did not create).
  *   2. Applies an `express-rate-limit` limiter keyed PER USER when
  *      authenticated, falling back to the (IPv6-safe) IP otherwise, with
  *      generous, media-app-realistic defaults and sensible exemptions.
@@ -203,11 +205,12 @@ function hashAnonymousIp(ip: string): string {
 /**
  * Resolve the trusted authenticated rate-limit key.
  *
- * `oxy.auth({ optional: true })` preserves legacy non-session user tokens by
- * decoding their JWT claims locally. Those claims are not cryptographically
- * verified and therefore MUST NOT influence abuse-control buckets. Only use
- * identities that came from a server-validated session or a verified service
- * token/delegation.
+ * Only identities that came from a server-validated session or a verified
+ * service token/delegation may pick a bucket. `req.sessionId` is the marker
+ * for the former: `oxy.auth()` sets it only after `validateSession()` came
+ * back valid, so requiring it here means an identity written by some OTHER
+ * middleware — which this package cannot vouch for — shares the anonymous
+ * per-IP bucket rather than getting the authenticated quota.
  */
 function resolveTrustedAuthenticatedKey(req: OxyAuthedRequest): string | null {
   const userId = req.userId ?? req.user?.id ?? req.user?._id;
@@ -260,7 +263,14 @@ export function createOxyRateLimit(
 
   // Idempotent optional-auth resolver. Reuses the SAME session resolution as
   // every protected route, so the limiter keys by the real user identity.
-  const resolveSession = oxy.auth({ ...auth, optional: true });
+  //
+  // `createOptionalOxyAuth` — NOT the raw `oxy.auth({ optional: true })` —
+  // because only the former skips resolution when a preceding middleware has
+  // already resolved a user. The raw middleware writes `req.userId = null` on
+  // every request it cannot authenticate, and because it mutates the shared
+  // `req` that erasure is visible to every handler downstream of the limiter,
+  // not just to the bucket calculation.
+  const resolveSession = createOptionalOxyAuth(oxy, { auth });
 
   const skip = (req: Request): boolean =>
     isBuiltInExempt(req) || (exempt ? exempt(req) : false);

package/src/session/SessionClient.ts

@@ -1,13 +1,19 @@
 import {
+  deviceActivateResponseSchema,
+  deviceDirectorySchema,
+  deviceDirectorySyncSchema,
   deviceSessionStateSchema,
   deviceSessionSyncSchema,
   safeParseContract,
   SESSION_ACCOUNTS_CHANGED_EVENT,
   sessionAccountsChangedEventSchema,
+  type DeviceDirectory,
   type DeviceSessionState,
+  type DeviceSessionSync,
 } from '@oxyhq/contracts';
 import { logger } from '../logger';
 import { computeIdentityTag } from '../utils/cacheKey';
+import { resolveActiveContext, type DeviceContext } from './deviceDirectory';
 import { getSocketIO } from './socketLoader';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 
@@ -98,6 +104,7 @@ export interface SessionClientOptions {
 }
 
 type StateListener = (state: DeviceSessionState | null) => void;
+type DirectoryListener = (directory: DeviceDirectory | null) => void;
 
 /**
  * Same-origin `BroadcastChannel` name for instant, network-free session-state
@@ -118,7 +125,20 @@ interface SessionBroadcastChannel {
 
 export class SessionClient {
   private state: DeviceSessionState | null = null;
+  /**
+   * The device DIRECTORY (ADR 0002) — principals, the contexts each may act as,
+   * and which context is active. Held BESIDE `state` rather than replacing it:
+   * `state` is the flat compatibility projection every app renders until Phase 7
+   * moves it, and the two describe the same device at the same `revision`.
+   *
+   * `null` until something asks for it. A client that never calls
+   * {@link refreshDirectory} has no consumer for a directory and never pays for
+   * the round trip — which is also what keeps the whole account lane's request
+   * count unchanged.
+   */
+  private directory: DeviceDirectory | null = null;
   private readonly listeners = new Set<StateListener>();
+  private readonly directoryListeners = new Set<DirectoryListener>();
   protected socket: MinimalSocket | null = null;
   private tokenUnsub: (() => void) | null = null;
   private started = false;
@@ -138,6 +158,27 @@ export class SessionClient {
     return this.state;
   }
 
+  /**
+   * The device directory, or `null` when this client has never read one.
+   * Populated by {@link refreshDirectory} / {@link activateContext} and kept
+   * fresh from there on.
+   */
+  getDirectory(): DeviceDirectory | null {
+    return this.directory;
+  }
+
+  /**
+   * The active `principal acting as account` pair, with the actor and the
+   * subject kept apart. `null` when no directory has been read, or when the
+   * device genuinely has no active context.
+   *
+   * This is the answer `getState()` cannot give: `activeAccountId` names the
+   * subject and says nothing about whose authentication is behind it.
+   */
+  getActiveContext(): DeviceContext | null {
+    return resolveActiveContext(this.directory);
+  }
+
   /**
    * 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
@@ -155,6 +196,20 @@ export class SessionClient {
     };
   }
 
+  /**
+   * Subscribe to the directory half. Fires from the SAME {@link notify} as
+   * {@link subscribe}, so the flat state and the directory are never published
+   * at two different points of the ordering sequence — a directory subscriber
+   * and a state subscriber woken by one transition always see the same device
+   * revision under the same bearer.
+   */
+  subscribeDirectory(listener: DirectoryListener): () => void {
+    this.directoryListeners.add(listener);
+    return () => {
+      this.directoryListeners.delete(listener);
+    };
+  }
+
   /**
    * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
    * Listeners survive reconnects and socket re-creation; the returned function
@@ -197,6 +252,13 @@ export class SessionClient {
         logger.error('[SessionClient] subscriber threw', error);
       }
     }
+    for (const listener of this.directoryListeners) {
+      try {
+        listener(this.directory);
+      } catch (error) {
+        logger.error('[SessionClient] directory subscriber threw', error);
+      }
+    }
   }
 
   /**
@@ -238,6 +300,13 @@ export class SessionClient {
     }
     const previousState = this.state;
     this.state = next;
+    if (next.accounts.length === 0) {
+      // A device with nobody signed in has no principals either. The directory
+      // is only ever refreshed by a bearer-carrying read and a sign-out leaves
+      // no bearer, so `settleDirectory` below cannot correct it — without this,
+      // the switcher would go on rendering the people who used to be here.
+      this.directory = null;
+    }
     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
@@ -271,7 +340,7 @@ export class SessionClient {
       next.accounts.length > 0 &&
       (activeAccountId === null || computeIdentityTag(this.host.getAccessToken()) !== activeAccountId);
 
-    const finishApply = (): void => {
+    const publish = (): void => {
       this.notify();
       if (next.accounts.length === 0 && this.options.onUnauthenticated) {
         try {
@@ -282,6 +351,22 @@ export class SessionClient {
       }
     };
 
+    // The directory half of the same ordering invariant: when this client holds
+    // a directory and the flat state has just moved past it, re-read the
+    // directory BEFORE anyone is notified — otherwise a directory-rendering
+    // consumer observes the PREVIOUS subject under the new subject's bearer,
+    // which is the account-switch race mirrored. `settleDirectory` returns null
+    // (and this stays synchronous) for every client that never read a
+    // directory, i.e. the whole account lane.
+    const finishApply = (): void => {
+      const settling = this.settleDirectory(next);
+      if (settling === null) {
+        publish();
+        return;
+      }
+      void settling.then(publish);
+    };
+
     if (needsMintBeforeNotify) {
       void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
         logger.warn('[SessionClient] ensureActiveToken failed — reverting session state', { component: 'SessionClient' }, error);
@@ -325,6 +410,20 @@ export class SessionClient {
       logger.warn('[SessionClient] discarded invalid session sync', { component: 'SessionClient', issues, keys });
       return;
     }
+    this.commitSync(sync);
+  }
+
+  /**
+   * The apply + token-plant half of {@link applySync}, on an ALREADY-VALIDATED
+   * sync. Split out so the context-aware removal lane — whose response is a
+   * different wire shape and therefore a different parse — reuses this ordering
+   * verbatim instead of re-deriving it. Two implementations of
+   * "plant before notify" is two chances to get it wrong once.
+   *
+   * Returns whether `applyState` applied, so a caller holding a second half
+   * (the directory) can decide whether anything still needs publishing.
+   */
+  private commitSync(sync: DeviceSessionSync): boolean {
     // A `sync` is always the response to a direct REST call this client made
     // (bootstrap / switch / signOut / add) → a `request`-origin, authoritative
     // verdict. Hand the active token to `applyState`: in the applied path it is
@@ -349,6 +448,166 @@ export class SessionClient {
     ) {
       this.host.setTokens(sync.activeToken.accessToken);
     }
+    return applied;
+  }
+
+  /**
+   * Validate + last-writer-wins, `deviceId`-SCOPED exactly as {@link applyState}
+   * is for the flat half: a directory belonging to a DIFFERENT device resets the
+   * baseline and is accepted at any revision, so a freshly-converged device
+   * cannot lose to a retired device's higher number.
+   *
+   * The comparison itself is deliberately WEAKER than the flat state's. There it
+   * is `revision <= current` — correct, because a `DeviceSessionState` arrives
+   * out of band over a socket, so a straggler can genuinely land after a newer
+   * one. A directory only ever arrives as the response to a request THIS client
+   * just made, so the newest response is the freshest answer and only a strictly
+   * LOWER revision can be a straggler (two GETs racing).
+   *
+   * Equal-revision reads are not redundant, and rejecting them was a bug: the
+   * directory includes rows projected from the account GRAPH, and the server
+   * materializes a context for every account a principal may act as WITHOUT
+   * bumping `revision` — deliberately, since `revision` tracks what the device
+   * holds and must never advance on a read. So a newly-granted `account:act_as`,
+   * and a removed-then-rematerialized context under its NEW id, both appear at
+   * an unchanged revision. Under `<=` neither would ever be seen until some
+   * unrelated device mutation happened to move the number.
+   *
+   * Notifies nothing. Every caller decides where in its own ordering sequence
+   * the publish belongs.
+   */
+  private applyDirectory(raw: unknown): boolean {
+    const next = safeParseContract(deviceDirectorySchema, raw);
+    if (!next) {
+      logger.warn('[SessionClient] discarded invalid device directory');
+      return false;
+    }
+    if (
+      this.directory &&
+      next.deviceId === this.directory.deviceId &&
+      next.revision < this.directory.revision
+    ) {
+      return false;
+    }
+    this.directory = next;
+    return true;
+  }
+
+  /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
+  private async fetchDirectory(): Promise<boolean> {
+    const res = await this.host.makeRequest<unknown>('GET', '/session/device/directory', undefined, { cache: false });
+    return this.applyDirectory(res);
+  }
+
+  /**
+   * Re-read the directory when the flat state has moved past it, returning the
+   * in-flight work so the caller can hold its notify until both halves describe
+   * the same revision.
+   *
+   * `null` — meaning "nothing to settle, stay synchronous" — when this client
+   * holds no directory (nobody reads one), when the directory is already at or
+   * ahead of the state, or when there is no bearer to make the call with.
+   * Never rejects: a failed refresh leaves the previous directory in place and
+   * the next transition tries again; it must not swallow the flat state's
+   * notify.
+   */
+  private settleDirectory(state: DeviceSessionState): Promise<void> | null {
+    const held = this.directory;
+    if (held === null) {
+      return null;
+    }
+    if (held.deviceId === state.deviceId && held.revision >= state.revision) {
+      return null;
+    }
+    if (!this.host.getAccessToken()) {
+      return null;
+    }
+    return this.fetchDirectory().then(
+      () => undefined,
+      (error: unknown) => {
+        logger.warn('[SessionClient] directory refresh failed', { component: 'SessionClient' }, error);
+      },
+    );
+  }
+
+  /**
+   * The highest device revision this client currently knows for `deviceId`,
+   * across BOTH halves, or `null` when it knows nothing about that device.
+   *
+   * Used to read the server's `changed` flag, which
+   * `POST /session/device/activate` deliberately does not carry: the revision
+   * already says whether the device moved, and a second field saying the same
+   * thing is a second field that can disagree with the first.
+   */
+  private knownRevisionFor(deviceId: string): number | null {
+    const fromDirectory = this.directory?.deviceId === deviceId ? this.directory.revision : null;
+    const fromState = this.state?.deviceId === deviceId ? this.state.revision : null;
+    if (fromDirectory === null) return fromState;
+    if (fromState === null) return fromDirectory;
+    return Math.max(fromDirectory, fromState);
+  }
+
+  /**
+   * Plant the bearer `POST /session/device/activate` returned for the newly
+   * active context, under the same guards {@link applyState} applies to a
+   * sync-supplied `activeToken`: never for a null active context, never a
+   * foreign account's token while pinned, and never a redundant re-plant of the
+   * token already held.
+   *
+   * `activeToken: null` is not an error — it is an identity-pinned client, or a
+   * caller whose application is not entitled to a bearer for the new context.
+   */
+  private plantActiveContextToken(directory: DeviceDirectory, accessToken: string | undefined): void {
+    if (!accessToken) {
+      return;
+    }
+    const subjectAccountId = resolveActiveContext(directory)?.subject.accountId ?? null;
+    if (subjectAccountId === null) {
+      return;
+    }
+    const pinnedAccountId = this.pinnedAccountId();
+    if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId) {
+      return;
+    }
+    if (accessToken === this.host.getAccessToken()) {
+      return;
+    }
+    this.host.setTokens(accessToken);
+  }
+
+  /**
+   * Bring the FLAT projection back in step after a context activation.
+   *
+   * The activation response answers with the directory and a bearer and
+   * deliberately not with `DeviceSessionState` (ADR 0002) — but every app that
+   * has not moved to the directory still renders from `getState()`, and leaving
+   * it a revision behind would show the PREVIOUS subject under the new
+   * subject's bearer. So it is settled BEFORE the notify, not after.
+   *
+   * This is also what converges the bearer when the activation returned no
+   * token: `GET /session/device/state` mints one for the active account, and
+   * `applyState`'s own mint-before-notify gate holds its notify until it lands.
+   *
+   * Non-fatal on failure — the directory is applied and (usually) the bearer is
+   * planted; the socket push or the next bootstrap catches the flat half up. A
+   * network blip must not turn a completed activation into a thrown error.
+   */
+  private async reconcileFlatState(directory: DeviceDirectory): Promise<void> {
+    if (
+      this.state &&
+      this.state.deviceId === directory.deviceId &&
+      this.state.revision >= directory.revision
+    ) {
+      return;
+    }
+    if (!this.host.getAccessToken()) {
+      return;
+    }
+    try {
+      await this.bootstrap();
+    } catch (error) {
+      logger.warn('[SessionClient] flat-state reconcile after activation failed', { component: 'SessionClient' }, error);
+    }
   }
 
   async bootstrap(): Promise<void> {
@@ -356,18 +615,144 @@ export class SessionClient {
     this.applySync(res);
   }
 
+  /**
+   * Read `GET /session/device/directory` and publish it.
+   *
+   * Calling this is what opts a client into the directory: from here on every
+   * applied device state re-reads it (see {@link settleDirectory}), so the two
+   * halves stay at one revision without the caller polling.
+   */
+  async refreshDirectory(): Promise<void> {
+    if (await this.fetchDirectory()) {
+      this.notify();
+    }
+  }
+
+  /**
+   * `POST /session/device/activate` — make one `principal acting as account`
+   * context active (ADR 0002).
+   *
+   * The body is `{ contextId }` and nothing else: an `accountId` cannot name
+   * what to activate on a device where two people can both reach the same
+   * organization, and the server refuses a body carrying one rather than
+   * guessing inside an authorization path.
+   *
+   * The sequence is the ADR's ordering invariant, in order — commit the bearer
+   * for the new context, publish the new snapshot, notify — with the flat
+   * projection reconciled in the middle so no consumer can observe the two
+   * halves disagreeing.
+   *
+   * An IDEMPOTENT activation (the target was already active) moves no revision,
+   * so it reconciles nothing and wakes no sibling tab, mirroring the server's
+   * "bumps nothing and broadcasts nothing". `switchAccount` remains the
+   * compatibility path for callers still keyed on account ids.
+   */
+  async activateContext(contextId: string): Promise<void> {
+    const res = await this.host.makeRequest<unknown>('POST', '/session/device/activate', { contextId }, { cache: false });
+    const activation = safeParseContract(deviceActivateResponseSchema, res);
+    if (!activation) {
+      logger.warn('[SessionClient] discarded invalid activation response');
+      return;
+    }
+    const known = this.knownRevisionFor(activation.directory.deviceId);
+    const moved = known === null || activation.directory.revision > known;
+    this.plantActiveContextToken(activation.directory, activation.activeToken?.accessToken);
+    // Applied BEFORE the reconcile, and only then: the reconcile's own
+    // `GET /session/device/state` runs the full apply path, whose
+    // `settleDirectory` would otherwise see a stale directory and issue a
+    // second, redundant `GET /session/device/directory` for the revision we are
+    // already holding in hand.
+    const applied = this.applyDirectory(activation.directory);
+    if (moved) {
+      await this.reconcileFlatState(activation.directory);
+    }
+    if (applied) {
+      this.notify();
+    }
+    if (moved) {
+      this.postCommitPing();
+    }
+  }
+
   async switchAccount(accountId: string): Promise<void> {
     const res = await this.host.makeRequest<unknown>('POST', '/session/device/switch', { accountId }, { cache: false });
     this.applySync(res);
     this.postCommitPing();
   }
 
+  /**
+   * The FLAT removal meanings, unchanged: `{ accountId }` removes that account
+   * however it is reached — plus the operator cascade — and `{ all: true }`
+   * removes the whole device including its credentials.
+   *
+   * `{ accountId }` is deliberately still account-grained. On a device holding
+   * two people it removes BOTH of their routes to that account, which is the
+   * right meaning for "sign this account out of this device" and the wrong one
+   * for "this person is done here" — see {@link signOutContext} and
+   * {@link signOutPrincipal} for the two that can tell those apart.
+   */
   async signOut(target: { accountId: string } | { all: true }): Promise<void> {
     const res = await this.host.makeRequest<unknown>('POST', '/session/device/signout', target, { cache: false });
     this.applySync(res);
     this.postCommitPing();
   }
 
+  /**
+   * Remove ONE `principal → account` pair, and only that pair.
+   *
+   * Never the account across the device: the same organization reached through
+   * a second person is a different session, a different audit actor and a
+   * different revocation path, and it stays. That distinction is unreachable
+   * through {@link signOut}, whose `accountId` cannot name which route to drop.
+   *
+   * Removal is not permanent while the membership lives — the server offers the
+   * pair again on the next directory read, as `onDevice: false` under a NEW id.
+   */
+  async signOutContext(contextId: string): Promise<void> {
+    await this.removeFromDevice({ contextId });
+  }
+
+  /**
+   * Remove ONE PERSON and every context they reach — and nobody else's,
+   * including when another principal independently operates the same account.
+   */
+  async signOutPrincipal(principalId: string): Promise<void> {
+    await this.removeFromDevice({ principalId });
+  }
+
+  /**
+   * The shared apply path for both context-aware removals.
+   *
+   * The response is `{directory, state, activeToken}` — its own contract, never
+   * `deviceSessionSyncSchema`, which would strip the directory silently. Both
+   * halves move in one server transition (a removal elects a replacement active
+   * context), so both are applied before anything is published: the directory
+   * first, so the flat apply's own `settleDirectory` sees a current directory
+   * and does not issue a redundant `GET /session/device/directory` for the
+   * revision already in hand.
+   *
+   * Token-before-notify is `commitSync`'s, reused verbatim rather than
+   * re-derived — including the equal-revision plant when a socket push already
+   * applied this revision.
+   */
+  private async removeFromDevice(target: { contextId: string } | { principalId: string }): Promise<void> {
+    const res = await this.host.makeRequest<unknown>('POST', '/session/device/signout', target, { cache: false });
+    const removal = safeParseContract(deviceDirectorySyncSchema, res);
+    if (!removal) {
+      logger.warn('[SessionClient] discarded invalid device removal response');
+      return;
+    }
+    const directoryApplied = this.applyDirectory(removal.directory);
+    const stateApplied = this.commitSync({ state: removal.state, activeToken: removal.activeToken });
+    // `commitSync` publishes whenever the flat state moved. When only the
+    // directory did — a socket push already applied this revision — the
+    // directory half would otherwise never reach a subscriber.
+    if (directoryApplied && !stateApplied) {
+      this.notify();
+    }
+    this.postCommitPing();
+  }
+
   async addCurrentAccount(): Promise<void> {
     const res = await this.host.makeRequest<unknown>('POST', '/session/device/add', undefined, { cache: false });
     this.applySync(res);