@tekvora/auth-sdk

A production-grade TypeScript SDK for the Tekvora Auth Platform. This SDK handles Multi-Factor Authentication (MFA), Passkeys (WebAuthn), and secure session management with built-in protection against brute-force and replay attacks.

Installation

npm install @tekvora/auth-sdk
# or
pnpm add @tekvora/auth-sdk

Initialization

The SDK is designed to work out-of-the-box with zero configuration beyond your identifiers.

Standard Initialization

const auth = new TekvoraAuth('your_api_key_here', 'https://auth-api.example.com');

The SDK automatically:

• Detects if it should use Secure cookies based on the connection (HTTPS vs HTTP).
• Sets SameSite: Lax for optimal security and compatibility.
• Manages token persistence and refreshing.

Advanced Config (Optional)

Only use this if you need to override cookie behavior or domains.

const auth = new TekvoraAuth({
  apiKey: 'your_api_key_here',
  baseUrl: 'https://auth-api.example.com',
  cookieConfig: {
    domain: '.yourdomain.com', // For cross-subdomain auth
    path: '/auth'
  }
});

1. Authentication Flow

The authentication flow is divided into two phases if Multi-Factor Authentication (MFA) is enabled.

Phase 1: Primary Login

Initializes the session with email and password.

const response = await auth.login('[email protected]', 'password123');

if (response.mfaRequired) {
  // MFA is enabled for this user. 
  // You MUST proceed to Phase 2 using the mfaToken.
  const { mfaToken, email, preferredMethod, enabledMethods } = response;
  // Store mfaToken in your frontend state
} else {
  // Login successful, tokens are automatically saved to cookies.
  console.log('User logged in:', response.user);
}

Phase 2: MFA Verification

Required if mfaRequired was returned in Phase 1. This uses a hardened partial-session approach.

// mfaToken is the token received from the login response
// code is the 6-digit TOTP or Email code
const result = await auth.verifyLogin(
  '[email protected]', 
  mfaCode, 
  mfaToken, 
  'totp' // optional: 'totp' | 'email' | 'passkey'
);

console.log('MFA Verified!', result.accessToken);

2. Passkey Authentication (WebAuthn)

The SDK uses @simplewebauthn/browser for biometrics and hardware keys.

Login with Passkey

This supports discoverable credentials (login without typing an email) if the browser facilitates it.

// Email is optional for discoverable credentials
const response = await auth.loginWithPasskey('[email protected]');

if (response.accessToken) {
  router.push('/dashboard');
}

Registering a Passkey (Logged In)

Users must be authenticated to register a new biometric credential.

const success = await auth.registerPasskey();
if (success) {
  alert('Passkey registered successfully!');
}

3. Account Security Management

MFA Setup (TOTP/App)

// 1. Initialize setup
const { qrCode, secret } = await auth.setupMFA('totp');

// 2. Show QR code to user, then verify the first code to enable
const { recoveryCodes } = await auth.verifyMFA(verificationCode, 'totp');

// IMPORTANT: Display recoveryCodes to the user and ensure they are saved.
// These are only shown once in plain text.

Regeneration of Recovery Codes

const { recoveryCodes } = await auth.regenerateRecoveryCodes();

4. Session & Token Management

The SDK automatically manages tekvora_at (Access Token) and tekvora_rt (Refresh Token) in browser cookies.

• auth.logout(): Clears tokens from memory and deletes cookies.
• auth.getMe(): Fetches the current user profile using the active session.
• auth.refreshTokens(): Manually triggers a refresh flow. This is also handled automatically via Axios interceptors on 401 responses.

5. Security Features

• Hardened MFA: The mfaToken is short-lived (5m) and cryptographically linked to the specific login attempt.
• Lockout Protection: After 5 failed MFA attempts, the account is locked for 15 minutes. The SDK will throw a 403 error in this case.
• Replay Protection: TOTP codes are tracked and cannot be reused within the same 30-second window.
• Encrypted Secrets: TOTP seeds and recovery codes are never stored or transmitted in plain text on the server (encrypted via AES-256-GCM and hashed via Argon2ID).

Error Handling

The SDK throws errors for non-2xx responses. Always wrap calls in try-catch.

try {
  await auth.login(email, password);
} catch (err: any) {
  const errorMessage = err.response?.data?.error || 'An unexpected error occurred';
  console.error(errorMessage);
}