@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/README.md CHANGED
@@ -1,3 +1,791 @@
1
- # Temporary Holding Version
1
+ # @lumoauth/react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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