@guardianchain/gc1

Official SDK for GC-1 governance evidence infrastructure.

Three lines to provable AI governance. Government-grade. Defense-ready. Enterprise-universal.

Installation

npm install @guardianchain/gc1

Zero dependencies. Uses only Node.js built-in crypto and fetch (Node 18+).

Quick Start

import { GuardianChain } from '@guardianchain/gc1';

const gc1 = new GuardianChain({ apiKey: process.env.GC1_API_KEY! });

const capsule = await gc1.seal({
  contentHash: gc1.hash('my governance decision data'),
});

console.log(capsule.data.capsule_id); // Permanent reference

Mode One: Seal Governance Evidence

Hash your governance data locally and seal it on-chain. Content never leaves your infrastructure.

const capsule = await gc1.seal({
  contentHash: gc1.hash(JSON.stringify(myGovernanceDecision)),
  anchorClass: 'INSTITUTIONAL_REGULATED',
  metadata: { kind: 'AI_GOVERNANCE', title: 'Credit Decision Governance' },
});

// Poll status
const status = await gc1.status(capsule.data.capsule_id);
console.log(status.data.lifecycle_state);    // 'SEALED'
console.log(status.data.confirmed_chains);   // ['base', 'polygon', ...]

Mode Two: Governance Checkpoint

Gate AI execution on a sealed governance verdict. The proof exists BEFORE the action.

const verdict = await gc1.checkpoint({
  actionClass: 'CREDIT_DECISION',
  verdict: 'PASS',
  ruleResults: [
    { ruleId: 'FAIR_LENDING_001', ruleName: 'Fair Lending Check', result: 'PASS' },
    { ruleId: 'CONFIDENCE_002', ruleName: 'Model Confidence', result: 'PASS', detail: '0.94 >= 0.90' },
  ],
  evaluatedAt: new Date().toISOString(),
});

// Verify the token before allowing execution
const auth = await gc1.verifyToken(verdict.data.authorization_token!);
if (!auth.valid) throw new Error('Governance checkpoint failed');

// Proceed with AI execution...

Silent Witness: Prove Absence

Prove that something did NOT happen in a given time window.

const absence = await gc1.silentWitness({
  contentHash: gc1.hash('event-that-should-not-exist'),
  from: '2026-01-01T00:00:00Z',
  to: '2026-03-22T00:00:00Z',
});

if (!absence.found) {
  console.log('Signed absence proof:', absence.absenceProof);
}

Evidence Weight Score

Quantified evidence strength (0-10) across multiple dimensions.

const weight = await gc1.evidenceWeight(capsuleId);
console.log(weight.score, weight.tier); // 7.5, 'VERIFIED'

Merkle Inclusion Proof

Retrieve the Merkle proof for independent blockchain verification.

const proof = await gc1.merkleProof(capsuleId);
console.log(proof.merkleRoot, proof.siblingHashes);

Local Verification (Offline)

Verify Ed25519 signatures and Merkle proofs with ZERO network connectivity. Designed for air-gapped environments, SCIFs, and classified networks.

import { LocalVerifier } from '@guardianchain/gc1';

const verifier = new LocalVerifier({
  publicKey: 'ed25519-public-key-hex-from-constitutional-status',
});

// Verify a signature (no network)
const sigResult = verifier.verifySignature(message, signature);

// Verify a Merkle proof (no network)
const proofResult = verifier.verifyMerkleProof(
  leafHash, siblingHashes, positions, expectedRoot
);

// Verify content integrity (no network)
const hashResult = verifier.verifyContentHash(content, claimedHash);

Configuration

const gc1 = new GuardianChain({
  apiKey: process.env.GC1_API_KEY!,            // Required
  baseUrl: 'https://gc-1-production.up.railway.app', // Default
  timeout: 30000,                               // 30 seconds
  retries: 3,                                   // Retry on 5xx
  publicKey: 'ed25519-hex-key',                 // For local verification
});

Error Handling

import { GC1AuthError, GC1RateLimitError, GC1ValidationError } from '@guardianchain/gc1';

try {
  await gc1.seal({ contentHash: gc1.hash(data) });
} catch (err) {
  if (err instanceof GC1AuthError) {
    // Invalid or missing API key
  } else if (err instanceof GC1RateLimitError) {
    // Rate limited — err.retryAfter has the wait time
  } else if (err instanceof GC1ValidationError) {
    // Invalid input — err.details has specifics
  }
}

API Reference

| Method | Auth | Description | |--------|------|-------------| | gc1.seal(request) | API Key | Mode One: seal governance evidence | | gc1.checkpoint(request) | API Key | Mode Two: governance checkpoint with token | | gc1.status(capsuleId) | API Key | Poll capsule lifecycle status | | gc1.verifyToken(token) | Public | Verify Mode Two authorization token | | gc1.verify(capsuleId) | Public | Full capsule verification with anchors | | gc1.evidenceWeight(capsuleId) | Public | Evidence Weight Score (0-10) | | gc1.merkleProof(capsuleId) | Public | Merkle inclusion proof | | gc1.silentWitness(request) | Public | Absence proof | | gc1.hash(data) | Local | SHA-256 hash | | gc1.hashObject(obj) | Local | Canonical JSON hash | | gc1.localVerifier(config) | Local | Offline verification instance | | gc1.qualityScores(params) | Public | VQS (0-100), MQS (0-100), Evidence Weight (0-10) | | gc1.classification(capsuleId) | Public | Auto-classification: tier, sensitivity, regulatory tags | | gc1.forwardVerify(capsuleId) | Public | Independent on-chain verification (no GC-1 trust required) | | gc1.capsuleGraph(capsuleId, opts) | Public | Relationship graph traversal (9 relationship types) | | gc1.governanceChain(directiveId) | Public | Complete directive-to-output governance chain | | gc1.agentTimeline(opts) | API Key | Agent session history with quality scores |

Security

• NON_CUSTODIAL: The SDK computes hashes locally. Content never leaves your infrastructure.
• Zero dependencies: Uses only Node.js built-in crypto and fetch.
• No secrets in logs: Error messages never contain API keys or content.
• Constant-time verification: Ed25519 signature verification uses constant-time comparison.
• FIPS 180-4 compliant: SHA-256 via Node.js crypto module.
• RFC 8032 compliant: Ed25519 via Node.js crypto module.

License

MIT — Copyright 2026 GuardianChain LLC