insumer-verify 1.0.1 → 1.1.1

package/README.md

@@ -1,6 +1,10 @@
 # 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.
+Client-side verifier for [InsumerAPI](https://insumermodel.com/developers/) attestations. Validates ECDSA P-256 signatures, condition hashes, block freshness, and attestation expiry. Zero runtime dependencies. Web Crypto API. Node.js 18+ and modern browsers.
+
+**In production:** [DJD Agent Score](https://github.com/jacobsd32-cpu/djdagentscore) (Coinbase x402 ecosystem) uses insumer-verify for client-side cryptographic verification in their AI agent wallet trust scoring pipeline. [Case study](https://insumermodel.com/blog/djd-agent-score-insumer-api-integration.html).
+
+Part of the InsumerAPI ecosystem: [REST API](https://insumermodel.com/developers/) (17 endpoints, 31 chains) | [MCP server](https://www.npmjs.com/package/mcp-server-insumer) (npm) | [LangChain](https://pypi.org/project/langchain-insumer/) (PyPI) | [OpenAI GPT](https://chatgpt.com/g/g-699c5e43ce2481918b3f1e7f144c8a49-insumerapi-verify) (GPT Store)
 
 ## Install
 
@@ -91,6 +95,18 @@ const result = await verifyAttestation(apiResponse, { maxAge: 120 });
 
 Results without `blockTimestamp` (Covalent and Solana chains) are skipped, not treated as failures.
 
+### JWKS key discovery
+
+By default, insumer-verify uses the hardcoded InsumerAPI public key. You can opt in to dynamic key discovery via the JWKS endpoint:
+
+```typescript
+const result = await verifyAttestation(apiResponse, {
+  jwksUrl: "https://insumermodel.com/.well-known/jwks.json"
+});
+```
+
+When `jwksUrl` is set, the library fetches the JWKS, matches the key by `kid` from the attestation response, and uses it for signature verification. This enables automatic key rotation without library updates.
+
 ## API
 
 ### `verifyAttestation(response, options?)`
@@ -99,6 +115,7 @@ Results without `blockTimestamp` (Covalent and Solana chains) are skipped, not t
 |-----------|------|-------------|
 | `response` | `unknown` | Full InsumerAPI response (must contain `data.attestation` and `data.sig`) |
 | `options.maxAge` | `number` | Optional max age in seconds for block freshness check |
+| `options.jwksUrl` | `string` | Optional JWKS URL for dynamic key discovery (e.g. `https://insumermodel.com/.well-known/jwks.json`) |
 
 Returns `Promise<VerifyResult>`:
 

package/build/index.d.ts

@@ -23,6 +23,8 @@ export interface CheckResult {
 export interface VerifyOptions {
     /** Maximum acceptable age of blockTimestamp in seconds. Results without blockTimestamp are skipped. */
     maxAge?: number;
+    /** JWKS URL for dynamic key discovery. When set, fetches the signing key from this URL instead of using the hardcoded key. Example: "https://insumermodel.com/.well-known/jwks.json" */
+    jwksUrl?: string;
 }
 /**
  * Verify an InsumerAPI attestation response.

package/build/index.js

@@ -34,6 +34,21 @@ function bytesToHex(bytes) {
     }
     return hex;
 }
+async function fetchJwksKey(jwksUrl, kid) {
+    const res = await fetch(jwksUrl);
+    if (!res.ok) {
+        throw new Error(`JWKS fetch failed: ${res.status} ${res.statusText}`);
+    }
+    const jwks = (await res.json());
+    if (!jwks.keys || !Array.isArray(jwks.keys) || jwks.keys.length === 0) {
+        throw new Error("JWKS response contains no keys");
+    }
+    // Match by kid if provided, otherwise use first key
+    const key = kid
+        ? jwks.keys.find((k) => k.kid === kid) || jwks.keys[0]
+        : jwks.keys[0];
+    return { kty: key.kty, crv: key.crv, x: key.x, y: key.y };
+}
 function parseResponse(response) {
     const obj = response;
     const data = obj?.data;
@@ -63,15 +78,16 @@ function parseResponse(response) {
     if (typeof attestation.expiresAt !== "string") {
         throw new Error("Invalid response: missing attestation.expiresAt");
     }
-    return { data: { attestation, sig } };
+    const kid = data.kid;
+    return { data: { attestation, sig, kid } };
 }
 // ── Verification checks ───────────────────────────────────────────
-async function checkSignature(attestation, sig) {
+async function checkSignature(attestation, sig, keyJwk) {
     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"]);
+        const key = await subtle.importKey("jwk", keyJwk || 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({
@@ -167,9 +183,27 @@ function checkExpiry(attestation) {
  */
 export async function verifyAttestation(response, options) {
     const parsed = parseResponse(response);
-    const { attestation, sig } = parsed.data;
+    const { attestation, sig, kid } = parsed.data;
+    // If jwksUrl is provided, fetch the signing key dynamically
+    let keyJwk;
+    if (options?.jwksUrl) {
+        try {
+            keyJwk = await fetchJwksKey(options.jwksUrl, kid);
+        }
+        catch (e) {
+            return {
+                valid: false,
+                checks: {
+                    signature: { passed: false, reason: `JWKS fetch error: ${e.message}` },
+                    conditionHashes: { passed: false, reason: "Skipped (JWKS fetch failed)" },
+                    freshness: { passed: false, reason: "Skipped (JWKS fetch failed)" },
+                    expiry: { passed: false, reason: "Skipped (JWKS fetch failed)" },
+                },
+            };
+        }
+    }
     const [signature, conditionHashes, freshness, expiry] = await Promise.all([
-        checkSignature(attestation, sig),
+        checkSignature(attestation, sig, keyJwk),
         checkConditionHashes(attestation.results),
         Promise.resolve(checkFreshness(attestation.results, options?.maxAge)),
         Promise.resolve(checkExpiry(attestation)),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "insumer-verify",
-  "version": "1.0.1",
-  "description": "Reference verifier for InsumerAPI attestations. Validates ECDSA signatures, condition hashes, block freshness, and expiry. Zero dependencies.",
+  "version": "1.1.1",
+  "description": "Client-side verifier for InsumerAPI attestations. ECDSA P-256 signatures, condition hashes, block freshness, expiry. Zero dependencies. Used by DJD Agent Score (Coinbase x402).",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -26,7 +26,11 @@
     "verification",
     "blockchain",
     "on-chain",
-    "web-crypto"
+    "web-crypto",
+    "ai-agents",
+    "token-gating",
+    "merkle-proof",
+    "agent-trust"
   ],
   "author": "Douglas Borthwick",
   "license": "MIT",