SDK Usage

The @certivu/sdk package wraps all Certivu API calls and handles hashing, signing, and token encoding for you.

Install

npm install @certivu/sdk

Initialize

import { CertivuClient } from '@certivu/sdk'

const certivu = new CertivuClient({
  apiKey: 'ctv_key_abc123',       // required
  generatorId: 'gen_xyz',         // required for signing
  privateKey: process.env.CERTIVU_PRIVATE_KEY, // required for signing
  baseUrl: 'https://api.certivu.ai', // optional, default shown
})

---

Sign content

const { token, record_id } = await certivu.sign({
  content: imageBuffer,   // Buffer or Uint8Array
  model: 'stable-diffusion-xl',
  watermarkId: 'wm_optional', // auto-generated if omitted
})

Internally, the SDK:

1. Computes sha3-256 of content
2. Builds and canonically serializes signed_payload
3. Signs with ML-DSA-65 using your private key
4. POSTs to POST /v1/records
5. Returns { token, record_id }

---

Verify content

// Token provided — fast path
const result = await certivu.verify({
  content: imageBuffer,
  token: 'ctv_7f3kx9mq2...',
})

// No token — auto-extracted from XMP then watermark
const result = await certivu.verify({ content: imageBuffer })

Result shape

{
  authentic: boolean,
  tampered: boolean,
  confidence: 'high' | 'medium' | 'low' | 'none',
  token_source?: 'provided' | 'xmp' | 'watermark',
  signals: {
    watermark_found: boolean,
    record_found: boolean,
    signature_valid: boolean,
  },
  provenance?: {
    org: string,
    model: string,
    signed_at: string,
  },
  reason?: string,
}

---

Batch verify

For platforms processing many images at once (up to 50 per call):

const results = await certivu.verifyBatch([
  { content: image1, token: token1 },
  { content: image2 },           // token optional per item
  { content: image3, token: token3 },
])

Returns an array of VerificationResult in the same order.

---

Audit log

const log = await certivu.getAuditLog({ page: 1, limit: 50 })

// log.events — array of { event_id, type, timestamp, metadata }
// log.total — total event count

---

Error handling

try {
  const result = await certivu.sign({ content, model })
} catch (err) {
  if (err.status === 402) {
    // Free tier limit hit
    console.log('Upgrade at:', err.upgrade_url)
  }
}

Status	Meaning
400	Validation error or invalid signature
401	Bad API key
402	Signature quota exhausted (free tier)
403	Generator doesn’t belong to your org
404	Generator not found or revoked