@lumoauth/react 0.0.0-stage → 1.0.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 +790 -2
- package/dist/index.d.mts +678 -0
- package/dist/index.d.ts +678 -0
- package/dist/index.js +2472 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +2424 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +66 -5
package/README.md
CHANGED
|
@@ -1,3 +1,791 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @lumoauth/react
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install @lumoauth/react @lumoauth/client
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
### 2. Wrap your app with the provider
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
import { LumoAuthProvider } from '@lumoauth/react';
|
|
31
|
+
|
|
32
|
+
function App() {
|
|
33
|
+
return (
|
|
34
|
+
<LumoAuthProvider
|
|
35
|
+
domain="https://auth.example.com"
|
|
36
|
+
orgId="acme-corp"
|
|
37
|
+
clientId="your-client-id"
|
|
38
|
+
afterSignInUrl="/dashboard"
|
|
39
|
+
afterSignOutUrl="/"
|
|
40
|
+
>
|
|
41
|
+
<Router />
|
|
42
|
+
</LumoAuthProvider>
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### 3. Add a callback route
|
|
48
|
+
|
|
49
|
+
```tsx
|
|
50
|
+
import { AuthCallback } from '@lumoauth/react';
|
|
51
|
+
|
|
52
|
+
// Mount at /auth/callback (or your custom redirectUri)
|
|
53
|
+
function CallbackPage() {
|
|
54
|
+
return <AuthCallback afterSignInUrl="/dashboard" />;
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### 4. Show sign-in or user profile based on session
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
import { SignedIn, SignedOut, SignIn, UserButton } from '@lumoauth/react';
|
|
62
|
+
|
|
63
|
+
function Header() {
|
|
64
|
+
return (
|
|
65
|
+
<nav>
|
|
66
|
+
<SignedOut>
|
|
67
|
+
<SignIn />
|
|
68
|
+
</SignedOut>
|
|
69
|
+
<SignedIn>
|
|
70
|
+
<UserButton showName />
|
|
71
|
+
</SignedIn>
|
|
72
|
+
</nav>
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Provider
|
|
80
|
+
|
|
81
|
+
### `<LumoAuthProvider>`
|
|
82
|
+
|
|
83
|
+
Wrap your application to manage auth state globally.
|
|
84
|
+
|
|
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 |
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## Authentication Components
|
|
99
|
+
|
|
100
|
+
### `<SignIn>`
|
|
101
|
+
|
|
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.
|
|
103
|
+
|
|
104
|
+
```tsx
|
|
105
|
+
import { SignIn } from '@lumoauth/react';
|
|
106
|
+
|
|
107
|
+
<SignIn
|
|
108
|
+
afterSignInUrl="/dashboard"
|
|
109
|
+
signUpUrl="/sign-up"
|
|
110
|
+
appearance={{ theme: 'dark' }}
|
|
111
|
+
/>
|
|
112
|
+
```
|
|
113
|
+
|
|
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 |
|
|
119
|
+
|
|
120
|
+
### `<SignUp>`
|
|
121
|
+
|
|
122
|
+
Registration component. PKCE mode redirects to hosted signup; password mode shows inline form.
|
|
123
|
+
|
|
124
|
+
```tsx
|
|
125
|
+
import { SignUp } from '@lumoauth/react';
|
|
126
|
+
|
|
127
|
+
<SignUp afterSignUpUrl="/onboarding" signInUrl="/sign-in" />
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### `<AuthCallback>`
|
|
131
|
+
|
|
132
|
+
Handles the OAuth redirect callback. Place on your callback route.
|
|
133
|
+
|
|
134
|
+
```tsx
|
|
135
|
+
import { AuthCallback } from '@lumoauth/react';
|
|
136
|
+
|
|
137
|
+
// Route: /auth/callback
|
|
138
|
+
<AuthCallback
|
|
139
|
+
afterSignInUrl="/dashboard"
|
|
140
|
+
loading={<MyCustomSpinner />}
|
|
141
|
+
error={(msg) => <MyErrorCard message={msg} />}
|
|
142
|
+
/>
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
| 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
|
+
---
|
|
152
|
+
|
|
153
|
+
## User Components
|
|
154
|
+
|
|
155
|
+
### `<UserButton>`
|
|
156
|
+
|
|
157
|
+
Avatar button with a dropdown menu for account management and sign-out. Only visible when signed in.
|
|
158
|
+
|
|
159
|
+
```tsx
|
|
160
|
+
import { UserButton } from '@lumoauth/react';
|
|
161
|
+
|
|
162
|
+
<UserButton showName afterSignOutUrl="/" />
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
| 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 |
|
|
170
|
+
|
|
171
|
+
### `<UserAvatar>`
|
|
172
|
+
|
|
173
|
+
Renders the user's profile image or initials. Shows a placeholder icon when not signed in.
|
|
174
|
+
|
|
175
|
+
```tsx
|
|
176
|
+
import { UserAvatar } from '@lumoauth/react';
|
|
177
|
+
|
|
178
|
+
// Default circle avatar
|
|
179
|
+
<UserAvatar />
|
|
180
|
+
|
|
181
|
+
// Large square avatar
|
|
182
|
+
<UserAvatar size={48} shape="square" />
|
|
183
|
+
```
|
|
184
|
+
|
|
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>`
|
|
192
|
+
|
|
193
|
+
Full profile card showing account details, security status, roles, groups, and sign-out.
|
|
194
|
+
|
|
195
|
+
```tsx
|
|
196
|
+
import { UserProfile } from '@lumoauth/react';
|
|
197
|
+
|
|
198
|
+
// Full profile card
|
|
199
|
+
<UserProfile afterSignOutUrl="/" />
|
|
200
|
+
|
|
201
|
+
// Compact mode (hides security and roles sections)
|
|
202
|
+
<UserProfile mode="compact" />
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
| 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
|
|
214
|
+
|
|
215
|
+
### `<SignedIn>` / `<SignedOut>`
|
|
216
|
+
|
|
217
|
+
Conditional rendering based on authentication state.
|
|
218
|
+
|
|
219
|
+
```tsx
|
|
220
|
+
import { SignedIn, SignedOut } from '@lumoauth/react';
|
|
221
|
+
|
|
222
|
+
function Page() {
|
|
223
|
+
return (
|
|
224
|
+
<>
|
|
225
|
+
<SignedIn>
|
|
226
|
+
<p>Welcome back! You are signed in.</p>
|
|
227
|
+
<UserProfile />
|
|
228
|
+
</SignedIn>
|
|
229
|
+
|
|
230
|
+
<SignedOut>
|
|
231
|
+
<p>Please sign in to continue.</p>
|
|
232
|
+
<SignIn />
|
|
233
|
+
</SignedOut>
|
|
234
|
+
</>
|
|
235
|
+
);
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### `<RedirectToSignIn>`
|
|
240
|
+
|
|
241
|
+
Automatically redirects unauthenticated users to the sign-in flow.
|
|
242
|
+
|
|
243
|
+
```tsx
|
|
244
|
+
import { SignedOut, RedirectToSignIn } from '@lumoauth/react';
|
|
245
|
+
|
|
246
|
+
function ProtectedPage() {
|
|
247
|
+
return (
|
|
248
|
+
<>
|
|
249
|
+
<SignedOut>
|
|
250
|
+
<RedirectToSignIn />
|
|
251
|
+
</SignedOut>
|
|
252
|
+
<SignedIn>
|
|
253
|
+
<Dashboard />
|
|
254
|
+
</SignedIn>
|
|
255
|
+
</>
|
|
256
|
+
);
|
|
257
|
+
}
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## Unstyled Components
|
|
263
|
+
|
|
264
|
+
Headless components without built-in UI — bring your own markup.
|
|
265
|
+
|
|
266
|
+
### `<SignInButton>`
|
|
267
|
+
|
|
268
|
+
```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>
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### `<SignUpButton>`
|
|
281
|
+
|
|
282
|
+
```tsx
|
|
283
|
+
import { SignUpButton } from '@lumoauth/react';
|
|
284
|
+
<SignUpButton signUpUrl="/register" />
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
### `<SignOutButton>`
|
|
288
|
+
|
|
289
|
+
```tsx
|
|
290
|
+
import { SignOutButton } from '@lumoauth/react';
|
|
291
|
+
|
|
292
|
+
<SignOutButton afterSignOutUrl="/">
|
|
293
|
+
<button className="my-btn">Log out</button>
|
|
294
|
+
</SignOutButton>
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## Hooks
|
|
300
|
+
|
|
301
|
+
### `useAuth()`
|
|
302
|
+
|
|
303
|
+
Primary hook — returns the full auth context.
|
|
304
|
+
|
|
305
|
+
```tsx
|
|
306
|
+
import { useAuth } from '@lumoauth/react';
|
|
307
|
+
|
|
308
|
+
function MyComponent() {
|
|
309
|
+
const { user, isSignedIn, isLoaded, signIn, signOut, getToken } = useAuth();
|
|
310
|
+
|
|
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
|
+
}
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
#### Return value
|
|
324
|
+
|
|
325
|
+
| 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
|
|
351
|
+
|
|
352
|
+
| 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()`
|
|
368
|
+
|
|
369
|
+
```tsx
|
|
370
|
+
import { useSignIn } from '@lumoauth/react';
|
|
371
|
+
|
|
372
|
+
const { signIn, signInWithRedirect, isLoading } = useSignIn();
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
### `useSession()`
|
|
376
|
+
|
|
377
|
+
```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
|
+
}
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
### `useLumoAuth()`
|
|
393
|
+
|
|
394
|
+
Returns a configured `LumoAuth` SDK client for authorization checks. Token is auto-managed.
|
|
395
|
+
|
|
396
|
+
```tsx
|
|
397
|
+
import { useLumoAuth } from '@lumoauth/react';
|
|
398
|
+
|
|
399
|
+
const client = useLumoAuth();
|
|
400
|
+
const canEdit = await client.permissions.check('documents.edit');
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
### `usePermission(slug)`
|
|
404
|
+
|
|
405
|
+
```tsx
|
|
406
|
+
import { usePermission } from '@lumoauth/react';
|
|
407
|
+
|
|
408
|
+
const { allowed, isLoading } = usePermission('documents.edit');
|
|
409
|
+
```
|
|
410
|
+
|
|
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
|
+
```
|
|
422
|
+
|
|
423
|
+
### `useAbac(request)`
|
|
424
|
+
|
|
425
|
+
```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
|
+
function PasswordlessForm() {
|
|
443
|
+
const [email, setEmail] = useState('');
|
|
444
|
+
const { sendMagicLink, isLoading, isSent, error, reset } = useMagicLink();
|
|
445
|
+
|
|
446
|
+
if (isSent) {
|
|
447
|
+
return (
|
|
448
|
+
<div>
|
|
449
|
+
<p>Check your inbox — we sent a sign-in link to <strong>{email}</strong>.</p>
|
|
450
|
+
<button onClick={reset}>Use a different email</button>
|
|
451
|
+
</div>
|
|
452
|
+
);
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
return (
|
|
456
|
+
<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>
|
|
466
|
+
{error && <p className="error">{error}</p>}
|
|
467
|
+
</form>
|
|
468
|
+
);
|
|
469
|
+
}
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
#### Return value
|
|
473
|
+
|
|
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.
|
|
485
|
+
|
|
486
|
+
```tsx
|
|
487
|
+
import { useEmailFirst } from '@lumoauth/react';
|
|
488
|
+
|
|
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
|
+
);
|
|
519
|
+
}
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
#### Return value
|
|
523
|
+
|
|
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:
|
|
565
|
+
|
|
566
|
+
```tsx
|
|
567
|
+
import {
|
|
568
|
+
SignedIn, SignedOut,
|
|
569
|
+
UserButton, SignInButton, SignUpButton,
|
|
570
|
+
} from '@lumoauth/react';
|
|
571
|
+
|
|
572
|
+
function Navbar() {
|
|
573
|
+
return (
|
|
574
|
+
<nav className="navbar">
|
|
575
|
+
<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>
|
|
587
|
+
</nav>
|
|
588
|
+
);
|
|
589
|
+
}
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
### Protected routes
|
|
593
|
+
|
|
594
|
+
Redirect unauthenticated users automatically:
|
|
595
|
+
|
|
596
|
+
```tsx
|
|
597
|
+
import { SignedIn, SignedOut, RedirectToSignIn } from '@lumoauth/react';
|
|
598
|
+
|
|
599
|
+
function ProtectedRoute({ children }: { children: React.ReactNode }) {
|
|
600
|
+
return (
|
|
601
|
+
<>
|
|
602
|
+
<SignedOut>
|
|
603
|
+
<RedirectToSignIn />
|
|
604
|
+
</SignedOut>
|
|
605
|
+
<SignedIn>
|
|
606
|
+
{children}
|
|
607
|
+
</SignedIn>
|
|
608
|
+
</>
|
|
609
|
+
);
|
|
610
|
+
}
|
|
611
|
+
|
|
612
|
+
// Usage
|
|
613
|
+
<ProtectedRoute>
|
|
614
|
+
<Dashboard />
|
|
615
|
+
</ProtectedRoute>
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
### Fetching data with session token
|
|
619
|
+
|
|
620
|
+
```tsx
|
|
621
|
+
import { useSession } from '@lumoauth/react';
|
|
622
|
+
import { useEffect, useState } from 'react';
|
|
623
|
+
|
|
624
|
+
function DataView() {
|
|
625
|
+
const { isActive, getToken } = useSession();
|
|
626
|
+
const [data, setData] = useState(null);
|
|
627
|
+
|
|
628
|
+
useEffect(() => {
|
|
629
|
+
if (!isActive) return;
|
|
630
|
+
|
|
631
|
+
getToken().then((token) => {
|
|
632
|
+
fetch('/api/data', {
|
|
633
|
+
headers: { Authorization: `Bearer ${token}` },
|
|
634
|
+
})
|
|
635
|
+
.then((r) => r.json())
|
|
636
|
+
.then(setData);
|
|
637
|
+
});
|
|
638
|
+
}, [isActive, getToken]);
|
|
639
|
+
|
|
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
|
+
);
|
|
686
|
+
}
|
|
687
|
+
```
|
|
688
|
+
|
|
689
|
+
---
|
|
690
|
+
|
|
691
|
+
## Appearance
|
|
692
|
+
|
|
693
|
+
All pre-built components accept an `appearance` prop:
|
|
694
|
+
|
|
695
|
+
```tsx
|
|
696
|
+
<SignIn appearance={{
|
|
697
|
+
theme: 'dark',
|
|
698
|
+
className: 'my-custom-card',
|
|
699
|
+
variables: { '--la-primary': '#6366f1' },
|
|
700
|
+
}} />
|
|
701
|
+
```
|
|
702
|
+
|
|
703
|
+
| 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
|