@gusnips/react 0.9.29 → 0.9.30

package/README.md

@@ -743,6 +743,73 @@ and send a stranger the link, and that sentence is the only guard against it. On
 page stays decided: it never asks the server again, because the server no longer knows the code,
 and asking on the next focus would tell someone who just said yes that their code is wrong.
 
+## A new API key, shown once
+
+```ts
+import { createKeyLifecycle } from "@gusnips/react/keys";
+
+export const apiKeys = createKeyLifecycle<ApiKey>();
+```
+
+Make it once, beside your query client, outside every route. It keeps each new key's secret in
+memory until the person presses Done. A second key never replaces the first, and a trip to your
+docs and back loses neither.
+
+Tell it who is signed in, and where, from the code that already hears about sign-in and workspace
+changes:
+
+```ts
+apiKeys.setScope(user ? `${user.id}:${workspaceId}` : null);
+```
+
+A new scope forgets every unread secret. A request started before the change rejects with
+`KeyScopeChangedError` instead of showing its secret, even when the same account signs straight
+back in. Build the scope from ids, never from an access token: a token refresh is not a new person.
+
+Send your create request through it:
+
+```ts
+const create = useMutation({
+  mutationFn: (name: string) =>
+    apiKeys.create(async () => {
+      const { key, ...record } = await api.post<NewApiKey>("/keys", { name });
+      return { record, key };
+    }),
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ["keys"] }),
+});
+```
+
+`create` keeps the secret and resolves only the record. In three products we read, `mutation.data`
+held the whole answer, so the secret stayed in react-query's cache for as long as the cache kept
+the mutation. A record that still contains the secret is refused, so that mistake shows on the
+first try. The reveal lands even when the page that asked has unmounted.
+
+Show what is unread, and let the person say they saved it:
+
+```tsx
+const reveals = useKeyReveals(apiKeys);
+
+return reveals.map(({ record, key }) => (
+  <KeyReveal key={record.id} secret={key} onDone={() => apiKeys.dismiss(record.id)} />
+));
+```
+
+Copy with `useCopy`, and keep Done separate: a copy can fail, and the secret must stay on screen
+when it does. Revoke goes through the same object:
+
+```ts
+mutationFn: (id: string) => apiKeys.revoke(id, () => api.delete(`/keys/${id}`)),
+```
+
+Only a successful revoke forgets that key's secret. A failed one leaves it on screen, because the
+key still works.
+
+Nothing is written to storage or the URL, so a reload loses an unread secret. While one is unread
+the tab asks before it closes, and the listener goes away with the last one, because a page with
+a `beforeunload` listener is kept out of some browsers' back-forward cache. Draw the list through
+`queryView`, so a failed refresh keeps the rows instead of saying there are no keys. Forms,
+permissions, plan limits and every word on the page stay yours.
+
 ## Also here
 
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,
@@ -825,6 +892,7 @@ lives behind a subpath, so you install a dependency only if you import the thing
 | `@gusnips/react/theme`    | `createTheme`, `startTheme`              | react                 |
 | `@gusnips/react/commands` | slash matching and `useSlashCommands`    | react                 |
 | `@gusnips/react/oauth`    | `useConsentRequest`, `useDeviceApproval` | @tanstack/react-query |
+| `@gusnips/react/keys`     | `createKeyLifecycle`, `useKeyReveals`    | react                 |
 
 The rule behind that table: **a peer marked optional must not be reachable from the main entry
 point.** An optional peer the barrel imports anyway is not optional: it is a required one whose

package/dist/keys.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A new API key, the one time the server sends its secret. Three products wrote this flow, and
+ * each knew one part the others missed:
+ *
+ * - One kept unread secrets in a list outside the page, so a second key did not overwrite the
+ *   first and a trip to the docs did not lose either. The tab asked before closing only while one
+ *   was unread, and signing out forgot them all.
+ * - One kept the secret out of the list cache, folding only the record into it.
+ * - None kept it out of react-query's MUTATION cache. Each `mutationFn` resolved the whole answer,
+ *   secret included, so `mutation.data` held it, one of them under a comment promising it did not.
+ *
+ * So `create` takes the secret here and resolves only the record, and the request is the caller's.
+ * Forms, permissions, list queries, invalidation and copy feedback stay in the product.
+ */
+/** What your create request resolves: the record your list shows, and the secret beside it. */
+export interface RevealedKey<Record> {
+    readonly record: Record;
+    readonly key: string;
+}
+/** The account or workspace changed while a create or revoke was in flight. */
+export declare class KeyScopeChangedError extends Error {
+    readonly operation: "create" | "revoke";
+    constructor(operation: "create" | "revoke");
+}
+export interface KeyLifecycle<Record> {
+    /**
+     * Who and where keys are made for: the signed-in account and the workspace, joined into one
+     * string, or `null` once signed out. Call it from your auth and workspace subscription, never
+     * from the keys page, which may not be mounted. A new scope forgets every unread secret and
+     * rejects requests started under the old one, including when the same account signs back in.
+     */
+    setScope(scope: string | null): void;
+    /**
+     * Run your create request, keep its secret here, and resolve only the record. Use it as a
+     * `mutationFn`: neither the result nor the variables carry the secret, and the reveal still
+     * lands when the page that asked has unmounted.
+     */
+    create(request: () => Promise<RevealedKey<Record>>): Promise<Record>;
+    /** Run your revoke request. Only a success, in the same scope, forgets that key's secret. */
+    revoke(id: string, request: () => Promise<unknown>): Promise<void>;
+    /** The person saved it. Wire this to "Done", never to a copy: a copy can fail. */
+    dismiss(id: string): void;
+    /** Unread secrets, newest first. */
+    getSnapshot(): readonly RevealedKey<Record>[];
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * One per app, created at module scope, outside every route. Memory only: never storage, the URL
+ * or a query cache, so a reload loses an unread secret, and the tab asks before closing while one
+ * is unread. The listener comes and goes with the secrets because a page with a `beforeunload`
+ * listener is kept out of some browsers' back-forward cache.
+ */
+export declare function createKeyLifecycle<Record extends {
+    readonly id: string;
+}>(): KeyLifecycle<Record>;
+/** Unread secrets, newest first. Unmounting the component forgets nothing. */
+export declare function useKeyReveals<Record>(lifecycle: KeyLifecycle<Record>): readonly RevealedKey<Record>[];
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,+FAA+F;AAC/F,MAAM,WAAW,WAAW,CAAC,MAAM;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,+EAA+E;AAC/E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;gBAE5B,SAAS,EAAE,QAAQ,GAAG,QAAQ;CAS3C;AAED,MAAM,WAAW,YAAY,CAAC,MAAM;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE,6FAA6F;IAC7F,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,kFAAkF;IAClF,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oCAAoC;IACpC,WAAW,IAAI,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;IAC9C,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,KAAK,YAAY,CAAC,MAAM,CAAC,CAkEjG;AAKD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,MAAM,EAClC,SAAS,EAAE,YAAY,CAAC,MAAM,CAAC,GAC9B,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,CAEhC"}

package/dist/keys.js

@@ -0,0 +1,94 @@
+import { useSyncExternalStore } from "react";
+/** The account or workspace changed while a create or revoke was in flight. */
+export class KeyScopeChangedError extends Error {
+    operation;
+    constructor(operation) {
+        super(operation === "create"
+            ? "The account or workspace changed before the new key could be shown. If nobody saved it, revoke it from that workspace's keys."
+            : "The account or workspace changed while the key was being revoked. Check that workspace's keys to see whether it worked.");
+        this.name = "KeyScopeChangedError";
+        this.operation = operation;
+    }
+}
+/**
+ * One per app, created at module scope, outside every route. Memory only: never storage, the URL
+ * or a query cache, so a reload loses an unread secret, and the tab asks before closing while one
+ * is unread. The listener comes and goes with the secrets because a page with a `beforeunload`
+ * listener is kept out of some browsers' back-forward cache.
+ */
+export function createKeyLifecycle() {
+    let revealed = [];
+    let scope = null;
+    let generation = 0;
+    const listeners = new Set();
+    // Per instance, so two lifecycles never remove each other's prompt.
+    function askBeforeLeaving(event) {
+        event.preventDefault();
+        // Older Chrome and Safari prompt only when this is set too. The browser picks the words.
+        event.returnValue = "";
+    }
+    function publish(next) {
+        const wasUnread = revealed.length > 0;
+        revealed = next;
+        if (wasUnread !== next.length > 0 && typeof window !== "undefined") {
+            if (next.length > 0)
+                window.addEventListener("beforeunload", askBeforeLeaving);
+            else
+                window.removeEventListener("beforeunload", askBeforeLeaving);
+        }
+        for (const listener of listeners)
+            listener();
+    }
+    /** Runs `request` under the current scope and refuses an answer that outlived it. */
+    async function scoped(operation, request) {
+        if (scope === null)
+            throw new Error("Call setScope with the signed-in account and workspace first.");
+        const started = generation;
+        const answer = await request();
+        if (started !== generation)
+            throw new KeyScopeChangedError(operation);
+        return answer;
+    }
+    function dismiss(id) {
+        const next = revealed.filter((one) => one.record.id !== id);
+        if (next.length !== revealed.length)
+            publish(next);
+    }
+    return {
+        setScope(next) {
+            if (scope === next)
+                return;
+            scope = next;
+            generation++;
+            if (revealed.length > 0)
+                publish([]);
+        },
+        async create(request) {
+            const { record, key } = await scoped("create", request);
+            // The record goes on to react-query and often into the list cache. A request that passed
+            // the whole answer as the record would put the secret there, which is the bug this exists
+            // to end, so say so on the first try instead.
+            if (JSON.stringify(record).includes(key))
+                throw new Error("The record still holds the secret. Resolve it without the key field.");
+            publish([{ record, key }, ...revealed]);
+            return record;
+        },
+        async revoke(id, request) {
+            await scoped("revoke", request);
+            dismiss(id);
+        },
+        dismiss,
+        getSnapshot: () => revealed,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+// The server has no unread secrets, and a prerender must never print one.
+const none = [];
+/** Unread secrets, newest first. Unmounting the component forgets nothing. */
+export function useKeyReveals(lifecycle) {
+    return useSyncExternalStore(lifecycle.subscribe, lifecycle.getSnapshot, () => none);
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.29",
+  "version": "0.9.30",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,10 @@
     "./oauth": {
       "types": "./dist/oauth.d.ts",
       "default": "./dist/oauth.js"
+    },
+    "./keys": {
+      "types": "./dist/keys.d.ts",
+      "default": "./dist/keys.js"
     }
   },
   "types": "./dist/index.d.ts",

package/src/keys.test.ts

@@ -0,0 +1,253 @@
+// @vitest-environment happy-dom
+import { QueryClient, QueryClientProvider, useMutation, useQuery } from "@tanstack/react-query";
+import { act, createElement, useLayoutEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createKeyLifecycle,
+  KeyScopeChangedError,
+  useKeyReveals,
+  type KeyLifecycle,
+  type RevealedKey,
+} from "./keys.ts";
+
+interface KeyRecord {
+  id: string;
+  name: string;
+  prefix: string;
+}
+
+vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+
+const cleanups: (() => void)[] = [];
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup();
+  document.body.replaceChildren();
+});
+
+function minted(id: string): RevealedKey<KeyRecord> {
+  const key = `sk_live_${id}_${"x".repeat(24)}`;
+  return { record: { id, name: `key ${id}`, prefix: key.slice(0, 10) }, key };
+}
+
+/** A request the test answers by hand, to hold it in flight across a navigation. */
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((yes) => {
+    resolve = yes;
+  });
+  return { promise, resolve };
+}
+
+function lifecycleIn(scope: string | null = "account-1:workspace-1") {
+  const keys = createKeyLifecycle<KeyRecord>();
+  keys.setScope(scope);
+  // Each test leaves the window as it found it: no unread secrets means no unload listener.
+  cleanups.push(() => keys.setScope(null));
+  return keys;
+}
+
+/** The prompt shows only when a listener cancels the event. */
+function closingPrompts(): boolean {
+  const event = new Event("beforeunload", { cancelable: true });
+  window.dispatchEvent(event);
+  return event.defaultPrevented;
+}
+
+describe("createKeyLifecycle", () => {
+  it("keeps every unread secret, newest first, and resolves only the record", async () => {
+    const keys = lifecycleIn();
+    const first = await keys.create(async () => minted("a"));
+    await keys.create(async () => minted("b"));
+
+    expect(first).toEqual(minted("a").record);
+    expect(keys.getSnapshot().map((one) => one.key)).toEqual([minted("b").key, minted("a").key]);
+    keys.dismiss("b");
+    expect(keys.getSnapshot()).toEqual([minted("a")]);
+  });
+
+  it("refuses a record that still holds the secret", async () => {
+    const keys = lifecycleIn();
+    // The whole answer passed as the record: the shape every donor's mutation cache ended up with.
+    const { record, key } = minted("a");
+    const answer = { ...record, key };
+    await expect(keys.create(async () => ({ record: answer, key }))).rejects.toThrow(
+      "still holds the secret",
+    );
+    expect(keys.getSnapshot()).toEqual([]);
+  });
+
+  it("sends nothing before a scope is set", async () => {
+    const keys = lifecycleIn(null);
+    const request = vi.fn(async () => minted("a"));
+    await expect(keys.create(request)).rejects.toThrow("setScope");
+    await expect(keys.revoke("a", request)).rejects.toThrow("setScope");
+    expect(request).not.toHaveBeenCalled();
+  });
+
+  it("a new scope forgets every secret and refuses answers from the old one", async () => {
+    const keys = lifecycleIn("account-1:workspace-1");
+    await keys.create(async () => minted("a"));
+    keys.setScope("account-1:workspace-1");
+    expect(keys.getSnapshot()).toHaveLength(1);
+
+    const late = deferred<RevealedKey<KeyRecord>>();
+    const creating = keys.create(() => late.promise);
+    // Signed out and straight back in as the same account: still not the scope that asked.
+    keys.setScope(null);
+    keys.setScope("account-1:workspace-1");
+    late.resolve(minted("b"));
+
+    const refused = await creating.catch((error: unknown) => error);
+    expect(refused).toBeInstanceOf(KeyScopeChangedError);
+    expect(refused).toMatchObject({ operation: "create" });
+    expect(keys.getSnapshot()).toEqual([]);
+  });
+
+  it("a failed revoke keeps the secret, and a success forgets only that key", async () => {
+    const keys = lifecycleIn();
+    await keys.create(async () => minted("a"));
+    await keys.create(async () => minted("b"));
+
+    await expect(
+      keys.revoke("a", async () => Promise.reject(new Error("offline"))),
+    ).rejects.toThrow("offline");
+    expect(keys.getSnapshot()).toHaveLength(2);
+
+    await keys.revoke("a", async () => undefined);
+    expect(keys.getSnapshot()).toEqual([minted("b")]);
+  });
+
+  it("a revoke answered after the scope changed forgets nothing in the new one", async () => {
+    const keys = lifecycleIn("account-1:workspace-1");
+    const late = deferred<void>();
+    const revoking = keys.revoke("a", () => late.promise);
+    keys.setScope("account-1:workspace-2");
+    await keys.create(async () => minted("a"));
+    late.resolve();
+
+    await expect(revoking).rejects.toMatchObject({ operation: "revoke" });
+    expect(keys.getSnapshot()).toEqual([minted("a")]);
+  });
+
+  it("asks before the tab closes only while a secret is unread, per lifecycle", async () => {
+    const one = lifecycleIn();
+    const other = lifecycleIn();
+    expect(closingPrompts()).toBe(false);
+
+    await one.create(async () => minted("a"));
+    await other.create(async () => minted("b"));
+    expect(closingPrompts()).toBe(true);
+
+    other.dismiss("b");
+    expect(closingPrompts()).toBe(true);
+    one.setScope(null);
+    expect(closingPrompts()).toBe(false);
+  });
+});
+
+describe("with react-query", () => {
+  function app(keys: KeyLifecycle<KeyRecord>, server: { list: KeyRecord[] }) {
+    const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    const element = document.createElement("div");
+    document.body.append(element);
+    const root = createRoot(element);
+    cleanups.push(() => act(() => root.unmount()));
+    let route: "keys" | "docs" = "keys";
+    let mint: ((request: () => Promise<RevealedKey<KeyRecord>>) => void) | undefined;
+    let shown: readonly RevealedKey<KeyRecord>[] = [];
+
+    function KeysPage() {
+      useQuery({ queryKey: ["keys"], queryFn: async () => server.list });
+      const create = useMutation({
+        mutationFn: (request: () => Promise<RevealedKey<KeyRecord>>) => keys.create(request),
+        onSuccess: () => client.invalidateQueries({ queryKey: ["keys"] }),
+      });
+      const reveals = useKeyReveals(keys);
+      useLayoutEffect(() => {
+        mint = create.mutate;
+        shown = reveals;
+      });
+      return createElement("p", null, reveals.map((one) => one.key).join(","));
+    }
+
+    const render = () =>
+      root.render(
+        createElement(
+          QueryClientProvider,
+          { client },
+          route === "keys" ? createElement(KeysPage) : createElement("p", null, "docs"),
+        ),
+      );
+    act(render);
+
+    return {
+      client,
+      element,
+      get shown() {
+        return shown;
+      },
+      mint(request: () => Promise<RevealedKey<KeyRecord>>) {
+        act(() => mint?.(request));
+      },
+      go(next: "keys" | "docs") {
+        route = next;
+        act(render);
+      },
+    };
+  }
+
+  it("a create in flight still reveals its secret after the page unmounts", async () => {
+    const keys = lifecycleIn();
+    const screen = app(keys, { list: [] });
+    const late = deferred<RevealedKey<KeyRecord>>();
+    screen.mint(() => late.promise);
+
+    screen.go("docs");
+    await act(async () => late.resolve(minted("a")));
+    expect(keys.getSnapshot()).toEqual([minted("a")]);
+
+    screen.go("keys");
+    expect(screen.shown).toEqual([minted("a")]);
+    expect(screen.element.textContent).toBe(minted("a").key);
+  });
+
+  it("no secret reaches the mutation cache or the list cache", async () => {
+    const keys = lifecycleIn();
+    const server = { list: [] as KeyRecord[] };
+    const screen = app(keys, server);
+    const { record, key } = minted("a");
+
+    screen.mint(async () => {
+      server.list = [record];
+      return { record, key };
+    });
+    await act(() =>
+      vi.waitFor(() => expect(screen.client.getQueryData(["keys"])).toEqual([record])),
+    );
+
+    const caches = JSON.stringify([
+      screen.client
+        .getMutationCache()
+        .getAll()
+        .map((mutation) => mutation.state),
+      screen.client
+        .getQueryCache()
+        .getAll()
+        .map((query) => query.state),
+    ]);
+    expect(caches).toContain(record.prefix);
+    expect(caches).not.toContain(key);
+    expect(keys.getSnapshot()).toEqual([{ record, key }]);
+  });
+
+  it("a prerender prints no secret", async () => {
+    const keys = lifecycleIn();
+    await keys.create(async () => minted("a"));
+    function Reveals() {
+      return createElement("p", null, useKeyReveals(keys).length);
+    }
+    expect(renderToString(createElement(Reveals))).toBe("<p>0</p>");
+  });
+});

package/src/keys.ts

@@ -0,0 +1,144 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * A new API key, the one time the server sends its secret. Three products wrote this flow, and
+ * each knew one part the others missed:
+ *
+ * - One kept unread secrets in a list outside the page, so a second key did not overwrite the
+ *   first and a trip to the docs did not lose either. The tab asked before closing only while one
+ *   was unread, and signing out forgot them all.
+ * - One kept the secret out of the list cache, folding only the record into it.
+ * - None kept it out of react-query's MUTATION cache. Each `mutationFn` resolved the whole answer,
+ *   secret included, so `mutation.data` held it, one of them under a comment promising it did not.
+ *
+ * So `create` takes the secret here and resolves only the record, and the request is the caller's.
+ * Forms, permissions, list queries, invalidation and copy feedback stay in the product.
+ */
+
+/** What your create request resolves: the record your list shows, and the secret beside it. */
+export interface RevealedKey<Record> {
+  readonly record: Record;
+  readonly key: string;
+}
+
+/** The account or workspace changed while a create or revoke was in flight. */
+export class KeyScopeChangedError extends Error {
+  readonly operation: "create" | "revoke";
+
+  constructor(operation: "create" | "revoke") {
+    super(
+      operation === "create"
+        ? "The account or workspace changed before the new key could be shown. If nobody saved it, revoke it from that workspace's keys."
+        : "The account or workspace changed while the key was being revoked. Check that workspace's keys to see whether it worked.",
+    );
+    this.name = "KeyScopeChangedError";
+    this.operation = operation;
+  }
+}
+
+export interface KeyLifecycle<Record> {
+  /**
+   * Who and where keys are made for: the signed-in account and the workspace, joined into one
+   * string, or `null` once signed out. Call it from your auth and workspace subscription, never
+   * from the keys page, which may not be mounted. A new scope forgets every unread secret and
+   * rejects requests started under the old one, including when the same account signs back in.
+   */
+  setScope(scope: string | null): void;
+  /**
+   * Run your create request, keep its secret here, and resolve only the record. Use it as a
+   * `mutationFn`: neither the result nor the variables carry the secret, and the reveal still
+   * lands when the page that asked has unmounted.
+   */
+  create(request: () => Promise<RevealedKey<Record>>): Promise<Record>;
+  /** Run your revoke request. Only a success, in the same scope, forgets that key's secret. */
+  revoke(id: string, request: () => Promise<unknown>): Promise<void>;
+  /** The person saved it. Wire this to "Done", never to a copy: a copy can fail. */
+  dismiss(id: string): void;
+  /** Unread secrets, newest first. */
+  getSnapshot(): readonly RevealedKey<Record>[];
+  subscribe(listener: () => void): () => void;
+}
+
+/**
+ * One per app, created at module scope, outside every route. Memory only: never storage, the URL
+ * or a query cache, so a reload loses an unread secret, and the tab asks before closing while one
+ * is unread. The listener comes and goes with the secrets because a page with a `beforeunload`
+ * listener is kept out of some browsers' back-forward cache.
+ */
+export function createKeyLifecycle<Record extends { readonly id: string }>(): KeyLifecycle<Record> {
+  let revealed: readonly RevealedKey<Record>[] = [];
+  let scope: string | null = null;
+  let generation = 0;
+  const listeners = new Set<() => void>();
+
+  // Per instance, so two lifecycles never remove each other's prompt.
+  function askBeforeLeaving(event: BeforeUnloadEvent): void {
+    event.preventDefault();
+    // Older Chrome and Safari prompt only when this is set too. The browser picks the words.
+    event.returnValue = "";
+  }
+
+  function publish(next: readonly RevealedKey<Record>[]): void {
+    const wasUnread = revealed.length > 0;
+    revealed = next;
+    if (wasUnread !== next.length > 0 && typeof window !== "undefined") {
+      if (next.length > 0) window.addEventListener("beforeunload", askBeforeLeaving);
+      else window.removeEventListener("beforeunload", askBeforeLeaving);
+    }
+    for (const listener of listeners) listener();
+  }
+
+  /** Runs `request` under the current scope and refuses an answer that outlived it. */
+  async function scoped<T>(operation: "create" | "revoke", request: () => Promise<T>): Promise<T> {
+    if (scope === null)
+      throw new Error("Call setScope with the signed-in account and workspace first.");
+    const started = generation;
+    const answer = await request();
+    if (started !== generation) throw new KeyScopeChangedError(operation);
+    return answer;
+  }
+
+  function dismiss(id: string): void {
+    const next = revealed.filter((one) => one.record.id !== id);
+    if (next.length !== revealed.length) publish(next);
+  }
+
+  return {
+    setScope(next) {
+      if (scope === next) return;
+      scope = next;
+      generation++;
+      if (revealed.length > 0) publish([]);
+    },
+    async create(request) {
+      const { record, key } = await scoped("create", request);
+      // The record goes on to react-query and often into the list cache. A request that passed
+      // the whole answer as the record would put the secret there, which is the bug this exists
+      // to end, so say so on the first try instead.
+      if (JSON.stringify(record).includes(key))
+        throw new Error("The record still holds the secret. Resolve it without the key field.");
+      publish([{ record, key }, ...revealed]);
+      return record;
+    },
+    async revoke(id, request) {
+      await scoped("revoke", request);
+      dismiss(id);
+    },
+    dismiss,
+    getSnapshot: () => revealed,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+// The server has no unread secrets, and a prerender must never print one.
+const none: readonly never[] = [];
+
+/** Unread secrets, newest first. Unmounting the component forgets nothing. */
+export function useKeyReveals<Record>(
+  lifecycle: KeyLifecycle<Record>,
+): readonly RevealedKey<Record>[] {
+  return useSyncExternalStore(lifecycle.subscribe, lifecycle.getSnapshot, () => none);
+}

package/src/supabase-session.browser.test.ts

@@ -1,10 +1,15 @@
 // @vitest-environment happy-dom
 import { createClient } from "@supabase/supabase-js";
-import { afterEach, describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { supabaseAuthStorage } from "./supabase-session.ts";
 
 // A real browser `localStorage` and a real auth-js, so what is measured is the choice supabase-js
 // makes for itself, not this file's idea of it. The Node tests beside this one can only stub it.
+// Node 26 has a `localStorage` of its own, `undefined` without `--localstorage-file`, and vitest
+// leaves it in front of happy-dom's (`window` is the global, so it reads Node's too). A browser
+// has one, so take a happy-dom window's and put it where a browser keeps it.
+vi.stubGlobal("localStorage", new Window().localStorage);
 const PROJECT_URL = "https://abcdefghijklmnop.supabase.co";
 const USER_ID = "11111111-1111-4111-8111-111111111111";