phone-number/options

7 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Sign up with phone number via signUpOnVerification

To allow users to sign up using phone number, pass the signUpOnVerification option to the plugin configuration with a getTempEmail function that generates a temporary email from the phone number. Optionally pass getTempName function to generate a temporary name (defaults to using the phone number). Additional required user schema fields can be passed in the verify request body.

Disable session creation after verification

By default, the phone number plugin creates a session after verification. To disable this, pass disableSession: true to the verify method. This prevents automatic session creation while still verifying the phone number.

Phone number plugin options reference

Plugin configuration options: otpLength (number, default 6) - length of OTP code; sendOTP (function, required) - sends OTP via SMS; expiresIn (number, default 300 seconds) - OTP expiration time; callbackOnVerification (function, optional) - called after verification with phoneNumber and user object; sendPasswordResetOTP (function, optional) - sends OTP for password reset; phoneNumberValidator (function, optional) - custom phone number validation; verifyOTP (function, optional) - custom OTP verification logic (overrides internal verification); signUpOnVerification (object, optional) - enables sign-up on verification with getTempEmail and getTempName functions; requireVerification (boolean, optional) - when enabled, prevents sign-in until phone number is verified.

OTP brute force protection

The phone number plugin includes built-in brute force protection with an allowedAttempts option (default is 3). When a user exceeds the allowed verification attempts, the OTP code is automatically deleted and further attempts return a 403 Forbidden status with 'Too many attempts' message. The user must request a new OTP code to continue.

Custom OTP verification with external provider

The verifyOTP option allows integration with external SMS providers like Twilio Verify or AWS SNS. When provided, this function is used instead of internal verification logic. It receives an object with phoneNumber and code properties and a request object, and returns a boolean or promise resolving to a boolean indicating whether the OTP is valid.

Avoid awaiting sendOTP function

It is highly recommended not to await the sendOTP function as it slows down requests and could cause timing attacks. For serverless platforms, use waitUntil to ensure the OTP is sent without blocking the request.

requireVerification option behavior

When requireVerification is enabled, users cannot sign in with their phone number until it has been verified. If an unverified user attempts to sign in, the server responds with a 401 error (PHONE_NUMBER_NOT_VERIFIED) and automatically triggers an OTP send to start the verification process.

Give your agent this brain