@user-hub/auth

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.
4. Your app stores its own data under the person's id.

Sessions

The hub decides how long a scan keeps someone signed in: 1, 2 or 4 hours, or until they are signed out from the hub. Your app needs no setup for this.

• When the app opens, and then every 5 minutes while it is open, the provider trades the token for a fresh one with the hub (POST <hub>/api/token/refresh); each fresh token lasts 10 minutes. With hubUrl set, it only ever asks that hub. The schedule follows the hub's clock, so a device whose clock is off still refreshes on time.
• Reopening the app later (even the next day) keeps the person signed in while their session lasts.
• When the hub ends a session (the person is deleted, signed out of all apps, or gets a new badge), the app signs them out within about 10 minutes. Name, team and role changes arrive the same way. Other tabs of the app follow a sign-out.
• A server checking tokens with verifyHubToken still accepts a token until it expires: up to 10 minutes after the hub ends the session, or up to 4 hours for the token a scan hands over.
• If the hub cannot be reached, the person stays signed in until their token runs out, then sees the signed-out screen; the app tries again when the device is back online, every 30 seconds, and on reload.
• A Content Security Policy needs the hub in connect-src.

Quick start

1. Install

bun add @user-hub/auth

Using a coding agent? The package ships an agent skill. Add it to your agents with:

bunx skills experimental_sync

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:

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):

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. --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

On your Convex deployment (every deployment you use):

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:

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>):

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

import { useHubUser } from "@user-hub/auth/react"; // also exported by /convex-react

const me = useHubUser(); // { id, name, team, role }

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 across reloads and restarts until that person's expiration in the hub (4 hours unless set otherwise).

• 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.

Sign out

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:

import { requireFacilitator } from "@user-hub/auth/convex";

export const closeVoting = mutation({
  args: {},
  handler: async (ctx) => {
    await requireFacilitator(ctx); // throws for members
    // …
  },
});

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. It changes every few minutes as it is refreshed, so read it for each request:

const token = useHubToken();
fetch("/api/thing", { headers: { Authorization: `Bearer ${token}` } });

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(), useHubSignOut() | The person (or null), the current token (or null; it changes as it is refreshed), 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>] [--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

bun install
bun test           # unit tests
bun run check      # Biome
bun run build      # dist/: commit it

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.