insumer-verify 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Douglas Borthwick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# insumer-verify
+
+Reference verifier for [InsumerAPI](https://insumermodel.com/developers/) attestations. Validates ECDSA P-256 signatures, condition hashes, block freshness, and attestation expiry using the Web Crypto API. Zero runtime dependencies. Works in Node.js 18+ and modern browsers.
+
+## Install
+
+```bash
+npm install insumer-verify
+```
+
+## Usage
+
+### Node.js
+
+```typescript
+import { verifyAttestation } from "insumer-verify";
+
+// Call InsumerAPI
+const res = await fetch("https://insumerapi.com/v1/attest", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "X-API-Key": "your-api-key",
+  },
+  body: JSON.stringify({
+    wallet: "0x...",
+    conditions: [
+      {
+        type: "token_balance",
+        chainId: 1,
+        contractAddress: "0xA0b8...",
+        threshold: "1000000",
+        decimals: 6,
+      },
+    ],
+  }),
+});
+
+const apiResponse = await res.json();
+
+// Verify the attestation
+const result = await verifyAttestation(apiResponse);
+
+if (result.valid) {
+  console.log("Attestation verified");
+} else {
+  console.log("Verification failed:", result.checks);
+}
+```
+
+### Browser
+
+```html
+<script type="module">
+  import { verifyAttestation } from "https://esm.sh/insumer-verify";
+
+  const res = await fetch("https://insumerapi.com/v1/attest", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-API-Key": "your-api-key",
+    },
+    body: JSON.stringify({
+      wallet: "0x...",
+      conditions: [
+        {
+          type: "token_balance",
+          chainId: 1,
+          contractAddress: "0xA0b8...",
+          threshold: "1000000",
+          decimals: 6,
+        },
+      ],
+    }),
+  });
+
+  const apiResponse = await res.json();
+  const result = await verifyAttestation(apiResponse);
+  console.log(result);
+</script>
+```
+
+### Freshness check
+
+Pass `maxAge` (seconds) to reject attestations where block data is too old:
+
+```typescript
+const result = await verifyAttestation(apiResponse, { maxAge: 120 });
+// Fails if any blockTimestamp is older than 120 seconds
+```
+
+Results without `blockTimestamp` (Covalent and Solana chains) are skipped, not treated as failures.
+
+## API
+
+### `verifyAttestation(response, options?)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `response` | `unknown` | Full InsumerAPI response (must contain `data.attestation` and `data.sig`) |
+| `options.maxAge` | `number` | Optional max age in seconds for block freshness check |
+
+Returns `Promise<VerifyResult>`:
+
+```typescript
+interface VerifyResult {
+  valid: boolean; // true only if ALL checks pass
+  checks: {
+    signature: { passed: boolean; reason?: string };
+    conditionHashes: { passed: boolean; failures?: number[]; reason?: string };
+    freshness: { passed: boolean; reason?: string };
+    expiry: { passed: boolean; reason?: string };
+  };
+}
+```
+
+## What gets verified
+
+| Check | What it does |
+|-------|-------------|
+| **Signature** | Verifies the ECDSA P-256 signature over `{id, pass, results, attestedAt}` using InsumerAPI's public key |
+| **Condition hashes** | Recomputes SHA-256 of each `evaluatedCondition` (canonical sorted-key JSON) and compares to `conditionHash` |
+| **Freshness** | Checks `blockTimestamp` age against caller-defined `maxAge` (optional, skipped if not set) |
+| **Expiry** | Checks whether the attestation's 30-minute validity window has elapsed |
+
+## Condition hash specification
+
+Each attestation result includes an `evaluatedCondition` object and a `conditionHash`. The hash is computed as:
+
+1. Extract all keys from `evaluatedCondition` and sort them alphabetically
+2. Serialize with `JSON.stringify(evaluatedCondition, sortedKeys)` (the sorted keys array as the replacer produces canonical key order)
+3. Compute SHA-256 of the UTF-8 encoded string
+4. Format as `"0x" + hex`
+
+This ensures the condition that was actually evaluated on-chain can be independently verified by any third party.
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * insumer-verify — Reference verifier for InsumerAPI attestations.
+ *
+ * Validates ECDSA P-256 signatures, condition hashes, block freshness,
+ * and attestation expiry using the Web Crypto API. Zero dependencies.
+ * Works in Node.js 18+ and modern browsers.
+ */
+export interface VerifyResult {
+    valid: boolean;
+    checks: {
+        signature: CheckResult;
+        conditionHashes: CheckResult & {
+            failures?: number[];
+        };
+        freshness: CheckResult;
+        expiry: CheckResult;
+    };
+}
+export interface CheckResult {
+    passed: boolean;
+    reason?: string;
+}
+export interface VerifyOptions {
+    /** Maximum acceptable age of blockTimestamp in seconds. Results without blockTimestamp are skipped. */
+    maxAge?: number;
+}
+/**
+ * Verify an InsumerAPI attestation response.
+ *
+ * Runs 4 independent checks:
+ * 1. **Signature** — ECDSA P-256 over {id, pass, results, attestedAt}
+ * 2. **Condition hashes** — SHA-256 of canonical sorted-key JSON
+ * 3. **Freshness** — blockTimestamp age vs caller-defined maxAge (optional)
+ * 4. **Expiry** — whether the 30-minute attestation window has elapsed
+ *
+ * @param response The full API response object (must contain data.attestation and data.sig)
+ * @param options Optional configuration: maxAge (seconds) for freshness check
+ * @returns Structured result with overall validity and per-check details
+ */
+export declare function verifyAttestation(response: unknown, options?: VerifyOptions): Promise<VerifyResult>;

package/build/index.js

@@ -0,0 +1,190 @@
+/**
+ * insumer-verify — Reference verifier for InsumerAPI attestations.
+ *
+ * Validates ECDSA P-256 signatures, condition hashes, block freshness,
+ * and attestation expiry using the Web Crypto API. Zero dependencies.
+ * Works in Node.js 18+ and modern browsers.
+ */
+// ── Public key ─────────────────────────────────────────────────────
+/**
+ * InsumerAPI ECDSA P-256 public key in JWK format.
+ * Matches the private key stored in Firebase Secret Manager (ECDSA_PRIVATE_KEY).
+ * Same key embedded in InsumerScanner for QR signature verification.
+ */
+const PUBLIC_KEY_JWK = {
+    kty: "EC",
+    x: "JtHPhDPnv8AfP0JSlGutxbOlxreV2Chey27Z76q3V2c",
+    y: "kn34HaxVSJfn8NxwNEBjjLkcrM_GDw1lgnqyADGuc4c",
+    crv: "P-256",
+};
+// ── Helpers ────────────────────────────────────────────────────────
+const subtle = globalThis.crypto?.subtle;
+function base64ToBytes(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function bytesToHex(bytes) {
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+function parseResponse(response) {
+    const obj = response;
+    const data = obj?.data;
+    if (!data || typeof data !== "object") {
+        throw new Error("Invalid response: missing data object");
+    }
+    const attestation = data.attestation;
+    const sig = data.sig;
+    if (!attestation || typeof attestation !== "object") {
+        throw new Error("Invalid response: missing data.attestation");
+    }
+    if (typeof sig !== "string" || sig.length === 0) {
+        throw new Error("Invalid response: missing data.sig");
+    }
+    if (typeof attestation.id !== "string") {
+        throw new Error("Invalid response: missing attestation.id");
+    }
+    if (typeof attestation.pass !== "boolean") {
+        throw new Error("Invalid response: missing attestation.pass");
+    }
+    if (!Array.isArray(attestation.results)) {
+        throw new Error("Invalid response: missing attestation.results");
+    }
+    if (typeof attestation.attestedAt !== "string") {
+        throw new Error("Invalid response: missing attestation.attestedAt");
+    }
+    if (typeof attestation.expiresAt !== "string") {
+        throw new Error("Invalid response: missing attestation.expiresAt");
+    }
+    return { data: { attestation, sig } };
+}
+// ── Verification checks ───────────────────────────────────────────
+async function checkSignature(attestation, sig) {
+    if (!subtle) {
+        return { passed: false, reason: "Web Crypto API not available" };
+    }
+    try {
+        const key = await subtle.importKey("jwk", PUBLIC_KEY_JWK, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+        // Reconstruct the exact payload that was signed server-side.
+        // The Cloud Function signs: JSON.stringify({ id, pass, results, attestedAt })
+        const payload = JSON.stringify({
+            id: attestation.id,
+            pass: attestation.pass,
+            results: attestation.results,
+            attestedAt: attestation.attestedAt,
+        });
+        const payloadBytes = new TextEncoder().encode(payload);
+        const sigBytes = base64ToBytes(sig);
+        const valid = await subtle.verify({ name: "ECDSA", hash: "SHA-256" }, key, sigBytes.buffer, payloadBytes);
+        return valid
+            ? { passed: true }
+            : { passed: false, reason: "Signature does not match payload" };
+    }
+    catch (e) {
+        return {
+            passed: false,
+            reason: `Signature verification error: ${e.message}`,
+        };
+    }
+}
+async function checkConditionHashes(results) {
+    if (!subtle) {
+        return { passed: false, reason: "Web Crypto API not available" };
+    }
+    const failures = [];
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        if (!r.evaluatedCondition || !r.conditionHash)
+            continue;
+        // Canonical JSON: sorted keys, same as Cloud Function logic
+        const sortedKeys = Object.keys(r.evaluatedCondition).sort();
+        const canonical = JSON.stringify(r.evaluatedCondition, sortedKeys);
+        const hashBuffer = await subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+        const computed = "0x" + bytesToHex(new Uint8Array(hashBuffer));
+        if (computed !== r.conditionHash) {
+            failures.push(i);
+        }
+    }
+    if (failures.length > 0) {
+        return {
+            passed: false,
+            failures,
+            reason: `Condition hash mismatch at result index(es): ${failures.join(", ")}`,
+        };
+    }
+    return { passed: true };
+}
+function checkFreshness(results, maxAge) {
+    if (maxAge === undefined) {
+        return { passed: true, reason: "Freshness check skipped (no maxAge)" };
+    }
+    const now = Date.now();
+    const maxAgeMs = maxAge * 1000;
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        if (!r.blockTimestamp)
+            continue; // Covalent/Solana results lack blockTimestamp
+        const age = now - new Date(r.blockTimestamp).getTime();
+        if (age > maxAgeMs) {
+            return {
+                passed: false,
+                reason: `Result ${i} blockTimestamp is ${Math.round(age / 1000)}s old (max: ${maxAge}s)`,
+            };
+        }
+    }
+    return { passed: true };
+}
+function checkExpiry(attestation) {
+    const expiresAt = new Date(attestation.expiresAt).getTime();
+    if (isNaN(expiresAt)) {
+        return { passed: false, reason: "Invalid expiresAt timestamp" };
+    }
+    if (Date.now() > expiresAt) {
+        return { passed: false, reason: "Attestation has expired" };
+    }
+    return { passed: true };
+}
+// ── Main export ────────────────────────────────────────────────────
+/**
+ * Verify an InsumerAPI attestation response.
+ *
+ * Runs 4 independent checks:
+ * 1. **Signature** — ECDSA P-256 over {id, pass, results, attestedAt}
+ * 2. **Condition hashes** — SHA-256 of canonical sorted-key JSON
+ * 3. **Freshness** — blockTimestamp age vs caller-defined maxAge (optional)
+ * 4. **Expiry** — whether the 30-minute attestation window has elapsed
+ *
+ * @param response The full API response object (must contain data.attestation and data.sig)
+ * @param options Optional configuration: maxAge (seconds) for freshness check
+ * @returns Structured result with overall validity and per-check details
+ */
+export async function verifyAttestation(response, options) {
+    const parsed = parseResponse(response);
+    const { attestation, sig } = parsed.data;
+    const [signature, conditionHashes, freshness, expiry] = await Promise.all([
+        checkSignature(attestation, sig),
+        checkConditionHashes(attestation.results),
+        Promise.resolve(checkFreshness(attestation.results, options?.maxAge)),
+        Promise.resolve(checkExpiry(attestation)),
+    ]);
+    const valid = signature.passed &&
+        conditionHashes.passed &&
+        freshness.passed &&
+        expiry.passed;
+    return {
+        valid,
+        checks: {
+            signature,
+            conditionHashes,
+            freshness,
+            expiry,
+        },
+    };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "insumer-verify",
+  "version": "1.0.0",
+  "description": "Reference verifier for InsumerAPI attestations. Validates ECDSA signatures, condition hashes, block freshness, and expiry. Zero dependencies.",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "insumer",
+    "attestation",
+    "ecdsa",
+    "verification",
+    "blockchain",
+    "on-chain",
+    "web-crypto"
+  ],
+  "author": "Douglas Borthwick",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/douglasborthwick-crypto/insumer-verify.git"
+  },
+  "homepage": "https://insumermodel.com/developers/",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}