@gusnips/react 0.9.27 → 0.9.29

package/README.md

@@ -108,7 +108,22 @@ Two rules come with it:
   has finished the first call: a moment later, or up to 22 seconds on auth-js 2.106.
 
 `error` is `null` when auth ended the session on the server too. Otherwise the person is signed
-out on this device and may still be signed in on others.
+out on this device, and that session may still be live on the server.
+
+It signs out this device only. auth-js's own default ends every session the person has, so signing
+out of a laptop also signed them out of their phone, and a tab left open there failed its next
+refresh with "Invalid Refresh Token". To end the others on purpose, give account settings a button
+that calls `signOutOtherDevices`. It keeps this device signed in, so it can be pressed again when
+it fails:
+
+```ts
+import { signOutOtherDevices } from "@gusnips/react/supabase";
+
+const { error } = await signOutOtherDevices(supabase.auth);
+```
+
+`error` is `null` once auth has ended the other sessions. Like the sign-out, it waits on auth for
+3 seconds at most.
 
 Pass the same object to `createSupabaseSessionAdapter(supabase.auth, authStorage)` and the API
 client's sign-out goes through the helper too.
@@ -674,6 +689,60 @@ silently become model messages. It returns `false` for ordinary text. The hook n
 message, clears a draft or changes attached files; those stay with the app. It also has no timer
 or scheduler: offer a repeat command only when your app has real scheduling behind it.
 
+## Signing an agent in
+
+When Claude or ChatGPT connects to your API, it sends the person to your consent page. When one of
+your scripts signs in on a machine with no browser, it prints a short code, and the person types
+it on your device page. `@gusnips/server/oauth` is the server half. These two hooks are the
+logic for the two pages. The pages themselves are yours.
+
+```tsx
+import { useConsentRequest } from "@gusnips/react/oauth";
+
+const consent = useConsentRequest(api.oauth, useLocation().search);
+
+if (consent.state.status === "ready")
+  return (
+    <Button onClick={() => consent.approve(workspaceId)} loading={consent.leaving}>
+      Allow {consent.state.view.clientName}
+    </Button>
+  );
+```
+
+`api.oauth` is two calls to your own API: `describe(query)` and `approve(query, choice)`. They
+reach the server's `describe` and `approve` through routes behind your sign-in. `state.status` is
+`loading`, `refused`, `failed` or `ready`:
+
+- **`refused`** means the request is not one to answer: an unknown app, or a return address it
+  never registered. Show `refusal.message` (or your own words for `refusal.reason`) and a link
+  home. Never a link back to the app, because sending the browser anywhere on a bad request is
+  how an open redirect is built.
+- **`failed`** means the request didn't arrive or answer. Show what failed and `state.retry`.
+- **`ready`** has the app's name and `redirectHost`, where the browser goes after the yes. Show
+  both: anyone can register any name, and the host is the part a stranger can't pick.
+
+`leaving` stays `true` from the press until the browser has left, so the button never comes back
+for a second press. Approve sends the browser on with `window.location.assign`, which also opens
+an app's own scheme such as `cursor://`.
+
+```tsx
+import { useDeviceApproval } from "@gusnips/react/oauth";
+
+const device = useDeviceApproval(api.device, useLocation().search);
+
+<input value={device.code} onChange={(event) => device.setCode(event.target.value)} />;
+```
+
+The link the script prints carries `?code=`, so the field usually starts full. The field shows
+what was typed as `WDJB-MJHT`, however it was typed. `invalidLetter` turns on as soon as a letter
+no code uses (a vowel) is typed, so you can say so before all eight are in. `state.status` adds
+three to the consent page's four: `typing` until the code is complete, then `approved` or
+`denied`. When it is `ready`, show `view.userCode` and say: go on only if you started this
+sign-in yourself, just now, and this is the code on your screen. Somebody can run the real script
+and send a stranger the link, and that sentence is the only guard against it. Once decided, the
+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.
+
 ## Also here
 
 `ErrorBoundary`, an SSE reader split into a platform-free parser and a stream wrapper,
@@ -755,6 +824,7 @@ lives behind a subpath, so you install a dependency only if you import the thing
 | `@gusnips/react/contract` | two prerender names                      | nothing               |
 | `@gusnips/react/theme`    | `createTheme`, `startTheme`              | react                 |
 | `@gusnips/react/commands` | slash matching and `useSlashCommands`    | react                 |
+| `@gusnips/react/oauth`    | `useConsentRequest`, `useDeviceApproval` | @tanstack/react-query |
 
 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/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,EACX,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -15,6 +15,7 @@
 //   @gusnips/react/supabase  the session adapter    → @supabase/supabase-js
 //   @gusnips/react/theme     the theme controller   → react only, but `@gusnips/vite/theme`
 //                                                    serializes it and must not load the rest
+//   @gusnips/react/oauth     the sign-in pages' logic → @tanstack/react-query, at runtime
 //
 // `react-dom` is the one the second migration added, and it is the sharpest case yet: that
 // adopter ships a REACT NATIVE app beside its two web apps, and React Native has no react-dom to

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,8DAA8D;AAC9D,uEAAuE;AACvE,gEAAgE;AAChE,4EAA4E;AAC5E,4FAA4F;AAC5F,8FAA8F;AAC9F,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAoC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAiB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,GAGZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GASb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,8DAA8D;AAC9D,uEAAuE;AACvE,gEAAgE;AAChE,4EAA4E;AAC5E,4FAA4F;AAC5F,8FAA8F;AAC9F,0FAA0F;AAC1F,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAoC,MAAM,WAAW,CAAC;AAChF,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAiB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EACL,aAAa,EACb,SAAS,EACT,YAAY,EACZ,WAAW,GAGZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GASb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}

package/dist/oauth.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The two pages behind an agent's sign-in: the consent page, where Claude or ChatGPT sends a
+ * person to connect, and the device page, where a script's short code is typed and approved.
+ * `@gusnips/server/oauth` is the server half. Logic only: the pages are the product's.
+ *
+ * Each hook takes your two API calls, so your client, your session and your envelope stay yours,
+ * and returns one state to draw. What they settle once:
+ *
+ * - A refusal (an unknown app, a return address it never registered) is a STATE, never a
+ *   redirect: sending the browser anywhere on a bad request is how an open redirect is built.
+ * - Approve stays busy from the press until the browser has left. The page is going away, so the
+ *   button must never come back and invite a second press.
+ * - A device code is read however it is typed (`wdjb mjht`, `WDJB-MJHT`), and once decided the
+ *   page stays decided. Asked again, the server no longer knows the code, and a page that asked on
+ *   the next focus would tell someone who just approved that their code is wrong.
+ */
+export type OAuthRefusalReason = "unknown-client" | "redirect-mismatch" | "invalid-request" | "wrong-resource" | "unknown-code";
+/** What the server sends instead of a view. Word your own page for `reason`. */
+export interface OAuthRefusal {
+    ok: false;
+    reason: OAuthRefusalReason;
+    /** An English fallback a person can read. */
+    message: string;
+}
+export interface ConsentView {
+    ok: true;
+    /** What the app calls itself. Anyone may pick any name, so show `redirectHost` beside it. */
+    clientName: string;
+    /** Where the browser goes after the yes: a host, or an app's own scheme (`cursor:`). */
+    redirectHost: string;
+    /** The key's name on your keys page. */
+    keyName: string;
+    /** Where "Cancel" goes: back to the app, which is told the person said no. */
+    cancelUrl: string;
+}
+export interface DeviceView {
+    ok: true;
+    clientName: string;
+    /** As the script printed it: `WDJB-MJHT`. */
+    userCode: string;
+    keyName: string;
+    /** ISO time: JSON carries the server's `Date` as a string. */
+    expiresAt: string;
+}
+export interface ConsentApi<Choice> {
+    /** Your API's call to the server's `describe`, with the query string as it came. */
+    describe(query: string): Promise<ConsentView | OAuthRefusal>;
+    /** Your API's call to `approve`. `choice` is anything your page adds, such as a workspace. */
+    approve(query: string, choice: Choice): Promise<{
+        ok: true;
+        redirectTo: string;
+    } | OAuthRefusal>;
+}
+export type ConsentState = {
+    status: "loading";
+}
+/** Show `refusal` and a way home. Never a link back to the app. */
+ | {
+    status: "refused";
+    refusal: OAuthRefusal;
+}
+/** The request failed to arrive or answer. Show what failed, and `retry`. */
+ | {
+    status: "failed";
+    error: unknown;
+    retry: () => void;
+} | {
+    status: "ready";
+    view: ConsentView;
+};
+export interface ConsentRequest<Choice> {
+    state: ConsentState;
+    approve(choice: Choice): void;
+    /** From the press until the browser has left. Keep the button busy the whole time. */
+    leaving: boolean;
+    /** Approve did not answer. Show it beside the button; pressing again retries. */
+    approveError: unknown;
+}
+/**
+ *     const consent = useConsentRequest(api.oauth, useLocation().search);
+ *     if (consent.state.status === "ready") ... consent.approve(workspaceId)
+ */
+export declare function useConsentRequest<Choice = void>(api: ConsentApi<Choice>, search: string): ConsentRequest<Choice>;
+export interface DeviceApi {
+    /** Your API's call to the server's `describeDevice`. */
+    describe(code: string): Promise<DeviceView | OAuthRefusal>;
+    /** Your API's call to `decideDevice`. */
+    decide(code: string, decision: "approve" | "deny"): Promise<{
+        ok: true;
+    } | OAuthRefusal>;
+}
+export type DeviceState = 
+/** Fewer than 8 letters so far, or one a code never uses (see `invalidLetter`). */
+{
+    status: "typing";
+} | {
+    status: "loading";
+}
+/** Unknown, expired or already decided: ask them to start again from the app. */
+ | {
+    status: "refused";
+    refusal: OAuthRefusal;
+} | {
+    status: "failed";
+    error: unknown;
+    retry: () => void;
+}
+/**
+ * Show `view.userCode` and say: go on only if you started this sign-in yourself, just now, and
+ * this is the code on your screen. Somebody can run the real script and send a stranger the
+ * link, and that sentence is the only guard against it (RFC 8628 §5.4).
+ */
+ | {
+    status: "ready";
+    view: DeviceView;
+}
+/** Done. Tell them to go back to the app, which carries on by itself. */
+ | {
+    status: "approved";
+} | {
+    status: "denied";
+};
+export interface DeviceApproval {
+    state: DeviceState;
+    /** What the field shows, formatted as they type: `WDJB-MJ`. */
+    code: string;
+    setCode(input: string): void;
+    /** A typed letter no code uses: a vowel. Say so now, not after eight letters. */
+    invalidLetter: boolean;
+    approve(): void;
+    deny(): void;
+    deciding: boolean;
+    /** The decision did not answer. Show it beside the buttons; pressing again retries. */
+    decideError: unknown;
+}
+/** Upper case, letters only, at most 8, with the dash after the fourth: what the field shows. */
+export declare function formatUserCode(input: string): string;
+/**
+ *     const device = useDeviceApproval(api.device, useLocation().search);
+ *     <input value={device.code} onChange={(e) => device.setCode(e.target.value)} />
+ *
+ * The link the script prints carries `?code=`, so the field usually starts full.
+ */
+export declare function useDeviceApproval(api: DeviceApi, search: string): DeviceApproval;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,kBAAkB,GAC5B,gBAAgB,GAAG,mBAAmB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAEjG,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,kBAAkB,CAAC;IAC3B,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,IAAI,CAAC;IACT,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;IACnB,wFAAwF;IACxF,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,IAAI,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU,CAAC,MAAM;IAChC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,YAAY,CAAC,CAAC;IAC7D,8FAA8F;IAC9F,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,YAAY,CAAC,CAAC;CAClG;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE;AACvB,mEAAmE;GACjE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE;AAC9C,6EAA6E;GAC3E;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAE3C,MAAM,WAAW,cAAc,CAAC,MAAM;IACpC,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sFAAsF;IACtF,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAG,IAAI,EAC7C,GAAG,EAAE,UAAU,CAAC,MAAM,CAAC,EACvB,MAAM,EAAE,MAAM,GACb,cAAc,CAAC,MAAM,CAAC,CA8BxB;AAED,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,YAAY,CAAC,CAAC;IAC3D,yCAAyC;IACzC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG,YAAY,CAAC,CAAC;CAC1F;AAED,MAAM,MAAM,WAAW;AACrB,mFAAmF;AACjF;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE;AACvB,iFAAiF;GAC/E;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE;AACzD;;;;GAIG;GACD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE;AACvC,yEAAyE;GACvE;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEzB,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,WAAW,CAAC;IACnB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iFAAiF;IACjF,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;IAChB,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,uFAAuF;IACvF,WAAW,EAAE,OAAO,CAAC;CACtB;AAMD,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CA2ChF"}

package/dist/oauth.js

@@ -0,0 +1,99 @@
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+/**
+ *     const consent = useConsentRequest(api.oauth, useLocation().search);
+ *     if (consent.state.status === "ready") ... consent.approve(workspaceId)
+ */
+export function useConsentRequest(api, search) {
+    const query = search.replace(/^\?/, "");
+    const request = useQuery({
+        queryKey: ["@gusnips/react/oauth", "consent", query],
+        queryFn: () => api.describe(query),
+    });
+    const approval = useMutation({
+        mutationFn: (choice) => api.approve(query, choice),
+        onSuccess: (answer) => {
+            if (answer.ok)
+                window.location.assign(answer.redirectTo);
+        },
+    });
+    // A refusal from approve (the request went stale between the two calls) outranks the view.
+    const answer = request.data;
+    const refusal = approval.data?.ok === false ? approval.data : answer?.ok === false ? answer : null;
+    let state;
+    if (refusal)
+        state = { status: "refused", refusal };
+    else if (answer?.ok === true)
+        state = { status: "ready", view: answer };
+    else if (request.isError)
+        state = { status: "failed", error: request.error, retry: () => void request.refetch() };
+    else
+        state = { status: "loading" };
+    return {
+        state,
+        approve: (choice) => approval.mutate(choice),
+        leaving: approval.isPending || approval.data?.ok === true,
+        approveError: approval.error,
+    };
+}
+/** The server's alphabet: no vowels, so a code never spells a word. */
+const ALPHABET = "BCDFGHJKLMNPQRSTVWXZ";
+const LENGTH = 8;
+/** Upper case, letters only, at most 8, with the dash after the fourth: what the field shows. */
+export function formatUserCode(input) {
+    const letters = input
+        .toUpperCase()
+        .replace(/[^A-Z]/g, "")
+        .slice(0, LENGTH);
+    return letters.length > 4 ? `${letters.slice(0, 4)}-${letters.slice(4)}` : letters;
+}
+/**
+ *     const device = useDeviceApproval(api.device, useLocation().search);
+ *     <input value={device.code} onChange={(e) => device.setCode(e.target.value)} />
+ *
+ * The link the script prints carries `?code=`, so the field usually starts full.
+ */
+export function useDeviceApproval(api, search) {
+    const [code, setTyped] = useState(() => formatUserCode(new URLSearchParams(search).get("code") ?? ""));
+    const letters = code.replace("-", "");
+    const invalidLetter = [...letters].some((letter) => !ALPHABET.includes(letter));
+    const complete = letters.length === LENGTH && !invalidLetter;
+    const decision = useMutation({
+        mutationFn: (choice) => api.decide(letters, choice),
+    });
+    const decided = decision.data?.ok === true ? decision.variables : undefined;
+    const request = useQuery({
+        queryKey: ["@gusnips/react/oauth", "device", letters],
+        queryFn: () => api.describe(letters),
+        enabled: complete && decided === undefined,
+    });
+    const answer = request.data;
+    const refusal = decision.data?.ok === false ? decision.data : answer?.ok === false ? answer : null;
+    let state;
+    if (decided !== undefined)
+        state = { status: decided === "approve" ? "approved" : "denied" };
+    else if (!complete)
+        state = { status: "typing" };
+    else if (refusal)
+        state = { status: "refused", refusal };
+    else if (answer?.ok === true)
+        state = { status: "ready", view: answer };
+    else if (request.isError)
+        state = { status: "failed", error: request.error, retry: () => void request.refetch() };
+    else
+        state = { status: "loading" };
+    return {
+        state,
+        code,
+        setCode: (input) => {
+            decision.reset();
+            setTyped(formatUserCode(input));
+        },
+        invalidLetter,
+        approve: () => decision.mutate("approve"),
+        deny: () => decision.mutate("deny"),
+        deciding: decision.isPending,
+        decideError: decision.error,
+    };
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.js","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AA4EjC;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAuB,EACvB,MAAc;IAEd,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,QAAQ,CAAC;QACvB,QAAQ,EAAE,CAAC,sBAAsB,EAAE,SAAS,EAAE,KAAK,CAAC;QACpD,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;KACnC,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,WAAW,CAAC;QAC3B,UAAU,EAAE,CAAC,MAAc,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;QAC1D,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE;YACpB,IAAI,MAAM,CAAC,EAAE;gBAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC3D,CAAC;KACF,CAAC,CAAC;IAEH,2FAA2F;IAC3F,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAC5B,MAAM,OAAO,GACX,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACrF,IAAI,KAAmB,CAAC;IACxB,IAAI,OAAO;QAAE,KAAK,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;SAC/C,IAAI,MAAM,EAAE,EAAE,KAAK,IAAI;QAAE,KAAK,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;SACnE,IAAI,OAAO,CAAC,OAAO;QACtB,KAAK,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;;QACrF,KAAK,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAEnC,OAAO;QACL,KAAK;QACL,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;QAC5C,OAAO,EAAE,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,IAAI;QACzD,YAAY,EAAE,QAAQ,CAAC,KAAK;KAC7B,CAAC;AACJ,CAAC;AAwCD,uEAAuE;AACvE,MAAM,QAAQ,GAAG,sBAAsB,CAAC;AACxC,MAAM,MAAM,GAAG,CAAC,CAAC;AAEjB,iGAAiG;AACjG,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,KAAK;SAClB,WAAW,EAAE;SACb,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;SACtB,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACpB,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AACrF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAc,EAAE,MAAc;IAC9D,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CACrC,cAAc,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAC9D,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,aAAa,CAAC;IAE7D,MAAM,QAAQ,GAAG,WAAW,CAAC;QAC3B,UAAU,EAAE,CAAC,MAA0B,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC;KACxE,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,MAAM,OAAO,GAAG,QAAQ,CAAC;QACvB,QAAQ,EAAE,CAAC,sBAAsB,EAAE,QAAQ,EAAE,OAAO,CAAC;QACrD,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC;QACpC,OAAO,EAAE,QAAQ,IAAI,OAAO,KAAK,SAAS;KAC3C,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAC5B,MAAM,OAAO,GACX,QAAQ,CAAC,IAAI,EAAE,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACrF,IAAI,KAAkB,CAAC;IACvB,IAAI,OAAO,KAAK,SAAS;QAAE,KAAK,GAAG,EAAE,MAAM,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;SACxF,IAAI,CAAC,QAAQ;QAAE,KAAK,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;SAC5C,IAAI,OAAO;QAAE,KAAK,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;SACpD,IAAI,MAAM,EAAE,EAAE,KAAK,IAAI;QAAE,KAAK,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;SACnE,IAAI,OAAO,CAAC,OAAO;QACtB,KAAK,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;;QACrF,KAAK,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAEnC,OAAO;QACL,KAAK;QACL,IAAI;QACJ,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACjB,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjB,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,aAAa;QACb,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;QACzC,IAAI,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;QACnC,QAAQ,EAAE,QAAQ,CAAC,SAAS;QAC5B,WAAW,EAAE,QAAQ,CAAC,KAAK;KAC5B,CAAC;AACJ,CAAC"}

package/dist/supabase-session.d.ts

@@ -93,11 +93,17 @@ export declare function supabaseAuthStorage(supabaseUrl: string): SupabaseSessio
  *   it touches storage. This happens at every version, and it is the common case: a laptop that
  *   wakes up offline with a tab still open.
  * - Before 2.110.2, the token is still good but `/logout` gets no answer. `signOut()` returns
- *   before it removes anything. `scope: "local"` does not help, because it calls `/logout` too.
+ *   before it removes anything.
  *
  * Either way a reload reads the session and signs the person back in. On a shared computer, that
  * person is whoever sits down next. A screen that says "signed out" at that point is wrong.
  *
+ * It ends this device's session and no other: `signOut({ scope: "local" })`, which fails in both
+ * cases above too, because it calls `/logout` as well. auth-js's default is `"global"`, which ends
+ * every session the person has. Signing out of a laptop then signed them out of their phone, and a
+ * tab left open anywhere failed its next refresh with "Invalid Refresh Token: Refresh Token Not
+ * Found". To end the other sessions on purpose, use {@link signOutOtherDevices}.
+ *
  * Removing the key yourself is not enough on its own: nothing tells your `onAuthStateChange`
  * listeners or your other tabs, and auth-js's PKCE verifiers stay behind. So after removing it,
  * this calls `signOut({ scope: "local" })`. That call finds no session, skips `/logout`, and runs
@@ -110,7 +116,7 @@ export declare function supabaseAuthStorage(supabaseUrl: string): SupabaseSessio
  *
  * It resolves once the stored session is gone. `error` is `null` when auth ended the session on the
  * server too. Otherwise it is the reason auth did not: its error, a thrown value or the deadline.
- * The session may still be live on the server and on other devices. `SIGNED_OUT` arrives once
+ * The session may still be live on the server. `SIGNED_OUT` arrives once
  * auth-js has finished with the first call: about 100 ms later from 2.108.2 on, and up to 22 s
  * later at 2.106.2. If your screen does not reload, clear your own store when this resolves instead
  * of waiting for the event.
@@ -118,6 +124,21 @@ export declare function supabaseAuthStorage(supabaseUrl: string): SupabaseSessio
 export declare function signOutEvenOffline(auth: Pick<SupabaseSessionAuth, "signOut">, { storage, storageKey }: SupabaseSessionStorage): Promise<{
     error: unknown;
 }>;
+/**
+ * Ends the person's sessions on every other device and keeps this one signed in. For a "sign out
+ * of other devices" button in account settings: a phone that was lost, a computer left signed in.
+ *
+ * It resolves `{ error: null }` once auth has ended the other sessions. Otherwise `error` says why
+ * it did not: auth's error, a thrown value, or the deadline. This device is untouched either way,
+ * so the person is still signed in and can press the button again.
+ *
+ * Like {@link signOutEvenOffline}, it waits on auth for {@link SIGN_OUT_TIMEOUT_MS} at most, because
+ * offline with an expired token auth-js first sits in its refresh backoff. A deadline does not
+ * prove the other sessions are still live: auth may end them after this gave up.
+ */
+export declare function signOutOtherDevices(auth: Pick<SupabaseSessionAuth, "signOut">): Promise<{
+    error: unknown;
+}>;
 /**
  * Connects a Supabase auth client to {@link SessionAdapter}.
  *
@@ -130,7 +151,8 @@ export declare function signOutEvenOffline(auth: Pick<SupabaseSessionAuth, "sign
  * rejection means. It still rejects when auth did not end the session, but by then the session
  * has already left this device. And a sign-out auth has not answered within
  * {@link SIGN_OUT_TIMEOUT_MS} now rejects instead of hanging. Without `stored`, it is
- * `auth.signOut()` and rejects on that call's error, as before.
+ * `auth.signOut({ scope: "local" })` and rejects on that call's error. Either way it ends this
+ * device's session only: a token one device's API refused says nothing about the others.
  *
  * `stored` is optional here but not at a sign-out button. The API client signs out only after
  * auth has answered: a refresh auth refused, or a new token the API refused. So the network was up

package/dist/supabase-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supabase-session.d.ts","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,OAAO,EAGZ,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE3E,UAAU,qBAAqB;IAC7B,IAAI,EAAE;QAAE,OAAO,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CACpD;AAED,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC,UAAU,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7C,cAAc,IAAI,OAAO,CAAC,qBAAqB,GAAG;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACzD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASpD;AAaD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,CAE/E;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,CAAC,EAC1C,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,sBAAsB,GAC9C,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAyB7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,EACzB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,cAAc,CAsBhB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GACvB,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,OAAO,CAAC;AAiB5E,qFAAqF;AACrF,MAAM,MAAM,YAAY;AACtB,0FAA0F;AACxF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAA;CAAE;AAChE;;;;;;GAMG;GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF;AACH;;;;GAIG;GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE;AAClF,qFAAqF;GACnF;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE,IAAI,SAAK,GAAG,YAAY,CA6B3F"}
+{"version":3,"file":"supabase-session.d.ts","sourceRoot":"","sources":["../src/supabase-session.ts"],"names":[],"mappings":"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"}

package/dist/supabase-session.js

@@ -116,11 +116,17 @@ function localStorageOrMemory() {
  *   it touches storage. This happens at every version, and it is the common case: a laptop that
  *   wakes up offline with a tab still open.
  * - Before 2.110.2, the token is still good but `/logout` gets no answer. `signOut()` returns
- *   before it removes anything. `scope: "local"` does not help, because it calls `/logout` too.
+ *   before it removes anything.
  *
  * Either way a reload reads the session and signs the person back in. On a shared computer, that
  * person is whoever sits down next. A screen that says "signed out" at that point is wrong.
  *
+ * It ends this device's session and no other: `signOut({ scope: "local" })`, which fails in both
+ * cases above too, because it calls `/logout` as well. auth-js's default is `"global"`, which ends
+ * every session the person has. Signing out of a laptop then signed them out of their phone, and a
+ * tab left open anywhere failed its next refresh with "Invalid Refresh Token: Refresh Token Not
+ * Found". To end the other sessions on purpose, use {@link signOutOtherDevices}.
+ *
  * Removing the key yourself is not enough on its own: nothing tells your `onAuthStateChange`
  * listeners or your other tabs, and auth-js's PKCE verifiers stay behind. So after removing it,
  * this calls `signOut({ scope: "local" })`. That call finds no session, skips `/logout`, and runs
@@ -133,23 +139,13 @@ function localStorageOrMemory() {
  *
  * It resolves once the stored session is gone. `error` is `null` when auth ended the session on the
  * server too. Otherwise it is the reason auth did not: its error, a thrown value or the deadline.
- * The session may still be live on the server and on other devices. `SIGNED_OUT` arrives once
+ * The session may still be live on the server. `SIGNED_OUT` arrives once
  * auth-js has finished with the first call: about 100 ms later from 2.108.2 on, and up to 22 s
  * later at 2.106.2. If your screen does not reload, clear your own store when this resolves instead
  * of waiting for the event.
  */
 export async function signOutEvenOffline(auth, { storage, storageKey }) {
-    let timer;
-    const deadline = new Promise((resolve) => {
-        timer = setTimeout(() => resolve({
-            error: new Error(`Auth did not answer the sign-out within ${SIGN_OUT_TIMEOUT_MS} ms`),
-        }), SIGN_OUT_TIMEOUT_MS);
-    });
-    const { error } = await Promise.race([
-        auth.signOut().catch((thrown) => ({ error: thrown })),
-        deadline,
-    ]);
-    clearTimeout(timer);
+    const { error } = await withinSignOutDeadline(auth.signOut({ scope: "local" }));
     if (error == null)
         return { error: null };
     // From 2.110.2 on, auth-js has already removed the session when only `/logout` failed, and has
@@ -162,6 +158,36 @@ export async function signOutEvenOffline(auth, { storage, storageKey }) {
     void auth.signOut({ scope: "local" }).catch(() => { });
     return { error };
 }
+/**
+ * Ends the person's sessions on every other device and keeps this one signed in. For a "sign out
+ * of other devices" button in account settings: a phone that was lost, a computer left signed in.
+ *
+ * It resolves `{ error: null }` once auth has ended the other sessions. Otherwise `error` says why
+ * it did not: auth's error, a thrown value, or the deadline. This device is untouched either way,
+ * so the person is still signed in and can press the button again.
+ *
+ * Like {@link signOutEvenOffline}, it waits on auth for {@link SIGN_OUT_TIMEOUT_MS} at most, because
+ * offline with an expired token auth-js first sits in its refresh backoff. A deadline does not
+ * prove the other sessions are still live: auth may end them after this gave up.
+ */
+export function signOutOtherDevices(auth) {
+    return withinSignOutDeadline(auth.signOut({ scope: "others" }));
+}
+/** `call`'s result, or the deadline as its error once {@link SIGN_OUT_TIMEOUT_MS} has passed. */
+async function withinSignOutDeadline(call) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({
+            error: new Error(`Auth did not answer the sign-out within ${SIGN_OUT_TIMEOUT_MS} ms`),
+        }), SIGN_OUT_TIMEOUT_MS);
+    });
+    const result = await Promise.race([
+        call.catch((thrown) => ({ error: thrown })),
+        deadline,
+    ]);
+    clearTimeout(timer);
+    return result;
+}
 /**
  * Connects a Supabase auth client to {@link SessionAdapter}.
  *
@@ -174,7 +200,8 @@ export async function signOutEvenOffline(auth, { storage, storageKey }) {
  * rejection means. It still rejects when auth did not end the session, but by then the session
  * has already left this device. And a sign-out auth has not answered within
  * {@link SIGN_OUT_TIMEOUT_MS} now rejects instead of hanging. Without `stored`, it is
- * `auth.signOut()` and rejects on that call's error, as before.
+ * `auth.signOut({ scope: "local" })` and rejects on that call's error. Either way it ends this
+ * device's session only: a token one device's API refused says nothing about the others.
  *
  * `stored` is optional here but not at a sign-out button. The API client signs out only after
  * auth has answered: a refresh auth refused, or a new token the API refused. So the network was up
@@ -199,7 +226,9 @@ export function createSupabaseSessionAdapter(auth, stored) {
             }
         },
         signOut: async () => {
-            const { error } = stored ? await signOutEvenOffline(auth, stored) : await auth.signOut();
+            const { error } = stored
+                ? await signOutEvenOffline(auth, stored)
+                : await auth.signOut({ scope: "local" });
             if (error)
                 throw error;
         },

package/dist/supabase-session.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.27",
+  "version": "0.9.29",
   "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",
@@ -45,6 +45,10 @@
     "./commands": {
       "types": "./dist/commands.d.ts",
       "default": "./dist/commands.js"
+    },
+    "./oauth": {
+      "types": "./dist/oauth.d.ts",
+      "default": "./dist/oauth.js"
     }
   },
   "types": "./dist/index.d.ts",

package/src/index.ts

@@ -15,6 +15,7 @@
 //   @gusnips/react/supabase  the session adapter    → @supabase/supabase-js
 //   @gusnips/react/theme     the theme controller   → react only, but `@gusnips/vite/theme`
 //                                                    serializes it and must not load the rest
+//   @gusnips/react/oauth     the sign-in pages' logic → @tanstack/react-query, at runtime
 //
 // `react-dom` is the one the second migration added, and it is the sharpest case yet: that
 // adopter ships a REACT NATIVE app beside its two web apps, and React Native has no react-dom to

package/src/oauth.test.ts

@@ -0,0 +1,257 @@
+// @vitest-environment happy-dom
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  formatUserCode,
+  useConsentRequest,
+  useDeviceApproval,
+  type ConsentApi,
+  type ConsentView,
+  type DeviceApi,
+  type DeviceView,
+  type OAuthRefusal,
+} from "./oauth.ts";
+
+vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+
+const roots = new Set<Root>();
+afterEach(() => {
+  for (const root of roots) act(() => root.unmount());
+  roots.clear();
+  vi.restoreAllMocks();
+});
+
+/** Renders `hook` under a fresh query client and keeps its latest answer in `current`. */
+function mount<T>(hook: () => T) {
+  const seen: T[] = [];
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  function Probe() {
+    seen.push(hook());
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  roots.add(root);
+  act(() => root.render(createElement(QueryClientProvider, { client }, createElement(Probe))));
+  return {
+    client,
+    get current(): T {
+      const last = seen.at(-1);
+      if (last === undefined) throw new Error("The hook never rendered");
+      return last;
+    },
+  };
+}
+
+/**
+ * Lets pending promises and the renders they cause finish. react-query hands its updates to a
+ * scheduler that runs on a later task, so one tick is not always enough.
+ */
+const settle = () =>
+  act(async () => {
+    for (let tick = 0; tick < 5; tick++) await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+const VIEW: ConsentView = {
+  ok: true,
+  clientName: "Claude",
+  redirectHost: "claude.ai",
+  keyName: "Claude (claude.ai)",
+  cancelUrl: "https://claude.ai/cb?error=access_denied",
+};
+const REFUSAL: OAuthRefusal = {
+  ok: false,
+  reason: "redirect-mismatch",
+  message: "This app's sign-in link is not valid.",
+};
+
+describe("useConsentRequest", () => {
+  it("loads the request, approves with the page's choice, and leaves for the redirect", async () => {
+    const assign = vi.spyOn(window.location, "assign").mockImplementation(() => {});
+    let release!: () => void;
+    const api: ConsentApi<string> = {
+      describe: vi.fn(async () => VIEW),
+      approve: vi.fn(
+        () =>
+          new Promise<{ ok: true; redirectTo: string }>((resolve) => {
+            release = () => resolve({ ok: true, redirectTo: "https://claude.ai/cb?code=c1" });
+          }),
+      ),
+    };
+    const page = mount(() => useConsentRequest(api, "?client_id=x&state=s"));
+    expect(page.current.state).toEqual({ status: "loading" });
+    await settle();
+    expect(page.current.state).toEqual({ status: "ready", view: VIEW });
+    expect(api.describe).toHaveBeenCalledWith("client_id=x&state=s");
+
+    act(() => page.current.approve("ws-1"));
+    await settle();
+    expect(api.approve).toHaveBeenCalledWith("client_id=x&state=s", "ws-1");
+    expect(page.current.leaving).toBe(true);
+
+    release();
+    await settle();
+    expect(assign).toHaveBeenCalledWith("https://claude.ai/cb?code=c1");
+    // The page is going away: the button must not come back for a second press.
+    expect(page.current.leaving).toBe(true);
+  });
+
+  it("shows a refusal as a state and never redirects on it", async () => {
+    const assign = vi.spyOn(window.location, "assign").mockImplementation(() => {});
+    const page = mount(() =>
+      useConsentRequest({ describe: async () => REFUSAL, approve: vi.fn() }, "?client_id=x"),
+    );
+    await settle();
+    expect(page.current.state).toEqual({ status: "refused", refusal: REFUSAL });
+    expect(assign).not.toHaveBeenCalled();
+  });
+
+  it("turns a refusal from approve into the refused state, and stays put", async () => {
+    const assign = vi.spyOn(window.location, "assign").mockImplementation(() => {});
+    const page = mount(() =>
+      useConsentRequest({ describe: async () => VIEW, approve: async () => REFUSAL }, ""),
+    );
+    await settle();
+    act(() => page.current.approve());
+    await settle();
+    expect(page.current.state).toEqual({ status: "refused", refusal: REFUSAL });
+    expect(page.current.leaving).toBe(false);
+    expect(assign).not.toHaveBeenCalled();
+  });
+
+  it("offers a retry when the request failed to answer, and recovers", async () => {
+    let calls = 0;
+    const page = mount(() =>
+      useConsentRequest(
+        {
+          describe: async () => {
+            calls += 1;
+            if (calls === 1) throw new TypeError("Failed to fetch");
+            return VIEW;
+          },
+          approve: vi.fn(),
+        },
+        "?a=1",
+      ),
+    );
+    await settle();
+    const failed = page.current.state;
+    if (failed.status !== "failed") throw new Error(`expected failed, got ${failed.status}`);
+    expect(failed.error).toBeInstanceOf(TypeError);
+    act(() => failed.retry());
+    await settle();
+    expect(page.current.state).toEqual({ status: "ready", view: VIEW });
+  });
+
+  it("keeps an approve that did not answer beside the button, ready to press again", async () => {
+    const page = mount(() =>
+      useConsentRequest(
+        {
+          describe: async () => VIEW,
+          approve: async () => {
+            throw new TypeError("Failed to fetch");
+          },
+        },
+        "",
+      ),
+    );
+    await settle();
+    act(() => page.current.approve());
+    await settle();
+    expect(page.current.approveError).toBeInstanceOf(TypeError);
+    expect(page.current.leaving).toBe(false);
+    expect(page.current.state.status).toBe("ready");
+  });
+});
+
+const DEVICE: DeviceView = {
+  ok: true,
+  clientName: "Acme CLI",
+  userCode: "WDJB-MJHT",
+  keyName: "Acme CLI (device sign-in)",
+  expiresAt: "2026-10-16T12:10:00.000Z",
+};
+
+describe("useDeviceApproval", () => {
+  function deviceApi(overrides: Partial<DeviceApi> = {}) {
+    return {
+      describe: vi.fn<DeviceApi["describe"]>(overrides.describe ?? (async () => DEVICE)),
+      decide: vi.fn<DeviceApi["decide"]>(overrides.decide ?? (async () => ({ ok: true }))),
+    };
+  }
+
+  it("starts from the link's code, asks the server, and stays approved after the yes", async () => {
+    const api = deviceApi();
+    const page = mount(() => useDeviceApproval(api, "?code=wdjb-mjht"));
+    expect(page.current.code).toBe("WDJB-MJHT");
+    await settle();
+    expect(page.current.state).toEqual({ status: "ready", view: DEVICE });
+    expect(api.describe).toHaveBeenCalledWith("WDJBMJHT");
+
+    act(() => page.current.approve());
+    await settle();
+    expect(api.decide).toHaveBeenCalledWith("WDJBMJHT", "approve");
+    expect(page.current.state).toEqual({ status: "approved" });
+
+    // A refetch on focus would now hear "unknown code". It must not be asked.
+    api.describe.mockResolvedValue({ ok: false, reason: "unknown-code", message: "gone" });
+    await act(async () => page.client.invalidateQueries());
+    await settle();
+    expect(page.current.state).toEqual({ status: "approved" });
+    expect(api.describe).toHaveBeenCalledTimes(1);
+  });
+
+  it("waits for all eight letters before asking, and flags a vowel at once", async () => {
+    const api = deviceApi();
+    const page = mount(() => useDeviceApproval(api, ""));
+    expect(page.current.state).toEqual({ status: "typing" });
+    act(() => page.current.setCode("wdjb m"));
+    expect(page.current.code).toBe("WDJB-M");
+    act(() => page.current.setCode("WDJA"));
+    expect(page.current.invalidLetter).toBe(true);
+    act(() => page.current.setCode("WDJB MJHTX"));
+    expect(page.current.code).toBe("WDJB-MJHT");
+    await settle();
+    expect(api.describe).toHaveBeenCalledTimes(1);
+    expect(page.current.state.status).toBe("ready");
+  });
+
+  it("says no, and shows a code the server does not know as refused", async () => {
+    const said = mount(() => useDeviceApproval(deviceApi(), "?code=WDJBMJHT"));
+    await settle();
+    act(() => said.current.deny());
+    await settle();
+    expect(said.current.state).toEqual({ status: "denied" });
+
+    const unknown: OAuthRefusal = { ok: false, reason: "unknown-code", message: "expired" };
+    const gone = mount(() =>
+      useDeviceApproval(deviceApi({ describe: async () => unknown }), "?code=WDJBMJHT"),
+    );
+    await settle();
+    expect(gone.current.state).toEqual({ status: "refused", refusal: unknown });
+  });
+
+  it("shows a decision the server refused, and lets a new code start over", async () => {
+    const unknown: OAuthRefusal = { ok: false, reason: "unknown-code", message: "expired" };
+    const api = deviceApi({ decide: async () => unknown });
+    const page = mount(() => useDeviceApproval(api, "?code=WDJBMJHT"));
+    await settle();
+    act(() => page.current.approve());
+    await settle();
+    expect(page.current.state).toEqual({ status: "refused", refusal: unknown });
+    act(() => page.current.setCode("BCDF GHJK"));
+    await settle();
+    expect(page.current.state.status).toBe("ready");
+  });
+});
+
+describe("formatUserCode", () => {
+  it("writes what the field shows", () => {
+    expect(formatUserCode("")).toBe("");
+    expect(formatUserCode("wdj")).toBe("WDJ");
+    expect(formatUserCode("wdjb")).toBe("WDJB");
+    expect(formatUserCode("wdjbm")).toBe("WDJB-M");
+    expect(formatUserCode(" w-d j b m j h t z ")).toBe("WDJB-MJHT");
+  });
+});

package/src/oauth.ts

@@ -0,0 +1,217 @@
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+
+/**
+ * The two pages behind an agent's sign-in: the consent page, where Claude or ChatGPT sends a
+ * person to connect, and the device page, where a script's short code is typed and approved.
+ * `@gusnips/server/oauth` is the server half. Logic only: the pages are the product's.
+ *
+ * Each hook takes your two API calls, so your client, your session and your envelope stay yours,
+ * and returns one state to draw. What they settle once:
+ *
+ * - A refusal (an unknown app, a return address it never registered) is a STATE, never a
+ *   redirect: sending the browser anywhere on a bad request is how an open redirect is built.
+ * - Approve stays busy from the press until the browser has left. The page is going away, so the
+ *   button must never come back and invite a second press.
+ * - A device code is read however it is typed (`wdjb mjht`, `WDJB-MJHT`), and once decided the
+ *   page stays decided. Asked again, the server no longer knows the code, and a page that asked on
+ *   the next focus would tell someone who just approved that their code is wrong.
+ */
+
+export type OAuthRefusalReason =
+  "unknown-client" | "redirect-mismatch" | "invalid-request" | "wrong-resource" | "unknown-code";
+
+/** What the server sends instead of a view. Word your own page for `reason`. */
+export interface OAuthRefusal {
+  ok: false;
+  reason: OAuthRefusalReason;
+  /** An English fallback a person can read. */
+  message: string;
+}
+
+export interface ConsentView {
+  ok: true;
+  /** What the app calls itself. Anyone may pick any name, so show `redirectHost` beside it. */
+  clientName: string;
+  /** Where the browser goes after the yes: a host, or an app's own scheme (`cursor:`). */
+  redirectHost: string;
+  /** The key's name on your keys page. */
+  keyName: string;
+  /** Where "Cancel" goes: back to the app, which is told the person said no. */
+  cancelUrl: string;
+}
+
+export interface DeviceView {
+  ok: true;
+  clientName: string;
+  /** As the script printed it: `WDJB-MJHT`. */
+  userCode: string;
+  keyName: string;
+  /** ISO time: JSON carries the server's `Date` as a string. */
+  expiresAt: string;
+}
+
+export interface ConsentApi<Choice> {
+  /** Your API's call to the server's `describe`, with the query string as it came. */
+  describe(query: string): Promise<ConsentView | OAuthRefusal>;
+  /** Your API's call to `approve`. `choice` is anything your page adds, such as a workspace. */
+  approve(query: string, choice: Choice): Promise<{ ok: true; redirectTo: string } | OAuthRefusal>;
+}
+
+export type ConsentState =
+  | { status: "loading" }
+  /** Show `refusal` and a way home. Never a link back to the app. */
+  | { status: "refused"; refusal: OAuthRefusal }
+  /** The request failed to arrive or answer. Show what failed, and `retry`. */
+  | { status: "failed"; error: unknown; retry: () => void }
+  | { status: "ready"; view: ConsentView };
+
+export interface ConsentRequest<Choice> {
+  state: ConsentState;
+  approve(choice: Choice): void;
+  /** From the press until the browser has left. Keep the button busy the whole time. */
+  leaving: boolean;
+  /** Approve did not answer. Show it beside the button; pressing again retries. */
+  approveError: unknown;
+}
+
+/**
+ *     const consent = useConsentRequest(api.oauth, useLocation().search);
+ *     if (consent.state.status === "ready") ... consent.approve(workspaceId)
+ */
+export function useConsentRequest<Choice = void>(
+  api: ConsentApi<Choice>,
+  search: string,
+): ConsentRequest<Choice> {
+  const query = search.replace(/^\?/, "");
+  const request = useQuery({
+    queryKey: ["@gusnips/react/oauth", "consent", query],
+    queryFn: () => api.describe(query),
+  });
+  const approval = useMutation({
+    mutationFn: (choice: Choice) => api.approve(query, choice),
+    onSuccess: (answer) => {
+      if (answer.ok) window.location.assign(answer.redirectTo);
+    },
+  });
+
+  // A refusal from approve (the request went stale between the two calls) outranks the view.
+  const answer = request.data;
+  const refusal =
+    approval.data?.ok === false ? approval.data : answer?.ok === false ? answer : null;
+  let state: ConsentState;
+  if (refusal) state = { status: "refused", refusal };
+  else if (answer?.ok === true) state = { status: "ready", view: answer };
+  else if (request.isError)
+    state = { status: "failed", error: request.error, retry: () => void request.refetch() };
+  else state = { status: "loading" };
+
+  return {
+    state,
+    approve: (choice) => approval.mutate(choice),
+    leaving: approval.isPending || approval.data?.ok === true,
+    approveError: approval.error,
+  };
+}
+
+export interface DeviceApi {
+  /** Your API's call to the server's `describeDevice`. */
+  describe(code: string): Promise<DeviceView | OAuthRefusal>;
+  /** Your API's call to `decideDevice`. */
+  decide(code: string, decision: "approve" | "deny"): Promise<{ ok: true } | OAuthRefusal>;
+}
+
+export type DeviceState =
+  /** Fewer than 8 letters so far, or one a code never uses (see `invalidLetter`). */
+  | { status: "typing" }
+  | { status: "loading" }
+  /** Unknown, expired or already decided: ask them to start again from the app. */
+  | { status: "refused"; refusal: OAuthRefusal }
+  | { status: "failed"; error: unknown; retry: () => void }
+  /**
+   * Show `view.userCode` and say: go on only if you started this sign-in yourself, just now, and
+   * this is the code on your screen. Somebody can run the real script and send a stranger the
+   * link, and that sentence is the only guard against it (RFC 8628 §5.4).
+   */
+  | { status: "ready"; view: DeviceView }
+  /** Done. Tell them to go back to the app, which carries on by itself. */
+  | { status: "approved" }
+  | { status: "denied" };
+
+export interface DeviceApproval {
+  state: DeviceState;
+  /** What the field shows, formatted as they type: `WDJB-MJ`. */
+  code: string;
+  setCode(input: string): void;
+  /** A typed letter no code uses: a vowel. Say so now, not after eight letters. */
+  invalidLetter: boolean;
+  approve(): void;
+  deny(): void;
+  deciding: boolean;
+  /** The decision did not answer. Show it beside the buttons; pressing again retries. */
+  decideError: unknown;
+}
+
+/** The server's alphabet: no vowels, so a code never spells a word. */
+const ALPHABET = "BCDFGHJKLMNPQRSTVWXZ";
+const LENGTH = 8;
+
+/** Upper case, letters only, at most 8, with the dash after the fourth: what the field shows. */
+export function formatUserCode(input: string): string {
+  const letters = input
+    .toUpperCase()
+    .replace(/[^A-Z]/g, "")
+    .slice(0, LENGTH);
+  return letters.length > 4 ? `${letters.slice(0, 4)}-${letters.slice(4)}` : letters;
+}
+
+/**
+ *     const device = useDeviceApproval(api.device, useLocation().search);
+ *     <input value={device.code} onChange={(e) => device.setCode(e.target.value)} />
+ *
+ * The link the script prints carries `?code=`, so the field usually starts full.
+ */
+export function useDeviceApproval(api: DeviceApi, search: string): DeviceApproval {
+  const [code, setTyped] = useState(() =>
+    formatUserCode(new URLSearchParams(search).get("code") ?? ""),
+  );
+  const letters = code.replace("-", "");
+  const invalidLetter = [...letters].some((letter) => !ALPHABET.includes(letter));
+  const complete = letters.length === LENGTH && !invalidLetter;
+
+  const decision = useMutation({
+    mutationFn: (choice: "approve" | "deny") => api.decide(letters, choice),
+  });
+  const decided = decision.data?.ok === true ? decision.variables : undefined;
+  const request = useQuery({
+    queryKey: ["@gusnips/react/oauth", "device", letters],
+    queryFn: () => api.describe(letters),
+    enabled: complete && decided === undefined,
+  });
+
+  const answer = request.data;
+  const refusal =
+    decision.data?.ok === false ? decision.data : answer?.ok === false ? answer : null;
+  let state: DeviceState;
+  if (decided !== undefined) state = { status: decided === "approve" ? "approved" : "denied" };
+  else if (!complete) state = { status: "typing" };
+  else if (refusal) state = { status: "refused", refusal };
+  else if (answer?.ok === true) state = { status: "ready", view: answer };
+  else if (request.isError)
+    state = { status: "failed", error: request.error, retry: () => void request.refetch() };
+  else state = { status: "loading" };
+
+  return {
+    state,
+    code,
+    setCode: (input) => {
+      decision.reset();
+      setTyped(formatUserCode(input));
+    },
+    invalidLetter,
+    approve: () => decision.mutate("approve"),
+    deny: () => decision.mutate("deny"),
+    deciding: decision.isPending,
+    decideError: decision.error,
+  };
+}

package/src/supabase-session.test.ts

@@ -12,6 +12,7 @@ import {
   isAuthOutage,
   parseAuthCallback,
   signOutEvenOffline,
+  signOutOtherDevices,
   supabaseAuthStorage,
   supabaseStorageKey,
   type SupabaseSessionAuth,
@@ -75,10 +76,11 @@ const unreachable: typeof fetch = async () => {
   throw new TypeError("fetch failed");
 };
 
+/** `paths` collects each request's path and query, so a test can read the scope `/logout` got. */
 function reachable(paths: string[] = []): typeof fetch {
   return async (input) => {
-    const { pathname } = new URL(input instanceof Request ? input.url : input);
-    paths.push(pathname);
+    const { pathname, search } = new URL(input instanceof Request ? input.url : input);
+    paths.push(pathname + search);
     if (pathname.endsWith("/token")) return Response.json(storedSession(now() + 3600));
     if (pathname.endsWith("/logout")) return new Response(null, { status: 204 });
     return Response.json({ msg: "not part of this test" }, { status: 404 });
@@ -204,7 +206,8 @@ describe("createSupabaseSessionAdapter", () => {
     const adapter = createSupabaseSessionAdapter(auth({ signOut }));
 
     await expect(adapter.signOut()).rejects.toBe(refusal);
-    expect(signOut).toHaveBeenCalledOnce();
+    // This device only: a token one device's API refused says nothing about the others.
+    expect(signOut).toHaveBeenCalledExactlyOnceWith({ scope: "local" });
   });
 
   it("with `stored`, rejects when auth never heard it, but the session has left", async () => {
@@ -273,19 +276,57 @@ describe("signOutEvenOffline", () => {
     expect(await sessionAfterReload(stored)).toBeNull();
   });
 
-  it("ends the session on the server too when auth answers", async () => {
+  it("ends this device's session on the server too when auth answers, and no other", async () => {
     const paths: string[] = [];
     const { stored, auth, signedOut } = await signedIn(now() + 3600, reachable(paths));
 
     const { error } = await signOutEvenOffline(auth, stored);
 
     expect(error).toBeNull();
-    expect(paths).toContain("/auth/v1/logout");
+    // auth-js's default, scope=global, would end the person's sessions on every device.
+    expect(paths).toContain("/auth/v1/logout?scope=local");
     expect(signedOut()).toBe(1);
     expect(await sessionAfterReload(stored)).toBeNull();
   });
 });
 
+describe("signOutOtherDevices", () => {
+  it("ends the other sessions and keeps this one", async () => {
+    const paths: string[] = [];
+    const { stored, auth, signedOut } = await signedIn(now() + 3600, reachable(paths));
+
+    const { error } = await signOutOtherDevices(auth);
+
+    expect(error).toBeNull();
+    expect(paths).toContain("/auth/v1/logout?scope=others");
+    expect(signedOut()).toBe(0);
+    expect(await sessionAfterReload(stored)).not.toBeNull();
+  });
+
+  it("keeps this device signed in and says why when auth cannot be reached", async () => {
+    const { stored, auth, signedOut } = await signedIn(now() + 3600);
+
+    const { error } = await signOutOtherDevices(auth);
+
+    expect(error).toBeInstanceOf(AuthRetryableFetchError);
+    expect(signedOut()).toBe(0);
+    expect(await sessionAfterReload(stored)).not.toBeNull();
+  });
+
+  it("gives up at the deadline instead of waiting out the refresh backoff", async () => {
+    vi.useFakeTimers();
+    const { stored, auth } = await signedIn(now() - 60);
+
+    const signingOut = signOutOtherDevices(auth);
+    await vi.advanceTimersByTimeAsync(SIGN_OUT_TIMEOUT_MS);
+    const { error } = await signingOut;
+
+    expect(error).toMatchObject({ message: expect.stringContaining(`${SIGN_OUT_TIMEOUT_MS} ms`) });
+    expect(await stored.storage.getItem(stored.storageKey)).not.toBeNull();
+    await vi.advanceTimersByTimeAsync(60_000);
+  });
+});
+
 describe("supabaseStorageKey", () => {
   it("names the key supabase-js picks when you set none", async () => {
     const storage = memoryStorage();

package/src/supabase-session.ts

@@ -156,11 +156,17 @@ function localStorageOrMemory(): SupportedStorage {
  *   it touches storage. This happens at every version, and it is the common case: a laptop that
  *   wakes up offline with a tab still open.
  * - Before 2.110.2, the token is still good but `/logout` gets no answer. `signOut()` returns
- *   before it removes anything. `scope: "local"` does not help, because it calls `/logout` too.
+ *   before it removes anything.
  *
  * Either way a reload reads the session and signs the person back in. On a shared computer, that
  * person is whoever sits down next. A screen that says "signed out" at that point is wrong.
  *
+ * It ends this device's session and no other: `signOut({ scope: "local" })`, which fails in both
+ * cases above too, because it calls `/logout` as well. auth-js's default is `"global"`, which ends
+ * every session the person has. Signing out of a laptop then signed them out of their phone, and a
+ * tab left open anywhere failed its next refresh with "Invalid Refresh Token: Refresh Token Not
+ * Found". To end the other sessions on purpose, use {@link signOutOtherDevices}.
+ *
  * Removing the key yourself is not enough on its own: nothing tells your `onAuthStateChange`
  * listeners or your other tabs, and auth-js's PKCE verifiers stay behind. So after removing it,
  * this calls `signOut({ scope: "local" })`. That call finds no session, skips `/logout`, and runs
@@ -173,7 +179,7 @@ function localStorageOrMemory(): SupportedStorage {
  *
  * It resolves once the stored session is gone. `error` is `null` when auth ended the session on the
  * server too. Otherwise it is the reason auth did not: its error, a thrown value or the deadline.
- * The session may still be live on the server and on other devices. `SIGNED_OUT` arrives once
+ * The session may still be live on the server. `SIGNED_OUT` arrives once
  * auth-js has finished with the first call: about 100 ms later from 2.108.2 on, and up to 22 s
  * later at 2.106.2. If your screen does not reload, clear your own store when this resolves instead
  * of waiting for the event.
@@ -181,6 +187,40 @@ function localStorageOrMemory(): SupportedStorage {
 export async function signOutEvenOffline(
   auth: Pick<SupabaseSessionAuth, "signOut">,
   { storage, storageKey }: SupabaseSessionStorage,
+): Promise<{ error: unknown }> {
+  const { error } = await withinSignOutDeadline(auth.signOut({ scope: "local" }));
+  if (error == null) return { error: null };
+  // From 2.110.2 on, auth-js has already removed the session when only `/logout` failed, and has
+  // already sent SIGNED_OUT. Going on would send it a second time.
+  if ((await storage.getItem(storageKey)) === null) return { error };
+  await storage.removeItem(storageKey);
+  // Not awaited: inside auth-js it can wait behind the first call, which may still be in its
+  // refresh backoff. The session is already out of storage, and storage is what a reload reads.
+  void auth.signOut({ scope: "local" }).catch(() => {});
+  return { error };
+}
+
+/**
+ * Ends the person's sessions on every other device and keeps this one signed in. For a "sign out
+ * of other devices" button in account settings: a phone that was lost, a computer left signed in.
+ *
+ * It resolves `{ error: null }` once auth has ended the other sessions. Otherwise `error` says why
+ * it did not: auth's error, a thrown value, or the deadline. This device is untouched either way,
+ * so the person is still signed in and can press the button again.
+ *
+ * Like {@link signOutEvenOffline}, it waits on auth for {@link SIGN_OUT_TIMEOUT_MS} at most, because
+ * offline with an expired token auth-js first sits in its refresh backoff. A deadline does not
+ * prove the other sessions are still live: auth may end them after this gave up.
+ */
+export function signOutOtherDevices(
+  auth: Pick<SupabaseSessionAuth, "signOut">,
+): Promise<{ error: unknown }> {
+  return withinSignOutDeadline(auth.signOut({ scope: "others" }));
+}
+
+/** `call`'s result, or the deadline as its error once {@link SIGN_OUT_TIMEOUT_MS} has passed. */
+async function withinSignOutDeadline(
+  call: Promise<{ error: unknown }>,
 ): Promise<{ error: unknown }> {
   let timer: ReturnType<typeof setTimeout> | undefined;
   const deadline = new Promise<{ error: unknown }>((resolve) => {
@@ -192,20 +232,12 @@ export async function signOutEvenOffline(
       SIGN_OUT_TIMEOUT_MS,
     );
   });
-  const { error } = await Promise.race([
-    auth.signOut().catch((thrown: unknown) => ({ error: thrown })),
+  const result = await Promise.race([
+    call.catch((thrown: unknown) => ({ error: thrown })),
     deadline,
   ]);
   clearTimeout(timer);
-  if (error == null) return { error: null };
-  // From 2.110.2 on, auth-js has already removed the session when only `/logout` failed, and has
-  // already sent SIGNED_OUT. Going on would send it a second time.
-  if ((await storage.getItem(storageKey)) === null) return { error };
-  await storage.removeItem(storageKey);
-  // Not awaited: inside auth-js it can wait behind the first call, which may still be in its
-  // refresh backoff. The session is already out of storage, and storage is what a reload reads.
-  void auth.signOut({ scope: "local" }).catch(() => {});
-  return { error };
+  return result;
 }
 
 /**
@@ -220,7 +252,8 @@ export async function signOutEvenOffline(
  * rejection means. It still rejects when auth did not end the session, but by then the session
  * has already left this device. And a sign-out auth has not answered within
  * {@link SIGN_OUT_TIMEOUT_MS} now rejects instead of hanging. Without `stored`, it is
- * `auth.signOut()` and rejects on that call's error, as before.
+ * `auth.signOut({ scope: "local" })` and rejects on that call's error. Either way it ends this
+ * device's session only: a token one device's API refused says nothing about the others.
  *
  * `stored` is optional here but not at a sign-out button. The API client signs out only after
  * auth has answered: a refresh auth refused, or a new token the API refused. So the network was up
@@ -247,7 +280,9 @@ export function createSupabaseSessionAdapter(
       }
     },
     signOut: async () => {
-      const { error } = stored ? await signOutEvenOffline(auth, stored) : await auth.signOut();
+      const { error } = stored
+        ? await signOutEvenOffline(auth, stored)
+        : await auth.signOut({ scope: "local" });
       if (error) throw error;
     },
   };