@sanna-ai/core

TypeScript SDK for the Sanna protocol — an open AI governance framework that enforces constitutional boundaries on AI agents through cryptographic receipts. Constitutions define what an agent can and cannot do; receipts provide tamper-evident proof that every action was evaluated against those rules.

Implements Sanna Protocol v1.1.

Install

npm install @sanna-ai/core

Requires Node.js 22+ (native Ed25519 support).

Quick Start

import {
  loadConstitution,
  verifyConstitutionSignature,
  loadPublicKey,
  loadPrivateKey,
  evaluateAuthority,
  generateReceipt,
  signReceipt,
  verifyReceipt,
} from "@sanna-ai/core";

// 1. Load and verify a constitution
const constitution = loadConstitution("constitution.yaml");
const authorKey = loadPublicKey("author.pub");
const valid = verifyConstitutionSignature(constitution, authorKey);

// 2. Evaluate an action against the constitution
const decision = evaluateAuthority(
  "database.write",
  { table: "users", operation: "delete" },
  constitution,
);
// decision.type → "can_execute" | "cannot_execute" | "must_escalate"

// 3. Generate a receipt
const receipt = generateReceipt({
  correlation_id: "req-001",
  inputs: { query: "Delete user 42", context: "admin panel" },
  outputs: { response: "User deleted" },
  checks: [
    { check_id: "auth-check", passed: true, severity: "critical", evidence: null },
  ],
});

// 4. Sign the receipt
const privKey = loadPrivateKey("author.key");
signReceipt(receipt as unknown as Record<string, unknown>, privKey, "[email protected]");

// 5. Verify a receipt
const result = verifyReceipt(receipt as unknown as Record<string, unknown>, authorKey);
// result.valid → true
// result.checks_performed → ["schema", "signature", "fingerprint", "content_hashes", ...]

API Reference

Hashing

• canonicalize(obj) — RFC 8785 JSON Canonicalization Scheme
• hashBytes(data) — SHA-256 of raw bytes (hex string)
• hashContent(data, truncate?) — SHA-256 with NFC + line-ending normalization
• hashObj(obj) — canonicalize then SHA-256
• EMPTY_HASH — SHA-256 of empty input

Crypto

• generateKeypair(label?) — generate Ed25519 keypair
• sign(data, privateKey) — Ed25519 sign, returns base64
• verify(data, signature, publicKey) — Ed25519 verify
• loadPrivateKey(path) — load PKCS#8 PEM private key
• loadPublicKey(path) — load SPKI PEM public key
• getKeyId(key) — SHA-256 of raw 32-byte Ed25519 public key
• exportPrivateKeyPem(key) — export private key as PEM string
• exportPublicKeyPem(key) — export public key as PEM string

Constitution

• loadConstitution(path) — load and parse YAML constitution
• parseConstitution(data) — parse raw object to typed Constitution
• validateConstitutionData(data) — validate structure, returns error list
• verifyConstitutionSignature(constitution, publicKey) — verify Ed25519 signature
• computeFileContentHash(path) — SHA-256 content hash of a file

Authority Evaluator

• evaluateAuthority(action, params, constitution) — 4-tier policy cascade evaluation
• normalizeAuthorityName(name) — normalize action name per Appendix D

Receipt

• generateReceipt(params) — create a complete receipt with hashes and fingerprints
• signReceipt(receipt, privateKey, signedBy) — Ed25519 sign a receipt
• computeFingerprints(receipt) — compute 16-hex and 64-hex fingerprints
• computeFingerprintInput(receipt) — compute the 14-field pipe-delimited input
• SPEC_VERSION — protocol version ("1.1")
• CHECKS_VERSION — checks schema version ("6")

Verifier

• verifyReceipt(receipt, publicKey?) — verify schema, signature, fingerprint, content hashes, status consistency, and timestamp

Types

Constitution, Boundary, HaltCondition, TrustTiers, TrustedSources, ConstitutionSignature, Provenance, AgentIdentity, Invariant, EscalationTargetConfig, EscalationRule, AuthorityBoundaries, AuthorityDecision, AuthorityDecisionType, BoundaryType, Receipt, CheckResult, ReceiptSignature, Enforcement, ConstitutionRef, VerificationResult, SannaKeypair, KeyObject, ReceiptParams

Cross-Language Compatibility

All hashing, fingerprinting, and signing operations are verified against golden fixtures from the Sanna protocol spec. Receipts generated by the Python SDK verify correctly with this TypeScript SDK, and vice versa.

Related

• sanna-ai/sanna-protocol — Protocol specification, schemas, and test fixtures
• sanna-ai/sanna — Python reference implementation

License

AGPL-3.0 — see LICENSE.