@zalt/core

Headless TypeScript client for Zalt.io authentication. Zero dependencies, works everywhere.

Installation

npm install @zalt/core

Quick Start

import { ZaltClient } from '@zalt/core';

const zalt = new ZaltClient({
  realmId: 'your-realm-id',
});

// Login
const result = await zalt.login('[email protected]', 'password');

if (result.mfaRequired) {
  // Handle MFA
  await zalt.mfa.verify(result.sessionId, '123456');
}

// Get current user
const user = zalt.getUser();
console.log('Logged in as:', user.email);

// Logout
await zalt.logout();

Features

• 🔐 Secure by default - httpOnly cookies, RS256 JWT
• 🔄 Auto token refresh - Seamless token management
• 🛡️ MFA support - TOTP, WebAuthn, SMS (with risk acceptance)
• 📦 Zero dependencies - < 5KB gzipped
• 🌐 Universal - Works in browser, Node.js, edge runtimes

API Reference

ZaltClient

const zalt = new ZaltClient({
  realmId: string;           // Required: Your realm ID
  apiUrl?: string;           // Default: 'https://api.zalt.io'
  storage?: 'cookie' | 'localStorage' | 'memory';
});

Authentication

// Login
const result = await zalt.login(email, password);
// Returns: { user, accessToken, mfaRequired?, sessionId? }

// Register
const user = await zalt.register(email, password, {
  firstName?: string;
  lastName?: string;
});

// Logout
await zalt.logout();

// Get current user
const user = zalt.getUser();

// Check authentication
const isAuth = zalt.isAuthenticated();

MFA

// Setup TOTP
const { qrCode, secret, backupCodes } = await zalt.mfa.setup('totp');

// Verify code
await zalt.mfa.verify(code);

// Get status
const status = await zalt.mfa.getStatus();

// Disable MFA
await zalt.mfa.disable(code);

WebAuthn

// Check support
const supported = await zalt.webauthn.isSupported();

// Register passkey
await zalt.webauthn.register({ name: 'My Laptop' });

// Authenticate with passkey
await zalt.webauthn.authenticate();

// List credentials
const credentials = await zalt.webauthn.listCredentials();

// Remove credential
await zalt.webauthn.removeCredential(credentialId);

SMS MFA (Not Recommended)

⚠️ SMS MFA is vulnerable to SS7 attacks. Use TOTP or WebAuthn instead.

// Setup with explicit risk acceptance
await zalt.sms.setup(phoneNumber, {
  acceptRisk: true,
  riskAcknowledgement: 'I understand SS7 vulnerabilities',
});

// Verify
await zalt.sms.verify(code);

Events

// Subscribe to auth state changes
const unsubscribe = zalt.onAuthStateChange((event, user) => {
  console.log('Auth event:', event); // 'login' | 'logout' | 'refresh' | 'error'
  console.log('User:', user);
});

// Unsubscribe
unsubscribe();

Error Handling

import { 
  ZaltError, 
  AuthenticationError, 
  RateLimitError,
  NetworkError,
  MFARequiredError 
} from '@zalt/core';

try {
  await zalt.login(email, password);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Retry after:', error.retryAfter, 'seconds');
  } else if (error instanceof AuthenticationError) {
    console.log('Invalid credentials');
  } else if (error instanceof MFARequiredError) {
    console.log('MFA required, session:', error.sessionId);
  }
}

Security

• Tokens stored in httpOnly cookies by default
• RS256 JWT algorithm (FIPS-compliant)
• Automatic token refresh
• Rate limiting awareness
• No sensitive data logging

License

MIT