@oxyhq/core 20.1.0 → 21.0.1

package/dist/types/server/auth.d.ts

@@ -16,6 +16,12 @@ export interface OxyServiceAppContext {
     appName: string;
     scopes: string[];
     credentialId: string;
+    /**
+     * The Oxy account that owns `appId` and is financially responsible for it.
+     * Read off the VERIFIED service-token claim set — never a user id, and never
+     * the delegated `X-Oxy-User-Id` (ADR 0007).
+     */
+    ownerAccountId: string;
     environment: OxyServiceEnvironment;
 }
 export interface OxyServiceActingAsContext {
@@ -44,6 +50,80 @@ export interface OxyAuthMiddlewareOptions {
 }
 export declare function getOxyUserId(req: Request): string | null;
 export declare function isOxyAuthenticated(req: Request): req is OxyAuthenticatedRequest;
+/**
+ * The principal a request is CHARGED to, and the identifiers a receipt needs.
+ *
+ * Every field is read from the verified service-token claim set. It is an
+ * OBJECT, not a string, and that is the point: `getOxyUserId` returns a
+ * `string | null`, so a delegated end-user id cannot be passed anywhere an
+ * `OxyBillingPrincipal` is expected. The confusion ADR 0007 forbids —
+ * attributing spend to the person a service is acting for rather than to the
+ * service's own account — stops being a code-review question and becomes a
+ * compile error.
+ *
+ * `scopes` are the effective scopes minted into the token (credential ∩
+ * application). Nothing re-intersects them here.
+ */
+export interface OxyBillingPrincipal {
+    /** `applications.owner_account_id` — the financially responsible account. */
+    readonly accountId: string;
+    readonly applicationId: string;
+    readonly credentialId: string;
+    readonly environment: OxyServiceEnvironment;
+    readonly scopes: readonly string[];
+}
+/**
+ * The full canonical attribution of ADR 0007 for a request: the billing
+ * principal PLUS the optional delegated end user.
+ *
+ * `delegatedUserId` is named for what it is. It answers "on whose behalf" and
+ * is absent for a machine credential acting for itself — its absence is normal,
+ * and nothing may synthesize one. If removing it would change what any account
+ * is charged, the code reading it is wrong.
+ */
+export interface OxyRequestAttribution extends OxyBillingPrincipal {
+    readonly delegatedUserId: string | null;
+}
+/**
+ * The billing principal of a request, or `null` when the request carries no
+ * verified service principal (an ordinary user session is not a billable
+ * machine principal — its account is resolved from the account graph, not from
+ * a token claim).
+ *
+ * Reads `req.serviceApp` and NOTHING else: not `req.userId`, not `req.user`,
+ * not `req.serviceActingAs`. That exclusivity is the invariant this function
+ * exists to hold, and `serviceTokenAttribution.test.ts` mutation-tests it.
+ *
+ * **It answers for the SERVICE-TOKEN lane only.** The API's machine-credential
+ * lane (`oxy_sk_*`, issue #972 §2.3) resolves the same five facts into its own
+ * `req.machineCredential`, deliberately never `req.serviceApp` — populating the
+ * latter would hand a self-serve third-party credential the lane that only
+ * platform-trusted applications may enter. So a machine-credential request has
+ * no billing principal HERE and resolves `null`, which fails closed: the caller
+ * must handle it, and `getRequiredOxyBillingPrincipal` throws rather than
+ * charging anyone. One accessor answering for both lanes belongs to the public
+ * inference edge that has to admit both, and it needs the machine principal's
+ * shape to move into this package first.
+ */
+export declare function getOxyBillingPrincipal(req: Request): OxyBillingPrincipal | null;
+/**
+ * {@link getOxyBillingPrincipal}, throwing when the request has none. Use on
+ * routes that have already required a service token.
+ */
+export declare function getRequiredOxyBillingPrincipal(req: Request): OxyBillingPrincipal;
+/**
+ * The delegated end user of a service request, or `null`.
+ *
+ * Deliberately reads `req.serviceActingAs` — the grant-verified delegation —
+ * and not `req.userId`, which on a non-service request is the caller's own
+ * session identity and is not a delegation at all.
+ */
+export declare function getOxyDelegatedUserId(req: Request): string | null;
+/**
+ * The whole attribution tuple for a service request: who pays, which
+ * application and credential, and optionally on whose behalf.
+ */
+export declare function getOxyRequestAttribution(req: Request): OxyRequestAttribution | null;
 export declare function getRequiredOxyUserId(req: Request): string;
 export declare function requireOxyAuth(req: Request, res: Response, next: NextFunction): void;
 export declare function createOptionalOxyAuth(oxy: OxyServices, options?: OxyAuthMiddlewareOptions): RequestHandler;

package/dist/types/server/index.d.ts

@@ -14,8 +14,8 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
-export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
+export type { OxyAuthenticatedRequest, OxyAuthMiddlewareOptions, OxyAuthRequest, OxyBillingPrincipal, OxyRequestAttribution, OxyRequestUser, OxyServiceActingAsContext, OxyServiceAppContext, OxyServiceEnvironment, } from './auth';
 export { createOxyRateLimit } from './rateLimit';
 export type { OxyRateLimitOptions } from './rateLimit';
 export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch';

package/dist/types/session/SessionClient.d.ts

@@ -1,4 +1,5 @@
-import { type DeviceSessionState } from '@oxyhq/contracts';
+import { type DeviceDirectory, type DeviceSessionState } from '@oxyhq/contracts';
+import { type DeviceContext } from './deviceDirectory';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 export interface TokenTransport {
     /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via the persisted refresh family / shared keychain). Best-effort. */
@@ -84,11 +85,25 @@ export interface SessionClientOptions {
     getPinnedAccountId?: () => string | null;
 }
 type StateListener = (state: DeviceSessionState | null) => void;
+type DirectoryListener = (directory: DeviceDirectory | null) => void;
 export declare class SessionClient {
     protected readonly host: SessionClientHost;
     protected readonly options: SessionClientOptions;
     private state;
+    /**
+     * 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;
     private readonly listeners;
+    private readonly directoryListeners;
     protected socket: MinimalSocket | null;
     private tokenUnsub;
     private started;
@@ -100,6 +115,21 @@ export declare class SessionClient {
     private readonly boundServerEvents;
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     getState(): DeviceSessionState | null;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * 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
@@ -108,6 +138,14 @@ export declare class SessionClient {
      */
     private pinnedAccountId;
     subscribe(listener: StateListener): () => void;
+    /**
+     * 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;
     /**
      * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
      * Listeners survive reconnects and socket re-creation; the returned function
@@ -143,13 +181,176 @@ export declare class SessionClient {
      * account that is no longer active.
      */
     private applySync;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
+    private fetchDirectory;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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 reconcileFlatState;
     bootstrap(): Promise<void>;
+    /**
+     * 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.
+     */
+    refreshDirectory(): Promise<void>;
+    /**
+     * `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.
+     */
+    activateContext(contextId: string): Promise<void>;
     switchAccount(accountId: string): Promise<void>;
+    /**
+     * 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.
+     */
     signOut(target: {
         accountId: string;
     } | {
         all: true;
     }): Promise<void>;
+    /**
+     * 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.
+     */
+    signOutContext(contextId: string): Promise<void>;
+    /**
+     * Remove ONE PERSON and every context they reach — and nobody else's,
+     * including when another principal independently operates the same account.
+     */
+    signOutPrincipal(principalId: string): Promise<void>;
+    /**
+     * 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 removeFromDevice;
     addCurrentAccount(): Promise<void>;
     /**
      * Register the just-signed-in account into the device set AND make it the

package/dist/types/session/accountDialogController.d.ts

@@ -9,15 +9,16 @@
  * replaces.
  *
  * The controller owns:
- *   - the unified account list (via {@link projectSwitchableAccounts}), fetched
- *     from `SessionClient` state ∪ `oxyServices.listAccounts()` and hydrated
- *     with `oxyServices.getUsersByIds()`;
+ *   - the device DIRECTORY (ADR 0002) — the server-authoritative read model of
+ *     who is on this device and what each of them may act as, read through
+ *     `SessionClient.refreshDirectory()`. It is not assembled here: the client
+ *     holds one caller's account graph and cannot enumerate another principal's,
+ *     so switchability is the server's answer and the controller only reads it;
  *   - the dialog `view` state machine (`accounts` | `signin` | `qr` | `add` |
  *     `signup`);
- *   - `switchTo` (the uniform switch: `SessionClient.switchAccount` for an
- *     account already on the device, `oxyServices.switchToAccount` to mint on
- *     first entry into a graph account — reusing the existing SDK primitives, no
- *     new switch path);
+ *   - `activateContext` (the ADR 0002 switch, keyed on the `principal acting as
+ *     account` pair) and the two removals an account id cannot name —
+ *     `signOutContext` and `signOutPrincipal`;
  *   - the "Sign in with Oxy" device flow (same-device shared-keychain via
  *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
  *     via `startCommonsSignIn` → poll → `claimSessionByToken`);
@@ -54,11 +55,12 @@
  * `add` / `startSignup` (the view axis) and `cancelSignIn` (device-flow
  * teardown), never an `open` / `close` / `visible`.
  */
+import type { DeviceDirectory } from '@oxyhq/contracts';
 import type { OxyServices } from '../OxyServices';
 import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import type { SessionClient } from './SessionClient';
 import type { SocketIOFactory } from './socketLoader';
-import { type SwitchableAccount } from './accountProjection';
+import { type DeviceContext } from './deviceDirectory';
 import { type CommonsDeliveryPlatform, type CommonsDeliveryRoute } from '../utils/commonsDelivery';
 /** The dialog's top-level view. */
 export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add' | 'signup';
@@ -192,16 +194,27 @@ export interface SignInFlowState {
 export interface AccountDialogSnapshot {
     /** The current view. */
     view: AccountDialogView;
-    /** The unified, deduped account list (device sign-ins ∪ graph accounts). */
-    accounts: SwitchableAccount[];
-    /** The currently-active account id, or `null` when signed out. */
-    activeAccountId: string | null;
-    /** `true` while the initial account-list fetch is in flight with no data yet. */
+    /**
+     * The server-authoritative device directory — principals and the contexts
+     * each may act as (ADR 0002) — or `null` before the first read.
+     *
+     * The ONE read model a switcher renders. The flat list this replaced was
+     * keyed by account id, so on a device holding two people it could show one
+     * route to a shared organization and never both.
+     */
+    directory: DeviceDirectory | null;
+    /** The active `principal acting as account` pair, actor and subject apart. */
+    activeContext: DeviceContext | null;
+    /** `true` while the first directory read is in flight with nothing to show. */
     loading: boolean;
-    /** A human-readable account-list error, or `null`. */
+    /** A human-readable directory error, or `null`. */
     error: string | null;
-    /** The `accountId` of an in-flight switch, or `null`. */
-    switchingAccountId: string | null;
+    /** The `contextId` of an in-flight activation, or `null`. */
+    activatingContextId: string | null;
+    /** The `contextId` of an in-flight context removal, or `null`. */
+    removingContextId: string | null;
+    /** The `principalId` of an in-flight principal removal, or `null`. */
+    removingPrincipalId: string | null;
     /** The "Sign in with Oxy" device-flow state. */
     signIn: SignInFlowState;
     /** Whether Commons is installed on this device. See {@link CommonsAvailability}. */
@@ -220,8 +233,6 @@ export interface AccountDialogControllerOptions {
      * server would reject.
      */
     clientId?: string | null;
-    /** Locale for display-name resolution. */
-    locale?: string;
     /**
      * Commit a freshly-authorized SIGN-IN session (device flow / shared identity)
      * into the host's session set — device-first registration + durable persist +
@@ -231,24 +242,12 @@ export interface AccountDialogControllerOptions {
      * `SessionClient.registerAndActivate` (registration + activation only — no
      * provider-side durable persist/hydration).
      *
-     * This is the SIGN-IN commit: registers the session into the host's device
-     * set with durable persist + profile hydration. An account SWITCH uses
-     * {@link commitSwitchedSession} instead — see below.
+     * Sign-in is the only thing that commits a session here. An account SWITCH
+     * used to mint one too, on first entry into a graph account; activation mints
+     * the delegated session SERVER-side and hands back a bearer, so there is no
+     * second commit funnel to keep in step with this one.
      */
     commitSession?: (session: SessionLoginResponse) => Promise<void>;
-    /**
-     * Commit a minted graph SWITCH session into the host's session set — same
-     * device-first registration + durable persist + profile hydration as
-     * {@link commitSession}, but IN-PLACE: it must NOT re-run sign-in side effects
-     * that belong only to a fresh authorization (for example, a redundant full
-     * device-set reconcile on switch). Cross-tab/app propagation of the switch
-     * still happens instantly via the server's device-scoped `session_state` /
-     * `session_accounts_changed` socket broadcast — no navigation required.
-     *
-     * When omitted the controller falls back to {@link commitSession} (if wired)
-     * and then to `SessionClient.registerAndActivate`.
-     */
-    commitSwitchedSession?: (session: SessionLoginResponse) => Promise<void>;
     /** Notified after a completed sign-in (bearer planted + session committed). */
     onSignedIn?: (user: MinimalUserData) => void;
     /**
@@ -313,9 +312,7 @@ export declare class AccountDialogController {
     private readonly oxyServices;
     private readonly sessionClient;
     private readonly clientId;
-    private readonly locale?;
     private readonly commitSession?;
-    private readonly commitSwitchedSession?;
     private readonly onSignedIn?;
     private readonly pollIntervalMs;
     private readonly openUrl?;
@@ -326,11 +323,11 @@ export declare class AccountDialogController {
     private readonly platform;
     private readonly listeners;
     private view;
-    private graph;
-    private profilesById;
     private loading;
     private error;
-    private switchingAccountId;
+    private activatingContextId;
+    private removingContextId;
+    private removingPrincipalId;
     private signIn;
     private commonsAvailability;
     /** The secret device-flow token of the active QR flow (never surfaced). */
@@ -406,35 +403,54 @@ export declare class AccountDialogController {
     /** Switch to the "create account" view (passkey / Commons signup entry). */
     startSignup(): void;
     /**
-     * Reload the account graph and per-account profiles, then re-project. Safe to
-     * call repeatedly; concurrent calls are reconciled by a sequence guard so a
-     * slow earlier fetch never overwrites a newer result.
+     * Re-read `GET /session/device/directory`. Safe to call repeatedly;
+     * concurrent calls are reconciled by a sequence guard so a slow earlier read
+     * never overwrites a newer result.
+     *
+     * This is ONE request. It used to be three — the directory, plus
+     * `listAccounts()` and `getUsersByIds()` to rebuild the same tree client-side
+     * — and the reconstruction was not merely redundant: it enumerated the
+     * CALLER's account graph, which on a device holding two people is one
+     * person's answer presented as the device's.
      */
     refresh(): Promise<void>;
     /**
-     * Fetch profiles for any account id (device set ∪ graph) not yet resolved.
-     * Cheap no-op when everything is already hydrated — used from the session
-     * subscription so a newly-added device account gets a name/avatar.
+     * Activate one `principal acting as account` context — the ADR 0002 switch,
+     * and the one that can express what an account id cannot: WHICH person's
+     * route to a shared organization to become.
+     *
+     * There is no on-device/graph fork. The directory has a row for a context the
+     * principal may act as but has never entered, and `POST /session/device/
+     * activate` reuses or mints the delegated session server-side, so one call
+     * covers both cases.
+     *
+     * A context id is not stable across a removal, so a stale one is an ordinary
+     * outcome rather than a bug: the server answers 404 or 403, heals the row, and
+     * the refresh below re-reads a directory that no longer offers it.
      */
-    private ensureProfiles;
-    private loadProfiles;
+    activateContext(contextId: string): Promise<boolean>;
     /**
-     * Switch the active account to `accountId`.
+     * Remove ONE `principal → account` pair, and only that pair.
+     *
+     * Not the account across the device: the same organization reached through a
+     * second person is a different session with a different audit actor, and it
+     * stays. Routing this through `signOut({accountId})` would revoke that second
+     * person's access as a side effect of one person tidying their own list.
      *
-     * Uniform switch model, mirroring the SDK's existing path — NOT a new switch
-     * mechanism:
-     *   - already on this device → `SessionClient.switchAccount` (device-first
-     *     switch of `/session/device/switch`);
-     *   - a graph account not yet on the device (first entry) →
-     *     `oxyServices.switchToAccount` mints + plants a real session and the
-     *     server registers it into the device set, then it is committed
-     *     (`commitSession` when supplied, else `SessionClient.registerAndActivate`).
+     * The removed pair is not gone for good while the membership lives — the
+     * server offers it again on the next read, under a NEW id and at an unchanged
+     * revision — so nothing may hold a context id across this call.
+     */
+    signOutContext(contextId: string): Promise<boolean>;
+    /**
+     * Remove ONE PERSON and every context they reach — and nobody else's,
+     * including when another principal independently operates the same account.
      *
-     * The resulting device-state change flows back through the `SessionClient`
-     * subscription, which re-projects the active row. Concurrent switches are
-     * ignored while one is in flight.
+     * A separate call from {@link signOutContext} because it is a separate
+     * question, not a loop over the first one: the server removes the principal
+     * and elects a replacement active context in one transition.
      */
-    switchTo(accountId: string): Promise<boolean>;
+    signOutPrincipal(principalId: string): Promise<boolean>;
     /**
      * Start "Sign in with Oxy". Native devices with a shared identity mint a
      * session silently (`signInWithSharedIdentity`); everything else (web, or a
@@ -595,10 +611,6 @@ export declare class AccountDialogController {
      * Register a token-planted session into the device set. Prefers the
      * consumer's commit funnel (durable persist + hydration); falls back to
      * `SessionClient.registerAndActivate` (registration + activation only).
-     *
-     * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel;
-     * a SIGN-IN uses `commitSession`. When the switch funnel is not wired it falls
-     * back to the sign-in funnel, then to `registerAndActivate`.
      */
     private commitAuthorizedSession;
     private failSignIn;

package/dist/types/session/accountSwitchTargets.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The two questions an account chooser asks of an account-graph node: is this
+ * kind switchable at all, and may THIS caller become it.
+ *
+ * Pure and I/O-free. They live here rather than beside the surfaces that ask
+ * them because there is more than one such surface — the Console's workspace
+ * tree, the Accounts app's managed-account rows — and a second enumeration of
+ * switch targets is a second place for the rule to go missing, which is
+ * precisely how the Console went on offering `channel` rows after the rule
+ * learned to drop them.
+ *
+ * The DEVICE switcher no longer asks anything here: it renders the server's
+ * device directory (ADR 0002, `deviceDirectory.ts`), whose `available` field is
+ * the server's own authorization verdict. These predicates answer a different
+ * question — one about the caller's account GRAPH, which is a list of accounts
+ * to manage, not a list of identities the device can become.
+ */
+import type { AccountRelationship, AccountKind, AccountMember } from '../mixins/OxyServices.accounts';
+/**
+ * Whether the caller can BECOME this account — the one question every account
+ * switcher asks, answered here so no surface has to re-derive it.
+ *
+ * Two independent grounds, either of which suffices:
+ *
+ *  - **It is already the caller's own identity** (`relationship: 'self'`).
+ *    `GET /accounts` resolves its caller through `resolveOperatorId`, so `self`
+ *    is the HUMAN operator's personal account even while they are operating an
+ *    org — never the operated account. Kind is irrelevant on this ground: the
+ *    caller IS that account, so returning to it asks the server for nothing.
+ *  - **The server will mint a session for it** — `isActAsEligibleKind(kind)` is
+ *    the exact predicate `POST /accounts/:id/switch` enforces, so a row offered
+ *    on this ground is never a dead button.
+ *
+ * `isActAsEligibleKind` ALONE is not this question, and reaching for it
+ * directly is the mistake this function exists to prevent: it is false for
+ * `personal` as well as `channel`, so a switcher gated on it alone renders an
+ * empty list rather than a filtered one. Equally, `kind !== 'channel'` is not
+ * this question either — it silently admits every kind invented after it was
+ * written, which is the same trap `isActAsEligibleKind` was introduced to close
+ * on the server.
+ *
+ * Takes a structural subset rather than a whole {@link AccountNode} so a caller
+ * holding an already-projected row can ask it too.
+ */
+export declare function isSwitchTargetAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+}): boolean;
+/**
+ * Whether the caller may switch INTO this account — the server-side
+ * `account:act_as` gate plus the structural {@link isSwitchTargetAccount} rule.
+ *
+ * `relationship: 'self'` always passes (returning to the caller's own personal
+ * account). Every other ground requires a switch-eligible kind AND
+ * `account:act_as` in the resolved membership permissions. When permissions are
+ * absent but the relationship is `owner`, the owner baseline is assumed — the
+ * API always resolves effective permissions for owned accounts, but test
+ * fixtures and stale rows may omit the membership blob.
+ */
+export declare function canSwitchIntoAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+    callerMembership?: AccountMember | null;
+}): boolean;