Email and password

The emailPassword plugin handles user registration, sign-in, email verification, and password management. Passwords are hashed with scrypt (N=16384, r=8, p=1) using Node’s built-in node:crypto module, no extra dependencies.

Because scrypt uses node:crypto, the emailPassword plugin requires a Node.js runtime. It does not run on Cloudflare Workers, Deno Deploy, or Vercel Edge Functions as-is. If you need edge runtime support, replace the hasher with PBKDF2 via the Web Crypto API using the password.hash and password.verify options shown below.

If you prefer username-based auth instead of email, see the username plugin.

Setup

By default, sign-in requires email verification. In development, set requireVerification: false to skip this. Without it, users who sign up cannot sign in until they verify their email.

Dev vs production config

// Development: skip email verification
emailPassword({
  requireVerification: false,
  onSendVerification: async (email, token) => {
    console.log(`Verify: http://localhost:3000/verify?token=${token}`);
  },
})

// Production: require verification
emailPassword({
  requireVerification: true, // default
  onSendVerification: async (email, token, url) => {
    await sendEmail(email, 'Verify your email', `Click: ${url}`);
  },
})

Install the plugin

lib/kavach.ts

import { createKavach } from 'kavachos';
import { emailPassword } from 'kavachos/auth'; 

const kavach = await createKavach({
  database: { provider: 'postgres', url: process.env.DATABASE_URL! },
  secret: process.env.KAVACH_SECRET!,
  baseUrl: 'https://auth.example.com',
  plugins: [
    emailPassword({ 
      appUrl: 'https://app.example.com', 
      requireVerification: true, 
      sendVerificationEmail: async (email, token, url) => { 
        await resend.emails.send({ 
          from: 'auth@example.com', 
          to: email, 
          subject: 'Confirm your email', 
          html: `<a href="${url}">Verify your email</a>`, 
        }); 
      }, 
      sendResetEmail: async (email, token, url) => { 
        await resend.emails.send({ 
          from: 'auth@example.com', 
          to: email, 
          subject: 'Reset your password', 
          html: `<a href="${url}">Reset password</a>`, 
        }); 
      }, 
    }), 
  ],
});

Mount the handler

The plugin registers endpoints automatically. You still need to route incoming requests to KavachOS from your framework adapter.

Next.js
Express
Hono

app/api/auth/[...kavach]/route.ts

import { kavach } from '@/lib/kavach';

export const { GET, POST } = kavach.handler;

server.ts

import { kavach } from './lib/kavach';

app.use('/auth', kavach.handler);

src/index.ts

import { kavach } from './lib/kavach';

app.use('/auth/*', kavach.handler);

POST /auth/sign-up Creates a new user account. Returns a session token on success. If requireVerification is true, the user also receives a verification email immediately.

const res = await fetch('/auth/sign-up', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com', 
    password: 'correct horse battery', 
    name: 'Ada Lovelace',
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  console.error(error.code, error.message);
} else {
  const { user, token } = await res.json();
  // token is the session token. Store it in a cookie or local storage
}

Request body

string

required

User email address.

string

required

Password. Must meet the configured length and complexity rules.

string

Display name for the user.

Response 201 Created

{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "Ada Lovelace",
    "emailVerified": false,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  },
  "token": "session-token"
}

You can extend the user record with additional fields (e.g. avatarUrl, role) by hooking into the onUserCreated lifecycle. The name field is the only optional built-in.

POST /auth/sign-in Authenticates a user and returns a session token. Always returns a generic “Invalid email or password” message for wrong credentials. The response does not distinguish between a missing account and a wrong password.

const res = await fetch('/auth/sign-in', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com', 
    password: 'correct horse battery', 
  }),
});

if (res.status === 401) {
  // Either wrong credentials or email not yet verified
  const { error } = await res.json();
  if (error.code === 'EMAIL_NOT_VERIFIED') {
    // prompt the user to check their inbox
  }
} else {
  const { user, session } = await res.json();
  // session.token, session.expiresAt
}

Request body

string

required

User email address.

string

required

User password.

Response 200 OK

{
  "user": { "id": "usr_abc123", "email": "user@example.com", "emailVerified": true },
  "session": {
    "token": "session-token",
    "expiresAt": "2025-01-08T00:00:00.000Z"
  }
}

Error codes

Code	Status	Meaning
`INVALID_CREDENTIALS`	401	Wrong email or password
`EMAIL_NOT_VERIFIED`	401	Account exists but email has not been verified

Sign out

POST /auth/sign-out Revokes the current session. The session cookie is cleared by the server.

Sign out (client)

await fetch('/auth/sign-out', {
  method: 'POST',
  credentials: 'include',
});

// Redirect to home or login
window.location.href = '/';

Email verification

When requireVerification: true, sign-in returns 401 with code EMAIL_NOT_VERIFIED until the user clicks the link sent at registration. The link hits your app’s callback URL, which should POST the token to /auth/verify-email.

Enable verification

lib/kavach.ts

emailPassword({
  appUrl: 'https://app.example.com',
  requireVerification: true, 
  sendVerificationEmail: async (email, token, url) => { 
    // `url` is already constructed: appUrl + /auth/verify-email?token=...
    await mailer.send({ to: email, subject: 'Verify your email', html: `<a href="${url}">Confirm</a>` });
  },
}),

Handle the callback

Your app receives the token in the URL. Send it to the endpoint:

app/auth/verify-email/page.tsx (Next.js)

const token = new URL(window.location.href).searchParams.get('token');

await fetch('/auth/verify-email', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token }), 
});

Resend verification

If the user lost the email, they can trigger a new one:

Resend verification (client)

await fetch('/auth/request-reset', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com' }),
});

The sendVerificationEmail callback runs synchronously during sign-up. If your email provider is slow, use fire-and-forget: wrap the send call in void someEmailFn(...) so it does not block the response. Make sure you have proper error logging so failures are visible.

Email enumeration protection

When requireVerification: true, the sign-up endpoint returns 201 even if the email is already registered. The existing user gets a “someone tried to create an account with your email” notification instead of an error being exposed to the attacker. This prevents an attacker from harvesting valid email addresses by observing which registrations fail with 409 Conflict. The password reset endpoint (/auth/request-reset) follows the same pattern. It always returns 200 regardless of whether the email exists. See OWASP: Prevent Username Enumeration for background.

Password reset

Configure the reset email

lib/kavach.ts

emailPassword({
  appUrl: 'https://app.example.com',
  sendResetEmail: async (email, token, url) => { 
    await mailer.send({
      to: email,
      subject: 'Reset your password',
      html: `<a href="${url}">Reset password</a> (expires in 1 hour)`,
    });
  },
  resetExpiry: 3600, // seconds, default 3600 (1 hour)
}),

Request a reset link

POST /auth/request-reset

Request reset (client)

await fetch('/auth/request-reset', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com' }), 
});
// Always returns { success: true }. Never reveals if the email exists

Submit the new password

POST /auth/reset-passwordYour reset page receives the token from the URL. Collect the new password and post both:

Reset password (client)

const token = new URL(window.location.href).searchParams.get('token');

const res = await fetch('/auth/reset-password', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    token, 
    newPassword: 'new-strong-password', 
  }),
});

On success, all sessions for that user are revoked. They will need to sign in again.

Rate limiting on /auth/request-reset is set to 3 requests per 60 seconds by default. Do not remove it. Without a rate limit, the endpoint can be used to spam users with reset emails.

Change password

POST /auth/change-password Requires an active session. The endpoint reads the user identity from the session, no userId in the request body.

Change password (client)

const res = await fetch('/auth/change-password', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    currentPassword: 'old-password', 
    newPassword: 'new-stronger-password', 
  }),
});

Request body

string

required

The user’s current password.

string

required

The new password. Must meet configured strength requirements.

The current session stays active after a successful change. Other sessions for the same user are not revoked (unlike a password reset). If you want to sign out other devices, revoke sessions explicitly via the session management API.

Password configuration

Passwords are hashed with scrypt using Node’s built-in node:crypto module (N=16384, r=8, p=1, keylen=64 bytes). These parameters match OWASP interactive login recommendations and require no external dependencies.

Custom strength rules

lib/kavach.ts

emailPassword({
  password: {
    minLength: 12, 
    maxLength: 128, 
    requireUppercase: true, 
    requireNumber: true, 
    requireSpecial: false,
  },
}),

Custom hash function

If you need a different algorithm, bring your own hash and verify functions. Edge runtimes (Cloudflare Workers, Deno Deploy, Vercel Edge): use PBKDF2 via the Web Crypto API, which is available everywhere:

lib/kavach.ts

emailPassword({
  password: {
    hash: async (password) => { 
      const enc = new TextEncoder();
      const keyMaterial = await crypto.subtle.importKey(
        'raw', enc.encode(password), 'PBKDF2', false, ['deriveBits'],
      );
      const salt = crypto.getRandomValues(new Uint8Array(32));
      const derived = await crypto.subtle.deriveBits(
        { name: 'PBKDF2', hash: 'SHA-256', salt, iterations: 600_000 },
        keyMaterial, 512,
      );
      const toHex = (b: Uint8Array) => Array.from(b).map(x => x.toString(16).padStart(2, '0')).join('');
      return `pbkdf2:600000:${toHex(salt)}:${toHex(new Uint8Array(derived))}`; 
    },
    verify: async (password, stored) => { 
      const [, iterations, saltHex, hashHex] = stored.split(':');
      const fromHex = (s: string) => new Uint8Array(s.match(/.{2}/g)!.map(b => parseInt(b, 16)));
      const enc = new TextEncoder();
      const keyMaterial = await crypto.subtle.importKey(
        'raw', enc.encode(password), 'PBKDF2', false, ['deriveBits'],
      );
      const derived = await crypto.subtle.deriveBits(
        { name: 'PBKDF2', hash: 'SHA-256', salt: fromHex(saltHex), iterations: parseInt(iterations, 10) },
        keyMaterial, 512,
      );
      const toHex = (b: Uint8Array) => Array.from(b).map(x => x.toString(16).padStart(2, '0')).join('');
      return toHex(new Uint8Array(derived)) === hashHex; 
    },
  },
}),

Node.js with argon2id: use @node-rs/argon2 for stronger memory-hard hashing on full Node.js servers:

lib/kavach.ts

import { hash, verify } from '@node-rs/argon2';

emailPassword({
  password: {
    hash: async (password) => { 
      return hash(password, { 
        memoryCost: 65536, 
        timeCost: 3, 
        parallelism: 4, 
      }); 
    }, 
    verify: async (password, stored) => { 
      return verify(stored, password); 
    }, 
  },
}),

The default scrypt implementation is fine for most Node.js deployments. Use a custom hasher when you are migrating from an existing system, need edge runtime support, or want stronger memory-hard guarantees.

Configuration reference

string

required

Base URL for verification and reset links. Links are constructed as appUrl + /auth/verify-email?token=… and appUrl + /auth/reset-password?token=…

required

Called after sign-up with the recipient email, raw token, and fully constructed URL.

required

Called when a user requests a password reset. Same signature as sendVerificationEmail.

boolean

default:"true"

Block sign-in until the user clicks the email verification link.

number

default:"86400 (24h)"

Verification token lifetime in seconds.

number

default:"3600 (1h)"

Password reset token lifetime in seconds.

Overview

Methods

OAuth providers

Enterprise

Email and password

Setup

Dev vs production config

Install the plugin

Mount the handler

Sign out

Email verification

Enable verification

Handle the callback

Resend verification

Email enumeration protection

Password reset

Configure the reset email

Request a reset link

Submit the new password

Change password

Password configuration

Custom strength rules

Custom hash function

Configuration reference

​Setup

​Dev vs production config

​Install the plugin

​Mount the handler

​Sign up

​Sign in

​Sign out

​Email verification

​Enable verification

​Handle the callback

​Resend verification

​Email enumeration protection

​Password reset

​Configure the reset email

​Request a reset link

​Submit the new password

​Change password

​Password configuration

​Custom strength rules

​Custom hash function

​Configuration reference

Setup

Dev vs production config

Install the plugin

Mount the handler

Sign up

Sign in

Sign out

Email verification

Enable verification

Handle the callback

Resend verification

Email enumeration protection

Password reset

Configure the reset email

Request a reset link

Submit the new password

Change password

Password configuration

Custom strength rules

Custom hash function

Configuration reference