@lumoauth/react 0.0.0-stage → 1.1.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/LICENSE +21 -0
- package/README.md +642 -2
- package/dist/index.d.mts +686 -0
- package/dist/index.d.ts +686 -0
- package/dist/index.js +2499 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +2451 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +67 -5
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LumoAuth LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,643 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @lumoauth/react
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@lumoauth/react)
|
|
4
|
+
[](./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
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm install @lumoauth/react
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`@lumoauth/client` is installed with it and re-exported as `LumoAuth`, so one install is enough.
|
|
62
|
+
|
|
63
|
+
## Quick start
|
|
64
|
+
|
|
65
|
+
**1. Wrap the app in the provider.**
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
import { LumoAuthProvider } from '@lumoauth/react';
|
|
69
|
+
|
|
70
|
+
export function App() {
|
|
71
|
+
return (
|
|
72
|
+
<LumoAuthProvider
|
|
73
|
+
domain="https://app.lumoauth.dev" // EU region: https://eu.app.lumoauth.dev
|
|
74
|
+
orgId="acme-corp"
|
|
75
|
+
clientId="your-client-id"
|
|
76
|
+
afterSignInUrl="/dashboard"
|
|
77
|
+
>
|
|
78
|
+
<Routes />
|
|
79
|
+
</LumoAuthProvider>
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**2. Add a callback page.** By default the provider sends users back to
|
|
85
|
+
`<your origin>/auth/callback`. Mount `<AuthCallback>` on that route:
|
|
86
|
+
|
|
87
|
+
```tsx
|
|
88
|
+
import { AuthCallback } from '@lumoauth/react';
|
|
89
|
+
|
|
90
|
+
export function CallbackPage() {
|
|
91
|
+
return <AuthCallback afterSignInUrl="/dashboard" />;
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**3. Show a sign-in button or the user menu.**
|
|
96
|
+
|
|
97
|
+
```tsx
|
|
98
|
+
import { SignedIn, SignedOut, SignInButton, UserButton } from '@lumoauth/react';
|
|
99
|
+
|
|
100
|
+
export function Header() {
|
|
101
|
+
return (
|
|
102
|
+
<nav>
|
|
103
|
+
<SignedOut><SignInButton>Sign in</SignInButton></SignedOut>
|
|
104
|
+
<SignedIn><UserButton showName /></SignedIn>
|
|
105
|
+
</nav>
|
|
106
|
+
);
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**4. Show content only to users who hold a permission.**
|
|
111
|
+
|
|
112
|
+
```tsx
|
|
113
|
+
import { Protect } from '@lumoauth/react';
|
|
114
|
+
|
|
115
|
+
<Protect permission="admin.dashboard" fallback={<p>You do not have access.</p>}>
|
|
116
|
+
<AdminPanel />
|
|
117
|
+
</Protect>
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Core concepts
|
|
121
|
+
|
|
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.
|
|
125
|
+
|
|
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.
|
|
129
|
+
|
|
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:
|
|
134
|
+
|
|
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).
|
|
145
|
+
|
|
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.
|
|
171
|
+
|
|
172
|
+
```tsx
|
|
173
|
+
import { localStorageAdapter } from '@lumoauth/client';
|
|
174
|
+
|
|
175
|
+
<LumoAuthProvider domain={domain} orgId={orgId} clientId={clientId} storage={localStorageAdapter()}>
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Create the adapter once, outside the component, or with `useMemo`. A new adapter on each render
|
|
179
|
+
rebuilds the session.
|
|
180
|
+
|
|
181
|
+
## Components
|
|
182
|
+
|
|
183
|
+
### Sign-in and sign-up
|
|
184
|
+
|
|
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.
|
|
188
|
+
|
|
189
|
+
```tsx
|
|
190
|
+
<SignIn afterSignInUrl="/dashboard" signUpUrl="/sign-up" socialProviders={['google', 'github']} />
|
|
191
|
+
```
|
|
192
|
+
|
|
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.
|
|
202
|
+
|
|
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.
|
|
206
|
+
|
|
207
|
+
```tsx
|
|
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.
|
|
213
|
+
|
|
214
|
+
```tsx
|
|
215
|
+
<AuthCallback
|
|
216
|
+
afterSignInUrl="/dashboard"
|
|
217
|
+
loading={<Spinner />}
|
|
218
|
+
error={(message) => <ErrorCard message={message} />}
|
|
219
|
+
/>
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
| Prop | Type | Description |
|
|
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 |
|
|
227
|
+
|
|
228
|
+
### User
|
|
229
|
+
|
|
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.
|
|
232
|
+
|
|
233
|
+
```tsx
|
|
234
|
+
<UserButton showName afterSignOutUrl="/" />
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
| Prop | Type | Default | Description |
|
|
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 |
|
|
242
|
+
|
|
243
|
+
**`<UserAvatar>`** shows the user's picture or initials. It shows a placeholder icon when nobody
|
|
244
|
+
is signed in.
|
|
245
|
+
|
|
246
|
+
```tsx
|
|
247
|
+
<UserAvatar />
|
|
248
|
+
<UserAvatar size={48} shape="square" />
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
| Prop | Type | Default |
|
|
252
|
+
|---|---|---|
|
|
253
|
+
| `size` | `number` (pixels) | `32` |
|
|
254
|
+
| `shape` | `'circle' \| 'square'` | `'circle'` |
|
|
255
|
+
| `appearance` | `AppearanceProps` | none |
|
|
256
|
+
|
|
257
|
+
**`<UserProfile>`** shows a profile card with account details, security status, roles, groups and
|
|
258
|
+
a sign-out button.
|
|
259
|
+
|
|
260
|
+
```tsx
|
|
261
|
+
<UserProfile afterSignOutUrl="/" />
|
|
262
|
+
<UserProfile mode="compact" /> {/* account details only */}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
| Prop | Type | Default | Description |
|
|
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 |
|
|
270
|
+
|
|
271
|
+
### Access checks
|
|
272
|
+
|
|
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`.
|
|
276
|
+
|
|
277
|
+
```tsx
|
|
278
|
+
// A permission (RBAC)
|
|
279
|
+
<Protect permission="admin.dashboard" fallback={<p>You do not have access.</p>}>
|
|
280
|
+
<AdminPanel />
|
|
281
|
+
</Protect>
|
|
282
|
+
|
|
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>
|
|
287
|
+
|
|
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>
|
|
292
|
+
```
|
|
293
|
+
|
|
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 |
|
|
301
|
+
|
|
302
|
+
Any error during the check, such as a missing scope, counts as denied.
|
|
303
|
+
|
|
304
|
+
### Show content by sign-in state
|
|
305
|
+
|
|
306
|
+
```tsx
|
|
307
|
+
<SignedIn><p>Welcome back.</p></SignedIn>
|
|
308
|
+
<SignedOut><SignIn /></SignedOut>
|
|
309
|
+
```
|
|
310
|
+
|
|
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.
|
|
313
|
+
|
|
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.
|
|
316
|
+
|
|
317
|
+
```tsx
|
|
318
|
+
<SignedOut><RedirectToSignIn /></SignedOut>
|
|
319
|
+
<SignedIn><Dashboard /></SignedIn>
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
### Unstyled buttons
|
|
323
|
+
|
|
324
|
+
These buttons have no styling of their own. Put your own markup inside them.
|
|
325
|
+
|
|
326
|
+
```tsx
|
|
327
|
+
<SignInButton><button className="btn">Log in</button></SignInButton>
|
|
328
|
+
<SignUpButton signUpUrl="/register" />
|
|
329
|
+
<SignOutButton afterSignOutUrl="/"><button className="btn">Log out</button></SignOutButton>
|
|
330
|
+
```
|
|
331
|
+
|
|
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 |
|
|
337
|
+
|
|
338
|
+
## Hooks
|
|
339
|
+
|
|
340
|
+
Every hook must be called inside `<LumoAuthProvider>`.
|
|
341
|
+
|
|
342
|
+
**`useAuth()`** returns the full auth context.
|
|
343
|
+
|
|
344
|
+
```tsx
|
|
345
|
+
const { user, isSignedIn, isLoaded, signIn, signOut, getToken } = useAuth();
|
|
346
|
+
|
|
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>;
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
| Property | Type | Description |
|
|
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`.
|
|
371
|
+
|
|
372
|
+
| Field | Type | Description |
|
|
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 |
|
|
384
|
+
|
|
385
|
+
The user comes from the OIDC UserInfo endpoint. A field is empty when the response does not
|
|
386
|
+
contain it.
|
|
387
|
+
|
|
388
|
+
**`useSignIn()`** returns `{ signIn, signInWithRedirect, isLoading }`.
|
|
389
|
+
|
|
390
|
+
**`useSession()`** returns `{ isActive, isLoaded, getToken, status }`. Use `getToken()` to call
|
|
391
|
+
your own API:
|
|
392
|
+
|
|
393
|
+
```tsx
|
|
394
|
+
const { getToken } = useSession();
|
|
395
|
+
const res = await fetch('/api/data', { headers: { Authorization: `Bearer ${await getToken()}` } });
|
|
396
|
+
```
|
|
397
|
+
|
|
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.
|
|
400
|
+
|
|
401
|
+
```tsx
|
|
402
|
+
const client = useLumoAuth();
|
|
403
|
+
const canEdit = await client.permissions.check('document.edit');
|
|
404
|
+
```
|
|
405
|
+
|
|
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.
|
|
408
|
+
|
|
409
|
+
```tsx
|
|
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' });
|
|
413
|
+
```
|
|
414
|
+
|
|
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).
|
|
417
|
+
|
|
418
|
+
**`useMagicLink()`** returns `{ sendMagicLink, isLoading, isSent, error, reset }`:
|
|
419
|
+
|
|
420
|
+
```tsx
|
|
421
|
+
function PasswordlessForm() {
|
|
422
|
+
const [email, setEmail] = useState('');
|
|
423
|
+
const { sendMagicLink, isLoading, isSent, error, reset } = useMagicLink();
|
|
424
|
+
|
|
425
|
+
if (isSent) {
|
|
426
|
+
return (
|
|
427
|
+
<p>
|
|
428
|
+
We sent a sign-in link to <strong>{email}</strong>.{' '}
|
|
429
|
+
<button onClick={reset}>Use a different email</button>
|
|
430
|
+
</p>
|
|
431
|
+
);
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
return (
|
|
435
|
+
<form onSubmit={(e) => { e.preventDefault(); sendMagicLink(email); }}>
|
|
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>
|
|
438
|
+
{error && <p className="error">{error}</p>}
|
|
439
|
+
</form>
|
|
440
|
+
);
|
|
441
|
+
}
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
`isSent` becomes `true` whether or not the account exists. The server never reveals that.
|
|
445
|
+
|
|
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.
|
|
451
|
+
|
|
452
|
+
```tsx
|
|
453
|
+
const { checkEmail, isLoading } = useEmailFirst();
|
|
454
|
+
|
|
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
|
|
461
|
+
}
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
## Common patterns
|
|
465
|
+
|
|
466
|
+
<details>
|
|
467
|
+
<summary><strong>A navigation bar that swaps sign-in links for the user menu</strong></summary>
|
|
468
|
+
|
|
469
|
+
```tsx
|
|
470
|
+
import { SignedIn, SignedOut, UserButton, SignInButton, SignUpButton } from '@lumoauth/react';
|
|
471
|
+
|
|
472
|
+
export function Navbar() {
|
|
473
|
+
return (
|
|
474
|
+
<nav className="navbar">
|
|
475
|
+
<a href="/">My App</a>
|
|
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>
|
|
483
|
+
</nav>
|
|
484
|
+
);
|
|
485
|
+
}
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
</details>
|
|
489
|
+
|
|
490
|
+
<details>
|
|
491
|
+
<summary><strong>A route that needs a signed-in user</strong></summary>
|
|
492
|
+
|
|
493
|
+
```tsx
|
|
494
|
+
import { SignedIn, SignedOut, RedirectToSignIn } from '@lumoauth/react';
|
|
495
|
+
|
|
496
|
+
export function ProtectedRoute({ children }: { children: React.ReactNode }) {
|
|
497
|
+
return (
|
|
498
|
+
<>
|
|
499
|
+
<SignedOut><RedirectToSignIn /></SignedOut>
|
|
500
|
+
<SignedIn>{children}</SignedIn>
|
|
501
|
+
</>
|
|
502
|
+
);
|
|
503
|
+
}
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
</details>
|
|
507
|
+
|
|
508
|
+
<details>
|
|
509
|
+
<summary><strong>Calling your API with the user's token</strong></summary>
|
|
510
|
+
|
|
511
|
+
```tsx
|
|
512
|
+
import { useSession } from '@lumoauth/react';
|
|
513
|
+
import { useEffect, useState } from 'react';
|
|
514
|
+
|
|
515
|
+
export function DataView() {
|
|
516
|
+
const { isActive, getToken } = useSession();
|
|
517
|
+
const [data, setData] = useState(null);
|
|
518
|
+
|
|
519
|
+
useEffect(() => {
|
|
520
|
+
if (!isActive) return;
|
|
521
|
+
getToken().then((token) =>
|
|
522
|
+
fetch('/api/data', { headers: { Authorization: `Bearer ${token}` } })
|
|
523
|
+
.then((r) => r.json())
|
|
524
|
+
.then(setData),
|
|
525
|
+
);
|
|
526
|
+
}, [isActive, getToken]);
|
|
527
|
+
|
|
528
|
+
return data ? <pre>{JSON.stringify(data, null, 2)}</pre> : <p>Loading…</p>;
|
|
529
|
+
}
|
|
530
|
+
```
|
|
531
|
+
|
|
532
|
+
</details>
|
|
533
|
+
|
|
534
|
+
## Appearance
|
|
535
|
+
|
|
536
|
+
Every ready-made component accepts an `appearance` prop:
|
|
537
|
+
|
|
538
|
+
```tsx
|
|
539
|
+
<SignIn appearance={{
|
|
540
|
+
theme: 'dark',
|
|
541
|
+
className: 'my-card',
|
|
542
|
+
variables: { '--la-primary': '#6366f1' },
|
|
543
|
+
}} />
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
| Option | Type | Description |
|
|
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)
|