@gusnips/react 0.9.28 → 0.9.29

package/README.md

@@ -689,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,
@@ -770,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":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.9.28",
+  "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,
+  };
+}