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

package/src/vatRatesData.ts

@@ -0,0 +1,43 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+//
+// GENERATED by scripts/build-vat-rates.mjs — do not edit by hand.
+//
+// Standard VAT rates (percent) with the date each took effect, per country.
+// Source: ibericode/vat-rates, https://raw.githubusercontent.com/ibericode/vat-rates/master/vat-rates.json
+// (MIT License, Copyright 2019 Danny van Kooten). Fetched 2026-10-13.
+
+export const VAT_RATES_SOURCE = 'ibericode/vat-rates (MIT)';
+export const VAT_RATES_FETCHED = '2026-10-13';
+
+/** country → [effective-from date, standard rate %][], oldest first. */
+export const STANDARD_VAT_RATES: Readonly<Record<string, ReadonlyArray<readonly [string, number]>>> = {
+  AT: [['1970-01-01', 20], ['2016-01-01', 20]],
+  BE: [['1970-01-01', 21]],
+  BG: [['1970-01-01', 20]],
+  CY: [['1970-01-01', 19]],
+  CZ: [['1970-01-01', 21], ['2024-01-01', 21]],
+  DE: [['1970-01-01', 19], ['2020-07-01', 16], ['2021-01-01', 19]],
+  DK: [['1970-01-01', 25]],
+  EE: [['1970-01-01', 20], ['2024-01-01', 22], ['2025-01-01', 22], ['2025-07-01', 24]],
+  ES: [['1970-01-01', 21]],
+  FI: [['1970-01-01', 24], ['2024-09-01', 25.5], ['2026-01-01', 25.5]],
+  FR: [['1970-01-01', 19.6], ['2012-01-01', 19.6], ['2014-01-01', 20]],
+  GB: [['2011-01-04', 20]],
+  GR: [['1970-01-01', 23], ['2016-01-01', 23], ['2016-06-01', 24]],
+  HR: [['1970-01-01', 25]],
+  HU: [['1970-01-01', 27]],
+  IE: [['1970-01-01', 23], ['2020-09-01', 21], ['2021-03-01', 23]],
+  IT: [['1970-01-01', 22]],
+  LT: [['1970-01-01', 21]],
+  LU: [['1970-01-01', 15], ['2015-01-01', 17], ['2016-01-01', 17], ['2023-01-01', 16], ['2024-01-01', 17]],
+  LV: [['1970-01-01', 21]],
+  MT: [['1970-01-01', 18]],
+  NL: [['1970-01-01', 19], ['2012-10-01', 21], ['2019-01-01', 21]],
+  PL: [['1970-01-01', 23]],
+  PT: [['1970-01-01', 23]],
+  RO: [['1970-01-01', 24], ['2016-01-01', 20], ['2017-01-01', 19], ['2025-08-01', 21]],
+  SE: [['1970-01-01', 25]],
+  SI: [['1970-01-01', 22]],
+  SK: [['1970-01-01', 19], ['2011-01-01', 20], ['2025-01-01', 23]],
+};

package/src/vendorAccountClient.ts

@@ -0,0 +1,120 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * vendorAccountClient.ts
+ *
+ * Browser-safe client for the vendor's shared legal/billing block —
+ * the fields that must stay consistent across every app registered by
+ * one vendor wallet (legal entity name, billing country and address,
+ * VAT id, company registry). One PATCH updates all of the vendor's
+ * apps atomically on the backend, so a legal-entity rename or address
+ * move doesn't leave old apps advertising stale CRD Art. 6 disclosures.
+ *
+ * Signature covers the vendor address, mirroring the "sign the
+ * resource id" pattern PUT /apps/:appId uses. The backend verifies
+ * against the on-chain vendor recorded on the app records.
+ */
+
+export type VendorLegalBlock = {
+  country?: string;
+  legalName?: string;
+  billingAddress?: {
+    line1: string;
+    line2?: string;
+    city: string;
+    postalCode: string;
+  };
+  invoiceEmail?: string;
+  supportEmail?: string;
+  vatId?: string;
+  companyRegistrationRegistry?: string;
+  companyRegistrationNumber?: string;
+  termsOfServiceUrl?: string;
+  privacyPolicyUrl?: string;
+  refundPolicyUrl?: string;
+};
+
+export type GetVendorLegalRequest = {
+  keeperUrl:          string;
+  vendorAddress:      string;
+  vendorSessionToken: string;
+  fetcher?:           typeof fetch;
+  signal?:            AbortSignal;
+};
+
+export type GetVendorLegalResponse = {
+  // null when the wallet has no apps yet — register form should prompt
+  // for the block instead of treating first-app registration as an error.
+  legal: VendorLegalBlock | null;
+};
+
+export type UpdateVendorLegalRequest = {
+  keeperUrl:     string;
+  vendorAddress: string;
+  payload:       VendorLegalBlock;
+  /** The vendor's session (`VendorSession` token) for the network its apps
+   * are on — mainnet if any app is on mainnet. Or give a `fetcher` that
+   * adds it. */
+  sessionToken?: string;
+  /** Ignored by the keeper (the old signature over the vendor's own address,
+   * which could be replayed); kept so existing callers compile. */
+  signature?:    { field: string; scalar: string };
+  fetcher?:      typeof fetch;
+  signal?:       AbortSignal;
+};
+
+export type UpdateVendorLegalResponse = {
+  ok:          true;
+  appsUpdated: number;
+};
+
+function baseUrl(url: string): string {
+  return url.replace(/\/+$/, '');
+}
+
+async function readJsonError(resp: Response): Promise<string> {
+  try {
+    const body = await resp.json() as Record<string, unknown>;
+    if (typeof body.error === 'string') return body.error;
+  } catch { /* body wasn't JSON */ }
+  return `HTTP ${resp.status}`;
+}
+
+// GET /vendors/:address/legal — fetch the shared legal block for a wallet.
+// Returns `{ legal: null }` for wallets with no registered apps.
+export async function getVendorLegal(req: GetVendorLegalRequest): Promise<GetVendorLegalResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(
+    `${baseUrl(req.keeperUrl)}/vendors/${encodeURIComponent(req.vendorAddress)}/legal`,
+    {
+      signal:  req.signal,
+      headers: { Authorization: `VendorSession ${req.vendorSessionToken}` },
+    },
+  );
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as GetVendorLegalResponse;
+}
+
+// PATCH /vendors/:address/legal — updates the block on EVERY app the vendor
+// owns in a single atomic sweep. Authorised by the vendor's session. Bypasses the pendingEdit staging that
+// per-app metadata edits go through; legal fields are factual (not
+// marketing copy) so admin review doesn't gain anything and staleness
+// hurts CRD Art. 6 compliance.
+export async function updateVendorLegal(req: UpdateVendorLegalRequest): Promise<UpdateVendorLegalResponse> {
+  const fetcher = req.fetcher ?? fetch;
+  const resp = await fetcher(
+    `${baseUrl(req.keeperUrl)}/vendors/${encodeURIComponent(req.vendorAddress)}/legal`,
+    {
+      method:  'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(req.sessionToken ? { Authorization: `VendorSession ${req.sessionToken}` } : {}),
+      },
+      signal:  req.signal,
+      body:    JSON.stringify({ payload: req.payload }),
+    },
+  );
+  if (!resp.ok) throw new Error(await readJsonError(resp));
+  return await resp.json() as UpdateVendorLegalResponse;
+}

package/src/verifyCore.ts

@@ -0,0 +1,100 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * verifyCore.ts
+ *
+ * Pure verification logic shared by keeperService and verifyService.
+ * No HTTP, no network — takes already-fetched on-chain state and
+ * performs Merkle inclusion check + expiry logic.
+ */
+
+import { Field } from 'o1js';
+import { buildMap, type LicenseRecord } from './licenseStore.js';
+import { GRACE_PERIOD_N, MS_PER_SLOT_N, SLOTS_PER_DAY_N, effectiveExpirySlot } from './contractInterface.js';
+
+export type VerifyResponse = {
+  valid: boolean;
+  expiresAt: string | null;
+  expirySlot: number;
+  // Set when a license that lapsed during the pre-fork sales freeze counts
+  // from the app's fork slot (see effectiveExpirySlot); validity uses it.
+  effectiveExpirySlot?: number;
+  inGracePeriod: boolean;
+  // Whole days until expiry. Negative while in the grace period (down to ~-7
+  // — GRACE_PERIOD_N is 6 720 slots = 7 days) and below that once expired.
+  // 0 when expirySlot is unknown (unknown/refunded/root-mismatch).
+  remainingDays: number;
+  reason: string | null;
+};
+
+function computeRemainingDays(expirySlot: number, currentSlot: number): number {
+  if (expirySlot === 0) return 0;
+  return Math.floor((expirySlot - currentSlot) / SLOTS_PER_DAY_N);
+}
+
+/**
+ * Core license verification.
+ *
+ * @param zkAppAddress - app address (composite key with licenseHash)
+ * @param licenseHash  - Poseidon hash of the buyer's Ed25519 pubkey (see ownershipLicenseHash.ts) as a field string
+ * @param records      - current off-chain license records (from licenseStore)
+ * @param onChainRoot  - zkApp appState[0] fetched from Mina
+ * @param currentSlot  - current blockchain slot (globalSlotSinceGenesis)
+ * @param forkActivationSlot - the app's forkActivationSlot state (0: none)
+ */
+export function verifyLicenseCore(params: {
+  zkAppAddress: string;
+  licenseHash: string;
+  records: LicenseRecord[];
+  onChainRoot: string;
+  currentSlot: number;
+  forkActivationSlot?: number;
+}): VerifyResponse {
+  const { zkAppAddress, licenseHash, records, onChainRoot, currentSlot } = params;
+
+  const map = buildMap(records, zkAppAddress);
+  const key = Field(licenseHash);
+  const currentValue = map.get(key).toString();
+  const witness = map.getWitness(key);
+
+  const [computedRoot] = witness.computeRootAndKey(Field(currentValue));
+
+  if (computedRoot.toString() !== onChainRoot) {
+    return { valid: false, expiresAt: null, expirySlot: 0, inGracePeriod: false, remainingDays: 0, reason: 'License state does not match on-chain root' };
+  }
+
+  // Post-LicenseLeaf: the map value is `leaf.hash()`, not raw expirySlot.
+  // Empty slots still hash to Field(0). Look up the record to recover
+  // expirySlot; `buildMap` excludes refunded/empty entries, so a missing
+  // record here means either "never bought" or "refunded" (record kept but
+  // expirySlot cleared to 0).
+  const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+
+  if (currentValue === '0') {
+    const reason = record?.refunded ? 'License has been refunded' : 'License not found';
+    return { valid: false, expiresAt: null, expirySlot: 0, inGracePeriod: false, remainingDays: 0, reason };
+  }
+
+  const expirySlot = record?.expirySlot ?? 0;
+  const effective = effectiveExpirySlot(expirySlot, params.forkActivationSlot ?? 0);
+  const bumped = effective !== expirySlot ? { effectiveExpirySlot: effective } : {};
+  const inGracePeriod = currentSlot > effective && currentSlot <= effective + GRACE_PERIOD_N;
+  const expired = currentSlot > effective + GRACE_PERIOD_N;
+  const expiresAt = new Date(Date.now() + (effective - currentSlot) * MS_PER_SLOT_N).toISOString();
+  const remainingDays = computeRemainingDays(effective, currentSlot);
+
+  if (expired) {
+    return { valid: false, expiresAt, expirySlot, ...bumped, inGracePeriod: false, remainingDays, reason: 'License has expired' };
+  }
+
+  return {
+    valid: true,
+    expiresAt,
+    expirySlot,
+    ...bumped,
+    inGracePeriod,
+    remainingDays,
+    reason: inGracePeriod ? 'License is in grace period — renew to avoid interruption' : null,
+  };
+}

package/src/verifyOffline.ts

@@ -0,0 +1,212 @@
+// 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, PublicKey, UInt32 } from 'o1js';
+import { deserializeWitness, type serializeWitness } from './licenseStore.js';
+import {
+  computeDeviceSlotsRoot,
+  DEVICE_SLOT_CAP_N,
+  leafHash,
+  LicenseLeaf,
+  packSlotTimes,
+} from './licenseLeaf.js';
+import { computeDeviceCommitment } from './deviceIdentity.js';
+
+// Serialized shape callers pass in for each of the DEVICE_SLOT_CAP_N slots.
+// Empty slots use `deviceCommitment: '0'` (matches the record mirror). The
+// two timestamps are Mina slot numbers (UInt32-range); freedAt=0 means the
+// slot has never been unbound since its bind.
+export type DeviceSlotSnapshot = {
+  slotIndex:        number;
+  deviceCommitment: string;
+  boundAtSlot:      number;
+  freedAtSlot:      number;
+};
+
+export type VerifyOfflineInput = {
+  // The on-chain root the caller has anchored to for this verification.
+  // See the "Trust anchoring" section of the module-level docstring for
+  // sourcing — non-custodial callers should pass the value returned by
+  // `fetchOnChainLicensesRoot` from `zklicensing/on-chain-root`; custodial
+  // callers can pass a service-reported root but forfeit the "service
+  // doesn't need to be trusted" property.
+  licensesRoot:     string;
+  currentSlot:      number;
+
+  // ── LicenseLeaf field set as of the sync ─────────────────────────────
+  // Together these reconstruct `leafHash(leaf)` and are matched against the
+  // witness. Any tampering with any field flips the reconstructed hash and
+  // fails the root check.
+  licenseHash:      string;   // Also serves as the on-chain owner-pubkey commitment (buy circuit asserts equality)
+  expirySlot:       number;
+  deviceCap:        number;   // 0 disables the device-commitment check entirely
+  devices:          DeviceSlotSnapshot[];  // exactly DEVICE_SLOT_CAP_N entries; caller pads empties
+
+  // MerkleMap witness for `licenseHash` in the licensesRoot tree, serialized
+  // by `serializeWitness` (same shape POST /prove/buy and the /verify handler
+  // both emit).
+  witness:          ReturnType<typeof serializeWitness>;
+
+  // Caller's device pubkey — only consulted when deviceCap > 0. Omit for
+  // uncapped apps; the module rejects a caller-supplied pubkey with cap=0
+  // so a misconfigured integration surfaces loudly instead of silently
+  // trusting whatever was passed.
+  devicePubKey?:    PublicKey;
+};
+
+export type VerifyOfflineResult = {
+  valid:  boolean;
+  reason: string | null;
+};
+
+// 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: DeviceSlotSnapshot[]): { occupied: Field[]; freedAt: Field[]; occupiedCommitments: string[] } {
+  const occupied: Field[] = [];
+  const freedAt:  Field[] = [];
+  const occupiedCommitments: string[] = [];
+  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: VerifyOfflineInput): VerifyOfflineResult {
+  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: Field, isOdd: Field): Field {
+  return Poseidon.hash([x, isOdd]);
+}