@zkpassport/sdk 0.16.2 → 0.17.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,10 +2,6 @@
2
2
 
3
3
  Privacy-preserving identity verification using passports and ID cards.
4
4
 
5
- _⚠️ Warning ⚠️_
6
-
7
- _This is experimental software that has not been audited yet. Use at your own risk._
8
-
9
5
  ## Installation
10
6
 
11
7
  ```
@@ -14,6 +10,8 @@ npm install @zkpassport/sdk
14
10
 
15
11
  ## How to use
16
12
 
13
+ For a drop-in QR card or verify button that wraps all of this, see [`@zkpassport/ui`](https://www.npmjs.com/package/@zkpassport/ui).
14
+
17
15
  ```ts
18
16
  import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"
19
17
 
@@ -26,24 +24,21 @@ const queryBuilder = await zkPassport.request({
26
24
  name: "ZKPassport",
27
25
  logo: "https://zkpassport.id/logo.png",
28
26
  purpose: "Prove you are an adult from the EU but not from Scandinavia",
29
- // The scope is optional and can be used to scope the unique identifier
30
- // of the request to a specific use case
31
- // By default, the request's unique identifier is scoped to your domain name only
27
+ // Optional: ties the user's unique identifier to a use case;
28
+ // by default it is tied to your domain only
32
29
  scope: "eu-adult-not-scandinavia",
33
30
  })
34
31
 
35
- // Specify the data you want to disclose
36
- // Then you can call the `done` method to get the url and the callbacks to follow the progress
37
- // and get back the result along with the proof
38
- // The example below requests to disclose the firstname, prove the user is at least 18 years old,
39
- // prove the user is from the EU but not from a Scandinavian country (note that Norway is not in the EU)
32
+ // Build the query; done() returns the request URL and the progress callbacks.
33
+ // Here: disclose the first name, prove 18+, prove EU nationality but not Scandinavian
34
+ // (Norway is already excluded — it is not in the EU)
40
35
  const {
41
36
  url,
42
37
  requestId,
43
38
  onRequestReceived,
44
39
  onGeneratingProof,
45
40
  onProofGenerated,
46
- onResult,
41
+ onSuccess,
47
42
  onReject,
48
43
  onError,
49
44
  } = queryBuilder
@@ -57,9 +52,7 @@ const {
57
52
  // or transform it into a button if the user is on their phone
58
53
 
59
54
  onRequestReceived(() => {
60
- // The user scanned the QR code or clicked the link to the request
61
- // Essentially, this means the request popup is now opened
62
- // on the user phone
55
+ // The user scanned the QR code or opened the link; the request is now on their phone
63
56
  console.log("Request received")
64
57
  })
65
58
 
@@ -69,12 +62,10 @@ onGeneratingProof(() => {
69
62
  })
70
63
 
71
64
  // You probably don't need to use this callback
72
- // But if you want to get the proofs and verify them manually, it's here
73
- onProofGenerated(({ proof, vkeyHash, version, name }: ProofResult) => {
65
+ // It reports the progress as the proofs are generated one by one;
66
+ // the full set arrives in onSuccess
67
+ onProofGenerated(({ proof, vkeyHash, version, name }) => {
74
68
  // One of the proofs has been generated
75
- // Here, you can retrieve the proof manually and verify it
76
- // But note that the verification of the proofs is handled
77
- // automatically by the SDK
78
69
  console.log("Proof generated", proof)
79
70
  console.log("Verification key hash", vkeyHash)
80
71
  console.log("Version", version)
@@ -82,112 +73,105 @@ onProofGenerated(({ proof, vkeyHash, version, name }: ProofResult) => {
82
73
  })
83
74
 
84
75
  // That's the callback you're looking for
85
- onResult(
86
- ({
87
- uniqueIdentifier,
88
- verified,
89
- result,
90
- }: {
91
- uniqueIdentifier: string
92
- verified: boolean
93
- result: QueryResult
94
- }) => {
95
- // All the proofs have been generated and the final result is available
96
- console.log("firstname", result.firstname.disclose.result)
97
- console.log("age over 18", result.age.gte.result)
98
- console.log("nationality in EU", result.nationality.in.result)
99
- console.log("nationality not from Scandinavia", result.nationality.out.result)
100
- // You can also retrieved what were the values originally requested
101
- console.log("age over", result.age.gte.expected)
102
- console.log("nationality in", result.nationality.in.expected)
103
- console.log("nationality not in", result.nationality.out.expected)
104
- // You can make sure the proof are valid by checking verified is set to true
105
- console.log("proofs are valid", verified)
106
- // You can also retrieve the unique identifier associated to this request
107
- // The assumption is that the unique identifier will be the same if coming
108
- // from the same ID for the same domain name and scope
109
- // So you can use it to identify if the user has already provided the proof
110
- // for this specific use case
111
- console.log("unique identifier", uniqueIdentifier)
112
- },
113
- )
76
+ onSuccess(({ proofs, result }) => {
77
+ // All the proofs have been generated and the result is available
78
+ console.log("firstname", result.firstname.disclose.result)
79
+ console.log("age over 18", result.age.gte.result)
80
+ console.log("nationality in EU", result.nationality.in.result)
81
+ console.log("nationality not from Scandinavia", result.nationality.out.result)
82
+ // You can also retrieve what were the values originally requested
83
+ console.log("age over", result.age.gte.expected)
84
+ console.log("nationality in", result.nationality.in.expected)
85
+ console.log("nationality not in", result.nationality.out.expected)
86
+ // The proofs are NOT verified at this point. A result checked in the browser
87
+ // can be tampered with, so send the proofs and the result to your backend
88
+ // and verify them there (see "Verifying the proofs" below)
89
+ fetch("/api/register", { method: "POST", body: JSON.stringify({ proofs, result }) })
90
+ })
114
91
  ```
115
92
 
93
+ The deprecated `onResult` callback still verifies the proofs for you and returns a `verified` flag along with the `uniqueIdentifier`, but a flag delivered to the browser cannot be trusted. Use `onSuccess` and verify on your backend instead.
94
+
95
+ ### Verifying the proofs
96
+
97
+ On your backend, recreate the original query so a tampered request cannot pass, then verify the proofs you received:
98
+
99
+ ```ts
100
+ import { ZKPassport, EU_COUNTRIES } from "@zkpassport/sdk"
101
+
102
+ const zkPassport = new ZKPassport("demo.zkpassport.id")
103
+
104
+ const { query } = zkPassport
105
+ .createQuery()
106
+ .disclose("firstname")
107
+ .gte("age", 18)
108
+ .in("nationality", EU_COUNTRIES)
109
+ .out("nationality", ["Sweden", "Denmark"])
110
+ .done()
111
+
112
+ const { verified, uniqueIdentifier } = await zkPassport.verify({
113
+ proofs,
114
+ originalQuery: query,
115
+ queryResult: result,
116
+ scope: "eu-adult-not-scandinavia",
117
+ })
118
+ if (!verified) return { registered: false }
119
+
120
+ // The unique identifier stays the same for the same ID, domain and scope,
121
+ // so it can act as the account key: store it in your DB with a uniqueness
122
+ // constraint, and a duplicate means this person already has an account
123
+ await db.users.insert({ zkpassportId: uniqueIdentifier })
124
+ return { registered: true }
125
+ ```
126
+
127
+ `verify()` checks the proofs locally and defers to the ZKPassport verifier API when the local result is not verified. Set `verifierMode` to `"local"` or `"api"` to force one.
128
+
116
129
  ### Using with Next.js
117
130
 
118
- You can integrate `@zkpassport/sdk` into a Next.js application by creating a backend API route and calling it from your frontend.
131
+ Request the proofs in the browser (with the "How to use" example above, or the drop-in card/button from `@zkpassport/ui`), then send them from `onSuccess` to an API route that verifies them:
119
132
 
120
- #### **Backend (API Route)**
133
+ ```ts
134
+ onSuccess(async ({ proofs, result }) => {
135
+ await fetch("/api/register", { method: "POST", body: JSON.stringify({ proofs, result }) })
136
+ })
137
+ ```
121
138
 
122
- **App Router:** `app/api/zkpassport/route.ts`
139
+ **App Router:** `app/api/register/route.ts`
123
140
 
124
141
  ```typescript
125
142
  import { NextResponse } from "next/server"
126
143
  import { ZKPassport } from "@zkpassport/sdk"
127
144
 
128
- export async function GET() {
129
- const zkPassport = new ZKPassport("demo.zkpassport.id") // Replace with your domain
130
- const queryBuilder = await zkPassport.request({
131
- name: "ZKPassport Demo",
132
- logo: "https://via.placeholder.com/150",
133
- purpose: "Verify user nationality and first name",
134
- })
135
- const { url } = queryBuilder.disclose("nationality").disclose("firstname").done()
136
- return NextResponse.json({ url })
137
- }
138
- ```
145
+ const zkPassport = new ZKPassport("demo.zkpassport.id") // Replace with your domain
139
146
 
140
- #### **Frontend Example**
141
-
142
- **App Router:** `app/page.tsx`
143
-
144
- ```tsx
145
- "use client"
146
- import { useEffect, useState } from "react"
147
-
148
- export default function Home() {
149
- const [verificationUrl, setVerificationUrl] = useState<string | null>(null)
150
-
151
- useEffect(() => {
152
- fetch("/api/zkpassport")
153
- .then((res) => res.json())
154
- .then((data) => setVerificationUrl(data.url))
155
- .catch(console.error)
156
- }, [])
157
-
158
- return (
159
- <div>
160
- <h1>ZKPassport Demo</h1>
161
- {verificationUrl ? (
162
- <a href={verificationUrl} target="_blank" rel="noopener noreferrer">
163
- <button>Verify Identity</button>
164
- </a>
165
- ) : (
166
- <p>Loading...</p>
167
- )}
168
- </div>
169
- )
170
- }
171
- ```
147
+ export async function POST(request: Request) {
148
+ const { proofs, result } = await request.json()
172
149
 
173
- ## Local installation
150
+ // Recreate the original query so a tampered request cannot pass
151
+ const { query } = zkPassport.createQuery().gte("age", 18).done()
174
152
 
175
- ### Clone the repository
153
+ const { verified, uniqueIdentifier } = await zkPassport.verify({
154
+ proofs,
155
+ originalQuery: query,
156
+ queryResult: result,
157
+ scope: "age-check",
158
+ })
159
+ if (!verified) return NextResponse.json({ registered: false })
176
160
 
177
- ```sh
178
- git clone https://github.com/zkpassport/zkpassport-sdk.git
179
- cd zkpassport-sdk
161
+ // Store uniqueIdentifier in your DB as the user's key
162
+ return NextResponse.json({ registered: true })
163
+ }
180
164
  ```
181
165
 
182
- ### Install dependencies
183
-
184
- ```sh
185
- bun install
186
- ```
166
+ ## Working on the SDK
187
167
 
188
- ### Run Tests
168
+ The SDK lives in the [zkpassport-packages](https://github.com/zkpassport/zkpassport-packages) monorepo:
189
169
 
190
170
  ```sh
171
+ git clone https://github.com/zkpassport/zkpassport-packages.git
172
+ cd zkpassport-packages
173
+ bun install
174
+ cd packages/zkpassport-sdk
191
175
  bun test
192
176
  ```
193
177
 
@@ -196,3 +180,8 @@ bun test
196
180
  Simulate mobile websocket messages: `bun run scripts/simulate.ts mobile`
197
181
 
198
182
  Simulate frontend websocket messages: `bun run scripts/simulate.ts frontend`
183
+
184
+
185
+ ### Security
186
+
187
+ ZKPassport has undergone multiple internal audits, but it has not yet had an external audit.