cap-tree-core

Reference implementation of the CAP-Tree v0.3 data model: JCS canonicalization, content addressing, Ed25519 signature envelopes, structural validation, and the normative verification algorithms (spec § 6).

• Zero runtime dependencies. WebCrypto only — the same code runs in Node ≥ 20 and modern browsers.
• Vector-pinned. The test suite reproduces every committed test vector byte-for-byte and rejects tampered variants.
• Courier-agnostic. Verification takes a Resolver you supply; every fetched payload is checked against the reference hash before it is believed.

Install

npm install cap-tree-core   # (not yet published — use the workspace path for now)

Usage

import {
  generateKeyPair, signEnvelope, verifyObject,
  verifyRootChain, verifyMerge, verifyRefs, objectHash,
} from 'cap-tree-core';

// Identity is a keypair; the fingerprint is who you are.
const me = await generateKeyPair();

// Every object is signed into a self-contained envelope.
const genesis = await signEnvelope({
  type: 'tree-root', specVersion: 3,
  ownerFingerprint: me.fingerprint,
  adminFingerprints: [], entries: [], parents: [],
  policy: null, approvals: [],
  message: 'genesis', timestamp: new Date().toISOString(),
}, me.privateJwk, me.publicJwk);

const treeId = await objectHash(genesis.payload); // the repo's name, forever

// Verify a chain fetched from an untrusted courier:
const resolve = async (ref) => myStore.get(ref.hash) ?? null;
const verdict = await verifyRootChain(tipEnvelope, treeId, resolve);
if (!verdict.ok) console.error(verdict.errors);

// Evaluate a merge against the policy its target branch declares:
const merge = await verifyMerge(mergeEnvelope, treeId, resolve);
merge.policySatisfied; // render the green badge — or don't

// Detect refs equivocation (silent force-push):
const refs = await verifyRefs(refsEnvelope, { treeId, resolve, previous: lastSeen });
refs.equivocation; // true = the owner or courier is lying about history

API surface

| Module | Exports | |---|---| | encoding | canonicalize, canonicalBytes, toBase64url, fromBase64url | | crypto | objectHash, blobHash, sha256, fingerprint, generateKeyPair, signEnvelope, verifyEnvelope | | objects | validateObject, validatePathSegment, all object types | | verify | verifyObject (§ 6.1), verifyRootChain (§ 6.2), verifyMerge (§ 6.3), verifyRefs (§ 6.4) |

Test

npm test   # builds, then runs the vector + verification suites

MIT