@lumoauth/react 1.4.2 → 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
@@ -363,7 +363,7 @@ return <button onClick={() => signOut()}>Sign out {user!.displayName}</button>;
363
363
  | `signOut({ afterSignOutUrl? })` | function | Revokes the access token, clears local tokens, and ends the LumoAuth session through the logout endpoint |
364
364
  | `getToken()` | `() => Promise<string \| null>` | A valid access token. It refreshes first when needed. |
365
365
  | `handleCallback()` | function | Exchanges the code on the callback page. `<AuthCallback>` calls it for you. |
366
- | `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. |
367
367
  | `checkEmail(email)` | `(email) => Promise<EmailCheckResult>` | Reports the sign-in methods for an email address |
368
368
  | `authStrategy` | `'pkce' \| 'password'` | The strategy in use |
369
369
  | `config` | object | The provider's `domain`, `orgId`, `clientId` and redirect URLs |
@@ -416,7 +416,7 @@ const canRead = useAbac({ resourceType: 'document', action: 'read', resourceId:
416
416
  A Zanzibar check about a user other than the signed-in user needs the `authz:check` scope or
417
417
  permission. `useAbac` needs `abac:read`; see [Core concepts](#core-concepts).
418
418
 
419
- **`useMagicLink()`** returns `{ sendMagicLink, isLoading, isSent, error, reset }`:
419
+ **`useMagicLink()`** returns `{ sendMagicLink, isLoading, isSent, error, errorCode, reset }`:
420
420
 
421
421
  ```tsx
422
422
  function PasswordlessForm() {
@@ -444,6 +444,30 @@ function PasswordlessForm() {
444
444
 
445
445
  `isSent` becomes `true` whether or not the account exists. The server never reveals that.
446
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
+
447
471
  **`useEmailFirst()`** returns `{ checkEmail, isLoading, result, exists, reset }`. Use it to build
448
472
  a sign-in screen that asks for the email address first. `checkEmail(email)` resolves to an
449
473
  `EmailCheckResult`. It reports whether the account exists and which methods it can use:
@@ -627,7 +651,7 @@ yourself, it throws the error classes that are described in the
627
651
  | `usePermission(slug)` | hook | `{ allowed, isLoading }` |
628
652
  | `useZanzibar(request)` | hook | `{ allowed, isLoading }` |
629
653
  | `useAbac(request)` | hook | `{ allowed, isLoading }`; needs `abac:read` |
630
- | `useMagicLink()` | hook | `{ sendMagicLink, isLoading, isSent, error, reset }` |
654
+ | `useMagicLink()` | hook | `{ sendMagicLink, isLoading, isSent, error, errorCode, reset }` |
631
655
  | `useEmailFirst()` | hook | `{ checkEmail, isLoading, result, exists, reset }` |
632
656
  | `LumoAuth` | class | The browser client, re-exported from `@lumoauth/client` |
633
657
 
package/dist/index.d.mts CHANGED
@@ -246,16 +246,27 @@ interface RedirectToSignInProps {
246
246
  */
247
247
  interface UseMagicLinkReturn {
248
248
  /**
249
- * Send a magic sign-in link to the given email.
250
- * 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`.
251
252
  */
252
- sendMagicLink: (email: string, redirectUri?: string) => Promise<void>;
253
+ sendMagicLink: (email: string, returnTo?: string, options?: {
254
+ captchaToken?: string;
255
+ }) => Promise<void>;
253
256
  /** True while the request is in-flight */
254
257
  isLoading: boolean;
255
- /** 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
+ */
256
262
  isSent: boolean;
257
263
  /** Error message if the request failed */
258
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;
259
270
  /** Reset sent/error state back to idle */
260
271
  reset: () => void;
261
272
  }
@@ -312,11 +323,21 @@ interface LumoAuthContextValue extends AuthState {
312
323
  /** Handle the OAuth callback — exchange code for tokens */
313
324
  handleCallback: () => Promise<void>;
314
325
  /**
315
- * Request a magic sign-in link for the given email.
316
- * Shows a "Check your inbox" page — works for both email-first and
317
- * 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.
318
337
  */
319
- sendMagicLink: (email: string, redirectUri?: string) => Promise<void>;
338
+ sendMagicLink: (email: string, returnTo?: string, options?: {
339
+ captchaToken?: string;
340
+ }) => Promise<void>;
320
341
  /**
321
342
  * Check whether an account with the given email exists in the organization.
322
343
  * Used to implement email-first login flows.
@@ -648,10 +669,16 @@ declare function useAbac(request: AbacCheckRequest): {
648
669
  isLoading: boolean;
649
670
  };
650
671
  /**
651
- * 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.
652
679
  *
653
- * Handles loading/sent/error state so you can build a fully-controlled
654
- * "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.
655
682
  *
656
683
  * @example
657
684
  * ```tsx
package/dist/index.d.ts CHANGED
@@ -246,16 +246,27 @@ interface RedirectToSignInProps {
246
246
  */
247
247
  interface UseMagicLinkReturn {
248
248
  /**
249
- * Send a magic sign-in link to the given email.
250
- * 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`.
251
252
  */
252
- sendMagicLink: (email: string, redirectUri?: string) => Promise<void>;
253
+ sendMagicLink: (email: string, returnTo?: string, options?: {
254
+ captchaToken?: string;
255
+ }) => Promise<void>;
253
256
  /** True while the request is in-flight */
254
257
  isLoading: boolean;
255
- /** 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
+ */
256
262
  isSent: boolean;
257
263
  /** Error message if the request failed */
258
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;
259
270
  /** Reset sent/error state back to idle */
260
271
  reset: () => void;
261
272
  }
@@ -312,11 +323,21 @@ interface LumoAuthContextValue extends AuthState {
312
323
  /** Handle the OAuth callback — exchange code for tokens */
313
324
  handleCallback: () => Promise<void>;
314
325
  /**
315
- * Request a magic sign-in link for the given email.
316
- * Shows a "Check your inbox" page — works for both email-first and
317
- * 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.
318
337
  */
319
- sendMagicLink: (email: string, redirectUri?: string) => Promise<void>;
338
+ sendMagicLink: (email: string, returnTo?: string, options?: {
339
+ captchaToken?: string;
340
+ }) => Promise<void>;
320
341
  /**
321
342
  * Check whether an account with the given email exists in the organization.
322
343
  * Used to implement email-first login flows.
@@ -648,10 +669,16 @@ declare function useAbac(request: AbacCheckRequest): {
648
669
  isLoading: boolean;
649
670
  };
650
671
  /**
651
- * 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.
652
679
  *
653
- * Handles loading/sent/error state so you can build a fully-controlled
654
- * "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.
655
682
  *
656
683
  * @example
657
684
  * ```tsx
package/dist/index.js CHANGED
@@ -52,6 +52,32 @@ var import_client4 = require("@lumoauth/client");
52
52
 
53
53
  // src/provider.tsx
54
54
  var import_react = require("react");
55
+
56
+ // src/utils/magicLink.ts
57
+ var MAGIC_LINK_CONTINUE_PARAM = "lumoauth_continue";
58
+ var MAGIC_LINK_RETURN_TO_MAX = 1024;
59
+ function defaultMagicLinkReturnTo(href) {
60
+ const page = new URL(href);
61
+ page.hash = "";
62
+ page.searchParams.set(MAGIC_LINK_CONTINUE_PARAM, "1");
63
+ if (page.href.length <= MAGIC_LINK_RETURN_TO_MAX) {
64
+ return page.href;
65
+ }
66
+ const withoutQuery = new URL(page.origin + page.pathname);
67
+ withoutQuery.searchParams.set(MAGIC_LINK_CONTINUE_PARAM, "1");
68
+ if (withoutQuery.href.length <= MAGIC_LINK_RETURN_TO_MAX) {
69
+ return withoutQuery.href;
70
+ }
71
+ return `${page.origin}/?${MAGIC_LINK_CONTINUE_PARAM}=1`;
72
+ }
73
+ function takeMagicLinkContinue(href) {
74
+ const page = new URL(href);
75
+ const found = page.searchParams.has(MAGIC_LINK_CONTINUE_PARAM);
76
+ page.searchParams.delete(MAGIC_LINK_CONTINUE_PARAM);
77
+ return { found, cleanUrl: `${page.pathname}${page.search}${page.hash}` };
78
+ }
79
+
80
+ // src/provider.tsx
55
81
  var import_client = require("@lumoauth/client");
56
82
  var import_client2 = require("@lumoauth/client");
57
83
 
@@ -951,6 +977,7 @@ function LumoAuthProvider({
951
977
  const [user, setUser] = (0, import_react.useState)(null);
952
978
  const tokensRef = (0, import_react.useRef)({ accessToken: null, refreshToken: null, expiresAt: null, idToken: null });
953
979
  const callbackHandledRef = (0, import_react.useRef)(false);
980
+ const magicLinkContinueRef = (0, import_react.useRef)(false);
954
981
  const callbackInflightRef = (0, import_react.useRef)(null);
955
982
  (0, import_react.useEffect)(() => {
956
983
  injectStyles();
@@ -1150,8 +1177,12 @@ function LumoAuthProvider({
1150
1177
  `Inline registration is not supported by this LumoAuth server: there is no JSON registration endpoint. Use redirectToSignUp() to send the user to the hosted registration page (${domain.replace(/\/+$/, "")}/orgs/${encodeURIComponent(orgId)}/register), or set authStrategy: "pkce".`
1151
1178
  );
1152
1179
  }, [authStrategy, domain, orgId, clientId, resolvedRedirectUri, scope, signIn]);
1153
- const sendMagicLink = (0, import_react.useCallback)(async (email, redirectUri2) => {
1154
- await authModule.requestMagicLink({ email, redirectUri: redirectUri2 });
1180
+ const sendMagicLink = (0, import_react.useCallback)(async (email, returnTo, options) => {
1181
+ const target = returnTo ?? (typeof window !== "undefined" ? defaultMagicLinkReturnTo(window.location.href) : void 0);
1182
+ const result = await authModule.requestMagicLink({ email, returnTo: target, captchaToken: options?.captchaToken });
1183
+ if (!result.sent) {
1184
+ throw new Error("The sign-in link request was not accepted.");
1185
+ }
1155
1186
  }, [authModule]);
1156
1187
  const checkEmail = (0, import_react.useCallback)(
1157
1188
  (email) => authModule.checkEmailExists(email),
@@ -1193,6 +1224,11 @@ function LumoAuthProvider({
1193
1224
  let cancelled = false;
1194
1225
  async function init() {
1195
1226
  if (typeof window === "undefined") return;
1227
+ const back = takeMagicLinkContinue(window.location.href);
1228
+ if (back.found) {
1229
+ magicLinkContinueRef.current = true;
1230
+ window.history.replaceState(window.history.state, "", back.cleanUrl);
1231
+ }
1196
1232
  const params = new URLSearchParams(window.location.search);
1197
1233
  const code = params.get("code");
1198
1234
  const returnedState = params.get("state");
@@ -1215,13 +1251,19 @@ function LumoAuthProvider({
1215
1251
  }
1216
1252
  }
1217
1253
  }
1218
- init().then(() => {
1219
- if (!cancelled) void session.hydrate();
1254
+ init().then(async () => {
1255
+ if (cancelled) return;
1256
+ await session.hydrate();
1257
+ if (cancelled || !magicLinkContinueRef.current) return;
1258
+ magicLinkContinueRef.current = false;
1259
+ if (!session.getSnapshot().isSignedIn) {
1260
+ signInWithRedirect();
1261
+ }
1220
1262
  });
1221
1263
  return () => {
1222
1264
  cancelled = true;
1223
1265
  };
1224
- }, [fetchUser, handleCallback, refreshAccessToken, session]);
1266
+ }, [fetchUser, handleCallback, refreshAccessToken, session, signInWithRedirect]);
1225
1267
  (0, import_react.useEffect)(() => {
1226
1268
  let cancelled = false;
1227
1269
  if (!sessionState.isSignedIn) {
@@ -2230,14 +2272,19 @@ function useMagicLink() {
2230
2272
  const [isLoading, setIsLoading] = (0, import_react7.useState)(false);
2231
2273
  const [isSent, setIsSent] = (0, import_react7.useState)(false);
2232
2274
  const [error, setError] = (0, import_react7.useState)(null);
2233
- const sendMagicLink = (0, import_react7.useCallback)(async (email, redirectUri) => {
2275
+ const [errorCode, setErrorCode] = (0, import_react7.useState)(null);
2276
+ const sendMagicLink = (0, import_react7.useCallback)(async (email, returnTo, options) => {
2234
2277
  setIsLoading(true);
2278
+ setIsSent(false);
2235
2279
  setError(null);
2280
+ setErrorCode(null);
2236
2281
  try {
2237
- await sendMagicLinkCtx(email, redirectUri);
2282
+ await sendMagicLinkCtx(email, returnTo, options);
2238
2283
  setIsSent(true);
2239
2284
  } catch (err) {
2240
2285
  setError(err instanceof Error ? err.message : "Failed to send magic link");
2286
+ const code = err?.code;
2287
+ setErrorCode(typeof code === "string" ? code : null);
2241
2288
  } finally {
2242
2289
  setIsLoading(false);
2243
2290
  }
@@ -2245,9 +2292,10 @@ function useMagicLink() {
2245
2292
  const reset = (0, import_react7.useCallback)(() => {
2246
2293
  setIsSent(false);
2247
2294
  setError(null);
2295
+ setErrorCode(null);
2248
2296
  setIsLoading(false);
2249
2297
  }, []);
2250
- return { sendMagicLink, isLoading, isSent, error, reset };
2298
+ return { sendMagicLink, isLoading, isSent, error, errorCode, reset };
2251
2299
  }
2252
2300
  function useEmailFirst() {
2253
2301
  const { checkEmail: checkEmailCtx } = useLumoAuthContext();