@lumoauth/react 1.4.1 → 1.5.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
@@ -255,7 +255,8 @@ is signed in.
255
255
  | `appearance` | `AppearanceProps` | none |
256
256
 
257
257
  **`<UserProfile>`** shows a profile card with account details, security status, roles, groups and
258
- a sign-out button.
258
+ a sign-out button. The MFA row, the roles and the groups appear only when the UserInfo response
259
+ holds the `mfa_enabled`, `roles` and `groups` claims. With the default scopes it holds none of them.
259
260
 
260
261
  ```tsx
261
262
  <UserProfile afterSignOutUrl="/" />
@@ -362,7 +363,7 @@ return <button onClick={() => signOut()}>Sign out {user!.displayName}</button>;
362
363
  | `signOut({ afterSignOutUrl? })` | function | Revokes the access token, clears local tokens, and ends the LumoAuth session through the logout endpoint |
363
364
  | `getToken()` | `() => Promise<string \| null>` | A valid access token. It refreshes first when needed. |
364
365
  | `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
+ | `sendMagicLink(email, returnTo?, { captchaToken? }?)` | function | Emails a sign-in link. Rejects with a `LumoAuthApiError` when the server refuses the request. |
366
367
  | `checkEmail(email)` | `(email) => Promise<EmailCheckResult>` | Reports the sign-in methods for an email address |
367
368
  | `authStrategy` | `'pkce' \| 'password'` | The strategy in use |
368
369
  | `config` | object | The provider's `domain`, `orgId`, `clientId` and redirect URLs |
@@ -415,7 +416,7 @@ const canRead = useAbac({ resourceType: 'document', action: 'read', resourceId:
415
416
  A Zanzibar check about a user other than the signed-in user needs the `authz:check` scope or
416
417
  permission. `useAbac` needs `abac:read`; see [Core concepts](#core-concepts).
417
418
 
418
- **`useMagicLink()`** returns `{ sendMagicLink, isLoading, isSent, error, reset }`:
419
+ **`useMagicLink()`** returns `{ sendMagicLink, isLoading, isSent, error, errorCode, reset }`:
419
420
 
420
421
  ```tsx
421
422
  function PasswordlessForm() {
@@ -443,6 +444,30 @@ function PasswordlessForm() {
443
444
 
444
445
  `isSent` becomes `true` whether or not the account exists. The server never reveals that.
445
446
 
447
+ How the sign-in completes:
448
+
449
+ 1. The person opens the link from the email and confirms on the LumoAuth page. They are now
450
+ signed in at LumoAuth, in the browser that opened the link.
451
+ 2. LumoAuth sends them back to the page that the request was made from.
452
+ 3. `<LumoAuthProvider>` sees that they came back and starts the normal sign-in. It completes
453
+ without a prompt, and your app receives its tokens on the callback page.
454
+
455
+ To send the person to another page of your app, pass it as the second argument:
456
+ `sendMagicLink(email, 'https://myapp.example.com/welcome')`. Call `signIn()` on that page.
457
+
458
+ What the request needs:
459
+
460
+ - The organization has sign-in links switched on (`magicLinkEnabled` from `checkEmail()`).
461
+ - The origin of your app is one of the allowed origins of the application (`clientId`).
462
+ - The return address is on an allowed origin or on the origin of a redirect URI of the
463
+ application, and has at most 1,024 characters.
464
+ - When the organization protects sign-in link requests with a CAPTCHA, render the widget in
465
+ your form and pass its token: `sendMagicLink(email, undefined, { captchaToken })`.
466
+
467
+ When the server refuses the request, `error` holds the message and `errorCode` the reason:
468
+ `magic_link_disabled`, `origin_not_allowed`, `invalid_return_to`, `captcha_required`,
469
+ `captcha_failed` or `rate_limited`.
470
+
446
471
  **`useEmailFirst()`** returns `{ checkEmail, isLoading, result, exists, reset }`. Use it to build
447
472
  a sign-in screen that asks for the email address first. `checkEmail(email)` resolves to an
448
473
  `EmailCheckResult`. It reports whether the account exists and which methods it can use:
@@ -545,13 +570,41 @@ Every ready-made component accepts an `appearance` prop:
545
570
 
546
571
  | Option | Type | Description |
547
572
  |---|---|---|
548
- | `theme` | `'light' \| 'dark'` | Force a theme. The default follows the system setting. |
573
+ | `theme` | `'light' \| 'dark'` | Force a theme for this component. The default follows the system setting. |
549
574
  | `className` | `string` | Extra class on the component's root element |
550
575
  | `variables` | `Record<string, string>` | Values for CSS custom properties |
551
576
 
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.
577
+ Commonly changed properties: `--la-primary`, `--la-primary-hover`, `--la-primary-text`, `--la-bg`,
578
+ `--la-text`, `--la-text-secondary`, `--la-border`, `--la-radius-md` and `--la-font-family`. The
579
+ stylesheet defines more for spacing, shadows, font sizes and states.
580
+
581
+ **Follow the theme of your app.** Without a choice the components follow the colour scheme of the
582
+ operating system, so a light app can get dark components. Choose the theme in one of three ways:
583
+
584
+ | Where | How |
585
+ |---|---|
586
+ | The whole app | `data-lumoauth-theme="light"` or `"dark"` on `<html>`, or the class `la-light` / `la-dark`. Change it when your theme switch changes. |
587
+ | A part of the page | The same attribute or class on any element that wraps the components |
588
+ | One component | `appearance={{ theme: 'light' }}` |
589
+
590
+ To use your own colours in both themes, map the properties to the design tokens of your app. The
591
+ values change with your theme, so the components follow it:
592
+
593
+ ```tsx
594
+ const appearance = {
595
+ variables: {
596
+ '--la-font-family': 'inherit',
597
+ '--la-bg': 'var(--card)',
598
+ '--la-text': 'var(--card-foreground)',
599
+ '--la-text-secondary': 'var(--muted-foreground)',
600
+ '--la-border': 'var(--border)',
601
+ '--la-primary': 'var(--primary)',
602
+ '--la-primary-text': 'var(--primary-foreground)',
603
+ },
604
+ };
605
+
606
+ <UserButton appearance={appearance} />
607
+ ```
555
608
 
556
609
  ## Sign-in strategies
557
610
 
@@ -598,7 +651,7 @@ yourself, it throws the error classes that are described in the
598
651
  | `usePermission(slug)` | hook | `{ allowed, isLoading }` |
599
652
  | `useZanzibar(request)` | hook | `{ allowed, isLoading }` |
600
653
  | `useAbac(request)` | hook | `{ allowed, isLoading }`; needs `abac:read` |
601
- | `useMagicLink()` | hook | `{ sendMagicLink, isLoading, isSent, error, reset }` |
654
+ | `useMagicLink()` | hook | `{ sendMagicLink, isLoading, isSent, error, errorCode, reset }` |
602
655
  | `useEmailFirst()` | hook | `{ checkEmail, isLoading, result, exists, reset }` |
603
656
  | `LumoAuth` | class | The browser client, re-exported from `@lumoauth/client` |
604
657
 
package/dist/index.d.mts CHANGED
@@ -18,7 +18,10 @@ interface LumoAuthUser {
18
18
  avatarUrl?: string;
19
19
  /** Whether email has been verified */
20
20
  emailVerified: boolean;
21
- /** Whether MFA is enabled */
21
+ /**
22
+ * Whether MFA is enabled. Also `false` when the UserInfo response has no
23
+ * `mfa_enabled` claim; check `claims.mfa_enabled` to tell the two apart.
24
+ */
22
25
  mfaEnabled: boolean;
23
26
  /** List of role slugs */
24
27
  roles: string[];
@@ -94,7 +97,12 @@ interface LumoAuthProviderProps {
94
97
  children: React.ReactNode;
95
98
  }
96
99
  interface AppearanceProps {
97
- /** Force light or dark theme (defaults to system preference) */
100
+ /**
101
+ * Force the light or the dark theme for this component. Without it the
102
+ * component follows the nearest ancestor that has the class `la-light` /
103
+ * `la-dark` or the attribute `data-lumoauth-theme="light" | "dark"`, and
104
+ * otherwise the colour scheme of the operating system.
105
+ */
98
106
  theme?: 'light' | 'dark';
99
107
  /** Override CSS custom properties */
100
108
  variables?: Record<string, string>;
@@ -218,7 +226,9 @@ interface UserProfileProps {
218
226
  afterSignOutUrl?: string;
219
227
  /**
220
228
  * Display mode:
221
- * - `'full'` — shows all sections (account, security, roles)
229
+ * - `'full'` — shows all sections (account, security, roles). The MFA
230
+ * row and the roles and groups appear only when the UserInfo response
231
+ * holds those claims.
222
232
  * - `'compact'` — shows only account details
223
233
  * @default 'full'
224
234
  */
@@ -236,16 +246,27 @@ interface RedirectToSignInProps {
236
246
  */
237
247
  interface UseMagicLinkReturn {
238
248
  /**
239
- * Send a magic sign-in link to the given email.
240
- * The server never reveals whether the email exists.
249
+ * Ask for a sign-in link to be mailed to the address. See
250
+ * {@link LumoAuthContextValue.sendMagicLink}. A refusal does not throw
251
+ * here: it sets `error` and `errorCode`.
241
252
  */
242
- sendMagicLink: (email: string, redirectUri?: string) => Promise<void>;
253
+ sendMagicLink: (email: string, returnTo?: string, options?: {
254
+ captchaToken?: string;
255
+ }) => Promise<void>;
243
256
  /** True while the request is in-flight */
244
257
  isLoading: boolean;
245
- /** True after the request completes (link was dispatched) */
258
+ /**
259
+ * True after the server accepted the request. It does not mean that the
260
+ * address belongs to an account: the server answers the same either way.
261
+ */
246
262
  isSent: boolean;
247
263
  /** Error message if the request failed */
248
264
  error: string | null;
265
+ /**
266
+ * The server's reason when it refused the request, for example
267
+ * `captcha_required`, `origin_not_allowed` or `rate_limited`; null otherwise.
268
+ */
269
+ errorCode: string | null;
249
270
  /** Reset sent/error state back to idle */
250
271
  reset: () => void;
251
272
  }
@@ -302,11 +323,21 @@ interface LumoAuthContextValue extends AuthState {
302
323
  /** Handle the OAuth callback — exchange code for tokens */
303
324
  handleCallback: () => Promise<void>;
304
325
  /**
305
- * Request a magic sign-in link for the given email.
306
- * Shows a "Check your inbox" page — works for both email-first and
307
- * magic-link-only organization configurations.
326
+ * Ask for a sign-in link to be mailed to the address. Resolves when the
327
+ * server accepted the request (it answers the same whether or not the
328
+ * address belongs to an account) and rejects with a `LumoAuthApiError`
329
+ * when it refused: `code` is the server's reason, for example
330
+ * `magic_link_disabled`, `origin_not_allowed` or `captcha_required`.
331
+ *
332
+ * The link signs the person in on the LumoAuth origin and returns them to
333
+ * `returnTo`: a page of your app on one of the application's allowed
334
+ * origins or redirect URI origins. Without it they return to the page
335
+ * they are on, and the provider finishes the sign-in there by itself.
336
+ * With your own `returnTo`, call `signIn()` on that page.
308
337
  */
309
- sendMagicLink: (email: string, redirectUri?: string) => Promise<void>;
338
+ sendMagicLink: (email: string, returnTo?: string, options?: {
339
+ captchaToken?: string;
340
+ }) => Promise<void>;
310
341
  /**
311
342
  * Check whether an account with the given email exists in the organization.
312
343
  * Used to implement email-first login flows.
@@ -638,10 +669,16 @@ declare function useAbac(request: AbacCheckRequest): {
638
669
  isLoading: boolean;
639
670
  };
640
671
  /**
641
- * Hook for requesting a magic sign-in link.
672
+ * Hook for requesting a sign-in link by email from your own form.
673
+ *
674
+ * It keeps the loading, sent and error state. `isSent` means that the server
675
+ * accepted the request; the link is mailed only when the address belongs to
676
+ * an account. The person opens the link, confirms on the LumoAuth page and
677
+ * comes back to the page the request was made from, where the provider signs
678
+ * them in. Pass a second argument to `sendMagicLink` to return them elsewhere.
642
679
  *
643
- * Handles loading/sent/error state so you can build a fully-controlled
644
- * "passwordless sign-in" form without any extra local state.
680
+ * The request must come from one of the application's allowed origins, and
681
+ * the organization must have sign-in links switched on.
645
682
  *
646
683
  * @example
647
684
  * ```tsx
package/dist/index.d.ts CHANGED
@@ -18,7 +18,10 @@ interface LumoAuthUser {
18
18
  avatarUrl?: string;
19
19
  /** Whether email has been verified */
20
20
  emailVerified: boolean;
21
- /** Whether MFA is enabled */
21
+ /**
22
+ * Whether MFA is enabled. Also `false` when the UserInfo response has no
23
+ * `mfa_enabled` claim; check `claims.mfa_enabled` to tell the two apart.
24
+ */
22
25
  mfaEnabled: boolean;
23
26
  /** List of role slugs */
24
27
  roles: string[];
@@ -94,7 +97,12 @@ interface LumoAuthProviderProps {
94
97
  children: React.ReactNode;
95
98
  }
96
99
  interface AppearanceProps {
97
- /** Force light or dark theme (defaults to system preference) */
100
+ /**
101
+ * Force the light or the dark theme for this component. Without it the
102
+ * component follows the nearest ancestor that has the class `la-light` /
103
+ * `la-dark` or the attribute `data-lumoauth-theme="light" | "dark"`, and
104
+ * otherwise the colour scheme of the operating system.
105
+ */
98
106
  theme?: 'light' | 'dark';
99
107
  /** Override CSS custom properties */
100
108
  variables?: Record<string, string>;
@@ -218,7 +226,9 @@ interface UserProfileProps {
218
226
  afterSignOutUrl?: string;
219
227
  /**
220
228
  * Display mode:
221
- * - `'full'` — shows all sections (account, security, roles)
229
+ * - `'full'` — shows all sections (account, security, roles). The MFA
230
+ * row and the roles and groups appear only when the UserInfo response
231
+ * holds those claims.
222
232
  * - `'compact'` — shows only account details
223
233
  * @default 'full'
224
234
  */
@@ -236,16 +246,27 @@ interface RedirectToSignInProps {
236
246
  */
237
247
  interface UseMagicLinkReturn {
238
248
  /**
239
- * Send a magic sign-in link to the given email.
240
- * The server never reveals whether the email exists.
249
+ * Ask for a sign-in link to be mailed to the address. See
250
+ * {@link LumoAuthContextValue.sendMagicLink}. A refusal does not throw
251
+ * here: it sets `error` and `errorCode`.
241
252
  */
242
- sendMagicLink: (email: string, redirectUri?: string) => Promise<void>;
253
+ sendMagicLink: (email: string, returnTo?: string, options?: {
254
+ captchaToken?: string;
255
+ }) => Promise<void>;
243
256
  /** True while the request is in-flight */
244
257
  isLoading: boolean;
245
- /** True after the request completes (link was dispatched) */
258
+ /**
259
+ * True after the server accepted the request. It does not mean that the
260
+ * address belongs to an account: the server answers the same either way.
261
+ */
246
262
  isSent: boolean;
247
263
  /** Error message if the request failed */
248
264
  error: string | null;
265
+ /**
266
+ * The server's reason when it refused the request, for example
267
+ * `captcha_required`, `origin_not_allowed` or `rate_limited`; null otherwise.
268
+ */
269
+ errorCode: string | null;
249
270
  /** Reset sent/error state back to idle */
250
271
  reset: () => void;
251
272
  }
@@ -302,11 +323,21 @@ interface LumoAuthContextValue extends AuthState {
302
323
  /** Handle the OAuth callback — exchange code for tokens */
303
324
  handleCallback: () => Promise<void>;
304
325
  /**
305
- * Request a magic sign-in link for the given email.
306
- * Shows a "Check your inbox" page — works for both email-first and
307
- * magic-link-only organization configurations.
326
+ * Ask for a sign-in link to be mailed to the address. Resolves when the
327
+ * server accepted the request (it answers the same whether or not the
328
+ * address belongs to an account) and rejects with a `LumoAuthApiError`
329
+ * when it refused: `code` is the server's reason, for example
330
+ * `magic_link_disabled`, `origin_not_allowed` or `captcha_required`.
331
+ *
332
+ * The link signs the person in on the LumoAuth origin and returns them to
333
+ * `returnTo`: a page of your app on one of the application's allowed
334
+ * origins or redirect URI origins. Without it they return to the page
335
+ * they are on, and the provider finishes the sign-in there by itself.
336
+ * With your own `returnTo`, call `signIn()` on that page.
308
337
  */
309
- sendMagicLink: (email: string, redirectUri?: string) => Promise<void>;
338
+ sendMagicLink: (email: string, returnTo?: string, options?: {
339
+ captchaToken?: string;
340
+ }) => Promise<void>;
310
341
  /**
311
342
  * Check whether an account with the given email exists in the organization.
312
343
  * Used to implement email-first login flows.
@@ -638,10 +669,16 @@ declare function useAbac(request: AbacCheckRequest): {
638
669
  isLoading: boolean;
639
670
  };
640
671
  /**
641
- * Hook for requesting a magic sign-in link.
672
+ * Hook for requesting a sign-in link by email from your own form.
673
+ *
674
+ * It keeps the loading, sent and error state. `isSent` means that the server
675
+ * accepted the request; the link is mailed only when the address belongs to
676
+ * an account. The person opens the link, confirms on the LumoAuth page and
677
+ * comes back to the page the request was made from, where the provider signs
678
+ * them in. Pass a second argument to `sendMagicLink` to return them elsewhere.
642
679
  *
643
- * Handles loading/sent/error state so you can build a fully-controlled
644
- * "passwordless sign-in" form without any extra local state.
680
+ * The request must come from one of the application's allowed origins, and
681
+ * the organization must have sign-in links switched on.
645
682
  *
646
683
  * @example
647
684
  * ```tsx