@sonate/verify-sdk

@sonate/verify-sdk

Client-side SDK for verifying SONATE Trust Receipts. Works in Node.js and browsers — zero backend calls required.

Install

npm install @sonate/verify-sdk

Quick Start

import { verify, fetchPublicKey } from '@sonate/verify-sdk';

// Fetch the SONATE public key (or provide your own)
const publicKey = await fetchPublicKey();

// Verify a receipt
const result = await verify(receipt, publicKey);

if (result.valid) {
  console.log('All checks passed');
  console.log('Trust score:', result.trustScore);
} else {
  console.error('Verification failed:', result.errors);
}

API

verify(receipt, publicKey)

Full verification with detailed check results.

const result = await verify(receipt, publicKey);

// result.valid — overall pass/fail
// result.checks.structure — required fields present
// result.checks.signature — Ed25519 signature valid
// result.checks.chain — hash chain intact
// result.checks.timestamp — timestamp reasonable
// result.trustScore — extracted from telemetry (0-100)
// result.errors — array of error messages

quickVerify(receipt, publicKey)

Boolean-only verification for simple pass/fail checks.

const isValid = await quickVerify(receipt, publicKey);

verifyBatch(receipts, publicKey)

Verify multiple receipts at once.

const { total, valid, invalid, results } = await verifyBatch(receipts, publicKey);

fetchPublicKey(url?)

Fetch a SONATE public key from a backend endpoint.

// Default: fetches from SONATE platform
const key = await fetchPublicKey();

// Custom endpoint
const key = await fetchPublicKey('https://your-server.com/api/public-key');

canonicalize(obj)

Deterministic JSON serialization. Useful for building custom verification flows.

import { canonicalize } from '@sonate/verify-sdk';

const canonical = canonicalize({ b: 2, a: 1 });
// '{"a":1,"b":2}'

Verification Checks

Check	What it verifies
Structure	Receipt has the required id and signature fields (V2 format)
Hash	id matches SHA-256 of the canonical receipt payload — the content hasn't been altered
Signature	Ed25519 signature over the canonical receipt content
Chain	chain_hash matches SHA-256(canonical_content + previous_hash)
Timestamp	Not in the future (5-min skew), not older than maxAgeMs (default 1 year)

Scope: these checks prove a receipt is authentic and untampered — it was signed by the holder of the key and nothing has been changed since. They do not re-derive the trust score; result.trustScore is read from the signed payload (authentic as issued).

Browser Support

The SDK uses Web Crypto API in browsers and falls back to Node.js crypto module. Ed25519 operations use @noble/ed25519 for cross-platform compatibility.

<script type="module">
  import { verify, fetchPublicKey } from '@sonate/verify-sdk';

  const publicKey = await fetchPublicKey();
  const result = await verify(receiptFromAPI, publicKey);
  console.log('Valid:', result.valid);
</script>

Receipt Format

The SDK verifies V2 Trust Receipts:

interface TrustReceipt {
  id: string;              // SHA-256 of canonical content
  version: '2.0.0' | '2.2.0';
  timestamp: string;       // ISO 8601
  session_id: string;
  agent_did: string;       // did:web:...
  human_did: string;
  mode: 'constitutional' | 'directive';
  interaction: {
    prompt?: string;        // Raw content (when included)
    response?: string;
    prompt_hash?: string;   // SHA-256 hash (privacy-preserving)
    response_hash?: string;
    model: string;
  };
  chain: {
    previous_hash: string;
    chain_hash: string;
  };
  signature: {
    algorithm: 'Ed25519';
    value: string;          // Hex-encoded
    key_version: string;
  };
}

Related Packages

• @sonate/trust-receipts — Generate signed receipts in your own applications
• @sonate/schemas — JSON Schema + TypeScript types
• @sonate/core — Core trust protocol implementation

License

MIT