@user-hub/auth 0.1.2 → 0.1.4

package/README.md

@@ -39,10 +39,10 @@ HUB_ADMIN_PASSWORD=…
 Then, from your app's folder (`bunx` reads `.env` and `.env.local` automatically; with a secret manager, run it through that):
 
 ```sh
-bunx hub-user register --name "Your App" --prod https://your-app.com --dev http://localhost:3000
+bunx hub-user register --name "Your App" --new --prod https://your-app.com --dev http://localhost:3000
 ```
 
-It prints your **app key** (made from the name) and the values to set. Not deployed yet? Leave out `--prod`: you can develop, and badge scans start reaching the app once you add it. Run it again with the same `--name` to update the URLs; a URL left out keeps the registered one. Give every app its own name: the same name updates the same app. (A hub admin can do the same under **Apps** in the hub, and copy the values from **Setup**.)
+It prints your **app key** (made from the name) and the values to set. Not deployed yet? Leave out `--prod`: you can develop, and badge scans start reaching the app once you add it. Run it again with the same `--name` to update the URLs; a URL left out keeps the registered one. `--new` refuses to touch an app that already has that name, so you never take over someone else's; leave it out when updating your own app later. (A hub admin can do the same under **Apps** in the hub, and copy the values from **Setup**.)
 
 ### 3. Set the values
 
@@ -109,6 +109,17 @@ Run your dev server as usual and open it. With no token yet, it sends you to the
 - **Different port:** run `hub-user register` again with the new `--dev` URL. The hub only sends tokens to registered URLs.
 - **Production:** someone without a token sees "Scan your badge to sign in". Pass `signedOut={…}` to `<HubSignedIn>` to style that screen.
 
+## Sign out
+
+```tsx
+import { useHubSignOut } from "@user-hub/auth/react"; // also from /convex-react
+
+const signOut = useHubSignOut();
+<button onClick={signOut}>Sign out</button>
+```
+
+It forgets this app's token; other apps stay signed in. In production the person sees "Scan your badge to sign in". On a local dev server the hub opens so you can pick who to be next.
+
 ## Facilitator pages
 
 People are members or facilitators. Always check on the server, then hide what members cannot use:
@@ -158,9 +169,9 @@ Apps without Convex use `HubAuthProvider` and `HubSignedIn` from `@user-hub/auth
 | `@user-hub/auth/convex-react` | `ConvexHubAuthProvider` | For Convex apps, in place of `ConvexProvider`, inside `<body>`. Props: `client`, `app`, `hubUrl?` |
 | `@user-hub/auth/react` | `HubAuthProvider` | The same without Convex: `app`, `hubUrl?` |
 | both | `HubSignedIn` | Shows its children only when signed in. Props: `signedOut?`, `loading?` |
-| | `useHubUser()`, `useHubToken()` | The person (or null), the raw token (or null). Also from `/convex-react` |
+| | `useHubUser()`, `useHubToken()`, `useHubSignOut()` | The person (or null), the raw token (or null), a sign-out function. Also from `/convex-react` |
 | `@user-hub/auth/server` | `verifyHubToken(requestOrToken, { app })` | Checks a token anywhere else |
-| CLI | `hub-user register --name <name> [--prod <url>] [--dev <url>] [--hub <url>] [--json]` | Registers or updates the app (at least one URL) |
+| CLI | `hub-user register --name <name> [--prod <url>] [--dev <url>] [--new] [--hub <url>] [--json]` | Registers or updates the app (at least one URL); `--new` only creates, exit code 3 if the name is taken |
 
 ## Developing this package
 
@@ -171,4 +182,4 @@ bun run check      # Biome
 bun run build      # dist/: commit it
 ```
 
-Publish with `bun publish`: it builds and runs the tests first.
+Release with `just release patch` (or `minor` / `major`): it bumps the version, publishes to npm and pushes the commit and tag. See the comments in the `justfile`.

package/dist/cli.js

@@ -2,12 +2,14 @@
 
 // src/cli.ts
 import { parseArgs } from "node:util";
-var USAGE = `Usage: hub-user register --name <name> [--prod <url>] [--dev <url>] [--hub <url>] [--json]
+var USAGE = `Usage: hub-user register --name <name> [--prod <url>] [--dev <url>] [--new] [--hub <url>] [--json]
 
   --name   The app's name in the hub; its key comes from it (required)
   --prod   Where badge scans send people. Leave it out until the app is
            deployed: it can be developed, but not scheduled.
   --dev    Where developers open the app as a person, e.g. http://localhost:3000
+  --new    Only create a new app: if the name is taken, change nothing and
+           exit with code 3 so you can pick another name
   --hub    The hub's URL (default: HUB_URL)
   --json   Print JSON instead of text
 
@@ -30,6 +32,7 @@ var { values, positionals } = parseArgs({
     name: { type: "string" },
     hub: { type: "string" },
     json: { type: "boolean", default: false },
+    new: { type: "boolean", default: false },
     help: { type: "boolean", short: "h", default: false }
   }
 });
@@ -57,10 +60,18 @@ var response = await fetch(`${hub}/api/apps/register`, {
   body: JSON.stringify({
     name,
     ...values.prod !== undefined && { url: values.prod },
-    ...values.dev !== undefined && { devUrl: values.dev }
+    ...values.dev !== undefined && { devUrl: values.dev },
+    ...values.new && { createOnly: true }
   })
 }).catch((error) => fail(`could not reach ${hub}: ${error.message}`));
 var result = await response.json().catch(() => ({}));
+if (result.taken) {
+  if (values.json)
+    console.log(JSON.stringify(result, null, 2));
+  else
+    console.error(`hub-user: ${result.error}`);
+  process.exit(3);
+}
 if (!response.ok) {
   fail(result.error ?? `the hub answered ${response.status}`);
 }

package/dist/convex-react.d.ts

@@ -1,6 +1,6 @@
 import { type ConvexReactClient } from "convex/react";
 import { type HubAuthProviderProps } from "./react";
-export { HubSignedIn, useHubSession, useHubToken, useHubUser, } from "./react";
+export { HubSignedIn, useHubSession, useHubSignOut, useHubToken, useHubUser, } from "./react";
 export type { HubRole, HubUser } from "./token";
 /**
  * HubAuthProvider for apps on Convex: the hub token becomes the Convex

package/dist/convex-react.js

@@ -1,10 +1,11 @@
 import {
   HubAuthProvider2,
   HubSignedIn2,
+  useHubSignOut2,
   useHubSession2,
   useHubUser2,
   useHubToken2
-} from "./convex-7n6dqf5r.js";
+} from "./convex-zgnvvwvn.js";
 
 // src/convex-react.tsx
 import { ConvexProviderWithAuth } from "convex/react";
@@ -12,11 +13,20 @@ import { useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 function useConvexHubAuth() {
   const session = useHubSession2();
+  const signOut = useHubSignOut2();
   return useMemo(() => ({
     isLoading: session === undefined,
     isAuthenticated: Boolean(session),
-    fetchAccessToken: async () => session && session.user.expiresAt > Date.now() ? session.token : null
-  }), [session]);
+    fetchAccessToken: async ({
+      forceRefreshToken
+    }) => {
+      if (forceRefreshToken) {
+        signOut();
+        return null;
+      }
+      return session && session.user.expiresAt > Date.now() ? session.token : null;
+    }
+  }), [session, signOut]);
 }
 function ConvexHubAuthProvider({
   client,
@@ -36,6 +46,7 @@ export {
   ConvexHubAuthProvider,
   HubSignedIn2 as HubSignedIn,
   useHubSession2 as useHubSession,
+  useHubSignOut2 as useHubSignOut,
   useHubToken2 as useHubToken,
   useHubUser2 as useHubUser
 };

package/dist/{convex-7n6dqf5r.js → convex-zgnvvwvn.js}

@@ -1,6 +1,7 @@
 // src/react.tsx
 import {
   createContext,
+  useCallback,
   useContext,
   useEffect,
   useMemo,
@@ -41,7 +42,8 @@ var MAX_TIMEOUT_MS = 2 ** 31 - 1;
 var LOCAL_HOST = /^(localhost|127(\.\d{1,3}){3}|10(\.\d{1,3}){3}|192\.168(\.\d{1,3}){2}|172\.(1[6-9]|2\d|3[01])(\.\d{1,3}){2}|\[::1\]|[a-z0-9-]+\.local)$/i;
 var HubContext = createContext({
   session: undefined,
-  redirecting: false
+  redirecting: false,
+  signOut: () => {}
 });
 var storageKey = (app) => `user-hub-token:${app}`;
 function readStorage(key) {
@@ -95,7 +97,11 @@ function HubAuthProvider2({
       window.location.replace(`${hubUrl.replace(/\/+$/, "")}/open/${encodeURIComponent(app)}`);
     }
   }, [redirecting, hubUrl, app]);
-  const state = useMemo(() => ({ session, redirecting }), [session, redirecting]);
+  const signOut = useCallback(() => {
+    writeStorage(storageKey(app), null);
+    setSession(null);
+  }, [app]);
+  const state = useMemo(() => ({ session, redirecting, signOut }), [session, redirecting, signOut]);
   return /* @__PURE__ */ jsx(HubContext.Provider, {
     value: state,
     children
@@ -117,6 +123,9 @@ function HubSignedIn2({
     return loading;
   return session ? children : signedOut;
 }
+function useHubSignOut2() {
+  return useContext(HubContext).signOut;
+}
 function useHubSession2() {
   return useContext(HubContext).session;
 }
@@ -128,4 +137,4 @@ function useHubToken2() {
   return useHubSession2()?.token ?? null;
 }
 
-export { HubAuthProvider2, HubSignedIn2, useHubSession2, useHubUser2, useHubToken2 };
+export { HubAuthProvider2, HubSignedIn2, useHubSignOut2, useHubSession2, useHubUser2, useHubToken2 };

package/dist/react.d.ts

@@ -22,6 +22,12 @@ export declare function HubSignedIn({ children, signedOut, loading, }: {
     signedOut?: ReactNode;
     loading?: ReactNode;
 }): ReactNode;
+/**
+ * Signs the person out of this app: `const signOut = useHubSignOut()`. They
+ * need to scan their badge again (or, on a dev server, pick a person at the
+ * hub). Other apps stay signed in.
+ */
+export declare function useHubSignOut(): () => void;
 /** The current session: undefined while loading, null when signed out. */
 export declare function useHubSession(): HubSession | null | undefined;
 /** The signed-in person, or null. */

package/dist/react.js

@@ -1,14 +1,16 @@
 import {
   HubAuthProvider2,
   HubSignedIn2,
+  useHubSignOut2,
   useHubSession2,
   useHubUser2,
   useHubToken2
-} from "./convex-7n6dqf5r.js";
+} from "./convex-zgnvvwvn.js";
 export {
   HubAuthProvider2 as HubAuthProvider,
   HubSignedIn2 as HubSignedIn,
   useHubSession2 as useHubSession,
+  useHubSignOut2 as useHubSignOut,
   useHubToken2 as useHubToken,
   useHubUser2 as useHubUser
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@user-hub/auth",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Sign people in from User Hub badges: Convex auth config, React provider, server verification and the hub-user CLI.",
   "type": "module",
   "files": [
@@ -51,6 +51,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
+    "@happy-dom/global-registrator": "^20.14.5",
     "@types/bun": "^1.4.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",

package/skills/user-hub-auth/SKILL.md

@@ -7,6 +7,26 @@ description: Sign people into an app from their User Hub badge. Use when an app
 
 People at a workshop scan a printed QR badge. The hub sends them to whichever app is live, signed in, with a token in the URL fragment (`#token=…`) that only that app accepts. This package turns that token into a signed-in person. The app keeps its own data, keyed on the person's hub id.
 
+## Starting a new app
+
+If there is no app yet, don't build one by hand: scaffold one with sign-in already wired (TanStack Start + Convex, sign-in and sign-out, a facilitator page, `CLAUDE.md` and this skill):
+
+```sh
+bun create @user-hub my-app
+```
+
+In a terminal it asks for the hub's URL and admin password and saves them to the new app's `.env.local`. As an agent you never handle the password, so either ask the human to run it, or run it only when `HUB_URL` and `HUB_ADMIN_PASSWORD` are already in the environment (for example `infisical run -- bun create @user-hub my-app`).
+
+Then:
+
+```sh
+cd my-app
+bun run setup    # Convex project, hub registration, HUB_ISSUER and HUB_JWKS, once
+bun run dev      # http://localhost:3000
+```
+
+That covers every step below; read on only to add User Hub to an existing app or to change the wiring.
+
 ## The hub's URL
 
 The hub has one address, for example `https://hub.example.com`. The human gives it to you; you need it in three places, all with the same value:
@@ -38,9 +58,11 @@ You need four things. Ask for them; never guess.
 2. **Register the app** from the app's repo root, with `HUB_URL` and the password supplied the way the human chose in question 3 above:
 
    ```sh
-   bunx hub-user register --name "<app name>" --prod https://app.example.com --dev http://localhost:3000
+   bunx hub-user register --name "<app name>" --new --prod https://app.example.com --dev http://localhost:3000
    ```
 
+   `--new` makes sure you never take over another app: if the name is already taken, nothing changes and it exits with code 3 and "already exists". Then ask the human for another name and run it again. Drop `--new` only when updating this app's own registration later.
+
    Leave out `--prod` if the app is not deployed yet. Running it again with the same `--name` updates the URLs; a URL left out keeps the registered one. If it fails with "set HUB_URL", "set HUB_ADMIN_PASSWORD" or a wrong password, stop and ask the human; do not work around it.
 
    It prints the app **key** (made from the name), `HUB_ISSUER` and `HUB_JWKS` (server side) and `VITE_HUB_URL` (frontend). Add `--json` to parse them.
@@ -94,6 +116,17 @@ Run the app as usual (`bun run dev`) on the `--dev` URL you registered. Opening
 - If the dev server runs on another port, run `hub-user register` again with the same `--name` and the new `--dev` URL: the hub only sends tokens back to registered URLs.
 - This only happens on local addresses (localhost, 127.x, 10.x, 172.16-31.x, 192.168.x, *.local). In production a person without a token sees "Scan your badge to sign in".
 
+## Sign out
+
+Use `useHubSignOut()` from the same entry point as the provider; never clear storage or tokens yourself.
+
+```tsx
+const signOut = useHubSignOut();
+<button onClick={signOut}>Sign out</button>
+```
+
+It forgets this app's token only. In production the person then sees the signed-out screen and scans their badge again; on a local dev server the hub opens to pick another person.
+
 ## Facilitator pages
 
 People are either `"member"` or `"facilitator"`, set in the hub. To give facilitators their own page or actions: