@oxyhq/core 5.4.3 → 6.0.0

package/src/session/__tests__/SessionClient.rest.test.ts

@@ -77,4 +77,29 @@ describe('SessionClient REST', () => {
     expect(c.getState()?.revision).toBe(7);
     expect(host.setTokens).not.toHaveBeenCalled();
   });
+
+  it('accepts a NEW device\'s lower-revision state and plants its token (cross-device revision reset)', async () => {
+    const deviceA: DeviceSessionState = {
+      deviceId: 'A', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: 10, updatedAt: 1720000000000,
+    };
+    const deviceB: DeviceSessionState = {
+      deviceId: 'B', accounts: [{ accountId: 'a2', sessionId: 's2', authuser: 0 }], activeAccountId: 'a2', revision: 1, updatedAt: 1720000001000,
+    };
+    const makeRequest = jest.fn()
+      .mockResolvedValueOnce({ state: deviceA, activeToken: { accessToken: 'jwt-A', expiresAt: 'x' } })
+      .mockResolvedValueOnce({ state: deviceB, activeToken: { accessToken: 'jwt-B', expiresAt: 'x' } });
+    const host = makeHost(makeRequest);
+    const c = new SessionClient(host);
+
+    await c.bootstrap();
+    expect(c.getState()?.deviceId).toBe('A');
+    expect(host.setTokens).toHaveBeenLastCalledWith('jwt-A');
+
+    // Device B is freshly converged (revision 1) — it must win over device A's
+    // stale-but-higher revision, and its token must be planted.
+    await c.bootstrap();
+    expect(c.getState()?.deviceId).toBe('B');
+    expect(c.getState()?.revision).toBe(1);
+    expect(host.setTokens).toHaveBeenLastCalledWith('jwt-B');
+  });
 });

package/src/session/__tests__/SessionClient.socketFactory.test.ts

@@ -0,0 +1,79 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import * as socketLoader from '../socketLoader';
+import type { MinimalSocket, SocketIOFactory } from '../socketLoader';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+/**
+ * P0 (bundler-fragility): SessionClient must NOT depend on a runtime dynamic
+ * `import('socket.io-client')` when a consumer (services/auth-sdk) injects the
+ * `io` factory statically. These tests pin the two branches of `connectSocket`:
+ *
+ *  1. `socketFactory` injected  → the injected factory is used and the lazy
+ *     loader (`getSocketIO`) is NEVER invoked (the exact call that fails in the
+ *     Metro/Expo-web + Vite published-dist consumers).
+ *  2. no `socketFactory`        → the lazy loader IS invoked (fallback).
+ */
+
+type Handler = (...args: unknown[]) => void;
+class FakeSocket implements MinimalSocket {
+  connected = false;
+  handlers = new Map<string, Handler[]>();
+  on(event: string, cb: Handler) { const l = this.handlers.get(event) ?? []; l.push(cb); this.handlers.set(event, l); }
+  off(event: string, cb?: Handler) { if (!cb) { this.handlers.delete(event); return; } this.handlers.set(event, (this.handlers.get(event) ?? []).filter((h) => h !== cb)); }
+  connect() { this.connected = true; }
+  disconnect() { this.connected = false; }
+}
+
+const STATE = (rev: number): DeviceSessionState => ({ deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000 });
+const SYNC = (rev: number) => ({ state: STATE(rev), activeToken: { accessToken: `jwt-${rev}`, expiresAt: 'x' } });
+
+function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
+  return {
+    makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 'tok',
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => 'a1',
+    ...over,
+  };
+}
+
+describe('SessionClient injected socketFactory', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('uses the injected factory and NEVER invokes the lazy loader', async () => {
+    const loaderSpy = jest.spyOn(socketLoader, 'getSocketIO');
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn((_uri: string) => {
+      created = new FakeSocket();
+      created.connected = true;
+      return created;
+    });
+
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    await client.start();
+
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(factory).toHaveBeenCalledWith('http://test.invalid', expect.objectContaining({ transports: ['websocket'] }));
+    expect(loaderSpy).not.toHaveBeenCalled();
+    expect(created).not.toBeNull();
+    client.stop();
+  });
+
+  it('falls back to the lazy loader when no factory is injected', async () => {
+    const fake = new FakeSocket();
+    fake.connected = true;
+    const lazyFactory: SocketIOFactory = jest.fn(() => fake);
+    const loaderSpy = jest.spyOn(socketLoader, 'getSocketIO').mockResolvedValue(lazyFactory);
+
+    const client = new SessionClient(makeHost());
+    await client.start();
+
+    expect(loaderSpy).toHaveBeenCalledTimes(1);
+    expect(lazyFactory).toHaveBeenCalledWith('http://test.invalid', expect.objectContaining({ transports: ['websocket'] }));
+    client.stop();
+  });
+});

package/src/session/__tests__/SessionClient.state.test.ts

@@ -32,12 +32,25 @@ describe('SessionClient state', () => {
     expect(seen.at(-1)?.revision).toBe(1);
   });
 
-  it('ignores a stale or equal revision (last-writer-wins)', () => {
+  it('ignores a stale or equal revision (last-writer-wins) WITHIN the same device', () => {
     const c = new TestClient(makeHost());
-    c.apply(STATE(5));
-    expect(c.apply(STATE(5))).toBe(false);
-    expect(c.apply(STATE(4))).toBe(false);
-    expect(c.getState()?.revision).toBe(5);
+    c.apply({ ...STATE(5), deviceId: 'A' });
+    expect(c.apply({ ...STATE(5), deviceId: 'A' })).toBe(false);
+    expect(c.apply({ ...STATE(4), deviceId: 'A' })).toBe(false);
+    expect(c.apply({ ...STATE(6), deviceId: 'A' })).toBe(true);
+    expect(c.getState()?.revision).toBe(6);
+  });
+
+  it('accepts a LOWER-revision state from a DIFFERENT device (revision baseline resets cross-device)', () => {
+    const c = new TestClient(makeHost());
+    // Device A at a high revision.
+    expect(c.apply({ ...STATE(10), deviceId: 'A' })).toBe(true);
+    expect(c.getState()?.deviceId).toBe('A');
+    // Device B, freshly converged (revision 1), must win over device A's
+    // stale-but-higher revision — the cross-device comparison is not monotone.
+    expect(c.apply({ ...STATE(1), deviceId: 'B' })).toBe(true);
+    expect(c.getState()?.deviceId).toBe('B');
+    expect(c.getState()?.revision).toBe(1);
   });
 
   it('rejects an invalid (unvalidated) state without applying', () => {

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

@@ -0,0 +1,209 @@
+import {
+  createWebAuthStateStore,
+  createNativeAuthStateStore,
+  createMemoryAuthStateStore,
+  AUTH_STATE_STORAGE_KEY,
+  DEVICE_TOKEN_STORAGE_KEY,
+  type PersistedAuthState,
+  type NativeKeyValueStorage,
+} from '../authStateStore';
+
+const SAMPLE: PersistedAuthState = {
+  sessionId: 's-1',
+  refreshToken: 'r-abcdefghijklmnop',
+  userId: 'u-1',
+  deviceToken: 'd-1234567890',
+  accessToken: 'a-jwt',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+};
+
+/** A minimal in-map Storage; setItem can be made to throw (quota simulation). */
+function makeFakeStorage(opts: { throwOnSet?: boolean } = {}): Storage {
+  const map = new Map<string, string>();
+  return {
+    getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+    setItem: (k: string, v: string) => {
+      if (opts.throwOnSet) {
+        throw new DOMException('QuotaExceededError', 'QuotaExceededError');
+      }
+      map.set(k, v);
+    },
+    removeItem: (k: string) => {
+      map.delete(k);
+    },
+    clear: () => map.clear(),
+    key: (i: number) => Array.from(map.keys())[i] ?? null,
+    get length() {
+      return map.size;
+    },
+  } as Storage;
+}
+
+function installLocalStorage(storage: Storage): void {
+  Object.defineProperty(globalThis, 'localStorage', {
+    value: storage,
+    configurable: true,
+    writable: true,
+  });
+}
+
+afterEach(() => {
+  // Remove whatever localStorage the test installed (value or throwing getter).
+  if (Object.getOwnPropertyDescriptor(globalThis, 'localStorage')) {
+    delete (globalThis as { localStorage?: Storage }).localStorage;
+  }
+});
+
+describe('createWebAuthStateStore', () => {
+  it('round-trips a PersistedAuthState under the versioned key', async () => {
+    const storage = makeFakeStorage();
+    installLocalStorage(storage);
+    const store = createWebAuthStateStore();
+
+    await store.save(SAMPLE);
+    expect(storage.getItem(AUTH_STATE_STORAGE_KEY)).toBeTruthy();
+    expect(await store.load()).toEqual(SAMPLE);
+  });
+
+  it('clear() wipes the session but the deviceToken survives', async () => {
+    installLocalStorage(makeFakeStorage());
+    const store = createWebAuthStateStore();
+
+    await store.save(SAMPLE);
+    await store.saveDeviceToken('device-token-xyz');
+    await store.clear();
+
+    expect(await store.load()).toBeNull();
+    expect(await store.loadDeviceToken()).toBe('device-token-xyz');
+  });
+
+  it('persists the deviceToken under a separate long-lived key', async () => {
+    const storage = makeFakeStorage();
+    installLocalStorage(storage);
+    const store = createWebAuthStateStore();
+
+    await store.saveDeviceToken('dt');
+    expect(storage.getItem(DEVICE_TOKEN_STORAGE_KEY)).toBe('dt');
+    await store.clearDeviceToken();
+    expect(await store.loadDeviceToken()).toBeNull();
+  });
+
+  it('returns null for a malformed or incomplete blob', async () => {
+    const storage = makeFakeStorage();
+    installLocalStorage(storage);
+    const store = createWebAuthStateStore();
+
+    storage.setItem(AUTH_STATE_STORAGE_KEY, 'not-json');
+    expect(await store.load()).toBeNull();
+
+    storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify({ sessionId: 's', userId: 'u' }));
+    expect(await store.load()).toBeNull();
+  });
+
+  it('degrades to in-memory when accessing localStorage throws (sandboxed iframe SecurityError)', async () => {
+    Object.defineProperty(globalThis, 'localStorage', {
+      configurable: true,
+      get() {
+        throw new DOMException('The operation is insecure.', 'SecurityError');
+      },
+    });
+
+    // Construction must not throw, and the store must still function (in-memory).
+    const store = createWebAuthStateStore();
+    await expect(store.save(SAMPLE)).resolves.toBeUndefined();
+    expect(await store.load()).toEqual(SAMPLE);
+  });
+
+  it('swallows a write that throws (quota / private mode) without rejecting', async () => {
+    installLocalStorage(makeFakeStorage({ throwOnSet: true }));
+    const store = createWebAuthStateStore();
+
+    await expect(store.save(SAMPLE)).resolves.toBeUndefined();
+    // The write never reached storage...
+    expect(localStorage.getItem(AUTH_STATE_STORAGE_KEY)).toBeNull();
+    // ...but the in-memory mirror keeps the session live for this page's lifetime.
+    expect(await store.load()).toEqual(SAMPLE);
+  });
+
+  it('the mirror keeps the deviceToken live when the write throws', async () => {
+    installLocalStorage(makeFakeStorage({ throwOnSet: true }));
+    const store = createWebAuthStateStore();
+
+    await store.saveDeviceToken('dt-mirrored');
+    expect(await store.loadDeviceToken()).toBe('dt-mirrored');
+  });
+
+  it('a cleared session reads null even if storage later holds a stale blob (mirror wins)', async () => {
+    const storage = makeFakeStorage();
+    installLocalStorage(storage);
+    const store = createWebAuthStateStore();
+
+    await store.save(SAMPLE);
+    await store.clear();
+    // Something (another tab / a failed remove) leaves a stale blob behind.
+    storage.setItem(AUTH_STATE_STORAGE_KEY, JSON.stringify(SAMPLE));
+    // The authoritative in-memory mirror still reports the cleared state.
+    expect(await store.load()).toBeNull();
+  });
+});
+
+describe('createNativeAuthStateStore', () => {
+  function makeNativeStorage(): NativeKeyValueStorage & { map: Map<string, string> } {
+    const map = new Map<string, string>();
+    return {
+      map,
+      getItem: async (k) => (map.has(k) ? (map.get(k) as string) : null),
+      setItem: async (k, v) => {
+        map.set(k, v);
+      },
+      removeItem: async (k) => {
+        map.delete(k);
+      },
+    };
+  }
+
+  it('round-trips through the injected async storage', async () => {
+    const storage = makeNativeStorage();
+    const store = createNativeAuthStateStore(storage);
+
+    await store.save(SAMPLE);
+    expect(storage.map.get(AUTH_STATE_STORAGE_KEY)).toBeTruthy();
+    expect(await store.load()).toEqual(SAMPLE);
+  });
+
+  it('deviceToken survives a session clear', async () => {
+    const store = createNativeAuthStateStore(makeNativeStorage());
+    await store.save(SAMPLE);
+    await store.saveDeviceToken('dt-native');
+    await store.clear();
+    expect(await store.load()).toBeNull();
+    expect(await store.loadDeviceToken()).toBe('dt-native');
+  });
+
+  it('keeps the session live via the mirror when the injected storage throws (locked keychain)', async () => {
+    const store = createNativeAuthStateStore({
+      getItem: async () => {
+        throw new Error('secure store locked');
+      },
+      setItem: async () => {
+        throw new Error('secure store locked');
+      },
+      removeItem: async () => {
+        throw new Error('secure store locked');
+      },
+    });
+    await expect(store.save(SAMPLE)).resolves.toBeUndefined();
+    // The write threw, but the in-memory mirror preserves the session.
+    expect(await store.load()).toEqual(SAMPLE);
+  });
+});
+
+describe('createMemoryAuthStateStore', () => {
+  it('round-trips and clears in process memory', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(SAMPLE);
+    expect(await store.load()).toEqual(SAMPLE);
+    await store.clear();
+    expect(await store.load()).toBeNull();
+  });
+});

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

@@ -0,0 +1,256 @@
+import type { OxyServices } from '../../OxyServices';
+import type { TokenRefreshResponse } from '@oxyhq/contracts';
+import type { SessionLoginResponse } from '../../models/session';
+import { refreshPersistedSession, startTokenRefreshScheduler } from '../refresh';
+import { createMemoryAuthStateStore, type PersistedAuthState } from '../authStateStore';
+
+const STORED: PersistedAuthState = {
+  sessionId: 'sess-old',
+  refreshToken: 'refresh-old-abcdefghij',
+  userId: 'user-1',
+  deviceToken: 'device-abcdefghij',
+};
+
+const ROTATED: TokenRefreshResponse = {
+  accessToken: 'access-new',
+  refreshToken: 'refresh-new-abcdefghij',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  sessionId: 'sess-new',
+};
+
+interface RefreshMockOverrides {
+  refreshWithToken?: OxyServices['refreshWithToken'];
+  signInWithSharedIdentity?: OxyServices['signInWithSharedIdentity'];
+}
+
+function makeOxy(overrides: RefreshMockOverrides = {}): { oxy: OxyServices; setTokens: jest.Mock } {
+  const setTokens = jest.fn();
+  const oxy = {
+    setTokens,
+    refreshWithToken: overrides.refreshWithToken ?? (async () => ROTATED),
+    signInWithSharedIdentity: overrides.signInWithSharedIdentity ?? (async () => null),
+  } as unknown as OxyServices;
+  return { oxy, setTokens };
+}
+
+describe('refreshPersistedSession — arm 1 (refresh-token rotation)', () => {
+  it('rotates, plants, persists the new family head, and returns the new token', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy, setTokens } = makeOxy();
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+
+    expect(token).toBe('access-new');
+    expect(setTokens).toHaveBeenCalledWith('access-new');
+    expect(await store.load()).toEqual({
+      sessionId: 'sess-new',
+      refreshToken: 'refresh-new-abcdefghij',
+      userId: 'user-1',
+      deviceToken: 'device-abcdefghij',
+      accessToken: 'access-new',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+    });
+  });
+
+  it('clears the store on a family-revoked (401) error', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy } = makeOxy({
+      refreshWithToken: async () => {
+        throw Object.assign(new Error('revoked'), { status: 401 });
+      },
+    });
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false });
+
+    expect(token).toBeNull();
+    expect(await store.load()).toBeNull();
+  });
+
+  it('clears the store on an invalid_grant code', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy } = makeOxy({
+      refreshWithToken: async () => {
+        throw Object.assign(new Error('bad'), { code: 'invalid_grant' });
+      },
+    });
+
+    expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false })).toBeNull();
+    expect(await store.load()).toBeNull();
+  });
+
+  it('KEEPS the store on a transient (500 / network) error', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const { oxy } = makeOxy({
+      refreshWithToken: async () => {
+        throw Object.assign(new Error('server'), { status: 500 });
+      },
+    });
+
+    expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false })).toBeNull();
+    expect(await store.load()).toEqual(STORED);
+  });
+});
+
+describe('refreshPersistedSession — arm 2 (native shared-key fallback)', () => {
+  const SHARED_SESSION: SessionLoginResponse = {
+    sessionId: 'sess-shared',
+    deviceId: 'dev-1',
+    expiresAt: '2030-01-01T00:00:00.000Z',
+    user: { id: 'user-1', username: 'u', name: {}, avatar: undefined },
+    accessToken: 'access-shared',
+  };
+
+  it('re-mints via shared identity when there is no refresh token', async () => {
+    const store = createMemoryAuthStateStore(); // no stored refresh token
+    const signInWithSharedIdentity = jest.fn(async () => SHARED_SESSION);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+
+    expect(token).toBe('access-shared');
+    expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+  });
+
+  it('falls back to shared-key after a revoked refresh token', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save(STORED);
+    const signInWithSharedIdentity = jest.fn(async () => SHARED_SESSION);
+    const { oxy } = makeOxy({
+      refreshWithToken: async () => {
+        throw Object.assign(new Error('revoked'), { status: 403 });
+      },
+      signInWithSharedIdentity,
+    });
+
+    const token = await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: true });
+
+    expect(token).toBe('access-shared');
+    expect(await store.load()).toBeNull(); // revoked family was cleared
+    expect(signInWithSharedIdentity).toHaveBeenCalledTimes(1);
+  });
+
+  it('does NOT try shared-key when the fallback is disabled (web)', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => SHARED_SESSION);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    expect(await refreshPersistedSession({ oxy, store, allowSharedKeyFallback: false })).toBeNull();
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+  });
+});
+
+describe('startTokenRefreshScheduler', () => {
+  function makeSchedulerOxy(expiresInSeconds: number | null): {
+    oxy: OxyServices;
+    refreshAccessToken: jest.Mock;
+  } {
+    let cleared = false;
+    const refreshAccessToken = jest.fn(async () => {
+      cleared = true; // stop the reschedule loop after the first fire
+      return null;
+    });
+    const nowSec = Math.floor(Date.now() / 1000);
+    const oxy = {
+      getAccessToken: () => (cleared ? null : 'tok'),
+      getAccessTokenExpiry: () => (expiresInSeconds === null ? null : nowSec + expiresInSeconds),
+      onTokensChanged: () => () => undefined,
+      httpService: { refreshAccessToken },
+    } as unknown as OxyServices;
+    return { oxy, refreshAccessToken };
+  }
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('fires a refresh ~60s before expiry', async () => {
+    jest.useFakeTimers();
+    const { oxy, refreshAccessToken } = makeSchedulerOxy(120);
+    const handle = startTokenRefreshScheduler(oxy);
+
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+    await jest.advanceTimersByTimeAsync(60_000);
+    expect(refreshAccessToken).toHaveBeenCalledWith('preflight');
+
+    handle.dispose();
+  });
+
+  it('no-ops cleanly for an opaque token with no exp', () => {
+    jest.useFakeTimers();
+    const { oxy, refreshAccessToken } = makeSchedulerOxy(null);
+    const handle = startTokenRefreshScheduler(oxy);
+    jest.advanceTimersByTime(10 * 60_000);
+    expect(refreshAccessToken).not.toHaveBeenCalled();
+    handle.dispose();
+  });
+
+  it('backs off on repeated failure — bounded attempts, never a zero-delay busy loop', async () => {
+    jest.useFakeTimers();
+    // Already-expired token + a refresh that ALWAYS fails. The old code floored
+    // the delay to 0 and re-armed in the finally block → a tight loop that would
+    // exhaust jest's 100k-timer guard. The backoff schedule fires only a handful
+    // of times per simulated minute.
+    const refreshAccessToken = jest.fn(async () => null);
+    const nowSec = Math.floor(Date.now() / 1000);
+    const oxy = {
+      getAccessToken: () => 'tok',
+      getAccessTokenExpiry: () => nowSec - 10,
+      onTokensChanged: () => () => undefined,
+      httpService: { refreshAccessToken },
+    } as unknown as OxyServices;
+
+    const handle = startTokenRefreshScheduler(oxy);
+    await jest.advanceTimersByTimeAsync(60_000);
+
+    expect(refreshAccessToken.mock.calls.length).toBeGreaterThan(0);
+    expect(refreshAccessToken.mock.calls.length).toBeLessThan(10);
+    handle.dispose();
+  });
+
+  it('resets the backoff after a successful refresh', async () => {
+    jest.useFakeTimers();
+    // Expiry is always ~1h from NOW, so a successful refresh genuinely pushes
+    // the token out (as a real rotation would). Fail once, then succeed.
+    const refreshAccessToken = jest
+      .fn<Promise<string | null>, [unknown]>()
+      .mockResolvedValueOnce(null)
+      .mockResolvedValue('fresh');
+    const oxy = {
+      getAccessToken: () => 'tok',
+      getAccessTokenExpiry: () => Math.floor(Date.now() / 1000) + 3600,
+      onTokensChanged: () => () => undefined,
+      httpService: { refreshAccessToken },
+    } as unknown as OxyServices;
+
+    const handle = startTokenRefreshScheduler(oxy);
+    // First fire ~ (3600-60)s out (fails → 5s backoff), then the backoff fire
+    // succeeds and re-arms ~1h out from the (now-fresh) expiry.
+    await jest.advanceTimersByTimeAsync((3600 - 60) * 1000);
+    await jest.advanceTimersByTimeAsync(5_000);
+    const callsAfterSuccess = refreshAccessToken.mock.calls.length;
+    expect(callsAfterSuccess).toBe(2); // one failure + one success
+    // A further minute must NOT produce a burst — the healthy re-arm is ~1h out.
+    await jest.advanceTimersByTimeAsync(60_000);
+    expect(refreshAccessToken.mock.calls.length).toBe(callsAfterSuccess);
+    handle.dispose();
+  });
+
+  it('calls unref() on its timer so it never holds the event loop', () => {
+    const unref = jest.fn();
+    const setTimeoutSpy = jest
+      .spyOn(global, 'setTimeout')
+      .mockReturnValue({ unref } as unknown as ReturnType<typeof setTimeout>);
+    const { oxy } = makeSchedulerOxy(120);
+
+    const handle = startTokenRefreshScheduler(oxy);
+    expect(setTimeoutSpy).toHaveBeenCalled();
+    expect(unref).toHaveBeenCalled();
+
+    handle.dispose();
+    setTimeoutSpy.mockRestore();
+  });
+});