@veroxm/sdk 1.8.0 → 1.9.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/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.9.0
4
+
5
+ - Bot protection (public API 2.12): `auth.getConfig()` says what a sign-in page should show (sign-up, social sign-in,
6
+ passkeys, and `botProtection`: the captcha provider, its site key, which forms need it, the honeypot and timing).
7
+ `signUp`, `signInWithEmail` and `requestPasswordReset` take a `BotCheck`: `botToken` (the Turnstile, hCaptcha or
8
+ reCAPTCHA v3 token), `website` (the hidden honeypot field) and `formStartedAt` (sent as `formElapsedMs`, so the
9
+ device's clock doesn't matter). Refusals are `VeroXMApiError`s with code `bot_check_required`, `bot_check_failed` or
10
+ `bot_check_unavailable`.
11
+
3
12
  ## 1.8.0
4
13
 
5
14
  - Writes to database content models (public API 2.11): `create`, `update` and `delete` work on a model that allows
package/dist/auth.d.ts CHANGED
@@ -15,6 +15,22 @@ export type EmailCode = {
15
15
  export type Account = Schemas['Account'];
16
16
  /** A social sign-in option to show a button for. */
17
17
  export type SocialProvider = Schemas['SocialProvider'];
18
+ /** What a sign-in page should show, from `getConfig()`: sign-up, social sign-in, passkeys and the bot check. */
19
+ export type AuthConfig = Schemas['AuthConfig'];
20
+ /** The bot check a project wants on its forms: the captcha provider and site key, the honeypot and timing. */
21
+ export type BotProtectionConfig = Schemas['BotProtectionConfig'];
22
+ /**
23
+ * Bot protection fields for sign-up, email sign-in and password reset, when the project has them on (see
24
+ * `getConfig().botProtection`). All optional.
25
+ */
26
+ export interface BotCheck {
27
+ /** The captcha widget's token (Turnstile, hCaptcha or reCAPTCHA v3). Each token works once: get a new one per try. */
28
+ botToken?: string;
29
+ /** The honeypot: the value of the hidden `website` field, which people leave empty. */
30
+ website?: string;
31
+ /** When the form was shown (`Date.now()` then). Sent as how long it was on screen, so the device's clock doesn't matter. */
32
+ formStartedAt?: number;
33
+ }
18
34
  /** The signed-in person's two-step sign-in and passkeys, from `twoStep()`. */
19
35
  export type TwoStepStatus = Schemas['TwoStepStatus'];
20
36
  /** A passkey on the person's account. */
@@ -77,20 +93,22 @@ export declare class VeroXMAuth {
77
93
  signInWithCredentials(username: string, password: string): Promise<AuthUser | null>;
78
94
  /**
79
95
  * Signs in a built-in account with its email and password. Throws VeroXMApiError with code `email_not_verified` until
80
- * the email is confirmed, and VeroXMTwoStepRequiredError when the person has two-step sign-in on.
96
+ * the email is confirmed, and VeroXMTwoStepRequiredError when the person has two-step sign-in on. Pass `bot` when the
97
+ * project's bot protection covers sign-in (codes `bot_check_required`, `bot_check_failed`, `bot_check_unavailable`).
81
98
  */
82
- signInWithEmail(email: string, password: string): Promise<AuthUser | null>;
99
+ signInWithEmail(email: string, password: string, bot?: BotCheck): Promise<AuthUser | null>;
83
100
  /** Signs out here: the refresh token is revoked on the server too (best effort), and the stored session cleared. */
84
101
  signOut(): Promise<void>;
85
102
  /**
86
103
  * Creates an account. When the project wants emails confirmed, resolves `{ verificationSent: true }` and the person
87
- * gets a 6-digit code (finish with `verifyEmail`); otherwise they're signed in and it resolves `{ user }`.
104
+ * gets a 6-digit code (finish with `verifyEmail`); otherwise they're signed in and it resolves `{ user }`. Add the
105
+ * `BotCheck` fields when the project's bot protection covers sign-up.
88
106
  */
89
107
  signUp(input: {
90
108
  email: string;
91
109
  password: string;
92
110
  name?: string;
93
- }): Promise<{
111
+ } & BotCheck): Promise<{
94
112
  verificationSent: true;
95
113
  } | {
96
114
  user: AuthUser | null;
@@ -99,8 +117,16 @@ export declare class VeroXMAuth {
99
117
  verifyEmail(input: EmailCode): Promise<AuthUser | null>;
100
118
  /** Sends a new confirmation code. Resolves the same whether or not the address has an account. */
101
119
  resendVerification(email: string): Promise<void>;
102
- /** Emails a password reset code. Resolves the same whether or not the address has an account. */
103
- requestPasswordReset(email: string): Promise<void>;
120
+ /**
121
+ * Emails a password reset code. Resolves the same whether or not the address has an account. Pass `bot` when the
122
+ * project's bot protection covers password reset.
123
+ */
124
+ requestPasswordReset(email: string, bot?: BotCheck): Promise<void>;
125
+ /**
126
+ * What a sign-in page should show: whether people can sign up, the social sign-in buttons, passkeys, and the bot
127
+ * check to render (`botProtection`: the provider, its site key, which forms need it, the honeypot and timing).
128
+ */
129
+ getConfig(): Promise<AuthConfig>;
104
130
  /** Sets a new password with the reset code (or the link's token), signs out every other device, and signs in here. */
105
131
  resetPassword(input: EmailCode & {
106
132
  password: string;
package/dist/auth.js CHANGED
@@ -2,6 +2,16 @@ import { rawRequest } from './http.js';
2
2
  import { VeroXMNotAuthenticatedError } from './errors.js';
3
3
  import { createPkce, randomString } from './pkce.js';
4
4
  import { browserPasskeys } from './passkeys.js';
5
+ /** The fields as the API takes them. */
6
+ function botFields(bot) {
7
+ if (!bot)
8
+ return {};
9
+ return {
10
+ ...(bot.botToken ? { botToken: bot.botToken } : {}),
11
+ ...(bot.website !== undefined ? { website: bot.website } : {}),
12
+ ...(typeof bot.formStartedAt === 'number' ? { formElapsedMs: Math.max(0, Date.now() - bot.formStartedAt) } : {}),
13
+ };
14
+ }
5
15
  function defaultPendingStore() {
6
16
  try {
7
17
  if (typeof window !== 'undefined' && window.sessionStorage) {
@@ -69,11 +79,11 @@ export class VeroXMAuth {
69
79
  }
70
80
  /**
71
81
  * Signs in a built-in account with its email and password. Throws VeroXMApiError with code `email_not_verified` until
72
- * the email is confirmed, and VeroXMTwoStepRequiredError when the person has two-step sign-in on.
82
+ * the email is confirmed, and VeroXMTwoStepRequiredError when the person has two-step sign-in on. Pass `bot` when the
83
+ * project's bot protection covers sign-in (codes `bot_check_required`, `bot_check_failed`, `bot_check_unavailable`).
73
84
  */
74
- async signInWithEmail(email, password) {
75
- await this.signInWithCredentials(email, password);
76
- return this.currentUser();
85
+ async signInWithEmail(email, password, bot) {
86
+ return this.signInWith('/auth/token', { username: email, password, ...botFields(bot) });
77
87
  }
78
88
  /** Signs out here: the refresh token is revoked on the server too (best effort), and the stored session cleared. */
79
89
  async signOut() {
@@ -91,10 +101,12 @@ export class VeroXMAuth {
91
101
  // ------------------------------------------------------------------ built-in accounts
92
102
  /**
93
103
  * Creates an account. When the project wants emails confirmed, resolves `{ verificationSent: true }` and the person
94
- * gets a 6-digit code (finish with `verifyEmail`); otherwise they're signed in and it resolves `{ user }`.
104
+ * gets a 6-digit code (finish with `verifyEmail`); otherwise they're signed in and it resolves `{ user }`. Add the
105
+ * `BotCheck` fields when the project's bot protection covers sign-up.
95
106
  */
96
107
  async signUp(input) {
97
- const data = (await this.post('/auth/signup', input));
108
+ const { botToken, website, formStartedAt, ...account } = input;
109
+ const data = (await this.post('/auth/signup', { ...account, ...botFields({ botToken, website, formStartedAt }) }));
98
110
  if ('accessToken' in data) {
99
111
  await this.persistSession(data);
100
112
  return { user: this.currentUser() };
@@ -109,9 +121,19 @@ export class VeroXMAuth {
109
121
  async resendVerification(email) {
110
122
  await this.post('/auth/verify/resend', { email });
111
123
  }
112
- /** Emails a password reset code. Resolves the same whether or not the address has an account. */
113
- async requestPasswordReset(email) {
114
- await this.post('/auth/password/forgot', { email });
124
+ /**
125
+ * Emails a password reset code. Resolves the same whether or not the address has an account. Pass `bot` when the
126
+ * project's bot protection covers password reset.
127
+ */
128
+ async requestPasswordReset(email, bot) {
129
+ await this.post('/auth/password/forgot', { email, ...botFields(bot) });
130
+ }
131
+ /**
132
+ * What a sign-in page should show: whether people can sign up, the social sign-in buttons, passkeys, and the bot
133
+ * check to render (`botProtection`: the provider, its site key, which forms need it, the honeypot and timing).
134
+ */
135
+ async getConfig() {
136
+ return (await rawRequest(this.apiBase, { path: '/auth/config' }));
115
137
  }
116
138
  /** Sets a new password with the reset code (or the link's token), signs out every other device, and signs in here. */
117
139
  async resetPassword(input) {
@@ -10,7 +10,7 @@ export interface paths {
10
10
  put?: never;
11
11
  /**
12
12
  * Sign in with a username (or email) and password
13
- * @description With two-step sign-in on for the person, answers 401 with code `two_step_required` and a `ticket` for /auth/two-step; when the project requires it and they have nothing set up, `two_step_setup_required` and a ticket for /auth/two-step/setup/...
13
+ * @description With two-step sign-in on for the person, answers 401 with code `two_step_required` and a `ticket` for /auth/two-step; when the project requires it and they have nothing set up, `two_step_setup_required` and a ticket for /auth/two-step/setup/... When the project's bot protection covers this form (GET /auth/config): send the captcha's `botToken`, the empty `website` honeypot, and `formElapsedMs`. No token is a 400 `bot_check_required`, a token the provider refuses a 403 `bot_check_failed`, and a 503 `bot_check_unavailable` when the provider cannot be reached (try again). A filled honeypot or a form sent too fast gets the usual answer (for sign-in, the wrong-password one), but nothing happens. It applies to signing in with an email address; usernames (API credentials, device accounts) are not asked.
14
14
  */
15
15
  post: operations["signIn"];
16
16
  delete?: never;
@@ -64,7 +64,7 @@ export interface paths {
64
64
  put?: never;
65
65
  /**
66
66
  * Create a built-in account
67
- * @description Signs the person in, or answers `{status: "verification_sent"}` when the project asks for a confirmed email first (or the address is already taken: the answer does not say which).
67
+ * @description Signs the person in, or answers `{status: "verification_sent"}` when the project asks for a confirmed email first (or the address is already taken: the answer does not say which). When the project's bot protection covers this form (GET /auth/config): send the captcha's `botToken`, the empty `website` honeypot, and `formElapsedMs`. No token is a 400 `bot_check_required`, a token the provider refuses a 403 `bot_check_failed`, and a 503 `bot_check_unavailable` when the provider cannot be reached (try again). A filled honeypot or a form sent too fast gets the usual answer (for sign-in, the wrong-password one), but nothing happens. The project limits sign-ups per IP address an hour (`too_many_attempts`, 429).
68
68
  */
69
69
  post: operations["signUp"];
70
70
  delete?: never;
@@ -116,7 +116,10 @@ export interface paths {
116
116
  };
117
117
  get?: never;
118
118
  put?: never;
119
- /** Email a password reset code */
119
+ /**
120
+ * Email a password reset code
121
+ * @description When the project's bot protection covers this form (GET /auth/config): send the captcha's `botToken`, the empty `website` honeypot, and `formElapsedMs`. No token is a 400 `bot_check_required`, a token the provider refuses a 403 `bot_check_failed`, and a 503 `bot_check_unavailable` when the provider cannot be reached (try again). A filled honeypot or a form sent too fast gets the usual answer (for sign-in, the wrong-password one), but nothing happens.
122
+ */
120
123
  post: operations["requestPasswordReset"];
121
124
  delete?: never;
122
125
  options?: never;
@@ -194,6 +197,26 @@ export interface paths {
194
197
  patch?: never;
195
198
  trace?: never;
196
199
  };
200
+ "/projects/{uuid}/auth/config": {
201
+ parameters: {
202
+ query?: never;
203
+ header?: never;
204
+ path?: never;
205
+ cookie?: never;
206
+ };
207
+ /**
208
+ * What a sign-in page should show
209
+ * @description Whether people can sign up, the social sign-in buttons, passkeys, and the bot check to render: the provider and its public site key, never the secret.
210
+ */
211
+ get: operations["getAuthConfig"];
212
+ put?: never;
213
+ post?: never;
214
+ delete?: never;
215
+ options?: never;
216
+ head?: never;
217
+ patch?: never;
218
+ trace?: never;
219
+ };
197
220
  "/projects/{uuid}/auth/social": {
198
221
  parameters: {
199
222
  query?: never;
@@ -540,7 +563,7 @@ export interface paths {
540
563
  };
541
564
  /**
542
565
  * A collection's entries
543
- * @description Flags are on when present (`?count`, `?timestamps`). With `count` the answer is a number. The slug can also name a database content model (entries read from a connected database): the key then also needs database:<db>:read, `filter.<field>[.<op>]=` filters, `userId=` or `ctx.<name>=` say whose rows for a model limited to the caller’s, and `state`, `locale` and `timestamps` don’t apply.
566
+ * @description Flags are on when present (`?count`, `?timestamps`). With `count` the answer is a number. The slug can also name a database content model (entries read from a connected database): the key then also needs database:<db>:read, `filter.<field>[.<op>]=` filters, `userId=` or `ctx.<name>=` say whose rows for a model limited to the caller’s, and `state`, `locale` and `timestamps` don’t apply. `unmask=true` returns masked fields in full and needs database:<db>:unmask (403 `forbidden` without it); each such read is marked in the database access log.
544
567
  */
545
568
  get: operations["listEntries"];
546
569
  put?: never;
@@ -778,7 +801,7 @@ export interface paths {
778
801
  };
779
802
  /**
780
803
  * A page of rows from an exposed table of a connected database
781
- * @description Needs database:<db>:read. Filters are filter.<column>=value or filter.<column>.<op>=value (eq, ne, gt, gte, lt, lte, in (comma-separated), contains, null (true/false)), on columns the table lets you filter. A table limited to the caller’s rows takes userId= or ctx.<name>= from a project key; an end user’s login is always themselves.
804
+ * @description Needs database:<db>:read. Filters are filter.<column>=value or filter.<column>.<op>=value (eq, ne, gt, gte, lt, lte, in (comma-separated), contains, null (true/false)), on columns the table lets you filter. A table limited to the caller’s rows takes userId= or ctx.<name>= from a project key; an end user’s login is always themselves. `unmask=true` returns masked columns in full and needs database:<db>:unmask; each such read is marked in the access log.
782
805
  */
783
806
  get: operations["listDatabaseRows"];
784
807
  put?: never;
@@ -1198,11 +1221,51 @@ export interface components {
1198
1221
  kind: "google" | "microsoft" | "apple" | "oidc";
1199
1222
  name: string;
1200
1223
  };
1224
+ BotProtectionConfig: {
1225
+ /**
1226
+ * @description The captcha to show: Cloudflare Turnstile, hCaptcha or Google reCAPTCHA v3.
1227
+ * @enum {string}
1228
+ */
1229
+ provider: "off" | "turnstile" | "hcaptcha" | "recaptcha";
1230
+ /** @description The provider's public site key, for the widget. */
1231
+ siteKey: string | null;
1232
+ /** @description The forms that need the check (and the honeypot and timing, when on). */
1233
+ actions: ("signup" | "signin" | "passwordReset")[];
1234
+ /** @description reCAPTCHA v3 only: the action name to pass to grecaptcha.execute for each form. */
1235
+ recaptchaActions: {
1236
+ signup: string;
1237
+ signin: string;
1238
+ passwordReset: string;
1239
+ } | null;
1240
+ /** @description Add a hidden `website` field to the forms and send it (empty). */
1241
+ honeypot: boolean;
1242
+ /** @description Send `formElapsedMs` with sign-up and password reset. */
1243
+ formTiming: boolean;
1244
+ };
1245
+ AuthConfig: {
1246
+ /**
1247
+ * @description Who can sign up: nobody by themselves (invitations), anyone, or people at some email domains.
1248
+ * @enum {string}
1249
+ */
1250
+ signup: "closed" | "open" | "domains";
1251
+ /** @description Whether people can sign in with a passkey. */
1252
+ passkeys: boolean;
1253
+ socialProviders: components["schemas"]["SocialProvider"][];
1254
+ botProtection: components["schemas"]["BotProtectionConfig"];
1255
+ };
1256
+ BotFields: {
1257
+ /** @description The captcha widget's token, when the project has a bot check for this form (or send it as `X-VeroXM-Bot-Token`). Each token works once. */
1258
+ botToken?: string;
1259
+ /** @description The honeypot: a field hidden from people. Leave it empty. */
1260
+ website?: string;
1261
+ /** @description How long the form was on screen before it was sent, in milliseconds (Date.now() minus when it was shown). */
1262
+ formElapsedMs?: number;
1263
+ };
1201
1264
  SignInRequest: {
1202
1265
  username?: string;
1203
1266
  email?: string;
1204
1267
  password?: string;
1205
- };
1268
+ } & components["schemas"]["BotFields"];
1206
1269
  RefreshRequest: {
1207
1270
  refreshToken?: string;
1208
1271
  };
@@ -1210,7 +1273,7 @@ export interface components {
1210
1273
  email?: string;
1211
1274
  password?: string;
1212
1275
  name?: string;
1213
- };
1276
+ } & components["schemas"]["BotFields"];
1214
1277
  CodeRequest: {
1215
1278
  email?: string;
1216
1279
  /** @description The 6-digit code from the email. */
@@ -1221,6 +1284,7 @@ export interface components {
1221
1284
  EmailRequest: {
1222
1285
  email?: string;
1223
1286
  };
1287
+ ForgotPasswordRequest: components["schemas"]["EmailRequest"] & components["schemas"]["BotFields"];
1224
1288
  ResetPasswordRequest: components["schemas"]["CodeRequest"] & {
1225
1289
  password?: string;
1226
1290
  };
@@ -2119,6 +2183,7 @@ export interface operations {
2119
2183
  403: components["responses"]["E403"];
2120
2184
  404: components["responses"]["E404"];
2121
2185
  429: components["responses"]["E429"];
2186
+ 503: components["responses"]["E503"];
2122
2187
  };
2123
2188
  };
2124
2189
  refreshSession: {
@@ -2209,6 +2274,7 @@ export interface operations {
2209
2274
  404: components["responses"]["E404"];
2210
2275
  409: components["responses"]["E409"];
2211
2276
  429: components["responses"]["E429"];
2277
+ 503: components["responses"]["E503"];
2212
2278
  };
2213
2279
  };
2214
2280
  verifyEmail: {
@@ -2285,7 +2351,7 @@ export interface operations {
2285
2351
  };
2286
2352
  requestBody: {
2287
2353
  content: {
2288
- "application/json": components["schemas"]["EmailRequest"];
2354
+ "application/json": components["schemas"]["ForgotPasswordRequest"];
2289
2355
  };
2290
2356
  };
2291
2357
  responses: {
@@ -2299,8 +2365,10 @@ export interface operations {
2299
2365
  };
2300
2366
  };
2301
2367
  400: components["responses"]["E400"];
2368
+ 403: components["responses"]["E403"];
2302
2369
  404: components["responses"]["E404"];
2303
2370
  429: components["responses"]["E429"];
2371
+ 503: components["responses"]["E503"];
2304
2372
  };
2305
2373
  };
2306
2374
  resetPassword: {
@@ -2489,6 +2557,30 @@ export interface operations {
2489
2557
  429: components["responses"]["E429"];
2490
2558
  };
2491
2559
  };
2560
+ getAuthConfig: {
2561
+ parameters: {
2562
+ query?: never;
2563
+ header?: never;
2564
+ path: {
2565
+ /** @description The project's UUID. */
2566
+ uuid: string;
2567
+ };
2568
+ cookie?: never;
2569
+ };
2570
+ requestBody?: never;
2571
+ responses: {
2572
+ /** @description OK */
2573
+ 200: {
2574
+ headers: {
2575
+ [name: string]: unknown;
2576
+ };
2577
+ content: {
2578
+ "application/json": components["schemas"]["AuthConfig"];
2579
+ };
2580
+ };
2581
+ 404: components["responses"]["E404"];
2582
+ };
2583
+ };
2492
2584
  listSocialProviders: {
2493
2585
  parameters: {
2494
2586
  query?: never;
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { VeroXMApp } from './client.js';
2
2
  export type { VeroXMAppOptions } from './client.js';
3
3
  export { VeroXMAuth } from './auth.js';
4
- export type { Account, AuthenticatorSetup, EmailCode, Passkey, PendingStore, SecondStep, SocialProvider, SocialSignInStart, TwoStepStatus, WithTicket, } from './auth.js';
4
+ export type { Account, AuthConfig, AuthenticatorSetup, BotCheck, BotProtectionConfig, EmailCode, Passkey, PendingStore, SecondStep, SocialProvider, SocialSignInStart, TwoStepStatus, WithTicket, } from './auth.js';
5
5
  export { browserPasskeys, creationOptionsFromJSON, credentialToJSON, requestOptionsFromJSON } from './passkeys.js';
6
6
  export type { PasskeyOptionsJSON, PasskeyProvider } from './passkeys.js';
7
7
  export { createPkce } from './pkce.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veroxm/sdk",
3
- "version": "1.8.0",
3
+ "version": "1.9.0",
4
4
  "description": "VeroXM client for JavaScript and TypeScript: content, media, experiences, events and the visitor tracker.",
5
5
  "keywords": [
6
6
  "veroxm",