@oxy.so/core 7.10.0 → 7.10.2

package/dist/cjs/HttpService.js

@@ -58,6 +58,14 @@ function sameTokenSession(left, right) {
     }
     if (!(a.userId || a.id || a.sub) || !(b.userId || b.id || b.sub))
         return false;
+    // A legacy bearer may omit deviceId; empty or non-string values also carry no
+    // usable device. Two known, different devices are distinct local contexts.
+    if (typeof a.deviceId === 'string' &&
+        a.deviceId.length > 0 &&
+        typeof b.deviceId === 'string' &&
+        b.deviceId.length > 0 &&
+        a.deviceId !== b.deviceId)
+        return false;
     // A refresh may rotate exp/iat/jti while preserving its account and session.
     // Opaque/malformed context fields cannot establish that equivalence.
     return [
@@ -71,6 +79,13 @@ function sameTokenSession(left, right) {
         'authMethodId',
     ].every((key) => (a[key] === undefined || typeof a[key] === 'string') && a[key] === b[key]);
 }
+/** Extract a known device for local ownership checks, never authorization. */
+function knownTokenDeviceId(token) {
+    const claims = (0, tokenClaims_1.decodeTokenClaims)(token);
+    return claims?.type !== 'service' && typeof claims?.deviceId === 'string' && claims.deviceId
+        ? claims.deviceId
+        : null;
+}
 /** Discard an unused body even when a platform's stream shim lacks cancel. */
 function discardResponseBody(response) {
     try {
@@ -328,6 +343,8 @@ class HttpService {
          * bearer — and through the token listeners, the account — back.
          */
         this.sessionEpoch = 0;
+        /** Preserve a known device across legacy rotations which omit the claim. */
+        this.sessionDeviceId = null;
         /**
          * Set by {@link endSession}, cleared by the next {@link setTokens}. Read by the
          * native Commons-identity re-mint arm: after a sign-out a 401 is the expected
@@ -566,8 +583,12 @@ class HttpService {
         const authHeader = usesSessionAuth
             ? await (0, requestSignal_1.awaitRequestSignal)(this.getAuthHeader(), signal)
             : null;
-        const isOriginalSession = () => this.sessionEpoch === contextEpoch &&
-            sameTokenSession(contextToken, this.syncAccessTokenFromProvider());
+        const isOriginalSession = () => {
+            if (this.sessionEpoch !== contextEpoch)
+                return false;
+            const currentToken = this.syncAccessTokenFromProvider();
+            return this.sessionEpoch === contextEpoch && sameTokenSession(contextToken, currentToken);
+        };
         const newerRequestToken = () => {
             if (!contextToken || !authHeader?.startsWith('Bearer '))
                 return null;
@@ -770,6 +791,7 @@ class HttpService {
                             if (this.tokenStore.getAccessToken())
                                 this.sessionEpoch += 1;
                             this.tokenStore.clearTokens();
+                            this.sessionDeviceId = null;
                             selfClearedEpoch = this.sessionEpoch;
                             this.notifyTokenChange();
                         }
@@ -1653,8 +1675,13 @@ class HttpService {
     // Token management
     setTokens(accessToken) {
         const current = this.tokenStore.getAccessToken();
-        if (current && !sameTokenSession(current, accessToken))
+        const deviceId = knownTokenDeviceId(accessToken);
+        const changed = current !== null &&
+            (!sameTokenSession(current, accessToken) ||
+                (this.sessionDeviceId !== null && deviceId !== null && this.sessionDeviceId !== deviceId));
+        if (changed)
             this.sessionEpoch += 1;
+        this.sessionDeviceId = !current || changed ? deviceId : (deviceId ?? this.sessionDeviceId);
         this.sessionEnded = false;
         this.tokenStore.setTokens(accessToken);
         this.notifyTokenChange();
@@ -1673,8 +1700,8 @@ class HttpService {
         this.clearTokens();
     }
     /**
-     * The current context epoch: account/session switches and bearer removal
-     * invalidate pending work; rotation within the same context preserves it.
+     * The current context epoch: account/session switches, known device changes,
+     * and bearer removal invalidate pending work; same-context rotation preserves it.
      * A re-mint lane that
      * plants tokens itself (the device-secret arm) compares it across its awaits.
      */
@@ -1705,6 +1732,7 @@ class HttpService {
         if (this.tokenStore.getAccessToken())
             this.sessionEpoch += 1;
         this.tokenStore.clearTokens();
+        this.sessionDeviceId = null;
         // Drop the response cache on logout. The cache is identity-scoped, so a
         // different user could never read these entries, but a logged-out client
         // must not keep the previous session's personalized data resident in
@@ -1864,6 +1892,7 @@ class HttpService {
     __resetTokensForTests() {
         this.sessionEnded = false;
         this.tokenStore.clearTokens();
+        this.sessionDeviceId = null;
     }
 }
 exports.HttpService = HttpService;

package/dist/cjs/session/SessionClient.js

@@ -39,6 +39,8 @@ class SessionClient {
         this.tokenUnsub = null;
         this.started = false;
         this.lifecycleGeneration = 0;
+        /** Changes whenever the locally projected device changes, including ABA. */
+        this.deviceGeneration = 0;
         this.fullSignOutPersistence = null;
         /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
         this.channel = null;
@@ -68,6 +70,25 @@ class SessionClient {
             throw new Error('Device session request was superseded');
         return response;
     }
+    /** Capture the local device before a request, including device ABA. */
+    captureDeviceRequest() {
+        return { generation: this.deviceGeneration, initialDevice: this.state?.deviceId ?? null };
+    }
+    isCurrentDeviceRequest(request, response) {
+        if (request.generation === this.deviceGeneration)
+            return true;
+        if (request.initialDevice !== null || this.deviceGeneration !== request.generation + 1)
+            return false;
+        if (response === null || typeof response !== 'object')
+            return false;
+        const record = response;
+        const deviceId = record.state?.deviceId ?? record.directory?.deviceId ?? record.deviceId;
+        return typeof deviceId === 'string' && deviceId === this.state?.deviceId;
+    }
+    assertCurrentDeviceRequest(request, response) {
+        if (!this.isCurrentDeviceRequest(request, response))
+            throw new Error('Device session request was superseded');
+    }
     /** Stop and discard only this client's local device projection; no server revocation. */
     resetLocalState() {
         this.lifecycleGeneration += 1;
@@ -216,6 +237,8 @@ class SessionClient {
             return false;
         }
         const previousState = this.state;
+        if (previousState?.deviceId !== next.deviceId)
+            this.deviceGeneration += 1;
         this.state = next;
         if (next.accounts.length === 0) {
             // A device with nobody signed in has no principals either. The directory
@@ -324,11 +347,13 @@ class SessionClient {
                 .ensureActiveToken(next)
                 .then(finishApply)
                 .catch((error) => {
-                if (generation !== this.lifecycleGeneration)
+                if (generation !== this.lifecycleGeneration || this.state !== next)
                     return;
                 logger_1.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.
+                if (this.state?.deviceId !== previousState?.deviceId)
+                    this.deviceGeneration += 1;
                 this.state = previousState ?? null;
             });
         }
@@ -378,6 +403,21 @@ class SessionClient {
         if (this.fullSignOutPersistence?.state === this.state)
             await this.fullSignOutPersistence.pending;
     }
+    /** Keep mutation callers from reporting success after a device change during persistence. */
+    async applySyncForMutation(raw) {
+        const before = this.captureDeviceRequest();
+        const lifecycle = this.lifecycleGeneration;
+        const checked = (0, client_1.deviceSessionSyncCheck)(raw, []);
+        const responseDevice = checked.ok ? checked.value.state.deviceId : before.initialDevice;
+        const expectedGeneration = before.generation + (responseDevice === before.initialDevice ? 0 : 1);
+        const pending = this.applySync(raw);
+        const generation = this.deviceGeneration;
+        await pending;
+        if (generation !== expectedGeneration ||
+            generation !== this.deviceGeneration ||
+            lifecycle !== this.lifecycleGeneration)
+            throw new Error('Device session request was superseded');
+    }
     /**
      * 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
@@ -397,14 +437,15 @@ class SessionClient {
         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`).
+        // needs planting. Only the exact same device revision is an equal-revision
+        // restate: an older response may identify a different operator of the same
+        // account. Also require the current account and the identity pin to match.
         const pinnedAccountId = this.pinnedAccountId();
         if (!applied &&
             sync.activeToken &&
             this.state &&
+            sync.state.deviceId === this.state.deviceId &&
+            sync.state.revision === this.state.revision &&
             sync.state.activeAccountId !== null &&
             sync.state.activeAccountId === this.state.activeAccountId &&
             (pinnedAccountId === null || sync.state.activeAccountId === pinnedAccountId) &&
@@ -454,9 +495,12 @@ class SessionClient {
     }
     /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
     async fetchDirectory() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('GET', '/session/device/directory', undefined, {
             cache: false,
         });
+        if (!this.isCurrentDeviceRequest(request, res))
+            return false;
         return this.applyDirectory(res);
     }
     /**
@@ -518,14 +562,13 @@ class SessionClient {
         if (!accessToken) {
             return;
         }
+        const pinnedAccountId = this.pinnedAccountId();
         const subjectAccountId = (0, deviceDirectory_1.resolveActiveContext)(directory)?.subject.accountId ?? null;
         if (subjectAccountId === null) {
             return;
         }
-        const pinnedAccountId = this.pinnedAccountId();
-        if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId) {
+        if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId)
             return;
-        }
         if (accessToken === this.host.getAccessToken()) {
             return;
         }
@@ -565,9 +608,12 @@ class SessionClient {
         }
     }
     async bootstrap() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('GET', '/session/device/state', undefined, {
             cache: false,
         });
+        if (!this.isCurrentDeviceRequest(request, res))
+            return;
         await this.applySync(res);
     }
     /**
@@ -611,13 +657,41 @@ class SessionClient {
      * compatibility path for callers still keyed on account ids.
      */
     async activateContext(contextId) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/activate', { contextId }, { cache: false });
+        this.assertCurrentDeviceRequest(request, res);
         const activation = (0, client_1.checkContract)(client_1.deviceActivateResponseCheck, res);
         if (!activation) {
             logger_1.logger.warn('[SessionClient] discarded invalid activation response');
             return;
         }
+        if (this.pinnedAccountId() === null) {
+            const active = (0, deviceDirectory_1.resolveActiveContext)(activation.directory);
+            if (!active || activation.directory.activeContextId !== contextId)
+                throw new Error('Device session request was superseded');
+            const claims = activation.activeToken?.accessToken
+                ? (0, tokenClaims_1.decodeTokenClaims)(activation.activeToken.accessToken)
+                : null;
+            const contextClaim = claims?.device_context_id;
+            const actor = claims?.act;
+            const actorClaim = actor !== null && typeof actor === 'object' ? actor.sub : undefined;
+            const subjectClaim = claims?.userId ?? claims?.id ?? claims?.sub;
+            // Decoded claims are only a consistency check, never authorization.
+            // Legacy and opaque bearers may omit these claims entirely.
+            if ((typeof contextClaim === 'string' && contextClaim !== active.contextId) ||
+                (typeof actorClaim === 'string' && actorClaim !== active.actor.userId) ||
+                (typeof subjectClaim === 'string' && subjectClaim !== active.subject.accountId))
+                throw new Error('Device session request was superseded');
+        }
         const known = this.knownRevisionFor(activation.directory.deviceId);
+        if (known !== null && activation.directory.revision < known)
+            throw new Error('Device session request was superseded');
+        const held = this.directory;
+        if (this.pinnedAccountId() === null &&
+            held?.deviceId === activation.directory.deviceId &&
+            held.revision === activation.directory.revision &&
+            held.activeContextId !== activation.directory.activeContextId)
+            throw new Error('Device session request was superseded');
         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
@@ -627,8 +701,21 @@ class SessionClient {
         // already holding in hand.
         const applied = this.applyDirectory(activation.directory);
         if (moved) {
+            const beforeReconcile = this.captureDeviceRequest();
+            const lifecycle = this.lifecycleGeneration;
             await this.reconcileFlatState(activation.directory);
+            const landedOnTarget = beforeReconcile.initialDevice !== activation.directory.deviceId &&
+                this.deviceGeneration === beforeReconcile.generation + 1 &&
+                this.state?.deviceId === activation.directory.deviceId;
+            if (lifecycle !== this.lifecycleGeneration ||
+                (this.deviceGeneration !== beforeReconcile.generation && !landedOnTarget))
+                throw new Error('Device session request was superseded');
         }
+        if (this.pinnedAccountId() === null &&
+            (this.knownRevisionFor(activation.directory.deviceId) !== activation.directory.revision ||
+                this.directory?.deviceId !== activation.directory.deviceId ||
+                this.directory.activeContextId !== contextId))
+            throw new Error('Device session request was superseded');
         if (applied) {
             this.notify();
         }
@@ -637,8 +724,18 @@ class SessionClient {
         }
     }
     async switchAccount(accountId) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/switch', { accountId }, { cache: false });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        const checked = (0, client_1.deviceSessionSyncCheck)(res, []);
+        const isStale = () => checked.ok &&
+            this.state?.deviceId === checked.value.state.deviceId &&
+            this.state.revision > checked.value.state.revision;
+        if (isStale())
+            throw new Error('Device session request was superseded');
+        await this.applySyncForMutation(res);
+        if (isStale())
+            throw new Error('Device session request was superseded');
         this.postCommitPing();
     }
     /**
@@ -653,10 +750,12 @@ class SessionClient {
      * {@link signOutPrincipal} for the two that can tell those apart.
      */
     async signOut(target) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/signout', target, {
             cache: false,
         });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        await this.applySyncForMutation(res);
         this.postCommitPing();
         if (this.state?.accounts.length === 0)
             await this.persistFullSignOut();
@@ -698,21 +797,34 @@ class SessionClient {
      * applied this revision.
      */
     async removeFromDevice(target) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/signout', target, {
             cache: false,
         });
+        this.assertCurrentDeviceRequest(request, res);
         const removal = (0, client_1.checkContract)(client_1.deviceDirectorySyncCheck, res);
         if (!removal) {
             logger_1.logger.warn('[SessionClient] discarded invalid device removal response');
             return;
         }
         const directoryApplied = this.applyDirectory(removal.directory);
+        const beforeCommit = this.captureDeviceRequest();
+        const commitLifecycle = this.lifecycleGeneration;
+        const expectedGeneration = beforeCommit.generation + (beforeCommit.initialDevice === removal.state.deviceId ? 0 : 1);
         const stateApplied = this.commitSync({
             state: removal.state,
             activeToken: removal.activeToken,
         });
-        if (this.fullSignOutPersistence?.state === this.state)
+        if (expectedGeneration !== this.deviceGeneration ||
+            commitLifecycle !== this.lifecycleGeneration)
+            throw new Error('Device session request was superseded');
+        if (this.fullSignOutPersistence?.state === this.state) {
+            const generation = this.deviceGeneration;
+            const lifecycle = this.lifecycleGeneration;
             await this.fullSignOutPersistence.pending;
+            if (generation !== this.deviceGeneration || lifecycle !== this.lifecycleGeneration)
+                throw new Error('Device session request was superseded');
+        }
         // `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.
@@ -724,10 +836,12 @@ class SessionClient {
             await this.persistFullSignOut();
     }
     async addCurrentAccount() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/add', undefined, {
             cache: false,
         });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        await this.applySyncForMutation(res);
         this.postCommitPing();
     }
     /**

package/dist/esm/HttpService.js

@@ -55,6 +55,14 @@ function sameTokenSession(left, right) {
     }
     if (!(a.userId || a.id || a.sub) || !(b.userId || b.id || b.sub))
         return false;
+    // A legacy bearer may omit deviceId; empty or non-string values also carry no
+    // usable device. Two known, different devices are distinct local contexts.
+    if (typeof a.deviceId === 'string' &&
+        a.deviceId.length > 0 &&
+        typeof b.deviceId === 'string' &&
+        b.deviceId.length > 0 &&
+        a.deviceId !== b.deviceId)
+        return false;
     // A refresh may rotate exp/iat/jti while preserving its account and session.
     // Opaque/malformed context fields cannot establish that equivalence.
     return [
@@ -68,6 +76,13 @@ function sameTokenSession(left, right) {
         'authMethodId',
     ].every((key) => (a[key] === undefined || typeof a[key] === 'string') && a[key] === b[key]);
 }
+/** Extract a known device for local ownership checks, never authorization. */
+function knownTokenDeviceId(token) {
+    const claims = decodeTokenClaims(token);
+    return claims?.type !== 'service' && typeof claims?.deviceId === 'string' && claims.deviceId
+        ? claims.deviceId
+        : null;
+}
 /** Discard an unused body even when a platform's stream shim lacks cancel. */
 function discardResponseBody(response) {
     try {
@@ -325,6 +340,8 @@ export class HttpService {
          * bearer — and through the token listeners, the account — back.
          */
         this.sessionEpoch = 0;
+        /** Preserve a known device across legacy rotations which omit the claim. */
+        this.sessionDeviceId = null;
         /**
          * Set by {@link endSession}, cleared by the next {@link setTokens}. Read by the
          * native Commons-identity re-mint arm: after a sign-out a 401 is the expected
@@ -563,8 +580,12 @@ export class HttpService {
         const authHeader = usesSessionAuth
             ? await awaitRequestSignal(this.getAuthHeader(), signal)
             : null;
-        const isOriginalSession = () => this.sessionEpoch === contextEpoch &&
-            sameTokenSession(contextToken, this.syncAccessTokenFromProvider());
+        const isOriginalSession = () => {
+            if (this.sessionEpoch !== contextEpoch)
+                return false;
+            const currentToken = this.syncAccessTokenFromProvider();
+            return this.sessionEpoch === contextEpoch && sameTokenSession(contextToken, currentToken);
+        };
         const newerRequestToken = () => {
             if (!contextToken || !authHeader?.startsWith('Bearer '))
                 return null;
@@ -767,6 +788,7 @@ export class HttpService {
                             if (this.tokenStore.getAccessToken())
                                 this.sessionEpoch += 1;
                             this.tokenStore.clearTokens();
+                            this.sessionDeviceId = null;
                             selfClearedEpoch = this.sessionEpoch;
                             this.notifyTokenChange();
                         }
@@ -1650,8 +1672,13 @@ export class HttpService {
     // Token management
     setTokens(accessToken) {
         const current = this.tokenStore.getAccessToken();
-        if (current && !sameTokenSession(current, accessToken))
+        const deviceId = knownTokenDeviceId(accessToken);
+        const changed = current !== null &&
+            (!sameTokenSession(current, accessToken) ||
+                (this.sessionDeviceId !== null && deviceId !== null && this.sessionDeviceId !== deviceId));
+        if (changed)
             this.sessionEpoch += 1;
+        this.sessionDeviceId = !current || changed ? deviceId : (deviceId ?? this.sessionDeviceId);
         this.sessionEnded = false;
         this.tokenStore.setTokens(accessToken);
         this.notifyTokenChange();
@@ -1670,8 +1697,8 @@ export class HttpService {
         this.clearTokens();
     }
     /**
-     * The current context epoch: account/session switches and bearer removal
-     * invalidate pending work; rotation within the same context preserves it.
+     * The current context epoch: account/session switches, known device changes,
+     * and bearer removal invalidate pending work; same-context rotation preserves it.
      * A re-mint lane that
      * plants tokens itself (the device-secret arm) compares it across its awaits.
      */
@@ -1702,6 +1729,7 @@ export class HttpService {
         if (this.tokenStore.getAccessToken())
             this.sessionEpoch += 1;
         this.tokenStore.clearTokens();
+        this.sessionDeviceId = null;
         // Drop the response cache on logout. The cache is identity-scoped, so a
         // different user could never read these entries, but a logged-out client
         // must not keep the previous session's personalized data resident in
@@ -1861,6 +1889,7 @@ export class HttpService {
     __resetTokensForTests() {
         this.sessionEnded = false;
         this.tokenStore.clearTokens();
+        this.sessionDeviceId = null;
     }
 }
 /**

package/dist/esm/session/SessionClient.js

@@ -36,6 +36,8 @@ export class SessionClient {
         this.tokenUnsub = null;
         this.started = false;
         this.lifecycleGeneration = 0;
+        /** Changes whenever the locally projected device changes, including ABA. */
+        this.deviceGeneration = 0;
         this.fullSignOutPersistence = null;
         /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
         this.channel = null;
@@ -65,6 +67,25 @@ export class SessionClient {
             throw new Error('Device session request was superseded');
         return response;
     }
+    /** Capture the local device before a request, including device ABA. */
+    captureDeviceRequest() {
+        return { generation: this.deviceGeneration, initialDevice: this.state?.deviceId ?? null };
+    }
+    isCurrentDeviceRequest(request, response) {
+        if (request.generation === this.deviceGeneration)
+            return true;
+        if (request.initialDevice !== null || this.deviceGeneration !== request.generation + 1)
+            return false;
+        if (response === null || typeof response !== 'object')
+            return false;
+        const record = response;
+        const deviceId = record.state?.deviceId ?? record.directory?.deviceId ?? record.deviceId;
+        return typeof deviceId === 'string' && deviceId === this.state?.deviceId;
+    }
+    assertCurrentDeviceRequest(request, response) {
+        if (!this.isCurrentDeviceRequest(request, response))
+            throw new Error('Device session request was superseded');
+    }
     /** Stop and discard only this client's local device projection; no server revocation. */
     resetLocalState() {
         this.lifecycleGeneration += 1;
@@ -213,6 +234,8 @@ export class SessionClient {
             return false;
         }
         const previousState = this.state;
+        if (previousState?.deviceId !== next.deviceId)
+            this.deviceGeneration += 1;
         this.state = next;
         if (next.accounts.length === 0) {
             // A device with nobody signed in has no principals either. The directory
@@ -321,11 +344,13 @@ export class SessionClient {
                 .ensureActiveToken(next)
                 .then(finishApply)
                 .catch((error) => {
-                if (generation !== this.lifecycleGeneration)
+                if (generation !== this.lifecycleGeneration || this.state !== next)
                     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.
+                if (this.state?.deviceId !== previousState?.deviceId)
+                    this.deviceGeneration += 1;
                 this.state = previousState ?? null;
             });
         }
@@ -375,6 +400,21 @@ export class SessionClient {
         if (this.fullSignOutPersistence?.state === this.state)
             await this.fullSignOutPersistence.pending;
     }
+    /** Keep mutation callers from reporting success after a device change during persistence. */
+    async applySyncForMutation(raw) {
+        const before = this.captureDeviceRequest();
+        const lifecycle = this.lifecycleGeneration;
+        const checked = deviceSessionSyncCheck(raw, []);
+        const responseDevice = checked.ok ? checked.value.state.deviceId : before.initialDevice;
+        const expectedGeneration = before.generation + (responseDevice === before.initialDevice ? 0 : 1);
+        const pending = this.applySync(raw);
+        const generation = this.deviceGeneration;
+        await pending;
+        if (generation !== expectedGeneration ||
+            generation !== this.deviceGeneration ||
+            lifecycle !== this.lifecycleGeneration)
+            throw new Error('Device session request was superseded');
+    }
     /**
      * 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
@@ -394,14 +434,15 @@ export class SessionClient {
         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`).
+        // needs planting. Only the exact same device revision is an equal-revision
+        // restate: an older response may identify a different operator of the same
+        // account. Also require the current account and the identity pin to match.
         const pinnedAccountId = this.pinnedAccountId();
         if (!applied &&
             sync.activeToken &&
             this.state &&
+            sync.state.deviceId === this.state.deviceId &&
+            sync.state.revision === this.state.revision &&
             sync.state.activeAccountId !== null &&
             sync.state.activeAccountId === this.state.activeAccountId &&
             (pinnedAccountId === null || sync.state.activeAccountId === pinnedAccountId) &&
@@ -451,9 +492,12 @@ export class SessionClient {
     }
     /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
     async fetchDirectory() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('GET', '/session/device/directory', undefined, {
             cache: false,
         });
+        if (!this.isCurrentDeviceRequest(request, res))
+            return false;
         return this.applyDirectory(res);
     }
     /**
@@ -515,14 +559,13 @@ export class SessionClient {
         if (!accessToken) {
             return;
         }
+        const pinnedAccountId = this.pinnedAccountId();
         const subjectAccountId = resolveActiveContext(directory)?.subject.accountId ?? null;
         if (subjectAccountId === null) {
             return;
         }
-        const pinnedAccountId = this.pinnedAccountId();
-        if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId) {
+        if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId)
             return;
-        }
         if (accessToken === this.host.getAccessToken()) {
             return;
         }
@@ -562,9 +605,12 @@ export class SessionClient {
         }
     }
     async bootstrap() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('GET', '/session/device/state', undefined, {
             cache: false,
         });
+        if (!this.isCurrentDeviceRequest(request, res))
+            return;
         await this.applySync(res);
     }
     /**
@@ -608,13 +654,41 @@ export class SessionClient {
      * compatibility path for callers still keyed on account ids.
      */
     async activateContext(contextId) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/activate', { contextId }, { cache: false });
+        this.assertCurrentDeviceRequest(request, res);
         const activation = checkContract(deviceActivateResponseCheck, res);
         if (!activation) {
             logger.warn('[SessionClient] discarded invalid activation response');
             return;
         }
+        if (this.pinnedAccountId() === null) {
+            const active = resolveActiveContext(activation.directory);
+            if (!active || activation.directory.activeContextId !== contextId)
+                throw new Error('Device session request was superseded');
+            const claims = activation.activeToken?.accessToken
+                ? decodeTokenClaims(activation.activeToken.accessToken)
+                : null;
+            const contextClaim = claims?.device_context_id;
+            const actor = claims?.act;
+            const actorClaim = actor !== null && typeof actor === 'object' ? actor.sub : undefined;
+            const subjectClaim = claims?.userId ?? claims?.id ?? claims?.sub;
+            // Decoded claims are only a consistency check, never authorization.
+            // Legacy and opaque bearers may omit these claims entirely.
+            if ((typeof contextClaim === 'string' && contextClaim !== active.contextId) ||
+                (typeof actorClaim === 'string' && actorClaim !== active.actor.userId) ||
+                (typeof subjectClaim === 'string' && subjectClaim !== active.subject.accountId))
+                throw new Error('Device session request was superseded');
+        }
         const known = this.knownRevisionFor(activation.directory.deviceId);
+        if (known !== null && activation.directory.revision < known)
+            throw new Error('Device session request was superseded');
+        const held = this.directory;
+        if (this.pinnedAccountId() === null &&
+            held?.deviceId === activation.directory.deviceId &&
+            held.revision === activation.directory.revision &&
+            held.activeContextId !== activation.directory.activeContextId)
+            throw new Error('Device session request was superseded');
         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
@@ -624,8 +698,21 @@ export class SessionClient {
         // already holding in hand.
         const applied = this.applyDirectory(activation.directory);
         if (moved) {
+            const beforeReconcile = this.captureDeviceRequest();
+            const lifecycle = this.lifecycleGeneration;
             await this.reconcileFlatState(activation.directory);
+            const landedOnTarget = beforeReconcile.initialDevice !== activation.directory.deviceId &&
+                this.deviceGeneration === beforeReconcile.generation + 1 &&
+                this.state?.deviceId === activation.directory.deviceId;
+            if (lifecycle !== this.lifecycleGeneration ||
+                (this.deviceGeneration !== beforeReconcile.generation && !landedOnTarget))
+                throw new Error('Device session request was superseded');
         }
+        if (this.pinnedAccountId() === null &&
+            (this.knownRevisionFor(activation.directory.deviceId) !== activation.directory.revision ||
+                this.directory?.deviceId !== activation.directory.deviceId ||
+                this.directory.activeContextId !== contextId))
+            throw new Error('Device session request was superseded');
         if (applied) {
             this.notify();
         }
@@ -634,8 +721,18 @@ export class SessionClient {
         }
     }
     async switchAccount(accountId) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/switch', { accountId }, { cache: false });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        const checked = deviceSessionSyncCheck(res, []);
+        const isStale = () => checked.ok &&
+            this.state?.deviceId === checked.value.state.deviceId &&
+            this.state.revision > checked.value.state.revision;
+        if (isStale())
+            throw new Error('Device session request was superseded');
+        await this.applySyncForMutation(res);
+        if (isStale())
+            throw new Error('Device session request was superseded');
         this.postCommitPing();
     }
     /**
@@ -650,10 +747,12 @@ export class SessionClient {
      * {@link signOutPrincipal} for the two that can tell those apart.
      */
     async signOut(target) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/signout', target, {
             cache: false,
         });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        await this.applySyncForMutation(res);
         this.postCommitPing();
         if (this.state?.accounts.length === 0)
             await this.persistFullSignOut();
@@ -695,21 +794,34 @@ export class SessionClient {
      * applied this revision.
      */
     async removeFromDevice(target) {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/signout', target, {
             cache: false,
         });
+        this.assertCurrentDeviceRequest(request, res);
         const removal = checkContract(deviceDirectorySyncCheck, res);
         if (!removal) {
             logger.warn('[SessionClient] discarded invalid device removal response');
             return;
         }
         const directoryApplied = this.applyDirectory(removal.directory);
+        const beforeCommit = this.captureDeviceRequest();
+        const commitLifecycle = this.lifecycleGeneration;
+        const expectedGeneration = beforeCommit.generation + (beforeCommit.initialDevice === removal.state.deviceId ? 0 : 1);
         const stateApplied = this.commitSync({
             state: removal.state,
             activeToken: removal.activeToken,
         });
-        if (this.fullSignOutPersistence?.state === this.state)
+        if (expectedGeneration !== this.deviceGeneration ||
+            commitLifecycle !== this.lifecycleGeneration)
+            throw new Error('Device session request was superseded');
+        if (this.fullSignOutPersistence?.state === this.state) {
+            const generation = this.deviceGeneration;
+            const lifecycle = this.lifecycleGeneration;
             await this.fullSignOutPersistence.pending;
+            if (generation !== this.deviceGeneration || lifecycle !== this.lifecycleGeneration)
+                throw new Error('Device session request was superseded');
+        }
         // `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.
@@ -721,10 +833,12 @@ export class SessionClient {
             await this.persistFullSignOut();
     }
     async addCurrentAccount() {
+        const request = this.captureDeviceRequest();
         const res = await this.requestDevice('POST', '/session/device/add', undefined, {
             cache: false,
         });
-        await this.applySync(res);
+        this.assertCurrentDeviceRequest(request, res);
+        await this.applySyncForMutation(res);
         this.postCommitPing();
     }
     /**

package/dist/types/HttpService.d.ts

@@ -228,6 +228,8 @@ export declare class HttpService {
      * bearer — and through the token listeners, the account — back.
      */
     private sessionEpoch;
+    /** Preserve a known device across legacy rotations which omit the claim. */
+    private sessionDeviceId;
     /**
      * Set by {@link endSession}, cleared by the next {@link setTokens}. Read by the
      * native Commons-identity re-mint arm: after a sign-out a 401 is the expected
@@ -509,8 +511,8 @@ export declare class HttpService {
      */
     endSession(): void;
     /**
-     * The current context epoch: account/session switches and bearer removal
-     * invalidate pending work; rotation within the same context preserves it.
+     * The current context epoch: account/session switches, known device changes,
+     * and bearer removal invalidate pending work; same-context rotation preserves it.
      * A re-mint lane that
      * plants tokens itself (the device-secret arm) compares it across its awaits.
      */

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

@@ -110,6 +110,8 @@ export declare class SessionClient {
     private tokenUnsub;
     private started;
     private lifecycleGeneration;
+    /** Changes whenever the locally projected device changes, including ABA. */
+    private deviceGeneration;
     private fullSignOutPersistence;
     /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
     private channel;
@@ -120,6 +122,10 @@ export declare class SessionClient {
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     private persistFullSignOut;
     private requestDevice;
+    /** Capture the local device before a request, including device ABA. */
+    private captureDeviceRequest;
+    private isCurrentDeviceRequest;
+    private assertCurrentDeviceRequest;
     /** Stop and discard only this client's local device projection; no server revocation. */
     resetLocalState(): void;
     getState(): DeviceSessionState | null;
@@ -189,6 +195,8 @@ export declare class SessionClient {
      * account that is no longer active.
      */
     private applySync;
+    /** Keep mutation callers from reporting success after a device change during persistence. */
+    private applySyncForMutation;
     /**
      * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.10.0",
+  "version": "7.10.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/HttpService.ts

@@ -74,6 +74,16 @@ function sameTokenSession(left: string | null, right: string | null): boolean {
     );
   }
   if (!(a.userId || a.id || a.sub) || !(b.userId || b.id || b.sub)) return false;
+  // A legacy bearer may omit deviceId; empty or non-string values also carry no
+  // usable device. Two known, different devices are distinct local contexts.
+  if (
+    typeof a.deviceId === 'string' &&
+    a.deviceId.length > 0 &&
+    typeof b.deviceId === 'string' &&
+    b.deviceId.length > 0 &&
+    a.deviceId !== b.deviceId
+  )
+    return false;
   // A refresh may rotate exp/iat/jti while preserving its account and session.
   // Opaque/malformed context fields cannot establish that equivalence.
   return [
@@ -88,6 +98,14 @@ function sameTokenSession(left: string | null, right: string | null): boolean {
   ].every((key) => (a[key] === undefined || typeof a[key] === 'string') && a[key] === b[key]);
 }
 
+/** Extract a known device for local ownership checks, never authorization. */
+function knownTokenDeviceId(token: string): string | null {
+  const claims = decodeTokenClaims(token);
+  return claims?.type !== 'service' && typeof claims?.deviceId === 'string' && claims.deviceId
+    ? claims.deviceId
+    : null;
+}
+
 /** Discard an unused body even when a platform's stream shim lacks cancel. */
 function discardResponseBody(response: Response): Promise<void> {
   try {
@@ -529,6 +547,8 @@ export class HttpService {
    * bearer — and through the token listeners, the account — back.
    */
   private sessionEpoch = 0;
+  /** Preserve a known device across legacy rotations which omit the claim. */
+  private sessionDeviceId: string | null = null;
   /**
    * Set by {@link endSession}, cleared by the next {@link setTokens}. Read by the
    * native Commons-identity re-mint arm: after a sign-out a 401 is the expected
@@ -825,9 +845,11 @@ export class HttpService {
     const authHeader = usesSessionAuth
       ? await awaitRequestSignal(this.getAuthHeader(), signal)
       : null;
-    const isOriginalSession = () =>
-      this.sessionEpoch === contextEpoch &&
-      sameTokenSession(contextToken, this.syncAccessTokenFromProvider());
+    const isOriginalSession = () => {
+      if (this.sessionEpoch !== contextEpoch) return false;
+      const currentToken = this.syncAccessTokenFromProvider();
+      return this.sessionEpoch === contextEpoch && sameTokenSession(contextToken, currentToken);
+    };
     const newerRequestToken = () => {
       if (!contextToken || !authHeader?.startsWith('Bearer ')) return null;
       const requestToken = authHeader.slice('Bearer '.length);
@@ -1060,6 +1082,7 @@ export class HttpService {
             if (isOriginalSession()) {
               if (this.tokenStore.getAccessToken()) this.sessionEpoch += 1;
               this.tokenStore.clearTokens();
+              this.sessionDeviceId = null;
               selfClearedEpoch = this.sessionEpoch;
               this.notifyTokenChange();
             }
@@ -2080,7 +2103,13 @@ export class HttpService {
   // Token management
   setTokens(accessToken: string): void {
     const current = this.tokenStore.getAccessToken();
-    if (current && !sameTokenSession(current, accessToken)) this.sessionEpoch += 1;
+    const deviceId = knownTokenDeviceId(accessToken);
+    const changed =
+      current !== null &&
+      (!sameTokenSession(current, accessToken) ||
+        (this.sessionDeviceId !== null && deviceId !== null && this.sessionDeviceId !== deviceId));
+    if (changed) this.sessionEpoch += 1;
+    this.sessionDeviceId = !current || changed ? deviceId : (deviceId ?? this.sessionDeviceId);
     this.sessionEnded = false;
     this.tokenStore.setTokens(accessToken);
     this.notifyTokenChange();
@@ -2100,8 +2129,8 @@ export class HttpService {
   }
 
   /**
-   * The current context epoch: account/session switches and bearer removal
-   * invalidate pending work; rotation within the same context preserves it.
+   * The current context epoch: account/session switches, known device changes,
+   * and bearer removal invalidate pending work; same-context rotation preserves it.
    * A re-mint lane that
    * plants tokens itself (the device-secret arm) compares it across its awaits.
    */
@@ -2136,6 +2165,7 @@ export class HttpService {
   clearTokens(): void {
     if (this.tokenStore.getAccessToken()) this.sessionEpoch += 1;
     this.tokenStore.clearTokens();
+    this.sessionDeviceId = null;
     // Drop the response cache on logout. The cache is identity-scoped, so a
     // different user could never read these entries, but a logged-out client
     // must not keep the previous session's personalized data resident in
@@ -2309,5 +2339,6 @@ export class HttpService {
   __resetTokensForTests(): void {
     this.sessionEnded = false;
     this.tokenStore.clearTokens();
+    this.sessionDeviceId = null;
   }
 }

package/src/session/SessionClient.ts

@@ -149,6 +149,8 @@ export class SessionClient {
   private tokenUnsub: (() => void) | null = null;
   private started = false;
   private lifecycleGeneration = 0;
+  /** Changes whenever the locally projected device changes, including ABA. */
+  private deviceGeneration = 0;
   private fullSignOutPersistence: { state: DeviceSessionState; pending: Promise<void> } | null =
     null;
   /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
@@ -188,6 +190,36 @@ export class SessionClient {
     return response;
   }
 
+  /** Capture the local device before a request, including device ABA. */
+  private captureDeviceRequest(): { generation: number; initialDevice: string | null } {
+    return { generation: this.deviceGeneration, initialDevice: this.state?.deviceId ?? null };
+  }
+
+  private isCurrentDeviceRequest(
+    request: { generation: number; initialDevice: string | null },
+    response: unknown,
+  ): boolean {
+    if (request.generation === this.deviceGeneration) return true;
+    if (request.initialDevice !== null || this.deviceGeneration !== request.generation + 1)
+      return false;
+    if (response === null || typeof response !== 'object') return false;
+    const record = response as {
+      deviceId?: unknown;
+      state?: { deviceId?: unknown };
+      directory?: { deviceId?: unknown };
+    };
+    const deviceId = record.state?.deviceId ?? record.directory?.deviceId ?? record.deviceId;
+    return typeof deviceId === 'string' && deviceId === this.state?.deviceId;
+  }
+
+  private assertCurrentDeviceRequest(
+    request: { generation: number; initialDevice: string | null },
+    response: unknown,
+  ): void {
+    if (!this.isCurrentDeviceRequest(request, response))
+      throw new Error('Device session request was superseded');
+  }
+
   /** Stop and discard only this client's local device projection; no server revocation. */
   resetLocalState(): void {
     this.lifecycleGeneration += 1;
@@ -351,6 +383,7 @@ export class SessionClient {
       return false;
     }
     const previousState = this.state;
+    if (previousState?.deviceId !== next.deviceId) this.deviceGeneration += 1;
     this.state = next;
     if (next.accounts.length === 0) {
       // A device with nobody signed in has no principals either. The directory
@@ -465,7 +498,7 @@ export class SessionClient {
         .ensureActiveToken(next)
         .then(finishApply)
         .catch((error) => {
-          if (generation !== this.lifecycleGeneration) return;
+          if (generation !== this.lifecycleGeneration || this.state !== next) return;
           logger.warn(
             '[SessionClient] ensureActiveToken failed — reverting session state',
             { component: 'SessionClient' },
@@ -473,6 +506,7 @@ export class SessionClient {
           );
           // Do NOT notify under a mismatched bearer. Revert to the last applied
           // state so subscribers keep observing the account whose token is planted.
+          if (this.state?.deviceId !== previousState?.deviceId) this.deviceGeneration += 1;
           this.state = previousState ?? null;
         });
     } else {
@@ -527,6 +561,25 @@ export class SessionClient {
       await this.fullSignOutPersistence.pending;
   }
 
+  /** Keep mutation callers from reporting success after a device change during persistence. */
+  private async applySyncForMutation(raw: unknown): Promise<void> {
+    const before = this.captureDeviceRequest();
+    const lifecycle = this.lifecycleGeneration;
+    const checked = deviceSessionSyncCheck(raw, []);
+    const responseDevice = checked.ok ? checked.value.state.deviceId : before.initialDevice;
+    const expectedGeneration =
+      before.generation + (responseDevice === before.initialDevice ? 0 : 1);
+    const pending = this.applySync(raw);
+    const generation = this.deviceGeneration;
+    await pending;
+    if (
+      generation !== expectedGeneration ||
+      generation !== this.deviceGeneration ||
+      lifecycle !== this.lifecycleGeneration
+    )
+      throw new Error('Device session request was superseded');
+  }
+
   /**
    * 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
@@ -546,15 +599,16 @@ export class SessionClient {
     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`).
+    // needs planting. Only the exact same device revision is an equal-revision
+    // restate: an older response may identify a different operator of the same
+    // account. Also require the current account and the identity pin to match.
     const pinnedAccountId = this.pinnedAccountId();
     if (
       !applied &&
       sync.activeToken &&
       this.state &&
+      sync.state.deviceId === this.state.deviceId &&
+      sync.state.revision === this.state.revision &&
       sync.state.activeAccountId !== null &&
       sync.state.activeAccountId === this.state.activeAccountId &&
       (pinnedAccountId === null || sync.state.activeAccountId === pinnedAccountId) &&
@@ -609,9 +663,11 @@ export class SessionClient {
 
   /** `GET /session/device/directory` → {@link applyDirectory}. No notify. */
   private async fetchDirectory(): Promise<boolean> {
+    const request = this.captureDeviceRequest();
     const res = await this.requestDevice<unknown>('GET', '/session/device/directory', undefined, {
       cache: false,
     });
+    if (!this.isCurrentDeviceRequest(request, res)) return false;
     return this.applyDirectory(res);
   }
 
@@ -684,14 +740,12 @@ export class SessionClient {
     if (!accessToken) {
       return;
     }
+    const pinnedAccountId = this.pinnedAccountId();
     const subjectAccountId = resolveActiveContext(directory)?.subject.accountId ?? null;
     if (subjectAccountId === null) {
       return;
     }
-    const pinnedAccountId = this.pinnedAccountId();
-    if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId) {
-      return;
-    }
+    if (pinnedAccountId !== null && subjectAccountId !== pinnedAccountId) return;
     if (accessToken === this.host.getAccessToken()) {
       return;
     }
@@ -738,9 +792,11 @@ export class SessionClient {
   }
 
   async bootstrap(): Promise<void> {
+    const request = this.captureDeviceRequest();
     const res = await this.requestDevice<unknown>('GET', '/session/device/state', undefined, {
       cache: false,
     });
+    if (!this.isCurrentDeviceRequest(request, res)) return;
     await this.applySync(res);
   }
 
@@ -787,18 +843,51 @@ export class SessionClient {
    * compatibility path for callers still keyed on account ids.
    */
   async activateContext(contextId: string): Promise<void> {
+    const request = this.captureDeviceRequest();
     const res = await this.requestDevice<unknown>(
       'POST',
       '/session/device/activate',
       { contextId },
       { cache: false },
     );
+    this.assertCurrentDeviceRequest(request, res);
     const activation = checkContract(deviceActivateResponseCheck, res);
     if (!activation) {
       logger.warn('[SessionClient] discarded invalid activation response');
       return;
     }
+    if (this.pinnedAccountId() === null) {
+      const active = resolveActiveContext(activation.directory);
+      if (!active || activation.directory.activeContextId !== contextId)
+        throw new Error('Device session request was superseded');
+      const claims = activation.activeToken?.accessToken
+        ? decodeTokenClaims(activation.activeToken.accessToken)
+        : null;
+      const contextClaim = claims?.device_context_id;
+      const actor = claims?.act;
+      const actorClaim =
+        actor !== null && typeof actor === 'object' ? (actor as { sub?: unknown }).sub : undefined;
+      const subjectClaim = claims?.userId ?? claims?.id ?? claims?.sub;
+      // Decoded claims are only a consistency check, never authorization.
+      // Legacy and opaque bearers may omit these claims entirely.
+      if (
+        (typeof contextClaim === 'string' && contextClaim !== active.contextId) ||
+        (typeof actorClaim === 'string' && actorClaim !== active.actor.userId) ||
+        (typeof subjectClaim === 'string' && subjectClaim !== active.subject.accountId)
+      )
+        throw new Error('Device session request was superseded');
+    }
     const known = this.knownRevisionFor(activation.directory.deviceId);
+    if (known !== null && activation.directory.revision < known)
+      throw new Error('Device session request was superseded');
+    const held = this.directory;
+    if (
+      this.pinnedAccountId() === null &&
+      held?.deviceId === activation.directory.deviceId &&
+      held.revision === activation.directory.revision &&
+      held.activeContextId !== activation.directory.activeContextId
+    )
+      throw new Error('Device session request was superseded');
     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
@@ -808,8 +897,26 @@ export class SessionClient {
     // already holding in hand.
     const applied = this.applyDirectory(activation.directory);
     if (moved) {
+      const beforeReconcile = this.captureDeviceRequest();
+      const lifecycle = this.lifecycleGeneration;
       await this.reconcileFlatState(activation.directory);
+      const landedOnTarget =
+        beforeReconcile.initialDevice !== activation.directory.deviceId &&
+        this.deviceGeneration === beforeReconcile.generation + 1 &&
+        this.state?.deviceId === activation.directory.deviceId;
+      if (
+        lifecycle !== this.lifecycleGeneration ||
+        (this.deviceGeneration !== beforeReconcile.generation && !landedOnTarget)
+      )
+        throw new Error('Device session request was superseded');
     }
+    if (
+      this.pinnedAccountId() === null &&
+      (this.knownRevisionFor(activation.directory.deviceId) !== activation.directory.revision ||
+        this.directory?.deviceId !== activation.directory.deviceId ||
+        this.directory.activeContextId !== contextId)
+    )
+      throw new Error('Device session request was superseded');
     if (applied) {
       this.notify();
     }
@@ -819,13 +926,22 @@ export class SessionClient {
   }
 
   async switchAccount(accountId: string): Promise<void> {
+    const request = this.captureDeviceRequest();
     const res = await this.requestDevice<unknown>(
       'POST',
       '/session/device/switch',
       { accountId },
       { cache: false },
     );
-    await this.applySync(res);
+    this.assertCurrentDeviceRequest(request, res);
+    const checked = deviceSessionSyncCheck(res, []);
+    const isStale = () =>
+      checked.ok &&
+      this.state?.deviceId === checked.value.state.deviceId &&
+      this.state.revision > checked.value.state.revision;
+    if (isStale()) throw new Error('Device session request was superseded');
+    await this.applySyncForMutation(res);
+    if (isStale()) throw new Error('Device session request was superseded');
     this.postCommitPing();
   }
 
@@ -841,10 +957,12 @@ export class SessionClient {
    * {@link signOutPrincipal} for the two that can tell those apart.
    */
   async signOut(target: { accountId: string } | { all: true }): Promise<void> {
+    const request = this.captureDeviceRequest();
     const res = await this.requestDevice<unknown>('POST', '/session/device/signout', target, {
       cache: false,
     });
-    await this.applySync(res);
+    this.assertCurrentDeviceRequest(request, res);
+    await this.applySyncForMutation(res);
     this.postCommitPing();
     if (this.state?.accounts.length === 0) await this.persistFullSignOut();
   }
@@ -890,21 +1008,37 @@ export class SessionClient {
   private async removeFromDevice(
     target: { contextId: string } | { principalId: string },
   ): Promise<void> {
+    const request = this.captureDeviceRequest();
     const res = await this.requestDevice<unknown>('POST', '/session/device/signout', target, {
       cache: false,
     });
+    this.assertCurrentDeviceRequest(request, res);
     const removal = checkContract(deviceDirectorySyncCheck, res);
     if (!removal) {
       logger.warn('[SessionClient] discarded invalid device removal response');
       return;
     }
     const directoryApplied = this.applyDirectory(removal.directory);
+    const beforeCommit = this.captureDeviceRequest();
+    const commitLifecycle = this.lifecycleGeneration;
+    const expectedGeneration =
+      beforeCommit.generation + (beforeCommit.initialDevice === removal.state.deviceId ? 0 : 1);
     const stateApplied = this.commitSync({
       state: removal.state,
       activeToken: removal.activeToken,
     });
-    if (this.fullSignOutPersistence?.state === this.state)
+    if (
+      expectedGeneration !== this.deviceGeneration ||
+      commitLifecycle !== this.lifecycleGeneration
+    )
+      throw new Error('Device session request was superseded');
+    if (this.fullSignOutPersistence?.state === this.state) {
+      const generation = this.deviceGeneration;
+      const lifecycle = this.lifecycleGeneration;
       await this.fullSignOutPersistence.pending;
+      if (generation !== this.deviceGeneration || lifecycle !== this.lifecycleGeneration)
+        throw new Error('Device session request was superseded');
+    }
     // `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.
@@ -916,10 +1050,12 @@ export class SessionClient {
   }
 
   async addCurrentAccount(): Promise<void> {
+    const request = this.captureDeviceRequest();
     const res = await this.requestDevice<unknown>('POST', '/session/device/add', undefined, {
       cache: false,
     });
-    await this.applySync(res);
+    this.assertCurrentDeviceRequest(request, res);
+    await this.applySyncForMutation(res);
     this.postCommitPing();
   }