ETH.id JavaScript/TypeScript SDK

Zero-Knowledge Document Verification SDK for JavaScript and TypeScript.

Installation

npm install @ethid/sdk

Quick Start

import { EthIdClient, LLMProvider } from '@ethid/sdk';

// Initialize client
const client = new EthIdClient({
  provider: LLMProvider.OPENAI,
  apiKey: 'sk-your-key'
});

// Verify a document
const result = await client.verify(
  'passport.pdf',
  'over 18 years old'
);

console.log(`Answer: ${result.answer}`);
console.log(`Confidence: ${result.confidence}%`);

Features

• Zero-Knowledge Verification: Documents never leave your machine
• Privacy-First: Only minimal, claim-relevant data is processed
• TypeScript Support: Full type definitions included
• Multiple LLM Providers: OpenAI, Claude, Ollama
• Cryptographic Attestations: Tamper-evident proof bundles
• Audit Trail: Complete verification history

Usage

Basic Verification

import { EthIdClient } from '@ethid/sdk';

const client = new EthIdClient();

// Age verification
const result = await client.verify(
  'id.pdf',
  'maior de 18 anos'
);

if (result.answer) {
  console.log('Person is over 18');
}

With Attestation

// Generate cryptographic proof
const result = await client.verify(
  'id.pdf',
  'over 21 years old',
  { attest: true }
);

// Get attestation bundle
const bundle = await client.getAttestation(result.sessionId);

// Verify integrity
if (client.verifyAttestationIntegrity(bundle)) {
  console.log('Attestation is valid');
}

Offline Mode

// Complete privacy with local LLM
const client = new EthIdClient({
  provider: LLMProvider.OLLAMA,
  offline: true
});

const result = await client.verify(
  'document.pdf',
  'document is signed'
);

Audit Log

// List all verifications
const entries = await client.listAuditLog({ limit: 10 });

for (const entry of entries) {
  console.log(`${entry.timestamp}: ${entry.claim} -> ${entry.answer}`);
}

// Get specific entry
const entry = await client.getAuditEntry(sessionId);

API Reference

EthIdClient

class EthIdClient {
  constructor(config?: EthIdConfig);
  
  verify(
    documentPath: string,
    claim: string,
    options?: VerifyOptions
  ): Promise<VerificationResult>;
  
  getAttestation(sessionId: string): Promise<AttestationBundle>;
  
  verifyAttestationIntegrity(bundle: AttestationBundle): boolean;
  
  listAuditLog(options?: AuditLogOptions): Promise<AuditEntry[]>;
  
  getAuditEntry(sessionId: string): Promise<AuditEntry>;
  
  configure(provider?: LLMProvider, apiKey?: string): Promise<void>;
  
  getConfig(): Promise<any>;
}

Types

interface VerificationResult {
  sessionId: string;
  answer: boolean;
  confidence: number;
  reasoning: string;
  proofType: ProofType;
  claim: string;
  privacyMetadata: PrivacyMetadata;
  timestamp: Date;
}

interface AttestationBundle {
  sessionId: string;
  documentHash: string;
  claim: string;
  result: VerificationResult;
  proofType: ProofType;
  bundleHash: string;
  createdAt: Date;
}

interface AuditEntry {
  sessionId: string;
  documentHash: string;
  claim: string;
  answer: boolean;
  confidence: number;
  proofType: ProofType;
  timestamp: Date;
}

Examples

Age Verification

const result = await client.verify(
  'passport.pdf',
  'over 18 years old'
);

console.log(`Over 18: ${result.answer}`);

CPF Verification

const result = await client.verify(
  'brazilian_id.pdf',
  'CPF bate com 123.456.789-00'
);

// Only masked CPF is sent: 123.***.***-00

Income Verification

const result = await client.verify(
  'income_proof.pdf',
  'renda acima de 5000'
);

// Only amount field is sent, no name/CPF

Error Handling

import {
  DocumentParsingError,
  ClaimParsingError,
  VerificationError,
} from '@ethid/sdk';

try {
  const result = await client.verify(
    'document.pdf',
    'over 18 years old'
  );
} catch (error) {
  if (error instanceof DocumentParsingError) {
    console.error('Failed to parse document:', error.message);
  } else if (error instanceof ClaimParsingError) {
    console.error('Failed to parse claim:', error.message);
  } else if (error instanceof VerificationError) {
    console.error('Verification failed:', error.message);
  }
}

Requirements

• Node.js 16+
• ETH.id CLI installed (cargo install --path .)

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Lint
npm run lint

License

MIT

Links

• Documentation
• GitHub
• NPM