# git-cas v6.0.0 Release Notes

v6.0.0 is the security and storage-shape release for `git-cas`. It simplifies
the encryption scheme model, makes CDC-compatible encryption deduplicate again,
hardens restore and metadata boundaries, and publishes a clearer operator path
for upgrading existing vault entries.

## What's New

- **Current encryption schemes only**: active manifests now use `whole`,
  `framed`, or `convergent`.
- **Convergent encryption**: CDC plus encryption now preserves deduplication by
  deriving per-chunk keys and nonces from plaintext chunk digests.
- **Framed authenticated streaming**: fixed-chunk encrypted stores default to
  `framed`, giving bounded per-frame authenticated restore.
- **AAD always on**: `whole` and `framed` bind slug context into AES-GCM
  authentication data.
- **Vault privacy mode**: encrypted vaults can HMAC slug names so repository
  readers cannot enumerate stored asset names.
- **Vault passphrase verifier**: encrypted vault metadata can authenticate a
  derived vault key before the first entry is added, and legacy encrypted vaults
  gain the verifier on the next keyed vault write.
- **Manifest integrity hashes**: manifests can carry codec-level integrity
  hashes that are verified on read.
- **Runtime-neutral byte contract**: public byte surfaces now use `Uint8Array`
  instead of Node-only `Buffer` types.
- **Simpler library setup**: `await ContentAddressableStore.open({ cwd })`
  creates the default Git-backed facade without requiring callers to wire
  `@git-stunts/plumbing`.
- **Package docs surface cleanup**: the npm package ships public runtime and
  user documentation without internal audits, planning logs, archives, or unused
  media.

## Core Library Compatibility

The v6.0.0 release uses npm registry state as the dependency source of truth:

| Package | npm latest checked during release prep | `git-cas` relationship |
| --- | --- | --- |
| `@git-stunts/plumbing` | `3.0.3` | Direct runtime dependency for async Git command execution. |
| `@git-stunts/vault` | `1.0.1` | Direct runtime dependency for OS-keychain passphrase lookup. |
| `@git-stunts/trailer-codec` | `2.1.1` | Ecosystem companion library; not a `git-cas` runtime dependency because v6 vault history is not trailer-backed. |

## Breaking Changes

- Legacy encryption scheme identifiers (`whole-v1`, `whole-v2`, `framed-v1`,
  `framed-v2`, `convergent-v1`) are rejected by normal reads with
  `LEGACY_SCHEME`.
- v1 whole/framed manifests require full re-encryption because they did not bind
  AAD.
- Direct `CasService` construction now requires explicit `chunker` and
  `compressionAdapter` ports. The `ContentAddressableStore` facade still
  supplies defaults.
- `ContentAddressableStore.open({ cwd })` is now async so the `@git-stunts/plumbing`
  v3 working-directory validation and runtime selection happen behind the
  infrastructure adapter before the facade is returned.
- Custom `CryptoPort` implementations must support HMAC and explicit
  nonce/tag AES-GCM helpers used by convergent encryption and vault privacy.
- Web Crypto no longer falls back to Node for scrypt.
- JSR publication is deferred for this release line because the external
  `jsr`/Deno dry-run toolchain panics before package validation. npm remains
  the supported v6 publication path.

## Upgrade Now

Existing v5 users with encrypted vault entries should dry-run the migration
before restoring old encrypted content:

```bash
npm run upgrade
```

If the dry-run reports entries that need a full migration, use a passphrase file
or stdin source:

```bash
printf '%s\n' '<content-passphrase>' | npm run upgrade -- --execute --passphrase-file -
```

Raw 32-byte key users can migrate with:

```bash
npm run upgrade -- --execute --key-file ./asset.key
```

Privacy-enabled vaults need vault credentials for listing and updates. Prefer a
vault passphrase file/stdin source when the vault passphrase differs from the
content passphrase:

```bash
printf '%s\n' '<vault-passphrase>' \
  | npm run upgrade -- --execute --key-file ./asset.key --vault-passphrase-file -
```

Inline `--passphrase` and `--vault-passphrase` are still accepted for
compatibility, but they print warnings because command-line arguments can leak
through shell history, process listings, CI logs, and terminal transcripts.

## Read Next

- [UPGRADING.md](../../UPGRADING.md): complete v5 to v6 migration guide.
- [CHANGELOG.md](../../CHANGELOG.md): full change history.
- [README.md](../../README.md): current product overview and quick start.
- [SECURITY.md](../../SECURITY.md): security model and vulnerability reporting.