@zoza/auth

Device-keypair authentication. Replaces SMS OTP and TOTP with a one-tap approve on the user's already-registered device. No shared secrets. No SIM-swap risk. Per-challenge metadata shows users exactly what they're approving.

Install

npm install @zoza/auth

Why

	SMS OTP	TOTP (Google Authenticator)	Zoza Auth
Shared secret on the server	❌	❌	✅ none (device holds private key)
SIM-swap survivable	❌	✅	✅
Shows what is being approved	❌	❌	✅ per-challenge metadata
Phishing-resistant	❌	❌	✅ signature bound to nonce
SMS cost per login	₹0.10-0.25	₹0	~₹0

Quick start (server side)

import { AuthClient } from '@zoza/auth';

const auth = new AuthClient({ apiKey: process.env.ZOZA_AUTH_KEY! });

// 1. Register each user's device at enrolment
await auth.registerDevice({
  user_id:    'user_123',
  device_id:  'dev_iphone15_abc',
  device_name: 'Rahul — iPhone 15',
  public_key: deviceCurve25519HexFromEnrollmentFlow,
});

// 2. Issue a challenge whenever you need an auth
const challenge = await auth.issueChallenge({
  user_id:  'user_123',
  context:  'payment',
  metadata: 'Transfer ₹5000 to Rahul Sharma',
  ttl:      30,
});
// push challenge.id to the user's device via your existing push/WebSocket

// 3. Poll for the signed response (or use v0.2 webhooks when they land)
const result = await auth.getChallengeStatus(challenge.id);
// → { status: 'approved' | 'rejected' | 'expired' | 'pending', ... }

Quick start (device side)

// On the user's already-registered device:
import { AuthClient } from '@zoza/auth';

const auth = new AuthClient({ apiKey: 'unused-for-device-endpoints' });

// Fetch the challenge details (public endpoint — ID is the capability)
const details = await auth.getChallengeDetails(challengeId);
// Show user details.metadata; let them approve/reject.

// Sign and submit
await auth.respondChallenge(challengeId, {
  device_id:  'dev_iphone15_abc',
  client_pub: ephemeralPubHex,
  proof:      sigHex,
  approved:   true,
});

The proof is produced with the device's Curve25519 private key over (nonce || challenge.id || client_pub || approved). See the Auth whitepaper for the exact derivation.

API

new AuthClient({ apiKey, apiUrl?, fetch? })

Option	Type	Notes
apiKey	string (required)	Issued at zoza.world/developers/auth. Format auth_<base64>.
apiUrl	string	Default https://auth-api.zoza.world.
fetch	typeof fetch	Optional — Node <18 or custom signers.

Methods

Method	Auth	Purpose
registerDevice({...})	API key	Add a device public key under a user
issueChallenge({...})	API key	Mint a challenge for a user
getChallengeStatus(id)	API key	Poll challenge result
getChallengeDetails(id)	public	Device-side: fetch metadata to display
respondChallenge(id, {...})	public	Device-side: submit signed response
getAppAudit(appId)	API key	Tamper-evident app audit log

Tests

npm install
npm test

License

MIT © Zoza