The phoneAuth plugin registers and authenticates users with a phone number and a one-time code. You supply the SMS delivery function. KavachOS handles code generation, expiry, and rate limiting.
Setup
import { createKavach } from 'kavachos';
import { phoneAuth } from 'kavachos/auth';
import { Twilio } from 'twilio';
const twilio = new Twilio(process.env.TWILIO_SID!, process.env.TWILIO_TOKEN!);
const kavach = await createKavach({
database: { provider: 'postgres', url: process.env.DATABASE_URL! },
secret: process.env.KAVACH_SECRET!,
baseUrl: 'https://auth.example.com',
plugins: [
phoneAuth({
onSendCode: async (phone, code) => {
await twilio.messages.create({
body: `Your verification code: ${code}`,
from: process.env.TWILIO_FROM!,
to: phone,
});
},
codeLength: 6,
codeExpiry: 300, // seconds
}),
],
});
Send code
POST /auth/phone/send-code
Sends a one-time code to the given phone number. Creates the user account on first send.
const res = await fetch('/auth/phone/send-code', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
phone: '+14155550123', // E.164 format
}),
});
// Always returns { success: true } to prevent phone enumeration
+ prefix, country code, number).
Error codes
| Code | Status | Meaning |
|---|
PHONE_INVALID | 422 | Not a valid E.164 phone number |
RATE_LIMITED | 429 | Too many codes sent to this number |
Verify code
POST /auth/phone/verify-code
Submits the code the user received. Returns a session on success.
const res = await fetch('/auth/phone/verify-code', {
method: 'POST',
credentials: 'include',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
phone: '+14155550123',
code: '482910',
}),
});
if (res.ok) {
const { user, session } = await res.json();
}
| Code | Status | Meaning |
|---|
INVALID_CODE | 401 | Code is wrong or expired |
CODE_EXPIRED | 401 | Code was valid but has passed its expiry window |
Configuration reference
Callback invoked to deliver the code. Receives the phone number (E.164) and the numeric code as a string.
Number of digits in the generated code.
codeExpiry
number
default:"300 (5 min)"
Code validity window in seconds.
Failed attempts allowed before the code is invalidated.
