zklicensing 0.1.0-beta.2 → 0.1.0-beta.4

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.
Files changed (173) hide show
  1. package/README.md +335 -97
  2. package/build/appsLookup.d.ts +14 -0
  3. package/build/appsLookup.d.ts.map +1 -0
  4. package/build/appsLookup.js +12 -0
  5. package/build/appsLookup.js.map +1 -0
  6. package/build/archiveBootstrap.d.ts +15 -1
  7. package/build/archiveBootstrap.d.ts.map +1 -0
  8. package/build/archiveBootstrap.js +62 -9
  9. package/build/archiveBootstrap.js.map +1 -0
  10. package/build/bindClient.d.ts +51 -0
  11. package/build/bindClient.d.ts.map +1 -0
  12. package/build/bindClient.js +115 -0
  13. package/build/bindClient.js.map +1 -0
  14. package/build/buyClient.d.ts +10 -3
  15. package/build/buyClient.d.ts.map +1 -0
  16. package/build/buyClient.js +33 -15
  17. package/build/buyClient.js.map +1 -0
  18. package/build/contractInterface.d.ts +11 -5
  19. package/build/contractInterface.d.ts.map +1 -0
  20. package/build/contractInterface.js +82 -17
  21. package/build/contractInterface.js.map +1 -0
  22. package/build/countryStats.d.ts +6 -1
  23. package/build/countryStats.d.ts.map +1 -0
  24. package/build/countryStats.js +33 -9
  25. package/build/countryStats.js.map +1 -0
  26. package/build/deployClient.d.ts.map +1 -0
  27. package/build/deployClient.js +1 -1
  28. package/build/deployClient.js.map +1 -0
  29. package/build/deviceIdentity.d.ts +68 -0
  30. package/build/deviceIdentity.d.ts.map +1 -0
  31. package/build/deviceIdentity.js +209 -0
  32. package/build/deviceIdentity.js.map +1 -0
  33. package/build/freezeClient.d.ts.map +1 -0
  34. package/build/freezeClient.js +1 -1
  35. package/build/freezeClient.js.map +1 -0
  36. package/build/generationClient.d.ts +1 -0
  37. package/build/generationClient.d.ts.map +1 -0
  38. package/build/generationClient.js +2 -2
  39. package/build/generationClient.js.map +1 -0
  40. package/build/index.d.ts +27 -37
  41. package/build/index.d.ts.map +1 -0
  42. package/build/index.js +85 -116
  43. package/build/index.js.map +1 -0
  44. package/build/licenseLeaf.d.ts +76 -0
  45. package/build/licenseLeaf.d.ts.map +1 -0
  46. package/build/licenseLeaf.js +189 -0
  47. package/build/licenseLeaf.js.map +1 -0
  48. package/build/licenseRecord.d.ts +20 -1
  49. package/build/licenseRecord.d.ts.map +1 -0
  50. package/build/licenseRecord.js +1 -1
  51. package/build/licenseRecord.js.map +1 -0
  52. package/build/licenseStore.d.ts +17 -2
  53. package/build/licenseStore.d.ts.map +1 -0
  54. package/build/licenseStore.js +167 -7
  55. package/build/licenseStore.js.map +1 -0
  56. package/build/manifestVerify.d.ts.map +1 -0
  57. package/build/manifestVerify.js +8 -3
  58. package/build/manifestVerify.js.map +1 -0
  59. package/build/migrateClient.d.ts +6 -21
  60. package/build/migrateClient.d.ts.map +1 -0
  61. package/build/migrateClient.js +30 -17
  62. package/build/migrateClient.js.map +1 -0
  63. package/build/onChainRoot.d.ts +67 -0
  64. package/build/onChainRoot.d.ts.map +1 -0
  65. package/build/onChainRoot.js +87 -0
  66. package/build/onChainRoot.js.map +1 -0
  67. package/build/ownershipLicenseHash.d.ts +25 -0
  68. package/build/ownershipLicenseHash.d.ts.map +1 -0
  69. package/build/ownershipLicenseHash.js +29 -0
  70. package/build/ownershipLicenseHash.js.map +1 -0
  71. package/build/ownershipSignature.d.ts +122 -0
  72. package/build/ownershipSignature.d.ts.map +1 -0
  73. package/build/ownershipSignature.js +244 -0
  74. package/build/ownershipSignature.js.map +1 -0
  75. package/build/proveErrors.d.ts +35 -0
  76. package/build/proveErrors.d.ts.map +1 -0
  77. package/build/proveErrors.js +49 -0
  78. package/build/proveErrors.js.map +1 -0
  79. package/build/refundClient.d.ts +2 -11
  80. package/build/refundClient.d.ts.map +1 -0
  81. package/build/refundClient.js +35 -17
  82. package/build/refundClient.js.map +1 -0
  83. package/build/renewClient.d.ts +4 -1
  84. package/build/renewClient.d.ts.map +1 -0
  85. package/build/renewClient.js +11 -4
  86. package/build/renewClient.js.map +1 -0
  87. package/build/seatName.d.ts +8 -0
  88. package/build/seatName.d.ts.map +1 -0
  89. package/build/seatName.js +136 -0
  90. package/build/seatName.js.map +1 -0
  91. package/build/statsClient.d.ts +47 -4
  92. package/build/statsClient.d.ts.map +1 -0
  93. package/build/statsClient.js +44 -5
  94. package/build/statsClient.js.map +1 -0
  95. package/build/trustAnchorVerify.d.ts +48 -0
  96. package/build/trustAnchorVerify.d.ts.map +1 -0
  97. package/build/trustAnchorVerify.js +431 -0
  98. package/build/trustAnchorVerify.js.map +1 -0
  99. package/build/trustAnchorVerifyCli.d.ts +35 -0
  100. package/build/trustAnchorVerifyCli.d.ts.map +1 -0
  101. package/build/trustAnchorVerifyCli.js +177 -0
  102. package/build/trustAnchorVerifyCli.js.map +1 -0
  103. package/build/txBroadcastClient.d.ts +26 -0
  104. package/build/txBroadcastClient.d.ts.map +1 -0
  105. package/build/txBroadcastClient.js +20 -0
  106. package/build/txBroadcastClient.js.map +1 -0
  107. package/build/unbindClient.d.ts +56 -0
  108. package/build/unbindClient.d.ts.map +1 -0
  109. package/build/unbindClient.js +113 -0
  110. package/build/unbindClient.js.map +1 -0
  111. package/build/vendorAccountClient.d.ts +56 -0
  112. package/build/vendorAccountClient.d.ts.map +1 -0
  113. package/build/vendorAccountClient.js +47 -0
  114. package/build/vendorAccountClient.js.map +1 -0
  115. package/build/verifyCore.d.ts +1 -1
  116. package/build/verifyCore.d.ts.map +1 -0
  117. package/build/verifyCore.js +11 -4
  118. package/build/verifyCore.js.map +1 -0
  119. package/build/verifyOffline.d.ts +85 -0
  120. package/build/verifyOffline.d.ts.map +1 -0
  121. package/build/verifyOffline.js +139 -0
  122. package/build/verifyOffline.js.map +1 -0
  123. package/build/verifyService.d.ts.map +1 -0
  124. package/build/verifyService.js +582 -455
  125. package/build/verifyService.js.map +1 -0
  126. package/build/verifyWithAncestors.d.ts +18 -0
  127. package/build/verifyWithAncestors.d.ts.map +1 -0
  128. package/build/verifyWithAncestors.js +119 -0
  129. package/build/verifyWithAncestors.js.map +1 -0
  130. package/build/zipToState.d.ts +2 -0
  131. package/build/zipToState.d.ts.map +1 -0
  132. package/build/zipToState.js +94 -0
  133. package/build/zipToState.js.map +1 -0
  134. package/package.json +57 -13
  135. package/src/appsLookup.ts +48 -0
  136. package/src/archiveBootstrap.ts +342 -0
  137. package/src/bindClient.ts +175 -0
  138. package/src/buyClient.ts +304 -0
  139. package/src/contractInterface.d.ts +61 -0
  140. package/src/contractInterface.ts +313 -0
  141. package/src/countryStats.ts +171 -0
  142. package/src/deployClient.ts +388 -0
  143. package/src/deviceIdentity.ts +249 -0
  144. package/src/freezeClient.ts +117 -0
  145. package/src/generationClient.ts +165 -0
  146. package/src/index.ts +329 -0
  147. package/src/licenseLeaf.ts +221 -0
  148. package/src/licenseRecord.ts +108 -0
  149. package/src/licenseStore.ts +538 -0
  150. package/src/manifestVerify.ts +111 -0
  151. package/src/migrateClient.ts +84 -0
  152. package/src/onChainRoot.ts +107 -0
  153. package/src/ownershipLicenseHash.ts +31 -0
  154. package/src/ownershipSignature.ts +354 -0
  155. package/src/proveErrors.ts +70 -0
  156. package/src/refundClient.ts +158 -0
  157. package/src/renewClient.ts +214 -0
  158. package/src/seatName.ts +165 -0
  159. package/src/statsClient.ts +235 -0
  160. package/src/trustAnchorVerify.ts +548 -0
  161. package/src/trustAnchorVerifyCli.ts +179 -0
  162. package/src/txBroadcastClient.ts +48 -0
  163. package/src/unbindClient.ts +149 -0
  164. package/src/vendorAccountClient.ts +110 -0
  165. package/src/verifyCore.ts +92 -0
  166. package/src/verifyOffline.ts +212 -0
  167. package/src/verifyService.ts +969 -0
  168. package/src/verifyWithAncestors.ts +153 -0
  169. package/src/zipToState.ts +94 -0
  170. package/build/licenseProof.d.ts +0 -26
  171. package/build/licenseProof.js +0 -41
  172. package/build/ownership.d.ts +0 -34
  173. package/build/ownership.js +0 -147
@@ -0,0 +1,212 @@
1
+ // Copyright (c) 2025-2026 zkLicensing project developers
2
+ // SPDX-License-Identifier: BUSL-1.1
3
+
4
+ /**
5
+ * verifyOffline.ts
6
+ *
7
+ * Non-custodial device-binding offline verifier. Given:
8
+ * - a serialized MerkleMapWitness for the license entry
9
+ * - a `licensesRoot` value the caller has anchored to (see "Trust anchoring")
10
+ * - the full LicenseLeaf field set (licenseHash, expirySlot, deviceCap,
11
+ * deviceSlots[]) as of that sync — the leaf carries no separate
12
+ * owner-pubkey commitment because `licenseHash` IS it (buy circuit
13
+ * asserts equality)
14
+ * - the caller's device public key
15
+ *
16
+ * this module:
17
+ * 1. Reconstructs the LicenseLeaf hash from its fields.
18
+ * 2. Rebuilds the on-chain root through the witness and asserts it matches
19
+ * the passed `licensesRoot` — proves the leaf field set is authentic
20
+ * relative to that root.
21
+ * 3. If `deviceCap > 0`: computes the device commitment for the caller's
22
+ * pubkey and asserts it appears in `occupied[]`.
23
+ * 4. Asserts `expirySlot > currentSlot` (grace-period handling stays in
24
+ * the online verifier; the device-bound offline path is pass/fail).
25
+ * 5. If `deviceCap === 0`: skips the device check entirely — the app has
26
+ * binding disabled at the vendor level.
27
+ *
28
+ * Trust anchoring — where does `licensesRoot` come from?
29
+ * -------------------------------------------------------
30
+ * This module treats the passed root as ground truth. It does NOT fetch
31
+ * it. Two ways to source it:
32
+ *
33
+ * • Non-custodial (recommended). Fetch it yourself from Mina via
34
+ * `fetchOnChainLicensesRoot({ zkAppAddress, network })` from
35
+ * `zklicensing/on-chain-root`. That reads `zkapp.appState[0]` on
36
+ * the deployed LicensingApp — the same field the circuit updates on
37
+ * every buy/renew/bind/unbind/refund. No trust in the licensing
38
+ * service required.
39
+ *
40
+ * • Custodial (trusted-service). Use whatever root the licensing
41
+ * service returned on its `/verify` or `/witness` response. Faster
42
+ * (no o1js + Mina RPC round-trip) but relies on the service to
43
+ * report the true chain state. If you go this route, cross-check
44
+ * the reported root against the on-chain value on some cadence.
45
+ *
46
+ * The caller fetches the device slot state (occupied[] + freedAt[] + cap)
47
+ * from the vendor SDK or platform verifier alongside the licensesRoot on
48
+ * the sync cadence of their choice. The parallel arrays fold to
49
+ * `deviceSlotsRoot`, so any tampering with slot contents changes the leaf
50
+ * hash and fails the witness check — provided `licensesRoot` itself is
51
+ * trustworthy (see above), verifyOffline needs no trust in whoever
52
+ * served the slot arrays.
53
+ *
54
+ * Not exported at the top-level barrel by default; vendors who ship a
55
+ * device-cap app import from `zklicensing/verify-offline` explicitly.
56
+ */
57
+
58
+ import { Field, Poseidon, PublicKey, UInt32 } from 'o1js';
59
+ import { deserializeWitness, type serializeWitness } from './licenseStore.js';
60
+ import {
61
+ computeDeviceSlotsRoot,
62
+ DEVICE_SLOT_CAP_N,
63
+ leafHash,
64
+ LicenseLeaf,
65
+ packSlotTimes,
66
+ } from './licenseLeaf.js';
67
+ import { computeDeviceCommitment } from './deviceIdentity.js';
68
+
69
+ // Serialized shape callers pass in for each of the DEVICE_SLOT_CAP_N slots.
70
+ // Empty slots use `deviceCommitment: '0'` (matches the record mirror). The
71
+ // two timestamps are Mina slot numbers (UInt32-range); freedAt=0 means the
72
+ // slot has never been unbound since its bind.
73
+ export type DeviceSlotSnapshot = {
74
+ slotIndex: number;
75
+ deviceCommitment: string;
76
+ boundAtSlot: number;
77
+ freedAtSlot: number;
78
+ };
79
+
80
+ export type VerifyOfflineInput = {
81
+ // The on-chain root the caller has anchored to for this verification.
82
+ // See the "Trust anchoring" section of the module-level docstring for
83
+ // sourcing — non-custodial callers should pass the value returned by
84
+ // `fetchOnChainLicensesRoot` from `zklicensing/on-chain-root`; custodial
85
+ // callers can pass a service-reported root but forfeit the "service
86
+ // doesn't need to be trusted" property.
87
+ licensesRoot: string;
88
+ currentSlot: number;
89
+
90
+ // ── LicenseLeaf field set as of the sync ─────────────────────────────
91
+ // Together these reconstruct `leafHash(leaf)` and are matched against the
92
+ // witness. Any tampering with any field flips the reconstructed hash and
93
+ // fails the root check.
94
+ licenseHash: string; // Also serves as the on-chain owner-pubkey commitment (buy circuit asserts equality)
95
+ expirySlot: number;
96
+ deviceCap: number; // 0 disables the device-commitment check entirely
97
+ devices: DeviceSlotSnapshot[]; // exactly DEVICE_SLOT_CAP_N entries; caller pads empties
98
+
99
+ // MerkleMap witness for `licenseHash` in the licensesRoot tree, serialized
100
+ // by `serializeWitness` (same shape POST /prove/buy and the /verify handler
101
+ // both emit).
102
+ witness: ReturnType<typeof serializeWitness>;
103
+
104
+ // Caller's device pubkey — only consulted when deviceCap > 0. Omit for
105
+ // uncapped apps; the module rejects a caller-supplied pubkey with cap=0
106
+ // so a misconfigured integration surfaces loudly instead of silently
107
+ // trusting whatever was passed.
108
+ devicePubKey?: PublicKey;
109
+ };
110
+
111
+ export type VerifyOfflineResult = {
112
+ valid: boolean;
113
+ reason: string | null;
114
+ };
115
+
116
+ // Pad or trim the caller-supplied slot list to exactly DEVICE_SLOT_CAP_N and
117
+ // order by slotIndex. `computeDeviceSlotsRoot` requires the exact layout
118
+ // (occupied[i], freedAt[i], ...) that the circuit folds — mismatched length
119
+ // or ordering yields a different root and (correctly) fails the witness
120
+ // check downstream. Doing the normalization here keeps the caller free to
121
+ // pass only the occupied slots.
122
+ function normalizeSlots(devices: DeviceSlotSnapshot[]): { occupied: Field[]; freedAt: Field[]; occupiedCommitments: string[] } {
123
+ const occupied: Field[] = [];
124
+ const freedAt: Field[] = [];
125
+ const occupiedCommitments: string[] = [];
126
+ for (let i = 0; i < DEVICE_SLOT_CAP_N; i++) {
127
+ const slot = devices.find(d => d.slotIndex === i);
128
+ const occ = slot?.deviceCommitment ?? '0';
129
+ occupied.push(Field(occ));
130
+ occupiedCommitments.push(occ);
131
+ const boundU32 = UInt32.from(slot?.boundAtSlot ?? 0);
132
+ const freedU32 = UInt32.from(slot?.freedAtSlot ?? 0);
133
+ freedAt.push(packSlotTimes(boundU32, freedU32));
134
+ }
135
+ return { occupied, freedAt, occupiedCommitments };
136
+ }
137
+
138
+ /**
139
+ * Pure offline device-binding verifier. See module-level docstring.
140
+ *
141
+ * All errors are returned via `{ valid: false, reason }` rather than thrown
142
+ * — callers integrate this into a boot-time gate and don't want to catch
143
+ * around every call. `reason` is stable enough to key error UX off of.
144
+ */
145
+ export function verifyOffline(input: VerifyOfflineInput): VerifyOfflineResult {
146
+ const {
147
+ licensesRoot,
148
+ currentSlot,
149
+ licenseHash,
150
+ expirySlot,
151
+ deviceCap,
152
+ devices,
153
+ witness,
154
+ devicePubKey,
155
+ } = input;
156
+
157
+ const { occupied, freedAt, occupiedCommitments } = normalizeSlots(devices);
158
+ const deviceSlotsRoot = computeDeviceSlotsRoot(occupied, freedAt);
159
+ const deviceSlotsFilled = occupiedCommitments.filter(c => c !== '0').length;
160
+
161
+ const leaf = new LicenseLeaf({
162
+ licenseHash: Field(licenseHash),
163
+ expirySlot: UInt32.from(expirySlot),
164
+ cap: UInt32.from(deviceCap),
165
+ deviceSlotsRoot,
166
+ deviceSlotsFilled: UInt32.from(deviceSlotsFilled),
167
+ });
168
+ const expectedLeafHash = leafHash(leaf);
169
+
170
+ const restoredWitness = deserializeWitness(witness);
171
+ const [computedRoot, computedKey] = restoredWitness.computeRootAndKey(expectedLeafHash);
172
+ if (computedKey.toString() !== Field(licenseHash).toString()) {
173
+ return { valid: false, reason: 'Witness key does not match licenseHash' };
174
+ }
175
+ if (computedRoot.toString() !== licensesRoot) {
176
+ return { valid: false, reason: 'Reconstructed leaf does not match synced licensesRoot' };
177
+ }
178
+
179
+ if (expirySlot <= currentSlot) {
180
+ return { valid: false, reason: 'License has expired' };
181
+ }
182
+
183
+ if (deviceCap === 0) {
184
+ if (devicePubKey !== undefined) {
185
+ // Fail loud rather than silently accept — a caller wiring devicePubKey
186
+ // into an app that turns out to have cap=0 is almost certainly a
187
+ // misconfiguration (they think the app enforces bindings when it
188
+ // doesn't).
189
+ return { valid: false, reason: 'deviceCap is 0 for this license; do not pass devicePubKey' };
190
+ }
191
+ return { valid: true, reason: null };
192
+ }
193
+
194
+ if (!devicePubKey) {
195
+ return { valid: false, reason: 'deviceCap > 0 requires devicePubKey' };
196
+ }
197
+ const commitment = computeDeviceCommitment(devicePubKey);
198
+ if (!occupiedCommitments.includes(commitment)) {
199
+ return { valid: false, reason: 'Device is not bound to this license' };
200
+ }
201
+
202
+ return { valid: true, reason: null };
203
+ }
204
+
205
+ // Re-export the shared Poseidon fold formula so callers that want to compute
206
+ // `deviceCommitment` for a pubkey they only have as (x, isOdd) can reuse
207
+ // the identical shape the circuit uses. Preferred entry point is still
208
+ // `computeDeviceCommitment(devicePubKey)` in ./deviceIdentity.ts — this is
209
+ // for callers who only hold raw fields.
210
+ export function deviceCommitmentFromFields(x: Field, isOdd: Field): Field {
211
+ return Poseidon.hash([x, isOdd]);
212
+ }