@zkauth/sdk

Official JavaScript/TypeScript SDK for ZKAuth - Zero-Knowledge Proof Authentication

🚀 Features

- Zero-Knowledge Proofs: Authenticate without ever sending passwords
- Privacy-First: Passwords never leave the client
- Device Management: Secure multi-device authentication
- MFA Support: Optional multi-factor authentication
- TypeScript: Full type safety with TypeScript definitions
- Easy Integration: Simple API with async/await
- Event System: React to authentication events
- Production Ready: Battle-tested and secure

📦 Installation

``bash
npm install @zkauth/sdk
`

or

`bash
yarn add @zkauth/sdk
`

🔑 Getting Started

$3

Visit the ZKAuth Developer Platform to:
1. Create an account
2. Create a new project
3. Get your API keys (live and test)

$3

`typescript
import { ZKAuthSDK } from '@zkauth/sdk';

const zkauth = new ZKAuthSDK({
apiKey: 'your-api-key', // From developer platform
baseUrl: 'https://zkauth.vercel.app', // Optional, defaults to production
debug: false, // Optional, enable debug logs
});
`

$3

`typescript
const result = await zkauth.register({
email: 'user@example.com',
password: 'secure-password',
deviceInfo: {
deviceName: 'Chrome on MacBook',
deviceType: 'desktop',
browserName: 'Chrome',
osName: 'macOS',
},
cognitiveQuestion: 'What is your favorite color?',
cognitiveAnswer: 'blue',
});

console.log('User registered:', result.data.userId);
`

$3

`typescript
const result = await zkauth.login({
email: 'user@example.com',
password: 'secure-password',
});

console.log('Logged in:', result.data.user);
console.log('Session token:', result.data.session.token);
`

$3

`typescript
if (zkauth.isAuthenticated()) {
const user = await zkauth.getCurrentUser();
console.log('Current user:', user);
}
`

$3

`typescript
await zkauth.logout();
`

📚 API Reference

$3

#### register(params: RegisterParams): Promise

Register a new user with ZKP commitment.

`typescript
const result = await zkauth.register({
email: 'user@example.com',
password: 'secure-password',
deviceInfo: {
deviceName: 'My Device',
deviceType: 'desktop',
},
});
`

#### login(params: LoginParams): Promise

Login user with ZKP proof.

`typescript
const result = await zkauth.login({
email: 'user@example.com',
password: 'secure-password',
});
`

#### logout(): Promise

Logout current user.

`typescript
await zkauth.logout();
`

#### getCurrentUser(): Promise

Get currently authenticated user.

`typescript
const user = await zkauth.getCurrentUser();
`

#### isAuthenticated(): boolean

Check if user is authenticated.

`typescript
if (zkauth.isAuthenticated()) {
// User is logged in
}
`

$3

#### forgotPassword(params: ForgotPasswordParams): Promise

Request password reset.

`typescript
await zkauth.forgotPassword({
email: 'user@example.com',
});
`

#### verifyResetToken(token: string): Promise

Verify password reset token.

`typescript
const result = await zkauth.verifyResetToken(token);
`

#### resetPassword(params: ResetPasswordParams): Promise

Complete password reset.

`typescript
await zkauth.resetPassword({
token: 'reset-token',
newPassword: 'new-secure-password',
});
`

$3

#### registerDevice(params: RegisterDeviceParams): Promise

Register a new trusted device.

`typescript
const result = await zkauth.registerDevice({
deviceInfo: {
deviceName: 'iPhone 13',
deviceType: 'mobile',
},
});
`

#### verifyDevice(params: VerifyDeviceParams): Promise

Verify device access with ZKP proof.

`typescript
const result = await zkauth.verifyDevice({
deviceId: 'device-id',
proof: proof,
publicSignals: signals,
proofNonce: nonce,
proofTimestamp: timestamp,
});
`

#### getDevices(): Promise

Get list of user's devices.

`typescript
const devices = await zkauth.getDevices();
`

#### removeDevice(deviceId: string): Promise

Remove a device.

`typescript
await zkauth.removeDevice('device-id');
`

$3

#### getMFAStatus(): Promise

Get MFA status for current user.

`typescript
const status = await zkauth.getMFAStatus();
console.log('MFA enabled:', status.mfaEnabled);
`

$3

#### on(event: ZKAuthEvent, callback: EventCallback): () => void

Subscribe to events.

`typescript
const unsubscribe = zkauth.on('login', (user) => {
console.log('User logged in:', user);
});

// Later, unsubscribe
unsubscribe();
`

Available events:
- login - User logged in
- logout - User logged out
- register - User registered
- session_expired - Session expired
- mfa_required - MFA required
- device_approval_required - Device approval required
- error - Error occurred

🔒 Security

$3

1. Password Hashing: Passwords are hashed client-side using Argon2id
2. Commitment Generation: A cryptographic commitment is created from the password hash
3. ZKP Generation: A zero-knowledge proof is generated to prove knowledge of the password
4. Proof Verification: Backend verifies the proof without ever seeing the password

$3

- ✅ Passwords never sent over the network
- ✅ Zero-knowledge proof authentication
- ✅ Argon2id password hashing (64 MB, 3 iterations, 4 parallelism)
- ✅ Replay attack protection
- ✅ Device fingerprinting
- ✅ Session management
- ✅ MFA support

🎨 Examples

$3

`typescript
import { useState, useEffect } from 'react';
import { ZKAuthSDK } from '@zkauth/sdk';

const zkauth = new ZKAuthSDK({
apiKey: process.env.REACT_APP_ZKAUTH_API_KEY!,
});

function App() {
const [user, setUser] = useState(null);

useEffect(() => {
// Subscribe to login events
const unsubscribe = zkauth.on('login', (userData) => {
setUser(userData);
});

// Check if already authenticated
zkauth.getCurrentUser().then(setUser);

return () => unsubscribe();
}, []);

const handleLogin = async (email: string, password: string) => {
try {
const result = await zkauth.login({ email, password });
setUser(result.data.user);
} catch (error) {
console.error('Login failed:', error);
}
};

const handleLogout = async () => {
await zkauth.logout();
setUser(null);
};

return (


`typescript
import { ref, onMounted } from 'vue';
import { ZKAuthSDK } from '@zkauth/sdk';

export default {
setup() {
const zkauth = new ZKAuthSDK({
apiKey: import.meta.env.VITE_ZKAUTH_API_KEY,
});

const user = ref(null);

onMounted(async () => {
zkauth.on('login', (userData) => {
user.value = userData;
});

user.value = await zkauth.getCurrentUser();
});

const login = async (email, password) => {
const result = await zkauth.login({ email, password });
user.value = result.data.user;
};

const logout = async () => {
await zkauth.logout();
user.value = null;
};

return { user, login, logout };
},
};
`

$3

`typescript
// lib/zkauth.ts
import { ZKAuthSDK } from '@zkauth/sdk';

export const zkauth = new ZKAuthSDK({
apiKey: process.env.NEXT_PUBLIC_ZKAUTH_API_KEY!,
});

// pages/login.tsx
import { useState } from 'react';
import { useRouter } from 'next/router';
import { zkauth } from '@/lib/zkauth';

export default function LoginPage() {
const router = useRouter();
const [error, setError] = useState('');

const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
const formData = new FormData(e.currentTarget);

try {
await zkauth.login({
email: formData.get('email') as string,
password: formData.get('password') as string,
});
router.push('/dashboard');
} catch (err) {
setError(err.message);
}
};

return (


`typescript
import { ZKAuthError, ZKAuthErrorCode } from '@zkauth/sdk';

try {
await zkauth.login({ email, password });
} catch (error) {
if (error instanceof ZKAuthError) {
switch (error.code) {
case ZKAuthErrorCode.AUTHENTICATION_ERROR:
console.error('Invalid credentials');
break;
case ZKAuthErrorCode.NETWORK_ERROR:
console.error('Network error, please try again');
break;
case ZKAuthErrorCode.MFA_REQUIRED:
console.error('MFA verification required');
break;
default:
console.error('An error occurred:', error.message);
}
}
}
`

📖 TypeScript Support

The SDK is written in TypeScript and includes full type definitions.

`typescript
import type {
User,
Session,
RegisterParams,
LoginParams,
Device,
} from '@zkauth/sdk';
``

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

- Website
- Documentation
- Developer Platform
- GitHub
- Support

💬 Support

- Email: support@zkauth.com
- Discord: Join our community
- GitHub Issues: Report a bug