@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 +61 -8
- package/dist/index.d.mts +51 -14
- package/dist/index.d.ts +51 -14
- package/dist/index.js +142 -91
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +142 -91
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
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,
|
|
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
|
|
554
|
-
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
240
|
-
*
|
|
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,
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
306
|
-
*
|
|
307
|
-
*
|
|
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,
|
|
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
|
|
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
|
-
*
|
|
644
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
240
|
-
*
|
|
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,
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
306
|
-
*
|
|
307
|
-
*
|
|
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,
|
|
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
|
|
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
|
-
*
|
|
644
|
-
*
|
|
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
|