@lumoauth/react 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,791 +1,643 @@
1
1
  # @lumoauth/react
2
2
 
3
- Drop-in authentication, user management, and authorization components for React & Next.js — powered by [LumoAuth](https://lumoauth.dev).
4
-
5
- > Built following [Clerk SDK](https://clerk.com/docs) patterns. Uses **OAuth 2.0 Authorization Code + PKCE** by default.
6
-
7
- ---
8
-
9
- ## 🤖 For AI Agents (Copilot, Cursor, Claude)
10
-
11
- Building a React or Next.js app with LumoAuth? Copy and paste the prompt below into your AI assistant to generate fully working auth scaffolding instantly:
12
-
13
- > **"I am building a [React/Next.js] web application. Please run `npm install @lumoauth/react @lumoauth/client`. Then, add `<LumoAuthProvider domain=\"...\" orgId=\"...\" clientId=\"...\">` to the root layout. Build a responsive Header navigation bar that uses `<SignedOut>` with `<SignInButton>` and `<SignedIn>` with `<UserButton>`. Create a protected `/dashboard` page using the `<Protect permission=\"admin.dashboard\">` wrapper component. Finally, implement an `/auth/callback` route utilizing the `<AuthCallback>` component. I don't have the library docs, so please assume these components and props exist exactly as described."**
14
-
15
- ---
16
-
17
- ## Getting Started
18
-
19
- ### 1. Installation
3
+ [![npm](https://img.shields.io/npm/v/@lumoauth/react.svg)](https://www.npmjs.com/package/@lumoauth/react)
4
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
5
+
6
+ `@lumoauth/react` adds LumoAuth sign-in, user menus and access checks to a React app. You wrap
7
+ the app in `<LumoAuthProvider>`, then use ready-made components such as `<SignIn>`,
8
+ `<UserButton>` and `<Protect>`, or hooks such as `useAuth()` and `usePermission()`. Users sign
9
+ in with OAuth 2.0 and PKCE by default.
10
+
11
+ It is part of the [LumoAuth JavaScript SDK](../../README.md), and it is built on
12
+ [`@lumoauth/client`](../client/README.md).
13
+
14
+ ## Contents
15
+
16
+ - [Is this the right package?](#is-this-the-right-package)
17
+ - [Requirements](#requirements)
18
+ - [Install](#install)
19
+ - [Quick start](#quick-start)
20
+ - [Core concepts](#core-concepts)
21
+ - [Configuration](#configuration)
22
+ - [Components](#components)
23
+ - [Sign-in and sign-up](#sign-in-and-sign-up)
24
+ - [User](#user)
25
+ - [Access checks](#access-checks)
26
+ - [Show content by sign-in state](#show-content-by-sign-in-state)
27
+ - [Unstyled buttons](#unstyled-buttons)
28
+ - [Hooks](#hooks)
29
+ - [Common patterns](#common-patterns)
30
+ - [Appearance](#appearance)
31
+ - [Sign-in strategies](#sign-in-strategies)
32
+ - [Errors](#errors)
33
+ - [API reference](#api-reference)
34
+ - [Troubleshooting](#troubleshooting)
35
+ - [Versioning and compatibility](#versioning-and-compatibility)
36
+ - [Related packages](#related-packages)
37
+ - [Licence](#licence)
38
+
39
+ ## Is this the right package?
40
+
41
+ | You are building… | Use |
42
+ |---|---|
43
+ | A React 18+ single-page app (Vite, Remix, React Router and similar) | **This package** |
44
+ | A Next.js App Router app | [`@lumoauth/nextjs`](../nextjs/README.md). It re-exports everything here and adds server-side sessions. |
45
+ | An app in Vue, Svelte, Angular or plain JavaScript | [`@lumoauth/client`](../client/README.md) |
46
+ | Server code | [`@lumoauth/backend`](../backend/README.md) or [`@lumoauth/express`](../express/README.md) |
47
+
48
+ ## Requirements
49
+
50
+ - React and React DOM 18 or newer (peer dependencies)
51
+ - Node 18 or newer for your build
52
+ - A LumoAuth organization and a **public** OAuth client with PKCE. Register your callback URL as a
53
+ redirect URI, and add your app's origin to the client's allowed origins.
54
+
55
+ ## Install
20
56
 
21
57
  ```bash
22
- npm install @lumoauth/react @lumoauth/client
58
+ npm install @lumoauth/react
23
59
  ```
24
60
 
25
- ---
61
+ `@lumoauth/client` is installed with it and re-exported as `LumoAuth`, so one install is enough.
62
+
63
+ ## Quick start
26
64
 
27
- ### 2. Wrap your app with the provider
65
+ **1. Wrap the app in the provider.**
28
66
 
29
67
  ```tsx
30
68
  import { LumoAuthProvider } from '@lumoauth/react';
31
69
 
32
- function App() {
70
+ export function App() {
33
71
  return (
34
72
  <LumoAuthProvider
35
- domain="https://auth.example.com"
73
+ domain="https://app.lumoauth.dev" // EU region: https://eu.app.lumoauth.dev
36
74
  orgId="acme-corp"
37
75
  clientId="your-client-id"
38
76
  afterSignInUrl="/dashboard"
39
- afterSignOutUrl="/"
40
77
  >
41
- <Router />
78
+ <Routes />
42
79
  </LumoAuthProvider>
43
80
  );
44
81
  }
45
82
  ```
46
83
 
47
- ### 3. Add a callback route
84
+ **2. Add a callback page.** By default the provider sends users back to
85
+ `<your origin>/auth/callback`. Mount `<AuthCallback>` on that route:
48
86
 
49
87
  ```tsx
50
88
  import { AuthCallback } from '@lumoauth/react';
51
89
 
52
- // Mount at /auth/callback (or your custom redirectUri)
53
- function CallbackPage() {
90
+ export function CallbackPage() {
54
91
  return <AuthCallback afterSignInUrl="/dashboard" />;
55
92
  }
56
93
  ```
57
94
 
58
- ### 4. Show sign-in or user profile based on session
95
+ **3. Show a sign-in button or the user menu.**
59
96
 
60
97
  ```tsx
61
- import { SignedIn, SignedOut, SignIn, UserButton } from '@lumoauth/react';
98
+ import { SignedIn, SignedOut, SignInButton, UserButton } from '@lumoauth/react';
62
99
 
63
- function Header() {
100
+ export function Header() {
64
101
  return (
65
102
  <nav>
66
- <SignedOut>
67
- <SignIn />
68
- </SignedOut>
69
- <SignedIn>
70
- <UserButton showName />
71
- </SignedIn>
103
+ <SignedOut><SignInButton>Sign in</SignInButton></SignedOut>
104
+ <SignedIn><UserButton showName /></SignedIn>
72
105
  </nav>
73
106
  );
74
107
  }
75
108
  ```
76
109
 
77
- ---
110
+ **4. Show content only to users who hold a permission.**
78
111
 
79
- ## Provider
112
+ ```tsx
113
+ import { Protect } from '@lumoauth/react';
80
114
 
81
- ### `<LumoAuthProvider>`
115
+ <Protect permission="admin.dashboard" fallback={<p>You do not have access.</p>}>
116
+ <AdminPanel />
117
+ </Protect>
118
+ ```
82
119
 
83
- Wrap your application to manage auth state globally.
120
+ ## Core concepts
84
121
 
85
- | Prop | Type | Default | Description |
86
- |------|------|---------|-------------|
87
- | `domain` | `string` | **required** | Your LumoAuth instance URL |
88
- | `orgId` | `string` | **required** | Your organization ID |
89
- | `clientId` | `string` | **required** | OAuth client ID |
90
- | `authStrategy` | `'pkce' \| 'password'` | `'pkce'` | Authentication method |
91
- | `redirectUri` | `string` | `origin + '/auth/callback'` | OAuth callback URL |
92
- | `afterSignInUrl` | `string` | `'/'` | Redirect after sign-in |
93
- | `afterSignUpUrl` | `string` | — | Redirect after sign-up |
94
- | `afterSignOutUrl` | `string` | `'/'` | Redirect after sign-out |
122
+ **The provider holds the session.** `<LumoAuthProvider>` signs the user in, stores the tokens,
123
+ refreshes the access token before it expires, and shares the session across tabs. Every component
124
+ and hook reads from it, so the provider must wrap them.
95
125
 
96
- ---
126
+ **Checks run as the signed-in user.** `usePermission`, `useZanzibar`, `useAbac` and `<Protect>`
127
+ call LumoAuth with the user's access token. They hide content in the browser, but they do not
128
+ protect data. Your API must check access again on the server.
97
129
 
98
- ## Authentication Components
130
+ **Scopes.** The provider requests `openid profile email` at sign-in unless you pass a `scope`
131
+ prop. Permission and relationship checks need nothing more. ABAC checks need `abac:read`, and
132
+ listing the user's permissions needs `authz:read`. Add them to `scope`, and allow them on the
133
+ OAuth client:
99
134
 
100
- ### `<SignIn>`
135
+ ```tsx
136
+ <LumoAuthProvider
137
+ domain="https://app.lumoauth.dev"
138
+ orgId="acme-corp"
139
+ clientId="client_…"
140
+ scope="openid profile email abac:read authz:read"
141
+ >
142
+ ```
143
+
144
+ The full scope table is in the [client README](../client/README.md#scopes).
101
145
 
102
- Full sign-in card. In PKCE mode, shows social buttons and a redirect-based email sign-in. In password mode, shows an inline email/password form.
146
+ ## Configuration
147
+
148
+ `<LumoAuthProvider>` props:
149
+
150
+ | Prop | Type | Default | Description |
151
+ |---|---|---|---|
152
+ | `domain` | `string` | required | Root URL of LumoAuth |
153
+ | `orgId` | `string` | required | Organization slug |
154
+ | `clientId` | `string` | required | OAuth client ID |
155
+ | `redirectUri` | `string` | `<origin>/auth/callback` | Callback URL. It must be registered on the OAuth client. |
156
+ | `scope` | `string` | `'openid profile email'` | Space-separated scopes for sign-in and sign-up. Add `abac:read` for `useAbac` and `<Protect abac>`, and `authz:read` for `listSlugs()`. The OAuth client must allow each scope. |
157
+ | `afterSignInUrl` | `string` | `'/'` | Where `<AuthCallback>` sends the user after sign-in |
158
+ | `afterSignUpUrl` | `string` | none | Where to go after sign-up |
159
+ | `afterSignOutUrl` | `string` | `'/'` | Where to go after sign-out. Register it as a post-logout redirect URI on the client. |
160
+ | `authStrategy` | `'pkce' \| 'password'` | `'pkce'` | See [Sign-in strategies](#sign-in-strategies) |
161
+ | `storage` | `TokenStorage` | `sessionStorage` in a browser, memory on a server | Where tokens are stored. Import an adapter from `@lumoauth/client`. |
162
+ | `crossTab` | `boolean` | `true` | Share the session across tabs. One tab does each refresh, and the others receive the result. |
163
+ | `children` | `ReactNode` | required | Your app |
164
+
165
+ **Where tokens are stored.** The default, `sessionStorage`, keeps one session per tab and clears
166
+ it when the tab closes. `localStorageAdapter()` shares the session across tabs and browser
167
+ restarts. `cookieStorageAdapter()` keeps tokens in an httpOnly cookie that scripts cannot read,
168
+ which is the only option that protects them from cross-site scripting. It needs a same-origin
169
+ server that serves a session endpoint, such as the one in `@lumoauth/nextjs`. The
170
+ [client README](../client/README.md#choose-where-tokens-are-stored) compares the adapters.
103
171
 
104
172
  ```tsx
105
- import { SignIn } from '@lumoauth/react';
173
+ import { localStorageAdapter } from '@lumoauth/client';
106
174
 
107
- <SignIn
108
- afterSignInUrl="/dashboard"
109
- signUpUrl="/sign-up"
110
- appearance={{ theme: 'dark' }}
111
- />
175
+ <LumoAuthProvider domain={domain} orgId={orgId} clientId={clientId} storage={localStorageAdapter()}>
112
176
  ```
113
177
 
114
- | Prop | Type | Description |
115
- |------|------|-------------|
116
- | `afterSignInUrl` | `string` | Redirect after sign-in |
117
- | `signUpUrl` | `string` | Link to sign-up page |
118
- | `appearance` | `AppearanceProps` | Theme/style overrides |
178
+ Create the adapter once, outside the component, or with `useMemo`. A new adapter on each render
179
+ rebuilds the session.
119
180
 
120
- ### `<SignUp>`
181
+ ## Components
121
182
 
122
- Registration component. PKCE mode redirects to hosted signup; password mode shows inline form.
183
+ ### Sign-in and sign-up
123
184
 
124
- ```tsx
125
- import { SignUp } from '@lumoauth/react';
185
+ **`<SignIn>`** renders a sign-in card. In PKCE mode it shows social buttons, if you list any, and
186
+ a button that redirects to the LumoAuth sign-in page. In password mode it shows an email and
187
+ password form.
126
188
 
127
- <SignUp afterSignUpUrl="/onboarding" signInUrl="/sign-in" />
189
+ ```tsx
190
+ <SignIn afterSignInUrl="/dashboard" signUpUrl="/sign-up" socialProviders={['google', 'github']} />
128
191
  ```
129
192
 
130
- ### `<AuthCallback>`
193
+ | Prop | Type | Description |
194
+ |---|---|---|
195
+ | `afterSignInUrl` | `string` | Where to go after sign-in |
196
+ | `signUpUrl` | `string` | Link to your sign-up page |
197
+ | `socialProviders` | `string[]` | Providers to show. The default is `[]`. Each button sends the user straight to that provider. If the organization has not set the provider up, the user sees the LumoAuth sign-in page instead. Icons are included for `google`, `github`, `microsoft` and `apple`. |
198
+ | `appearance` | `AppearanceProps` | See [Appearance](#appearance) |
199
+
200
+ The SDK has no default list of providers. An unauthenticated page cannot read which providers
201
+ the organization has turned on, so you list them yourself.
131
202
 
132
- Handles the OAuth redirect callback. Place on your callback route.
203
+ **`<SignUp>`** renders a sign-up card. In PKCE mode it sends the user to the LumoAuth registration
204
+ page. Password mode has no inline registration, because LumoAuth has no JSON registration
205
+ endpoint.
133
206
 
134
207
  ```tsx
135
- import { AuthCallback } from '@lumoauth/react';
208
+ <SignUp afterSignUpUrl="/onboarding" signInUrl="/sign-in" />
209
+ ```
210
+
211
+ **`<AuthCallback>`** finishes sign-in on your callback route. It checks the `state`, exchanges the
212
+ code for tokens, loads the user and redirects.
136
213
 
137
- // Route: /auth/callback
214
+ ```tsx
138
215
  <AuthCallback
139
216
  afterSignInUrl="/dashboard"
140
- loading={<MyCustomSpinner />}
141
- error={(msg) => <MyErrorCard message={msg} />}
217
+ loading={<Spinner />}
218
+ error={(message) => <ErrorCard message={message} />}
142
219
  />
143
220
  ```
144
221
 
145
222
  | Prop | Type | Description |
146
- |------|------|-------------|
147
- | `afterSignInUrl` | `string` | Redirect on success |
148
- | `loading` | `ReactNode` | Custom loading UI |
149
- | `error` | `ReactNode \| (msg) => ReactNode` | Custom error UI |
150
-
151
- ---
223
+ |---|---|---|
224
+ | `afterSignInUrl` | `string` | Where to go on success. Falls back to the provider's `afterSignInUrl`, then `/`. |
225
+ | `loading` | `ReactNode` | Shown during the exchange |
226
+ | `error` | `ReactNode \| (message: string) => ReactNode` | Shown when sign-in fails |
152
227
 
153
- ## User Components
228
+ ### User
154
229
 
155
- ### `<UserButton>`
156
-
157
- Avatar button with a dropdown menu for account management and sign-out. Only visible when signed in.
230
+ **`<UserButton>`** shows the user's avatar with a menu for the account and sign-out. It renders
231
+ nothing when nobody is signed in.
158
232
 
159
233
  ```tsx
160
- import { UserButton } from '@lumoauth/react';
161
-
162
234
  <UserButton showName afterSignOutUrl="/" />
163
235
  ```
164
236
 
165
237
  | Prop | Type | Default | Description |
166
- |------|------|---------|-------------|
167
- | `showName` | `boolean` | `false` | Show display name next to avatar |
168
- | `afterSignOutUrl` | `string` | `'/'` | Redirect after sign-out |
169
- | `appearance` | `AppearanceProps` | — | Theme/style overrides |
238
+ |---|---|---|---|
239
+ | `showName` | `boolean` | `false` | Show the display name next to the avatar |
240
+ | `afterSignOutUrl` | `string` | provider value, then `'/'` | Where to go after sign-out |
241
+ | `appearance` | `AppearanceProps` | none | Style overrides |
170
242
 
171
- ### `<UserAvatar>`
172
-
173
- Renders the user's profile image or initials. Shows a placeholder icon when not signed in.
243
+ **`<UserAvatar>`** shows the user's picture or initials. It shows a placeholder icon when nobody
244
+ is signed in.
174
245
 
175
246
  ```tsx
176
- import { UserAvatar } from '@lumoauth/react';
177
-
178
- // Default circle avatar
179
247
  <UserAvatar />
180
-
181
- // Large square avatar
182
248
  <UserAvatar size={48} shape="square" />
183
249
  ```
184
250
 
185
- | Prop | Type | Default | Description |
186
- |------|------|---------|-------------|
187
- | `size` | `number` | `32` | Size in pixels |
188
- | `shape` | `'circle' \| 'square'` | `'circle'` | Avatar shape |
189
- | `appearance` | `AppearanceProps` | — | Theme/style overrides |
190
-
191
- ### `<UserProfile>`
251
+ | Prop | Type | Default |
252
+ |---|---|---|
253
+ | `size` | `number` (pixels) | `32` |
254
+ | `shape` | `'circle' \| 'square'` | `'circle'` |
255
+ | `appearance` | `AppearanceProps` | none |
192
256
 
193
- Full profile card showing account details, security status, roles, groups, and sign-out.
257
+ **`<UserProfile>`** shows a profile card with account details, security status, roles, groups and
258
+ a sign-out button.
194
259
 
195
260
  ```tsx
196
- import { UserProfile } from '@lumoauth/react';
197
-
198
- // Full profile card
199
261
  <UserProfile afterSignOutUrl="/" />
200
-
201
- // Compact mode (hides security and roles sections)
202
- <UserProfile mode="compact" />
262
+ <UserProfile mode="compact" /> {/* account details only */}
203
263
  ```
204
264
 
205
265
  | Prop | Type | Default | Description |
206
- |------|------|---------|-------------|
207
- | `mode` | `'full' \| 'compact'` | `'full'` | Display mode |
208
- | `afterSignOutUrl` | `string` | `'/'` | Redirect after sign-out |
209
- | `appearance` | `AppearanceProps` | — | Theme/style overrides |
210
-
211
- ---
212
-
213
- ## Control Components
266
+ |---|---|---|---|
267
+ | `mode` | `'full' \| 'compact'` | `'full'` | `'compact'` hides the security and roles sections |
268
+ | `afterSignOutUrl` | `string` | none | Where to go after sign-out |
269
+ | `appearance` | `AppearanceProps` | none | Style overrides |
214
270
 
215
- ### `<SignedIn>` / `<SignedOut>`
271
+ ### Access checks
216
272
 
217
- Conditional rendering based on authentication state.
273
+ **`<Protect>`** renders its children only when a check allows it. Pass exactly one of
274
+ `permission`, `zanzibar` or `abac`. While the check runs, and when it is denied, `<Protect>`
275
+ renders `fallback`.
218
276
 
219
277
  ```tsx
220
- import { SignedIn, SignedOut } from '@lumoauth/react';
278
+ // A permission (RBAC)
279
+ <Protect permission="admin.dashboard" fallback={<p>You do not have access.</p>}>
280
+ <AdminPanel />
281
+ </Protect>
221
282
 
222
- function Page() {
223
- return (
224
- <>
225
- <SignedIn>
226
- <p>Welcome back! You are signed in.</p>
227
- <UserProfile />
228
- </SignedIn>
283
+ // A relationship (Zanzibar). Without subject, the check is about the signed-in user.
284
+ <Protect zanzibar={{ object: 'document:readme', relation: 'editor' }}>
285
+ <EditButton />
286
+ </Protect>
229
287
 
230
- <SignedOut>
231
- <p>Please sign in to continue.</p>
232
- <SignIn />
233
- </SignedOut>
234
- </>
235
- );
236
- }
288
+ // An attribute policy (ABAC). Needs abac:read on the token.
289
+ <Protect abac={{ resourceType: 'document', action: 'delete', resourceId: 'doc-123' }}>
290
+ <DeleteButton />
291
+ </Protect>
237
292
  ```
238
293
 
239
- ### `<RedirectToSignIn>`
294
+ | Prop | Type | Description |
295
+ |---|---|---|
296
+ | `permission` | `string` | Permission slug |
297
+ | `zanzibar` | `{ object, relation, subject? }` | Relationship check. Without `subject`, the SDK asks about `user:<sub>`, where `<sub>` is the signed-in user's subject. When nobody is signed in, `<Protect>` renders `fallback` and sends no request. |
298
+ | `abac` | `{ resourceType, action, resourceId? }` | ABAC check |
299
+ | `fallback` | `ReactNode` | Shown while checking and when denied. Default: nothing. |
300
+ | `children` | `ReactNode` | Shown when allowed |
240
301
 
241
- Automatically redirects unauthenticated users to the sign-in flow.
302
+ Any error during the check, such as a missing scope, counts as denied.
242
303
 
243
- ```tsx
244
- import { SignedOut, RedirectToSignIn } from '@lumoauth/react';
304
+ ### Show content by sign-in state
245
305
 
246
- function ProtectedPage() {
247
- return (
248
- <>
249
- <SignedOut>
250
- <RedirectToSignIn />
251
- </SignedOut>
252
- <SignedIn>
253
- <Dashboard />
254
- </SignedIn>
255
- </>
256
- );
257
- }
306
+ ```tsx
307
+ <SignedIn><p>Welcome back.</p></SignedIn>
308
+ <SignedOut><SignIn /></SignedOut>
258
309
  ```
259
310
 
260
- ---
261
-
262
- ## Unstyled Components
263
-
264
- Headless components without built-in UI — bring your own markup.
311
+ `<SignedIn>` renders its children only when a user is signed in. `<SignedOut>` renders them only
312
+ when nobody is. Neither renders anything while the session is loading.
265
313
 
266
- ### `<SignInButton>`
314
+ **`<RedirectToSignIn>`** starts sign-in as soon as it renders. In PKCE mode it sends the user to
315
+ LumoAuth. In password mode it sends the user to `signInUrl`, when you pass one.
267
316
 
268
317
  ```tsx
269
- import { SignInButton } from '@lumoauth/react';
270
-
271
- // Default
272
- <SignInButton />
273
-
274
- // Custom children
275
- <SignInButton>
276
- <button className="my-btn">Log in</button>
277
- </SignInButton>
318
+ <SignedOut><RedirectToSignIn /></SignedOut>
319
+ <SignedIn><Dashboard /></SignedIn>
278
320
  ```
279
321
 
280
- ### `<SignUpButton>`
322
+ ### Unstyled buttons
281
323
 
282
- ```tsx
283
- import { SignUpButton } from '@lumoauth/react';
284
- <SignUpButton signUpUrl="/register" />
285
- ```
286
-
287
- ### `<SignOutButton>`
324
+ These buttons have no styling of their own. Put your own markup inside them.
288
325
 
289
326
  ```tsx
290
- import { SignOutButton } from '@lumoauth/react';
291
-
292
- <SignOutButton afterSignOutUrl="/">
293
- <button className="my-btn">Log out</button>
294
- </SignOutButton>
327
+ <SignInButton><button className="btn">Log in</button></SignInButton>
328
+ <SignUpButton signUpUrl="/register" />
329
+ <SignOutButton afterSignOutUrl="/"><button className="btn">Log out</button></SignOutButton>
295
330
  ```
296
331
 
297
- ---
332
+ | Component | Props | What a click does |
333
+ |---|---|---|
334
+ | `<SignInButton>` | `children?`, `signInUrl?`, `className?` | PKCE mode: starts sign-in. Password mode: goes to `signInUrl`. |
335
+ | `<SignUpButton>` | `children?`, `signUpUrl?`, `className?` | Goes to `signUpUrl` |
336
+ | `<SignOutButton>` | `children?`, `afterSignOutUrl?`, `className?` | Signs the user out, then redirects |
298
337
 
299
338
  ## Hooks
300
339
 
301
- ### `useAuth()`
340
+ Every hook must be called inside `<LumoAuthProvider>`.
302
341
 
303
- Primary hook — returns the full auth context.
342
+ **`useAuth()`** returns the full auth context.
304
343
 
305
344
  ```tsx
306
- import { useAuth } from '@lumoauth/react';
307
-
308
- function MyComponent() {
309
- const { user, isSignedIn, isLoaded, signIn, signOut, getToken } = useAuth();
345
+ const { user, isSignedIn, isLoaded, signIn, signOut, getToken } = useAuth();
310
346
 
311
- if (!isLoaded) return <p>Loading…</p>;
312
- if (!isSignedIn) return <button onClick={() => signIn()}>Sign in</button>;
313
-
314
- return (
315
- <div>
316
- <p>Hello, {user.displayName}!</p>
317
- <button onClick={() => signOut()}>Sign out</button>
318
- </div>
319
- );
320
- }
347
+ if (!isLoaded) return <p>Loading…</p>;
348
+ if (!isSignedIn) return <button onClick={() => signIn()}>Sign in</button>;
349
+ return <button onClick={() => signOut()}>Sign out {user!.displayName}</button>;
321
350
  ```
322
351
 
323
- #### Return value
324
-
325
352
  | Property | Type | Description |
326
- |----------|------|-------------|
327
- | `user` | `LumoAuthUser \| null` | Current user object |
328
- | `isSignedIn` | `boolean` | Whether user is authenticated |
329
- | `isLoaded` | `boolean` | Whether initial auth check is done |
330
- | `status` | `'loading' \| 'authenticated' \| 'unauthenticated'` | Auth status |
331
- | `signIn` | `(email?, password?) => void` | Trigger sign-in |
332
- | `signInWithRedirect` | `() => void` | Force PKCE redirect |
333
- | `signUp` | `(params) => Promise<void>` | Trigger sign-up |
334
- | `signOut` | `() => Promise<void>` | Sign out |
335
- | `getToken` | `() => Promise<string \| null>` | Get access token |
336
- | `handleCallback` | `() => Promise<void>` | Exchange OAuth code |
337
- | `authStrategy` | `'pkce' \| 'password'` | Current strategy |
338
-
339
- ### `useUser()`
340
-
341
- Returns the current user, or `null`.
342
-
343
- ```tsx
344
- import { useUser } from '@lumoauth/react';
345
-
346
- const user = useUser();
347
- console.log(user?.email, user?.roles);
348
- ```
349
-
350
- #### `LumoAuthUser` object
353
+ |---|---|---|
354
+ | `user` | `LumoAuthUser \| null` | The signed-in user |
355
+ | `status` | `'loading' \| 'authenticated' \| 'unauthenticated'` | Session status |
356
+ | `isLoaded` | `boolean` | The first session check has finished |
357
+ | `isSignedIn` | `boolean` | A user is signed in |
358
+ | `signIn(email?, password?)` | function | PKCE mode: call with no arguments to redirect to LumoAuth. Password mode: pass the email and password. |
359
+ | `signInWithRedirect()` | function | Starts the PKCE redirect in either mode |
360
+ | `signInWithSocial(provider)` | function | Starts the PKCE redirect straight to a social provider, such as `'google'` |
361
+ | `signUp(params)` | function | PKCE mode: sends the user to the registration page. Password mode: throws, because inline registration is not available. |
362
+ | `signOut({ afterSignOutUrl? })` | function | Revokes the access token, clears local tokens, and ends the LumoAuth session through the logout endpoint |
363
+ | `getToken()` | `() => Promise<string \| null>` | A valid access token. It refreshes first when needed. |
364
+ | `handleCallback()` | function | Exchanges the code on the callback page. `<AuthCallback>` calls it for you. |
365
+ | `sendMagicLink(email, redirectUri?)` | function | Emails a sign-in link |
366
+ | `checkEmail(email)` | `(email) => Promise<EmailCheckResult>` | Reports the sign-in methods for an email address |
367
+ | `authStrategy` | `'pkce' \| 'password'` | The strategy in use |
368
+ | `config` | object | The provider's `domain`, `orgId`, `clientId` and redirect URLs |
369
+
370
+ **`useUser()`** returns the signed-in `LumoAuthUser`, or `null`.
351
371
 
352
372
  | Field | Type | Description |
353
- |-------|------|-------------|
354
- | `id` | `string \| number` | User ID |
355
- | `email` | `string` | Primary email |
356
- | `firstName` | `string?` | First name |
357
- | `lastName` | `string?` | Last name |
358
- | `displayName` | `string` | Computed display name |
359
- | `avatarUrl` | `string?` | Profile image URL |
360
- | `emailVerified` | `boolean` | Email verification status |
361
- | `mfaEnabled` | `boolean` | MFA status |
362
- | `roles` | `string[]` | Role slugs |
363
- | `groups` | `string[]` | Group names |
364
- | `sub` | `string?` | OIDC subject ID |
365
- | `claims` | `Record<string, unknown>` | Additional claims |
366
-
367
- ### `useSignIn()`
373
+ |---|---|---|
374
+ | `id` | `string \| number` | User ID (the OIDC `sub`) |
375
+ | `email` | `string` | Primary email address |
376
+ | `firstName`, `lastName` | `string \| undefined` | Name parts |
377
+ | `displayName` | `string` | The name, or the email when there is no name |
378
+ | `avatarUrl` | `string \| undefined` | Profile picture |
379
+ | `emailVerified` | `boolean` | Whether the email address is verified |
380
+ | `mfaEnabled` | `boolean` | From the `mfa_enabled` claim; `false` when absent |
381
+ | `roles`, `groups` | `string[]` | From the `roles` and `groups` claims; empty when absent |
382
+ | `sub` | `string \| undefined` | OIDC subject |
383
+ | `claims` | `Record<string, unknown>` | Every claim from the UserInfo response |
368
384
 
369
- ```tsx
370
- import { useSignIn } from '@lumoauth/react';
385
+ The user comes from the OIDC UserInfo endpoint. A field is empty when the response does not
386
+ contain it.
371
387
 
372
- const { signIn, signInWithRedirect, isLoading } = useSignIn();
373
- ```
388
+ **`useSignIn()`** returns `{ signIn, signInWithRedirect, isLoading }`.
374
389
 
375
- ### `useSession()`
390
+ **`useSession()`** returns `{ isActive, isLoaded, getToken, status }`. Use `getToken()` to call
391
+ your own API:
376
392
 
377
393
  ```tsx
378
- import { useSession } from '@lumoauth/react';
379
-
380
- const { isActive, isLoaded, getToken, status } = useSession();
381
-
382
- // Fetch API data with the access token
383
- async function fetchData() {
384
- const token = await getToken();
385
- const res = await fetch('/api/data', {
386
- headers: { Authorization: `Bearer ${token}` },
387
- });
388
- return res.json();
389
- }
394
+ const { getToken } = useSession();
395
+ const res = await fetch('/api/data', { headers: { Authorization: `Bearer ${await getToken()}` } });
390
396
  ```
391
397
 
392
- ### `useLumoAuth()`
393
-
394
- Returns a configured `LumoAuth` SDK client for authorization checks. Token is auto-managed.
398
+ **`useLumoAuth()`** returns a `LumoAuth` client from `@lumoauth/client`. Its token comes from the
399
+ session. Use it for any call that the hooks do not cover.
395
400
 
396
401
  ```tsx
397
- import { useLumoAuth } from '@lumoauth/react';
398
-
399
402
  const client = useLumoAuth();
400
- const canEdit = await client.permissions.check('documents.edit');
403
+ const canEdit = await client.permissions.check('document.edit');
401
404
  ```
402
405
 
403
- ### `usePermission(slug)`
406
+ **`usePermission(slug)`**, **`useZanzibar(request)`** and **`useAbac(request)`** each return
407
+ `{ allowed, isLoading }`. Each one runs again when its input changes. An error counts as denied.
404
408
 
405
409
  ```tsx
406
- import { usePermission } from '@lumoauth/react';
407
-
408
- const { allowed, isLoading } = usePermission('documents.edit');
410
+ const { allowed, isLoading } = usePermission('document.edit');
411
+ const editor = useZanzibar({ object: 'document:readme', relation: 'editor', subject: 'user:alice' });
412
+ const canRead = useAbac({ resourceType: 'document', action: 'read', resourceId: 'doc-123' });
409
413
  ```
410
414
 
411
- ### `useZanzibar(request)`
412
-
413
- ```tsx
414
- import { useZanzibar } from '@lumoauth/react';
415
-
416
- const { allowed, isLoading } = useZanzibar({
417
- object: 'document:readme',
418
- relation: 'editor',
419
- subject: 'user:alice',
420
- });
421
- ```
415
+ A Zanzibar check about a user other than the signed-in user needs the `authz:check` scope or
416
+ permission. `useAbac` needs `abac:read`; see [Core concepts](#core-concepts).
422
417
 
423
- ### `useAbac(request)`
418
+ **`useMagicLink()`** returns `{ sendMagicLink, isLoading, isSent, error, reset }`:
424
419
 
425
420
  ```tsx
426
- import { useAbac } from '@lumoauth/react';
427
-
428
- const { allowed, isLoading } = useAbac({
429
- resourceType: 'document',
430
- action: 'read',
431
- resourceId: 'doc-123',
432
- });
433
- ```
434
-
435
- ### `useMagicLink()`
436
-
437
- Manages the full state machine for sending a passwordless magic-link email. Handles in-flight loading, success, and error states so you can build a controlled form without any extra local state.
438
-
439
- ```tsx
440
- import { useMagicLink } from '@lumoauth/react';
441
-
442
421
  function PasswordlessForm() {
443
422
  const [email, setEmail] = useState('');
444
423
  const { sendMagicLink, isLoading, isSent, error, reset } = useMagicLink();
445
424
 
446
425
  if (isSent) {
447
426
  return (
448
- <div>
449
- <p>Check your inbox — we sent a sign-in link to <strong>{email}</strong>.</p>
427
+ <p>
428
+ We sent a sign-in link to <strong>{email}</strong>.{' '}
450
429
  <button onClick={reset}>Use a different email</button>
451
- </div>
430
+ </p>
452
431
  );
453
432
  }
454
433
 
455
434
  return (
456
435
  <form onSubmit={(e) => { e.preventDefault(); sendMagicLink(email); }}>
457
- <input
458
- type="email"
459
- value={email}
460
- onChange={(e) => setEmail(e.target.value)}
461
- placeholder="you@example.com"
462
- />
463
- <button type="submit" disabled={isLoading}>
464
- {isLoading ? 'Sending…' : 'Send sign-in link'}
465
- </button>
436
+ <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
437
+ <button type="submit" disabled={isLoading}>{isLoading ? 'Sending…' : 'Send sign-in link'}</button>
466
438
  {error && <p className="error">{error}</p>}
467
439
  </form>
468
440
  );
469
441
  }
470
442
  ```
471
443
 
472
- #### Return value
444
+ `isSent` becomes `true` whether or not the account exists. The server never reveals that.
473
445
 
474
- | Property | Type | Description |
475
- |----------|------|-------------|
476
- | `sendMagicLink` | `(email, redirectUri?) => Promise<void>` | Send the magic link; sets `isSent` on success |
477
- | `isLoading` | `boolean` | True while the request is in-flight |
478
- | `isSent` | `boolean` | True after a successful request |
479
- | `error` | `string \| null` | Error message if the request failed |
480
- | `reset` | `() => void` | Reset back to idle state |
481
-
482
- ### `useEmailFirst()`
483
-
484
- Checks whether an account exists for a given email before revealing the next step (password field, magic-link option, or sign-up prompt). Useful for building a single email-input screen that adapts to whether the user already has an account.
446
+ **`useEmailFirst()`** returns `{ checkEmail, isLoading, result, exists, reset }`. Use it to build
447
+ a sign-in screen that asks for the email address first. `checkEmail(email)` resolves to an
448
+ `EmailCheckResult`. It reports whether the account exists and which methods it can use:
449
+ `passwordEnabled`, `passkeyEnabled`, `magicLinkEnabled`, `hasPasskey`, `hasPushDevice` and
450
+ `maskedEmail`. `exists` is `null` until the first check.
485
451
 
486
452
  ```tsx
487
- import { useEmailFirst } from '@lumoauth/react';
453
+ const { checkEmail, isLoading } = useEmailFirst();
488
454
 
489
- function EmailStep({ onKnownUser, onNewUser }: {
490
- onKnownUser: () => void;
491
- onNewUser: () => void;
492
- }) {
493
- const [email, setEmail] = useState('');
494
- const { checkEmail, isLoading, exists, reset } = useEmailFirst();
495
-
496
- async function handleSubmit(e: React.FormEvent) {
497
- e.preventDefault();
498
- const found = await checkEmail(email);
499
- if (found) {
500
- onKnownUser(); // show password / magic-link step
501
- } else {
502
- onNewUser(); // show sign-up prompt
503
- }
504
- }
505
-
506
- return (
507
- <form onSubmit={handleSubmit}>
508
- <input
509
- type="email"
510
- value={email}
511
- onChange={(e) => setEmail(e.target.value)}
512
- placeholder="you@example.com"
513
- />
514
- <button type="submit" disabled={isLoading}>
515
- {isLoading ? 'Checking…' : 'Continue'}
516
- </button>
517
- </form>
518
- );
455
+ async function onSubmit(e: React.FormEvent) {
456
+ e.preventDefault();
457
+ const found = await checkEmail(email);
458
+ if (!found.exists) return showSignUp();
459
+ if (found.magicLinkEnabled) return showMagicLinkOption();
460
+ signIn(); // fall back to the LumoAuth sign-in page
519
461
  }
520
462
  ```
521
463
 
522
- #### Return value
464
+ ## Common patterns
523
465
 
524
- | Property | Type | Description |
525
- |----------|------|-------------|
526
- | `checkEmail` | `(email) => Promise<boolean>` | Returns `true` if account exists |
527
- | `isLoading` | `boolean` | True while the check is in-flight |
528
- | `exists` | `boolean \| null` | Result of last check (`null` = not yet checked) |
529
- | `reset` | `() => void` | Reset state back to idle |
530
-
531
- ---
532
-
533
- ## Authorization
534
-
535
- ### `<Protect>`
536
-
537
- Conditional rendering based on permissions, Zanzibar (ReBAC), or ABAC.
538
-
539
- ```tsx
540
- import { Protect } from '@lumoauth/react';
541
-
542
- // RBAC
543
- <Protect permission="admin.dashboard" fallback={<p>Access denied</p>}>
544
- <AdminPanel />
545
- </Protect>
546
-
547
- // Zanzibar (ReBAC)
548
- <Protect zanzibar={{ object: 'doc:readme', relation: 'editor' }}>
549
- <EditButton />
550
- </Protect>
551
-
552
- // ABAC
553
- <Protect abac={{ resourceType: 'document', action: 'delete', resourceId: 'doc-123' }}>
554
- <DeleteButton />
555
- </Protect>
556
- ```
557
-
558
- ---
559
-
560
- ## Common Patterns
561
-
562
- ### Navbar with login detection
563
-
564
- Swap sign-in/sign-up links for user avatar and sign-out when authenticated:
466
+ <details>
467
+ <summary><strong>A navigation bar that swaps sign-in links for the user menu</strong></summary>
565
468
 
566
469
  ```tsx
567
- import {
568
- SignedIn, SignedOut,
569
- UserButton, SignInButton, SignUpButton,
570
- } from '@lumoauth/react';
470
+ import { SignedIn, SignedOut, UserButton, SignInButton, SignUpButton } from '@lumoauth/react';
571
471
 
572
- function Navbar() {
472
+ export function Navbar() {
573
473
  return (
574
474
  <nav className="navbar">
575
475
  <a href="/">My App</a>
576
-
577
- <div className="navbar-actions">
578
- <SignedOut>
579
- <SignInButton className="btn">Sign in</SignInButton>
580
- <SignUpButton className="btn btn-primary">Sign up</SignUpButton>
581
- </SignedOut>
582
-
583
- <SignedIn>
584
- <UserButton showName />
585
- </SignedIn>
586
- </div>
476
+ <SignedOut>
477
+ <SignInButton className="btn">Sign in</SignInButton>
478
+ <SignUpButton className="btn btn-primary">Sign up</SignUpButton>
479
+ </SignedOut>
480
+ <SignedIn>
481
+ <UserButton showName />
482
+ </SignedIn>
587
483
  </nav>
588
484
  );
589
485
  }
590
486
  ```
591
487
 
592
- ### Protected routes
488
+ </details>
593
489
 
594
- Redirect unauthenticated users automatically:
490
+ <details>
491
+ <summary><strong>A route that needs a signed-in user</strong></summary>
595
492
 
596
493
  ```tsx
597
494
  import { SignedIn, SignedOut, RedirectToSignIn } from '@lumoauth/react';
598
495
 
599
- function ProtectedRoute({ children }: { children: React.ReactNode }) {
496
+ export function ProtectedRoute({ children }: { children: React.ReactNode }) {
600
497
  return (
601
498
  <>
602
- <SignedOut>
603
- <RedirectToSignIn />
604
- </SignedOut>
605
- <SignedIn>
606
- {children}
607
- </SignedIn>
499
+ <SignedOut><RedirectToSignIn /></SignedOut>
500
+ <SignedIn>{children}</SignedIn>
608
501
  </>
609
502
  );
610
503
  }
611
-
612
- // Usage
613
- <ProtectedRoute>
614
- <Dashboard />
615
- </ProtectedRoute>
616
504
  ```
617
505
 
618
- ### Fetching data with session token
506
+ </details>
507
+
508
+ <details>
509
+ <summary><strong>Calling your API with the user's token</strong></summary>
619
510
 
620
511
  ```tsx
621
512
  import { useSession } from '@lumoauth/react';
622
513
  import { useEffect, useState } from 'react';
623
514
 
624
- function DataView() {
515
+ export function DataView() {
625
516
  const { isActive, getToken } = useSession();
626
517
  const [data, setData] = useState(null);
627
518
 
628
519
  useEffect(() => {
629
520
  if (!isActive) return;
630
-
631
- getToken().then((token) => {
632
- fetch('/api/data', {
633
- headers: { Authorization: `Bearer ${token}` },
634
- })
521
+ getToken().then((token) =>
522
+ fetch('/api/data', { headers: { Authorization: `Bearer ${token}` } })
635
523
  .then((r) => r.json())
636
- .then(setData);
637
- });
524
+ .then(setData),
525
+ );
638
526
  }, [isActive, getToken]);
639
527
 
640
- if (!data) return <p>Loading…</p>;
641
- return <pre>{JSON.stringify(data, null, 2)}</pre>;
642
- }
643
- ```
644
-
645
- ### User profile page
646
-
647
- ```tsx
648
- import { SignedIn, SignedOut, UserProfile, RedirectToSignIn } from '@lumoauth/react';
649
-
650
- function ProfilePage() {
651
- return (
652
- <>
653
- <SignedOut>
654
- <RedirectToSignIn />
655
- </SignedOut>
656
- <SignedIn>
657
- <h1>Your Profile</h1>
658
- <UserProfile afterSignOutUrl="/" />
659
- </SignedIn>
660
- </>
661
- );
662
- }
663
- ```
664
-
665
- ### Custom header with avatar
666
-
667
- ```tsx
668
- import { useAuth, UserAvatar } from '@lumoauth/react';
669
-
670
- function CustomHeader() {
671
- const { user, isSignedIn, signIn, signOut } = useAuth();
672
-
673
- return (
674
- <header>
675
- {isSignedIn ? (
676
- <div className="user-info">
677
- <UserAvatar size={36} />
678
- <span>{user?.displayName}</span>
679
- <button onClick={() => signOut()}>Log out</button>
680
- </div>
681
- ) : (
682
- <button onClick={() => signIn()}>Log in</button>
683
- )}
684
- </header>
685
- );
528
+ return data ? <pre>{JSON.stringify(data, null, 2)}</pre> : <p>Loading…</p>;
686
529
  }
687
530
  ```
688
531
 
689
- ---
532
+ </details>
690
533
 
691
534
  ## Appearance
692
535
 
693
- All pre-built components accept an `appearance` prop:
536
+ Every ready-made component accepts an `appearance` prop:
694
537
 
695
538
  ```tsx
696
539
  <SignIn appearance={{
697
540
  theme: 'dark',
698
- className: 'my-custom-card',
541
+ className: 'my-card',
699
542
  variables: { '--la-primary': '#6366f1' },
700
543
  }} />
701
544
  ```
702
545
 
703
546
  | Option | Type | Description |
704
- |--------|------|-------------|
705
- | `theme` | `'light' \| 'dark'` | Force theme (default: system) |
706
- | `className` | `string` | Additional CSS class |
707
- | `variables` | `Record<string, string>` | Override CSS custom properties |
708
-
709
- ### Themeable CSS variables
710
-
711
- ```css
712
- --la-primary /* Primary brand color */
713
- --la-primary-hover /* Primary hover state */
714
- --la-bg /* Card background */
715
- --la-text-primary /* Primary text color */
716
- --la-text-secondary /* Secondary text color */
717
- --la-border /* Border color */
718
- --la-radius-md /* Default border radius */
719
- --la-font-family /* Font stack */
720
- ```
721
-
722
- ---
723
-
724
- ## Auth Strategy
725
-
726
- ### PKCE (default)
727
-
728
- The recommended mode for SPAs. Uses OAuth 2.0 Authorization Code with PKCE. Users are redirected to the LumoAuth-hosted login page.
729
-
730
- ```tsx
731
- <LumoAuthProvider
732
- domain="https://auth.example.com"
733
- orgId="acme"
734
- clientId="abc"
735
- // authStrategy="pkce" (default)
736
- />
737
- ```
738
-
739
- ### Password (legacy)
740
-
741
- Enables the inline email/password form. Not recommended for production SPAs.
742
-
743
- ```tsx
744
- <LumoAuthProvider
745
- domain="https://auth.example.com"
746
- orgId="acme"
747
- clientId="abc"
748
- authStrategy="password"
749
- />
750
- ```
751
-
752
- ---
753
-
754
- ## Component Reference
755
-
756
- | Component | Category | Description |
757
- |-----------|----------|-------------|
758
- | `<SignIn>` | Authentication | Sign-in card (PKCE redirect or password form) |
759
- | `<SignUp>` | Authentication | Sign-up card |
760
- | `<AuthCallback>` | Authentication | OAuth callback handler |
761
- | `<UserButton>` | User | Avatar + dropdown menu |
762
- | `<UserAvatar>` | User | Standalone avatar (image or initials) |
763
- | `<UserProfile>` | User | Full account profile card |
764
- | `<Protect>` | Authorization | Conditional render by permission |
765
- | `<SignedIn>` | Control | Show children when authenticated |
766
- | `<SignedOut>` | Control | Show children when unauthenticated |
767
- | `<RedirectToSignIn>` | Control | Auto-redirect to sign-in |
768
- | `<SignInButton>` | Unstyled | Headless sign-in trigger |
769
- | `<SignUpButton>` | Unstyled | Headless sign-up trigger |
770
- | `<SignOutButton>` | Unstyled | Headless sign-out trigger |
771
-
772
- ## Hook Reference
773
-
774
- | Hook | Description |
775
- |------|-------------|
776
- | `useAuth()` | Full auth context (user, state, actions) |
777
- | `useUser()` | Current user object |
778
- | `useSignIn()` | Sign-in utilities |
779
- | `useSession()` | Session state and token access |
780
- | `useLumoAuth()` | Configured authorization SDK client |
781
- | `usePermission(slug)` | RBAC permission check |
782
- | `useZanzibar(req)` | ReBAC relationship check |
783
- | `useAbac(req)` | ABAC policy check |
784
- | `useMagicLink()` | Send passwordless magic-link email |
785
- | `useEmailFirst()` | Check if email account exists (email-first flow) |
786
-
787
- ---
788
-
789
- ## License
790
-
791
- MIT
547
+ |---|---|---|
548
+ | `theme` | `'light' \| 'dark'` | Force a theme. The default follows the system setting. |
549
+ | `className` | `string` | Extra class on the component's root element |
550
+ | `variables` | `Record<string, string>` | Values for CSS custom properties |
551
+
552
+ Commonly changed properties: `--la-primary`, `--la-primary-hover`, `--la-bg`,
553
+ `--la-text-primary`, `--la-text-secondary`, `--la-border`, `--la-radius-md` and
554
+ `--la-font-family`. The stylesheet defines more for spacing, shadows, font sizes and states.
555
+
556
+ ## Sign-in strategies
557
+
558
+ **PKCE (default).** The user goes to the LumoAuth sign-in page and comes back to your callback
559
+ route. This is the right choice for browser apps. LumoAuth handles passwords, passkeys, social
560
+ sign-in and MFA on that page.
561
+
562
+ **Password.** `authStrategy="password"` shows an email and password form in `<SignIn>` and uses
563
+ the older resource-owner password grant. The organization must allow it. Use PKCE for new apps.
564
+
565
+ ```tsx
566
+ <LumoAuthProvider domain="https://app.lumoauth.dev" orgId="acme-corp" clientId="abc" authStrategy="password">
567
+ ```
568
+
569
+ To keep your own form but still use PKCE, call `useLumoAuth().auth.loginWithPassword()` and then
570
+ `signIn()`. The [client README](../client/README.md#passwordless-email-first-and-embedded-sign-in)
571
+ explains the flow, and the example app shows it on its `/embedded` page.
572
+
573
+ ## Errors
574
+
575
+ The hooks and `<Protect>` catch errors and report them as `allowed: false`. `<AuthCallback>`
576
+ shows sign-in errors through its `error` prop. When you call the client from `useLumoAuth()`
577
+ yourself, it throws the error classes that are described in the
578
+ [client README](../client/README.md#errors). For example, a missing scope throws a
579
+ `LumoAuthPermissionDeniedError` with `requiredScopes`.
580
+
581
+ ## API reference
582
+
583
+ | Export | Kind | Purpose |
584
+ |---|---|---|
585
+ | `LumoAuthProvider` | provider | Holds the session. Wrap the app once. |
586
+ | `SignIn`, `SignUp` | component | Sign-in and sign-up cards |
587
+ | `AuthCallback` | component | Finishes sign-in on the callback route |
588
+ | `UserButton`, `UserAvatar`, `UserProfile` | component | User menu, avatar and profile card |
589
+ | `Protect` | component | Renders children when a permission, relationship or policy allows it |
590
+ | `SignedIn`, `SignedOut` | component | Render by sign-in state |
591
+ | `RedirectToSignIn` | component | Starts sign-in when rendered |
592
+ | `SignInButton`, `SignUpButton`, `SignOutButton` | component | Unstyled triggers |
593
+ | `useAuth()` | hook | Full auth context |
594
+ | `useUser()` | hook | `LumoAuthUser \| null` |
595
+ | `useSignIn()` | hook | `{ signIn, signInWithRedirect, isLoading }` |
596
+ | `useSession()` | hook | `{ isActive, isLoaded, getToken, status }` |
597
+ | `useLumoAuth()` | hook | A `LumoAuth` client that uses the session token |
598
+ | `usePermission(slug)` | hook | `{ allowed, isLoading }` |
599
+ | `useZanzibar(request)` | hook | `{ allowed, isLoading }` |
600
+ | `useAbac(request)` | hook | `{ allowed, isLoading }`; needs `abac:read` |
601
+ | `useMagicLink()` | hook | `{ sendMagicLink, isLoading, isSent, error, reset }` |
602
+ | `useEmailFirst()` | hook | `{ checkEmail, isLoading, result, exists, reset }` |
603
+ | `LumoAuth` | class | The browser client, re-exported from `@lumoauth/client` |
604
+
605
+ The prop and return types are exported too, for example `LumoAuthProviderProps`,
606
+ `LumoAuthUser`, `ProtectProps` and `UseEmailFirstReturn`.
607
+
608
+ ## Troubleshooting
609
+
610
+ | Symptom | Cause | Fix |
611
+ |---|---|---|
612
+ | `useAbac` and `<Protect abac={…}>` always deny | The token lacks `abac:read`. | Add `abac:read` to the provider's `scope` prop and to the OAuth client's allowed scopes, then sign in again. |
613
+ | `listSlugs()` throws `403` with `requiredScopes: ['authz:read']` | The token lacks `authz:read`. | Add `authz:read` to the `scope` prop and to the OAuth client, then sign in again. |
614
+ | `<Protect zanzibar={…}>` denies a user who has the relation | The tuple names the user by a different ID than the `sub` claim. | Write the tuple with the user's `sub`, or pass `subject` yourself. |
615
+ | `useZanzibar` about another user always denies | Asking about another subject needs `authz:check`. | Run that check on your server with a credential that holds `authz:check`. |
616
+ | The callback page shows a CORS error | Your origin is not in the OAuth client's allowed origins. | Add it in the LumoAuth dashboard. |
617
+ | The callback fails with a redirect URI error | `redirectUri` does not match a registered redirect URI exactly. | Register `<origin>/auth/callback`, or pass the registered value as `redirectUri`. |
618
+ | After sign-out, the user is signed straight back in | `afterSignOutUrl` is not a registered post-logout redirect URI, so the LumoAuth session did not end. | Register the URL on the OAuth client. |
619
+ | `signUp()` throws in password mode | Inline registration is not available. | Use PKCE mode, which sends the user to the registration page. |
620
+ | The page shows signed-out content first, then the user | A client-side provider must load the session after the page renders. | Use `@lumoauth/nextjs` for server-rendered sessions. |
621
+
622
+ ## Versioning and compatibility
623
+
624
+ This package is version 1.0.0. It needs LumoAuth server API 1.0.0 or newer, React 18 or newer,
625
+ and `@lumoauth/client` 1.0.0.
626
+
627
+ ## Related packages
628
+
629
+ | Package | Relationship |
630
+ |---|---|
631
+ | [`@lumoauth/nextjs`](../nextjs/README.md) | Re-exports this package and adds server-side sessions for Next.js |
632
+ | [`@lumoauth/client`](../client/README.md) | The client, session runtime and storage adapters underneath |
633
+ | [`@lumoauth/express`](../express/README.md), [`@lumoauth/backend`](../backend/README.md) | Server side |
634
+ | [`create-lumo-agent`](../create-lumo-agent/README.md) | Creates a Next.js agent app that uses this package for sign-in |
635
+ | [Workspace README](../../README.md) | How the packages fit together |
636
+
637
+ More: [React quickstart](https://docs.lumoauth.dev/quickstarts/react/),
638
+ [SDK overview](https://docs.lumoauth.dev/developer/sdks/), and the
639
+ [example app](../../examples/nextjs/README.md), which uses every component and hook.
640
+
641
+ ## Licence
642
+
643
+ [MIT](./LICENSE)