CertiSigma SDKs

npm install @certisigma/sdk

const { CertiSigmaClient } = require('@certisigma/sdk');

const client = new CertiSigmaClient({
  apiKey: process.env.CERTISIGMA_API_KEY,
});

(async function main() {
  const { CertiSigmaClient, hashFile, hashBytes } = require('@certisigma/sdk');
  const fs = require('fs');

  const client = new CertiSigmaClient({ apiKey: process.env.CERTISIGMA_API_KEY });

  // 1. Compute the SHA-256 hash of your file
  const fileHash = await hashFile(fs.readFileSync('contract.pdf'));
  console.log(`SHA-256: ${fileHash}`);  // 64-char lowercase hex

  // 2. Attest — creates a timestamped, signed proof of existence
  const result = await client.attest(fileHash, { source: 'my-app' });
  console.log(`Attestation: ${result.id} at ${result.timestamp}`);

  // 3. Verify — confirm the hash was attested
  const check = await client.verify(fileHash);
  console.log(`Exists: ${check.exists}, Level: ${check.level}`);

  // Or hash raw bytes directly
  const dataHash = await hashBytes(new TextEncoder().encode('any raw content'));
  const result2 = await client.attest(dataHash);
})();

(async function run() {
  const { CertiSigmaClient, hashFile } = require('@certisigma/sdk');
  const fs = require('fs');

  const client = new CertiSigmaClient({ apiKey: process.env.CERTISIGMA_API_KEY });

  // 1. Hash the file locally (SHA-256 via Web Crypto API; loads full file into memory)
  const hashHex = await hashFile(fs.readFileSync('contract.pdf'));

  // 2. Attest
  const result = await client.attest(hashHex, { source: 'contract-pipeline' });

  // 3. Save to a local JSON manifest
  const manifest = {
    id: result.id,
    hash: result.hash_hex,
    timestamp: result.timestamp,
    signature: result.signature,
    source: 'contract-pipeline',
  };
  fs.writeFileSync('contract.pdf.certisigma.json', JSON.stringify(manifest, null, 2));

  // 4. Later — download evidence (includes T2 when available)
  const evidence = await client.getEvidence(result.id);
  console.log(`Level: ${evidence.level}`);

  // 5. Update manifest with evidence
  manifest.level = evidence.level;
  manifest.t1 = evidence.t1;
  manifest.t2 = evidence.t2;
  fs.writeFileSync('contract.pdf.certisigma.json', JSON.stringify(manifest, null, 2));
})();

{
  "id": "att_a1b2c3d4e5f6",
  "hash": "e3b0c44298fc1c149afbf4c8996fb924...",
  "timestamp": "2025-06-15T10:30:00Z",
  "signature": "MEUCIQDx...",
  "source": "contract-pipeline",
  "original_file": "contract.pdf",
  "level": "T2",
  "t1": { "batchId": 42, "merkleRoot": "c4f3b2...", "tsaTimestamp": "2025-06-15T10:35:00Z" },
  "t2": {
    "bitcoinBlockHeight": 850123,
    "bitcoinBlockHash": "00000000000000000002a7c4...",
    "bitcoinTxid": "d4e5f6a7b8c9...",
    "confirmedAt": "2025-06-15T14:20:00Z"
  }
}

(async function run() {
  const { hashFile } = require('@certisigma/sdk');
  const fs = require('fs');

  // Compute hashes for all invoices (each file loaded fully into memory)
  const files = fs.readdirSync('invoices/').filter(f => f.endsWith('.pdf'));
  const hashes = await Promise.all(
    files.map(f => hashFile(fs.readFileSync(`invoices/${f}`)))
  );

  // Attest up to 100 hashes in one call — returns full claim metadata per item
  const batch = await client.batchAttest(hashes, { source: 'invoice-processor' });
  console.log(`Created: ${batch.created}, Existing: ${batch.existing}`);
  batch.attestations.forEach(a =>
    console.log(`  ${a.id} claim=${a.claim_id} src=${a.source}`)
  );

  // Later — verify the same files haven't been tampered with
  const currentHashes = await Promise.all(
    files.map(f => hashFile(fs.readFileSync(`invoices/${f}`)))
  );
  const results = await client.batchVerify(currentHashes);
  console.log(`Found: ${results.found}/${results.count}`);

  // Detailed mode — certification level + claim metadata (requires apiKey)
  const detailed = await client.batchVerify(currentHashes, { detailed: true });
  detailed.results.filter(r => r.exists).forEach(r =>
    console.log(`  ${r.id} level=${r.level} src=${r.source}`)
  );
})();

// Browser — from a file input (inside an async function)
const file = document.getElementById('fileInput').files[0];
const result = await client.attestFile(file, { source: 'upload-form' });

// Node.js — from a buffer (inside an async function)
const buf = fs.readFileSync('document.pdf');
const result2 = await client.attestFile(buf, { source: 'cli-tool' });

(async function run() {
  const { hashFile, hashBytes, hashString } = require('@certisigma/sdk');
  // or: const { hashFile, hashBytes, hashString } = require('@certisigma/sdk/hash');

  // Hash a File, Blob, ArrayBuffer, or Uint8Array
  const fileHash = await hashFile(fileInput.files[0]);

  // Hash raw bytes
  const dataHash = await hashBytes(new TextEncoder().encode('raw content'));

  // Hash a string (UTF-8, no file needed)
  const strHash = await hashString('SN-2026-001234');

  // Node.js — hash a local file for batch preparation
  const fs = require('fs');
  const hashes = await Promise.all(
    filePaths.map(p => hashBytes(fs.readFileSync(p)))
  );
  const batch = await client.batchAttest(hashes, { source: 'bulk-ingest' });
})();

// One-step: hash + attest
const result = await client.attestString('SN-2026-001234', { source: 'serial-registry' });

// Verify later
const check = await client.verifyString('SN-2026-001234');
console.assert(check.exists);

// Also works for files
const fileCheck = await client.verifyFile(fileInput.files[0]);

(async function run() {
  // Update claim metadata
  await client.updateMetadata('att_1234', {
    source: 'pipeline-v2',
    extraData: { project: 'alpha', version: '2.0' },
  });

  // Soft-delete claim
  await client.deleteMetadata('att_1234');

  // Get full cryptographic evidence
  const evidence = await client.getEvidence('att_1234');
})();

(async function run() {
  const { generateKey, encryptMetadata, decryptMetadata } = require('@certisigma/sdk/crypto');

  // Generate a key (store securely — server never sees it)
  const key = await generateKey();

  // Encrypt before sending
  const encrypted = await encryptMetadata({ secret: 'classified' }, key);
  const result = await client.attest(hash, { extraData: encrypted, clientEncrypted: true });

  // Decrypt after retrieving (extraData comes from the attest response, not verify)
  const plaintext = await decryptMetadata(result.extra_data, key);
})();

(async function run() {
  const token = await client.createShareToken([42, 43, 44], {
    expiresIn: 86400,             // 24 hours (max 30 days)
    recipientLabel: 'forensic-analyst',
    maxUses: 10,
  });
  console.log(`Share token: ${token.share_token}`); // shown once, save it

  // List, inspect, revoke
  const tokens = await client.listShareTokens();
  const info = await client.getShareTokenInfo(token.id);
  await client.revokeShareToken(token.id);
})();

(async function run() {
  // Upsert tags (max 50 per attestation per key)
  await client.putTags('att_42', [
    { key: 'department', value: 'hr' },
    { key: 'classification', value: 'confidential' },
  ]);

  const tags = await client.getTags('att_42');

  // Query by tags (AND semantics, max 10 conditions)
  const results = await client.queryTags(
    { and: [
      { key: 'department', value: 'hr' },
      { key: 'classification', value: 'confidential' },
    ]},
    { limit: 100 },
  );
  console.log(`Found ${results.count} matching attestations`);

  // Delete a tag
  await client.deleteTag('att_42', 'classification');
})();

const { CertiSigmaClient } = require('@certisigma/sdk');

const client = new CertiSigmaClient({ apiKey: process.env.CERTISIGMA_API_KEY });

// Leak detection — compare suspect hashes against org inventory
// Requires `scan` scope + org_id
const suspectHashes = ['a665a459...', 'b4c9a289...', 'e3b0c442...'];
const result = await client.scan(suspectHashes);
console.log(`Scan ${result.scan_id}: ${result.matched}/${result.total_scanned} matched`);
result.matches.forEach(m =>
  console.log(`  ${m.hash_hex} first_seen=${m.first_seen} source=${m.source}`)
);

// Inventory statistics — aggregate view of your org's claims
// Requires `batch` scope + org_id
const stats = await client.getBulkStats();
console.log(`Org ${stats.org_id_hash}: ${stats.total_claims} claims, ${stats.unique_hashes} unique`);
Object.entries(stats.claims_by_month).forEach(([month, count]) =>
  console.log(`  ${month}: ${count} claims`)
);

(async function run() {
  // 1. Create a derived list from explicit hashes
  const dl = await client.createDerivedList({
    hashes: ['a665a459...', 'b4c9a289...'],
    label: 'Partner audit Q1',
    expiresInHours: 720,
  });
  console.log(`List ID: ${dl.id}`);
  console.log(`List key (save now!): ${dl.list_key}`);

  // 2. Or create from tag filter
  const dl2 = await client.createDerivedList({
    tagFilter: { and: [{ key: 'department', value: 'hr' }] },
    label: 'HR confidential subset',
  });

  // 3. Third party: match files against the list
  // (can be done WITHOUT an API key — only needs list_key)
  const { CertiSigmaClient } = require('@certisigma/sdk');
  const { createHmac } = require('node:crypto');
  const pub = new CertiSigmaClient();

  const fileHash = 'a665a459...';
  const derived = createHmac('sha256', Buffer.from(dl.list_key, 'hex'))
    .update(fileHash).digest('hex');

  const result = await pub.matchDerivedList(dl.id, dl.list_key, [derived]);
  console.log(`Matched: ${result.matched}/${result.total}`);

  // 4. Verify list signature (public)
  const sig = await pub.getDerivedListSignature(dl.id);
  console.log(`Signed by: ${sig.signing_key_id}`);

  // 5. Owner: list, inspect, revoke
  const lists = await client.listDerivedLists();
  const detail = await client.getDerivedList(dl.id);
  const log = await client.getDerivedListAccessLog(dl.id);
  await client.revokeDerivedList(dl.id);
})();

(async function run() {
  const meta = await client.getMetadata('att_42');
  console.log(`Source: ${meta.source}, Extra: ${JSON.stringify(meta.extra_data)}`);
})();

(async function run() {
  // Verify a single hash
  const check = await client.verify('e3b0c44...');
  if (check.exists) {
    console.log(`Attested at ${check.timestamp}, Level: ${check.level}`);
  }

  // Verify from a saved manifest
  const manifest = JSON.parse(fs.readFileSync('contract.pdf.certisigma.json', 'utf8'));
  const check2 = await client.verify(manifest.hash);
  console.log(`Level: ${check2.level}`);

  // Batch verify (up to 100)
  const results = await client.batchVerify(['aabb...', 'ccdd...']);
  results.results.forEach(r => console.log(`${r.hash_hex}: ${r.exists}`));
})();

(async function run() {
  const { CertiSigmaClient, hashFile } = require('@certisigma/sdk');
  const fs = require('fs');

  // No apiKey needed — public verification
  const client = new CertiSigmaClient();

  const fileHash = await hashFile(fs.readFileSync('contract.pdf'));
  const check = await client.verify(fileHash);
  console.log(`Exists: ${check.exists}, Level: ${check.level}`);

  // Batch verify also works without a key
  const results = await client.batchVerify([fileHash]);
  console.log(`Found: ${results.found}/${results.count}`);
})();

const { RateLimitError } = require('@certisigma/sdk');

async function attestWithBackoff(client, hashHex, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.attest(hashHex);
    } catch (err) {
      if (err instanceof RateLimitError) {
        const wait = err.retryAfter * 1000 * (2 ** i);
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
  throw new Error('Max retries exceeded');
}

async function waitForT1(client, attId, timeoutMs = 600000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const s = await client.status(attId);
    if (s.level === 'T1' || s.level === 'T2') return s;
    await new Promise(r => setTimeout(r, 30000));
  }
  throw new Error('T1 not reached within timeout');
}

const { verifyWebhookSignature } = require('@certisigma/sdk');

const isValid = verifyWebhookSignature(rawBody, signatureHeader, signingSecret);
// Uses crypto.timingSafeEqual internally — timing-attack resistant

const seenDeliveries = new Set();  // In production, use Redis or a DB table
const MAX_AGE_MS = 300000;        // 5-minute anti-replay window

function handleWebhook(headers, body, rawBody) {
  const deliveryId = headers['x-certisigma-delivery'];
  if (seenDeliveries.has(deliveryId)) return 200;  // Idempotent ACK

  const age = Date.now() - new Date(body.created_at).getTime();
  if (age > MAX_AGE_MS) return 200;  // Stale — ACK to stop retries

  if (!verifyWebhookSignature(rawBody, headers['x-certisigma-signature'], secret))
    return 401;

  processEvent(body.attestation_id, headers['x-certisigma-event']);
  seenDeliveries.add(deliveryId);
  return 200;
}

const result = await client.registerWebhook(
  'https://my-server.com/census-hook',
  ['t1_complete', 't2_complete'],
  { label: 'census-watch-prod' },  // optional, for identification
);
// result.id             → "wh_abc123"
// result.signing_secret → "a1b2c3..." (shown once — store securely)
// result.label          → "census-watch-prod"

const result = await client.listWebhooks();
result.webhooks.forEach(wh => console.log(wh.id, wh.url, wh.label, wh.failure_count));

const result = await client.deleteWebhook('wh_abc123');
// result.deleted → true

const result = await client.listWebhookDeliveries('wh_abc123');
result.deliveries.forEach(d => console.log(d.event_type, d.status, d.response_code));

const { verifyWebhookSignature } = require('@certisigma/sdk');

// In your webhook handler (Express, Fastify, etc.):
const isValid = verifyWebhookSignature(
  req.rawBody,                              // Buffer
  req.headers['x-certisigma-signature'],    // "sha256={hex}"
  signingSecret,                            // from registerWebhook().signing_secret
);

(async function run() {
  const { CertiSigmaClient, getBlockchainUrl, saveOtsProof } = require('@certisigma/sdk');
  const fs = require('fs');

  const client = new CertiSigmaClient({ apiKey: process.env.CERTISIGMA_API_KEY });

  // Retrieve the full evidence bundle
  const evidence = await client.getEvidence('att_1234');
console.log(`Level: ${evidence.level}`);  // "T0", "T1", or "T2"

if (evidence.level === 'T2') {
  // Get the Bitcoin block explorer link
  const blockUrl = getBlockchainUrl(evidence);              // mempool.space/block/...
  const txUrl    = getBlockchainUrl(evidence, 'tx');      // mempool.space/tx/...
  console.log(`Block: ${blockUrl}`);
  console.log(`Tx:    ${txUrl}`);
  console.log(`Height: ${evidence.t2.bitcoinBlockHeight}`);

  // Save the raw .ots proof (for independent OTS verification)
  saveOtsProof(evidence, 'contract.pdf.ots');

  // Update your local manifest
  const manifest = JSON.parse(fs.readFileSync('contract.pdf.certisigma.json', 'utf8'));
  manifest.level = evidence.level;
  manifest.t2 = evidence.t2;
  fs.writeFileSync('contract.pdf.certisigma.json', JSON.stringify(manifest, null, 2));
}
})();

# Install the OpenTimestamps client
pip install opentimestamps-client

# Verify the proof against the Bitcoin blockchain
ots verify contract.pdf.ots

# Or verify online at https://opentimestamps.org

const { AuthenticationError, RateLimitError, QuotaExceededError } = require('@certisigma/sdk');

// Inside an async function
try {
  await client.attest(hash);
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited, retry after ${err.retryAfter}s`);
  } else if (err instanceof QuotaExceededError) {
    console.error('Monthly quota reached');
  }
}

{ "error": true, "code": "ERROR_CODE", "message": "Human-readable description", "details": null }

{ "error": true, "code": "RATE_LIMIT", "message": "Rate limit exceeded", "details": null }
// Headers: Retry-After: 12, X-RateLimit-Remaining: 0

{ "error": true, "code": "AUTH_ERROR", "message": "Invalid or missing API key", "details": null }

{ "error": true, "code": "VALIDATION_ERROR", "message": "hash_hex must be exactly 64 lowercase hex characters", "details": null }

{ "error": true, "code": "INTERNAL_ERROR", "message": "An internal error occurred", "details": null }

2.0.0|7fd9101e1dce01c87570d767b4b87a6e608250253c9d8c77fdd1b15731cf0aac|2026-02-28T00:33:19.291619+00:00

f5203ed4089a3bd3367f9301de43db93b574e92e1d597227c738d5338cd5ae01

{
  "kty": "EC", "crv": "P-256", "alg": "ES256",
  "kid": "certisigma-3cb3ab64f5cfc983",
  "x": "7AKMIyF5Rm3SfCASYsJsBHvZhF9cqtjEcmbu5DL8wA8",
  "y": "94l-xPf8HVkp03XELgIeDvsBDtWTL8tj7glvfjFU1Fk"
}

const crypto = require('crypto');

// Evidence fields
const hashHex    = '7fd9101e1dce01c87570d767b4b87a6e608250253c9d8c77fdd1b15731cf0aac';
const version    = '2.0.0';
const registered = '2026-02-28T00:33:19.291619+00:00';
const sigB64     = 'MEQCIGuKNpN1MERfn7jeJW4aRG2om7nIp2eRz/GHueM/Hi9qAiA2ik/6not2lJUWnYGpQ6x9xouOt8j8Cr42vBVSrSeN+Q==';

// Public key JWK
const jwk = {
  kty: 'EC', crv: 'P-256', alg: 'ES256',
  x: '7AKMIyF5Rm3SfCASYsJsBHvZhF9cqtjEcmbu5DL8wA8',
  y: '94l-xPf8HVkp03XELgIeDvsBDtWTL8tj7glvfjFU1Fk',
};

(async () => {
  // Import public key
  const key = await crypto.subtle.importKey(
    'jwk', jwk, { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify']
  );

  // Reconstruct canonical payload (WebCrypto hashes internally — do NOT pre-hash)
  const payload = new TextEncoder().encode(`${version}|${hashHex}|${registered}`);

  // DER → raw r||s (WebCrypto expects IEEE P1363, not DER)
  const derBuf = Buffer.from(sigB64, 'base64');
  const rLen = derBuf[3];
  const r = derBuf.subarray(4, 4 + rLen);
  const sStart = 4 + rLen + 2;
  const s = derBuf.subarray(sStart);
  const raw = Buffer.alloc(64);
  r.copy(raw, 32 - r.length);
  s.copy(raw, 64 - s.length);

  // Pass payload (not digest!) — WebCrypto computes SHA-256 internally
  const ok = await crypto.subtle.verify(
    { name: 'ECDSA', hash: 'SHA-256' }, key, raw, payload
  );
  console.log(ok ? '✅ T0 signature verified' : '❌ verification failed');
})();

Leaf: 7fd9101e1dce01c87570d767b4b87a6e608250253c9d8c77fdd1b15731cf0aac

Step 0: H(0x01 || 63792cf5...b8e026 || 7fd9101e...cf0aac) → 844370b7ddafe4f9...
Step 1: H(0x01 || 82950bd8...631955 || 844370b7...e4f9..) → 4529ddc8d19457a9...
Step 2: H(0x01 || 4529ddc8...57a9.. || a35f3d52...27f35e) → 1ccb4cfd5ea666d2...

Computed root: 1ccb4cfd5ea666d2f7418f104cebf200ef258b784dc483698335a084cf0f1d67 ✅

const crypto = require('crypto');

const leaf = '7fd9101e1dce01c87570d767b4b87a6e608250253c9d8c77fdd1b15731cf0aac';
const root = '1ccb4cfd5ea666d2f7418f104cebf200ef258b784dc483698335a084cf0f1d67';
const proof = [
  { hash: '63792cf512a74247fe1ac05e25494f40143fe0f6da9b1db855e9444035b8e026', position: 'left' },
  { hash: '82950bd8a3b929aaf12905e2457c91240c9f479a64888a1bd53fbdee23631955', position: 'left' },
  { hash: 'a35f3d526cbffff89d8099580271cb855109e84d357ed4cf31a46f7d0427f35e', position: 'right' },
];

let current = Buffer.from(leaf, 'hex');
for (const step of proof) {
  const sibling = Buffer.from(step.hash, 'hex');
  const prefix = Buffer.from([0x01]);
  current = step.position === 'left'
    ? crypto.createHash('sha256').update(Buffer.concat([prefix, sibling, current])).digest()
    : crypto.createHash('sha256').update(Buffer.concat([prefix, current, sibling])).digest();
}

console.log(current.toString('hex') === root
  ? '✅ Merkle inclusion verified'
  : '❌ Merkle proof failed');

const altered = new TextEncoder().encode(
  '2.0.0|7fd9101e1dce01c87570d767b4b87a6e608250253c9d8c77fdd1b15731cf0aac|2026-02-28T00:33:19.291620+00:00'
);
const bad = await crypto.subtle.verify(
  { name: 'ECDSA', hash: 'SHA-256' }, key, raw, altered
);
console.log(bad ? '❌ BUG: should have failed' : '✅ Correctly rejected altered timestamp');

const { CertiSigmaClient, RateLimitError, CertiSigmaError } = require('@certisigma/sdk');

async function resilientCall(fn, { retries = 3 } = {}) {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      const result = await fn();
      console.log(`OK attempt=${attempt + 1}`);
      return result;
    } catch (err) {
      if (err instanceof RateLimitError) {
        const wait = (err.retryAfter || 2 ** attempt) * 1000;
        console.warn(`429 retryAfter=${err.retryAfter} attempt=${attempt + 1}`);
        await new Promise(r => setTimeout(r, wait));
      } else if (err instanceof CertiSigmaError && err.statusCode >= 500 && attempt < retries - 1) {
        const wait = 2 ** attempt * 1000;
        console.warn(`5xx status=${err.statusCode} attempt=${attempt + 1}`);
        await new Promise(r => setTimeout(r, wait));
      } else {
        throw err;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

const client = new CertiSigmaClient({ apiKey: process.env.CERTISIGMA_API_KEY });
const result = await resilientCall(() => client.attest(hash, { source: 'pipeline' }));