@zauth/captcha-sdk

Zero-knowledge proof based CAPTCHA SDK for the modern web. Privacy-preserving, bot-resistant authentication without compromising user experience.

Runtime Defaults

This SDK keeps a browser-capable prover path by default and uses the backend URL only for challenge/verify transport. The backend URL is optional because the SDK already ships with a production default:

• https://zauth-captcha.onrender.com

The current browser prover stack in this package is pinned as:

• @noir-lang/noir_js: 1.0.0-beta.11
• @aztec/bb.js: 1.0.0

If you change any of these versions, revalidate the full proof flow against the backend before publishing.

Features

• Zero-Knowledge Proofs: Uses advanced ZK cryptography to verify humanity without exposing sensitive data
• Privacy-First: No tracking, no fingerprinting, no personal data collection
• Easy Integration: Simple API for vanilla JavaScript and React
• Bot-Resistant: Computational puzzles that are easy for humans, hard for bots
• TypeScript Support: Full TypeScript definitions included
• Lightweight: Minimal bundle size with tree-shaking support

Installation

npm install @zauth/captcha-sdk
# or
yarn add @zauth/captcha-sdk
# or
pnpm add @zauth/captcha-sdk

Quick Start

Vanilla JavaScript

import { ZkCaptcha } from '@zauth/captcha-sdk';

// Initialize the SDK
const captcha = new ZkCaptcha({
  siteId: 'your-site-id',
});

// Initialize (loads ZK circuits)
await captcha.initialize();

// Get a challenge
const challenge = await captcha.getChallenge();

// Generate proof
const proof = await captcha.generateProof(challenge);

// Verify
const result = await captcha.verify(challenge.challengeId, proof);

if (result.success) {
  console.log('CAPTCHA verified! Token:', result.token);
}

React Hook

import { useZkCaptcha } from '@zauth/captcha-sdk/react';

function CaptchaComponent() {
  const { 
    generateProof, 
    fetchChallenge, 
    status, 
    token, 
    error, 
    progress 
  } = useZkCaptcha({
    siteId: 'your-site-id',
    onSuccess: (token) => {
      console.log('Verification successful!', token);
    },
    onError: (err) => {
      console.error('Verification failed:', err);
    },
  });

  return (
    <div>
      <button 
        onClick={generateProof}
        disabled={status === 'processing'}
      >
        {status === 'processing' ? `Verifying (${progress}%)...` : 'Verify CAPTCHA'}
      </button>
      
      {status === 'success' && <p>✅ Verified!</p>}
      {status === 'error' && <p>❌ Error: {error?.message}</p>}
    </div>
  );
}

API Reference

ZkCaptcha Class

Constructor

new ZkCaptcha(config: ZkCaptchaConfig)

Config Options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | backendUrl | string | Optional | Backend server URL. Defaults to https://zauth-captcha.onrender.com | | siteId | string | ❌ | Unique identifier for your site | | timeout | number | ❌ | Request timeout in milliseconds (default: 30000) | | artifactUrl | string | ❌ | URL to load ZK circuit artifacts from |

Methods

initialize(): Promise<void>

Initializes the SDK and loads ZK circuits. Must be called before other operations.

getChallenge(siteId?: string): Promise<Challenge>

Fetches a new CAPTCHA challenge from the backend.

generateProof(challenge: Challenge, options?: GenerateProofOptions): Promise<Proof>

Generates a zero-knowledge proof for the given challenge.

Options:

• silent?: boolean - Suppress console output
• onProgress?: (progress: number) => void - Progress callback (0-100)

verify(challengeId: string, proof: Proof): Promise<VerificationResult>

Submits the proof to the backend for verification.

destroy(): Promise<void>

Cleans up resources. Call this when the SDK is no longer needed.

React Hook

useZkCaptcha(options: UseZkCaptchaOptions): UseZkCaptchaReturn

Options:

| Option | Type | Description | |--------|------|-------------| | backendUrl | string | Backend server URL. Defaults to the production Render backend | | siteId | string | Site identifier | | onSuccess | (token: string) => void | Callback on successful verification | | onError | (error: Error) => void | Callback on error | | autoChallenge | boolean | Automatically fetch challenge on mount |

Returns:

| Property | Type | Description | |----------|------|-------------| | generateProof | () => Promise<void> | Trigger proof generation | | fetchChallenge | () => Promise<void> | Fetch a new challenge | | status | CaptchaStatus | Current status: 'idle', 'loading', 'processing', 'success', 'error' | | token | string \| null | Verification token (on success) | | error | Error \| null | Error object (on failure) | | challenge | Challenge \| null | Current challenge data | | progress | number | Progress percentage (0-100) | | reset | () => void | Reset the state |

Configuration

Setting up your backend

The SDK requires a ZAuth-compatible backend. Your backend must implement:

1. POST /api/challenge - Returns a challenge

   {
     "challengeId": "uuid",
     "nonce": "hex-string",
     "difficulty": 4,
     "expiresAt": "2024-01-01T00:00:00Z"
   }

2. POST /api/verify - Verifies a proof

   {
     "challengeId": "uuid",
     "proof": { "proofData": "...", "publicInputs": [...] },
     "siteId": "your-site-id"
   }

Environment Variables

For React apps, set these environment variables only when you want to override the SDK default backend:

NEXT_PUBLIC_ZAUTH_BACKEND_URL=http://127.0.0.1:3000
NEXT_PUBLIC_ZAUTH_SITE_ID=your-site-id

Advanced Usage

Custom Progress Tracking

const proof = await captcha.generateProof(challenge, {
  onProgress: (progress) => {
    console.log(`Proof generation: ${progress}%`);
  },
});

Loading Artifacts from Custom URL

const captcha = new ZkCaptcha({
  artifactUrl: 'https://your-cdn.com/circuit-artifact.json',
});

Manual Artifact Loading

import { circuitArtifact } from './your-artifact';

const captcha = new ZkCaptcha();
captcha.setArtifactData(circuitArtifact);
await captcha.initialize();

Default Backend URL

If you do not pass backendUrl, the SDK uses the production Render backend.

import { DEFAULT_BACKEND_URL, ZkCaptcha } from '@zauth/captcha-sdk';

console.log(DEFAULT_BACKEND_URL); // https://zauth-captcha.onrender.com

const captcha = new ZkCaptcha();

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Requires crypto.getRandomValues API support.

TypeScript

Full TypeScript definitions are included. Import types as needed:

import type { 
  Challenge, 
  Proof, 
  VerificationResult, 
  ZkCaptchaConfig 
} from '@zauth/captcha-sdk';

License

MIT © ZAuth Team

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Support

• 📧 Email: [email protected]
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues

Made with 🔒 by Zauth Team