npm package: @guardianchain-llc/gc1
Description: Official SDK for GC-1 governance evidence infrastructure. Three lines to provable AI governance.
Author: GuardianChain LLC
Latest version: 1.0.0

# @guardianchain/gc1

**Official SDK for GC-1 governance evidence infrastructure.**

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

## Installation

```bash
npm install @guardianchain/gc1
```

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

## Quick Start

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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

```typescript
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

```typescript
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