@user-hub/auth 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# @user-hub/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> [!NOTE]
+> **Private beta.** This package needs a User Hub, which is not public yet. Until then it is only useful to teams already running one.
+
+Sign people into your app with their User Hub badge. People scan a printed QR code and arrive in your app already signed in. You get `{ id, name, team, role }` and build no sign-in screens, passwords or sessions.
+
+Works with Convex apps, React frontends and any server that can check a token.
+
+## How it works
+
+1. A person scans their badge. The hub sends them to your app with a token in the URL: `https://your-app.com/#token=…`.
+2. The provider takes the token out of the address bar and keeps it in the browser, separately for each app.
+3. Convex (or your server) checks the token with the hub's public key. A token is only accepted by the app it was made for, and lasts 4 hours.
+4. Your app stores its own data under the person's `id`.
+
+## Quick start
+
+### 1. Install
+
+```sh
+bun add @user-hub/auth
+```
+
+Using a coding agent? The package ships an agent skill at `node_modules/@user-hub/auth/skills/user-hub-auth`; point your agent to it.
+
+### 2. Register your app with the hub
+
+Ask the hub's admin for its URL and the admin password, and put both in your app's `.env` or `.env.local` (keep it gitignored), or your secret manager:
+
+```sh
+HUB_URL=https://hub.example.com
+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
+```
+
+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**.)
+
+### 3. Set the values
+
+On your Convex deployment (every deployment you use):
+
+```sh
+bunx convex env set HUB_ISSUER '…'
+bunx convex env set HUB_JWKS '…'
+```
+
+In your frontend env: `VITE_HUB_URL`, the same value as `HUB_URL`.
+
+### 4. Wire it up
+
+`convex/auth.config.ts`:
+
+```ts
+import type { AuthConfig } from "convex/server";
+import { hubAuth } from "@user-hub/auth/convex";
+
+export default { providers: [hubAuth({ app: "your-app-key" })] } satisfies AuthConfig;
+```
+
+In place of `ConvexProvider`, **inside the root document's `<body>`** (in TanStack Start, the root route's shell component; never the router's `Wrap` or anything outside `<html>`):
+
+```tsx
+import { ConvexHubAuthProvider, HubSignedIn } from "@user-hub/auth/convex-react";
+
+<body>
+  <ConvexHubAuthProvider client={convex} app="your-app-key" hubUrl={import.meta.env.VITE_HUB_URL}>
+    <HubSignedIn>{children}</HubSignedIn>
+  </ConvexHubAuthProvider>
+  <Scripts />
+</body>
+```
+
+The provider always renders its children. `<HubSignedIn>` shows them only to a signed-in person, and "Scan your badge to sign in" otherwise; anything outside it shows to everyone.
+
+### 5. Use the person
+
+```tsx
+import { useHubUser } from "@user-hub/auth/react"; // also exported by /convex-react
+
+const me = useHubUser(); // { id, name, team, role }
+```
+
+```ts
+import { requireHubUser } from "@user-hub/auth/convex";
+
+export const myVotes = query({
+  args: {},
+  handler: async (ctx) => {
+    const me = await requireHubUser(ctx); // throws when signed out
+    return await ctx.db.query("votes").withIndex("by_person", (q) => q.eq("personId", me.id)).take(50);
+  },
+});
+```
+
+## Working on your app locally
+
+Run your dev server as usual and open it. With no token yet, it sends you to the hub, where you pick who to be (the admin password is asked once per browser), and brings you back signed in. You stay signed in for 4 hours, across reloads and restarts.
+
+- **Switch person:** open `<hub>/open/<your-app-key>`.
+- **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.
+
+## Facilitator pages
+
+People are members or facilitators. Always check on the server, then hide what members cannot use:
+
+```ts
+import { requireFacilitator } from "@user-hub/auth/convex";
+
+export const closeVoting = mutation({
+  args: {},
+  handler: async (ctx) => {
+    await requireFacilitator(ctx); // throws for members
+    // …
+  },
+});
+```
+
+```tsx
+const me = useHubUser();
+if (me?.role !== "facilitator") return <p>This page is for facilitators.</p>;
+```
+
+Hiding a page does not protect it: the server check does.
+
+## Not using Convex?
+
+Send the token to your server and check it there:
+
+```tsx
+const token = useHubToken();
+fetch("/api/thing", { headers: { Authorization: `Bearer ${token}` } });
+```
+
+```ts
+import { verifyHubToken } from "@user-hub/auth/server";
+
+const me = await verifyHubToken(request, { app: "your-app-key" }); // reads HUB_ISSUER and HUB_JWKS
+```
+
+Apps without Convex use `HubAuthProvider` and `HubSignedIn` from `@user-hub/auth/react`, in the same place, and do not need Convex installed.
+
+## API
+
+| Import | Export | What |
+|---|---|---|
+| `@user-hub/auth/convex` | `hubAuth({ app })` | The Convex auth provider, from `HUB_ISSUER` and `HUB_JWKS` |
+| | `getHubUser(ctx)`, `requireHubUser(ctx)`, `requireFacilitator(ctx)` | The person in Convex functions: or null, or throw |
+| `@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` |
+| `@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) |
+
+## Developing this package
+
+```sh
+bun install
+bun test           # unit tests
+bun run check      # Biome
+bun run build      # dist/: commit it
+```
+
+Publish with `bun publish`: it builds and runs the tests first.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+
+// src/cli.ts
+import { parseArgs } from "node:util";
+var USAGE = `Usage: hub-user register --name <name> [--prod <url>] [--dev <url>] [--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
+  --hub    The hub's URL (default: HUB_URL)
+  --json   Print JSON instead of text
+
+At least one of --prod and --dev is needed. A URL left out on a later run keeps
+the registered one.
+
+Needs HUB_URL and HUB_ADMIN_PASSWORD in the environment (.env and .env.local
+are read automatically). Running it again with the same
+name updates that app.`;
+function fail(message) {
+  console.error(`hub-user: ${message}`);
+  process.exit(1);
+}
+var { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  allowPositionals: true,
+  options: {
+    prod: { type: "string" },
+    dev: { type: "string" },
+    name: { type: "string" },
+    hub: { type: "string" },
+    json: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false }
+  }
+});
+if (values.help || positionals[0] !== "register") {
+  console.log(USAGE);
+  process.exit(values.help ? 0 : 1);
+}
+var hub = (values.hub ?? process.env.HUB_URL)?.replace(/\/+$/, "");
+var password = process.env.HUB_ADMIN_PASSWORD;
+var name = values.name?.trim();
+if (!hub)
+  fail("set HUB_URL (in .env or .env.local) or pass --hub");
+if (!password)
+  fail("set HUB_ADMIN_PASSWORD (in .env or .env.local)");
+if (!values.prod && !values.dev)
+  fail("pass --prod <url>, --dev <url> or both");
+if (!name)
+  fail("pass --name <name>, the app's name in the hub");
+var response = await fetch(`${hub}/api/apps/register`, {
+  method: "POST",
+  headers: {
+    Authorization: `Bearer ${password}`,
+    "Content-Type": "application/json"
+  },
+  body: JSON.stringify({
+    name,
+    ...values.prod !== undefined && { url: values.prod },
+    ...values.dev !== undefined && { devUrl: values.dev }
+  })
+}).catch((error) => fail(`could not reach ${hub}: ${error.message}`));
+var result = await response.json().catch(() => ({}));
+if (!response.ok) {
+  fail(result.error ?? `the hub answered ${response.status}`);
+}
+if (values.json) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(`Registered "${name}" with key: ${result.key}
+
+Environment (Convex deployment, or the app's server):
+HUB_ISSUER=${result.env.HUB_ISSUER}
+HUB_JWKS=${result.env.HUB_JWKS}
+
+For Convex:
+bunx convex env set HUB_ISSUER '${result.env.HUB_ISSUER}'
+bunx convex env set HUB_JWKS '${result.env.HUB_JWKS}'
+
+Frontend (the dev server sends you to the hub to pick who to be):
+VITE_HUB_URL=${result.hubUrl}
+
+Then use the key in code: hubAuth({ app: "${result.key}" }) and <ConvexHubAuthProvider app="${result.key}" hubUrl={import.meta.env.VITE_HUB_URL} client={convex}>`);
+}

package/dist/convex-7n6dqf5r.js

@@ -0,0 +1,131 @@
+// src/react.tsx
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState
+} from "react";
+
+// src/token.ts
+function decodeSegment(segment) {
+  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  return JSON.parse(atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, "=")));
+}
+function readClaims(token) {
+  try {
+    const payload = decodeSegment(token.split(".")[1] ?? "");
+    if (typeof payload.sub !== "string" || typeof payload.exp !== "number" || typeof payload.aud !== "string") {
+      return null;
+    }
+    return {
+      id: payload.sub,
+      name: payload.name,
+      team: payload.team,
+      role: payload.role === "facilitator" ? "facilitator" : "member",
+      app: payload.aud,
+      expiresAt: payload.exp * 1000
+    };
+  } catch {
+    return null;
+  }
+}
+function sessionFor(token, app, now = Date.now()) {
+  const user = token ? readClaims(token) : null;
+  return token && user && user.app === app && user.expiresAt > now ? { token, user } : null;
+}
+
+// src/react.tsx
+import { jsx } from "react/jsx-runtime";
+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
+});
+var storageKey = (app) => `user-hub-token:${app}`;
+function readStorage(key) {
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function writeStorage(key, token) {
+  try {
+    if (token)
+      window.localStorage.setItem(key, token);
+    else
+      window.localStorage.removeItem(key);
+  } catch {}
+}
+function loadSession(app) {
+  const hash = new URLSearchParams(window.location.hash.slice(1));
+  const fromUrl = hash.get("token");
+  if (fromUrl) {
+    hash.delete("token");
+    const rest = hash.toString();
+    window.history.replaceState(window.history.state, "", `${window.location.pathname}${window.location.search}${rest ? `#${rest}` : ""}`);
+  }
+  const session = sessionFor(fromUrl, app) ?? sessionFor(readStorage(storageKey(app)), app);
+  writeStorage(storageKey(app), session?.token ?? null);
+  return session;
+}
+function HubAuthProvider2({
+  app,
+  hubUrl,
+  children
+}) {
+  const [session, setSession] = useState();
+  const redirecting = session === null && Boolean(hubUrl) && typeof window !== "undefined" && LOCAL_HOST.test(window.location.hostname);
+  useEffect(() => {
+    setSession(loadSession(app));
+  }, [app]);
+  useEffect(() => {
+    if (!session)
+      return;
+    const id = setTimeout(() => {
+      writeStorage(storageKey(app), null);
+      setSession(null);
+    }, Math.min(session.user.expiresAt - Date.now(), MAX_TIMEOUT_MS));
+    return () => clearTimeout(id);
+  }, [session, app]);
+  useEffect(() => {
+    if (redirecting && hubUrl) {
+      window.location.replace(`${hubUrl.replace(/\/+$/, "")}/open/${encodeURIComponent(app)}`);
+    }
+  }, [redirecting, hubUrl, app]);
+  const state = useMemo(() => ({ session, redirecting }), [session, redirecting]);
+  return /* @__PURE__ */ jsx(HubContext.Provider, {
+    value: state,
+    children
+  });
+}
+function DefaultSignedOut() {
+  return /* @__PURE__ */ jsx("p", {
+    style: { padding: "2rem", textAlign: "center" },
+    children: "Scan your badge to sign in."
+  });
+}
+function HubSignedIn2({
+  children,
+  signedOut = /* @__PURE__ */ jsx(DefaultSignedOut, {}),
+  loading = null
+}) {
+  const { session, redirecting } = useContext(HubContext);
+  if (session === undefined || redirecting)
+    return loading;
+  return session ? children : signedOut;
+}
+function useHubSession2() {
+  return useContext(HubContext).session;
+}
+function useHubUser2() {
+  const user = useHubSession2()?.user;
+  return useMemo(() => user ? { id: user.id, name: user.name, team: user.team, role: user.role } : null, [user]);
+}
+function useHubToken2() {
+  return useHubSession2()?.token ?? null;
+}
+
+export { HubAuthProvider2, HubSignedIn2, useHubSession2, useHubUser2, useHubToken2 };

package/dist/convex-react.d.ts

@@ -0,0 +1,13 @@
+import { type ConvexReactClient } from "convex/react";
+import { type HubAuthProviderProps } from "./react";
+export { HubSignedIn, useHubSession, useHubToken, useHubUser, } from "./react";
+export type { HubRole, HubUser } from "./token";
+/**
+ * HubAuthProvider for apps on Convex: the hub token becomes the Convex
+ * identity. Use it in place of ConvexProvider, with the same client, inside
+ * the root document's <body>. Always renders its children; wrap signed-in
+ * content in <HubSignedIn>.
+ */
+export declare function ConvexHubAuthProvider({ client, children, ...props }: HubAuthProviderProps & {
+    client: ConvexReactClient;
+}): import("react").JSX.Element;

package/dist/convex-react.js

@@ -0,0 +1,41 @@
+import {
+  HubAuthProvider2,
+  HubSignedIn2,
+  useHubSession2,
+  useHubUser2,
+  useHubToken2
+} from "./convex-7n6dqf5r.js";
+
+// src/convex-react.tsx
+import { ConvexProviderWithAuth } from "convex/react";
+import { useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+function useConvexHubAuth() {
+  const session = useHubSession2();
+  return useMemo(() => ({
+    isLoading: session === undefined,
+    isAuthenticated: Boolean(session),
+    fetchAccessToken: async () => session && session.user.expiresAt > Date.now() ? session.token : null
+  }), [session]);
+}
+function ConvexHubAuthProvider({
+  client,
+  children,
+  ...props
+}) {
+  return /* @__PURE__ */ jsx(HubAuthProvider2, {
+    ...props,
+    children: /* @__PURE__ */ jsx(ConvexProviderWithAuth, {
+      client,
+      useAuth: useConvexHubAuth,
+      children
+    })
+  });
+}
+export {
+  ConvexHubAuthProvider,
+  HubSignedIn2 as HubSignedIn,
+  useHubSession2 as useHubSession,
+  useHubToken2 as useHubToken,
+  useHubUser2 as useHubUser
+};

package/dist/convex.d.ts

@@ -0,0 +1,31 @@
+import type { Auth, AuthConfig } from "convex/server";
+import type { HubUser } from "./token";
+export type { HubRole, HubUser } from "./token";
+type Provider = AuthConfig["providers"][number];
+/**
+ * The Convex auth provider for hub tokens. In `convex/auth.config.ts`:
+ *
+ *   export default { providers: [hubAuth({ app: "voting" })] } satisfies AuthConfig;
+ *
+ * Reads HUB_ISSUER and HUB_JWKS from the Convex deployment's environment
+ * (`bunx hub-user register` prints both). Then `ctx.auth.getUserIdentity()`
+ * returns the person: `subject` is their hub id, plus `name`, `team`, `role`.
+ */
+export declare function hubAuth({ app }: {
+    app: string;
+}): Provider;
+/**
+ * The signed-in person in a Convex query, mutation or action, or null.
+ * `id` is their hub id: key the app's data on it.
+ */
+export declare function getHubUser(ctx: {
+    auth: Auth;
+}): Promise<HubUser | null>;
+/** The signed-in person; throws "Sign in with your badge" otherwise. */
+export declare function requireHubUser(ctx: {
+    auth: Auth;
+}): Promise<HubUser>;
+/** A signed-in facilitator; throws for anyone else. */
+export declare function requireFacilitator(ctx: {
+    auth: Auth;
+}): Promise<HubUser>;

package/dist/convex.js

@@ -0,0 +1,48 @@
+// src/convex.ts
+import { ConvexError } from "convex/values";
+function hubAuth({ app }) {
+  const issuer = process.env.HUB_ISSUER;
+  const jwks = process.env.HUB_JWKS;
+  if (!issuer || !jwks) {
+    throw new Error("Set HUB_ISSUER and HUB_JWKS on this Convex deployment: run `bunx hub-user register`");
+  }
+  return {
+    type: "customJwt",
+    applicationID: app,
+    issuer,
+    jwks,
+    algorithm: "ES256"
+  };
+}
+async function getHubUser(ctx) {
+  const identity = await ctx.auth.getUserIdentity();
+  if (!identity) {
+    return null;
+  }
+  return {
+    id: identity.subject,
+    name: typeof identity.name === "string" ? identity.name : undefined,
+    team: typeof identity.team === "string" ? identity.team : undefined,
+    role: identity.role === "facilitator" ? "facilitator" : "member"
+  };
+}
+async function requireHubUser(ctx) {
+  const user = await getHubUser(ctx);
+  if (!user) {
+    throw new ConvexError("Sign in with your badge");
+  }
+  return user;
+}
+async function requireFacilitator(ctx) {
+  const user = await requireHubUser(ctx);
+  if (user.role !== "facilitator") {
+    throw new ConvexError("Only facilitators can do this");
+  }
+  return user;
+}
+export {
+  getHubUser,
+  hubAuth,
+  requireFacilitator,
+  requireHubUser
+};

package/dist/react.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode } from "react";
+import { type HubSession, type HubUser } from "./token";
+export type { HubRole, HubUser } from "./token";
+export type HubAuthProviderProps = {
+    app: string;
+    hubUrl?: string;
+    children: ReactNode;
+};
+/**
+ * Provides the signed-in person to the app. Always renders its children:
+ * put it inside the root document's <body>, and use <HubSignedIn> to decide
+ * what to show. Apps on Convex use ConvexHubAuthProvider instead.
+ */
+export declare function HubAuthProvider({ app, hubUrl, children, }: HubAuthProviderProps): import("react").JSX.Element;
+/**
+ * Shows its children only to a signed-in person. Otherwise `signedOut`
+ * ("Scan your badge to sign in" by default), or `loading` while the session is
+ * being read or a dev server is on its way to the hub.
+ */
+export declare function HubSignedIn({ children, signedOut, loading, }: {
+    children: ReactNode;
+    signedOut?: ReactNode;
+    loading?: ReactNode;
+}): ReactNode;
+/** The current session: undefined while loading, null when signed out. */
+export declare function useHubSession(): HubSession | null | undefined;
+/** The signed-in person, or null. */
+export declare function useHubUser(): HubUser | null;
+/**
+ * The raw token, for apps whose own server checks it with verifyHubToken:
+ * send it as `Authorization: Bearer <token>`.
+ */
+export declare function useHubToken(): string | null;

package/dist/react.js

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

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import type { HubUser } from "./token";
+export type { HubRole, HubUser } from "./token";
+type Options = {
+    app: string;
+    issuer?: string;
+    jwks?: string;
+};
+/**
+ * For servers that are not Convex. Pass the request (token in an
+ * `Authorization: Bearer` header) or the token itself. Returns the person, or
+ * throws when the token is missing, expired, forged or meant for another app.
+ */
+export declare function verifyHubToken(input: Request | string, { app, issuer, jwks, }: Options): Promise<HubUser>;

package/dist/server.js

@@ -0,0 +1,54 @@
+// src/server.ts
+import {
+  createLocalJWKSet,
+  createRemoteJWKSet,
+  jwtVerify
+} from "jose";
+var keySets = new Map;
+function keySet(jwks, issuer) {
+  const source = jwks ?? `${issuer}/.well-known/jwks.json`;
+  let keys = keySets.get(source);
+  if (!keys) {
+    if (source.startsWith("data:")) {
+      const json = Buffer.from(source.split(",")[1] ?? "", "base64").toString();
+      keys = createLocalJWKSet(JSON.parse(json));
+    } else {
+      keys = createRemoteJWKSet(new URL(source));
+    }
+    keySets.set(source, keys);
+  }
+  return keys;
+}
+function bearer(input) {
+  if (typeof input === "string")
+    return input;
+  const header = input.headers.get("authorization") ?? "";
+  return header.startsWith("Bearer ") ? header.slice("Bearer ".length) : "";
+}
+async function verifyHubToken(input, {
+  app,
+  issuer = process.env.HUB_ISSUER,
+  jwks = process.env.HUB_JWKS
+}) {
+  if (!issuer) {
+    throw new Error("Set HUB_ISSUER: run `bunx hub-user register`");
+  }
+  const token = bearer(input);
+  if (!token) {
+    throw new Error("No hub token");
+  }
+  const { payload } = await jwtVerify(token, keySet(jwks, issuer), {
+    issuer,
+    audience: app,
+    algorithms: ["ES256"]
+  });
+  return {
+    id: payload.sub,
+    name: payload.name,
+    team: payload.team,
+    role: payload.role === "facilitator" ? "facilitator" : "member"
+  };
+}
+export {
+  verifyHubToken
+};

package/dist/token.d.ts

@@ -0,0 +1,17 @@
+export type HubRole = "member" | "facilitator";
+export type HubUser = {
+    id: string;
+    name?: string;
+    team?: string;
+    role: HubRole;
+};
+export type HubClaims = HubUser & {
+    app: string;
+    expiresAt: number;
+};
+export declare function readClaims(token: string): HubClaims | null;
+export type HubSession = {
+    token: string;
+    user: HubClaims;
+};
+export declare function sessionFor(token: string | null, app: string, now?: number): HubSession | null;

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@user-hub/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Sign people in from User Hub badges: Convex auth config, React provider, server verification and the hub-user CLI.",
+  "type": "module",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "bin": {
+    "hub-user": "./dist/cli.js"
+  },
+  "exports": {
+    "./convex": {
+      "types": "./dist/convex.d.ts",
+      "default": "./dist/convex.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./convex-react": {
+      "types": "./dist/convex-react.d.ts",
+      "default": "./dist/convex-react.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/convex.ts src/react.tsx src/convex-react.tsx src/server.ts src/cli.ts --outdir dist --target node --format esm --splitting --packages external && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "check": "biome check",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun test"
+  },
+  "peerDependencies": {
+    "convex": ">=1.25.0",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "convex": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "jose": "^6.2.12"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@types/bun": "^1.4.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "convex": "^1.46.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "user-hub",
+    "auth",
+    "badge",
+    "qr",
+    "convex",
+    "react"
+  ]
+}

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

@@ -0,0 +1,135 @@
+---
+name: user-hub-auth
+description: Sign people into an app from their User Hub badge. Use when an app needs User Hub auth (workshop badges, QR sign-in, hubAuth, ConvexHubAuthProvider, HubAuthProvider, HubSignedIn, useHubUser, verifyHubToken, hub-user register), or when asked to connect an app to the hub. Never hand-roll login, passwords or token checks for these apps.
+---
+
+# User Hub auth
+
+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
+
+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.
+
+## Before you start: ask the human
+
+You need four things. Ask for them; never guess.
+
+1. **The app's name** in the hub, unique to this app (the same name updates the same app, and apps copied from a template often share a package name).
+2. **Its local URL** (usually `http://localhost:3000`) and **its production URL** if it is deployed. Without a production URL the app can be developed but not scheduled, so badge scans never reach it; add it later by running register again with `--prod`.
+3. **Where `HUB_URL` and `HUB_ADMIN_PASSWORD` are.** You do not have the password, and you must never ask for it in chat, write it into a file yourself, commit it or print it. Ask the human which of these applies:
+   - **`.env` or `.env.local`** in the app's repo (must be gitignored): the human adds `HUB_URL=…` and `HUB_ADMIN_PASSWORD=…` themselves. `bunx hub-user` reads `.env` and `.env.local` automatically.
+   - **Infisical** (or another secret manager): run the command through it, for example `infisical run -- bunx hub-user register …`.
+   - **The human runs the command** and pastes you only the output, which contains no secrets.
+4. **Which Convex deployments** the app uses (dev, prod), so the values go on each.
+
+## Steps
+
+1. **Install:**
+
+   ```sh
+   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:
+
+   ```sh
+   bunx hub-user register --name "Voting" --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.
+
+   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.
+
+3. **Set the two values** where tokens are checked:
+   - 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.
+
+   Convex, `convex/auth.config.ts`:
+
+   ```ts
+   import type { AuthConfig } from "convex/server";
+   import { hubAuth } from "@user-hub/auth/convex";
+
+   export default { providers: [hubAuth({ app: "<key>" })] } satisfies AuthConfig;
+   ```
+
+   The provider replaces `ConvexProvider` (keep the same `ConvexReactClient`). Set `VITE_HUB_URL` (the hub's URL) in the app's frontend env.
+
+   **Where it goes:** inside the root document's `<body>`, around the page content. In TanStack Start that is the root route's shell component (`src/routes/__root.tsx`); in a Vite SPA, around `<App />`; in Next.js, inside `<body>` in the root layout. **Never** in the router's `Wrap`, or anywhere outside `<html>`.
+
+   ```tsx
+   import { ConvexHubAuthProvider, HubSignedIn } from "@user-hub/auth/convex-react";
+
+   <body>
+     <ConvexHubAuthProvider
+       client={convex}
+       app="<key>"
+       hubUrl={import.meta.env.VITE_HUB_URL}
+     >
+       <HubSignedIn>{children}</HubSignedIn>
+     </ConvexHubAuthProvider>
+     <Scripts />
+   </body>
+   ```
+
+   The provider always renders its children; `<HubSignedIn>` shows them only to a signed-in person. Without a valid token it shows "Scan your badge to sign in": pass `signedOut={…}` to style that screen and `loading={…}` for the first render. Anything outside `<HubSignedIn>` (a public landing page, say) shows to everyone. Apps without Convex use `HubAuthProvider` and `HubSignedIn` from `@user-hub/auth/react`, with the same props minus `client`.
+
+5. **Use the person.**
+   - In components: `const me = useHubUser()` gives `{ id, name, team, role }`.
+   - In Convex functions: `const me = await requireHubUser(ctx)` gives the same `{ id, name, team, role }` (see Facilitator pages).
+   - Not Convex: wrap the app in `HubAuthProvider` and `HubSignedIn` (`@user-hub/auth/react`), send `useHubToken()` as `Authorization: Bearer <token>`, and check it on the server with `await verifyHubToken(request, { app: "<key>" })` from `@user-hub/auth/server`.
+
+## Your dev server
+
+Run the app as usual (`bun run dev`) on the `--dev` URL you registered. Opening it with no token sends the browser to the hub (admin password once per browser), where you pick who to be; the hub sends you back signed in as them. The token is kept for 4 hours across reloads and restarts, then the same thing happens again.
+
+- To switch person: open `<hub>/open/<key>` and pick someone else.
+- 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".
+
+## Facilitator pages
+
+People are either `"member"` or `"facilitator"`, set in the hub. To give facilitators their own page or actions:
+
+- **Protect the data on the server, always.** In Convex functions use the helpers from `@user-hub/auth/convex`:
+
+  ```ts
+  import { requireFacilitator, requireHubUser } from "@user-hub/auth/convex";
+
+  export const closeVoting = mutation({
+    args: {},
+    handler: async (ctx) => {
+      const facilitator = await requireFacilitator(ctx); // throws for members
+      // …
+    },
+  });
+
+  export const myVotes = query({
+    args: {},
+    handler: async (ctx) => {
+      const me = await requireHubUser(ctx); // throws when signed out
+      // query by me.id
+    },
+  });
+  ```
+
+  `getHubUser(ctx)` returns the person or null when signing in is optional. Not Convex: check `(await verifyHubToken(request, { app })).role`.
+
+- **Then hide what members cannot use**, for a clean UI only:
+
+  ```tsx
+  const me = useHubUser();
+  if (me?.role !== "facilitator") return <p>This page is for facilitators.</p>;
+  ```
+
+  A hidden page is not protection: members can still call the functions, which is why the server check comes first.
+
+## Rules
+
+- Key all data on the hub id (`identity.subject` / `useHubUser().id`). Never on the name, and never on the badge token, which the app never sees.
+- Check access on the server: `requireFacilitator(ctx)` / `requireHubUser(ctx)` in Convex, or `verifyHubToken` elsewhere. `useHubUser()` is for display only.
+- Tokens last 4 hours; the provider then shows the signed-out screen. Do not try to refresh them: people scan their badge again.
+- Do not add other sign-in methods, sessions or token handling. If something is missing, change this package instead.