feat: M11 Locksmith — envelope encryption with multi-recipient DEK/KEK

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased] — Locksmith
+
+### Added
+- **Envelope encryption (DEK/KEK)** — multi-recipient model where a random DEK encrypts content and per-recipient KEKs wrap the DEK. Recipients can be added/removed without re-encrypting data.
+- **`RecipientSchema`** — Zod schema for validating recipient entries in manifests.
+- **`recipients` field on `EncryptionSchema`** — optional array of `{ label, wrappedDek, nonce, tag }` entries.
+- **`CasService.addRecipient()` / `removeRecipient()` / `listRecipients()`** — manage envelope recipients on existing manifests.
+- **`--recipient <label:keyfile>` CLI flag** — repeatable flag on `git cas store` for envelope encryption.
+- **`git cas recipient add/remove/list`** subcommands — CLI management of envelope recipients.
+- **`RecipientEntry` type re-exported** from `index.d.ts`.
+- 48 new unit tests (757 total).
+
+### Fixed
+- **`_wrapDek` / `_unwrapDek` missing `await`** — these called async `encryptBuffer()` / `decryptBuffer()` without `await`, silently producing garbage on Bun/Deno runtimes where crypto is async.
+- **`--recipient` + `--vault-passphrase` not guarded** — CLI now rejects combining `--recipient` with `--key-file` or `--vault-passphrase`.
+- **Dead `_resolveEncryptionKey` method removed** — superseded by `_resolveDecryptionKey` but left behind.
+- **Redundant `RECIPIENT_NOT_FOUND` guards** in `removeRecipient` collapsed into one.
+- **`addRecipient` duplicated unwrap loop** replaced with `_resolveKeyForRecipients` reuse.
+- **`removeRecipient` post-filter guard** — defense-in-depth check prevents zero recipients when duplicate labels exist in corrupted/crafted manifests.
+- **`EncryptionSchema` empty recipients** — `recipients` array now enforces `min(1)` to reject undecryptable envelope manifests.
+- **`parseRecipient` empty keyfile** — CLI now rejects `--recipient alice:` (missing keyfile path) with a clear error.
+
 ## [5.0.0] — Hydra (2026-02-28)
 
 ### Breaking Changes

bin/actions.js

@@ -8,6 +8,11 @@ const HINTS = {
   VAULT_ENTRY_NOT_FOUND: "Run 'git cas vault list' to see available entries",
   VAULT_ENTRY_EXISTS: 'Use --force to overwrite',
   INTEGRITY_ERROR: 'Check that the correct key or passphrase was used',
+  NO_MATCHING_RECIPIENT: 'The provided key does not match any recipient in the manifest',
+  DEK_UNWRAP_FAILED: 'The existing key does not match any recipient — cannot unwrap DEK',
+  RECIPIENT_NOT_FOUND: 'No recipient with that label exists in the manifest',
+  RECIPIENT_ALREADY_EXISTS: 'A recipient with that label already exists',
+  CANNOT_REMOVE_LAST_RECIPIENT: 'At least one recipient must remain in the manifest',
 };
 
 /**

bin/git-cas.js

@@ -18,7 +18,7 @@ const getJson = () => program.opts().json;
 program
   .name('git-cas')
   .description('Content Addressable Storage backed by Git')
-  .version('4.0.1')
+  .version('5.0.0')
   .option('-q, --quiet', 'Suppress progress output')
   .option('--json', 'Output results as JSON');
 
@@ -96,52 +96,75 @@ function validateRestoreFlags(opts) {
 // ---------------------------------------------------------------------------
 // store
 // ---------------------------------------------------------------------------
+/**
+ * Build store options, resolving encryption key or recipients.
+ */
+async function buildStoreOpts(cas, file, opts) {
+  const storeOpts = { filePath: file, slug: opts.slug };
+  if (opts.recipient) {
+    storeOpts.recipients = opts.recipient;
+  } else {
+    const encryptionKey = await resolveEncryptionKey(cas, opts);
+    if (encryptionKey) { storeOpts.encryptionKey = encryptionKey; }
+  }
+  return storeOpts;
+}
+
+/**
+ * Parse a --recipient flag value into { label, key }.
+ * Format: label:keyfile
+ */
+function parseRecipient(value, previous) {
+  const sep = value.indexOf(':');
+  if (sep < 1) {
+    throw new Error(`Invalid --recipient format "${value}": expected label:keyfile`);
+  }
+  const label = value.slice(0, sep);
+  const keyfile = value.slice(sep + 1);
+  if (!keyfile) {
+    throw new Error(`Invalid --recipient format "${value}": missing keyfile path`);
+  }
+  const key = readKeyFile(keyfile);
+  const list = previous || [];
+  list.push({ label, key });
+  return list;
+}
+
 program
   .command('store <file>')
   .description('Store a file into Git CAS')
   .requiredOption('--slug <slug>', 'Asset slug identifier')
   .option('--key-file <path>', 'Path to 32-byte raw encryption key file')
+  .option('--recipient <label:keyfile>', 'Envelope recipient (repeatable)', parseRecipient)
   .option('--tree', 'Also create a Git tree and print its OID')
   .option('--force', 'Overwrite existing vault entry')
   .option('--vault-passphrase <pass>', 'Vault-level passphrase for encryption (prefer GIT_CAS_PASSPHRASE env var)')
   .option('--cwd <dir>', 'Git working directory', '.')
   .action(runAction(async (file, opts) => {
+    if (opts.recipient && (opts.keyFile || resolvePassphrase(opts))) {
+      throw new Error('Provide --key-file/--vault-passphrase or --recipient, not both');
+    }
+    if (opts.force && !opts.tree) {
+      throw new Error('--force requires --tree');
+    }
     const json = program.opts().json;
     const quiet = program.opts().quiet || json;
     const observer = new EventEmitterObserver();
     const cas = createCas(opts.cwd, { observability: observer });
-    const encryptionKey = await resolveEncryptionKey(cas, opts);
-    if (opts.force && !opts.tree) {
-      throw new Error('--force requires --tree');
-    }
-    const storeOpts = { filePath: file, slug: opts.slug };
-    if (encryptionKey) {
-      storeOpts.encryptionKey = encryptionKey;
-    }
 
-    const progress = createStoreProgress({
-      filePath: file, chunkSize: cas.chunkSize, quiet,
-    });
+    const storeOpts = await buildStoreOpts(cas, file, opts);
+    const progress = createStoreProgress({ filePath: file, chunkSize: cas.chunkSize, quiet });
     progress.attach(observer);
     let manifest;
-    try {
-      manifest = await cas.storeFile(storeOpts);
-    } finally {
-      progress.detach();
-    }
+    try { manifest = await cas.storeFile(storeOpts); } finally { progress.detach(); }
 
     if (opts.tree) {
       const treeOid = await cas.createTree({ manifest });
       await cas.addToVault({ slug: opts.slug, treeOid, force: !!opts.force });
-      if (json) {
-        process.stdout.write(`${JSON.stringify({ treeOid })}\n`);
-      } else {
-        process.stdout.write(`${treeOid}\n`);
-      }
-    } else if (json) {
-      process.stdout.write(`${JSON.stringify({ manifest: manifest.toJSON() })}\n`);
+      process.stdout.write(json ? `${JSON.stringify({ treeOid })}\n` : `${treeOid}\n`);
     } else {
-      process.stdout.write(`${JSON.stringify(manifest.toJSON(), null, 2)}\n`);
+      const output = json ? JSON.stringify({ manifest: manifest.toJSON() }) : JSON.stringify(manifest.toJSON(), null, 2);
+      process.stdout.write(`${output}\n`);
     }
   }, getJson));
 
@@ -419,4 +442,87 @@ vault
     await launchDashboard(cas);
   }, getJson));
 
-await program.parseAsync();
+// ---------------------------------------------------------------------------
+// recipient add / remove / list
+// ---------------------------------------------------------------------------
+const recipient = program
+  .command('recipient')
+  .description('Manage envelope encryption recipients');
+
+recipient
+  .command('add <slug>')
+  .description('Add a recipient to an envelope-encrypted asset')
+  .requiredOption('--label <label>', 'Label for the new recipient')
+  .requiredOption('--key-file <path>', 'Path to 32-byte key file for the new recipient')
+  .requiredOption('--existing-key-file <path>', 'Path to key file of an existing recipient')
+  .option('--cwd <dir>', 'Git working directory', '.')
+  .action(runAction(async (slug, opts) => {
+    const cas = createCas(opts.cwd);
+    const treeOid = await cas.resolveVaultEntry({ slug });
+    const manifest = await cas.readManifest({ treeOid });
+
+    const existingKey = readKeyFile(opts.existingKeyFile);
+    const newRecipientKey = readKeyFile(opts.keyFile);
+
+    const updated = await cas.addRecipient({
+      manifest,
+      existingKey,
+      newRecipientKey,
+      label: opts.label,
+    });
+
+    const newTreeOid = await cas.createTree({ manifest: updated });
+    await cas.addToVault({ slug, treeOid: newTreeOid, force: true });
+
+    const json = program.opts().json;
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid })}\n`);
+    } else {
+      process.stdout.write(`${newTreeOid}\n`);
+    }
+  }, getJson));
+
+recipient
+  .command('remove <slug>')
+  .description('Remove a recipient from an envelope-encrypted asset')
+  .requiredOption('--label <label>', 'Label of the recipient to remove')
+  .option('--cwd <dir>', 'Git working directory', '.')
+  .action(runAction(async (slug, opts) => {
+    const cas = createCas(opts.cwd);
+    const treeOid = await cas.resolveVaultEntry({ slug });
+    const manifest = await cas.readManifest({ treeOid });
+
+    const updated = await cas.removeRecipient({ manifest, label: opts.label });
+
+    const newTreeOid = await cas.createTree({ manifest: updated });
+    await cas.addToVault({ slug, treeOid: newTreeOid, force: true });
+
+    const json = program.opts().json;
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid })}\n`);
+    } else {
+      process.stdout.write(`${newTreeOid}\n`);
+    }
+  }, getJson));
+
+recipient
+  .command('list <slug>')
+  .description('List recipients of an envelope-encrypted asset')
+  .option('--cwd <dir>', 'Git working directory', '.')
+  .action(runAction(async (slug, opts) => {
+    const cas = createCas(opts.cwd);
+    const treeOid = await cas.resolveVaultEntry({ slug });
+    const manifest = await cas.readManifest({ treeOid });
+
+    const labels = await cas.listRecipients(manifest);
+    const json = program.opts().json;
+    if (json) {
+      process.stdout.write(`${JSON.stringify(labels)}\n`);
+    } else {
+      for (const label of labels) {
+        process.stdout.write(`${label}\n`);
+      }
+    }
+  }, getJson));
+
+await program.parseAsync();

index.d.ts

@@ -4,7 +4,7 @@
  */
 
 import Manifest from "./src/domain/value-objects/Manifest.js";
-import type { EncryptionMeta, ManifestData, CompressionMeta, KdfParams, SubManifestRef } from "./src/domain/value-objects/Manifest.js";
+import type { EncryptionMeta, ManifestData, CompressionMeta, KdfParams, SubManifestRef, RecipientEntry } from "./src/domain/value-objects/Manifest.js";
 import Chunk from "./src/domain/value-objects/Chunk.js";
 import CasService from "./src/domain/services/CasService.js";
 import type {
@@ -18,7 +18,7 @@ import type {
 } from "./src/domain/services/CasService.js";
 
 export { CasService, Manifest, Chunk };
-export type { EncryptionMeta, ManifestData, CompressionMeta, KdfParams, SubManifestRef, CryptoPort, CodecPort, GitPersistencePort, ObservabilityPort, CasServiceOptions, DeriveKeyOptions, DeriveKeyResult };
+export type { EncryptionMeta, ManifestData, CompressionMeta, KdfParams, SubManifestRef, RecipientEntry, CryptoPort, CodecPort, GitPersistencePort, ObservabilityPort, CasServiceOptions, DeriveKeyOptions, DeriveKeyResult };
 
 /** Abstract port for splitting a byte stream into chunks. */
 export declare class ChunkingPort {
@@ -302,6 +302,7 @@ export default class ContentAddressableStore {
     passphrase?: string;
     kdfOptions?: Omit<DeriveKeyOptions, "passphrase">;
     compression?: { algorithm: "gzip" };
+    recipients?: Array<{ label: string; key: Buffer }>;
   }): Promise<Manifest>;
 
   store(options: {
@@ -312,6 +313,7 @@ export default class ContentAddressableStore {
     passphrase?: string;
     kdfOptions?: Omit<DeriveKeyOptions, "passphrase">;
     compression?: { algorithm: "gzip" };
+    recipients?: Array<{ label: string; key: Buffer }>;
   }): Promise<Manifest>;
 
   restoreFile(options: {
@@ -349,6 +351,20 @@ export default class ContentAddressableStore {
 
   deriveKey(options: DeriveKeyOptions): Promise<DeriveKeyResult>;
 
+  addRecipient(options: {
+    manifest: Manifest;
+    existingKey: Buffer;
+    newRecipientKey: Buffer;
+    label: string;
+  }): Promise<Manifest>;
+
+  removeRecipient(options: {
+    manifest: Manifest;
+    label: string;
+  }): Promise<Manifest>;
+
+  listRecipients(manifest: Manifest): Promise<string[]>;
+
   // Vault — delegates to VaultService
 
   static VAULT_REF: string;

index.js

@@ -265,9 +265,10 @@ export default class ContentAddressableStore {
    * @param {string} [options.passphrase] - Derive encryption key from passphrase.
    * @param {Object} [options.kdfOptions] - KDF options when using passphrase.
    * @param {{ algorithm: 'gzip' }} [options.compression] - Enable compression.
+   * @param {Array<{label: string, key: Buffer}>} [options.recipients] - Envelope recipients (mutually exclusive with encryptionKey/passphrase).
    * @returns {Promise<import('./src/domain/value-objects/Manifest.js').default>} The resulting manifest.
    */
-  async storeFile({ filePath, slug, filename, encryptionKey, passphrase, kdfOptions, compression }) {
+  async storeFile({ filePath, slug, filename, encryptionKey, passphrase, kdfOptions, compression, recipients }) {
     const source = createReadStream(filePath);
     const service = await this.#getService();
     return await service.store({
@@ -278,6 +279,7 @@ export default class ContentAddressableStore {
       passphrase,
       kdfOptions,
       compression,
+      recipients,
     });
   }
 
@@ -291,6 +293,7 @@ export default class ContentAddressableStore {
    * @param {string} [options.passphrase] - Derive encryption key from passphrase.
    * @param {Object} [options.kdfOptions] - KDF options when using passphrase.
    * @param {{ algorithm: 'gzip' }} [options.compression] - Enable compression.
+   * @param {Array<{label: string, key: Buffer}>} [options.recipients] - Envelope recipients (mutually exclusive with encryptionKey/passphrase).
    * @returns {Promise<import('./src/domain/value-objects/Manifest.js').default>} The resulting manifest.
    */
   async store(options) {
@@ -421,6 +424,46 @@ export default class ContentAddressableStore {
     return await service.deriveKey(options);
   }
 
+  // ---------------------------------------------------------------------------
+  // Recipient management — delegates to CasService
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Adds a recipient to an envelope-encrypted manifest.
+   * @param {Object} options
+   * @param {import('./src/domain/value-objects/Manifest.js').default} options.manifest
+   * @param {Buffer} options.existingKey - KEK of an existing recipient.
+   * @param {Buffer} options.newRecipientKey - KEK for the new recipient.
+   * @param {string} options.label - Label for the new recipient.
+   * @returns {Promise<import('./src/domain/value-objects/Manifest.js').default>}
+   */
+  async addRecipient(options) {
+    const service = await this.#getService();
+    return await service.addRecipient(options);
+  }
+
+  /**
+   * Removes a recipient from an envelope-encrypted manifest.
+   * @param {Object} options
+   * @param {import('./src/domain/value-objects/Manifest.js').default} options.manifest
+   * @param {string} options.label - Label to remove.
+   * @returns {Promise<import('./src/domain/value-objects/Manifest.js').default>}
+   */
+  async removeRecipient(options) {
+    const service = await this.#getService();
+    return await service.removeRecipient(options);
+  }
+
+  /**
+   * Lists recipient labels from an envelope-encrypted manifest.
+   * @param {import('./src/domain/value-objects/Manifest.js').default} manifest
+   * @returns {Promise<string[]>}
+   */
+  async listRecipients(manifest) {
+    const service = await this.#getService();
+    return service.listRecipients(manifest);
+  }
+
   // ---------------------------------------------------------------------------
   // Vault — delegates to VaultService
   // ---------------------------------------------------------------------------

src/domain/schemas/ManifestSchema.d.ts

@@ -24,13 +24,23 @@ export declare const KdfSchema: z.ZodObject<{
   keyLength: z.ZodDefault<z.ZodNumber>;
 }>;
 
+/** Validates a single recipient entry in an envelope-encrypted manifest. */
+export declare const RecipientSchema: z.ZodObject<{
+  label: z.ZodString;
+  wrappedDek: z.ZodString;
+  nonce: z.ZodString;
+  tag: z.ZodString;
+  kekType: z.ZodOptional<z.ZodString>;
+}>;
+
 /** Validates the encryption metadata attached to an encrypted manifest. */
 export declare const EncryptionSchema: z.ZodObject<{
   algorithm: z.ZodString;
   nonce: z.ZodString;
   tag: z.ZodString;
   encrypted: z.ZodDefault<z.ZodBoolean>;
   kdf: z.ZodOptional<typeof KdfSchema>;
+  recipients: z.ZodOptional<z.ZodArray<typeof RecipientSchema>>;
 }>;
 
 /** Validates compression metadata. */