@useauthio/react 0.3.0 → 0.3.1

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/src/sign-in.ts CHANGED
@@ -1,5 +1,10 @@
1
1
  import { AuthioError } from "@useauthio/node";
2
2
  import { authioFetch } from "./fetch";
3
+ import {
4
+ AUTHIO_MESSAGES,
5
+ riskDecisionError,
6
+ type RiskDecisionBody,
7
+ } from "./errors";
3
8
  import {
4
9
  deviceSignalsExtraHeaders,
5
10
  type DeviceSignalsCapture,
@@ -26,6 +31,8 @@ export interface SignInWithMagicLinkOptions {
26
31
  * after the user clicks the link in their inbox.
27
32
  */
28
33
  redirectUri: string;
34
+ /** Opaque, consent-gated proof minted by @useauthio/xray. */
35
+ xrayVisitorProof?: string;
29
36
  signal?: AbortSignal;
30
37
  fetch?: typeof fetch;
31
38
  }
@@ -69,6 +76,9 @@ export async function signInWithMagicLink(
69
76
  // (email or E.164), NOT `email`. See magiclink.go magicLinkSendReq.
70
77
  destination: opts.email,
71
78
  redirect_uri: opts.redirectUri,
79
+ ...(opts.xrayVisitorProof
80
+ ? { xray_visitor_proof: opts.xrayVisitorProof }
81
+ : {}),
72
82
  },
73
83
  signal: opts.signal,
74
84
  fetchImpl: opts.fetch,
@@ -91,6 +101,8 @@ export interface SignInWithPasskeyOptions {
91
101
  next?: string;
92
102
  /** Organization scope (`org_…`) for org-policy enforcement. */
93
103
  organizationId?: string;
104
+ /** Opaque, consent-gated proof minted by @useauthio/xray. */
105
+ xrayVisitorProof?: string;
94
106
  signal?: AbortSignal;
95
107
  fetch?: typeof fetch;
96
108
  }
@@ -115,18 +127,74 @@ interface PasskeyLoginOptionsResponse {
115
127
  }>;
116
128
  }
117
129
 
118
- interface PasskeyLoginVerifyResponse {
119
- access_token: string;
130
+ /**
131
+ * Wire shape of a sign-in verify response. Every field is optional on
132
+ * purpose: the same endpoint returns either a session envelope or a
133
+ * risk-engine `step_up` body (HTTP 200, no tokens, no user), so nothing
134
+ * may be assumed present. See `sessionFromResponse`.
135
+ */
136
+ interface SignInVerifyResponse extends RiskDecisionBody {
137
+ access_token?: string;
120
138
  refresh_token?: string;
121
139
  session_policy?: RawSessionPolicy;
122
- user: {
123
- id: string;
124
- email: string;
140
+ user?: {
141
+ id?: string;
142
+ email?: string;
125
143
  email_verified?: boolean;
126
144
  emailVerified?: boolean;
127
145
  name?: string;
128
146
  avatar_url?: string;
129
147
  avatarUrl?: string;
148
+ } | null;
149
+ }
150
+
151
+ interface SignInSession {
152
+ accessToken: string;
153
+ refreshToken?: string;
154
+ sessionPolicy: SessionPolicy | null;
155
+ user: AuthioUser;
156
+ }
157
+
158
+ /**
159
+ * Map a 2xx sign-in verify body to a session, never assuming a field
160
+ * is present:
161
+ *
162
+ * - `decision: "step_up"` → `AuthioStepUpRequiredError`
163
+ * (`step_up_required`, carries `stepUpUrl` / `challengeId` /
164
+ * `requiredMethod`).
165
+ * - `decision: "block" | "deny"` → `AuthioSignInDeniedError`
166
+ * (`sign_in_denied`).
167
+ * - no access token or no user id → `AuthioError` `invalid_response`.
168
+ */
169
+ export function sessionFromResponse(
170
+ res: SignInVerifyResponse | null | undefined,
171
+ status = 200,
172
+ ): SignInSession {
173
+ const risk = riskDecisionError(res, status);
174
+ if (risk) throw risk;
175
+ const accessToken =
176
+ res && typeof res.access_token === "string" ? res.access_token : "";
177
+ const user = res && res.user && typeof res.user === "object" ? res.user : null;
178
+ const userId = user && typeof user.id === "string" ? user.id : "";
179
+ if (!res || !accessToken || !user || !userId) {
180
+ throw new AuthioError({
181
+ code: "invalid_response",
182
+ message: AUTHIO_MESSAGES.invalid_response,
183
+ status,
184
+ });
185
+ }
186
+ return {
187
+ accessToken,
188
+ refreshToken:
189
+ typeof res.refresh_token === "string" ? res.refresh_token : undefined,
190
+ sessionPolicy: coerceSessionPolicy(res.session_policy),
191
+ user: {
192
+ id: userId,
193
+ email: typeof user.email === "string" ? user.email : "",
194
+ emailVerified: Boolean(user.emailVerified ?? user.email_verified),
195
+ name: user.name,
196
+ avatarUrl: user.avatarUrl ?? user.avatar_url,
197
+ },
130
198
  };
131
199
  }
132
200
 
@@ -148,7 +216,13 @@ interface PasskeyLoginVerifyResponse {
148
216
  * - `webauthn_unsupported` if `navigator.credentials.get` is
149
217
  * missing (legacy browser).
150
218
  * - `webauthn_cancelled` if the user dismisses the chooser.
151
- * - Whatever auth-core returns on the options or verify call.
219
+ * - `step_up_required` (`AuthioStepUpRequiredError`) when the risk
220
+ * engine wants one more check. Redirect to `err.stepUpUrl`.
221
+ * - `sign_in_denied` (`AuthioSignInDeniedError`) when the risk engine
222
+ * or a project policy refuses the sign-in. `err.message` is
223
+ * auth-core's readable reason.
224
+ * - `invalid_response` if auth-core answered without a session.
225
+ * - Whatever else auth-core returns on the options or verify call.
152
226
  *
153
227
  * The returned `refreshToken` is included for completeness, but the
154
228
  * SDK never persists it — auth-core's `/v1/auth/passkey/login/verify`
@@ -162,14 +236,14 @@ export async function signInWithPasskey(
162
236
  throw new AuthioError({
163
237
  code: "not_in_browser",
164
238
  message:
165
- "signInWithPasskey can only be invoked in a browser environment.",
239
+ "Passkey sign-in only works in a web browser. Call signInWithPasskey from client-side code.",
166
240
  status: 0,
167
241
  });
168
242
  }
169
243
  if (!navigator.credentials || !navigator.credentials.get) {
170
244
  throw new AuthioError({
171
245
  code: "webauthn_unsupported",
172
- message: "This browser does not support WebAuthn (passkeys).",
246
+ message: AUTHIO_MESSAGES.webauthn_unsupported,
173
247
  status: 0,
174
248
  });
175
249
  }
@@ -184,6 +258,14 @@ export async function signInWithPasskey(
184
258
  fetchImpl: opts.fetch,
185
259
  });
186
260
 
261
+ if (!options || typeof options.challenge !== "string" || !options.challenge) {
262
+ throw new AuthioError({
263
+ code: "invalid_response",
264
+ message: AUTHIO_MESSAGES.invalid_response,
265
+ status: 200,
266
+ });
267
+ }
268
+
187
269
  const publicKey: PublicKeyCredentialRequestOptions = {
188
270
  challenge: base64UrlToBuffer(options.challenge),
189
271
  rpId: options.rpId,
@@ -203,19 +285,20 @@ export async function signInWithPasskey(
203
285
  signal: opts.signal,
204
286
  });
205
287
  } catch (err) {
206
- throw new AuthioError({
288
+ // Browser text ("The operation either timed out or was not
289
+ // allowed…") is not user-friendly; keep it on `cause` only.
290
+ const e = new AuthioError({
207
291
  code: "webauthn_cancelled",
208
- message:
209
- err instanceof Error
210
- ? err.message
211
- : "Passkey ceremony cancelled by user.",
292
+ message: AUTHIO_MESSAGES.webauthn_cancelled,
212
293
  status: 0,
213
294
  });
295
+ Object.defineProperty(e, "cause", { value: err, enumerable: false });
296
+ throw e;
214
297
  }
215
298
  if (!credential) {
216
299
  throw new AuthioError({
217
300
  code: "webauthn_cancelled",
218
- message: "Passkey ceremony returned no credential.",
301
+ message: AUTHIO_MESSAGES.webauthn_cancelled,
219
302
  status: 0,
220
303
  });
221
304
  }
@@ -244,7 +327,7 @@ export async function signInWithPasskey(
244
327
  },
245
328
  };
246
329
 
247
- const verifyRes = await authioFetch<PasskeyLoginVerifyResponse>({
330
+ const verifyRes = await authioFetch<SignInVerifyResponse>({
248
331
  apiUrl: opts.apiUrl,
249
332
  projectId: opts.projectId,
250
333
  path: "/v1/auth/passkey/login/verify",
@@ -253,6 +336,9 @@ export async function signInWithPasskey(
253
336
  credential: webauthnCredential,
254
337
  ...(opts.next ? { next: opts.next } : {}),
255
338
  ...(opts.organizationId ? { organization_id: opts.organizationId } : {}),
339
+ ...(opts.xrayVisitorProof
340
+ ? { xray_visitor_proof: opts.xrayVisitorProof }
341
+ : {}),
256
342
  },
257
343
  extraHeaders: deviceSignalsExtraHeaders(),
258
344
  credentials: "include",
@@ -260,20 +346,7 @@ export async function signInWithPasskey(
260
346
  fetchImpl: opts.fetch,
261
347
  });
262
348
 
263
- return {
264
- accessToken: verifyRes.access_token,
265
- refreshToken: verifyRes.refresh_token,
266
- sessionPolicy: coerceSessionPolicy(verifyRes.session_policy),
267
- user: {
268
- id: verifyRes.user.id,
269
- email: verifyRes.user.email,
270
- emailVerified: Boolean(
271
- verifyRes.user.emailVerified ?? verifyRes.user.email_verified,
272
- ),
273
- name: verifyRes.user.name,
274
- avatarUrl: verifyRes.user.avatarUrl ?? verifyRes.user.avatar_url,
275
- },
276
- };
349
+ return sessionFromResponse(verifyRes);
277
350
  }
278
351
 
279
352
  // ============================================================
@@ -296,6 +369,8 @@ export interface SendEmailOtpOptions {
296
369
  next?: string;
297
370
  /** Organization scope (`org_…`) for org-policy enforcement. */
298
371
  organizationId?: string;
372
+ /** Opaque, consent-gated proof minted by @useauthio/xray. */
373
+ xrayVisitorProof?: string;
299
374
  signal?: AbortSignal;
300
375
  fetch?: typeof fetch;
301
376
  }
@@ -320,6 +395,9 @@ export async function sendEmailOtp(opts: SendEmailOtpOptions): Promise<void> {
320
395
  ...(opts.redirectUri ? { redirect_uri: opts.redirectUri } : {}),
321
396
  ...(opts.next ? { next: opts.next } : {}),
322
397
  ...(opts.organizationId ? { organization_id: opts.organizationId } : {}),
398
+ ...(opts.xrayVisitorProof
399
+ ? { xray_visitor_proof: opts.xrayVisitorProof }
400
+ : {}),
323
401
  },
324
402
  signal: opts.signal,
325
403
  fetchImpl: opts.fetch,
@@ -343,6 +421,8 @@ export interface VerifyEmailOtpOptions {
343
421
  clientLocation?: ClientLocationCapture;
344
422
  /** Optional coarse device signals for risk / device recognition. */
345
423
  deviceSignals?: DeviceSignalsCapture;
424
+ /** Opaque, consent-gated proof minted by @useauthio/xray. */
425
+ xrayVisitorProof?: string;
346
426
  signal?: AbortSignal;
347
427
  fetch?: typeof fetch;
348
428
  }
@@ -355,23 +435,6 @@ export interface VerifyEmailOtpResult {
355
435
  user: AuthioUser;
356
436
  }
357
437
 
358
- interface EmailOtpVerifyResponse {
359
- decision?: string;
360
- challenge_id?: string;
361
- access_token: string;
362
- refresh_token?: string;
363
- session_policy?: RawSessionPolicy;
364
- user: {
365
- id: string;
366
- email: string;
367
- email_verified?: boolean;
368
- emailVerified?: boolean;
369
- name?: string;
370
- avatar_url?: string;
371
- avatarUrl?: string;
372
- };
373
- }
374
-
375
438
  /**
376
439
  * POSTs `/v1/auth/email-otp/verify` with the code the user typed —
377
440
  * mirrors the hosted Lobby's verify body shape. On success returns
@@ -382,14 +445,18 @@ interface EmailOtpVerifyResponse {
382
445
  * Throws `AuthioError`:
383
446
  *
384
447
  * - `invalid_code` for a wrong/expired code (auth-core's code).
385
- * - `step_up_required` when the risk engine withholds the session
386
- * pending a second factor — finish the sign-in on the hosted UI.
448
+ * - `step_up_required` (`AuthioStepUpRequiredError`) when the risk
449
+ * engine withholds the session pending a second factor. Redirect to
450
+ * `err.stepUpUrl` to finish the sign-in on the hosted UI.
451
+ * - `sign_in_denied` (`AuthioSignInDeniedError`) when the sign-in is
452
+ * refused by risk or project policy.
453
+ * - `invalid_response` if auth-core answered without a session.
387
454
  * - Whatever else auth-core returns (rate-limit, policy, etc.).
388
455
  */
389
456
  export async function verifyEmailOtp(
390
457
  opts: VerifyEmailOtpOptions,
391
458
  ): Promise<VerifyEmailOtpResult> {
392
- const verifyRes = await authioFetch<EmailOtpVerifyResponse>({
459
+ const verifyRes = await authioFetch<SignInVerifyResponse>({
393
460
  apiUrl: opts.apiUrl,
394
461
  projectId: opts.projectId,
395
462
  path: "/v1/auth/email-otp/verify",
@@ -402,38 +469,18 @@ export async function verifyEmailOtp(
402
469
  ...(opts.organizationId ? { organization_id: opts.organizationId } : {}),
403
470
  ...(opts.clientLocation ? { client_location: opts.clientLocation } : {}),
404
471
  ...(opts.deviceSignals ? { device_signals: opts.deviceSignals } : {}),
472
+ ...(opts.xrayVisitorProof
473
+ ? { xray_visitor_proof: opts.xrayVisitorProof }
474
+ : {}),
405
475
  },
406
476
  credentials: "include",
407
477
  signal: opts.signal,
408
478
  fetchImpl: opts.fetch,
409
479
  });
410
480
 
411
- // The risk engine may withhold the session and demand a second factor.
412
- // A pure SPA can't run the step-up ceremony itself — surface a typed
413
- // error so callers can bounce the user to the hosted step-up page.
414
- if (verifyRes.decision === "step_up") {
415
- throw new AuthioError({
416
- code: "step_up_required",
417
- message:
418
- "Additional verification is required. Complete the step-up challenge on the hosted sign-in page.",
419
- status: 200,
420
- });
421
- }
422
-
423
- return {
424
- accessToken: verifyRes.access_token,
425
- refreshToken: verifyRes.refresh_token,
426
- sessionPolicy: coerceSessionPolicy(verifyRes.session_policy),
427
- user: {
428
- id: verifyRes.user.id,
429
- email: verifyRes.user.email,
430
- emailVerified: Boolean(
431
- verifyRes.user.emailVerified ?? verifyRes.user.email_verified,
432
- ),
433
- name: verifyRes.user.name,
434
- avatarUrl: verifyRes.user.avatarUrl ?? verifyRes.user.avatar_url,
435
- },
436
- };
481
+ // The risk engine may withhold the session (decision: "step_up") —
482
+ // sessionFromResponse turns that into a typed error with stepUpUrl.
483
+ return sessionFromResponse(verifyRes);
437
484
  }
438
485
 
439
486
  function base64UrlToBuffer(b64u: string): ArrayBuffer {
@@ -7,6 +7,15 @@ import {
7
7
  revokePasskey,
8
8
  type AuthioPasskey,
9
9
  } from "./passkeys";
10
+ import { AUTHIO_MESSAGES, AuthioError } from "./errors";
11
+
12
+ function notSignedIn(): AuthioError {
13
+ return new AuthioError({
14
+ code: "not_signed_in",
15
+ message: AUTHIO_MESSAGES.not_signed_in,
16
+ status: 401,
17
+ });
18
+ }
10
19
 
11
20
  export interface UsePasskeysResult {
12
21
  passkeys: AuthioPasskey[];
@@ -50,7 +59,7 @@ export function usePasskeys(): UsePasskeysResult {
50
59
  });
51
60
  setPasskeys(rows);
52
61
  } catch (err) {
53
- setError(err instanceof Error ? err.message : "Failed to load passkeys");
62
+ setError(err instanceof AuthioError ? err.message : "We couldn't load your passkeys. Please refresh the page and try again.");
54
63
  setPasskeys([]);
55
64
  } finally {
56
65
  setLoading(false);
@@ -70,7 +79,7 @@ export function usePasskeys(): UsePasskeysResult {
70
79
  const rename = useCallback(
71
80
  async (credentialId: string, nickname: string) => {
72
81
  const token = await ctx.getAccessToken();
73
- if (!token) throw new Error("Not signed in");
82
+ if (!token) throw notSignedIn();
74
83
  await renamePasskey(
75
84
  {
76
85
  apiUrl: ctx.apiUrl,
@@ -89,7 +98,7 @@ export function usePasskeys(): UsePasskeysResult {
89
98
  const revoke = useCallback(
90
99
  async (credentialId: string) => {
91
100
  const token = await ctx.getAccessToken();
92
- if (!token) throw new Error("Not signed in");
101
+ if (!token) throw notSignedIn();
93
102
  await revokePasskey(
94
103
  {
95
104
  apiUrl: ctx.apiUrl,
@@ -108,7 +117,7 @@ export function usePasskeys(): UsePasskeysResult {
108
117
  async (opts?: { returnUrl?: string; next?: string }) => {
109
118
  const token = await ctx.getAccessToken();
110
119
  const email = ctx.user?.email;
111
- if (!token || !email) throw new Error("Not signed in");
120
+ if (!token || !email) throw notSignedIn();
112
121
  await enrollPasskey({
113
122
  apiUrl: ctx.apiUrl,
114
123
  projectId: ctx.projectId,
package/src/version.ts CHANGED
@@ -1,4 +1,4 @@
1
1
  /** Published @useauthio/react version — keep in sync with package.json. */
2
- export const SDK_VERSION = "0.3.0";
2
+ export const SDK_VERSION = "0.3.1";
3
3
 
4
4
  export const SDK_USER_AGENT = `react/${SDK_VERSION}` as const;