insumer-verify 1.1.4 → 1.2.0

package/README.md

@@ -4,7 +4,7 @@ Client-side verifier for [InsumerAPI](https://insumermodel.com/developers/) atte
 
 **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/) (25 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)
+Part of the InsumerAPI ecosystem: [REST API](https://insumermodel.com/developers/) (25 endpoints, 32 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
 

package/build/index.d.ts

@@ -4,6 +4,10 @@
  * 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.
+ *
+ * Accepts two input formats (auto-detected):
+ * - **JWT string**: ES256-signed JWT from POST /v1/attest with format: "jwt"
+ * - **Object**: Raw API response object with data.attestation and data.sig
  */
 export interface VerifyResult {
     valid: boolean;
@@ -29,14 +33,18 @@ export interface VerifyOptions {
 /**
  * Verify an InsumerAPI attestation response.
  *
- * Runs 4 independent checks:
- * 1. **Signature** — ECDSA P-256 over {id, pass, results, attestedAt}
+ * Auto-detects input format:
+ * - **String** → JWT verification path (ES256 signature via JWKS)
+ * - **Object** → Raw attestation response path (ECDSA P1363 signature)
+ *
+ * Both formats run the same 4 checks:
+ * 1. **Signature** — ECDSA P-256 verification
  * 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
+ * 4. **Expiry** — whether the 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
+ * @param response JWT string or full API response object
+ * @param options Optional configuration: maxAge (seconds), jwksUrl
  * @returns Structured result with overall validity and per-check details
  */
 export declare function verifyAttestation(response: unknown, options?: VerifyOptions): Promise<VerifyResult>;

package/build/index.js

@@ -4,6 +4,10 @@
  * 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.
+ *
+ * Accepts two input formats (auto-detected):
+ * - **JWT string**: ES256-signed JWT from POST /v1/attest with format: "jwt"
+ * - **Object**: Raw API response object with data.attestation and data.sig
  */
 // ── Public key ─────────────────────────────────────────────────────
 /**
@@ -17,6 +21,7 @@ const PUBLIC_KEY_JWK = {
     y: "kn34HaxVSJfn8NxwNEBjjLkcrM_GDw1lgnqyADGuc4c",
     crv: "P-256",
 };
+const DEFAULT_JWKS_URL = "https://insumermodel.com/.well-known/jwks.json";
 // ── Helpers ────────────────────────────────────────────────────────
 const subtle = globalThis.crypto?.subtle;
 function base64ToBytes(b64) {
@@ -27,6 +32,21 @@ function base64ToBytes(b64) {
     }
     return bytes;
 }
+function base64UrlToBytes(b64url) {
+    // Convert base64url to standard base64
+    let b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+    // Add padding
+    const pad = b64.length % 4;
+    if (pad === 2)
+        b64 += "==";
+    else if (pad === 3)
+        b64 += "=";
+    return base64ToBytes(b64);
+}
+function base64UrlDecode(b64url) {
+    const bytes = base64UrlToBytes(b64url);
+    return new TextDecoder().decode(bytes);
+}
 function bytesToHex(bytes) {
     let hex = "";
     for (let i = 0; i < bytes.length; i++) {
@@ -81,6 +101,63 @@ function parseResponse(response) {
     const kid = data.kid;
     return { data: { attestation, sig, kid } };
 }
+function parseJwt(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new Error("Invalid JWT: expected 3 dot-separated segments");
+    }
+    const [headerB64, payloadB64, sigB64] = parts;
+    let header;
+    let payload;
+    try {
+        header = JSON.parse(base64UrlDecode(headerB64));
+    }
+    catch {
+        throw new Error("Invalid JWT: malformed header");
+    }
+    try {
+        payload = JSON.parse(base64UrlDecode(payloadB64));
+    }
+    catch {
+        throw new Error("Invalid JWT: malformed payload");
+    }
+    const signatureBytes = base64UrlToBytes(sigB64);
+    return { header, payload, headerB64, payloadB64, signatureBytes };
+}
+/**
+ * Convert a DER-encoded ECDSA signature to raw IEEE P1363 format (r || s).
+ * jose/Node.js crypto may produce DER signatures; Web Crypto expects P1363.
+ */
+function derToP1363(der, keySize = 32) {
+    if (der[0] !== 0x30)
+        return der; // Not DER, assume already P1363
+    let offset = 2;
+    // Parse r
+    if (der[offset] !== 0x02)
+        return der;
+    offset++;
+    const rLen = der[offset];
+    offset++;
+    let r = der.slice(offset, offset + rLen);
+    offset += rLen;
+    // Parse s
+    if (der[offset] !== 0x02)
+        return der;
+    offset++;
+    const sLen = der[offset];
+    offset++;
+    let s = der.slice(offset, offset + sLen);
+    // Remove leading zero padding
+    if (r.length > keySize)
+        r = r.slice(r.length - keySize);
+    if (s.length > keySize)
+        s = s.slice(s.length - keySize);
+    // Pad to fixed keySize
+    const result = new Uint8Array(keySize * 2);
+    result.set(r, keySize - r.length);
+    result.set(s, keySize * 2 - s.length);
+    return result;
+}
 // ── Verification checks ───────────────────────────────────────────
 async function checkSignature(attestation, sig, keyJwk) {
     if (!subtle) {
@@ -110,6 +187,35 @@ async function checkSignature(attestation, sig, keyJwk) {
         };
     }
 }
+async function checkJwtSignature(jwt, keyJwk) {
+    if (!subtle) {
+        return { passed: false, reason: "Web Crypto API not available" };
+    }
+    try {
+        if (jwt.header.alg !== "ES256") {
+            return { passed: false, reason: `Unsupported JWT algorithm: ${jwt.header.alg}` };
+        }
+        const key = await subtle.importKey("jwk", keyJwk || PUBLIC_KEY_JWK, { name: "ECDSA", namedCurve: "P-256" }, false, ["verify"]);
+        // JWT signature is over "header.payload" (the raw base64url segments)
+        const signingInput = new TextEncoder().encode(`${jwt.headerB64}.${jwt.payloadB64}`);
+        // JWT ES256 signatures should be raw r||s (P1363, 64 bytes)
+        // but some libraries produce DER encoding — handle both
+        let sigBytes = jwt.signatureBytes;
+        if (sigBytes.length !== 64) {
+            sigBytes = derToP1363(sigBytes);
+        }
+        const valid = await subtle.verify({ name: "ECDSA", hash: "SHA-256" }, key, sigBytes.buffer, signingInput);
+        return valid
+            ? { passed: true }
+            : { passed: false, reason: "JWT signature does not match payload" };
+    }
+    catch (e) {
+        return {
+            passed: false,
+            reason: `JWT signature verification error: ${e.message}`,
+        };
+    }
+}
 async function checkConditionHashes(results) {
     if (!subtle) {
         return { passed: false, reason: "Web Crypto API not available" };
@@ -157,31 +263,92 @@ function checkFreshness(results, maxAge) {
     }
     return { passed: true };
 }
-function checkExpiry(attestation) {
-    const expiresAt = new Date(attestation.expiresAt).getTime();
-    if (isNaN(expiresAt)) {
+function checkExpiry(expiresAt) {
+    const ts = new Date(expiresAt).getTime();
+    if (isNaN(ts)) {
         return { passed: false, reason: "Invalid expiresAt timestamp" };
     }
-    if (Date.now() > expiresAt) {
+    if (Date.now() > ts) {
         return { passed: false, reason: "Attestation has expired" };
     }
     return { passed: true };
 }
+// ── JWT verification path ─────────────────────────────────────────
+async function verifyJwt(token, options) {
+    let jwt;
+    try {
+        jwt = parseJwt(token);
+    }
+    catch (e) {
+        return {
+            valid: false,
+            checks: {
+                signature: { passed: false, reason: `JWT parse error: ${e.message}` },
+                conditionHashes: { passed: false, reason: "Skipped (JWT parse failed)" },
+                freshness: { passed: false, reason: "Skipped (JWT parse failed)" },
+                expiry: { passed: false, reason: "Skipped (JWT parse failed)" },
+            },
+        };
+    }
+    const p = jwt.payload;
+    // Resolve the signing key: use jwksUrl from options, or from JWT kid, or hardcoded
+    const jwksUrl = options?.jwksUrl || DEFAULT_JWKS_URL;
+    const kid = jwt.header.kid;
+    let keyJwk;
+    try {
+        keyJwk = await fetchJwksKey(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)" },
+            },
+        };
+    }
+    // Extract attestation data from JWT claims
+    const results = (p.results || []);
+    // JWT exp → expiresAt ISO string
+    const expUnix = p.exp;
+    const expiresAt = expUnix ? new Date(expUnix * 1000).toISOString() : "";
+    const [signature, conditionHashes, freshness, expiry] = await Promise.all([
+        checkJwtSignature(jwt, keyJwk),
+        checkConditionHashes(results),
+        Promise.resolve(checkFreshness(results, options?.maxAge)),
+        Promise.resolve(checkExpiry(expiresAt)),
+    ]);
+    const valid = signature.passed &&
+        conditionHashes.passed &&
+        freshness.passed &&
+        expiry.passed;
+    return { valid, checks: { signature, conditionHashes, freshness, expiry } };
+}
 // ── Main export ────────────────────────────────────────────────────
 /**
  * Verify an InsumerAPI attestation response.
  *
- * Runs 4 independent checks:
- * 1. **Signature** — ECDSA P-256 over {id, pass, results, attestedAt}
+ * Auto-detects input format:
+ * - **String** → JWT verification path (ES256 signature via JWKS)
+ * - **Object** → Raw attestation response path (ECDSA P1363 signature)
+ *
+ * Both formats run the same 4 checks:
+ * 1. **Signature** — ECDSA P-256 verification
  * 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
+ * 4. **Expiry** — whether the 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
+ * @param response JWT string or full API response object
+ * @param options Optional configuration: maxAge (seconds), jwksUrl
  * @returns Structured result with overall validity and per-check details
  */
 export async function verifyAttestation(response, options) {
+    // Auto-detect: string → JWT, object → raw attestation
+    if (typeof response === "string") {
+        return verifyJwt(response, options);
+    }
     const parsed = parseResponse(response);
     const { attestation, sig, kid } = parsed.data;
     // If jwksUrl is provided, fetch the signing key dynamically
@@ -206,7 +373,7 @@ export async function verifyAttestation(response, options) {
         checkSignature(attestation, sig, keyJwk),
         checkConditionHashes(attestation.results),
         Promise.resolve(checkFreshness(attestation.results, options?.maxAge)),
-        Promise.resolve(checkExpiry(attestation)),
+        Promise.resolve(checkExpiry(attestation.expiresAt)),
     ]);
     const valid = signature.passed &&
         conditionHashes.passed &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insumer-verify",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "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",