@git-stunts/git-cas 1.6.0

package/index.js

@@ -0,0 +1,290 @@
+/**
+ * @fileoverview Content Addressable Store - Managed blob storage in Git.
+ */
+
+import { createReadStream, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import CasService from './src/domain/services/CasService.js';
+import GitPersistenceAdapter from './src/infrastructure/adapters/GitPersistenceAdapter.js';
+import NodeCryptoAdapter from './src/infrastructure/adapters/NodeCryptoAdapter.js';
+import Manifest from './src/domain/value-objects/Manifest.js';
+import Chunk from './src/domain/value-objects/Chunk.js';
+import CryptoPort from './src/ports/CryptoPort.js';
+import JsonCodec from './src/infrastructure/codecs/JsonCodec.js';
+import CborCodec from './src/infrastructure/codecs/CborCodec.js';
+
+export {
+  CasService,
+  GitPersistenceAdapter,
+  NodeCryptoAdapter,
+  CryptoPort,
+  Manifest,
+  Chunk,
+  JsonCodec,
+  CborCodec
+};
+
+/**
+ * Detects the best crypto adapter for the current runtime.
+ * @returns {Promise<import('./src/ports/CryptoPort.js').default>} A runtime-appropriate CryptoPort implementation.
+ */
+async function getDefaultCryptoAdapter() {
+  if (globalThis.Bun) {
+    const { default: BunCryptoAdapter } = await import('./src/infrastructure/adapters/BunCryptoAdapter.js');
+    return new BunCryptoAdapter();
+  }
+  if (globalThis.Deno) {
+    const { default: WebCryptoAdapter } = await import('./src/infrastructure/adapters/WebCryptoAdapter.js');
+    return new WebCryptoAdapter();
+  }
+  return new NodeCryptoAdapter();
+}
+
+/**
+ * High-level facade for the Content Addressable Store library.
+ *
+ * Wraps {@link CasService} with lazy initialization, runtime-adaptive crypto
+ * selection, and convenience helpers for file I/O.
+ */
+export default class ContentAddressableStore {
+  /**
+   * @param {Object} options
+   * @param {import('@git-stunts/plumbing').default} options.plumbing - GitPlumbing instance for Git operations.
+   * @param {number} [options.chunkSize] - Chunk size in bytes (default 256 KiB).
+   * @param {import('./src/ports/CodecPort.js').default} [options.codec] - Manifest codec (default JsonCodec).
+   * @param {import('./src/ports/CryptoPort.js').default} [options.crypto] - Crypto adapter (auto-detected if omitted).
+   * @param {import('@git-stunts/alfred').Policy} [options.policy] - Resilience policy for Git I/O.
+   */
+  constructor({ plumbing, chunkSize, codec, policy, crypto }) {
+    this.plumbing = plumbing;
+    this.chunkSizeConfig = chunkSize;
+    this.codecConfig = codec;
+    this.policyConfig = policy;
+    this.cryptoConfig = crypto;
+    this.service = null;
+    this.#servicePromise = null;
+  }
+
+  #servicePromise = null;
+
+  /**
+   * Lazily initializes the service, handling async adapter discovery.
+   * @private
+   * @returns {Promise<CasService>}
+   */
+  async #getService() {
+    if (!this.#servicePromise) {
+      this.#servicePromise = this.#initService();
+    }
+    return await this.#servicePromise;
+  }
+
+  /**
+   * Constructs the persistence adapter, resolves crypto, and creates the CasService.
+   * @private
+   * @returns {Promise<CasService>}
+   */
+  async #initService() {
+    const persistence = new GitPersistenceAdapter({
+      plumbing: this.plumbing,
+      policy: this.policyConfig
+    });
+    const crypto = this.cryptoConfig || await getDefaultCryptoAdapter();
+    this.service = new CasService({
+      persistence,
+      chunkSize: this.chunkSizeConfig,
+      codec: this.codecConfig || new JsonCodec(),
+      crypto,
+    });
+    return this.service;
+  }
+
+  /**
+   * Lazily initializes and returns the underlying {@link CasService}.
+   * @returns {Promise<CasService>}
+   */
+  async getService() {
+    return await this.#getService();
+  }
+
+  /**
+   * Factory to create a CAS with JSON codec.
+   * @param {Object} options
+   * @param {import('@git-stunts/plumbing').default} options.plumbing - GitPlumbing instance.
+   * @param {number} [options.chunkSize] - Chunk size in bytes.
+   * @param {import('@git-stunts/alfred').Policy} [options.policy] - Resilience policy.
+   * @returns {ContentAddressableStore}
+   */
+  static createJson({ plumbing, chunkSize, policy }) {
+    return new ContentAddressableStore({ plumbing, chunkSize, codec: new JsonCodec(), policy });
+  }
+
+  /**
+   * Factory to create a CAS with CBOR codec.
+   * @param {Object} options
+   * @param {import('@git-stunts/plumbing').default} options.plumbing - GitPlumbing instance.
+   * @param {number} [options.chunkSize] - Chunk size in bytes.
+   * @param {import('@git-stunts/alfred').Policy} [options.policy] - Resilience policy.
+   * @returns {ContentAddressableStore}
+   */
+  static createCbor({ plumbing, chunkSize, policy }) {
+    return new ContentAddressableStore({ plumbing, chunkSize, codec: new CborCodec(), policy });
+  }
+
+  /**
+   * Returns the configured chunk size in bytes.
+   * @returns {number}
+   */
+  get chunkSize() {
+    return this.service?.chunkSize || this.chunkSizeConfig || 256 * 1024;
+  }
+
+  /**
+   * Encrypts a buffer using AES-256-GCM.
+   * @param {Object} options
+   * @param {Buffer} options.buffer - Plaintext data to encrypt.
+   * @param {Buffer} options.key - 32-byte encryption key.
+   * @returns {Promise<{ buf: Buffer, meta: { algorithm: string, nonce: string, tag: string, encrypted: boolean } }>}
+   */
+  async encrypt(options) {
+    const service = await this.#getService();
+    return await service.encrypt(options);
+  }
+
+  /**
+   * Decrypts a buffer. Returns it unchanged if `meta.encrypted` is falsy.
+   * @param {Object} options
+   * @param {Buffer} options.buffer - Ciphertext to decrypt.
+   * @param {Buffer} options.key - 32-byte encryption key.
+   * @param {{ encrypted: boolean, algorithm: string, nonce: string, tag: string }} options.meta - Encryption metadata.
+   * @returns {Promise<Buffer>}
+   */
+  async decrypt(options) {
+    const service = await this.#getService();
+    return await service.decrypt(options);
+  }
+
+  /**
+   * Reads a file from disk and stores it in Git as chunked blobs.
+   *
+   * Convenience wrapper that opens a read stream and delegates to
+   * {@link CasService#store}.
+   *
+   * @param {Object} options
+   * @param {string} options.filePath - Absolute or relative path to the file.
+   * @param {string} options.slug - Logical identifier for the stored asset.
+   * @param {string} [options.filename] - Override filename (defaults to basename of filePath).
+   * @param {Buffer} [options.encryptionKey] - 32-byte key for AES-256-GCM encryption.
+   * @returns {Promise<import('./src/domain/value-objects/Manifest.js').default>} The resulting manifest.
+   */
+  async storeFile({ filePath, slug, filename, encryptionKey }) {
+    const source = createReadStream(filePath);
+    const service = await this.#getService();
+    return await service.store({
+      source,
+      slug,
+      filename: filename || path.basename(filePath),
+      encryptionKey,
+    });
+  }
+
+  /**
+   * Stores an async iterable source in Git as chunked blobs.
+   * @param {Object} options
+   * @param {AsyncIterable<Buffer>} options.source - Data to store.
+   * @param {string} options.slug - Logical identifier for the stored asset.
+   * @param {string} options.filename - Filename for the manifest.
+   * @param {Buffer} [options.encryptionKey] - 32-byte key for AES-256-GCM encryption.
+   * @returns {Promise<import('./src/domain/value-objects/Manifest.js').default>} The resulting manifest.
+   */
+  async store(options) {
+    const service = await this.#getService();
+    return await service.store(options);
+  }
+
+  /**
+   * Restores a file from its manifest and writes it to disk.
+   * @param {Object} options
+   * @param {import('./src/domain/value-objects/Manifest.js').default} options.manifest - The file manifest.
+   * @param {Buffer} [options.encryptionKey] - 32-byte key, required if manifest is encrypted.
+   * @param {string} options.outputPath - Destination file path.
+   * @returns {Promise<{ bytesWritten: number }>}
+   */
+  async restoreFile({ manifest, encryptionKey, outputPath }) {
+    const service = await this.#getService();
+    const { buffer, bytesWritten } = await service.restore({
+      manifest,
+      encryptionKey,
+    });
+    writeFileSync(outputPath, buffer);
+    return { bytesWritten };
+  }
+
+  /**
+   * Restores a file from its manifest, returning the buffer directly.
+   * @param {Object} options
+   * @param {import('./src/domain/value-objects/Manifest.js').default} options.manifest - The file manifest.
+   * @param {Buffer} [options.encryptionKey] - 32-byte key, required if manifest is encrypted.
+   * @returns {Promise<{ buffer: Buffer, bytesWritten: number }>}
+   */
+  async restore(options) {
+    const service = await this.#getService();
+    return await service.restore(options);
+  }
+
+  /**
+   * Creates a Git tree object from a manifest.
+   * @param {Object} options
+   * @param {import('./src/domain/value-objects/Manifest.js').default} options.manifest - The file manifest.
+   * @returns {Promise<string>} Git OID of the created tree.
+   */
+  async createTree(options) {
+    const service = await this.#getService();
+    return await service.createTree(options);
+  }
+
+  /**
+   * Verifies the integrity of a stored file by re-hashing its chunks.
+   * @param {import('./src/domain/value-objects/Manifest.js').default} manifest - The file manifest.
+   * @returns {Promise<boolean>} `true` if all chunks pass verification.
+   */
+  async verifyIntegrity(manifest) {
+    const service = await this.#getService();
+    return await service.verifyIntegrity(manifest);
+  }
+
+  /**
+   * Reads a manifest from a Git tree OID.
+   * @param {Object} options
+   * @param {string} options.treeOid - Git tree OID to read the manifest from.
+   * @returns {Promise<import('./src/domain/value-objects/Manifest.js').default>}
+   */
+  async readManifest(options) {
+    const service = await this.#getService();
+    return await service.readManifest(options);
+  }
+
+  /**
+   * Returns deletion metadata for an asset stored in a Git tree.
+   * Does not perform any destructive Git operations.
+   * @param {Object} options
+   * @param {string} options.treeOid - Git tree OID of the asset.
+   * @returns {Promise<{ slug: string, chunksOrphaned: number }>}
+   */
+  async deleteAsset(options) {
+    const service = await this.#getService();
+    return await service.deleteAsset(options);
+  }
+
+  /**
+   * Aggregates referenced chunk blob OIDs across multiple stored assets.
+   * Analysis only — does not delete or modify anything.
+   * @param {Object} options
+   * @param {string[]} options.treeOids - Git tree OIDs to analyze.
+   * @returns {Promise<{ referenced: Set<string>, total: number }>}
+   */
+  async findOrphanedChunks(options) {
+    const service = await this.#getService();
+    return await service.findOrphanedChunks(options);
+  }
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@git-stunts/git-cas",
+  "version": "1.6.0",
+  "description": "Content-addressed storage backed by Git's object database, with optional encryption and pluggable codecs",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "git-cas": "./bin/git-cas.js"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./service": "./src/domain/services/CasService.js",
+    "./schema": "./src/domain/schemas/ManifestSchema.js"
+  },
+  "files": [
+    "index.js",
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/git-stunts/git-cas.git"
+  },
+  "keywords": [
+    "git",
+    "cas",
+    "content-addressable",
+    "storage",
+    "deduplication",
+    "encryption",
+    "blob",
+    "bun",
+    "deno"
+  ],
+  "author": "James Ross <james@flyingrobots.dev>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/git-stunts/git-cas/issues"
+  },
+  "homepage": "https://github.com/git-stunts/git-cas#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "vitest run test/unit",
+    "test:local": "vitest run test/unit",
+    "test:node": "docker compose run --build --rm test-node",
+    "test:bun": "docker compose run --build --rm test-bun",
+    "test:deno": "docker compose run --build --rm test-deno",
+    "test:integration": "vitest run test/integration",
+    "test:integration:node": "docker compose run --build --rm test-node npx vitest run test/integration",
+    "test:integration:bun": "docker compose run --build --rm test-bun bunx vitest run test/integration",
+    "test:integration:deno": "docker compose run --build --rm test-deno deno run -A npm:vitest run test/integration",
+    "test:platforms": "bats --jobs 3 test/platform/runtimes.bats",
+    "benchmark": "vitest bench test/benchmark",
+    "benchmark:local": "vitest bench test/benchmark",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    "@git-stunts/alfred": "^0.10.0",
+    "@git-stunts/plumbing": "^2.8.0",
+    "cbor-x": "^1.6.0",
+    "commander": "^14.0.3",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "eslint": "^9.17.0",
+    "jsr": "^0.14.2",
+    "prettier": "^3.4.2",
+    "vitest": "^2.1.8"
+  }
+}

package/src/domain/errors/CasError.js

@@ -0,0 +1,20 @@
+/**
+ * Base error class for CAS operations.
+ *
+ * Carries a machine-readable `code` and an optional `meta` bag for
+ * structured error context.
+ */
+export default class CasError extends Error {
+  /**
+   * @param {string} message - Human-readable error description.
+   * @param {string} code - Machine-readable error code (e.g. `'INTEGRITY_ERROR'`).
+   * @param {Object} [meta={}] - Arbitrary metadata for diagnostics.
+   */
+  constructor(message, code, meta = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.meta = meta;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}

package/src/domain/schemas/ManifestSchema.js

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Zod schemas for validating CAS manifest and chunk data.
+ */
+
+import z from 'zod';
+
+/** Validates a single chunk entry within a manifest. */
+export const ChunkSchema = z.object({
+  index: z.number().int().min(0),
+  size: z.number().int().positive(),
+  digest: z.string().length(64), // SHA-256
+  blob: z.string().min(1),       // Git OID
+});
+
+/** Validates the encryption metadata attached to an encrypted manifest. */
+export const EncryptionSchema = z.object({
+  algorithm: z.string(),
+  nonce: z.string(),
+  tag: z.string(),
+  encrypted: z.boolean().default(true),
+});
+
+/** Validates a complete file manifest. */
+export const ManifestSchema = z.object({
+  slug: z.string().min(1),
+  filename: z.string().min(1),
+  size: z.number().int().min(0),
+  chunks: z.array(ChunkSchema),
+  encryption: EncryptionSchema.optional(),
+});