zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/build/verifyOffline.js

@@ -0,0 +1,139 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+/**
+ * verifyOffline.ts
+ *
+ * Non-custodial device-binding offline verifier. Given:
+ *   - a serialized MerkleMapWitness for the license entry
+ *   - a `licensesRoot` value the caller has anchored to (see "Trust anchoring")
+ *   - the full LicenseLeaf field set (licenseHash, expirySlot, deviceCap,
+ *     deviceSlots[]) as of that sync — the leaf carries no separate
+ *     owner-pubkey commitment because `licenseHash` IS it (buy circuit
+ *     asserts equality)
+ *   - the caller's device public key
+ *
+ * this module:
+ *   1. Reconstructs the LicenseLeaf hash from its fields.
+ *   2. Rebuilds the on-chain root through the witness and asserts it matches
+ *      the passed `licensesRoot` — proves the leaf field set is authentic
+ *      relative to that root.
+ *   3. If `deviceCap > 0`: computes the device commitment for the caller's
+ *      pubkey and asserts it appears in `occupied[]`.
+ *   4. Asserts `expirySlot > currentSlot` (grace-period handling stays in
+ *      the online verifier; the device-bound offline path is pass/fail).
+ *   5. If `deviceCap === 0`: skips the device check entirely — the app has
+ *      binding disabled at the vendor level.
+ *
+ * Trust anchoring — where does `licensesRoot` come from?
+ * -------------------------------------------------------
+ * This module treats the passed root as ground truth. It does NOT fetch
+ * it. Two ways to source it:
+ *
+ *   • Non-custodial (recommended). Fetch it yourself from Mina via
+ *     `fetchOnChainLicensesRoot({ zkAppAddress, network })` from
+ *     `zklicensing/on-chain-root`. That reads `zkapp.appState[0]` on
+ *     the deployed LicensingApp — the same field the circuit updates on
+ *     every buy/renew/bind/unbind/refund. No trust in the licensing
+ *     service required.
+ *
+ *   • Custodial (trusted-service). Use whatever root the licensing
+ *     service returned on its `/verify` or `/witness` response. Faster
+ *     (no o1js + Mina RPC round-trip) but relies on the service to
+ *     report the true chain state. If you go this route, cross-check
+ *     the reported root against the on-chain value on some cadence.
+ *
+ * The caller fetches the device slot state (occupied[] + freedAt[] + cap)
+ * from the vendor SDK or platform verifier alongside the licensesRoot on
+ * the sync cadence of their choice. The parallel arrays fold to
+ * `deviceSlotsRoot`, so any tampering with slot contents changes the leaf
+ * hash and fails the witness check — provided `licensesRoot` itself is
+ * trustworthy (see above), verifyOffline needs no trust in whoever
+ * served the slot arrays.
+ *
+ * Not exported at the top-level barrel by default; vendors who ship a
+ * device-cap app import from `zklicensing/verify-offline` explicitly.
+ */
+import { Field, Poseidon, UInt32 } from 'o1js';
+import { deserializeWitness } from './licenseStore.js';
+import { computeDeviceSlotsRoot, DEVICE_SLOT_CAP_N, leafHash, LicenseLeaf, packSlotTimes, } from './licenseLeaf.js';
+import { computeDeviceCommitment } from './deviceIdentity.js';
+// Pad or trim the caller-supplied slot list to exactly DEVICE_SLOT_CAP_N and
+// order by slotIndex. `computeDeviceSlotsRoot` requires the exact layout
+// (occupied[i], freedAt[i], ...) that the circuit folds — mismatched length
+// or ordering yields a different root and (correctly) fails the witness
+// check downstream. Doing the normalization here keeps the caller free to
+// pass only the occupied slots.
+function normalizeSlots(devices) {
+    const occupied = [];
+    const freedAt = [];
+    const occupiedCommitments = [];
+    for (let i = 0; i < DEVICE_SLOT_CAP_N; i++) {
+        const slot = devices.find(d => d.slotIndex === i);
+        const occ = slot?.deviceCommitment ?? '0';
+        occupied.push(Field(occ));
+        occupiedCommitments.push(occ);
+        const boundU32 = UInt32.from(slot?.boundAtSlot ?? 0);
+        const freedU32 = UInt32.from(slot?.freedAtSlot ?? 0);
+        freedAt.push(packSlotTimes(boundU32, freedU32));
+    }
+    return { occupied, freedAt, occupiedCommitments };
+}
+/**
+ * Pure offline device-binding verifier. See module-level docstring.
+ *
+ * All errors are returned via `{ valid: false, reason }` rather than thrown
+ * — callers integrate this into a boot-time gate and don't want to catch
+ * around every call. `reason` is stable enough to key error UX off of.
+ */
+export function verifyOffline(input) {
+    const { licensesRoot, currentSlot, licenseHash, expirySlot, deviceCap, devices, witness, devicePubKey, } = input;
+    const { occupied, freedAt, occupiedCommitments } = normalizeSlots(devices);
+    const deviceSlotsRoot = computeDeviceSlotsRoot(occupied, freedAt);
+    const deviceSlotsFilled = occupiedCommitments.filter(c => c !== '0').length;
+    const leaf = new LicenseLeaf({
+        licenseHash: Field(licenseHash),
+        expirySlot: UInt32.from(expirySlot),
+        cap: UInt32.from(deviceCap),
+        deviceSlotsRoot,
+        deviceSlotsFilled: UInt32.from(deviceSlotsFilled),
+    });
+    const expectedLeafHash = leafHash(leaf);
+    const restoredWitness = deserializeWitness(witness);
+    const [computedRoot, computedKey] = restoredWitness.computeRootAndKey(expectedLeafHash);
+    if (computedKey.toString() !== Field(licenseHash).toString()) {
+        return { valid: false, reason: 'Witness key does not match licenseHash' };
+    }
+    if (computedRoot.toString() !== licensesRoot) {
+        return { valid: false, reason: 'Reconstructed leaf does not match synced licensesRoot' };
+    }
+    if (expirySlot <= currentSlot) {
+        return { valid: false, reason: 'License has expired' };
+    }
+    if (deviceCap === 0) {
+        if (devicePubKey !== undefined) {
+            // Fail loud rather than silently accept — a caller wiring devicePubKey
+            // into an app that turns out to have cap=0 is almost certainly a
+            // misconfiguration (they think the app enforces bindings when it
+            // doesn't).
+            return { valid: false, reason: 'deviceCap is 0 for this license; do not pass devicePubKey' };
+        }
+        return { valid: true, reason: null };
+    }
+    if (!devicePubKey) {
+        return { valid: false, reason: 'deviceCap > 0 requires devicePubKey' };
+    }
+    const commitment = computeDeviceCommitment(devicePubKey);
+    if (!occupiedCommitments.includes(commitment)) {
+        return { valid: false, reason: 'Device is not bound to this license' };
+    }
+    return { valid: true, reason: null };
+}
+// Re-export the shared Poseidon fold formula so callers that want to compute
+// `deviceCommitment` for a pubkey they only have as (x, isOdd) can reuse
+// the identical shape the circuit uses. Preferred entry point is still
+// `computeDeviceCommitment(devicePubKey)` in ./deviceIdentity.ts — this is
+// for callers who only hold raw fields.
+export function deviceCommitmentFromFields(x, isOdd) {
+    return Poseidon.hash([x, isOdd]);
+}
+//# sourceMappingURL=verifyOffline.js.map

package/build/verifyOffline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyOffline.js","sourceRoot":"","sources":["../src/verifyOffline.ts"],"names":[],"mappings":"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"}

package/build/verifyService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyService.d.ts","sourceRoot":"","sources":["../src/verifyService.ts"],"names":[],"mappings":""}