@yantrixai/openproof-verify 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# openproof-verify
+
+Verify [OpenProof](https://openproof.io) cryptographic signatures on API responses.
+
+OpenProof is an open protocol that adds ECDSA signatures to every API response — so AI agents can cryptographically verify that data came from the claimed source and hasn't been tampered with.
+
+## Install
+
+```bash
+npm install openproof-verify
+# or
+npm install openproof-verify ethers  # recommended for full signature recovery
+```
+
+## Usage
+
+```javascript
+const { verify, verifyResponse } = require('openproof-verify')
+
+// From a Yantrix API response:
+const response = await fetch('https://agent-registry.yantrix.ai/v1/agents/agt_abc123')
+const json = await response.json()
+
+// Verify the signature
+const result = verifyResponse(json)
+
+if (result.valid) {
+  console.log('✓ Response verified')
+  console.log('  Signed by:', result.signer)
+  console.log('  Signed at:', new Date(result.signed_at * 1000).toISOString())
+} else {
+  console.error('✗ Verification failed:', result.reason)
+}
+```
+
+### With trusted signers
+
+```javascript
+const result = verify(json.data, json._proof, {
+  trustedSigners: ['0x41a024c1c89fd30122c8b184de99cbe751eac970'],
+  maxAgeSeconds: 60,  // reject signatures older than 1 minute
+})
+```
+
+### Remote verification
+
+```javascript
+const { verifyRemote } = require('openproof-verify')
+
+const result = await verifyRemote(
+  'https://agent-registry.yantrix.ai',
+  json.data,
+  json._proof
+)
+```
+
+## What is OpenProof?
+
+OpenProof adds a `_proof` envelope to every API response:
+
+```json
+{
+  "data": { "price": 2081.41, "symbol": "ETH" },
+  "_proof": {
+    "call_id":      "ytx_abc123def456",
+    "endpoint":     "/v1/price/ETH",
+    "payload_hash": "sha256:9f86d081...",
+    "timestamp":    1711234567,
+    "signer":       "0x41A024c1C89Fd30122c8b184de99cbE751eaC970",
+    "signature":    "0x3ad7f1..."
+  }
+}
+```
+
+The signature proves:
+1. The response came from the owner of `0x41A024...`
+2. The `data` field hasn't been modified since signing
+3. The response was signed at `timestamp`
+
+## API
+
+### `verify(data, trust, options?)`
+Verify locally. Returns `{ valid, signer, signed_at, reason }`.
+
+### `verifyResponse(response, options?)`
+Verify a full response object with `data` and `_proof` fields.
+
+### `verifyRemote(apiBaseUrl, data, trust)`
+Verify via the API's own `/v1/verify/signature` endpoint. Returns a Promise.
+
+### `canonical(obj)`
+Serialize an object to canonical JSON (sorted keys, no whitespace).
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `trustedSigners` | `string[]` | `undefined` | Allowlist of trusted signer addresses |
+| `maxAgeSeconds` | `number` | `300` | Reject signatures older than this. Set to `0` to disable. |
+
+## OpenProof-compliant APIs
+
+- [Yantrix Agent Registry](https://agent-registry.yantrix.ai)
+- [Yantrix Agent Session](https://agent-session.yantrix.ai)
+- [Yantrix Relay](https://relay.yantrix.ai)
+- [Full list at openproof.io/registry](https://openproof.io/registry)
+
+## Protocol Spec
+
+[SPEC.md](https://github.com/yantrix-ai/openproof/blob/main/SPEC.md)
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,56 @@
+export interface TrustEnvelope {
+  call_id: string
+  endpoint: string
+  payload_hash: string
+  timestamp: number
+  signer: string
+  signature: string
+  receipt_url?: string
+}
+
+export interface VerifyResult {
+  valid: boolean
+  signer?: string
+  signed_at?: number
+  call_id?: string
+  endpoint?: string
+  reason?: string
+}
+
+export interface VerifyOptions {
+  /** List of trusted signer addresses (lowercase). If provided, signer must be in this list. */
+  trustedSigners?: string[]
+  /** Maximum age of signature in seconds. 0 = skip age check. Default: 300 (5 minutes) */
+  maxAgeSeconds?: number
+}
+
+/**
+ * Verify a OpenProof signature locally.
+ */
+export function verify(
+  data: object,
+  trust: TrustEnvelope,
+  options?: VerifyOptions
+): VerifyResult
+
+/**
+ * Verify a OpenProof signature remotely via the API's /v1/verify/signature endpoint.
+ */
+export function verifyRemote(
+  apiBaseUrl: string,
+  data: object,
+  trust: TrustEnvelope
+): Promise<VerifyResult>
+
+/**
+ * Extract and verify OpenProof from a full API response containing `data` and `_proof`.
+ */
+export function verifyResponse(
+  response: { data: object; _proof: TrustEnvelope; [key: string]: any },
+  options?: VerifyOptions
+): VerifyResult
+
+/**
+ * Canonicalize an object to deterministic JSON (sorted keys, no whitespace).
+ */
+export function canonical(obj: object): string

package/index.js

@@ -0,0 +1,173 @@
+'use strict'
+
+/**
+ * openproof-verify
+ * Verify OpenProof signatures on API responses.
+ * https://openproof.io
+ */
+
+const crypto = require('crypto')
+
+/**
+ * Canonicalize an object to deterministic JSON.
+ * Sorted keys, no whitespace.
+ */
+function canonical(obj) {
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    return JSON.stringify(obj)
+  }
+  const sorted = Object.keys(obj).sort().reduce((acc, key) => {
+    acc[key] = obj[key]
+    return acc
+  }, {})
+  return JSON.stringify(sorted, (_, v) => {
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      return Object.keys(v).sort().reduce((acc, k) => {
+        acc[k] = v[k]
+        return acc
+      }, {})
+    }
+    return v
+  })
+}
+
+/**
+ * Recover Ethereum address from a personal_sign signature.
+ * Works in Node.js without ethers.js dependency.
+ */
+function recoverAddress(message, signature) {
+  try {
+    // Try using ethers if available
+    const ethers = require('ethers')
+    return ethers.verifyMessage(message, signature).toLowerCase()
+  } catch (e) {
+    // Fallback: manual recovery using secp256k1
+    try {
+      const { ecdsaRecover, publicKeyConvert } = require('secp256k1')
+      const prefix = `\x19Ethereum Signed Message:\n${Buffer.byteLength(message)}`
+      const msgHash = crypto.createHash('sha256')
+        .update(Buffer.from(prefix + message))
+        .digest()
+      const sigBuf = Buffer.from(signature.replace('0x', ''), 'hex')
+      const r = sigBuf.slice(0, 32)
+      const s = sigBuf.slice(32, 64)
+      let v = sigBuf[64]
+      if (v >= 27) v -= 27
+      const pubKey = ecdsaRecover(Buffer.concat([r, s]), v, msgHash, false)
+      const pubKeyHash = crypto.createHash('sha256').update(pubKeyConvert(pubKey, false).slice(1)).digest()
+      return '0x' + pubKeyHash.slice(-20).toString('hex').toLowerCase()
+    } catch (e2) {
+      throw new Error(`Cannot recover address: no ethers or secp256k1 available. Install ethers: npm install ethers`)
+    }
+  }
+}
+
+/**
+ * Verify a OpenProof signature.
+ *
+ * @param {object} data - The `data` field from the API response
+ * @param {object} trust - The `_proof` envelope from the API response
+ * @param {object} [options] - Verification options
+ * @param {string[]} [options.trustedSigners] - List of trusted signer addresses (lowercase)
+ * @param {number} [options.maxAgeSeconds=300] - Max age of signature in seconds (0 = skip)
+ * @returns {{ valid: boolean, signer?: string, signed_at?: number, reason?: string }}
+ */
+function verify(data, trust, options = {}) {
+  const { trustedSigners, maxAgeSeconds = 300 } = options
+
+  if (!trust || typeof trust !== 'object') {
+    return { valid: false, reason: 'Missing _proof envelope' }
+  }
+
+  const { call_id, endpoint, payload_hash, timestamp, signer, signature } = trust
+
+  if (!call_id || !endpoint || !payload_hash || !timestamp || !signer || !signature) {
+    return { valid: false, reason: 'Incomplete _proof envelope — missing required fields' }
+  }
+
+  // Step 1: Verify payload hash
+  const canonicalData = canonical(data)
+  const computedHash = crypto.createHash('sha256').update(canonicalData).digest('hex')
+  const expectedHash = payload_hash.replace('sha256:', '')
+
+  if (computedHash !== expectedHash) {
+    return { valid: false, reason: 'Payload hash mismatch — data may have been tampered with' }
+  }
+
+  // Step 2: Check timestamp freshness
+  if (maxAgeSeconds > 0) {
+    const now = Math.floor(Date.now() / 1000)
+    const age = now - timestamp
+    if (age > maxAgeSeconds) {
+      return { valid: false, reason: `Signature expired — ${age}s old, max ${maxAgeSeconds}s` }
+    }
+  }
+
+  // Step 3: Recover signer from signature
+  const message = `${call_id}:${endpoint}:sha256:${computedHash}:${timestamp}`
+  let recovered
+  try {
+    recovered = recoverAddress(message, signature)
+  } catch (e) {
+    return { valid: false, reason: `Signature recovery failed: ${e.message}` }
+  }
+
+  if (recovered !== signer.toLowerCase()) {
+    return { valid: false, reason: `Signer mismatch — expected ${signer}, got ${recovered}` }
+  }
+
+  // Step 4: Check trusted signers (optional)
+  if (trustedSigners && trustedSigners.length > 0) {
+    const normalizedTrusted = trustedSigners.map(s => s.toLowerCase())
+    if (!normalizedTrusted.includes(recovered)) {
+      return { valid: false, reason: `Signer ${recovered} not in trusted signers list` }
+    }
+  }
+
+  return {
+    valid: true,
+    signer: recovered,
+    signed_at: timestamp,
+    call_id,
+    endpoint,
+  }
+}
+
+/**
+ * Verify a OpenProof signature asynchronously (remote verification).
+ * Calls the API's /v1/verify/signature endpoint.
+ *
+ * @param {string} apiBaseUrl - Base URL of the API (e.g. https://agent-registry.yantrix.ai)
+ * @param {object} data - The `data` field from the response
+ * @param {object} trust - The `_proof` envelope from the response
+ * @returns {Promise<{ valid: boolean, signer?: string, signed_at?: number }>}
+ */
+async function verifyRemote(apiBaseUrl, data, trust) {
+  const url = `${apiBaseUrl.replace(/\/$/, '')}/v1/verify/signature`
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ envelope: trust, payload: data }),
+  })
+  const result = await response.json()
+  return result.data || result
+}
+
+/**
+ * Extract and verify OpenProof from a full API response object.
+ *
+ * @param {object} response - Full API response containing `data` and `_proof`
+ * @param {object} [options] - Same options as verify()
+ */
+function verifyResponse(response, options = {}) {
+  if (!response || typeof response !== 'object') {
+    return { valid: false, reason: 'Invalid response object' }
+  }
+  const { data, _proof } = response
+  if (!_proof) {
+    return { valid: false, reason: 'Response does not include _proof envelope — not OpenProof compliant' }
+  }
+  return verify(data, _proof, options)
+}
+
+module.exports = { verify, verifyRemote, verifyResponse, canonical }

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@yantrixai/openproof-verify",
+  "version": "1.0.0",
+  "description": "Verify OpenProof cryptographic signatures on API responses. For AI agents that need to trust external data.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "openproof",
+    "api",
+    "signature",
+    "verification",
+    "ecdsa",
+    "ethereum",
+    "ai-agents",
+    "x402",
+    "yantrix"
+  ],
+  "author": "Yantrix <hello@yantrix.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yantrix-ai/openproof"
+  },
+  "homepage": "https://openproof.io",
+  "peerDependencies": {
+    "ethers": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ethers": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}