@oxyhq/core 20.0.0 → 21.0.0

package/dist/esm/session/accountDialogController.js

@@ -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`);
@@ -57,7 +58,7 @@
 import { logger } from '../logger/index.js';
 import { extractErrorStatus } from '../utils/errorUtils.js';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl.js';
-import { projectSwitchableAccounts, switchableAccountIds, } from './accountProjection.js';
+import { resolveActiveContext } from './deviceDirectory.js';
 import { pushTargetsFromDelivery, selectCommonsDelivery, } from '../utils/commonsDelivery.js';
 /**
  * Derive the surface-facing progress from the flow's real facts. Pure, total,
@@ -137,11 +138,11 @@ export class AccountDialogController {
         this.listeners = new Set();
         // --- Internal (unprojected) state ---
         this.view = 'accounts';
-        this.graph = [];
-        this.profilesById = new Map();
         this.loading = false;
         this.error = null;
-        this.switchingAccountId = null;
+        this.activatingContextId = null;
+        this.removingContextId = null;
+        this.removingPrincipalId = null;
         this.signIn = IDLE_SIGN_IN;
         this.commonsAvailability = 'unknown';
         // --- Sign-in device-flow bookkeeping ---
@@ -174,9 +175,7 @@ export class AccountDialogController {
         this.oxyServices = options.oxyServices;
         this.sessionClient = options.sessionClient;
         this.clientId = options.clientId ?? null;
-        this.locale = options.locale;
         this.commitSession = options.commitSession;
-        this.commitSwitchedSession = options.commitSwitchedSession;
         this.onSignedIn = options.onSignedIn;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.openUrl = options.openUrl;
@@ -215,11 +214,12 @@ export class AccountDialogController {
         this.started = true;
         this.authed = this.isAuthenticated();
         this.unsubscribeSession = this.sessionClient.subscribe(() => {
-            // A device-state change (switch / sign-out / sibling sign-in) can add or
-            // remove accounts — re-project immediately, refetch profiles when new
-            // account ids appeared, and reconcile the auth-readiness edge.
+            // A device change (switch / sign-out / sibling sign-in) re-reads the
+            // directory inside `SessionClient` before it notifies, so the snapshot
+            // this rebuilds is already the new one — publish it and reconcile the
+            // auth-readiness edge. No profile fetch: the directory carries the display
+            // metadata a row needs.
             this.emit();
-            void this.ensureProfiles();
             this.reconcileAuth();
         });
         // The access token is planted AFTER `SessionClient.applyState` fires its
@@ -299,9 +299,9 @@ export class AccountDialogController {
             void this.refresh();
             return;
         }
-        // Signed out: the graph is no longer fetchable/switchable — drop it and
-        // re-project from the device session set alone.
-        this.graph = [];
+        // Signed out. The directory is bearer-read and `SessionClient` drops the one
+        // it holds when the device empties, so there is nothing to clear here — only
+        // the in-flight bookkeeping, which no longer describes anything.
         this.error = null;
         this.loading = false;
         this.emit();
@@ -332,157 +332,142 @@ export class AccountDialogController {
         this.setView('signup');
     }
     // =========================================================================
-    // Account list
+    // The directory
     // =========================================================================
     /**
-     * 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.
      */
     async refresh() {
         const seq = ++this.refreshSeq;
-        // Never hit the private `listAccounts()` while signed out: at cold boot the
-        // bearer is not planted yet, so the call 401s → `HttpService` clears the
-        // token and signs the user out. Re-project from the device session set alone
-        // (`projectSwitchableAccounts` works from `SessionClient` state) and stop.
+        // Never read the directory while signed out: at cold boot the bearer is not
+        // planted yet, so the call 401s → `HttpService` clears the token and signs
+        // the user out.
         if (!this.isAuthenticated()) {
-            this.graph = [];
             this.loading = false;
             this.error = null;
             this.emit();
             return;
         }
-        const hadAccounts = this.snapshot.accounts.length > 0;
-        this.loading = !hadAccounts;
+        // Nothing to show yet is the only state worth a spinner; a re-read behind an
+        // already-rendered directory refreshes in place.
+        this.loading = this.sessionClient.getDirectory() === null;
         this.error = null;
         this.emit();
-        let graph = this.graph;
         try {
-            graph = await this.oxyServices.listAccounts();
+            await this.sessionClient.refreshDirectory();
         }
         catch (error) {
-            // A 401 here is the EXPECTED signed-out edge, not a failure: the bearer was
+            // A 401 is the EXPECTED signed-out edge, not a failure: the bearer was
             // stale/revoked, so `HttpService` already cleared it and emitted
-            // `onTokensChanged(null)`, which drops the graph via `reconcileAuth`. Log at
-            // debug and leave the dialog error-free — a signed-out device with zero
-            // accounts is a normal state, not a warning. Any other error (network, 5xx,
-            // malformed) IS unexpected: surface it and warn while keeping the prior graph
-            // so device rows still render.
+            // `onTokensChanged(null)`. Any OTHER error (network, 5xx, malformed) IS
+            // unexpected — surface it, and keep whatever directory is already held so
+            // an outage degrades rather than blanks the switcher.
             if (extractErrorStatus(error) === 401) {
-                logger.debug('[AccountDialogController] listAccounts unauthorized (signed out)', { component: 'AccountDialogController' }, error);
+                logger.debug('[AccountDialogController] directory unauthorized (signed out)', { component: 'AccountDialogController' }, error);
             }
             else {
                 this.error = errorMessage(error);
-                logger.warn('[AccountDialogController] listAccounts failed', { component: 'AccountDialogController' }, error);
+                logger.warn('[AccountDialogController] directory refresh failed', { component: 'AccountDialogController' }, error);
             }
         }
         if (seq !== this.refreshSeq)
             return; // superseded by a newer refresh
-        this.graph = graph;
-        await this.loadProfiles(seq);
-        if (seq !== this.refreshSeq)
-            return;
         this.loading = false;
         this.emit();
     }
+    // =========================================================================
+    // Activation and the two removals (ADR 0002)
+    // =========================================================================
     /**
-     * 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.
      */
-    async ensureProfiles() {
-        // `getUsersByIds` is private — skip the whole path while signed out.
-        if (!this.isAuthenticated())
-            return;
-        const ids = switchableAccountIds(this.sessionClient.getState(), this.graph);
-        if (ids.every((id) => this.profilesById.has(id)))
-            return;
-        await this.loadProfiles(this.refreshSeq);
+    async activateContext(contextId) {
+        if (this.activatingContextId)
+            return false;
+        this.activatingContextId = contextId;
+        this.error = null;
         this.emit();
-    }
-    async loadProfiles(seq) {
-        // `getUsersByIds` (`POST /users/by-ids`) is a private call — never issue it
-        // while signed out (the 401 → sign-out cascade). Callers already gate; this
-        // guards the network chokepoint too (e.g. the token was cleared mid-refresh).
-        if (!this.isAuthenticated())
-            return;
-        const ids = switchableAccountIds(this.sessionClient.getState(), this.graph);
-        if (ids.length === 0)
-            return;
-        let profiles = [];
         try {
-            profiles = await this.oxyServices.getUsersByIds(ids);
+            await this.sessionClient.activateContext(contextId);
+            await this.refresh();
+            return true;
         }
         catch (error) {
-            // A 401 is the EXPECTED signed-out edge (stale/cleared bearer) — log at debug.
-            // `getUsersByIds` already swallows per-chunk failures and returns `[]`, so any
-            // OTHER error here is an unexpected total failure worth a warn. Either way keep
-            // the prior profile map.
-            if (extractErrorStatus(error) === 401) {
-                logger.debug('[AccountDialogController] getUsersByIds unauthorized (signed out)', { component: 'AccountDialogController' }, error);
-            }
-            else {
-                logger.warn('[AccountDialogController] getUsersByIds failed', { component: 'AccountDialogController' }, error);
-            }
-            return;
+            this.error = errorMessage(error);
+            return false;
         }
-        if (seq !== this.refreshSeq)
-            return; // superseded
-        const next = new Map(this.profilesById);
-        for (const profile of profiles) {
-            next.set(profile.id, profile);
+        finally {
+            this.activatingContextId = null;
+            this.emit();
         }
-        this.profilesById = next;
     }
-    // =========================================================================
-    // Switching (uniform switch model — reuses the existing SDK primitives)
-    // =========================================================================
     /**
-     * Switch the active account to `accountId`.
+     * Remove ONE `principal → account` pair, and only that pair.
      *
-     * 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`).
+     * 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.
      *
-     * 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.
+     * 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.
      */
-    async switchTo(accountId) {
-        if (this.switchingAccountId)
+    async signOutContext(contextId) {
+        if (this.removingContextId || this.removingPrincipalId)
             return false;
-        this.switchingAccountId = accountId;
+        this.removingContextId = contextId;
         this.error = null;
         this.emit();
         try {
-            const state = this.sessionClient.getState();
-            const onDevice = state?.accounts.some((account) => account.accountId === accountId) ?? false;
-            if (onDevice) {
-                await this.sessionClient.switchAccount(accountId);
-            }
-            else {
-                const result = await this.oxyServices.switchToAccount(accountId);
-                if (!result?.user || !result?.sessionId) {
-                    throw new Error('Account switch did not return a valid session');
-                }
-                await this.commitAuthorizedSession({
-                    sessionId: result.sessionId,
-                    deviceId: result.deviceId,
-                    expiresAt: result.expiresAt,
-                    user: result.user,
-                    accessToken: result.accessToken,
-                }, result.user, 
-                // A switch is IN-PLACE: use the switch commit funnel (not sign-in).
-                // Cross-tab/app propagation rides the server's `session_state` socket
-                // broadcast, not a navigation.
-                { fromSwitch: true });
-            }
-            // Re-project + refetch immediately; the subscription also fires.
+            await this.sessionClient.signOutContext(contextId);
+            await this.refresh();
+            return true;
+        }
+        catch (error) {
+            this.error = errorMessage(error);
+            return false;
+        }
+        finally {
+            this.removingContextId = null;
+            this.emit();
+        }
+    }
+    /**
+     * Remove ONE PERSON and every context they reach — and nobody else's,
+     * including when another principal independently operates the same account.
+     *
+     * 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.
+     */
+    async signOutPrincipal(principalId) {
+        if (this.removingContextId || this.removingPrincipalId)
+            return false;
+        this.removingPrincipalId = principalId;
+        this.error = null;
+        this.emit();
+        try {
+            await this.sessionClient.signOutPrincipal(principalId);
             await this.refresh();
             return true;
         }
@@ -491,7 +476,7 @@ export class AccountDialogController {
             return false;
         }
         finally {
-            this.switchingAccountId = null;
+            this.removingPrincipalId = null;
             this.emit();
         }
     }
@@ -983,17 +968,10 @@ export 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`.
      */
-    async commitAuthorizedSession(session, user, opts) {
-        const commit = opts?.fromSwitch
-            ? this.commitSwitchedSession ?? this.commitSession
-            : this.commitSession;
-        if (commit) {
-            await commit(session);
+    async commitAuthorizedSession(session, user) {
+        if (this.commitSession) {
+            await this.commitSession(session);
         }
         else {
             await this.sessionClient.registerAndActivate(user.id);
@@ -1113,20 +1091,16 @@ export class AccountDialogController {
         });
     }
     computeSnapshot() {
-        const state = this.sessionClient.getState();
+        const directory = this.sessionClient.getDirectory();
         return {
             view: this.view,
-            accounts: projectSwitchableAccounts({
-                state,
-                graph: this.graph,
-                profilesById: this.profilesById,
-                locale: this.locale,
-                resolveAvatarUrl: (avatar) => (avatar ? this.oxyServices.getFileDownloadUrl(avatar, 'thumb') : undefined),
-            }),
-            activeAccountId: state?.activeAccountId ?? null,
+            directory,
+            activeContext: resolveActiveContext(directory),
             loading: this.loading,
             error: this.error,
-            switchingAccountId: this.switchingAccountId,
+            activatingContextId: this.activatingContextId,
+            removingContextId: this.removingContextId,
+            removingPrincipalId: this.removingPrincipalId,
             signIn: this.signIn,
             commonsAvailability: this.commonsAvailability,
         };

package/dist/esm/session/accountSwitchTargets.js

@@ -0,0 +1,71 @@
+/**
+ * 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 { isActAsEligibleKind } from '@oxyhq/contracts';
+/**
+ * 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 function isSwitchTargetAccount(node) {
+    return node.relationship === 'self' || isActAsEligibleKind(node.kind);
+}
+/**
+ * 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 function canSwitchIntoAccount(node) {
+    if (node.relationship === 'self') {
+        return true;
+    }
+    if (!isSwitchTargetAccount(node)) {
+        return false;
+    }
+    const permissions = node.callerMembership?.permissions;
+    if (permissions) {
+        return permissions.includes('account:act_as');
+    }
+    return node.relationship === 'owner';
+}

package/dist/esm/session/deviceDirectory.js

@@ -0,0 +1,135 @@
+import { getAccountDisplayName } from '../utils/accountUtils.js';
+import { getNormalizedUserHandle } from '../utils/userHandle.js';
+/** Resolve one wire context under the principal it hangs off. */
+function toDeviceContext(principal, context) {
+    return {
+        contextId: context.id,
+        actor: {
+            principalId: principal.id,
+            userId: principal.userId,
+            authuser: principal.authuser,
+            profile: principal.user,
+        },
+        subject: {
+            accountId: context.accountId,
+            kind: context.kind,
+            relationship: context.relationship,
+            profile: context.account,
+            onDevice: context.onDevice,
+            available: context.available,
+            lastUsedAt: context.lastUsedAt,
+        },
+        isDelegated: context.accountId !== principal.userId,
+    };
+}
+/**
+ * Resolve one context by its id.
+ *
+ * The search is over `(principal, context)` PAIRS, not over accounts: the same
+ * `accountId` legitimately appears under two principals on a shared device, and
+ * matching on the account would hand back whichever person happened to be
+ * enumerated first.
+ */
+export function resolveDeviceContext(directory, contextId) {
+    if (directory === null) {
+        return null;
+    }
+    for (const principal of directory.principals) {
+        for (const context of principal.contexts) {
+            if (context.id === contextId) {
+                return toDeviceContext(principal, context);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * The directory as the switcher renders it: people, each with what they may
+ * become.
+ *
+ * A principal with no contexts is kept rather than dropped. It is a real state
+ * — a person whose every context was removed while they remain on the device —
+ * and rendering them with nothing under them is how "sign out of this person"
+ * stays reachable. Silently omitting them would strand the row.
+ */
+export function projectDevicePrincipals(directory) {
+    if (directory === null) {
+        return [];
+    }
+    return directory.principals.map((principal) => ({
+        principalId: principal.id,
+        userId: principal.userId,
+        authuser: principal.authuser,
+        profile: principal.user,
+        contexts: principal.contexts.map((context) => toDeviceContext(principal, context)),
+        isActive: directory.activeContextId !== null &&
+            principal.contexts.some((context) => context.id === directory.activeContextId),
+    }));
+}
+/**
+ * The device's active context, or `null`.
+ *
+ * `null` is a real state, not an error: a device with every context removed, or
+ * one whose active context was healed away, has none. It is also the answer when
+ * `activeContextId` names a row no principal holds — a directory that
+ * disagreed with itself, which resolves to "nothing is active" rather than to a
+ * guess.
+ */
+export function resolveActiveContext(directory) {
+    if (directory === null || directory.activeContextId === null) {
+        return null;
+    }
+    return resolveDeviceContext(directory, directory.activeContextId);
+}
+/**
+ * The name a directory row renders: the API's `displayName` when it has one,
+ * otherwise the normalized handle, otherwise the localized unnamed sentinel.
+ *
+ * The identity contract's `displayName ?? handle`, and deliberately not
+ * `getAccountDisplayName`'s multi-field chain — that one is for LOCAL account
+ * surfaces, and the directory profile is an API DTO whose `name.displayName`
+ * the server already composed or deliberately omitted. `getAccountDisplayName`
+ * appears here only for its `null` case, which is the sentinel.
+ */
+export function directoryDisplayName(profile, locale) {
+    const displayName = profile.name?.displayName?.trim();
+    if (displayName) {
+        return displayName;
+    }
+    return getNormalizedUserHandle(profile) ?? getAccountDisplayName(null, locale);
+}
+/**
+ * A directory row's `@handle`, or `null` when the profile carries no usable
+ * username.
+ *
+ * The directory profile has no email — by design, it is the minimum that
+ * renders a row — so the handle is the secondary line, never a synthesized
+ * `username@oxy.so` address.
+ */
+export function directoryHandle(profile) {
+    return getNormalizedUserHandle(profile);
+}
+/**
+ * Whether a switcher may offer this row — the one question it asks, answered
+ * here so no surface has to re-derive it.
+ *
+ * It is deliberately a single field. `available` is the server's complete
+ * verdict (see {@link DeviceContextSubject.available}), and switchability is an
+ * authorization question the client must READ, never recompute; this exists to
+ * name the field that answers it, not to combine several.
+ *
+ * `onDevice` is NOT part of the question and composing the two is the mistake
+ * this function exists to prevent, in both directions. `onDevice: false` is an
+ * ordinary reachable context whose session is minted on first activation, so
+ * requiring it hides every organization the person has not used here yet.
+ * `onDevice: true` does not imply activatable either: when a principal's own
+ * personal session dies, their delegated contexts keep live sessions of their
+ * own and still cannot be activated, so `available || onDevice` would render a
+ * row the server answers with 403 and then heals away.
+ *
+ * Takes a structural subset so a caller holding a raw `DeviceAccountContext`
+ * from the wire can ask it without resolving the pair first.
+ */
+export function canActivateContext(context) {
+    return context.available;
+}