@oxy.so/core 1.0.0

package/dist/esm/session/SessionClient.js

@@ -0,0 +1,861 @@
+import { deviceActivateResponseSchema, deviceDirectorySchema, deviceDirectorySyncSchema, deviceSessionStateSchema, deviceSessionSyncSchema, safeParseContract, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedEventSchema, } from '@oxy.so/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
+ * propagation across tabs of the SAME origin (e.g. two `accounts.oxy.so` tabs):
+ * when one authenticated tab commits an account switch / sign-out, siblings
+ * re-sync their device state without waiting on the socket. Cross-origin
+ * same-apex propagation rides the authenticated device socket; cross-APEX
+ * (mention.earth) relies on a reload — the documented limitation.
+ */
+const SESSION_BROADCAST_CHANNEL = 'oxy.session';
+export class SessionClient {
+    constructor(host, options = {}) {
+        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;
+        /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
+        this.channel = null;
+        /** App-facing subscriptions to named server-pushed socket events. */
+        this.serverEvents = new Map();
+        /** Event names already bound on the CURRENT socket instance. */
+        this.boundServerEvents = new Set();
+    }
+    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
+     * synchronous read of already-resolved state (see
+     * {@link SessionClientOptions.getPinnedAccountId}).
+     */
+    pinnedAccountId() {
+        return this.options.getPinnedAccountId?.() ?? null;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            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
+     * unsubscribes. Payloads are delivered as-is — callers validate shape.
+     */
+    onServerEvent(event, listener) {
+        let listeners = this.serverEvents.get(event);
+        if (!listeners) {
+            listeners = new Set();
+            this.serverEvents.set(event, listeners);
+        }
+        listeners.add(listener);
+        this.bindServerEvent(event);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    bindServerEvent(event) {
+        if (!this.socket || this.boundServerEvents.has(event))
+            return;
+        this.boundServerEvents.add(event);
+        this.socket.on(event, (payload) => {
+            const listeners = this.serverEvents.get(event);
+            if (!listeners)
+                return;
+            for (const listener of [...listeners]) {
+                try {
+                    listener(payload);
+                }
+                catch (error) {
+                    logger.warn('[SessionClient] server-event listener threw', { component: 'SessionClient' }, error);
+                }
+            }
+        });
+    }
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener(this.state);
+            }
+            catch (error) {
+                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.
+     *
+     * `activeToken` (sync path only) is the server-issued access token for
+     * `raw.activeAccountId`. When present and the state is applied, it is planted
+     * BEFORE any subscriber is notified so the bearer already belongs to the new
+     * active account — the local switch/bootstrap path then needs no redundant
+     * device-secret mint. Push-origin applies carry no token and rely on the
+     * mint-before-notify gate below.
+     *
+     * ORDERING INVARIANT: a subscriber must NEVER observe a newly-active account
+     * while the planted bearer still identifies the PREVIOUS one — otherwise a
+     * `useCurrentUser`-style refetch fires under the wrong account's token (the
+     * account-switch 404 race). So when a transport is available and the planted
+     * bearer does not already belong to `next.activeAccountId`, minting is awaited
+     * BEFORE `notify()`. This covers EVERY notify source (a switch push, a
+     * cross-device push, a cold mint), not just the initial "no bearer yet" case.
+     */
+    applyState(raw, origin = 'push', activeToken) {
+        const next = safeParseContract(deviceSessionStateSchema, raw);
+        if (!next) {
+            logger.warn('[SessionClient] discarded invalid session state');
+            return false;
+        }
+        // The revision is monotone ONLY within a single deviceId. When the incoming
+        // state belongs to a DIFFERENT device than the currently-applied one, reset
+        // the baseline and accept it regardless of revision: a freshly-converged
+        // device (low revision) must not lose last-writer-wins to a stale, higher-
+        // revision state from a retired device. Only when the deviceIds MATCH is the
+        // `revision <= current` guard a valid staleness check.
+        if (this.state &&
+            next.deviceId === this.state.deviceId &&
+            next.revision <= this.state.revision) {
+            return false;
+        }
+        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
+        // account when subscribers observe it. Guarded on difference to avoid a
+        // redundant token-change notification on an unchanged token (bootstrap
+        // restate). An identity-bound client only accepts it when the active account
+        // IS its pinned account — otherwise the token belongs to somebody else's
+        // switch and must never displace the pinned bearer.
+        if (activeToken &&
+            next.activeAccountId !== null &&
+            (pinnedAccountId === null || next.activeAccountId === pinnedAccountId) &&
+            activeToken !== this.host.getAccessToken()) {
+            this.host.setTokens(activeToken);
+        }
+        // The transport's entire job is converging the bearer on `activeAccountId`,
+        // which is precisely what an identity-bound client must not do: its token is
+        // minted for the pinned account by the cold boot / re-mint lane. Bypass it
+        // while pinned (also removing the mint-before-notify gate, which exists only
+        // to keep the bearer and the ACTIVE account in step).
+        const transport = pinnedAccountId === null ? this.options.transport : null;
+        const activeAccountId = next.activeAccountId;
+        // Mint before notifying when the bearer does not already belong to the new
+        // active account: no bearer at all, an opaque bearer, OR a bearer for a
+        // DIFFERENT account. `computeIdentityTag` yields the token's `userId`/`id`
+        // for a real JWT (comparable to the account id) and a non-account sentinel
+        // otherwise, so a mismatch always resolves to "mint".
+        const needsMintBeforeNotify = transport != null &&
+            next.accounts.length > 0 &&
+            (activeAccountId === null || computeIdentityTag(this.host.getAccessToken()) !== activeAccountId);
+        const publish = () => {
+            this.notify();
+            if (next.accounts.length === 0 && this.options.onUnauthenticated) {
+                try {
+                    this.options.onUnauthenticated(origin);
+                }
+                catch (error) {
+                    logger.error('[SessionClient] onUnauthenticated threw', error);
+                }
+            }
+        };
+        // 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);
+                // Do NOT notify under a mismatched bearer. Revert to the last applied
+                // state so subscribers keep observing the account whose token is planted.
+                this.state = previousState ?? null;
+            });
+        }
+        else {
+            if (transport) {
+                void transport.ensureActiveToken(next).catch((error) => {
+                    logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+                });
+            }
+            finishApply();
+        }
+        return true;
+    }
+    /**
+     * Validate `{ state, activeToken }`, apply the state, and plant the active token host-side.
+     * Token-planting is decoupled from whether `applyState` advanced the revision: a socket push
+     * followed by this same `GET /state` fetch returns the SAME revision (applyState no-ops), but
+     * the token still needs to be planted. The account-match guard rejects a stale response for an
+     * account that is no longer active.
+     */
+    applySync(raw) {
+        const sync = safeParseContract(deviceSessionSyncSchema, raw);
+        if (!sync) {
+            const parsed = deviceSessionSyncSchema.safeParse(raw);
+            // Log field-level type diagnostics ONLY — never values. The payload carries tokens and
+            // session ids; issue.path/code and the invalid_type expected/received TYPE names are safe,
+            // but zod messages can embed offending values for other codes, so they are omitted.
+            const issues = parsed.success
+                ? []
+                : parsed.error.issues.map((issue) => issue.code === 'invalid_type'
+                    ? { path: issue.path.join('.'), code: issue.code, expected: issue.expected, received: issue.received }
+                    : { path: issue.path.join('.'), code: issue.code });
+            const keys = raw && typeof raw === 'object' ? Object.keys(raw) : [];
+            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
+        // planted BEFORE notify (bearer matches the new active account when
+        // subscribers observe it, and no redundant device-secret mint is triggered).
+        const applied = this.applyState(sync.state, 'request', sync.activeToken?.accessToken);
+        // Equal-revision restate (this revision was already applied by a preceding
+        // socket push): `applyState` no-ops without planting, but the token still
+        // needs planting. Guard on the sync's active account STILL being the current
+        // active account so a stale response cannot adopt a token for an account a
+        // newer state already switched away from — and, when pinned, on that account
+        // being the PINNED one (same rule as the applied path in `applyState`).
+        const pinnedAccountId = this.pinnedAccountId();
+        if (!applied &&
+            sync.activeToken &&
+            this.state &&
+            sync.state.activeAccountId !== null &&
+            sync.state.activeAccountId === this.state.activeAccountId &&
+            (pinnedAccountId === null || sync.state.activeAccountId === pinnedAccountId) &&
+            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);
+    }
+    /**
+     * Adopt server-authoritative state already returned by another session
+     * endpoint. This avoids immediately re-reading `/session/device/state` after
+     * a successful device-token mint while preserving the same validation,
+     * revision ordering and notification path as `bootstrap()`.
+     */
+    adoptState(state) {
+        return this.applyState(state, 'request');
+    }
+    /**
+     * 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);
+        this.postCommitPing();
+    }
+    /**
+     * Register the just-signed-in account into the device set AND make it the
+     * ACTIVE account — the explicit user-intent activation a sign-in UI performs.
+     *
+     * `addCurrentAccount` alone honors the server's `activate:'if-empty'` policy
+     * (a new account does NOT steal focus from an already-active one), which is
+     * correct for a background/silent add but wrong right after a deliberate
+     * sign-in. This adds, then switches to the target so the UI lands on the
+     * account the user just authenticated.
+     *
+     * An identity-bound (pinned) client only ADDS: its own session is minted for
+     * the pinned account explicitly, so switching the device would gratuitously
+     * re-elect the active account under every OTHER app on this device — a
+     * mutation a pinned client must never make.
+     *
+     * @param accountId - The signed-in account id (e.g. `session.user.id`). When
+     *   omitted, falls back to the host's current-account ref. If neither
+     *   resolves, the add still applies and no switch is performed.
+     */
+    async registerAndActivate(accountId) {
+        await this.addCurrentAccount();
+        if (this.pinnedAccountId() !== null)
+            return;
+        const target = accountId ?? this.host.getCurrentAccountId();
+        if (target && this.state?.activeAccountId !== target) {
+            await this.switchAccount(target);
+        }
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.tokenUnsub = this.host.onTokensChanged((token) => {
+            // A rotated/fresh bearer landed — reconnect a dropped socket so its
+            // handshake re-runs with the current token. Sign-out (null token) keeps
+            // the device-scoped socket when a device credential is available.
+            if (!this.socket)
+                return;
+            if (token) {
+                if (!this.socket.connected) {
+                    this.socket.connect();
+                }
+                return;
+            }
+            const cred = this.host.getDeviceCredential();
+            if (cred && !this.socket.connected) {
+                this.socket.connect();
+            }
+        });
+        this.openBroadcastChannel();
+        // Device-scoped socket: bearer when authenticated, else deviceId+deviceSecret so
+        // signed-out tabs still receive `session_state` and can mint on change.
+        if (this.host.getAccessToken()) {
+            try {
+                await this.bootstrap();
+            }
+            catch (error) {
+                logger.warn('[SessionClient] bootstrap during start failed (non-fatal)', { component: 'SessionClient' }, error);
+            }
+        }
+        await this.connectSocket();
+    }
+    stop() {
+        this.started = false;
+        if (this.tokenUnsub) {
+            this.tokenUnsub();
+            this.tokenUnsub = null;
+        }
+        if (this.channel) {
+            this.channel.onmessage = null;
+            try {
+                this.channel.close();
+            }
+            catch (error) {
+                logger.debug('[SessionClient] BroadcastChannel close failed', { component: 'SessionClient' }, error);
+            }
+            this.channel = null;
+        }
+        if (this.socket) {
+            this.socket.disconnect();
+            this.socket = null;
+            this.boundServerEvents.clear();
+        }
+    }
+    async connectSocket() {
+        // Prefer a statically-injected factory (services/auth-sdk bundle
+        // socket.io-client as a real dep); fall back to the lazy loader — and warn
+        // if THAT yields nothing — only when no factory was injected.
+        const io = this.options.socketFactory ?? (await getSocketIO());
+        if (!io) {
+            logger.warn('[SessionClient] no socket.io-client; running REST-only (no realtime sync)', { component: 'SessionClient' });
+            return;
+        }
+        if (!this.started)
+            return; // stopped while the dynamic import was in flight
+        const token = this.host.getAccessToken();
+        const deviceCredential = this.host.getDeviceCredential();
+        if (!token && !deviceCredential)
+            return;
+        const socket = io(this.host.getBaseURL(), {
+            transports: ['websocket'],
+            autoConnect: true,
+            reconnection: true,
+            reconnectionAttempts: Number.POSITIVE_INFINITY,
+            reconnectionDelay: 1000,
+            reconnectionDelayMax: 10000,
+            auth: (cb) => {
+                const bearer = this.host.getAccessToken();
+                if (bearer) {
+                    cb({ token: bearer });
+                    return;
+                }
+                const cred = this.host.getDeviceCredential();
+                if (cred) {
+                    cb({ deviceId: cred.deviceId, deviceSecret: cred.deviceSecret });
+                    return;
+                }
+                cb({ token: '' });
+            },
+        });
+        socket.on('session_state', (payload) => {
+            // A socket broadcast is a `push`-origin — potentially transient, so an
+            // empty state here must not erase the durable device credential.
+            const applied = this.applyState(payload, 'push');
+            if (!applied)
+                return;
+            // An identity-bound client tracks the pushed state but NEVER chases the
+            // device's active account: re-fetching here would only pull an
+            // `activeToken` for somebody else's switch, which the plant guards would
+            // then discard. Skip the round-trip entirely.
+            if (this.pinnedAccountId() !== null)
+                return;
+            // A push changed the active account on another device/tab — re-fetch state
+            // to plant the access token for the newly-active account. When this tab is
+            // still signed out, applyState mints via ensureActiveToken first; bootstrap
+            // requires a bearer and must not run until then.
+            const active = this.state?.activeAccountId ?? null;
+            if (active && active !== this.host.getCurrentAccountId() && this.host.getAccessToken()) {
+                void this.bootstrap().catch((error) => {
+                    logger.warn('[SessionClient] post-push token fetch failed', { component: 'SessionClient' }, error);
+                });
+            }
+        });
+        socket.on(SESSION_ACCOUNTS_CHANGED_EVENT, (payload) => {
+            this.onSessionAccountsChanged(payload);
+        });
+        this.socket = socket;
+        // (Re)bind app-facing server-event subscriptions on the fresh socket.
+        this.boundServerEvents.clear();
+        for (const event of this.serverEvents.keys()) {
+            this.bindServerEvent(event);
+        }
+    }
+    /**
+     * Handle the token-free `session_accounts_changed` signal (room `user:<userId>`).
+     *
+     * Unlike `session_state` (device-scoped, carries the new state to APPLY), this
+     * reaches ALL of a user's connected sockets across their devices/origins and is
+     * a pure SIGNAL: it carries no token, no secret, and no account bodies. The only
+     * trustworthy bit is "something changed for this user", so — matching the
+     * `session_state` contract's guidance — we re-fetch our OWN authoritative device
+     * state (`bootstrap` → `GET /session/device/state`) and let the existing
+     * `applyState` revision guard reconcile it. We never trust any field on the event
+     * beyond routing it to the current user.
+     *
+     * The refetch is a private (bearer) call: the socket only joins `user:<userId>`
+     * when authenticated, so a signed-out client never receives this — but we guard
+     * the bearer anyway so a race at sign-out can't 401.
+     */
+    onSessionAccountsChanged(payload) {
+        const event = safeParseContract(sessionAccountsChangedEventSchema, payload);
+        if (!event) {
+            logger.warn('[SessionClient] discarded invalid session_accounts_changed', { component: 'SessionClient' });
+            return;
+        }
+        // The socket is in `user:<activeUserId>` for the planted bearer, so this should
+        // always be the current user; ignore a foreign id defensively (out-of-band relay).
+        if (event.userId !== this.host.getCurrentAccountId())
+            return;
+        if (!this.host.getAccessToken())
+            return;
+        void this.bootstrap().catch((error) => {
+            logger.warn('[SessionClient] session_accounts_changed refetch failed', { component: 'SessionClient' }, error);
+        });
+    }
+    /**
+     * Open the same-origin `BroadcastChannel` (web only). A sibling tab that
+     * commits an account switch / sign-out posts a wake ping; on receipt an
+     * authenticated tab re-syncs its device state — instant + network-free for the
+     * common "two tabs of the same origin" case, with no state (and no tokens)
+     * ever crossing the channel. No-op on native (no BroadcastChannel).
+     */
+    openBroadcastChannel() {
+        if (this.channel)
+            return;
+        const Ctor = globalThis.BroadcastChannel;
+        if (typeof Ctor !== 'function')
+            return; // native RN / SSR — feature absent
+        let channel;
+        try {
+            channel = new Ctor(SESSION_BROADCAST_CHANNEL);
+        }
+        catch (error) {
+            logger.debug('[SessionClient] BroadcastChannel unavailable', { component: 'SessionClient' }, error);
+            return;
+        }
+        channel.onmessage = (event) => {
+            if (!event || typeof event.data !== 'object' || event.data === null)
+                return;
+            if (event.data.type !== 'commit')
+                return;
+            // BroadcastChannel never echoes to the posting context, so this is a
+            // sibling's commit. An authenticated tab re-syncs its device state; the
+            // re-sync does not re-post, so there is no cross-tab ping loop.
+            if (this.host.getAccessToken()) {
+                void this.bootstrap().catch((error) => {
+                    logger.warn('[SessionClient] broadcast re-sync failed', { component: 'SessionClient' }, error);
+                });
+            }
+        };
+        this.channel = channel;
+    }
+    /**
+     * Wake same-origin sibling tabs after a locally-initiated session mutation.
+     * Opens the channel lazily: a sign-in registers the account (`addCurrentAccount`
+     * / `switchAccount`) BEFORE `start()` runs, so the ping must not depend on
+     * `start()` having opened the channel first.
+     */
+    postCommitPing() {
+        this.openBroadcastChannel();
+        if (!this.channel)
+            return;
+        try {
+            this.channel.postMessage({ type: 'commit', at: Date.now() });
+        }
+        catch (error) {
+            logger.debug('[SessionClient] BroadcastChannel post failed', { component: 'SessionClient' }, error);
+        }
+    }
+}