zkauth-client

JavaScript and TypeScript SDK for ZKAuth-H zero-knowledge authentication.

The current production engine is:

https://zkp-engine-main-1.vercel.app

The SDK sends the project API key with x-api-key and sends user session JWTs with Authorization: Bearer <token> for authenticated user routes.

Installation

npm install zkauth-client

Node.js installs also try to install the optional native @node-rs/argon2 package. When available, the SDK uses that native Argon2id path for password hashing; browser builds keep the portable JavaScript implementation.

Basic Usage

import { ZKAuthSDK } from 'zkauth-client';

const zkauth = new ZKAuthSDK({
  apiKey: process.env.ZKAUTH_API_KEY!,
  baseUrl: 'https://zkp-engine-main-1.vercel.app'
});

const registered = await zkauth.register({
  email: '[email protected]',
  password: 'SecurePassword123!',
  deviceInfo: {
    deviceName: 'Chrome on macOS',
    deviceType: 'desktop',
    browserName: 'Chrome',
    osName: 'macOS'
  }
});

if (registered.data.verificationToken) {
  await zkauth.verifyEmail(registered.data.verificationToken);
}

const loggedIn = await zkauth.login({
  email: '[email protected]',
  password: 'SecurePassword123!',
  deviceInfo: {
    deviceName: 'Chrome on macOS',
    deviceType: 'desktop',
    browserName: 'Chrome',
    osName: 'macOS'
  }
});

console.log(registered.data.userId);
console.log(loggedIn.data.session.token);

Current Backend Contract

Core routes used by this SDK:

GET  /api/v1/client/me
POST /api/v1/auth/register
GET  /api/v1/auth/salt/:email
POST /api/v1/auth/login
GET  /api/v1/auth/me
POST /api/v1/auth/logout
POST /api/v1/auth/refresh
GET  /api/v1/devices
POST /api/v1/devices/register
POST /api/v1/devices/verify
DELETE /api/v1/devices/:deviceId
GET  /api/v1/opaque/status
POST /api/v1/opaque/register/response
POST /api/v1/opaque/register/finish
POST /api/v1/opaque/login/start
POST /api/v1/opaque/login/finish
POST /api/v1/webauthn/register/options
POST /api/v1/webauthn/register/verify
POST /api/v1/webauthn/authenticate/options
POST /api/v1/webauthn/authenticate/verify

Authentication Flow

Registration:

1. The SDK fetches the tenant/client ID from /api/v1/client/me.
2. The SDK generates a 32-byte salt.
3. The SDK derives the password hash with Argon2id using the current backend parameters: memory 19456, time cost 2, parallelism 1, hash length 32.
4. The SDK computes the tenant-bound Poseidon commitment.
5. The SDK adds a deterministic device fingerprint when the application does not provide one.
6. The SDK sends only the email, salt, commitment, and device metadata to the backend.

Login:

1. The SDK fetches the tenant/client ID.
2. The SDK fetches the user's salt.
3. The SDK regenerates the password hash and commitment locally.
4. The SDK generates a Groth16 proof using the bundled auth circuit.
5. The SDK reuses the same deterministic device fingerprint for exact trusted-device matching.
6. The backend verifies the proof, timestamp, nonce, tenant binding, device trust, and replay registry before issuing a session JWT.

API

Constructor

new ZKAuthSDK({
  apiKey: 'zka_live_or_test_key',
  baseUrl?: 'https://zkp-engine-main-1.vercel.app',
  timeout?: 30000,
  debug?: false,
  clientId?: 'optional-client-uuid'
});

Core Methods

await zkauth.register(params);
await zkauth.login(params);
await zkauth.logout();
await zkauth.getCurrentUser();
zkauth.isAuthenticated();
zkauth.getSession();
await zkauth.verifyEmail(token);
await zkauth.getDevices();
await zkauth.healthCheck();

OPAQUE Helpers

These methods expose the current backend OPAQUE routes. The caller is responsible for creating the OPAQUE client messages with a compatible OPAQUE library.

await zkauth.opaqueStatus();
await zkauth.opaqueRegistrationResponse({ registrationRequest, email, userId });
await zkauth.opaqueRegistrationFinish({ email, userId, registrationRecord, serverStaticPublicKey });
await zkauth.opaqueLoginStart({ startLoginRequest, email, userId });
await zkauth.opaqueLoginFinish({ sessionId, finishLoginRequest });

WebAuthn Helpers

These methods expose the current backend WebAuthn routes. Browser applications still need to call navigator.credentials.create() and navigator.credentials.get() with the returned options.

await zkauth.webAuthnRegistrationOptions({ userId, email, displayName });
await zkauth.webAuthnRegistrationVerify({ userId, credential });
await zkauth.webAuthnAuthenticationOptions({ userId, email });
await zkauth.webAuthnAuthenticationVerify({ userId, email, credential });

Error Handling

import { ZKAuthError, ZKAuthErrorCode } from 'zkauth-client';

try {
  await zkauth.login({ email, password });
} catch (error) {
  if (error instanceof ZKAuthError) {
    if (error.code === ZKAuthErrorCode.UNAUTHORIZED) {
      // Invalid credentials or expired session.
    }
  }
}

Security Notes

• Passwords are not sent to the server.
• The proof is tenant-bound through the client hash in the circuit public inputs.
• The backend performs nonce, timestamp, replay, public-signal, and Groth16 verification.
• The backend fails closed for production Redis replay protection.
• This package does not claim post-quantum security, external audit status, NIST AAL certification, or universal hardware-passkey compatibility.

Development

npm install
npm run build
npm test

License

MIT