@oxy.so/core 1.9.1 → 1.10.0

package/src/__tests__/{httpServiceCsrf.test.ts → httpServiceWrites.test.ts}

@@ -31,7 +31,12 @@ function readHeaders(init: RequestInit | undefined): Record<string, string> {
   return headers as Record<string, string>;
 }
 
-describe('HttpService CSRF behavior', () => {
+/**
+ * Writes carry exactly one credential: the bearer, when there is one. Oxy's API
+ * has no CSRF layer (issue #1044) and the SDK neither fetches `/csrf-token` nor
+ * sends `X-CSRF-Token` / `X-Native-App`, for its own API or a linked one.
+ */
+describe('HttpService writes', () => {
   const originalFetch = globalThis.fetch;
 
   afterEach(() => {
@@ -39,13 +44,18 @@ describe('HttpService CSRF behavior', () => {
     jest.restoreAllMocks();
   });
 
-  it('does not fetch csrf-token before bearer-authenticated writes', async () => {
+  function recordFetches(respond: (url: string) => Response = () => jsonResponse({ ok: true })): FetchCall[] {
     const calls: FetchCall[] = [];
     globalThis.fetch = async (input, init) => {
       const url = String(input);
       calls.push({ url, init });
-      return jsonResponse({ ok: true });
+      return respond(url);
     };
+    return calls;
+  }
+
+  it('sends a bearer-authenticated write as a single request', async () => {
+    const calls = recordFetches();
 
     const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
     const accessToken = createJwt({
@@ -56,20 +66,31 @@ describe('HttpService CSRF behavior', () => {
 
     await http.post('/posts', { text: 'hello' });
 
-    expect(calls).toHaveLength(1);
-    expect(calls[0].url).toBe('https://api.mention.earth/posts');
+    expect(calls.map((call) => call.url)).toEqual(['https://api.mention.earth/posts']);
     const headers = readHeaders(calls[0].init);
     expect(headers.Authorization).toBe(`Bearer ${accessToken}`);
     expect(headers['X-CSRF-Token']).toBeUndefined();
+    expect(headers['X-Native-App']).toBeUndefined();
+  });
+
+  it('sends a write without a bearer as a single request with no CSRF preflight', async () => {
+    const calls = recordFetches();
+
+    const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
+
+    await http.post('/users/by-ids', { ids: ['user_1'] });
+
+    // POSITIVE CONTROL: the write itself went out, so the absence below is not
+    // the absence of any request at all.
+    expect(calls.map((call) => call.url)).toEqual(['https://api.oxy.so/users/by-ids']);
+    const headers = readHeaders(calls[0].init);
+    expect(headers.Authorization).toBeUndefined();
+    expect(headers['X-CSRF-Token']).toBeUndefined();
+    expect(headers['X-Native-App']).toBeUndefined();
   });
 
   it('keeps a valid near-expiry bearer token when preflight refresh cannot refresh', async () => {
-    const calls: FetchCall[] = [];
-    globalThis.fetch = async (input, init) => {
-      const url = String(input);
-      calls.push({ url, init });
-      return jsonResponse({ ok: true });
-    };
+    const calls = recordFetches();
 
     const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
     const accessToken = createJwt({
@@ -86,26 +107,12 @@ describe('HttpService CSRF behavior', () => {
     await http.post('/posts', { text: 'hello' });
 
     expect(refreshAttempts).toBe(1);
-    expect(calls).toHaveLength(1);
-    expect(calls[0].url).toBe('https://api.mention.earth/posts');
-    const headers = readHeaders(calls[0].init);
-    expect(headers.Authorization).toBe(`Bearer ${accessToken}`);
-    expect(headers['X-CSRF-Token']).toBeUndefined();
+    expect(calls.map((call) => call.url)).toEqual(['https://api.mention.earth/posts']);
+    expect(readHeaders(calls[0].init).Authorization).toBe(`Bearer ${accessToken}`);
   });
 
   it('does not use an expired bearer token when preflight refresh cannot refresh', async () => {
-    const calls: FetchCall[] = [];
-    globalThis.fetch = async (input, init) => {
-      const url = String(input);
-      calls.push({ url, init });
-      if (url.endsWith('/csrf-token')) {
-        return new Response(JSON.stringify({ csrfToken: 'csrf_1' }), {
-          status: 200,
-          headers: { 'content-type': 'application/json' },
-        });
-      }
-      return jsonResponse({ ok: true });
-    };
+    const calls = recordFetches();
 
     const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
     const accessToken = createJwt({
@@ -122,48 +129,28 @@ describe('HttpService CSRF behavior', () => {
     await http.post('/posts', { text: 'hello' });
 
     expect(refreshAttempts).toBe(1);
-    expect(calls.map((call) => call.url)).toEqual([
-      'https://api.mention.earth/csrf-token',
-      'https://api.mention.earth/posts',
-    ]);
-    const headers = readHeaders(calls[1].init);
-    expect(headers.Authorization).toBeUndefined();
-    expect(headers['X-CSRF-Token']).toBe('csrf_1');
+    expect(calls.map((call) => call.url)).toEqual(['https://api.mention.earth/posts']);
+    expect(readHeaders(calls[0].init).Authorization).toBeUndefined();
   });
 
-  it('still fetches csrf-token for cookie-authenticated writes without bearer', async () => {
-    const calls: FetchCall[] = [];
-    globalThis.fetch = async (input, init) => {
-      const url = String(input);
-      calls.push({ url, init });
-      if (url.endsWith('/csrf-token')) {
-        return new Response(JSON.stringify({ csrfToken: 'csrf_1' }), {
-          status: 200,
+  it('does not retry a 403, whatever its code says', async () => {
+    const calls = recordFetches(
+      () =>
+        new Response(JSON.stringify({ code: 'CSRF_TOKEN_INVALID' }), {
+          status: 403,
+          statusText: 'Forbidden',
           headers: { 'content-type': 'application/json' },
-        });
-      }
-      return jsonResponse({ ok: true });
-    };
+        }),
+    );
 
     const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
 
-    await http.post('/posts', { text: 'hello' });
-
-    expect(calls.map((call) => call.url)).toEqual([
-      'https://api.mention.earth/csrf-token',
-      'https://api.mention.earth/posts',
-    ]);
-    const headers = readHeaders(calls[1].init);
-    expect(headers.Authorization).toBeUndefined();
-    expect(headers['X-CSRF-Token']).toBe('csrf_1');
+    await expect(http.post('/posts', { text: 'hello' })).rejects.toBeDefined();
+    expect(calls.map((call) => call.url)).toEqual(['https://api.mention.earth/posts']);
   });
 
   it('includes credentials for configured API origin requests', async () => {
-    const calls: FetchCall[] = [];
-    globalThis.fetch = async (input, init) => {
-      calls.push({ url: String(input), init });
-      return jsonResponse({ ok: true });
-    };
+    const calls = recordFetches();
 
     const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
 
@@ -175,11 +162,7 @@ describe('HttpService CSRF behavior', () => {
   });
 
   it('omits credentials for caller-supplied absolute URLs outside the configured API origin', async () => {
-    const calls: FetchCall[] = [];
-    globalThis.fetch = async (input, init) => {
-      calls.push({ url: String(input), init });
-      return jsonResponse({ ok: true });
-    };
+    const calls = recordFetches();
 
     const http = new HttpService({ baseURL: 'https://api.oxy.so', enableRetry: false });
 
@@ -189,47 +172,4 @@ describe('HttpService CSRF behavior', () => {
     expect(calls[0].url).toBe('https://attacker.oxy.so/collect');
     expect(calls[0].init?.credentials).toBe('omit');
   });
-
-  it('bypasses request deduplication for the internal CSRF retry', async () => {
-    const calls: FetchCall[] = [];
-    let csrfFetches = 0;
-    let postFetches = 0;
-
-    globalThis.fetch = async (input, init) => {
-      const url = String(input);
-      calls.push({ url, init });
-
-      if (url.endsWith('/csrf-token')) {
-        csrfFetches += 1;
-        return new Response(JSON.stringify({ csrfToken: `csrf_${csrfFetches}` }), {
-          status: 200,
-          headers: { 'content-type': 'application/json' },
-        });
-      }
-
-      postFetches += 1;
-      if (postFetches === 1) {
-        return new Response(JSON.stringify({ code: 'CSRF_TOKEN_INVALID' }), {
-          status: 403,
-          statusText: 'Forbidden',
-          headers: { 'content-type': 'application/json' },
-        });
-      }
-
-      return jsonResponse({ ok: true });
-    };
-
-    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
-
-    await expect(http.post('/posts', { text: 'hello' })).resolves.toEqual({ ok: true });
-    expect(calls.map((call) => call.url)).toEqual([
-      'https://api.mention.earth/csrf-token',
-      'https://api.mention.earth/posts',
-      'https://api.mention.earth/csrf-token',
-      'https://api.mention.earth/posts',
-    ]);
-
-    expect(readHeaders(calls[1].init)['X-CSRF-Token']).toBe('csrf_1');
-    expect(readHeaders(calls[3].init)['X-CSRF-Token']).toBe('csrf_2');
-  });
 });

package/src/__tests__/inSessionRefresh.test.ts

@@ -233,6 +233,59 @@ describe('HttpService in-session refresh handler', () => {
   });
 });
 
+describe('HttpService.endSession — a sign-out outranks a refresh', () => {
+  it('plants nothing when the session ends while a re-mint is in flight', async () => {
+    const oldToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'old' });
+    const lateToken = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'late' });
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    http.setTokens(oldToken);
+
+    let finish!: (token: string | null) => void;
+    http.setAuthRefreshHandler(
+      () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        }),
+    );
+    const seen: Array<string | null> = [];
+    http.addTokenChangeListener((token) => seen.push(token));
+
+    const pending = http.refreshAccessToken('preflight');
+    http.endSession();
+    finish(lateToken);
+
+    await expect(pending).resolves.toBeNull();
+    expect(http.getAccessToken()).toBeNull();
+    expect(seen).toEqual([null]);
+  });
+
+  it('abandons only what was in flight: a later re-mint (another tab signed in) still runs', async () => {
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    const fresh = createJwt({ userId: 'u', exp: farFutureExp(), jti: 'fresh' });
+    const handler = jest.fn(async () => fresh);
+    http.setAuthRefreshHandler(handler);
+
+    http.endSession();
+    expect(http.hasSessionEnded()).toBe(true);
+    await expect(http.refreshAccessToken('preflight')).resolves.toBe(fresh);
+    expect(http.getAccessToken()).toBe(fresh);
+    expect(http.hasSessionEnded()).toBe(false);
+  });
+
+  it('is what OxyServices.clearTokens does; a plain HttpService.clearTokens (a mirror) is not', () => {
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const before = oxy.httpService.getSessionEpoch();
+    oxy.clearTokens();
+    expect(oxy.httpService.getSessionEpoch()).toBe(before + 1);
+    expect(oxy.httpService.hasSessionEnded()).toBe(true);
+
+    const mirror = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    mirror.clearTokens();
+    expect(mirror.getSessionEpoch()).toBe(0);
+    expect(mirror.hasSessionEnded()).toBe(false);
+  });
+});
+
 describe('OxyServices.getAccessTokenExpiry', () => {
   it('returns the JWT exp (seconds) of the current access token', () => {
     const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });

package/src/__tests__/linkedClient.test.ts

@@ -208,13 +208,6 @@ describe('OxyServices.createLinkedClient', () => {
       const url = String(input);
       calls.push({ url, init });
 
-      if (url.endsWith('/csrf-token')) {
-        return new Response(JSON.stringify({ csrfToken: 'csrf_1' }), {
-          status: 200,
-          headers: { 'content-type': 'application/json' },
-        });
-      }
-
       if (url.endsWith('/api/queue/current')) {
         queueWriteAttempts += 1;
         if (queueWriteAttempts === 1) {

package/src/boot/__tests__/sessionColdBoot.identity.test.ts

@@ -104,7 +104,7 @@ function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: j
       overrides.requestChallenge
       ?? (async () => ({ challenge: 'chal-1', expiresAt: '2030-01-01T00:00:00.000Z' })),
     verifyChallenge: overrides.verifyChallenge ?? (async () => IDENTITY_SESSION),
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight(), getSessionEpoch: () => 0 },
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }

package/src/boot/__tests__/sessionColdBoot.sharedDevice.test.ts

@@ -79,7 +79,7 @@ function makeOxy(overrides: {
     setTokens,
     mintFromDeviceSecret,
     signInWithSharedIdentity,
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight(), getSessionEpoch: () => 0 },
   } as unknown as OxyServices;
   return { oxy, setTokens, mintFromDeviceSecret, signInWithSharedIdentity };
 }

package/src/boot/__tests__/sessionColdBoot.test.ts

@@ -45,7 +45,7 @@ function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: j
         throw new Error('mintFromDeviceSecret not stubbed');
       }),
     // The device-secret-mint step runs through the client's single-flight.
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight(), getSessionEpoch: () => 0 },
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }

package/src/boot/sessionColdBoot.ts

@@ -326,6 +326,9 @@ export async function runSessionColdBoot(
             { component: 'sessionColdBoot', method: 'device-secret-mint' },
           );
           return { kind: 'skip' };
+        case 'session-ended':
+          // Signed out while the boot was minting; the arm planted nothing.
+          return { kind: 'skip' };
         case 'no-secret':
           return { kind: 'skip' };
       }

package/src/mixins/OxyServices.user.ts

@@ -470,10 +470,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      *   `PostHydrationService`) and is unchanged.
      * - **Plain client (browser / React Native with a user session):** when no
      *   service credentials are configured, the chunk is fetched via
-     *   `makeRequest`, which attaches the configured user bearer. oxy-api's CSRF
-     *   middleware skips bearer-authenticated writes, and `makeRequest` only
-     *   fetches a CSRF token for cookie-only (no-bearer) state-changing requests,
-     *   so the user-bearer POST is sent without CSRF and succeeds. Previously
+     *   `makeRequest`, which attaches the configured user bearer. Previously
      *   this method always used the service path, so every client-side caller
      *   silently received `[]` because `getServiceToken()` had no credentials.
      *
@@ -504,7 +501,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
       // A backend that called configureServiceAuth() uses the bearer-service
       // path; any other caller (browser / RN with a user session) uses the
-      // user-bearer path. See the method doc for why the user path is CSRF-safe.
+      // user-bearer path.
       const useServiceAuth = Boolean(this._serviceApiKey && this._serviceApiSecret);
 
       // Run chunks concurrently; a single chunk failure must not sink the rest.

package/src/mixins/__tests__/backgroundCredential.httpIntegration.test.ts

@@ -22,11 +22,9 @@ import { OxyServices } from '../../OxyServices';
  *     hand-built `Object.assign(new Error(), { status: 404 })` proves only that
  *     the branch reads the shape the test itself invented.
  *
- * The stub is URL-aware because a state-changing request through the real stack
- * fetches `GET /csrf-token` FIRST. A blanket stub answers that call too, which
- * both shifts the request under test out of `calls[0]` and (on a non-200 stub)
- * makes the CSRF fetch burn its own retries — so a naive call-count assertion
- * measures CSRF attempts rather than the route.
+ * Assertions select calls by URL rather than position, so a preflight added
+ * to the real stack later cannot make a call-count assertion measure it
+ * instead of the route.
  */
 const ROUTE = '/session/device/background-credential';
 
@@ -67,19 +65,16 @@ const ACCESS_TOKEN = (() => {
 describe('provisionBackgroundCredential over a real HttpService', () => {
   const originalFetch = global.fetch;
 
-  /** Answers the CSRF preflight properly; answers the route under test with `body`/`status`. */
+  /** Answers every call with `body`/`status`. */
   const stubFetch = (body: unknown, status: number) => {
     const fetchMock = jest.fn(async (input: unknown) => {
-      if (String(input).includes('/csrf-token')) {
-        return jsonResponse({ csrfToken: 'csrf-test-token' }, 200);
-      }
       return jsonResponse(body, status);
     });
     global.fetch = fetchMock as unknown as typeof fetch;
     return fetchMock;
   };
 
-  /** Every stubbed call whose URL is the route under test (i.e. not the CSRF preflight). */
+  /** Every stubbed call whose URL is the route under test. */
   const routeCalls = (fetchMock: jest.Mock) =>
     fetchMock.mock.calls.filter(([input]) => String(input).includes(ROUTE));
 

package/src/mixins/__tests__/discoveryErrorHandling.test.ts

@@ -27,7 +27,7 @@ function jsonResponse(data: unknown): Response {
  * Build a non-verified JWT whose payload decodes to the given claims.
  * `jwtDecode` only base64url-decodes the middle segment (no signature check).
  * Used to put the SDK in an authenticated state so a state-changing POST
- * carries a bearer header and skips the CSRF-token pre-fetch.
+ * carries a bearer header.
  */
 function makeJwt(payload: Record<string, unknown>): string {
   const b64url = (obj: Record<string, unknown>): string =>
@@ -142,9 +142,8 @@ describe('discovery error handling', () => {
    * `POST /profiles/recommendations` with the validated request body.
    */
   describe('getProfileRecommendations routing (GET vs POST)', () => {
-    // Authenticate so the state-changing POST carries a bearer header and the
-    // SDK skips the CSRF-token pre-fetch (which would otherwise consume a mock).
-    // A bearer token does not affect GET routing or the request body, so the
+    // Authenticate so the state-changing POST carries a bearer header. A bearer
+    // token does not affect GET routing or the request body, so the
     // GET-path assertions below are unaffected.
     beforeEach(() => {
       oxy.httpService.setTokens(makeJwt({ userId: 'me' }));

package/src/mixins/__tests__/topics.test.ts

@@ -24,8 +24,7 @@ function rawResponse(body: unknown): Response {
 
 /**
  * A non-verified JWT whose payload decodes to the given claims. Puts the SDK in
- * an authenticated state so the `POST /topics/resolve` carries a bearer header
- * and skips the CSRF-token pre-fetch (which would otherwise consume a mock).
+ * an authenticated state so the `POST /topics/resolve` carries a bearer header.
  */
 function makeJwt(payload: Record<string, unknown>): string {
   const b64url = (obj: Record<string, unknown>): string =>
@@ -59,7 +58,7 @@ describe('topics mixin envelope unwrapping', () => {
     fetchMock = jest.fn();
     globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
     oxy = new OxyServices({ baseURL: 'http://test.invalid', enableRetry: false });
-    // Authenticate so the resolve POST skips the CSRF pre-fetch. Harmless for GETs.
+    // Authenticate so the resolve POST carries a bearer. Harmless for GETs.
     oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
   });
 

package/src/server/cors.ts

@@ -40,7 +40,6 @@ const DEFAULT_ALLOWED_HEADERS = [
   'X-Requested-With',
   'X-Oxy-User-Id',
   'X-Oxy-Internal',
-  'X-CSRF-Token',
   'X-Oxy-Edge-Region',
   'X-Oxy-Activity-Id',
 ];

package/src/session/__tests__/refresh.identityPin.test.ts

@@ -82,7 +82,7 @@ function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: j
       overrides.requestChallenge
       ?? (async () => ({ challenge: 'chal-1', expiresAt: '2030-01-01T00:00:00.000Z' })),
     verifyChallenge: overrides.verifyChallenge ?? (async () => IDENTITY_SESSION),
-    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight() },
+    httpService: { runSingleFlightDeviceSecretMint: makeMintSingleFlight(), getSessionEpoch: () => 0 },
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }

package/src/session/__tests__/refresh.test.ts

@@ -59,8 +59,18 @@ interface RefreshMockOverrides {
 
 function makeOxy(
   overrides: RefreshMockOverrides = {},
-): { oxy: OxyServices; setTokens: jest.Mock; noteRefreshRateLimited: jest.Mock } {
+): {
+  oxy: OxyServices;
+  setTokens: jest.Mock;
+  noteRefreshRateLimited: jest.Mock;
+  /** `HttpService`'s session epoch; bump it to simulate a sign-out mid-refresh. */
+  epoch: { current: number };
+  /** `HttpService.hasSessionEnded()`: a sign-out with no token planted since. */
+  ended: { current: boolean };
+} {
   const setTokens = jest.fn();
+  const epoch = { current: 0 };
+  const ended = { current: false };
   const noteRefreshRateLimited = jest.fn();
   const oxy = {
     setTokens,
@@ -71,9 +81,11 @@ function makeOxy(
     httpService: {
       runSingleFlightDeviceSecretMint: makeMintSingleFlight(),
       noteRefreshRateLimited,
+      getSessionEpoch: () => epoch.current,
+      hasSessionEnded: () => ended.current,
     },
   } as unknown as OxyServices;
-  return { oxy, setTokens, noteRefreshRateLimited };
+  return { oxy, setTokens, noteRefreshRateLimited, epoch, ended };
 }
 
 describe('refreshPersistedSession — arm 1 (device-secret mint)', () => {
@@ -297,6 +309,107 @@ describe('refreshPersistedSession — arm 2 (native shared-key fallback)', () =>
   });
 });
 
+describe('refreshPersistedSession — a sign-out mid-refresh', () => {
+  it('arm 1: plants nothing and leaves a cleared store cleared', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    let respond!: () => void;
+    const { oxy, setTokens, epoch } = makeOxy({
+      mintFromDeviceSecret: () =>
+        new Promise((resolve) => {
+          respond = () => resolve(MINT);
+        }),
+    });
+
+    const pending = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // The sign-out: the credential is dropped and the session epoch moves.
+    await store.clear();
+    epoch.current += 1;
+    respond();
+
+    await expect(pending).resolves.toBeNull();
+    expect(setTokens).not.toHaveBeenCalled();
+    expect(await store.load()).toBeNull();
+  });
+
+  it('arm 1: still persists the rotated secret when the store kept the credential', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    let respond!: () => void;
+    const { oxy, setTokens, epoch } = makeOxy({
+      mintFromDeviceSecret: () =>
+        new Promise((resolve) => {
+          respond = () => resolve(MINT);
+        }),
+    });
+
+    const pending = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // A local teardown that keeps the store (so a reload can restore): the
+    // server rotated the secret, and the store must not be left holding the old one.
+    epoch.current += 1;
+    respond();
+
+    await expect(pending).resolves.toBeNull();
+    expect(setTokens).not.toHaveBeenCalled();
+    expect((await store.load())?.deviceSecret).toBe('ds-next-secret');
+  });
+
+  it('arm 2: the shared keychain does not sign the user back in', async () => {
+    const store = createMemoryAuthStateStore();
+    let respond!: () => void;
+    const signInWithSharedIdentity = jest.fn(
+      (_opts?: { plantTokens?: boolean }) =>
+        new Promise<SessionLoginResponse>((resolve) => {
+          respond = () =>
+            resolve({
+              sessionId: 'sess-shared',
+              deviceId: 'dev-1',
+              deviceSecret: 'ds-shared',
+              expiresAt: '2030-01-01T00:00:00.000Z',
+              user: { id: 'user-1', username: 'u', name: {}, avatar: undefined },
+              accessToken: 'access-shared',
+            });
+        }),
+    );
+    const { oxy, setTokens, epoch } = makeOxy({ signInWithSharedIdentity });
+
+    const pending = refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    epoch.current += 1;
+    respond();
+
+    await expect(pending).resolves.toBeNull();
+    expect(signInWithSharedIdentity).toHaveBeenCalledWith({ plantTokens: false });
+    expect(setTokens).not.toHaveBeenCalled();
+    expect(await store.load()).toBeNull();
+  });
+});
+
+describe('refreshPersistedSession — after a sign-out', () => {
+  it('does not re-sign-in with the shared keychain', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => null);
+    const { oxy, setTokens, ended } = makeOxy({ signInWithSharedIdentity });
+    ended.current = true;
+
+    await expect(refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).resolves.toBeNull();
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+    expect(setTokens).not.toHaveBeenCalled();
+  });
+
+  it('still mints from a device credential the store holds (a sign-in made in another tab)', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy, setTokens, ended } = makeOxy();
+    ended.current = true;
+
+    await expect(refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true })).resolves.toBe('access-new');
+    expect(setTokens).toHaveBeenCalledWith('access-new');
+  });
+});
+
 describe('refreshPersistedSession — single-flight (no double-rotation)', () => {
   it('coalesces two concurrent mints into ONE server rotation; the store holds the final current secret', async () => {
     // The server rotates the secret on every mint. Two concurrent lanes must