@git-stunts/git-cas 1.6.0

package/src/infrastructure/adapters/GitPersistenceAdapter.js

@@ -0,0 +1,103 @@
+import { Policy } from '@git-stunts/alfred';
+import GitPersistencePort from '../../ports/GitPersistencePort.js';
+import CasError from '../../domain/errors/CasError.js';
+
+/** Default resilience policy: 30 s timeout wrapping 2 retries with exponential backoff. */
+const DEFAULT_POLICY = Policy.timeout(30_000).wrap(
+  Policy.retry({
+    retries: 2,
+    backoff: 'exponential',
+    delay: 100,
+    maxDelay: 2_000,
+  }),
+);
+
+/**
+ * {@link GitPersistencePort} implementation backed by `@git-stunts/plumbing`.
+ *
+ * All Git I/O is wrapped with a configurable resilience {@link Policy}
+ * (timeout + retry by default).
+ */
+export default class GitPersistenceAdapter extends GitPersistencePort {
+  /**
+   * @param {Object} options
+   * @param {import('@git-stunts/plumbing').default} options.plumbing - GitPlumbing instance.
+   * @param {import('@git-stunts/alfred').Policy} [options.policy] - Resilience policy (defaults to 30 s timeout + 2 retries).
+   */
+  constructor({ plumbing, policy }) {
+    super();
+    this.plumbing = plumbing;
+    this.policy = policy ?? DEFAULT_POLICY;
+  }
+
+  /** @override */
+  async writeBlob(content) {
+    return this.policy.execute(() =>
+      this.plumbing.execute({
+        args: ['hash-object', '-w', '--stdin'],
+        input: content,
+      }),
+    );
+  }
+
+  /** @override */
+  async writeTree(entries) {
+    return this.policy.execute(() =>
+      this.plumbing.execute({
+        args: ['mktree'],
+        input: `${entries.join('\n')}\n`,
+      }),
+    );
+  }
+
+  /** @override */
+  async readBlob(oid) {
+    return this.policy.execute(async () => {
+      const stream = await this.plumbing.executeStream({
+        args: ['cat-file', 'blob', oid],
+      });
+      const data = await stream.collect({ asString: false });
+      // Plumbing returns Uint8Array; ensure we return a Buffer for codec/crypto compat
+      return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    });
+  }
+
+  /** @override */
+  async readTree(treeOid) {
+    return this.policy.execute(async () => {
+      const output = await this.plumbing.execute({
+        args: ['ls-tree', '-z', treeOid],
+      });
+
+      if (!output || output.length === 0) {
+        return [];
+      }
+
+      return output.split('\0').filter(Boolean).map((entry) => {
+        // Format: <mode> <type> <oid>\t<name>
+        const tabIndex = entry.indexOf('\t');
+        if (tabIndex === -1) {
+          throw new CasError(
+            `Malformed ls-tree entry: ${entry}`,
+            'TREE_PARSE_ERROR',
+            { rawEntry: entry },
+          );
+        }
+        const meta = entry.slice(0, tabIndex).split(' ');
+        if (meta.length !== 3) {
+          throw new CasError(
+            `Malformed ls-tree entry: ${entry}`,
+            'TREE_PARSE_ERROR',
+            { rawEntry: entry },
+          );
+        }
+        return {
+          mode: meta[0],
+          type: meta[1],
+          oid: meta[2],
+          name: entry.slice(tabIndex + 1),
+        };
+      });
+    });
+  }
+}

package/src/infrastructure/adapters/NodeCryptoAdapter.js

@@ -0,0 +1,103 @@
+import { createHash, createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import CryptoPort from '../../ports/CryptoPort.js';
+import CasError from '../../domain/errors/CasError.js';
+
+/**
+ * Node.js implementation of CryptoPort using node:crypto.
+ */
+export default class NodeCryptoAdapter extends CryptoPort {
+  /** @override */
+  sha256(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+  }
+
+  /** @override */
+  randomBytes(n) {
+    return randomBytes(n);
+  }
+
+  /** @override */
+  encryptBuffer(buffer, key) {
+    this.#validateKey(key);
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    const enc = Buffer.concat([cipher.update(buffer), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return {
+      buf: enc,
+      meta: this.#buildMeta(nonce, tag),
+    };
+  }
+
+  /** @override */
+  decryptBuffer(buffer, key, meta) {
+    const nonce = Buffer.from(meta.nonce, 'base64');
+    const tag = Buffer.from(meta.tag, 'base64');
+    const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(buffer), decipher.final()]);
+  }
+
+  /** @override */
+  createEncryptionStream(key) {
+    this.#validateKey(key);
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+
+    const encrypt = async function* (source) {
+      for await (const chunk of source) {
+        const encrypted = cipher.update(chunk);
+        if (encrypted.length > 0) {
+          yield encrypted;
+        }
+      }
+      const final = cipher.final();
+      if (final.length > 0) {
+        yield final;
+      }
+    };
+
+    const finalize = () => {
+      const tag = cipher.getAuthTag();
+      return this.#buildMeta(nonce, tag);
+    };
+
+    return { encrypt, finalize };
+  }
+
+  /**
+   * Validates that a key is a 32-byte Buffer.
+   * @param {Buffer} key
+   * @throws {CasError} INVALID_KEY_TYPE | INVALID_KEY_LENGTH
+   */
+  #validateKey(key) {
+    if (!Buffer.isBuffer(key)) {
+      throw new CasError(
+        'Encryption key must be a Buffer',
+        'INVALID_KEY_TYPE',
+      );
+    }
+    if (key.length !== 32) {
+      throw new CasError(
+        `Encryption key must be 32 bytes, got ${key.length}`,
+        'INVALID_KEY_LENGTH',
+        { expected: 32, actual: key.length },
+      );
+    }
+  }
+
+  /**
+   * Builds the encryption metadata object.
+   * @param {Buffer} nonce - 12-byte AES-GCM nonce.
+   * @param {Buffer} tag - 16-byte GCM authentication tag.
+   * @returns {{ algorithm: string, nonce: string, tag: string, encrypted: boolean }}
+   */
+  #buildMeta(nonce, tag) {
+    return {
+      algorithm: 'aes-256-gcm',
+      nonce: nonce.toString('base64'),
+      tag: tag.toString('base64'),
+      encrypted: true,
+    };
+  }
+}

package/src/infrastructure/adapters/WebCryptoAdapter.js

@@ -0,0 +1,194 @@
+import CryptoPort from '../../ports/CryptoPort.js';
+import CasError from '../../domain/errors/CasError.js';
+
+/**
+ * {@link CryptoPort} implementation using the Web Crypto API.
+ *
+ * Works in Deno, browsers, and other environments supporting `globalThis.crypto.subtle`.
+ * Note: streaming encryption buffers all data internally because Web Crypto's
+ * AES-GCM is a one-shot API (the GCM tag is computed over the entire plaintext).
+ */
+export default class WebCryptoAdapter extends CryptoPort {
+  /** @override */
+  async sha256(buf) {
+    const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', buf);
+    return Array.from(new Uint8Array(hashBuffer))
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  /** @override */
+  randomBytes(n) {
+    const uint8 = globalThis.crypto.getRandomValues(new Uint8Array(n));
+    if (globalThis.Buffer) {
+      return Buffer.from(uint8.buffer, uint8.byteOffset, uint8.byteLength);
+    }
+    return uint8;
+  }
+
+  /** @override */
+  async encryptBuffer(buffer, key) {
+    this.#validateKey(key);
+    const nonce = this.randomBytes(12);
+    const cryptoKey = await this.#importKey(key);
+    
+    // AES-GCM in Web Crypto includes the tag at the end of the ciphertext
+    const encrypted = await globalThis.crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv: nonce },
+      cryptoKey,
+      buffer
+    );
+
+    const fullBuffer = new Uint8Array(encrypted);
+    const tagLength = 16;
+    const ciphertext = fullBuffer.slice(0, -tagLength);
+    const tag = fullBuffer.slice(-tagLength);
+
+    return {
+      buf: Buffer.from(ciphertext),
+      meta: this.#buildMeta(nonce, tag),
+    };
+  }
+
+  /** @override */
+  async decryptBuffer(buffer, key, meta) {
+    const nonce = this.#fromBase64(meta.nonce);
+    const tag = this.#fromBase64(meta.tag);
+    const cryptoKey = await this.#importKey(key);
+
+    // Reconstruct Web Crypto format (ciphertext + tag)
+    const combined = new Uint8Array(buffer.length + tag.length);
+    combined.set(new Uint8Array(buffer));
+    combined.set(tag, buffer.length);
+
+    try {
+      const decrypted = await globalThis.crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv: nonce },
+        cryptoKey,
+        combined
+      );
+      return Buffer.from(decrypted);
+    } catch (err) {
+      throw new CasError('Decryption failed', 'INTEGRITY_ERROR', { originalError: err });
+    }
+  }
+
+  /** @override */
+  createEncryptionStream(key) {
+    this.#validateKey(key);
+    const nonce = this.randomBytes(12);
+    const cryptoKeyPromise = this.#importKey(key);
+    
+    // Web Crypto doesn't have a native streaming AES-GCM API like Node
+    // We have to buffer for the one-shot call because GCM tag is computed over the whole thing.
+    // NOTE: This limits the "stream" to memory capacity, matching the project's 
+    // current CasService.restore limitation.
+    const chunks = [];
+    let finalTag = null;
+
+    const encrypt = async function* (source) {
+      for await (const chunk of source) {
+        chunks.push(chunk);
+        // We can't yield partial encrypted chunks for GCM in Web Crypto 
+        // without complex chunk-chaining which would break compatibility 
+        // with the Node adapter's single-stream GCM.
+      }
+      
+      const buffer = Buffer.concat(chunks);
+      const cryptoKey = await cryptoKeyPromise;
+      const encrypted = await globalThis.crypto.subtle.encrypt(
+        { name: 'AES-GCM', iv: nonce },
+        cryptoKey,
+        buffer
+      );
+
+      const fullBuffer = new Uint8Array(encrypted);
+      const tagLength = 16;
+      const ciphertext = fullBuffer.slice(0, -tagLength);
+      finalTag = fullBuffer.slice(-tagLength);
+
+      yield Buffer.from(ciphertext);
+    };
+
+    const finalize = () => {
+      return this.#buildMeta(nonce, finalTag);
+    };
+
+    return { encrypt, finalize };
+  }
+
+  /**
+   * Imports a raw key for use with Web Crypto AES-GCM operations.
+   * @param {Buffer|Uint8Array} rawKey - 32-byte raw key material.
+   * @returns {Promise<CryptoKey>}
+   */
+  async #importKey(rawKey) {
+    return globalThis.crypto.subtle.importKey(
+      'raw',
+      rawKey,
+      { name: 'AES-GCM' },
+      false,
+      ['encrypt', 'decrypt']
+    );
+  }
+
+  /**
+   * Validates that a key is a 32-byte Buffer or Uint8Array.
+   * @param {Buffer|Uint8Array} key
+   * @throws {CasError} INVALID_KEY_TYPE | INVALID_KEY_LENGTH
+   */
+  #validateKey(key) {
+    if (!globalThis.Buffer?.isBuffer(key) && !(key instanceof Uint8Array)) {
+      throw new CasError(
+        'Encryption key must be a Buffer or Uint8Array',
+        'INVALID_KEY_TYPE',
+      );
+    }
+    if (key.length !== 32) {
+      throw new CasError(
+        `Encryption key must be 32 bytes, got ${key.length}`,
+        'INVALID_KEY_LENGTH',
+        { expected: 32, actual: key.length },
+      );
+    }
+  }
+
+  /**
+   * Builds the encryption metadata object.
+   * @param {Uint8Array} nonce - 12-byte AES-GCM nonce.
+   * @param {Uint8Array} tag - 16-byte GCM authentication tag.
+   * @returns {{ algorithm: string, nonce: string, tag: string, encrypted: boolean }}
+   */
+  #buildMeta(nonce, tag) {
+    return {
+      algorithm: 'aes-256-gcm',
+      nonce: this.#toBase64(nonce),
+      tag: this.#toBase64(tag),
+      encrypted: true,
+    };
+  }
+
+  /**
+   * Encodes binary data to base64, using Buffer when available.
+   * @param {Uint8Array} buf
+   * @returns {string}
+   */
+  #toBase64(buf) {
+    if (globalThis.Buffer) {
+      return Buffer.from(buf).toString('base64');
+    }
+    return globalThis.btoa(String.fromCharCode(...new Uint8Array(buf)));
+  }
+
+  /**
+   * Decodes a base64 string to binary, using Buffer when available.
+   * @param {string} str
+   * @returns {Buffer|Uint8Array}
+   */
+  #fromBase64(str) {
+    if (globalThis.Buffer) {
+      return Buffer.from(str, 'base64');
+    }
+    return Uint8Array.from(globalThis.atob(str), c => c.charCodeAt(0));
+  }
+}

package/src/infrastructure/codecs/CborCodec.js

@@ -0,0 +1,22 @@
+import CodecPort from '../../ports/CodecPort.js';
+import { encode, decode } from 'cbor-x';
+
+/**
+ * {@link CodecPort} implementation that serializes manifests as CBOR (binary).
+ */
+export default class CborCodec extends CodecPort {
+  /** @override */
+  encode(data) {
+    return encode(data);
+  }
+
+  /** @override */
+  decode(buffer) {
+    return decode(buffer);
+  }
+
+  /** @override */
+  get extension() {
+    return 'cbor';
+  }
+}

package/src/infrastructure/codecs/JsonCodec.js

@@ -0,0 +1,23 @@
+import CodecPort from '../../ports/CodecPort.js';
+
+/**
+ * {@link CodecPort} implementation that serializes manifests as pretty-printed JSON.
+ */
+export default class JsonCodec extends CodecPort {
+  /** @override */
+  encode(data) {
+    // Determine if we need to handle Buffers specially for JSON
+    // For now, we assume data is JSON-safe or uses toJSON() methods
+    return JSON.stringify(data, null, 2);
+  }
+
+  /** @override */
+  decode(buffer) {
+    return JSON.parse(buffer.toString('utf8'));
+  }
+
+  /** @override */
+  get extension() {
+    return 'json';
+  }
+}

package/src/ports/CodecPort.js

@@ -0,0 +1,31 @@
+/**
+ * Abstract interface for encoding and decoding manifest data.
+ * @abstract
+ */
+export default class CodecPort {
+  /**
+   * Encodes data to a Buffer or string.
+   * @param {Object} data
+   * @returns {Buffer|string}
+   */
+  encode(_data) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Decodes data from a Buffer or string.
+   * @param {Buffer|string} buffer
+   * @returns {Object}
+   */
+  decode(_buffer) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Returns the file extension for this codec (e.g. 'json', 'cbor').
+   * @returns {string}
+   */
+  get extension() {
+    throw new Error('Not implemented');
+  }
+}

package/src/ports/CryptoPort.js

@@ -0,0 +1,54 @@
+/**
+ * Abstract port for cryptographic operations (hashing, random bytes, AES-256-GCM).
+ * @abstract
+ */
+export default class CryptoPort {
+  /**
+   * Returns the SHA-256 hex digest of a buffer.
+   * @param {Buffer} buf
+   * @returns {string} 64-char hex digest
+   */
+  sha256(_buf) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Returns a Buffer of n cryptographically random bytes.
+   * @param {number} n
+   * @returns {Buffer}
+   */
+  randomBytes(_n) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Encrypts a buffer using AES-256-GCM.
+   * @param {Buffer} buffer
+   * @param {Buffer} key - 32-byte encryption key
+   * @returns {{ buf: Buffer, meta: { algorithm: string, nonce: string, tag: string, encrypted: boolean } }}
+   */
+  encryptBuffer(_buffer, _key) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Decrypts a buffer using AES-256-GCM.
+   * @param {Buffer} buffer
+   * @param {Buffer} key - 32-byte encryption key
+   * @param {{ algorithm: string, nonce: string, tag: string, encrypted: boolean }} meta
+   * @returns {Buffer}
+   * @throws on authentication failure
+   */
+  decryptBuffer(_buffer, _key, _meta) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Creates a streaming encryption context.
+   * @param {Buffer} key - 32-byte encryption key
+   * @returns {{ encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>, finalize: () => { algorithm: string, nonce: string, tag: string, encrypted: boolean } }}
+   */
+  createEncryptionStream(_key) {
+    throw new Error('Not implemented');
+  }
+}

package/src/ports/GitPersistencePort.js

@@ -0,0 +1,41 @@
+/**
+ * Abstract port for persisting data to Git's object database.
+ * @abstract
+ */
+export default class GitPersistencePort {
+  /**
+   * Writes content as a Git blob object.
+   * @param {Buffer|string} content - Data to store.
+   * @returns {Promise<string>} The Git OID of the stored blob.
+   */
+  async writeBlob(_content) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Creates a Git tree object from formatted entries.
+   * @param {string[]} entries - Lines in `git mktree` format.
+   * @returns {Promise<string>} The Git OID of the created tree.
+   */
+  async writeTree(_entries) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Reads a Git blob by its OID.
+   * @param {string} oid - Git object ID.
+   * @returns {Promise<Buffer>} The blob content.
+   */
+  async readBlob(_oid) {
+    throw new Error('Not implemented');
+  }
+
+  /**
+   * Reads and parses a Git tree object.
+   * @param {string} treeOid - Git tree OID.
+   * @returns {Promise<Array<{ mode: string, type: string, oid: string, name: string }>>} Parsed tree entries.
+   */
+  async readTree(_treeOid) {
+    throw new Error('Not implemented');
+  }
+}