@user-hub/auth 0.1.1 → 0.1.3

package/README.md

@@ -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,7 +169,7 @@ 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) |
 
@@ -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/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";
@@ -36,6 +37,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.1",
+  "version": "0.1.3",
   "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,9 +7,33 @@ 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.
 
-## The hub
+## Starting a new app
 
-Ask the human for the hub's URL. It is `HUB_URL` for `hub-user`, the `HUB_ISSUER` the app trusts and the `VITE_HUB_URL` its frontend uses.
+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`). Never pass `--admin-password` with a value you typed yourself.
+
+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:
+
+- `HUB_URL` in the app's `.env` or `.env.local`: read by `hub-user register` (**Register the app**). The human puts it there with the admin password.
+- `HUB_ISSUER` on the app's Convex deployment: `hub-user register` prints it for you (**Set the two values**).
+- `VITE_HUB_URL` in the app's frontend env: lets the dev server send you to the hub to sign in (**Wire it up**).
 
 ## Before you start: ask the human
 
@@ -31,10 +55,10 @@ You need four things. Ask for them; never guess.
    bun add @user-hub/auth
    ```
 
-2. **Register the app** from the app's repo root, with the secrets supplied as the human chose in step 3 above:
+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 "Voting" --prod https://app.example.com --dev http://localhost:3000
+   bunx hub-user register --name "<app name>" --prod https://app.example.com --dev http://localhost:3000
    ```
 
    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.
@@ -45,7 +69,7 @@ You need four things. Ask for them; never guess.
    - Convex: `bunx convex env set HUB_ISSUER '…'` and `bunx convex env set HUB_JWKS '…'` (on every deployment the app uses).
    - Other servers: their environment, same names.
 
-4. **Wire it up** with the key from step 2.
+4. **Wire it up** with the key from **Register the app**.
 
    Convex, `convex/auth.config.ts`:
 
@@ -90,6 +114,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: