@oxyhq/core 20.1.0 → 21.0.0

package/dist/esm/session/SessionClient.js

@@ -1,6 +1,7 @@
-import { deviceSessionStateSchema, deviceSessionSyncSchema, safeParseContract, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedEventSchema, } from '@oxyhq/contracts';
+import { deviceActivateResponseSchema, deviceDirectorySchema, deviceDirectorySyncSchema, deviceSessionStateSchema, deviceSessionSyncSchema, safeParseContract, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedEventSchema, } from '@oxyhq/contracts';
 import { logger } from '../logger/index.js';
 import { computeIdentityTag } from '../utils/cacheKey.js';
+import { resolveActiveContext } from './deviceDirectory.js';
 import { getSocketIO } from './socketLoader.js';
 /**
  * Same-origin `BroadcastChannel` name for instant, network-free session-state
@@ -16,7 +17,20 @@ export class SessionClient {
         this.host = host;
         this.options = options;
         this.state = 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.
+         */
+        this.directory = null;
         this.listeners = new Set();
+        this.directoryListeners = new Set();
         this.socket = null;
         this.tokenUnsub = null;
         this.started = false;
@@ -30,6 +44,25 @@ export class SessionClient {
     getState() {
         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() {
+        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() {
+        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
@@ -45,6 +78,19 @@ export class SessionClient {
             this.listeners.delete(listener);
         };
     }
+    /**
+     * 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) {
+        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
@@ -89,6 +135,14 @@ 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);
+            }
+        }
     }
     /**
      * Validate + last-writer-wins by revision. Returns true if applied.
@@ -127,6 +181,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
@@ -156,7 +217,7 @@ export class SessionClient {
         const needsMintBeforeNotify = transport != null &&
             next.accounts.length > 0 &&
             (activeAccountId === null || computeIdentityTag(this.host.getAccessToken()) !== activeAccountId);
-        const finishApply = () => {
+        const publish = () => {
             this.notify();
             if (next.accounts.length === 0 && this.options.onUnauthenticated) {
                 try {
@@ -167,6 +228,21 @@ 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 = () => {
+            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);
@@ -208,6 +284,19 @@ 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.
+     */
+    commitSync(sync) {
         // 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
@@ -230,21 +319,292 @@ export class SessionClient {
             sync.activeToken.accessToken !== this.host.getAccessToken()) {
             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.
+     */
+    applyDirectory(raw) {
+        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. */
+    async fetchDirectory() {
+        const res = await this.host.makeRequest('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.
+     */
+    settleDirectory(state) {
+        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) => {
+            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.
+     */
+    knownRevisionFor(deviceId) {
+        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.
+     */
+    plantActiveContextToken(directory, accessToken) {
+        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.
+     */
+    async reconcileFlatState(directory) {
+        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() {
         const res = await this.host.makeRequest('GET', '/session/device/state', undefined, { cache: false });
         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() {
+        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) {
+        const res = await this.host.makeRequest('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) {
         const res = await this.host.makeRequest('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) {
         const res = await this.host.makeRequest('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) {
+        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) {
+        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.
+     */
+    async removeFromDevice(target) {
+        const res = await this.host.makeRequest('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() {
         const res = await this.host.makeRequest('POST', '/session/device/add', undefined, { cache: false });
         this.applySync(res);