@oxy.so/core 4.1.0 → 4.3.0

package/dist/esm/server/auth.js

@@ -25,6 +25,24 @@ export function getOxyUserId(req) {
         normalizeId(authReq.user?.id) ??
         normalizeId(authReq.user?._id));
 }
+/**
+ * Who acted, and as whom, on this user session (issue #1520), or `null` when
+ * the session authority did not report it.
+ *
+ * An audit records `actorAccountId` as the actor and `effectiveAccountId`
+ * (equal to {@link getOxyUserId}) as the account spoken as. A bot acting with
+ * nobody operating it is its own actor; a person acting as an organization or
+ * a bot is the actor of a `delegated` chain. Never substitute the effective
+ * account's owner for either: when this is `null`, record the actor as unknown.
+ */
+export function getOxyActor(req) {
+    const actor = req.oxyActor;
+    if (!actor)
+        return null;
+    // Defence in depth: a chain that does not describe the authenticated
+    // subject is not this request's chain.
+    return actor.effectiveAccountId === getOxyUserId(req) ? actor : null;
+}
 export function isOxyAuthenticated(req) {
     return getOxyUserId(req) !== null;
 }

package/dist/esm/server/capabilityTicket.js

@@ -21,45 +21,6 @@ function decodeJsonSegment(segment) {
         throw new CapabilityTicketError('malformed', 'Capability ticket is not valid base64url JSON');
     }
 }
-function valuesAtPath(input, path) {
-    let current = [input];
-    for (const segment of path.split('.')) {
-        const next = [];
-        for (const value of current) {
-            const records = Array.isArray(value) ? value : [value];
-            for (const record of records) {
-                if (typeof record !== 'object' || record === null || Array.isArray(record))
-                    continue;
-                if (Object.prototype.hasOwnProperty.call(record, segment)) {
-                    next.push(record[segment]);
-                }
-            }
-        }
-        if (next.length === 0)
-            return [];
-        current = next;
-    }
-    return current.flatMap((value) => Array.isArray(value) ? value : [value]);
-}
-/** Enforces the signed per-action bounds before a domain handler runs. */
-export function inputSatisfiesCapabilityLimits(tool, input, limits) {
-    for (const limit of limits) {
-        if (limit.tool !== tool)
-            return false;
-        const actualValues = valuesAtPath(input, limit.key);
-        if (actualValues.length === 0)
-            return false;
-        if (typeof limit.value === 'number') {
-            const maximum = limit.value;
-            if (!actualValues.every((actual) => (typeof actual === 'number' && Number.isFinite(actual) && actual <= maximum)))
-                return false;
-            continue;
-        }
-        if (!actualValues.every((actual) => actual === limit.value))
-            return false;
-    }
-    return true;
-}
 export function issueCapabilityTicket(claims, options) {
     const ttlSeconds = options.ttlSeconds ?? 60;
     if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > DEFAULT_MAX_TTL_SECONDS) {
@@ -181,3 +142,4 @@ export function createCapabilityTicketMiddleware(options) {
         }
     };
 }
+export { inputSatisfiesCapabilityLimits } from '@oxy.so/contracts';

package/dist/esm/server/index.js

@@ -19,7 +19,7 @@
 export { OxyServer, ServiceCredentialMismatchError, ANONYMOUS_SERVICE_TOKEN_RETRY_MS } from './OxyServer.js';
 export { ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi, } from './namespaces.js';
 export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './middleware.js';
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth.js';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyActor, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth.js';
 export { createOxyRateLimit } from './rateLimit.js';
 // SSRF-safe upstream fetch + URL validation (Node-only).
 export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch.js';
@@ -40,6 +40,7 @@ export { CapabilityTicketError, createCapabilityTicketMiddleware, inputSatisfies
 export { createOxyJwksKeyResolver, createOxyRequesterAssertionAuth, OXY_REQUESTER_ASSERTION_DEFAULT_ISSUER, OXY_REQUESTER_ASSERTION_HEADER, OXY_REQUESTER_ASSERTION_MAX_TTL_SECONDS, OXY_REQUESTER_ASSERTION_TYPE, OxyRequesterAssertionError, oxyRequesterAssertionClaimsSchema, readOxyRequesterAssertionKeyId, signOxyRequesterAssertion, verifyOxyRequesterAssertion, } from './requesterAssertion.js';
 // Constant-time secret comparison.
 export { verifySecret } from './verifySecret.js';
+export { createLiveCapabilityTicketVerifier } from './liveCapabilityTicket.js';
 // Cross-service user-invalidation signal: oxy-api publishes when identity
 // changes, every consuming backend sweeps its caches instead of waiting out a TTL.
 export { createOxyUserInvalidationHandler, publishOxyUserInvalidation, } from './userInvalidation.js';
@@ -62,3 +63,5 @@ export { observeNodeHttp, withoutNodeHttpObservation } from './trafficNodeHttp.j
  * container credentials endpoint.
  */
 export { canAttestWorkloadIdentity, requestWorkloadServiceToken } from './workloadIdentity.js';
+export { OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS, hasBoundedServiceTokenLifetime } from './serviceTokenLifetime.js';
+export { signInAgentAccount } from './agentAccount.js';

package/dist/esm/server/liveCapabilityTicket.js

@@ -0,0 +1,45 @@
+import { canonicalCapabilityJson, capabilityTicketClaimsSchema } from '@oxy.so/contracts';
+import { verifyCapabilityTicket } from './capabilityTicket.js';
+/** Local signature + live receiving-service introspection; no cache or retry. */
+export function createLiveCapabilityTicketVerifier(options) {
+    if (typeof options.issuer !== 'string' || options.issuer.trim() === '')
+        throw new Error('A trusted Capability issuer is required');
+    const timeoutMs = options.timeoutMs ?? 5000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60000) {
+        throw new Error('Capability introspection timeout must be between 1 and 60000ms');
+    }
+    return async (ticket, input = {}) => {
+        input.signal?.throwIfAborted();
+        const signed = verifyCapabilityTicket(ticket, options);
+        if (!signed.catalog)
+            throw new Error('Internal MCP requires a signed catalogue binding');
+        const controller = new AbortController();
+        const abort = () => controller.abort(input.signal?.reason);
+        input.signal?.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(() => controller.abort(new Error('Capability introspection timed out')), timeoutMs);
+        let rejectAbort;
+        try {
+            const interrupted = new Promise((_resolve, reject) => {
+                rejectAbort = () => reject(controller.signal.reason ?? new Error('Capability introspection aborted'));
+                controller.signal.addEventListener('abort', rejectAbort, { once: true });
+                if (controller.signal.aborted)
+                    rejectAbort();
+            });
+            const result = await Promise.race([options.introspect(ticket, { signal: controller.signal }), interrupted]);
+            controller.signal.throwIfAborted();
+            if (result.active !== true)
+                throw new Error('Capability ticket is inactive');
+            const live = capabilityTicketClaimsSchema.parse(result.claims);
+            if (canonicalCapabilityJson(live) !== canonicalCapabilityJson(signed))
+                throw new Error('Capability introspection claims mismatch');
+            // An authority response delayed past expiry cannot extend the signed grant.
+            return verifyCapabilityTicket(ticket, options);
+        }
+        finally {
+            clearTimeout(timer);
+            input.signal?.removeEventListener('abort', abort);
+            if (rejectAbort)
+                controller.signal.removeEventListener('abort', rejectAbort);
+        }
+    };
+}

package/dist/esm/server/middleware.js

@@ -1,3 +1,5 @@
+import { hasBoundedServiceTokenLifetime } from './serviceTokenLifetime.js';
+import { accountActorChainSchema } from '@oxy.so/contracts';
 import { jwtDecode } from 'jwt-decode';
 import { loadNodeCrypto } from '@oxy.so/protocol';
 import { logger } from '../logger/index.js';
@@ -405,22 +407,18 @@ export function createOxyMiddleware(host) {
                             return onError(error);
                         return res.status(401).json(error);
                     }
-                    // One of Oxy's own applications acts for a user without a grant:
-                    // inside the ecosystem that is trust, not consent. It still acts
-                    // with the USER's authority only — what that user may do is for the
-                    // receiving service to check.
-                    if (oxyUserId && tier === 'internal') {
-                        req.userId = oxyUserId;
-                        req.user = { id: oxyUserId };
-                        req.serviceActingAs = { userId: oxyUserId, scopes: [] };
-                    }
-                    else if (oxyUserId) {
-                        // C3: an EXTERNAL service may only act as a user when an explicit
+                    // A service credential plus a user header is never a present user
+                    // session, even for an internal tier. Offline delegation is explicit.
+                    if (oxyUserId) {
+                        // C3: every service may only act as a user when an explicit
                         // ServiceActingAs grant exists for that (appId, userId) pair.
                         // Without the grant we MUST refuse — silently attaching
                         // `req.userId = oxyUserId` would let any service impersonate
                         // any user simply by setting the header.
-                        const grant = await host.verifyActingAs(appId, oxyUserId);
+                        const grant = await host.verifyActingAs(appId, oxyUserId, {
+                            cache: false, credentialId: decoded.credentialId,
+                            ownerAccountId: decoded.ownerAccountId, environment: decoded.environment,
+                        });
                         if (!grant || !grant.authorized) {
                             logger.warn('[oxy.auth] Service token rejected — no delegation grant', {
                                 component: 'auth',
@@ -640,7 +638,43 @@ export function createOxyMiddleware(host) {
                             return onError(error);
                         return res.status(401).json(error);
                     }
+                    // Who acted, and as whom — from the session authority's answer
+                    // (#1520), never from a header or this undecoded token. An API that
+                    // predates the field answers without it, and that is `null` here:
+                    // "not reported", never a guess that the subject acted for itself.
+                    // A chain naming a DIFFERENT effective account than the session
+                    // resolved to has no benign cause and is refused like a user
+                    // mismatch.
+                    const actor = readActorChain(validationResult.actor);
+                    if (actor === 'invalid' || (actor && actor.effectiveAccountId !== validatedUserId)) {
+                        logger.warn('[oxy.auth] Session rejected — actor chain does not describe the session', {
+                            component: 'auth',
+                            method: 'auth',
+                            validatedUserId,
+                        });
+                        recordRefusal(req, {
+                            code: 'SESSION_ACTOR_MISMATCH',
+                            stage: 'session',
+                            reason: 'Session actor chain does not describe the validated session',
+                            status: 401,
+                        });
+                        if (optional) {
+                            req.userId = null;
+                            req.user = null;
+                            return next();
+                        }
+                        const error = {
+                            error: 'SESSION_ACTOR_MISMATCH',
+                            message: 'Session actor does not match the session',
+                            code: 'SESSION_ACTOR_MISMATCH',
+                            status: 401
+                        };
+                        if (onError)
+                            return onError(error);
+                        return res.status(401).json(error);
+                    }
                     req.userId = validatedUserId;
+                    req.oxyActor = actor;
                     req.accessToken = token;
                     req.sessionId = sessionId;
                     // Session validation already returned the full user, so `loadUser`
@@ -902,12 +936,6 @@ export function createOxyMiddleware(host) {
                 });
                 return;
             }
-            // Oxy's own applications are trusted app to app; scopes are the
-            // external lane.
-            if (req.serviceApp.tier === 'internal') {
-                next();
-                return;
-            }
             const appHasScope = appScopes.includes(scope);
             const delegationHasScope = delegatedScopes.includes(scope);
             const hasRequiredScope = req.serviceActingAs
@@ -1123,6 +1151,9 @@ function getUserIdentityId(user) {
  * service token because no claim binding existed.
  */
 function verifyServiceTokenClaims(decoded, expected) {
+    if (!hasBoundedServiceTokenLifetime(decoded)) {
+        throw new ServiceTokenClaimError('Service token lifetime must be positive and at most 300 seconds');
+    }
     if (decoded.type !== 'service') {
         throw new ServiceTokenClaimError(`Service token has unexpected type '${String(decoded.type)}'`);
     }
@@ -1139,3 +1170,14 @@ function verifyServiceTokenClaims(decoded, expected) {
         throw new ServiceTokenClaimError(`Service token audience mismatch: expected '${expected.audience}', got '${String(aud)}'`);
     }
 }
+/**
+ * Parse the session authority's actor chain. `null` when the API did not send
+ * one; `'invalid'` when it sent something that is not a chain, which the caller
+ * refuses rather than ignores.
+ */
+function readActorChain(raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    const parsed = accountActorChainSchema.safeParse(raw);
+    return parsed.success ? parsed.data : 'invalid';
+}

package/dist/esm/server/namespaces.js

@@ -1,3 +1,10 @@
+/**
+ * The server-side halves of the namespaces: what exists only with a service
+ * credential. `OxyServer` returns these from its namespace getters, so
+ * `server.assets.metadataByIds(...)` sits beside every client method of
+ * `oxy.assets`.
+ */
+import { capabilityTicketRequestSchema, foregroundExecutionAuthorizationInputSchema } from '@oxy.so/contracts';
 import { AssetsApi } from '../api/assets.js';
 import { NotificationsApi } from '../api/notifications.js';
 import { LinkedAccountsApi } from '../api/linkedAccounts.js';
@@ -179,7 +186,57 @@ export class ServerLinkedAccountsApi extends LinkedAccountsApi {
         return lane(this.ctx).request('GET', `/linked-accounts/by-user/${encodeURIComponent(userId)}`);
     }
 }
+function agencyAuthorityOptions(signal) {
+    signal?.throwIfAborted();
+    return { cache: false, deduplicate: false, retry: false, skipAuth: true, timeout: 5000, ...(signal ? { signal } : {}) };
+}
 export class ServerAgencyApi extends AgencyApi {
+    /** Live registry discovery with this service's existing capability scopes. */
+    async serviceCatalogs(input = {}) {
+        const path = `/capabilities/catalogs${input.appId === undefined ? '' : `?appId=${encodeURIComponent(input.appId)}`}`;
+        const result = await lane(this.ctx).request('GET', path, undefined, agencyAuthorityOptions(input.signal));
+        return result.registrations;
+    }
+    /** Existing Oxy execution authority is required; this call creates none. */
+    async issueCapabilityTicket(input, options = {}) {
+        return lane(this.ctx).request('POST', '/capabilities/tickets', capabilityTicketRequestSchema.parse(input), agencyAuthorityOptions(options.signal));
+    }
+    /** Receiving app authenticates live introspection using its own service credential. */
+    async introspectCapabilityTicket(ticket, options = {}) {
+        if (ticket.trim() === '')
+            throw new Error('A capability ticket is required');
+        return lane(this.ctx).request('POST', '/capabilities/tickets/introspect', { ticket }, agencyAuthorityOptions(options.signal));
+    }
+    /**
+     * Authenticates the existing user-authority route with the requester's bearer.
+     * The service bearer and attribution headers cannot substitute for that user.
+     * The token goes only to this client's configured Oxy authority; never retry.
+     */
+    async createExecutionAuthorization(input, options) {
+        if (options.requesterToken === '' || /\s/.test(options.requesterToken))
+            throw new Error('A requester bearer is required');
+        const result = await this.ctx.request('POST', '/capabilities/execution-authorizations', input, {
+            ...agencyAuthorityOptions(options.signal),
+            headers: { Authorization: `Bearer ${options.requesterToken}` },
+        });
+        return result.authorization;
+    }
+    /** Revoke a direct approval on its canonical requester-authenticated lane. */
+    async revokeExecutionAuthorization(authorizationId, options) {
+        options.signal?.throwIfAborted();
+        if (!authorizationId || authorizationId.length > 255 || /\s/.test(authorizationId))
+            throw new Error('An execution authorization id is required');
+        if (!options.requesterToken || options.requesterToken.length > 16384 || /\s/.test(options.requesterToken))
+            throw new Error('A requester bearer is required');
+        await this.ctx.request('DELETE', `/capabilities/execution-authorizations/${encodeURIComponent(authorizationId)}`, undefined, { ...agencyAuthorityOptions(options.signal), headers: { Authorization: `Bearer ${options.requesterToken}` } });
+    }
+    /** Independent service proof plus present requester bearer, sent only to Oxy. */
+    async createForegroundExecutionAuthorization(input, options) {
+        if (options.requesterToken === '' || options.requesterToken.length > 16384 || /\s/.test(options.requesterToken))
+            throw new Error('A requester bearer is required');
+        const result = await lane(this.ctx).request('POST', '/capabilities/foreground-execution-authorizations', { ...foregroundExecutionAuthorizationInputSchema.parse(input), subjectToken: options.requesterToken }, agencyAuthorityOptions(options.signal));
+        return result.authorization;
+    }
     /**
      * Product backend → Oxy: trade the signed-in requester's access token for a
      * one-use assertion naming `agentId` (ADR 0025), authenticated with this

package/dist/esm/server/serviceTokenLifetime.js

@@ -0,0 +1,9 @@
+/** Approved I03 ceiling shared by issuance and both JWT verifiers. */
+export const OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS = 300;
+/** Call only after signature verification; cache checks alone confer no authority. */
+export function hasBoundedServiceTokenLifetime(claims, nowSeconds = Math.floor(Date.now() / 1000)) {
+    return typeof claims.iat === 'number' && Number.isSafeInteger(claims.iat)
+        && typeof claims.exp === 'number' && Number.isSafeInteger(claims.exp)
+        && claims.iat <= nowSeconds && claims.exp > claims.iat
+        && claims.exp - claims.iat <= OXY_SERVICE_TOKEN_MAX_LIFETIME_SECONDS;
+}

package/dist/esm/session/SessionClient.js

@@ -1,6 +1,7 @@
 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 { decodeTokenClaims } from '../utils/tokenClaims.js';
 import { resolveActiveContext } from './deviceDirectory.js';
 import { getSocketIO } from './socketLoader.js';
 /**
@@ -34,6 +35,8 @@ export class SessionClient {
         this.socket = null;
         this.tokenUnsub = null;
         this.started = false;
+        this.lifecycleGeneration = 0;
+        this.fullSignOutPersistence = null;
         /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
         this.channel = null;
         /** App-facing subscriptions to named server-pushed socket events. */
@@ -41,6 +44,35 @@ export class SessionClient {
         /** Event names already bound on the CURRENT socket instance. */
         this.boundServerEvents = new Set();
     }
+    persistFullSignOut() {
+        const state = this.state;
+        if (!state || !this.options.onFullExplicitSignOut)
+            return Promise.resolve();
+        if (this.fullSignOutPersistence?.state === state)
+            return this.fullSignOutPersistence.pending;
+        const pending = this.options.onFullExplicitSignOut();
+        this.fullSignOutPersistence = { state, pending };
+        void pending.catch(() => {
+            if (this.fullSignOutPersistence?.pending === pending)
+                this.fullSignOutPersistence = null;
+        });
+        return pending;
+    }
+    async requestDevice(method, url, data, requestOptions) {
+        const generation = this.lifecycleGeneration;
+        const response = await this.host.makeRequest(method, url, data, requestOptions);
+        if (generation !== this.lifecycleGeneration)
+            throw new Error('Device session request was superseded');
+        return response;
+    }
+    /** Stop and discard only this client's local device projection; no server revocation. */
+    resetLocalState() {
+        this.lifecycleGeneration += 1;
+        this.stop();
+        this.state = null;
+        this.directory = null;
+        this.notify();
+    }
     getState() {
         return this.state;
     }
@@ -163,6 +195,7 @@ export class SessionClient {
      * cross-device push, a cold mint), not just the initial "no bearer yet" case.
      */
     applyState(raw, origin = 'push', activeToken) {
+        const generation = this.lifecycleGeneration;
         const next = safeParseContract(deviceSessionStateSchema, raw);
         if (!next) {
             logger.warn('[SessionClient] discarded invalid session state');
@@ -218,6 +251,8 @@ export class SessionClient {
             next.accounts.length > 0 &&
             (activeAccountId === null || computeIdentityTag(this.host.getAccessToken()) !== activeAccountId);
         const publish = () => {
+            if (generation !== this.lifecycleGeneration || this.state !== next)
+                return;
             this.notify();
             if (next.accounts.length === 0 && this.options.onUnauthenticated) {
                 try {
@@ -236,6 +271,8 @@ export class SessionClient {
         // (and this stays synchronous) for every client that never read a
         // directory, i.e. the whole account lane.
         const finishApply = () => {
+            if (generation !== this.lifecycleGeneration || this.state !== next)
+                return;
             const settling = this.settleDirectory(next);
             if (settling === null) {
                 publish();
@@ -243,8 +280,38 @@ export class SessionClient {
             }
             void settling.then(publish);
         };
+        // A sibling's validated full removal is logout here too. Persist the local
+        // account-mode recovery suppression before publishing signed-out or running
+        // the empty-state refresh (which could otherwise challenge Commons again).
+        // Keep the push credential intact; a marker is not a destructive wipe.
+        // Unknown initial empty state, stale revisions and identity pins do not
+        // turn into logout intent. A newer state/lifecycle suppresses this publish.
+        const priorBearer = this.host.getAccessToken();
+        const bearerAccount = priorBearer ? decodeTokenClaims(priorBearer)?.userId : null;
+        // Warm cold boot may fetch authoritative empty state before it ever had a
+        // local projection. Its authenticated holder is history too. Decoding only
+        // identifies local history; authority remains the validated REST response.
+        const warmHolderEnded = previousState === null && origin === 'request' &&
+            typeof bearerAccount === 'string' && bearerAccount.length > 0 &&
+            this.host.getDeviceCredential()?.deviceId === next.deviceId;
+        if (((previousState?.deviceId === next.deviceId && previousState.accounts.length > 0) || warmHolderEnded) &&
+            next.accounts.length === 0 && pinnedAccountId === null && this.options.onFullExplicitSignOut) {
+            try {
+                void this.persistFullSignOut().then(finishApply).catch((error) => {
+                    logger.error('[SessionClient] failed to persist received full sign-out', error);
+                    finishApply();
+                });
+            }
+            catch (error) {
+                logger.error('[SessionClient] failed to persist received full sign-out', error);
+                finishApply();
+            }
+            return true;
+        }
         if (needsMintBeforeNotify) {
             void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
+                if (generation !== this.lifecycleGeneration)
+                    return;
                 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.
@@ -268,7 +335,7 @@ export class SessionClient {
      * 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) {
+    async applySync(raw) {
         const sync = safeParseContract(deviceSessionSyncSchema, raw);
         if (!sync) {
             const parsed = deviceSessionSyncSchema.safeParse(raw);
@@ -285,6 +352,8 @@ export class SessionClient {
             return;
         }
         this.commitSync(sync);
+        if (this.fullSignOutPersistence?.state === this.state)
+            await this.fullSignOutPersistence.pending;
     }
     /**
      * The apply + token-plant half of {@link applySync}, on an ALREADY-VALIDATED
@@ -362,7 +431,7 @@ export class SessionClient {
     }
     /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
     async fetchDirectory() {
-        const res = await this.host.makeRequest('GET', '/session/device/directory', undefined, { cache: false });
+        const res = await this.requestDevice('GET', '/session/device/directory', undefined, { cache: false });
         return this.applyDirectory(res);
     }
     /**
@@ -471,8 +540,8 @@ export class SessionClient {
         }
     }
     async bootstrap() {
-        const res = await this.host.makeRequest('GET', '/session/device/state', undefined, { cache: false });
-        this.applySync(res);
+        const res = await this.requestDevice('GET', '/session/device/state', undefined, { cache: false });
+        await this.applySync(res);
     }
     /**
      * Adopt server-authoritative state already returned by another session
@@ -515,7 +584,7 @@ export class SessionClient {
      * 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 res = await this.requestDevice('POST', '/session/device/activate', { contextId }, { cache: false });
         const activation = safeParseContract(deviceActivateResponseSchema, res);
         if (!activation) {
             logger.warn('[SessionClient] discarded invalid activation response');
@@ -541,8 +610,8 @@ export class SessionClient {
         }
     }
     async switchAccount(accountId) {
-        const res = await this.host.makeRequest('POST', '/session/device/switch', { accountId }, { cache: false });
-        this.applySync(res);
+        const res = await this.requestDevice('POST', '/session/device/switch', { accountId }, { cache: false });
+        await this.applySync(res);
         this.postCommitPing();
     }
     /**
@@ -557,9 +626,11 @@ export class SessionClient {
      * {@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);
+        const res = await this.requestDevice('POST', '/session/device/signout', target, { cache: false });
+        await this.applySync(res);
         this.postCommitPing();
+        if (this.state?.accounts.length === 0)
+            await this.persistFullSignOut();
     }
     /**
      * Remove ONE `principal → account` pair, and only that pair.
@@ -598,7 +669,7 @@ export class SessionClient {
      * applied this revision.
      */
     async removeFromDevice(target) {
-        const res = await this.host.makeRequest('POST', '/session/device/signout', target, { cache: false });
+        const res = await this.requestDevice('POST', '/session/device/signout', target, { cache: false });
         const removal = safeParseContract(deviceDirectorySyncSchema, res);
         if (!removal) {
             logger.warn('[SessionClient] discarded invalid device removal response');
@@ -606,6 +677,8 @@ export class SessionClient {
         }
         const directoryApplied = this.applyDirectory(removal.directory);
         const stateApplied = this.commitSync({ state: removal.state, activeToken: removal.activeToken });
+        if (this.fullSignOutPersistence?.state === this.state)
+            await this.fullSignOutPersistence.pending;
         // `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.
@@ -613,10 +686,12 @@ export class SessionClient {
             this.notify();
         }
         this.postCommitPing();
+        if (this.state?.accounts.length === 0)
+            await this.persistFullSignOut();
     }
     async addCurrentAccount() {
-        const res = await this.host.makeRequest('POST', '/session/device/add', undefined, { cache: false });
-        this.applySync(res);
+        const res = await this.requestDevice('POST', '/session/device/add', undefined, { cache: false });
+        await this.applySync(res);
         this.postCommitPing();
     }
     /**
@@ -718,6 +793,7 @@ export class SessionClient {
         const deviceCredential = this.host.getDeviceCredential();
         if (!token && !deviceCredential)
             return;
+        const generation = this.lifecycleGeneration;
         const socket = io(this.host.getBaseURL(), {
             transports: ['websocket'],
             autoConnect: true,
@@ -742,6 +818,8 @@ export class SessionClient {
         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.
+            if (generation !== this.lifecycleGeneration)
+                return;
             const applied = this.applyState(payload, 'push');
             if (!applied)
                 return;