openproof-verify

Verify OpenProof cryptographic signatures on API responses.

OpenProof is an open protocol that adds ECDSA signatures to every API response — so any client can cryptographically prove that data came from the claimed source and has not been tampered with in transit.

Install

npm install openproof-verify
# recommended: also install ethers for full signature recovery
npm install openproof-verify ethers

Usage

const { verifyResponse } = require('openproof-verify')

const response = await fetch('https://your-api.com/v1/data')
const json = await response.json()

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)
}

What OpenProof adds to an API response

Every OpenProof-compliant API includes a _trust envelope alongside the response data:

{
  "data": { "price": 2081.41, "symbol": "ETH" },
  "_trust": {
    "call_id":      "op_abc123def456",
    "endpoint":     "/v1/price/ETH",
    "payload_hash": "sha256:9f86d081...",
    "timestamp":    1711234567,
    "signer":       "0x41A024...",
    "signature":    "0x3ad7f1..."
  }
}

This proves:

• The response came from the owner of 0x41A024...
• The data field has not been modified since signing
• The response was signed at timestamp (verified against a 5-minute window)

API

verifyResponse(response, options?)

Verify a full response object containing data and _trust.

verify(data, trust, options?)

Verify with explicit data and trust envelope objects.

verifyRemote(apiBaseUrl, data, trust)

Verify via the API's own /v1/verify/signature endpoint. Returns a Promise.

canonical(obj)

Serialize an object to deterministic canonical JSON (sorted keys, no whitespace).

clearReplayCache()

Clear the in-process replay protection cache. Useful in tests.

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | trustedSigners | string[] | undefined | Allowlist of signer addresses. If set, signature must come from one of these. | | maxAgeSeconds | number | 300 | Reject signatures older than N seconds. Set to 0 to disable. | | checkReplay | boolean | true | Reject duplicate call_id values (in-process cache). |

Security features

• Replay protection — tracks call_id values in memory, rejects duplicates
• Timestamp validation — rejects signatures older than 5 minutes by default
• Future timestamp detection — rejects timestamps more than 30s in the future
• Canonical JSON — deterministic serialization prevents hash manipulation
• Input validation — validates all envelope fields before processing

Implementing OpenProof on your API

Any API can implement OpenProof. See the full protocol spec at openproof.io/spec or the SPEC.md.

Reference implementations:

• Python (FastAPI): SPEC.md#python
• TypeScript (Node.js): SPEC.md#typescript

License

MIT — free to use in any project, open or commercial.