The canonical trust anchor for GuardSpine evidence bundles.

Offline evidence-bundle verification and sealing. Zero runtime dependencies.

This is the single source of truth for hash chain computation and bundle verification in the GuardSpine ecosystem. All other implementations (Python, Go, etc.) MUST produce byte-identical output to this library.

Bundle Format: v0.2.0 / v0.2.1

All bundles sealed by this library use the v0.2.0 immutability proof format:

• Chain entries link via previous_hash -> prior chain_hash (not content_hash)
• Version enforcement: bundles must declare version: "0.2.0" or "0.2.1"
• v0.2.1 adds optional sanitization metadata (PII/secret redaction attestation); the proof format is unchanged from v0.2.0
• Golden vectors in tests/fixtures/ validate cross-implementation parity
• Legacy proof format (pre-v0.2.0, 3-field chain hash) is deprecated with a console.warn

npm install @guardspine/kernel

import { sealBundle } from "@guardspine/kernel";

const { items, immutabilityProof } = sealBundle({
  items: [
    { item_id: "item-1", content_type: "guardspine/test-result", content: { passed: true, name: "auth-check" } },
    { item_id: "item-2", content_type: "guardspine/lint-result", content: { errors: 0 } },
  ],
});

const bundle = {
  bundle_id: crypto.randomUUID(),
  version: "0.2.0",
  created_at: new Date().toISOString(),
  items,
  immutability_proof: immutabilityProof,
};

import { verifyBundle } from "@guardspine/kernel";

const result = verifyBundle(bundle);

if (result.valid) {
  console.log("Bundle integrity verified.");
} else {
  for (const err of result.errors) {
    console.error(`[${err.code}] ${err.message}`);
  }
}

import { computeContentHash } from "@guardspine/kernel";

const hash = computeContentHash({ foo: "bar" });
// => "sha256:..."

import { canonicalJson } from "@guardspine/kernel";

canonicalJson({ z: 1, a: 2 });
// => '{"a":2,"z":1}'

• Node.js 18+ (uses node:crypto)
• TypeScript 5.4+

The kernel includes several defensive measures added during security audit:

• HMAC buffer length guard: timingSafeEqual throws on mismatched buffer lengths. The HMAC verification path checks length equality before calling timingSafeEqual, returning false on mismatch instead of crashing.
• Incremental root hash: computeRootHash uses streaming createHash('sha256').update() instead of string concatenation, avoiding memory pressure on large chains.
• Max chain items: buildHashChain rejects inputs exceeding 10,000 items.
• Input validation: sealBundle validates that each item has item_id and content_type before processing.
• Constant-time comparison: All hash comparisons use a safeEqual() wrapper over timingSafeEqual to prevent timing side-channels.

verifyBundle checks optional signatures[] on the bundle:

Pass public keys via options.publicKeys (a map of key_id -> PEM/base64) and HMAC secrets via options.hmacSecret.

The tests/fixtures/ directory contains golden vector bundles that ALL implementations must verify identically. Do not modify these fixtures.

This TypeScript library is the canonical reference implementation. All other language ports MUST produce byte-identical hashes.

Cross-language guarantee: Both implementations use RFC 8785 canonical JSON serialization and produce identical SHA256 hashes for the same input. Golden vector tests in guardspine-spec validate parity.

Apache-2.0