@gusnips/react 0.9.28 → 0.9.30

package/README.md

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

package/dist/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/keys.d.ts

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

package/dist/keys.d.ts.map

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

package/dist/keys.js

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

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAuB7C,+EAA+E;AAC/E,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,SAAS,CAAsB;IAExC,YAAY,SAA8B;QACxC,KAAK,CACH,SAAS,KAAK,QAAQ;YACpB,CAAC,CAAC,+HAA+H;YACjI,CAAC,CAAC,yHAAyH,CAC9H,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAyBD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,IAAI,QAAQ,GAAmC,EAAE,CAAC;IAClD,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAExC,oEAAoE;IACpE,SAAS,gBAAgB,CAAC,KAAwB;QAChD,KAAK,CAAC,cAAc,EAAE,CAAC;QACvB,yFAAyF;QACzF,KAAK,CAAC,WAAW,GAAG,EAAE,CAAC;IACzB,CAAC;IAED,SAAS,OAAO,CAAC,IAAoC;QACnD,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;QACtC,QAAQ,GAAG,IAAI,CAAC;QAChB,IAAI,SAAS,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YACnE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,MAAM,CAAC,gBAAgB,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;;gBAC1E,MAAM,CAAC,mBAAmB,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;QACpE,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,SAAS;YAAE,QAAQ,EAAE,CAAC;IAC/C,CAAC;IAED,qFAAqF;IACrF,KAAK,UAAU,MAAM,CAAI,SAA8B,EAAE,OAAyB;QAChF,IAAI,KAAK,KAAK,IAAI;YAChB,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,MAAM,OAAO,GAAG,UAAU,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,OAAO,EAAE,CAAC;QAC/B,IAAI,OAAO,KAAK,UAAU;YAAE,MAAM,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;QACtE,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,SAAS,OAAO,CAAC,EAAU;QACzB,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED,OAAO;QACL,QAAQ,CAAC,IAAI;YACX,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO;YAC3B,KAAK,GAAG,IAAI,CAAC;YACb,UAAU,EAAE,CAAC;YACb,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,OAAO;YAClB,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACxD,yFAAyF;YACzF,0FAA0F;YAC1F,8CAA8C;YAC9C,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC;gBACtC,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;YAC1F,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;YACxC,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO;YACtB,MAAM,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAChC,OAAO,CAAC,EAAE,CAAC,CAAC;QACd,CAAC;QACD,OAAO;QACP,WAAW,EAAE,GAAG,EAAE,CAAC,QAAQ;QAC3B,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,IAAI,GAAqB,EAAE,CAAC;AAElC,8EAA8E;AAC9E,MAAM,UAAU,aAAa,CAC3B,SAA+B;IAE/B,OAAO,oBAAoB,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AACtF,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":"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"}

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.30",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, stale-tab recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,14 @@
     "./commands": {
       "types": "./dist/commands.d.ts",
       "default": "./dist/commands.js"
+    },
+    "./oauth": {
+      "types": "./dist/oauth.d.ts",
+      "default": "./dist/oauth.js"
+    },
+    "./keys": {
+      "types": "./dist/keys.d.ts",
+      "default": "./dist/keys.js"
     }
   },
   "types": "./dist/index.d.ts",

package/src/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