fix: address v6 release review findings

Author: flyingrobots

.gitignore

@@ -16,3 +16,5 @@ CODE-EVAL.md
 .mcp.json
 build-info.json
 .obsidian/*
+/Untitled.md
+/output-*.txt

CHANGELOG.md

@@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- **Migration script (`npm run upgrade`)** — fully implemented `scripts/migrate-encryption.js` for v6.0.0 encryption scheme upgrades. Two modes: **fast** (rename-only for v2 schemes and `convergent-v1`) and **full** (re-encryption for v1 whole/framed schemes that lacked AAD). Supports `--execute` (default dry-run), `--passphrase`, and `--cwd`. Reads every vault entry, classifies it, and reports what will/did change.
+- **Migration script (`npm run upgrade`)** — fully implemented `scripts/migrate-encryption.js` for v6.0.0 encryption scheme upgrades. Two modes: **fast** (rename-only for v2 schemes and `convergent-v1`) and **full** (re-encryption for v1 whole/framed schemes that lacked AAD). Supports `--execute` (default dry-run), `--passphrase`, `--key-file`, privacy-vault key options, and `--cwd`. Reads every vault entry, classifies it, and reports what will/did change.
 - **`CasService.readManifestRaw()`** — reads a manifest from a Git tree OID and returns the raw decoded object without Manifest construction or scheme assertion. Migration entry point for inspecting legacy manifests.
 - **`CasService` `legacyMode` constructor option** — when `true`, `readManifest()` maps legacy scheme identifiers (v1/v2) to their current names instead of throwing `LEGACY_SCHEME`. Legacy v1 manifests (no AAD) are correctly decrypted without AAD during restore.
 - **`mapToCurrentScheme()` and `isLegacyNoAad()` in `schemes.js`** — public helpers for mapping legacy scheme strings to current names and detecting v1 no-AAD schemes.
@@ -58,7 +58,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Plaintext+compressed restore is now streaming** — compressed unencrypted data uses `_restoreCompressedStreaming` instead of the buffered path, eliminating the `maxRestoreBufferSize` constraint for this case.
 - **`formatVersion` stamped into new manifests** — new manifests include a `formatVersion` field carrying the package semver at store time. The field is optional on read for backward compatibility with older manifests.
 - **`CryptoPort._buildMeta` default scheme** — changed to the current `whole` identifier.
-- **CompressionPort extraction** — `CasService` no longer imports `node:zlib`, `node:stream`, or `node:util` directly. Compression is now delegated through a `CompressionPort` abstract port with a `NodeCompressionAdapter` default implementation. The `CasService` constructor accepts an optional `compressionAdapter` parameter for injecting alternative implementations. Public API unchanged; internal refactor only.
+- **CompressionPort extraction** — `CasService` no longer imports `node:zlib`, `node:stream`, or `node:util` directly. Compression is now delegated through a `CompressionPort` abstract port. Direct `CasService` construction must inject `compressionAdapter`; the facade still provides the Node gzip default for normal callers.
 - **AES-GCM adapter enforcement** — Node, Bun, and Web Crypto decrypt paths now all reject malformed AES-256-GCM metadata at the adapter boundary, enforce the declared algorithm before decrypting, and reject short or malformed nonce/tag fields before any runtime-specific decrypt call runs.
 - **Buffered restore adapter contract** — hard-limited buffered restore modes now require `readBlobStream()` on the persistence adapter instead of silently degrading to whole-blob `readBlob()` fallback behavior. Plaintext restore keeps the compatibility fallback.
 - **KDF salt shape hardening** — stored KDF salt metadata now rejects malformed base64 at both the manifest schema layer and the runtime stored-KDF policy path, keeping vault metadata and passphrase-restore behavior aligned before derive work starts.

GUIDE.md

@@ -295,9 +295,11 @@ Manifests created with earlier versions may use v1/v2 scheme identifiers (`whole
 
 ```sh
 node scripts/migrate-encryption.js
+node scripts/migrate-encryption.js --execute --passphrase my-secret
+node scripts/migrate-encryption.js --execute --key-file ./asset.key
 ```
 
-The migration script handles both fast (rename-only for v2 schemes) and full (re-encryption with AAD for v1 schemes) migration paths. The main `src/` codebase throws `LEGACY_SCHEME` if it encounters a v1/v2 identifier.
+The migration script handles both fast (rename-only for v2 schemes) and full (re-encryption with AAD for v1 schemes) migration paths. Full migration accepts either `--passphrase` or `--key-file`. For privacy-enabled vaults, add `--vault-passphrase`, `--vault-passphrase-file`, or `--vault-key-file` when the vault passphrase differs from the content passphrase. The main `src/` codebase throws `LEGACY_SCHEME` if it encounters a v1/v2 identifier.
 
 ---
 

README.md

@@ -89,7 +89,7 @@ Three encryption schemes are supported:
 | `framed` | Bounded frames | Slug + frame index | Default for fixed-chunk encrypted stores — streaming decrypt with per-frame AAD binding |
 | `convergent` | Per-chunk deterministic | Derived from content hash | **Default for CDC + encryption** — preserves deduplication across encrypted stores. Implemented as a standalone `ConvergentEncryption` service. |
 
-Legacy schemes (`whole-v1`, `whole-v2`, `framed-v1`, `framed-v2`, `convergent-v1`) are no longer accepted and throw a `LEGACY_SCHEME` error. Run `npm run upgrade` (or `node scripts/migrate-encryption.js`) to migrate existing vault entries. The script auto-detects whether each entry needs a rename-only (fast) or full re-encryption (v1 schemes without AAD) and defaults to dry-run mode.
+Legacy schemes (`whole-v1`, `whole-v2`, `framed-v1`, `framed-v2`, `convergent-v1`) are no longer accepted and throw a `LEGACY_SCHEME` error. Run `npm run upgrade` (or `node scripts/migrate-encryption.js`) to migrate existing vault entries. The script auto-detects whether each entry needs a rename-only (fast) or full re-encryption (v1 schemes without AAD), accepts either `--passphrase` or `--key-file` for full migrations, supports privacy-vault key options, and defaults to dry-run mode.
 
 **Envelope encryption** wraps a random Data Encryption Key (DEK) with one or more Key Encryption Keys (KEKs). Each recipient is labeled, enabling multi-recipient access to the same encrypted content. Key rotation replaces the KEK wrapping without re-encrypting data blobs.
 

UPGRADING.md

@@ -11,7 +11,7 @@ If you have an existing vault with encrypted assets:
 npm run upgrade
 
 # Apply the migration
-npm run upgrade -- --execute --passphrase <your-vault-passphrase>
+npm run upgrade -- --execute --passphrase <your-content-passphrase>
 ```
 
 If you only use the library API (no vault), skip to [API Changes](#api-changes).
@@ -54,12 +54,26 @@ npm run upgrade
 
 # Execute: migrate all vault entries
 npm run upgrade -- --execute --passphrase <passphrase>
+
+# Or migrate entries encrypted with a raw 32-byte key
+npm run upgrade -- --execute --key-file ./asset.key
 ```
 
 The migration script has two modes:
 
 - **Fast mode** (v2 schemes + convergent): renames the scheme in the manifest metadata. No re-encryption. Seconds.
-- **Full mode** (v1 schemes): restores through the legacy pipeline (decrypts without AAD), then re-stores with the current scheme (encrypts with AAD). Requires passphrase.
+- **Full mode** (v1 schemes): restores through the legacy pipeline (decrypts without AAD), then re-stores with the current scheme (encrypts with AAD). Requires `--passphrase` or `--key-file`.
+
+Privacy-enabled vaults need the vault encryption key to list and update slugs.
+If the vault passphrase differs from the content passphrase, pass
+`--vault-passphrase`, `--vault-passphrase-file`, or `--vault-key-file`.
+When no explicit vault key option is provided, `--passphrase` is reused for the
+privacy vault.
+
+Recipient-encrypted v1 manifests are not automatically full-migrated because
+preserving recipient access requires the original recipient key set. Re-store
+those assets with current recipients after restoring them with a matching
+recipient key.
 
 Original blobs are never deleted — Git's garbage collection only removes unreferenced objects after `git gc`.
 
@@ -202,7 +216,8 @@ These are new capabilities that don't require migration:
 CasError: Legacy encryption scheme "whole-v1" is no longer supported.
 ```
 
-Run `npm run upgrade -- --execute --passphrase <pass>` to migrate.
+Run `npm run upgrade -- --execute --passphrase <pass>` or
+`npm run upgrade -- --execute --key-file <path>` to migrate.
 
 ### `KDF_POLICY_VIOLATION` on deriveKey
 

Untitled.md

@@ -16,7 +16,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * Reads the git SHA from build-info.json (published package).
  * @returns {string|null}
  */
-function readStampedSha() {
+export function readStampedSha() {
   try {
     const info = JSON.parse(
       readFileSync(path.resolve(__dirname, '../build-info.json'), 'utf8'),
@@ -31,7 +31,7 @@ function readStampedSha() {
  * Reads the git SHA from the live repo (development).
  * @returns {string|null}
  */
-function readGitSha() {
+export function readGitSha() {
   try {
     return execSync('git rev-parse --short HEAD', {
       encoding: 'utf8',
@@ -47,7 +47,10 @@ function readGitSha() {
  * @param {string} semver - The package version from package.json.
  * @returns {string}
  */
-export function resolveVersionString(semver) {
-  const sha = readStampedSha() || readGitSha();
+export function resolveVersionString(
+  semver,
+  { readGitSha: readGit = readGitSha, readStampedSha: readStamped = readStampedSha } = {}
+) {
+  const sha = readGit() || readStamped();
   return sha ? `${semver}+${sha}` : semver;
 }

src/build-version.js bin/build-version.jssrc/build-version.js renamed to bin/build-version.js

@@ -33,7 +33,7 @@ import {
 } from './passphrase-source.js';
 import { loadConfig, mergeConfig } from './config.js';
 
-import { resolveVersionString } from '../src/build-version.js';
+import { resolveVersionString } from './build-version.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI_VERSION = resolveVersionString(

bin/git-cas.js

@@ -58,7 +58,7 @@ export function renderEncryptionCard({ metadata, unlocked = false }) {
 
   const rows = buildKdfRows(metadata.encryption);
   const maxKey = Math.max(...rows.map(([k]) => k.length));
-  
+
   const kvSurfaces = rows.map(([k, v]) => {
     const label = themeText(ctx, k.padEnd(maxKey), { tone: 'accent' });
     return hstackSurface(2,
@@ -72,7 +72,7 @@ export function renderEncryptionCard({ metadata, unlocked = false }) {
     variant: unlocked ? 'success' : 'danger',
     ctx,
   });
-  
+
   const statusLabel = themeText(ctx, 'status'.padEnd(maxKey), { tone: 'accent' });
   const statusRow = hstackSurface(2,
     createSurface(2, 1),

bin/ui/encryption-card.js

@@ -110,7 +110,7 @@ function drawLine({ x0, y0, x1, y1, color }) {
 function drawPoint({ x, y, color, radius = 1 }) {
   const ix = Math.round(((x / 1.6) + 1) * 0.5 * (bufferW - 1));
   const iy = Math.round(((y / 1.2) + 1) * 0.5 * (bufferH - 1));
-  
+
   for (let dy = -radius; dy <= radius; dy++) {
     for (let dx = -radius; dx <= radius; dx++) {
       const cx = ix + dx;
@@ -133,11 +133,11 @@ function rasterizeFrame(time) {
     const headProj = project3D({ x: Math.cos(theta), y: Math.sin(theta), z: fitnessState[i], elevation, azimuth });
 
     drawLine({ x0: baseProj.px, y0: baseProj.py, x1: headProj.px, y1: headProj.py, color: STEM_INT });
-    
+
     const nextTheta = ((i + 1) / currentNumSpecies) * 2 * Math.PI + (time * 0.5);
     const nextBaseProj = project3D({ x: Math.cos(nextTheta), y: Math.sin(nextTheta), z: 0, elevation, azimuth });
     drawLine({ x0: baseProj.px, y0: baseProj.py, x1: nextBaseProj.px, y1: nextBaseProj.py, color: DR_INT });
-    
+
     drawPoint({ x: headProj.px, y: headProj.py, color: HEAD_INT });
   }
 }