The trusted device module lets users mark a device as trusted after completing two-factor authentication. On subsequent sign-ins from that device, 2FA is skipped. Trust is stored as an HMAC-signed fingerprint, not a plain device ID, so it cannot be guessed or forged.
Setup
import { createKavach } from 'kavachos';
import { twoFactor } from 'kavachos/auth';
import { createTrustedDeviceModule } from 'kavachos/modules/trusted-device';
const trustedDevice = createTrustedDeviceModule({
secret: process.env.TRUSTED_DEVICE_SECRET!, // separate from KAVACH_SECRET
trustDuration: 30 * 24 * 60 * 60, // 30 days in seconds
});
const kavach = await createKavach({
database: { provider: 'postgres', url: process.env.DATABASE_URL! },
secret: process.env.KAVACH_SECRET!,
baseUrl: 'https://auth.example.com',
plugins: [
twoFactor({
isTrustedDevice: trustedDevice.verify,
}),
],
modules: [trustedDevice],
});
Trust a device
After the user completes 2FA, call trust() to mark their device. Pass any stable identifier, a browser fingerprint, a cookie value you control, or a combination:
import { trustedDevice } from './lib/kavach';
// After verifying the 2FA code:
const { token, expiresAt } = await trustedDevice.trust({
userId: session.userId,
fingerprint: request.headers.get('x-device-fingerprint') ?? '',
userAgent: request.headers.get('user-agent') ?? '',
});
// Store the token in a long-lived cookie
response.setCookie('td_token', token, { maxAge: 30 * 24 * 60 * 60, httpOnly: true });
Verify a trusted device
On sign-in, check whether the device is already trusted before requiring 2FA:
Check on sign-in (server)
const token = request.cookies.get('td_token');
const trusted = await trustedDevice.verify({
userId: user.id,
token,
fingerprint: request.headers.get('x-device-fingerprint') ?? '',
});
if (trusted) {
// Skip 2FA, proceed with session creation
}
Revoke a device
Users can revoke specific devices from an account settings page:
Revoke one device (server)
await trustedDevice.revoke({ userId: session.userId, token: deviceToken });
Revoke all devices
Revoke all devices (server)
await trustedDevice.revokeAll({ userId: session.userId });
List trusted devices
const devices = await trustedDevice.list({ userId: session.userId });
// [{ id, userAgent, createdAt, expiresAt }, ...]
Configuration reference
Secret used to HMAC-sign device fingerprints. Rotate this to invalidate all trusted devices instantly.
trustDuration
number
default:"2592000 (30 days)"
How long a device stays trusted, in seconds.
Maximum number of trusted devices per user. Oldest is evicted when exceeded.
