Skip to content

README.md

Latest commit

 

History

History
146 lines (103 loc) · 6.45 KB

README.md

File metadata and controls

146 lines (103 loc) · 6.45 KB

zk-id

CI License Version TypeScript OpenID4VP Docs

Privacy-preserving identity verification using zero-knowledge proofs.

zk-id lets users prove claims (for example, "age >= 18" or "nationality is in the EU") without revealing raw identity data (for example, exact birth date, name, or ID number). It includes SDKs for issuers/verifiers, OpenID4VP support, nationality/residency set-membership proofs, and runnable demos.

Quick Start

Prerequisites

  • Node.js 20 (repo .nvmrc)
  • npm

Install and prepare circuits

npm install
npm run compile:circuits
npm run --workspace=@zk-id/circuits setup

Run the main web demo

npm start --workspace=@zk-id/example-web-app

Open http://localhost:5050.

Optional: run the interactive portal

npm run portal:dev

Open http://localhost:4321.

For an end-to-end walkthrough, see GETTING-STARTED.md.

What You Can Run

Examples

Example What it shows Run Default URL Docs
examples/web-app Full issuance + verification flow (age, nationality, scenarios, revocation) npm start --workspace=@zk-id/example-web-app http://localhost:5050 examples/web-app/README.md
examples/openid4vp-demo QR-based OpenID4VP verifier + wallet flow npm start --workspace=zk-id-openid4vp-demo http://localhost:5173 examples/openid4vp-demo/README.md
examples/age-gate-widget Embeddable age-gate widget integration npm run dev --workspace=zk-id-age-gate-widget http://localhost:5174 (or next Vite port) examples/age-gate-widget/README.md

Workspace-level examples index: examples/README.md

Mobile Clarification

There are two mobile code paths in this repo:

  • @zk-id/mobile (packages/mobile): TypeScript SDK for React Native/Expo/Node-style environments.
  • @zk-id/wallet-app (packages/wallet-app): native iOS SwiftUI wallet app (workspace app/reference implementation, private package).

They are related but different. The iOS app is not the same package as the TypeScript mobile SDK.

Package Overview

zk-id is a monorepo with 11 package workspaces:

Workspace Purpose
@zk-id/core Core credential, proof, verification, revocation, and BBS+ primitives
@zk-id/circuits Circom circuits and proving artifacts
@zk-id/sdk Web client/server SDK and OpenID4VP components
@zk-id/issuer Credential issuance and key-management helpers
@zk-id/issuer-server Reference Express issuer service
@zk-id/redis Redis-backed stores for production deployments
@zk-id/contracts Solidity verifier contracts for EVM chains
@zk-id/mobile Mobile TypeScript SDK (React Native/Expo)
@zk-id/portal Developer portal and playground app
@zk-id/wallet-app Native iOS wallet app (SwiftUI, private workspace app)
@zk-id/wallet-app-rn React Native / Expo wallet app

Minimal SDK Usage

import { ZkIdClient } from '@zk-id/sdk';

const client = new ZkIdClient({
  verificationEndpoint: '/api/verify-age',
});

const verified = await client.verifyAge(18);
if (verified) {
  // grant access
}
import { ZkIdServer } from '@zk-id/sdk';

const server = new ZkIdServer({
  verificationKeyPath: './verification_key.json',
});

app.post('/api/verify-age', async (req, res) => {
  const result = await server.verifyProof(req.body, req.ip);
  res.json({ verified: result.verified });
});

See package docs for complete APIs:

Security and Operational Notes

Additional Docs

Contributing

License

Apache-2.0. See LICENSE and NOTICE.