@git-stunts/git-cas

中文文档
7.2.0发布于 2026/11/07Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 9132

Content-addressed storage backed by Git's object database, with optional encryption and pluggable codecs

原始使用文档
文档目录9 节
  1. Why git-cas?
  2. Quick Start
  3. 1. CLI Usage
  4. 2. TUI Cockpit
  5. 3. Library Ingress
  6. Capability Map
  7. Safety Snapshot
  8. Runtime Support
  9. Documentation

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

npm version License

git-cas demo

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.
  • Mutable Root Sets: Cache and derived-state trees can be anchored under refs/cas/rootsets/* while live, then become collectible after eviction, without vault history retaining every prior generation.
  • Managed Cache Sets: Applications can store handles under refs/cas/caches/* with TTL, entry and logical-byte limits, approximate LRU eviction, immutable retention evidence, bounded inspection, repair, and scoped acquisitions that keep a selected generation reachable during use. Cache indexes and object reachability remain git-cas responsibilities.
  • Expiry-Safe Replay Sets: Security-sensitive markers can live under refs/cas/expiring/* with atomic add-if-absent, digest-only metadata, and expiry-only release. Live markers have no remove, repair, capacity, or LRU path that could shorten their acceptance window.
  • Opaque Application Handles: Applications stage assets, immutable pages, and deterministic structured bundles through validated handles, then retain or publish them with generation-scoped evidence instead of managing Git objects, trees, or payload OIDs directly.
  • Bounded Git Process Reuse: Immutable object metadata and tree reads reuse typed Git sessions behind the adapter. On session-capable adapters, streaming blob reads at or below a fixed 10 MiB ceiling use one bounded session read; larger payloads retain the genuine one-shot streaming path. Explicitly bounded page, asset, and ordered-bundle batches pipeline independent Git writes. workspace.batch() can compose dependent asset, page, and bundle waves in one private persistence scope and either retain their union or an explicitly selected set of newly staged terminal roots under one exact final generation without changing content identity.
  • 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. The published v7.0.0 release changes the public schema dependency to Zod 4. Before upgrading, read the migration guidance and release notes. This release requires published Plumbing 3.3.3. Release and registry evidence records its publication.

Published v7.1.0 adds durable reservations: hard record-slot admission before an application effect, pinned evidence and bounded recovery/inspection. See the release notes and publication and fresh registry-consumer evidence. The signed tag, npm gitHead and successful release workflow agree on 18f87dd.

The v7.2.0 release candidate path-compresses the reservation index, so a ledger update writes about log16(records) trees instead of 64. A 7.1.0 index still reads and updates, but 7.1.0 refuses an index 7.2.0 has written; see the release notes and #169.

The published v6.5.12 release bounds object-metadata requests so root sets with more than 1000 targets (936 for SHA-256) validate within Plumbing's cat-file request limits. Admission still rejects missing and mismatched targets before publication; see v6.5.12 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

The framed cockpit keeps Explorer, Atlas, and Operations in one shared session. Use / to search assets, Ctrl+P for the command palette, ? for keyboard help, F2 for session settings, and q for a confirmed exit. Noninteractive invocations retain the plain tab-separated listing.

3. Library Ingress

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

import { createReadStream } from 'node:fs';
import ContentAddressableStore from '@git-stunts/git-cas';

const cas = await ContentAddressableStore.open({ cwd: '.' });
const staged = await cas.assets.put({
  source: createReadStream('./asset.bin'),
  slug: 'app/asset',
  filename: 'asset.bin',
});
const retained = await cas.retention.retain({
  handle: staged.handle,
  root: { ref: 'refs/cas/rootsets/my-app', name: 'app/asset' },
  policy: 'pinned',
});
await cas.close();

staged.handle is a content locator, not a durability promise. The returned retention witness identifies the exact Git generation and tree edge that made the asset reachable. close() releases local resources only; it never deletes objects, updates refs, or changes retention.

Capability Map

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

NeedStart Here
Productive library and CLI workflowsDeveloper Guide
Restore memory behaviorStreaming and restore matrix
Encryption scheme selectionEncryption Modes
CDC internals, Merkle manifests, KDF policy, and tuningAdvanced Guide
Ports, adapters, and collaborator boundariesArchitecture
Assets, pages, bundles, retention, and publicationApplication storage
Temporary retention during multi-step compositionScoped staging workspaces
GC retention for caches and derived stateRoot Sets
Managed TTL and capacity cachesCache Sets
Scoped protection while consuming a cache hitCache acquisitions
Durable replay markers with expiry-only releaseExpiring Sets
Repository reachability and git-cas usage evidenceRepository Diagnostics
v5 to v6 migrationUpgrading

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.
  • Root-set retention: current cache entries live under caller-owned refs/cas/rootsets/* refs. Entries are Git-reachable while present, and old set generations are not retained as commit history.
  • Managed cache lifecycle: caches.open() owns immutable cache indexes, compare-and-swap replacement, expiry, capacity eviction, retention witnesses, diagnostics, and repair. Reads do not write access metadata; callers opt into coalesced access updates with touch().
  • Scoped cache acquisitions: cache.acquire() performs a reference-only lookup and atomically anchors the selected cache generation for the caller's explicit lifetime. release() is idempotent, while inspection and checked cleanup make abandoned acquisition refs observable and recoverable.
  • Expiry-safe replay lifecycle: expiringSets.open() atomically retains digest-only replay markers through their declared window. contains() is read-only, and sweep() can release only markers whose expiry has passed.
  • Application storage: assets, pages, bundles, retention, and publications compose streaming CAS writes, bounded structured materializations, explicitly bounded asset/page/bundle batches, direct-reference or complete-validation member reads, reachability roots, compare-and-swap refs, and immutable lifecycle evidence.
  • Scoped staging workspaces: workspaces.open() mirrors application writes behind one renewable temporary RootSet, supports one-generation bounded asset/page/bundle batches plus compound dependent asset/page/bundle admission with exact newly staged terminal-root selection, returns only after each public result is anchored, promotes destination-first, and exposes bounded age, expiry, logical-content, and direct-root diagnostics with opaque cleanup pagination.
  • Envelope recipients: multi-recipient key wrapping and recipient rotation avoid re-encrypting data blobs.
  • Operational diagnostics: cas.diagnostics.doctor() streams repository object/ref evidence, classifies anchored, orphaned, and volatile objects, and summarizes workspaces, cache acquisitions, CacheSet, RootSet, ExpiringSet, and Vault usage without mutating Git. The git-cas doctor CLI continues to validate vault health.

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

RuntimeVersionCrypto BackendStatus
Node.js22+node:cryptoPrimary — full streaming support
BunLatestnode:crypto compatTested via Docker
DenoLatestWeb Crypto APITested 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.
  • v6.1.0 Release Notes: Root-set retention, doctor/repair, and GC-policy guidance.
  • v6.2.0 Release Notes: Opaque application storage, managed cache and replay lifecycles, retention evidence, and repository diagnostics.
  • v6.3.0 Release Notes: Lifetime-safe, reference-only cache acquisitions with explicit release and doctor evidence.
  • v6.4.0 Release Notes: Scoped staging workspaces for temporary multi-object reachability, promotion, and cleanup.
  • v6.5.0 Release Notes: Bounded direct bundle references, immutable metadata reuse, and corrected concurrency settlement.
  • v6.5.1 Release Notes: Bounded immutable page payload reuse with zero-command warm reads.
  • v6.5.2 Release Notes: Persistent bounded Git object sessions, scoped page batches, and deterministic resource closure.
  • v6.5.3 Release Notes: Coherent reuse of persistent Git object sessions across compatible immutable writes.
  • v6.5.4 Release Notes: Ordered page batches retained under one exact staging-workspace generation.
  • v6.5.5 Release Notes: Self-contained identity for git-cas-owned commits in unconfigured bare repositories.
  • v6.5.6 Release Notes: Bijou 7 hosted cockpit ownership and deterministic checked-ref conflict classification.
  • v6.5.7 Release Notes: Bounded persistent sessions for small streaming blob reads while large payloads remain streamed.
  • v6.5.8 Release Notes: Bounded application write waves, one-generation workspace batches, and reusable ref sessions.
  • v6.5.9 Release Notes: Compound dependent write waves retained under one exact staging-workspace generation.
  • v6.5.10 Release Notes: Compound asset, page, and bundle admission with exact selected terminal roots.
  • Upgrading: Migration guide for v5 → v6.
  • Changelog: Version history and migration notes.

Built with terminal ambition by FLYING ROBOTS

版本与发布记录

@git-stunts/git-cas 共发布 35 个版本,首次发布于 2026/02/07;过去 12 个月发布了 35 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
7.2.0latest2026/11/079 天前
7.1.02026/11/0313 天前
7.0.02026/11/0214 天前
6.5.122026/10/2027 天前
6.5.112026/10/021 个月前
6.5.102026/08/252 个月前

关于 @git-stunts/git-cas 的常见问题

@git-stunts/git-cas 是什么?

Content-addressed storage backed by Git's object database, with optional encryption and pluggable codecs

如何安装 @git-stunts/git-cas?

在项目目录运行 npm install @git-stunts/git-cas,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 git-cas,可以用 npx git-cas 直接运行。

@git-stunts/git-cas 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@git-stunts/git-cas 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@git-stunts/git-cas 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@git-stunts/git-cas 可以商用吗?

@git-stunts/git-cas 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@git-stunts/git-cas 的下载量有多少?

根据 npm 官方下载统计,@git-stunts/git-cas 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,132 次,日均约 304 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@git-stunts/git-cas 还在维护吗?

最新版本 7.2.0 发布于 2026/11/07(9 天前);至今共发布 35 个版本,其中过去 12 个月发布了 35 个;首次发布于 2026/02/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。