git-cas

Modern open-source systems still rely on centralized infrastructure to distribute binary artifacts, even when their source code is fully decentralized. This creates a fragile dependency: if hosting endpoints are blocked, degraded, or removed, critical artifacts become unavailable or unverifiable.

git-cas addresses this by making artifact distribution inherit Git’s existing replication model, allowing binaries to be stored, verified, and transported anywhere Git can operate, including mirrored networks, constrained environments, or fully offline contexts.

git-cas 6.0.0 is an industrial-grade Content-Addressable Storage (CAS) engine backed by Git’s object database. Its Security First posture makes explicit restore boundaries, bounded metadata reads, authenticated encryption, and legacy-scheme rejection the default. Stored content is chunked, deduplicated, and optionally encrypted — keeping high-fidelity assets and security-sensitive files directly within your repository history.

git-cas is designed for the architect who demands mathematical certainty and the operator who needs a stable foundation for artifact storage. It scales from simple binary blob management to multi-recipient envelope-encrypted vaults with key rotation, privacy-mode slug hashing, and Merkle-style manifests for assets of any size.

Why git-cas?

Unlike traditional LFS which moves files to external servers, git-cas treats the Git object database as a first-class storage substrate.

• Deduplication by Default: Content-defined chunking (CDC) with Buzhash rolling hash identifies repeated patterns across files and versions, minimizing repository growth.
• Cryptographic Trust: Every chunk is verified against a SHA-256 digest. Optional AES-256-GCM encryption with multi-recipient envelope support ensures privacy at rest, and framed binds per-frame AAD to prevent cross-manifest blob swaps.
• GC-Safe Vault: Named assets are indexed through a stable ref (refs/cas/vault) with optimistic concurrency, preventing Git garbage collection from reclaiming referenced blobs.
• Key Lifecycle: Envelope encryption separates DEKs from KEKs. Rotate passphrases across an entire vault without re-encrypting data blobs. Privacy mode HMAC-hashes slug names to prevent metadata discovery.
• Runtime-Adaptive: A single core supports Node.js 22+, Bun, and Deno through a strict hexagonal port architecture with runtime-specific crypto adapters.

Quick Start

Existing v5 users should read UPGRADING.md and run npm run upgrade in dry-run mode before restoring old encrypted vault entries. For the release overview, see the v6.0.0 Release Notes.

1. CLI Usage

Initialize a vault and store your first asset.

git init
git-cas vault init
git-cas store data.bin --slug assets/v1 --tree
git-cas restore --slug assets/v1 --out data-restored.bin

2. TUI Cockpit

Navigate your stored assets through the reader-first interactive dashboard.

git-cas vault dashboard

3. Library Ingress

Integrate managed blob storage directly into your TypeScript or JavaScript application.

import ContentAddressableStore from '@git-stunts/git-cas';
const cas = await ContentAddressableStore.open({ cwd: '.' });
const manifest = await cas.storeFile({ filePath: './asset.bin', slug: 'app/asset' });

Capability Map

The README is the front door. Detailed mechanics live in the guide set:

Need	Start Here
Productive library and CLI workflows	Developer Guide
Restore memory behavior	Streaming and restore matrix
Encryption scheme selection	Encryption Modes
CDC internals, Merkle manifests, KDF policy, and tuning	Advanced Guide
Ports, adapters, and collaborator boundaries	Architecture
v5 to v6 migration	Upgrading

Core capabilities:

• Content-addressed storage: chunks are addressed by SHA-256 digest and integrity-verified on read.
• Deduplication: fixed chunking and content-defined chunking (CDC) support predictable or shift-resistant chunk boundaries.
• Encryption: AES-256-GCM with authenticated metadata. whole and framed use fresh random 96-bit nonces; convergent derives per-chunk keys and nonces deterministically from the plaintext content hash to preserve deduplication.
• Vault indexing: named assets live under refs/cas/vault so Git garbage collection does not reclaim referenced blobs.
• Envelope recipients: multi-recipient key wrapping and recipient rotation avoid re-encrypting data blobs.
• Operational diagnostics: git-cas doctor validates vault health and reports deduplication efficiency.

Safety Snapshot

The v6 line is Security First by default:

• restoreFile() requires baseDirectory and refuses output paths that escape it.
• Manifest and sub-manifest blob reads default to a 10 MiB maxBlobSize safety limit.
• Legacy encryption scheme identifiers throw LEGACY_SCHEME with migration guidance.
• KDF parameters, salts, frame sizes, restore buffers, and concurrency are policy-bounded.
• Recipient trial decryption and vault verifier checks use constant-time comparisons.

For the full hardening table, see Advanced Guide: Security Hardening Summary.

Runtime Support

Runtime	Version	Crypto Backend	Status
Node.js	22+	node:crypto	Primary — full streaming support
Bun	Latest	node:crypto compat	Tested via Docker
Deno	Latest	Web Crypto API	Tested via Docker; whole decrypt is bounded-buffer

All three runtimes are tested in CI on every push. The hexagonal architecture isolates runtime differences behind the CryptoPort boundary, so the domain core is runtime-agnostic.

Documentation

• Guide: Productive path, library/CLI usage, vault workflows, and the feature coverage map.
• Advanced Guide: CDC internals, direct service contracts, security limits, operational tooling, and performance baselines.
• Architecture: The authoritative system map — Facade, Domain, Ports, and Adapters.
• Extending: Custom adapter contracts and extension-point checklist.
• Store/Restore Pipeline: Maintainer state machines for byte storage, restore, tree publication, and vault boundaries.
• Vault Internals: Maintainer map for vault persistence, caching, codecs, privacy indexing, key verification, and retry policy.
• Security: Threat models, trust boundaries, and encryption internals.
• Agent API: JSONL agent protocol for CI/CD automation.
• Workflow: Repo work doctrine, cycles, and invariants.
• Contributing, Code of Conduct, and Support: Project participation and help paths.
• v6.0.0 Release Notes: Major-release summary, upgrade call-to-action, and publication notes.
• Upgrading: Migration guide for v5 → v6.
• Changelog: Version history and migration notes.

---

Built with terminal ambition by FLYING ROBOTS