@oxy.so/services 4.0.2 → 4.0.3

package/src/ui/session/__tests__/tokenLossRecovery.test.ts

@@ -0,0 +1,195 @@
+/**
+ * A lost access token is a question, not a sign-out (OxyHQ/Mention#1140).
+ *
+ * The provider used to sign the user out on ANY cleared bearer. HttpService
+ * clears it whenever a 401's refresh comes back empty — including when the mint
+ * is merely cooling down after a 429 or the network blipped — and with no token
+ * the refresh scheduler stops, so the session never came back until a relaunch
+ * re-minted from the device credential that had been intact the whole time.
+ */
+import {
+  createTokenLossRecovery,
+  MAX_KEYED_RECOVERY_ATTEMPTS,
+  TOKEN_RECOVERY_BACKOFF_MS,
+  type TokenLossRecoveryDeps,
+} from '../tokenLossRecovery';
+
+interface Harness {
+  deps: TokenLossRecoveryDeps;
+  state: { signedIn: boolean; token: string | null; credential: boolean; keyed: boolean };
+  remint: jest.Mock<Promise<string | null>, []>;
+  signOutLocally: jest.Mock<Promise<void>, []>;
+  sleeps: number[];
+}
+
+function harness(remintAnswers: Array<string | null | 'drop-credential'>): Harness {
+  const state = { signedIn: true, token: null as string | null, credential: true, keyed: false };
+  const sleeps: number[] = [];
+  const remint = jest.fn(async (): Promise<string | null> => {
+    const answer = remintAnswers.length > 0 ? remintAnswers.shift() : null;
+    if (answer === 'drop-credential') {
+      // What the refresh handler does on `invalid_device_secret` /
+      // `no_active_session`: the credential goes, and the mint returns nothing.
+      state.credential = false;
+      return null;
+    }
+    if (answer) {
+      state.token = answer;
+    }
+    return answer ?? null;
+  });
+  const signOutLocally = jest.fn(async () => {
+    state.signedIn = false;
+  });
+  const deps: TokenLossRecoveryDeps = {
+    remint,
+    hasDeviceCredential: async () => state.credential,
+    hasKeyedRecovery: async () => state.keyed,
+    isSignedIn: () => state.signedIn,
+    hasToken: () => state.token !== null,
+    signOutLocally,
+    sleep: async (ms) => {
+      sleeps.push(ms);
+    },
+  };
+  return { deps, state, remint, signOutLocally, sleeps };
+}
+
+async function runToCompletion(recovery: ReturnType<typeof createTokenLossRecovery>): Promise<void> {
+  for (let i = 0; i < 200 && recovery.isRecovering(); i += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  expect(recovery.isRecovering()).toBe(false);
+}
+
+describe('token loss recovery', () => {
+  it('keeps a user with an intact device credential signed in through transient failures, then restores the token', async () => {
+    // The incident: the mint is rate limited / cooling down for a while, then
+    // succeeds — exactly what a relaunch a few minutes later did.
+    const h = harness([null, null, null, 'fresh']);
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.signOutLocally).not.toHaveBeenCalled();
+    expect(h.state.token).toBe('fresh');
+    expect(h.remint).toHaveBeenCalledTimes(4);
+    expect(h.sleeps).toEqual(TOKEN_RECOVERY_BACKOFF_MS.slice(0, 3));
+  });
+
+  it('signs out once a re-mint gets a definitive verdict and no key can re-establish the session', async () => {
+    const h = harness([null, 'drop-credential']);
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.signOutLocally).toHaveBeenCalledTimes(1);
+    expect(h.remint).toHaveBeenCalledTimes(2);
+  });
+
+  it('signs out at once when the credential was already gone and there is no key-based lane (the old behaviour for a real revocation)', async () => {
+    const h = harness([]);
+    h.state.credential = false;
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.remint).not.toHaveBeenCalled();
+    expect(h.signOutLocally).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-establishes through the shared identity when the credential is gone, like the cold boot does', async () => {
+    const h = harness([null, 'from-shared-key']);
+    h.state.credential = false;
+    h.state.keyed = true;
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.signOutLocally).not.toHaveBeenCalled();
+    expect(h.state.token).toBe('from-shared-key');
+  });
+
+  it('gives the key-based lane a bounded number of tries, then signs out', async () => {
+    const h = harness([]);
+    h.state.credential = false;
+    h.state.keyed = true;
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.remint).toHaveBeenCalledTimes(MAX_KEYED_RECOVERY_ATTEMPTS);
+    expect(h.signOutLocally).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops without touching the session when the user signs out meanwhile', async () => {
+    const h = harness([]);
+    h.remint.mockImplementation(async () => {
+      h.state.signedIn = false;
+      return null;
+    });
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.remint).toHaveBeenCalledTimes(1);
+    expect(h.signOutLocally).not.toHaveBeenCalled();
+  });
+
+  it('stops when another lane planted a token first', async () => {
+    const h = harness([]);
+    h.remint.mockImplementation(async () => {
+      h.state.token = 'planted-by-a-sign-in';
+      return null;
+    });
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.remint).toHaveBeenCalledTimes(1);
+    expect(h.signOutLocally).not.toHaveBeenCalled();
+  });
+
+  it('runs one recovery at a time', async () => {
+    const h = harness([null, 'fresh']);
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.remint).toHaveBeenCalledTimes(2);
+  });
+
+  it('signs out rather than strand a signed-in UI with no bearer when recovery itself throws', async () => {
+    const h = harness([]);
+    h.deps.hasDeviceCredential = async () => {
+      throw new Error('store exploded');
+    };
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.signOutLocally).toHaveBeenCalledTimes(1);
+  });
+
+  it('does nothing after dispose', async () => {
+    const h = harness([]);
+    const recovery = createTokenLossRecovery(h.deps);
+
+    recovery.dispose();
+    recovery.start();
+    await runToCompletion(recovery);
+
+    expect(h.remint).not.toHaveBeenCalled();
+    expect(h.signOutLocally).not.toHaveBeenCalled();
+  });
+});

package/src/ui/session/tokenLossRecovery.ts

@@ -0,0 +1,146 @@
+/**
+ * What a signed-in app does when its access token disappears at runtime.
+ *
+ * `HttpService` clears the bearer when a request draws a 401 and the refresh it
+ * then tries returns nothing. That refresh can return nothing for reasons that
+ * say NOTHING about the session: the mint is cooling down after a failure or a
+ * 429, the network dropped, the server was restarting. The provider used to read
+ * every such clear as a sign-out and tore the session down on the spot — and
+ * because the proactive refresh scheduler only runs while a token exists, nothing
+ * was left to bring the session back. Only a relaunch did, because the cold boot
+ * mints from the durable device credential that had been there all along
+ * (OxyHQ/Mention#1140).
+ *
+ * So a lost token is a question, and this answers it the way a relaunch would:
+ *
+ *  - The durable store still holds the device credential → the session is NOT
+ *    known to be over. Keep the user signed in (private queries pause, because
+ *    there is no bearer) and re-mint with backoff until one succeeds. A
+ *    definitive server verdict (`invalid_device_secret`, `no_active_session`)
+ *    makes the refresh handler drop or clear that credential, which is what ends
+ *    this loop in a sign-out — so a real revocation still signs out.
+ *  - No credential, but a key-based lane can still re-establish (the native
+ *    shared identity, or an identity-bound client's own key) → try that a few
+ *    times, as the cold boot's shared-key step would, then sign out.
+ *  - Neither → the session is over. Sign out now, as before.
+ *
+ * Framework-free and clock-injectable so the policy is unit tested without a
+ * provider.
+ */
+import { logger } from '@oxy.so/core';
+
+export interface TokenLossRecoveryDeps {
+  /** Re-mint once through the installed refresh handler; the token, or null. */
+  remint: () => Promise<string | null>;
+  /** Whether the durable auth store still holds `deviceId` + `deviceSecret`. */
+  hasDeviceCredential: () => Promise<boolean>;
+  /**
+   * Whether a key-based lane could still re-establish the session without a
+   * device secret. Consulted only once the credential is gone.
+   */
+  hasKeyedRecovery: () => Promise<boolean>;
+  /** Whether the UI still shows a signed-in user. */
+  isSignedIn: () => boolean;
+  /** Whether a bearer is planted right now. */
+  hasToken: () => boolean;
+  /** Tear down the local session (the provider's `clearSessionState`). */
+  signOutLocally: () => Promise<void>;
+  /** Timer seam for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface TokenLossRecovery {
+  /** Start recovering, unless a recovery is already running. */
+  start(): void;
+  /** Abandon any running recovery (provider unmount). */
+  dispose(): void;
+  /** Whether a recovery is running. */
+  isRecovering(): boolean;
+}
+
+/**
+ * Delays between re-mint attempts while the device credential is intact. Starts
+ * near the post-failure refresh cooldowns and settles at one attempt a minute,
+ * which also respects the mint's own 60s rate-limit cooldown.
+ */
+export const TOKEN_RECOVERY_BACKOFF_MS: readonly number[] = [2_000, 5_000, 10_000, 20_000, 30_000, 60_000];
+
+/** Attempts through a key-based lane once the device credential is gone. */
+export const MAX_KEYED_RECOVERY_ATTEMPTS = 3;
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+const LOG_CONTEXT = { component: 'OxyContext', method: 'tokenLossRecovery' } as const;
+
+export function createTokenLossRecovery(deps: TokenLossRecoveryDeps): TokenLossRecovery {
+  const sleep = deps.sleep ?? defaultSleep;
+  let running = false;
+  let disposed = false;
+
+  const settled = (): boolean => disposed || deps.hasToken() || !deps.isSignedIn();
+
+  const run = async (): Promise<void> => {
+    let attempt = 0;
+    let keyedAttempts = 0;
+    logger.warn('Access token lost while signed in — recovering the session instead of signing out', LOG_CONTEXT);
+    while (!settled()) {
+      if (!(await deps.hasDeviceCredential())) {
+        const keyed = keyedAttempts < MAX_KEYED_RECOVERY_ATTEMPTS && (await deps.hasKeyedRecovery());
+        if (!keyed) {
+          if (settled()) {
+            return;
+          }
+          logger.warn('Session recovery ended: no device credential and no key-based lane left — signing out', {
+            ...LOG_CONTEXT,
+            attempts: attempt,
+            keyedAttempts,
+          });
+          await deps.signOutLocally();
+          return;
+        }
+        keyedAttempts += 1;
+      }
+      if (settled()) {
+        return;
+      }
+      const token = await deps.remint().catch(() => null);
+      attempt += 1;
+      if (token || settled()) {
+        if (token) {
+          logger.warn('Session recovered after a lost access token', { ...LOG_CONTEXT, attempts: attempt });
+        }
+        return;
+      }
+      await sleep(TOKEN_RECOVERY_BACKOFF_MS[Math.min(attempt - 1, TOKEN_RECOVERY_BACKOFF_MS.length - 1)]);
+    }
+  };
+
+  return {
+    start(): void {
+      if (running || disposed) {
+        return;
+      }
+      running = true;
+      void run()
+        .catch(async (error: unknown) => {
+          // Never leave a signed-in UI with no bearer and nothing recovering it.
+          logger.warn('Session recovery failed unexpectedly — signing out', LOG_CONTEXT, error);
+          if (!settled()) {
+            await deps.signOutLocally().catch(() => undefined);
+          }
+        })
+        .finally(() => {
+          running = false;
+        });
+    },
+    dispose(): void {
+      disposed = true;
+    },
+    isRecovering(): boolean {
+      return running;
+    },
+  };
+}