@zkpassport/sdk 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# zkpassport-sdk
+
+## Installation
+
+```
+npm install https://github.com/zkpassport/zkpassport-sdk.git
+```
+
+## How to use
+
+```ts
+import { ZkPassport } from 'zkpassport-sdk'
+
+// Replace with your domain
+const zkPassport = new ZkPassport('demo.zkpassport.id')
+
+// Specify your app name, logo and the purpose of the request
+// you'll send to your visitors or users
+const queryBuilder = await zkPassport.request({
+  name: 'ZKpassport',
+  logo: 'https://zkpassport.id/logo.png',
+  purpose: 'Proof of country and first name',
+})
+
+// Specify the data you want to disclose
+// Then you can call the `done` method to get the url and the callbacks to follow the progress
+// and get back the result along with the proof
+const { url, requestId, onQRCodeScanned, onGeneratingProof, onProofGenerated, onReject, onError } = queryBuilder
+  .disclose('nationality')
+  .disclose('firstname')
+  .done()
+
+// Generate a url with the url and let your user scan it
+// or transform it into a button if the user is on mobile
+
+onQRCodeScanned(() => {
+  // The user scanned the QR code or clicked the button
+  // Essentially, this means the request popup is now opened
+  // on the user phone
+  console.log('QR code scanned')
+})
+
+onGeneratingProof(() => {
+  // The user accepted the request and the proof is being generated
+  console.log('Generating proof')
+})
+
+onProofGenerated((result: ProofResult) => {
+  // The proof has been generated
+  // You can retrieve the proof, the verification key and the result of your query
+  // Note: the verify function will soon be added to the SDK so you can verify the proof
+  // directly
+  console.log('Proof', result.proof)
+  console.log('Verification key', result.verificationKey)
+  console.log('Query result', result.queryResult)
+  console.log('firstname', result.queryResult.firstname.disclose.result)
+  console.log('nationality', result.queryResult.nationality.disclose.result)
+})
+```
+### Using with Next.js
+
+You can integrate `zkpassport-sdk` into a Next.js application by creating a backend API route and calling it from your frontend.
+
+#### **Backend (API Route)**
+
+**App Router:** `app/api/zkpassport/route.ts`
+```typescript
+import { NextResponse } from 'next/server';
+import { ZkPassport } from 'zkpassport-sdk';
+
+export async function GET() {
+  const zkPassport = new ZkPassport('demo.zkpassport.id'); // Replace with your domain
+  const queryBuilder = await zkPassport.request({
+    name: 'ZKpassport Demo',
+    logo: 'https://via.placeholder.com/150',
+    purpose: 'Verify user nationality and first name',
+  });
+  const { url } = queryBuilder.disclose('nationality').disclose('firstname').done();
+  return NextResponse.json({ url });
+}
+```
+
+#### **Frontend Example**
+
+**App Router:** `app/page.tsx`
+```tsx
+'use client';
+import { useEffect, useState } from 'react';
+
+export default function Home() {
+  const [verificationUrl, setVerificationUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetch('/api/zkpassport')
+      .then(res => res.json())
+      .then(data => setVerificationUrl(data.url))
+      .catch(console.error);
+  }, []);
+
+  return (
+    <div>
+      <h1>ZKPassport Demo</h1>
+      {verificationUrl ? (
+        <a href={verificationUrl} target="_blank" rel="noopener noreferrer">
+          <button>Verify Identity</button>
+        </a>
+      ) : (
+        <p>Loading...</p>
+      )}
+    </div>
+  );
+}
+
+```
+
+## Local installation
+
+### Clone the repository
+
+```sh
+git clone https://github.com/zkpassport/zkpassport-sdk.git
+cd zkpassport-sdk
+```
+
+### Install dependencies
+
+```sh
+bun install
+```
+
+### Run Tests
+
+```sh
+bun test
+```
+
+### Simulate Websocket Messages
+
+Simulate mobile websocket messages: `bun run scripts/simulate.ts mobile`
+
+Simulate frontend websocket messages: `bun run scripts/simulate.ts frontend`

package/dist/constants/index.d.ts

@@ -0,0 +1,13 @@
+import { CountryName } from '@/types/countries';
+/**
+ * List of countries that are sanctioned by the US government.
+ */
+export declare const SANCTIONED_COUNTRIES: CountryName[];
+export declare const EU_COUNTRIES: CountryName[];
+declare const constants: {
+    countries: {
+        EU: CountryName[];
+        SANCTIONED: CountryName[];
+    };
+};
+export default constants;

package/dist/constants/index.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EU_COUNTRIES = exports.SANCTIONED_COUNTRIES = void 0;
+/**
+ * List of countries that are sanctioned by the US government.
+ */
+exports.SANCTIONED_COUNTRIES = [
+    'North Korea',
+    'Iran',
+    'Iraq',
+    'Libya',
+    'Somalia',
+    'Sudan',
+    'Syrian Arab Republic',
+    'Yemen',
+];
+exports.EU_COUNTRIES = [
+    'Austria',
+    'Belgium',
+    'Bulgaria',
+    'Croatia',
+    'Cyprus',
+    'Czech Republic',
+    'Denmark',
+    'Estonia',
+    'Finland',
+    'France',
+    'Germany',
+    'Greece',
+    'Hungary',
+    'Ireland',
+    'Italy',
+    'Latvia',
+    'Lithuania',
+    'Luxembourg',
+    'Malta',
+    'Netherlands',
+    'Poland',
+    'Portugal',
+    'Romania',
+    'Slovakia',
+    'Slovenia',
+    'Spain',
+    'Sweden',
+];
+var constants = {
+    countries: {
+        EU: exports.EU_COUNTRIES,
+        SANCTIONED: exports.SANCTIONED_COUNTRIES,
+    },
+};
+exports.default = constants;

package/dist/encryption.d.ts

@@ -0,0 +1,7 @@
+export declare function generateECDHKeyPair(): Promise<{
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}>;
+export declare function getSharedSecret(privateKey: string, publicKey: string): Promise<Uint8Array>;
+export declare function encrypt(message: string, sharedSecret: Uint8Array, topic: string): Promise<Uint8Array>;
+export declare function decrypt(ciphertext: Uint8Array, sharedSecret: Uint8Array, topic: string): Promise<string>;

package/dist/encryption.js

@@ -0,0 +1,126 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateECDHKeyPair = generateECDHKeyPair;
+exports.getSharedSecret = getSharedSecret;
+exports.encrypt = encrypt;
+exports.decrypt = decrypt;
+var aes_1 = require("@noble/ciphers/aes");
+var utils_1 = require("@noble/ciphers/utils");
+function sha256Truncate(topic) {
+    return __awaiter(this, void 0, void 0, function () {
+        var encoder, data, hashBuffer, fullHashArray, truncatedHashArray;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    encoder = new TextEncoder();
+                    data = encoder.encode(topic);
+                    return [4 /*yield*/, crypto.subtle.digest('SHA-256', data)];
+                case 1:
+                    hashBuffer = _a.sent();
+                    fullHashArray = new Uint8Array(hashBuffer);
+                    truncatedHashArray = fullHashArray.slice(0, 12);
+                    return [2 /*return*/, truncatedHashArray];
+            }
+        });
+    });
+}
+function generateECDHKeyPair() {
+    return __awaiter(this, void 0, void 0, function () {
+        var secp256k1, privKey, pubKey;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, import('@noble/secp256k1')];
+                case 1:
+                    secp256k1 = _a.sent();
+                    privKey = secp256k1.utils.randomPrivateKey();
+                    pubKey = secp256k1.getPublicKey(privKey);
+                    return [2 /*return*/, {
+                            privateKey: privKey,
+                            publicKey: pubKey,
+                        }];
+            }
+        });
+    });
+}
+function getSharedSecret(privateKey, publicKey) {
+    return __awaiter(this, void 0, void 0, function () {
+        var secp256k1, sharedSecret;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, import('@noble/secp256k1')];
+                case 1:
+                    secp256k1 = _a.sent();
+                    sharedSecret = secp256k1.getSharedSecret(privateKey, publicKey);
+                    return [2 /*return*/, sharedSecret.slice(0, 32)];
+            }
+        });
+    });
+}
+function encrypt(message, sharedSecret, topic) {
+    return __awaiter(this, void 0, void 0, function () {
+        var nonce, aes, data, ciphertext;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, sha256Truncate(topic)];
+                case 1:
+                    nonce = _a.sent();
+                    aes = (0, aes_1.gcm)(sharedSecret, nonce);
+                    data = (0, utils_1.utf8ToBytes)(message);
+                    ciphertext = aes.encrypt(data);
+                    return [2 /*return*/, ciphertext];
+            }
+        });
+    });
+}
+function decrypt(ciphertext, sharedSecret, topic) {
+    return __awaiter(this, void 0, void 0, function () {
+        var nonce, aes, data, dataString;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0: return [4 /*yield*/, sha256Truncate(topic)];
+                case 1:
+                    nonce = _a.sent();
+                    aes = (0, aes_1.gcm)(sharedSecret, nonce);
+                    data = aes.decrypt(ciphertext);
+                    dataString = new TextDecoder().decode(data);
+                    return [2 /*return*/, dataString];
+            }
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { DisclosableIDCredential, IDCredential, IDCredentialValue, NumericalIDCredential } from '@/types/credentials';
+import { ProofResult } from '@/types/query-result';
+export * from '@/constants';
+export * from '@/types';
+export declare class ZkPassport {
+    private domain;
+    private topicToConfig;
+    private topicToKeyPair;
+    private topicToWebSocketClient;
+    private topicToSharedSecret;
+    private topicToQRCodeScanned;
+    private onQRCodeScannedCallbacks;
+    private onGeneratingProofCallbacks;
+    private onBridgeConnectCallbacks;
+    private onProofGeneratedCallbacks;
+    private onRejectCallbacks;
+    private onErrorCallbacks;
+    private topicToService;
+    constructor(_domain?: string);
+    /**
+     * @notice Handle an encrypted message.
+     * @param request The request.
+     * @param outerRequest The outer request.
+     */
+    private handleEncryptedMessage;
+    private getZkPassportRequest;
+    /**
+     * @notice Create a new request.
+     * @returns The query builder object.
+     */
+    request({ name, logo, purpose, topicOverride, keyPairOverride, }: {
+        name: string;
+        logo: string;
+        purpose: string;
+        topicOverride?: string;
+        keyPairOverride?: {
+            privateKey: Uint8Array;
+            publicKey: Uint8Array;
+        };
+    }): Promise<{
+        eq: <T extends IDCredential>(key: T, value: IDCredentialValue<T>) => any;
+        gte: <T extends NumericalIDCredential>(key: T, value: IDCredentialValue<T>) => any;
+        gt: <T extends NumericalIDCredential>(key: T, value: IDCredentialValue<T>) => any;
+        lte: <T extends NumericalIDCredential>(key: T, value: IDCredentialValue<T>) => any;
+        lt: <T extends NumericalIDCredential>(key: T, value: IDCredentialValue<T>) => any;
+        range: <T extends NumericalIDCredential>(key: T, start: IDCredentialValue<T>, end: IDCredentialValue<T>) => any;
+        in: <T extends IDCredential>(key: T, value: IDCredentialValue<T>[]) => any;
+        out: <T extends IDCredential>(key: T, value: IDCredentialValue<T>[]) => any;
+        disclose: (key: DisclosableIDCredential) => any;
+        done: () => {
+            url: string;
+            requestId: string;
+            onQRCodeScanned: (callback: () => void) => number;
+            onGeneratingProof: (callback: () => void) => number;
+            onBridgeConnect: (callback: () => void) => number;
+            onProofGenerated: (callback: (result: ProofResult) => void) => number;
+            onReject: (callback: () => void) => number;
+            onError: (callback: (error: string) => void) => number;
+            isBridgeConnected: () => boolean;
+            isQRCodeScanned: () => boolean;
+        };
+    }>;
+    /**
+     * @notice Verifies a proof.
+     * @param proof The proof to verify.
+     * @returns True if the proof is valid, false otherwise.
+     */
+    /**
+     * @notice Returns the URL of the request.
+     * @param requestId The request ID.
+     * @returns The URL of the request.
+     */
+    getUrl(requestId: string): string;
+    /**
+     * @notice Cancels a request by closing the WebSocket connection and deleting the associated data.
+     * @param requestId The request ID.
+     */
+    cancelRequest(requestId: string): void;
+}