From 0175e1b355fa710e06648bf3c0f101378509bfeb Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Sat, 11 Jul 2026 16:13:34 +0900 Subject: [PATCH 1/9] docs: add research for clone smudge issue --- codex-notes/fix-clone-smudge/research.md | 169 +++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 codex-notes/fix-clone-smudge/research.md diff --git a/codex-notes/fix-clone-smudge/research.md b/codex-notes/fix-clone-smudge/research.md new file mode 100644 index 0000000..d4dcf5a --- /dev/null +++ b/codex-notes/fix-clone-smudge/research.md @@ -0,0 +1,169 @@ +## Relevant Files And Modules + +- `src/main.rs` + - Dispatches CLI commands and implements the filter entry points. + - `clean` loads a named local key, compresses stdin, encrypts, encodes a blob, and writes ciphertext to stdout. + - `smudge` reads stdin, decodes a blob, resolves the blob key id through local key state, decrypts, decompresses, and writes plaintext to stdout. + +- `src/key_store.rs` + - Discovers repository-local state below `.git/git-zcrypt/`. + - Stores keys under `.git/git-zcrypt/keys/`. + - Stores key-id-to-alias mappings in `.git/git-zcrypt/index.json`. + - `read_key_by_id` is the current smudge lookup path and fails if the blob key id is not registered locally. + - Review correction: `.git/git-zcrypt/index.json` is not secret, but it is local-only. The intended direction is for committed manifest files to replace this local index as the durable key-id mapping. + +- `src/git_config.rs` + - `install_filter` writes local Git config: + - `filter.git-zcrypt.clean = git-zcrypt clean --key ` + - `filter.git-zcrypt.smudge = git-zcrypt smudge` + - `filter.git-zcrypt.required = true` + - The required flag means a filter process failure blocks checkout. + - Current filter commands do not pass the target path to `clean` or `smudge`. + +- `src/blob.rs` + - Defines the committed encrypted blob format. + - `decode` validates magic, version, key id length, nonce length, reserved byte, UTF-8 key id, and non-empty key id. + +- `tests/filter_roundtrip.rs` + - Integration tests execute the built `git-zcrypt` binary. + - Existing missing-key coverage currently expects smudge to fail after deleting a key. + +- `.gitattributes` + - Applies `filter=git-zcrypt diff=git-zcrypt` to `secrets/**`. + - Does not currently identify a committed key manifest path. + +- Proposed committed key manifest, per review note + - A non-secret JSON file should be checked into the repository. + - Preferred name direction: `zit-crypt-keys.json` or similar. + - It may live at the repository root or in relevant subdirectories. + - If multiple manifests are found, file-specific lookup should use the first manifest found by walking ancestor directories from the target file directory upward. + - This committed manifest should replace the local `.git/git-zcrypt/index.json` role, not merely duplicate it. + +## Execution Flow And Call Graph + +Clean path: + +1. Git invokes `git-zcrypt clean --key `. +2. `Cli::parse_env` produces `Command::Clean`. +3. `run` calls `clean`. +4. `clean` calls `KeyStore::discover`. +5. `clean` calls `KeyStore::read_key_with_id`. +6. `clean` reads stdin, compresses, encrypts, blob-encodes, and writes stdout. + +Smudge path: + +1. Git invokes `git-zcrypt smudge`. +2. `Cli::parse_env` produces `Command::Smudge`. +3. `run` calls `smudge`. +4. `smudge` calls `KeyStore::discover`. +5. `smudge` reads stdin. +6. `smudge` calls `blob::decode`. +7. `smudge` calls `KeyStore::read_key_by_id`. +8. `read_key_by_id` validates the key id, reads `.git/git-zcrypt/index.json`, and requires a matching alias. +9. If found, it reads the key file and checks that the key computes to the requested key id. +10. `smudge` decrypts, decompresses, and writes plaintext. + +Path-sensitive committed manifest lookup is not possible with the current smudge command shape: + +1. Current Git config invokes `git-zcrypt smudge` with only blob bytes on stdin. +2. The command does not receive the target file path. +3. Without the target path, smudge cannot walk from the target file directory upward to choose the nearest committed manifest. +4. A plan that uses per-directory manifests therefore needs a way to pass the target path into the filter command, likely by changing installed filter config and CLI parsing. + +Failure observed while creating the issue worktree: + +1. Checkout reached `secrets/secret.txt`. +2. Git invoked `git-zcrypt smudge`. +3. The blob decoded with key id `sha256:a8a3cfd8a3833578e4d66ca0acc596fc0aa90df5656d354b3cf91fbd740d4f6c`. +4. No local key index entry existed in the new worktree state. +5. `read_key_by_id` returned `no local key is registered for ...`. +6. Git treated the required smudge filter failure as fatal and aborted checkout. + +## Data Structures And Invariants + +- Encrypted blob format: + - Magic: `GZC1\0\0\0\0` + - Version: `1` + - Header carries key id length, nonce length, and one reserved byte. + - Key id is authenticated metadata and must be present. + - Nonce length must be 12 bytes. + +- Key ids: + - Must be `sha256:` plus 64 lowercase hex characters. + - Are derived from the raw 32-byte key material. + - Are used in committed blobs, unlike local aliases. + +- Local key store: + - Key aliases are local names. + - `.git/git-zcrypt/index.json` maps committed key ids to local aliases. + - Key files live outside the worktree and are not committed. + - Current local index contents are not secret; the problem is clone portability, because the file is stored under `.git/` and is therefore absent from fresh clones. + +- Committed key manifest: + - Should contain only non-secret metadata safe to commit. + - Needs to identify which key ids are expected for files governed by that manifest. + - Should not contain raw key material. + - Replaces the current local key-id mapping role now handled by `.git/git-zcrypt/index.json`. + - Needs a clearly documented relationship to `.gitattributes`: the manifest controls which key ids are expected; attributes control which paths run through the filter. + +## Existing Architectural Patterns + +- Modules are small and direct: CLI parsing, Git config, key storage, blob encoding, compression, and crypto are separate. +- Errors use the repository-local `Error` type with `Context`, `bail!`, and `ensure!`. +- Secret key bytes use `Zeroizing>`. +- Tests prefer black-box integration through the compiled binary for filter behavior. + +## Naming Conventions + +- CLI commands are explicit verbs: `generate-key`, `derive-key`, `install-filter`, `delete-key`, `clean`, `smudge`. +- Key aliases are called `key` or `name`. +- Stable committed identifiers are called `key_id`. +- Tests are descriptive snake_case function names. + +## Error Handling Patterns + +- Invalid user input and malformed formats return `Error::msg`. +- `Context` wraps IO and parse failures with path or operation context. +- Existing smudge behavior treats missing local key registration as a hard error. +- Git filter failures surface through stderr and non-zero exit status. +- Review note resolved: warning text is preferred when smudge passes through because a local key is unavailable, as long as the warning does not inhibit Git filter behavior. + +## Potential Pitfalls + +- Passing through every smudge error would hide corruption or wrong-key failures. + - Review note: To address this, the repository should check in a non-secret key manifest. The preferred name is `zit-crypt-keys.json` or similar. It can be placed at the repo root or in relevant directories. If multiple manifests are found, use the first one in the target file's ancestor directories, searched from the file directory upward. +- Passing through only missing local key registration preserves validation for malformed blobs and cryptographic failures. +- If smudge succeeds without decrypting, the worktree file contains encrypted bytes. That is acceptable for clone completion but must be documented. +- Because `filter.git-zcrypt.required=true`, any non-zero smudge exit during checkout remains fatal. +- Tests that run Git checkout/clone need filter config available in the cloned repo or command-local config, since local Git config is not committed. +- If a file was checked out as encrypted pass-through bytes before keys were registered, Git will not necessarily rewrite it to plaintext merely because key state changes later. Documentation or setup flow may need to tell users how to force Git to run smudge again after registering the key. +- A manifest lookup based on ancestor directories depends on knowing the target path. The current smudge command lacks that information. +- Keeping both committed manifest files and `.git/git-zcrypt/index.json` as independent key-id mapping sources would create drift risk. The intended design should replace the local index with committed manifests rather than maintaining two durable mappings. + +## Constraints + +- The fix should keep one logical PR scope: clone/checkout with unavailable local key should not fail. +- Existing encrypted blob format should not change. +- Existing key file format should not change. +- `.git/git-zcrypt/index.json` has never been secret, but it is local-only and should be replaced by committed manifest lookup rather than kept as the durable mapping. +- Normal decryption with a registered key must keep working. +- Missing-key pass-through must not weaken tamper detection when a key is registered. +- Warning text on missing-key pass-through should be included unless testing shows it breaks Git filter behavior. +- Per-directory manifest selection requires path-aware filter invocation. + +## Unknowns + +- Whether `install-filter` should keep `required=true`. + - Review note: this is not decided yet. + - Current research implication: `required=true` is compatible with clone-safe behavior if smudge exits successfully only for the specific missing-local-key case. Disabling `required=true` globally would also let malformed blobs or other filter failures pass checkout more easily, so it needs explicit plan-level justification if chosen. +- Exact user-facing recovery command after importing or deriving the key for a clone that currently has encrypted pass-through bytes in the worktree. + - The issue is not key registration itself; it is making Git apply smudge again to files already materialized as encrypted bytes. + - Candidate commands belong in the plan/test phase, where they can be validated instead of guessed. +- Exact committed manifest schema. + - The research identifies the need for committed, non-secret key-id metadata, but schema choices belong in the plan. +- Migration/removal strategy for `.git/git-zcrypt/index.json`. + - Current commands write and read this local index. + - The plan must decide whether to delete this code path immediately, retain a compatibility fallback, or convert existing local index data into committed manifests. +- Exact installed filter command shape for passing target paths. + - The current command is insufficient for nearest-ancestor manifest lookup. + - The plan must verify the Git filter placeholder behavior locally before implementation. From 532aaa04ee87e02de220661e7b73570afb85c665 Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Sat, 11 Jul 2026 16:25:57 +0900 Subject: [PATCH 2/9] docs: add plan for clone smudge issue --- .../fix-clone-smudge/feature_list.json | 58 ++++++ codex-notes/fix-clone-smudge/plan.md | 193 ++++++++++++++++++ 2 files changed, 251 insertions(+) create mode 100644 codex-notes/fix-clone-smudge/feature_list.json create mode 100644 codex-notes/fix-clone-smudge/plan.md diff --git a/codex-notes/fix-clone-smudge/feature_list.json b/codex-notes/fix-clone-smudge/feature_list.json new file mode 100644 index 0000000..228967e --- /dev/null +++ b/codex-notes/fix-clone-smudge/feature_list.json @@ -0,0 +1,58 @@ +{ + "features": [ + { + "id": "path-aware-filters", + "description": "Update installed filter commands and CLI parsing so clean and smudge receive the filtered file path.", + "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact && cargo test git_config::tests::install_filter_writes_local_git_config -- --exact", + "passes": false + }, + { + "id": "committed-key-manifest", + "description": "Add committed zit-crypt-keys.json parsing, formatting, validation, and nearest-ancestor lookup.", + "validation": "cargo test key_manifest::tests", + "passes": false + }, + { + "id": "replace-local-index", + "description": "Replace .git/git-zcrypt/index.json as the durable key-id mapping with committed manifest lookup and local key scanning.", + "validation": "cargo test key_store::tests", + "passes": false + }, + { + "id": "clean-updates-manifest", + "description": "Make clean update the nearest committed manifest for the filtered path with the selected key id.", + "validation": "cargo test --test filter_roundtrip clean_updates_committed_key_manifest -- --exact", + "passes": false + }, + { + "id": "smudge-authorizes-by-manifest", + "description": "Make smudge require the blob key id to be declared by the nearest committed manifest.", + "validation": "cargo test --test filter_roundtrip smudge_rejects_manifest_mismatch -- --exact", + "passes": false + }, + { + "id": "missing-key-pass-through", + "description": "Make smudge warn and pass encrypted bytes through when the manifest authorizes the blob key id but no local key is available.", + "validation": "cargo test --test filter_roundtrip missing_key_smudge_passes_through_manifest_authorized_blob -- --exact", + "passes": false + }, + { + "id": "clone-without-key", + "description": "Add clone/checkout coverage showing a repo with committed manifests can be checked out without local key material.", + "validation": "cargo test --test filter_roundtrip clone_without_local_key_checks_out_encrypted_blob -- --exact", + "passes": false + }, + { + "id": "document-manifest-flow", + "description": "Document committed manifests, clone-without-key behavior, and the validated re-smudge command after key setup.", + "validation": "rg -q 'zit-crypt-keys\\.json' README.md docs/data-formats.md", + "passes": false + }, + { + "id": "full-validation", + "description": "Run formatting and the full test suite after implementation.", + "validation": "cargo fmt --check && cargo test", + "passes": false + } + ] +} diff --git a/codex-notes/fix-clone-smudge/plan.md b/codex-notes/fix-clone-smudge/plan.md new file mode 100644 index 0000000..52dfc6c --- /dev/null +++ b/codex-notes/fix-clone-smudge/plan.md @@ -0,0 +1,193 @@ +## Overview + +Fix issue 8 by making key-id metadata clone-portable. The local `.git/git-zcrypt/index.json` is non-secret but unavailable in fresh clones, so it should be replaced as the durable mapping by committed non-secret manifest files named `zit-crypt-keys.json`. + +The manifest lookup must be path-sensitive: for a filtered file, use the nearest `zit-crypt-keys.json` found by walking from the file's directory upward toward the repository root. To support that, installed Git filter commands must pass the filtered path to `clean` and `smudge` using Git's filter path placeholder. The implementation should verify the placeholder behavior in tests before relying on it. + +When smudge sees a well-formed encrypted blob whose key id is allowed by the committed manifest but whose local key file is not present, it should warn to stderr, write the original encrypted bytes to stdout, and exit successfully. This lets clone and checkout complete without local key material. Malformed blobs, manifest mismatches, wrong keys, and decryption failures with an available key remain hard failures. + +## Files To Change + +- `src/cli.rs` + - Add path options to the filter commands. + - `clean` should accept `--path ` in addition to `--key `. + - `smudge` should accept `--path `. + +- `src/git_config.rs` + - Install path-aware filter commands, likely: + - `git-zcrypt clean --key --path %f` + - `git-zcrypt smudge --path %f` + - Keep `filter.git-zcrypt.required=true` initially. + - Update `status` to report committed manifest state instead of local index state. + +- `src/main.rs` + - Pass the target path from CLI parsing into `clean` and `smudge`. + - On clean, update the nearest committed manifest for the path with the blob key id produced for the selected key. + - On smudge, use the target path to find the nearest committed manifest and validate that the blob key id is declared there. + - If the manifest declares the blob key id but no local key material exists, warn and pass encrypted bytes through unchanged. + +- `src/key_store.rs` + - Stop using `.git/git-zcrypt/index.json` as the durable key-id mapping. + - Keep local key files under `.git/git-zcrypt/keys/`. + - Resolve local key material by computing each local key file's key id and matching it to the manifest-declared blob key id. + - Preserve duplicate-key-material detection where practical by scanning local keys. + - Remove or deprecate index write/read paths after replacement behavior is covered. + +- New module, likely `src/key_manifest.rs` + - Own committed `zit-crypt-keys.json` parsing and formatting. + - Find the nearest manifest for a target path by walking ancestors from file directory upward. + - Update manifests atomically when clean introduces a key id. + - Validate key ids with existing `key_store::validate_key_id`. + +- `tests/filter_roundtrip.rs` + - Add integration coverage for path-aware filter commands. + - Add clone/checkout coverage with committed manifests but no local key material. + - Update existing missing-key expectations to pass-through behavior only when the manifest authorizes the key id. + +- `README.md` + - Document `zit-crypt-keys.json`, nearest-ancestor lookup, clone behavior without local keys, and how to re-smudge files after importing or deriving keys. + +- `docs/data-formats.md` + - Document the committed manifest format. + +- `codex-notes/fix-clone-smudge/feature_list.json` + - Track implementation tasks and validation commands. + +## Detailed Implementation Steps + +1. Verify Git filter path placeholder behavior. + - Add a focused integration test or temporary test harness that configures a filter command containing `%f` and confirms Git passes the filtered path as an argument. + - Use the validated command shape in `install_filter`. + - If `%f` needs quoting or has path separator edge cases, encode that in tests before implementation proceeds. + +2. Add CLI path parsing for filters. + - Change `Command::Clean { key }` to `Command::Clean { key, path }`. + - Change `Command::Smudge` to `Command::Smudge { path }`. + - Add tests for: + - `clean --key default --path secrets/a.txt` + - `smudge --path secrets/a.txt` + - duplicate/missing/unexpected options. + +3. Introduce committed manifest support. + - Use `zit-crypt-keys.json` as the manifest filename. + - Start with a constrained JSON object rather than free-form JSON. + - Proposed schema for planning: + ```json + { + "version": 1, + "keys": [ + "sha256:<64 lowercase hex chars>" + ] + } + ``` + - Keep keys sorted lexicographically for stable diffs. + - Reject malformed JSON, unsupported version, missing `keys`, duplicate key ids, and invalid key ids. + - Find the relevant manifest by walking ancestors of the filtered file path from deepest to shallowest. + +4. Replace local index lookup with local key scanning. + - Keep `.git/git-zcrypt/keys/.key` as the local secret-key storage. + - Add a method that scans local key files, computes each key id, and returns the matching key for a requested key id. + - If no local key matches, return a typed or distinguishable missing-local-key result. + - If a local key file is malformed, surface a warning or hard error according to the command context: + - Smudge for a manifest-declared key with no matching local key should pass through only when no matching key exists. + - Smudge should still fail if it finds a matching key but decrypt/decompress fails. + +5. Update key creation commands. + - `generate-key`, `derive-key`, and `import-key` should still create local key files. + - They should not write `.git/git-zcrypt/index.json`. + - Duplicate key material detection should scan local keys rather than consult local index. + - `delete-key` should remove only local key files; it should not remove committed manifest declarations because those describe repository data, not local possession. + +6. Update clean behavior. + - Resolve selected local key alias as today. + - Compute its key id and encrypt with that id as today. + - Find or create the nearest applicable `zit-crypt-keys.json` for the target path. + - Add the key id if absent and write the manifest with stable formatting. + - Do not write `.git/git-zcrypt/index.json`. + +7. Update smudge behavior. + - Decode the blob first; malformed blobs remain fatal. + - Find the nearest committed manifest for the target path. + - Fail if no manifest exists or if the blob key id is not listed in the manifest. + - Scan local key files for a matching key id. + - If no matching key is present, print a warning to stderr, write the original encrypted input to stdout, and return success. + - If a matching key is present, decrypt and decompress as today. + +8. Preserve `filter.git-zcrypt.required=true` unless validation shows it prevents the intended pass-through. + - The intended pass-through exits with status 0, so `required=true` should remain compatible. + - Keeping it true preserves hard failures for malformed blobs and manifest mismatches. + +9. Document recovery after key setup. + - Validate a concrete command for re-smudging pass-through files after the user imports or derives a key. + - Candidate to validate in tests: `git checkout -- path` or an equivalent forced checkout command. + - Document only the validated command. + +10. Update data-format documentation and README. + - Explain that `zit-crypt-keys.json` is safe to commit because it contains key ids, not raw keys. + - Explain nearest-ancestor lookup. + - Explain that a clone without local keys may contain encrypted pass-through bytes until keys are registered and files are re-smudged. + +## Alternatives Considered + +- Only pass through missing local key errors without a committed manifest. + - Rejected because it hides too much: a fresh clone cannot know whether the key id is expected for that path or whether the blob is unexpected repository data. + +- Commit `.git/git-zcrypt/index.json` directly. + - Rejected because files under `.git/` are not part of the worktree and cannot be committed normally. The concept is useful, but it needs a committed worktree manifest file. + +- Keep both `.git/git-zcrypt/index.json` and committed manifests. + - Rejected as the durable design because two mapping sources can drift. A short compatibility fallback can be considered only if needed, but the target behavior should use committed manifests. + +- Disable `filter.git-zcrypt.required`. + - Rejected for the initial plan because a status-0 pass-through for the specific missing-local-key case should be compatible with `required=true`, while disabling it would make unrelated filter failures easier to miss. + +- Put all key ids in one root-only manifest. + - Rejected because the requested behavior allows manifests in relevant subdirectories with nearest-ancestor lookup. + +## Risks + +- Git path placeholder behavior may differ from assumptions. This must be validated before implementing path-sensitive lookup. +- Existing repositories with `.git/git-zcrypt/index.json` will need a transition path or clear breakage note. +- Pass-through files are encrypted bytes in the worktree; users need a validated recovery command after key setup. +- Manifest lookup can fail if the file path is absolute, outside the worktree, or contains `..`; path normalization must be conservative. +- Clean updating a committed manifest means normal encryption can modify both the secret file and `zit-crypt-keys.json`; docs and tests should make this expected. +- Scanning all local key files for each smudge may be slower than index lookup in repositories with many keys. This is acceptable initially, but the implementation should keep the scan simple and measurable. + +## Test Strategy + +- Unit tests: + - CLI parses path-aware `clean` and `smudge`. + - Manifest parser rejects malformed schemas and invalid key ids. + - Manifest formatter produces stable sorted output. + - Manifest lookup chooses the nearest ancestor manifest. + - Local key scanning resolves a key by computed key id. + +- Integration tests: + - `cargo test --test filter_roundtrip raw_key_round_trip_uses_hash_prefixed_key_id -- --exact` + - New test: clean writes/updates `zit-crypt-keys.json` for the filtered path. + - New test: smudge fails when the manifest is missing. + - New test: smudge fails when the manifest does not list the blob key id. + - New test: smudge passes through with a warning when the manifest lists the key id but no local key exists. + - New test: clone/checkout with committed manifest and no local key succeeds and leaves encrypted bytes in the worktree. + - New test: after importing/deriving the key, the validated recovery command rewrites pass-through bytes to plaintext. + +- Full validation: + - `cargo fmt --check` + - `cargo test` + - If binary-size-sensitive changes are expected from new dependencies, avoid new dependencies; otherwise build release and report size. + +## Assumptions + +- `zit-crypt-keys.json` is an acceptable final filename unless review changes it. +- The manifest contains key ids only, not raw keys. +- The local secret key files remain in `.git/git-zcrypt/keys/`. +- A manifest-declared missing local key should warn and pass through. +- A manifest mismatch should fail even if the local key exists. +- `required=true` should remain unless tests show it blocks the intended behavior. + +## Open Questions + +- Confirm final manifest filename: `zit-crypt-keys.json` versus another exact spelling. +- Confirm final manifest schema before implementation. +- Decide whether to retain a short compatibility fallback for existing `.git/git-zcrypt/index.json`, or remove it entirely in this PR. +- Confirm the validated re-smudge command to document after key setup. From 9e7e50a302ab9cd8dd7f66e2898b3527bbaa6897 Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Sat, 11 Jul 2026 21:53:37 +0900 Subject: [PATCH 3/9] docs: revise clone smudge implementation plan --- .../fix-clone-smudge/feature_list.json | 14 ++- codex-notes/fix-clone-smudge/plan.md | 89 ++++++++++++------- 2 files changed, 67 insertions(+), 36 deletions(-) diff --git a/codex-notes/fix-clone-smudge/feature_list.json b/codex-notes/fix-clone-smudge/feature_list.json index 228967e..c388db9 100644 --- a/codex-notes/fix-clone-smudge/feature_list.json +++ b/codex-notes/fix-clone-smudge/feature_list.json @@ -6,9 +6,15 @@ "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact && cargo test git_config::tests::install_filter_writes_local_git_config -- --exact", "passes": false }, + { + "id": "init-manifest-command", + "description": "Add git-zcrypt init-manifest with optional --path to create git-zcrypt-keys.json in the current or specified directory.", + "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact && cargo test --test filter_roundtrip init_manifest_creates_committed_key_manifest -- --exact", + "passes": false + }, { "id": "committed-key-manifest", - "description": "Add committed zit-crypt-keys.json parsing, formatting, validation, and nearest-ancestor lookup.", + "description": "Add committed git-zcrypt-keys.json parsing, formatting, validation, initialization, and nearest-ancestor lookup.", "validation": "cargo test key_manifest::tests", "passes": false }, @@ -20,7 +26,7 @@ }, { "id": "clean-updates-manifest", - "description": "Make clean update the nearest committed manifest for the filtered path with the selected key id.", + "description": "Make clean update the nearest existing committed manifest for the filtered path with the selected key id and fail clearly when none exists.", "validation": "cargo test --test filter_roundtrip clean_updates_committed_key_manifest -- --exact", "passes": false }, @@ -44,8 +50,8 @@ }, { "id": "document-manifest-flow", - "description": "Document committed manifests, clone-without-key behavior, and the validated re-smudge command after key setup.", - "validation": "rg -q 'zit-crypt-keys\\.json' README.md docs/data-formats.md", + "description": "Document init-manifest, committed manifests, clone-without-key behavior, and the validated re-smudge command after key setup.", + "validation": "rg -q 'git-zcrypt-keys\\.json' README.md docs/data-formats.md", "passes": false }, { diff --git a/codex-notes/fix-clone-smudge/plan.md b/codex-notes/fix-clone-smudge/plan.md index 52dfc6c..d68daee 100644 --- a/codex-notes/fix-clone-smudge/plan.md +++ b/codex-notes/fix-clone-smudge/plan.md @@ -1,14 +1,16 @@ ## Overview -Fix issue 8 by making key-id metadata clone-portable. The local `.git/git-zcrypt/index.json` is non-secret but unavailable in fresh clones, so it should be replaced as the durable mapping by committed non-secret manifest files named `zit-crypt-keys.json`. +Fix issue 8 by making key-id metadata clone-portable. The local `.git/git-zcrypt/index.json` is non-secret but unavailable in fresh clones, so it should be replaced as the durable mapping by committed non-secret manifest files named `git-zcrypt-keys.json`. -The manifest lookup must be path-sensitive: for a filtered file, use the nearest `zit-crypt-keys.json` found by walking from the file's directory upward toward the repository root. To support that, installed Git filter commands must pass the filtered path to `clean` and `smudge` using Git's filter path placeholder. The implementation should verify the placeholder behavior in tests before relying on it. +The manifest lookup must be path-sensitive: for a filtered file, use the nearest `git-zcrypt-keys.json` found by walking from the file's directory upward toward the repository root. To support that, installed Git filter commands must pass the filtered path to `clean` and `smudge` using Git's filter path placeholder. The implementation should verify the placeholder behavior in tests before relying on it. When smudge sees a well-formed encrypted blob whose key id is allowed by the committed manifest but whose local key file is not present, it should warn to stderr, write the original encrypted bytes to stdout, and exit successfully. This lets clone and checkout complete without local key material. Malformed blobs, manifest mismatches, wrong keys, and decryption failures with an available key remain hard failures. ## Files To Change - `src/cli.rs` + - Add an `init-manifest` command. + - `init-manifest` should default to the current directory and accept `--path ` to initialize a manifest in a specified directory. - Add path options to the filter commands. - `clean` should accept `--path ` in addition to `--key `. - `smudge` should accept `--path `. @@ -21,6 +23,7 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com - Update `status` to report committed manifest state instead of local index state. - `src/main.rs` + - Implement `init-manifest` by creating `git-zcrypt-keys.json` in the current or specified directory. - Pass the target path from CLI parsing into `clean` and `smudge`. - On clean, update the nearest committed manifest for the path with the blob key id produced for the selected key. - On smudge, use the target path to find the nearest committed manifest and validate that the blob key id is declared there. @@ -34,10 +37,12 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com - Remove or deprecate index write/read paths after replacement behavior is covered. - New module, likely `src/key_manifest.rs` - - Own committed `zit-crypt-keys.json` parsing and formatting. + - Own committed `git-zcrypt-keys.json` parsing and formatting. + - Initialize empty manifests. - Find the nearest manifest for a target path by walking ancestors from file directory upward. - Update manifests atomically when clean introduces a key id. - - Validate key ids with existing `key_store::validate_key_id`. + - Reuse the existing constrained JSON map shape from `.git/git-zcrypt/index.json`. + - Validate key ids with existing `key_store::validate_key_id` and names with existing key-name validation. - `tests/filter_roundtrip.rs` - Add integration coverage for path-aware filter commands. @@ -45,7 +50,7 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com - Update existing missing-key expectations to pass-through behavior only when the manifest authorizes the key id. - `README.md` - - Document `zit-crypt-keys.json`, nearest-ancestor lookup, clone behavior without local keys, and how to re-smudge files after importing or deriving keys. + - Document `init-manifest`, `git-zcrypt-keys.json`, nearest-ancestor lookup, clone behavior without local keys, and how to re-smudge files after importing or deriving keys. - `docs/data-formats.md` - Document the committed manifest format. @@ -60,29 +65,38 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com - Use the validated command shape in `install_filter`. - If `%f` needs quoting or has path separator edge cases, encode that in tests before implementation proceeds. -2. Add CLI path parsing for filters. +2. Add CLI parsing for manifest initialization and path-aware filters. + - Add `Command::InitManifest { path }`. + - Parse `init-manifest` with optional `--path `. + - Default `init-manifest` to the current directory when `--path` is omitted. - Change `Command::Clean { key }` to `Command::Clean { key, path }`. - Change `Command::Smudge` to `Command::Smudge { path }`. - Add tests for: + - `init-manifest` + - `init-manifest --path secrets/team-a` - `clean --key default --path secrets/a.txt` - `smudge --path secrets/a.txt` - duplicate/missing/unexpected options. 3. Introduce committed manifest support. - - Use `zit-crypt-keys.json` as the manifest filename. - - Start with a constrained JSON object rather than free-form JSON. - - Proposed schema for planning: + - Use `git-zcrypt-keys.json` as the manifest filename. + - Keep the current `.git/git-zcrypt/index.json` schema instead of inventing a new one: a constrained JSON object mapping key id to key name. + - Example: ```json { - "version": 1, - "keys": [ - "sha256:<64 lowercase hex chars>" - ] + "sha256:<64 lowercase hex chars>": "default" } ``` - - Keep keys sorted lexicographically for stable diffs. - - Reject malformed JSON, unsupported version, missing `keys`, duplicate key ids, and invalid key ids. + - Keep entries sorted lexicographically by key id for stable diffs. + - Reject malformed JSON, duplicate keys as far as the parser can detect, invalid key ids, and invalid key names. + - Add an initializer that creates an empty manifest: + ```json + {} + ``` - Find the relevant manifest by walking ancestors of the filtered file path from deepest to shallowest. + - `clean` should update the nearest existing manifest. + - If no manifest exists anywhere in the repository, `clean` should create a root `git-zcrypt-keys.json`. + - Users create subdirectory manifests explicitly with `init-manifest --path `. 4. Replace local index lookup with local key scanning. - Keep `.git/git-zcrypt/keys/.key` as the local secret-key storage. @@ -94,14 +108,16 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com 5. Update key creation commands. - `generate-key`, `derive-key`, and `import-key` should still create local key files. + - They should update the nearest `git-zcrypt-keys.json` only when a command has enough path context; otherwise they should create local key material only and leave manifest registration to `clean`. - They should not write `.git/git-zcrypt/index.json`. - - Duplicate key material detection should scan local keys rather than consult local index. + - Duplicate key material detection should scan local keys and committed manifests rather than consult local index. - `delete-key` should remove only local key files; it should not remove committed manifest declarations because those describe repository data, not local possession. 6. Update clean behavior. - Resolve selected local key alias as today. - Compute its key id and encrypt with that id as today. - - Find or create the nearest applicable `zit-crypt-keys.json` for the target path. + - Find the nearest applicable `git-zcrypt-keys.json` for the target path. + - If no manifest exists in any ancestor directory up to the repository root, create a root `git-zcrypt-keys.json`. - Add the key id if absent and write the manifest with stable formatting. - Do not write `.git/git-zcrypt/index.json`. @@ -118,12 +134,12 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com - Keeping it true preserves hard failures for malformed blobs and manifest mismatches. 9. Document recovery after key setup. - - Validate a concrete command for re-smudging pass-through files after the user imports or derives a key. - - Candidate to validate in tests: `git checkout -- path` or an equivalent forced checkout command. - - Document only the validated command. + - Validate `git restore --source=HEAD --worktree -- ` for re-smudging pass-through files after the user imports or derives a key. + - Document this command if the integration test confirms it rewrites encrypted pass-through bytes to plaintext. 10. Update data-format documentation and README. - - Explain that `zit-crypt-keys.json` is safe to commit because it contains key ids, not raw keys. + - Explain that `git-zcrypt-keys.json` is safe to commit because it contains key ids, not raw keys. + - Explain how to create root and subdirectory manifests with `git-zcrypt init-manifest`. - Explain nearest-ancestor lookup. - Explain that a clone without local keys may contain encrypted pass-through bytes until keys are registered and files are re-smudged. @@ -136,7 +152,10 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com - Rejected because files under `.git/` are not part of the worktree and cannot be committed normally. The concept is useful, but it needs a committed worktree manifest file. - Keep both `.git/git-zcrypt/index.json` and committed manifests. - - Rejected as the durable design because two mapping sources can drift. A short compatibility fallback can be considered only if needed, but the target behavior should use committed manifests. + - Rejected because two mapping sources can drift and there is no compatibility guarantee needed for this change. + +- Change the manifest schema to a versioned `{ "version": 1, "keys": [...] }` object. + - Rejected because the existing `index.json` constrained map shape is already adequate and simpler. - Disable `filter.git-zcrypt.required`. - Rejected for the initial plan because a status-0 pass-through for the specific missing-local-key case should be compatible with `required=true`, while disabling it would make unrelated filter failures easier to miss. @@ -144,32 +163,40 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com - Put all key ids in one root-only manifest. - Rejected because the requested behavior allows manifests in relevant subdirectories with nearest-ancestor lookup. +- Have `clean` automatically create subdirectory manifests. + - Rejected because automatic creation cannot know the intended subdirectory boundary. `clean` should create a root manifest only when no manifest exists, otherwise update the nearest existing manifest. `init-manifest --path ` gives users an explicit way to create subdirectory boundaries. + ## Risks - Git path placeholder behavior may differ from assumptions. This must be validated before implementing path-sensitive lookup. -- Existing repositories with `.git/git-zcrypt/index.json` will need a transition path or clear breakage note. +- Existing repositories with `.git/git-zcrypt/index.json` will need a clear breakage note; no compatibility fallback is planned. - Pass-through files are encrypted bytes in the worktree; users need a validated recovery command after key setup. - Manifest lookup can fail if the file path is absolute, outside the worktree, or contains `..`; path normalization must be conservative. -- Clean updating a committed manifest means normal encryption can modify both the secret file and `zit-crypt-keys.json`; docs and tests should make this expected. +- Clean updating a committed manifest means normal encryption can modify both the secret file and `git-zcrypt-keys.json`; docs and tests should make this expected. +- If no manifest exists before cleaning filtered files, clean will create a root manifest. Users must explicitly create subdirectory manifests when they want narrower manifest boundaries. - Scanning all local key files for each smudge may be slower than index lookup in repositories with many keys. This is acceptable initially, but the implementation should keep the scan simple and measurable. ## Test Strategy - Unit tests: + - CLI parses `init-manifest` with and without `--path`. - CLI parses path-aware `clean` and `smudge`. - - Manifest parser rejects malformed schemas and invalid key ids. + - Manifest parser accepts the existing index-style map and rejects malformed maps, invalid key ids, and invalid key names. - Manifest formatter produces stable sorted output. + - Manifest initializer writes an empty index-style map. - Manifest lookup chooses the nearest ancestor manifest. - Local key scanning resolves a key by computed key id. - Integration tests: - `cargo test --test filter_roundtrip raw_key_round_trip_uses_hash_prefixed_key_id -- --exact` - - New test: clean writes/updates `zit-crypt-keys.json` for the filtered path. + - New test: `init-manifest` creates `git-zcrypt-keys.json` in the current directory. + - New test: `init-manifest --path ` creates `git-zcrypt-keys.json` in a subdirectory. + - New test: clean writes/updates `git-zcrypt-keys.json` for the filtered path. - New test: smudge fails when the manifest is missing. - New test: smudge fails when the manifest does not list the blob key id. - New test: smudge passes through with a warning when the manifest lists the key id but no local key exists. - New test: clone/checkout with committed manifest and no local key succeeds and leaves encrypted bytes in the worktree. - - New test: after importing/deriving the key, the validated recovery command rewrites pass-through bytes to plaintext. + - New test: after importing/deriving the key, `git restore --source=HEAD --worktree -- ` rewrites pass-through bytes to plaintext. - Full validation: - `cargo fmt --check` @@ -178,8 +205,9 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com ## Assumptions -- `zit-crypt-keys.json` is an acceptable final filename unless review changes it. +- `git-zcrypt-keys.json` is the planned manifest filename. - The manifest contains key ids only, not raw keys. +- Users create subdirectory manifests explicitly with `git-zcrypt init-manifest --path `; root manifests can also be created explicitly, but `clean` creates the root manifest when no manifest exists. - The local secret key files remain in `.git/git-zcrypt/keys/`. - A manifest-declared missing local key should warn and pass through. - A manifest mismatch should fail even if the local key exists. @@ -187,7 +215,4 @@ When smudge sees a well-formed encrypted blob whose key id is allowed by the com ## Open Questions -- Confirm final manifest filename: `zit-crypt-keys.json` versus another exact spelling. -- Confirm final manifest schema before implementation. -- Decide whether to retain a short compatibility fallback for existing `.git/git-zcrypt/index.json`, or remove it entirely in this PR. -- Confirm the validated re-smudge command to document after key setup. +- Confirm `git restore --source=HEAD --worktree -- ` in implementation tests before documenting it as the recovery command. From 3b8f834b576b2d9f0663eb7519cfb8d4b959139c Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Sat, 11 Jul 2026 22:06:39 +0900 Subject: [PATCH 4/9] fix: allow clone without local zcrypt keys --- README.md | 49 ++- .../fix-clone-smudge/feature_list.json | 24 +- docs/data-formats.md | 43 +-- src/cli.rs | 88 +++++- src/git_config.rs | 42 +-- src/key_manifest.rs | 213 +++++++++++++ src/key_store.rs | 153 ++-------- src/main.rs | 27 +- tests/filter_roundtrip.rs | 289 +++++++++++++++++- 9 files changed, 713 insertions(+), 215 deletions(-) create mode 100644 src/key_manifest.rs diff --git a/README.md b/README.md index 73c35b3..876aea9 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,9 @@ and encrypts them with ChaCha20-Poly1305 before Git stores them. Keys are stored locally under `.git/git-zcrypt/`. Raw 32-byte keys can be generated or imported directly, and password-derived keys can be created with -Argon2id. Encrypted blobs store a hash-prefixed key id such as `sha256:...`; -local aliases map to those ids through `.git/git-zcrypt/index.json`. +Argon2id. Encrypted blobs store a hash-prefixed key id such as `sha256:...`. +Committed `git-zcrypt-keys.json` manifests map those key ids to local aliases +without storing raw key material. ## Install @@ -59,7 +60,8 @@ a8a3cfd8a3833578e4d66ca0acc596fc0aa90df5656d354b3cf91fbd740d4f6c - ``` After `derive-key`, the key lives under `.git/git-zcrypt/keys/` in the versioned -local key format, and the key id is recorded in `.git/git-zcrypt/index.json`: +local key format. The key id is recorded in a committed manifest when filtered +content is cleaned: ```console $ hexdump -C .git/git-zcrypt/keys/test.key @@ -68,12 +70,25 @@ $ hexdump -C .git/git-zcrypt/keys/test.key 00000020 44 69 a4 62 0b fc 83 90 9e 0c f4 83 |Di.b........| $ tail -c 32 .git/git-zcrypt/keys/test.key | shasum -a 256 a8a3cfd8a3833578e4d66ca0acc596fc0aa90df5656d354b3cf91fbd740d4f6c - -$ cat .git/git-zcrypt/index.json +$ cat git-zcrypt-keys.json { "sha256:a8a3cfd8a3833578e4d66ca0acc596fc0aa90df5656d354b3cf91fbd740d4f6c": "test" } ``` +Create a root manifest explicitly when setting up a repository, or let the first +clean create it automatically at the repository root: + +```sh +git-zcrypt init-manifest +``` + +To create a narrower manifest boundary for a subdirectory, initialize one there: + +```sh +git-zcrypt init-manifest --path secrets/team-a +``` + Install the local Git filter config: ```sh @@ -112,11 +127,11 @@ original bytes: ```console $ ": "" +} +``` + +The file contains no raw key material and is safe to commit. Entries are written +in lexicographic key-id order. Duplicate JSON keys are rejected by the parser as +far as they can be observed, and both key ids and key names are validated when a +manifest is read. Key names may contain only ASCII letters, digits, `_`, and +`-`. + +For a filtered path, `git-zcrypt` uses the nearest `git-zcrypt-keys.json` found +by walking from the file's directory upward toward the repository root. A root +manifest can be created with `git-zcrypt init-manifest`; subdirectory manifests +can be created with `git-zcrypt init-manifest --path `. + ## Local Key File Format Each local key file is a versioned binary wrapper around raw key material: @@ -52,16 +74,3 @@ imported, and password-derived keys all persist in this same versioned format. Password-derived keys do not persist Argon2id parameters, salt, or other KDF metadata. `export-key` writes only the raw 32-byte key payload for backup or transfer. - -The local key index maps committed blob key ids back to local aliases: - -```json -{ - "sha256:<64 lowercase hex chars>": "" -} -``` - -The index file is `.git/git-zcrypt/index.json`. It is a constrained JSON object -whose keys are hash-prefixed key ids and whose values are key names. Entries are -written in lexicographic key order, duplicate JSON keys are rejected, and both -key ids and key names are validated when the index is read. diff --git a/src/cli.rs b/src/cli.rs index 63af9af..d8ea724 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -13,6 +13,7 @@ pub(crate) struct Cli { pub(crate) enum Command { Help, Init, + InitManifest { path: PathBuf }, GenerateKey { key: String }, ImportKey { key: String, input: PathBuf }, DeriveKey { key: String, stdin: bool }, @@ -20,8 +21,8 @@ pub(crate) enum Command { DeleteKey { key: String }, InstallFilter { key: String }, Status, - Clean { key: String }, - Smudge, + Clean { key: String, path: PathBuf }, + Smudge { path: PathBuf }, } impl Cli { @@ -47,6 +48,9 @@ impl Cli { args.expect_empty("init")?; Command::Init } + "init-manifest" => Command::InitManifest { + path: parse_optional_path("init-manifest", &mut args)?, + }, "generate-key" => Command::GenerateKey { key: parse_key_only("generate-key", &mut args, true)?, }, @@ -72,13 +76,13 @@ impl Cli { args.expect_empty("status")?; Command::Status } - "clean" => Command::Clean { - key: parse_key_only("clean", &mut args, false)?, - }, - "smudge" => { - args.expect_empty("smudge")?; - Command::Smudge + "clean" => { + let (key, path) = parse_key_and_path("clean", &mut args, "--path")?; + Command::Clean { key, path } } + "smudge" => Command::Smudge { + path: parse_required_path("smudge", &mut args, "--path")?, + }, _ => bail!("unknown command '{command}'\n\n{}", usage()), }; Ok(Self { command }) @@ -179,6 +183,46 @@ fn parse_key_and_path( Ok((key, path)) } +fn parse_optional_path(command: &str, args: &mut Args) -> Result { + let mut path = None; + while let Some(arg) = args.next() { + let (option, inline_value) = parse_option(command, arg)?; + if option == "--path" { + set_once( + command, + option, + &mut path, + PathBuf::from(option_value(command, option, inline_value, args)?), + )?; + } else { + bail!("{command}: unexpected option '{option}'"); + } + } + Ok(path.unwrap_or_else(|| PathBuf::from("."))) +} + +fn parse_required_path( + command: &str, + args: &mut Args, + path_option: &'static str, +) -> Result { + let mut path = None; + while let Some(arg) = args.next() { + let (option, inline_value) = parse_option(command, arg)?; + if option == path_option { + set_once( + command, + option, + &mut path, + PathBuf::from(option_value(command, option, inline_value, args)?), + )?; + } else { + bail!("{command}: unexpected option '{option}'"); + } + } + path.context(format!("{command}: missing {path_option}")) +} + fn parse_derive_key(args: &mut Args) -> Result<(String, bool)> { let command = "derive-key"; let mut key = None; @@ -223,6 +267,7 @@ fn parse_option(command: &str, arg: OsString) -> Result<(&'static str, Option "--input", "--output" => "--output", "--stdin" => "--stdin", + "--path" => "--path", _ => bail!("{command}: unknown option '{name}'"), }; Ok((option, value)) @@ -264,6 +309,7 @@ fn set_once(command: &str, option: &str, target: &mut Option, value: T) -> pub(crate) fn usage() -> &'static str { "Usage: git-zcrypt init + git-zcrypt init-manifest [--path ] git-zcrypt generate-key --key git-zcrypt import-key --key --input git-zcrypt derive-key --key [--stdin] @@ -271,8 +317,8 @@ pub(crate) fn usage() -> &'static str { git-zcrypt delete-key --key git-zcrypt install-filter --key git-zcrypt status - git-zcrypt clean --key - git-zcrypt smudge" + git-zcrypt clean --key --path + git-zcrypt smudge --path " } #[cfg(test)] @@ -283,6 +329,8 @@ mod tests { fn parses_planned_subcommands() { for args in [ vec!["git-zcrypt", "init"], + vec!["git-zcrypt", "init-manifest"], + vec!["git-zcrypt", "init-manifest", "--path", "secrets/team-a"], vec!["git-zcrypt", "generate-key", "--key", "default"], vec![ "git-zcrypt", @@ -305,8 +353,15 @@ mod tests { vec!["git-zcrypt", "delete-key", "--key", "default"], vec!["git-zcrypt", "install-filter", "--key", "default"], vec!["git-zcrypt", "status"], - vec!["git-zcrypt", "clean", "--key", "default"], - vec!["git-zcrypt", "smudge"], + vec![ + "git-zcrypt", + "clean", + "--key", + "default", + "--path", + "secrets/a.txt", + ], + vec!["git-zcrypt", "smudge", "--path", "secrets/a.txt"], ] { Cli::try_parse_from(args).expect("subcommand should parse"); } @@ -336,7 +391,14 @@ mod tests { ], vec!["git-zcrypt", "delete-key", "--key", "default"], vec!["git-zcrypt", "install-filter", "--key", "default"], - vec!["git-zcrypt", "clean", "--key", "default"], + vec![ + "git-zcrypt", + "clean", + "--key", + "default", + "--path", + "secrets/a.txt", + ], ] { Cli::try_parse_from(args).expect("--key should parse"); } diff --git a/src/git_config.rs b/src/git_config.rs index 1e29527..0ba37d9 100644 --- a/src/git_config.rs +++ b/src/git_config.rs @@ -9,8 +9,11 @@ const REQUIRED_KEY: &str = "filter.git-zcrypt.required"; pub fn install_filter(key_name: &str) -> Result<()> { key_store::validate_key_name(key_name)?; - git_config_set(CLEAN_KEY, &format!("git-zcrypt clean --key {key_name}"))?; - git_config_set(SMUDGE_KEY, "git-zcrypt smudge")?; + git_config_set( + CLEAN_KEY, + &format!("git-zcrypt clean --key {key_name} --path %f"), + )?; + git_config_set(SMUDGE_KEY, "git-zcrypt smudge --path %f")?; git_config_set(REQUIRED_KEY, "true")?; Ok(()) } @@ -65,10 +68,10 @@ struct FilterConfig { impl FilterConfig { fn is_installed(&self) -> bool { - self.clean - .as_deref() - .is_some_and(|value| value.starts_with(&format!("{FILTER_NAME} clean --key "))) - && self.smudge.as_deref() == Some("git-zcrypt smudge") + self.clean.as_deref().is_some_and(|value| { + value.starts_with(&format!("{FILTER_NAME} clean --key ")) + && value.contains(" --path %f") + }) && self.smudge.as_deref() == Some("git-zcrypt smudge --path %f") && self.required.as_deref() == Some("true") } } @@ -122,7 +125,7 @@ fn git_config_get(key: &str) -> Result> { mod tests { use super::{filter_config, format_keys, install_filter}; use crate::key_store::{KeyStatus, KeyStore}; - use std::{fs, process::Command}; + use std::process::Command; use tempfile::TempDir; #[test] @@ -142,9 +145,12 @@ mod tests { let config = filter_config()?; assert_eq!( config.clean.as_deref(), - Some("git-zcrypt clean --key default") + Some("git-zcrypt clean --key default --path %f") + ); + assert_eq!( + config.smudge.as_deref(), + Some("git-zcrypt smudge --path %f") ); - assert_eq!(config.smudge.as_deref(), Some("git-zcrypt smudge")); assert_eq!(config.required.as_deref(), Some("true")); assert!(config.is_installed()); Ok::<_, crate::error::Error>(()) @@ -180,7 +186,7 @@ mod tests { } #[test] - fn status_warns_on_key_index_mismatch() { + fn status_lists_local_key_files() { let temp = TempDir::new().expect("tempdir"); let status = Command::new("git") .arg("init") @@ -192,20 +198,14 @@ mod tests { let result = (|| { let store = KeyStore::discover_from(temp.path())?; store.store_key("default", &[1_u8; 32])?; - fs::write( - store.index_path(), - "{\n \"sha256:0000000000000000000000000000000000000000000000000000000000000000\": \"default\"\n}\n", - )?; let (keys, warnings) = store.indexed_keys()?; - assert!(keys.is_empty()); - assert!( - warnings - .iter() - .any(|warning| warning.contains("key index mismatch")) - ); + assert!(warnings.is_empty()); + assert_eq!(keys.len(), 1); + assert_eq!(keys[0].name, "default"); + assert!(keys[0].key_id.starts_with("sha256:")); Ok::<_, crate::error::Error>(()) })(); - result.expect("status mismatch warning"); + result.expect("status local key listing"); } } diff --git a/src/key_manifest.rs b/src/key_manifest.rs new file mode 100644 index 0000000..52dba30 --- /dev/null +++ b/src/key_manifest.rs @@ -0,0 +1,213 @@ +use crate::error::{Context, Error, Result}; +use crate::index_json; +use crate::key_store; +use crate::{bail, ensure}; +use std::collections::BTreeMap; +use std::fs; +use std::io::Write; +use std::path::{Component, Path, PathBuf}; +use std::process::Command; + +pub const MANIFEST_FILE: &str = "git-zcrypt-keys.json"; + +pub fn init_manifest(path: &Path) -> Result { + let root = worktree_root()?; + let dir = resolve_dir(&root, path)?; + fs::create_dir_all(&dir) + .with_context(|| format!("failed to create manifest directory {}", dir.display()))?; + let manifest = dir.join(MANIFEST_FILE); + if manifest.exists() { + read_manifest(&manifest)?; + return Ok(manifest); + } + write_manifest(&manifest, &BTreeMap::new())?; + Ok(manifest) +} + +pub fn add_key_for_path(path: &Path, key_id: &str, key_name: &str) -> Result { + key_store::validate_key_id(key_id)?; + key_store::validate_key_name(key_name)?; + let root = worktree_root()?; + let manifest = find_manifest_path(&root, path)?.unwrap_or_else(|| root.join(MANIFEST_FILE)); + let mut keys = if manifest.exists() { + read_manifest(&manifest)? + } else { + BTreeMap::new() + }; + if let Some(existing) = keys.get(key_id) { + ensure!( + existing == key_name, + "manifest {} maps {key_id} to {existing}, not {key_name}", + manifest.display() + ); + return Ok(manifest); + } + keys.insert(key_id.to_owned(), key_name.to_owned()); + write_manifest(&manifest, &keys)?; + Ok(manifest) +} + +pub fn key_allowed_for_path(path: &Path, key_id: &str) -> Result { + key_store::validate_key_id(key_id)?; + let root = worktree_root()?; + let manifest = find_manifest_path(&root, path)?.with_context(|| { + format!( + "no {MANIFEST_FILE} found for {}; run git-zcrypt init-manifest", + path.display() + ) + })?; + let keys = read_manifest(&manifest)?; + Ok(keys.contains_key(key_id)) +} + +pub fn read_manifest(path: &Path) -> Result> { + let input = fs::read_to_string(path) + .with_context(|| format!("failed to read key manifest {}", path.display()))?; + let keys = index_json::parse_string_map(&input) + .with_context(|| format!("failed to parse key manifest {}", path.display()))?; + for (key_id, name) in &keys { + key_store::validate_key_id(key_id)?; + key_store::validate_key_name(name)?; + } + Ok(keys) +} + +fn find_manifest_path(root: &Path, target: &Path) -> Result> { + let mut dir = target_dir(root, target)?; + loop { + let manifest = dir.join(MANIFEST_FILE); + if manifest.exists() { + return Ok(Some(manifest)); + } + if dir == root { + return Ok(None); + } + if !dir.pop() { + return Ok(None); + } + } +} + +fn target_dir(root: &Path, target: &Path) -> Result { + ensure!( + !target.as_os_str().is_empty(), + "filter path must not be empty" + ); + ensure!( + !target.is_absolute(), + "filter path must be repository-relative: {}", + target.display() + ); + for component in target.components() { + if matches!( + component, + Component::ParentDir | Component::RootDir | Component::Prefix(_) + ) { + bail!( + "filter path must stay inside the repository: {}", + target.display() + ); + } + } + Ok(root.join(target).parent().unwrap_or(root).to_path_buf()) +} + +fn resolve_dir(root: &Path, path: &Path) -> Result { + if path.as_os_str().is_empty() || path == Path::new(".") { + return Ok(root.to_path_buf()); + } + ensure!( + !path.is_absolute(), + "manifest path must be repository-relative: {}", + path.display() + ); + for component in path.components() { + if matches!( + component, + Component::ParentDir | Component::RootDir | Component::Prefix(_) + ) { + bail!( + "manifest path must stay inside the repository: {}", + path.display() + ); + } + } + Ok(root.join(path)) +} + +fn write_manifest(path: &Path, keys: &BTreeMap) -> Result<()> { + if let Some(parent) = path.parent() { + fs::create_dir_all(parent) + .with_context(|| format!("failed to create manifest directory {}", parent.display()))?; + } + let temp_path = path.with_extension("json.tmp"); + let json = index_json::format_string_map(keys); + { + let mut file = fs::OpenOptions::new() + .create(true) + .truncate(true) + .write(true) + .open(&temp_path) + .with_context(|| { + format!("failed to open temporary manifest {}", temp_path.display()) + })?; + file.write_all(json.as_bytes())?; + file.sync_all()?; + } + fs::rename(&temp_path, path).with_context(|| { + format!( + "failed to replace key manifest {} with {}", + path.display(), + temp_path.display() + ) + })?; + Ok(()) +} + +fn worktree_root() -> Result { + let output = Command::new("git") + .args(["rev-parse", "--show-toplevel"]) + .output() + .context("failed to locate Git worktree root")?; + if !output.status.success() { + return Err(Error::msg(format!( + "not inside a Git worktree: {}", + String::from_utf8_lossy(&output.stderr).trim() + ))); + } + let stdout = String::from_utf8(output.stdout).context("Git worktree root is not UTF-8")?; + let path = stdout.trim(); + ensure!(!path.is_empty(), "Git worktree root path is empty"); + Ok(PathBuf::from(path)) +} + +#[cfg(test)] +mod tests { + use super::{MANIFEST_FILE, read_manifest}; + use crate::index_json; + use std::collections::BTreeMap; + use std::fs; + use tempfile::TempDir; + + #[test] + fn manifest_uses_index_style_map() { + let temp = TempDir::new().expect("tempdir"); + let path = temp.path().join(MANIFEST_FILE); + fs::write( + &path, + "{\n \"sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\": \"default\"\n}\n", + ) + .expect("write manifest"); + let keys = read_manifest(&path).expect("read manifest"); + assert_eq!( + keys.get("sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"), + Some(&"default".to_owned()) + ); + } + + #[test] + fn formatter_writes_empty_manifest() { + let keys = BTreeMap::new(); + assert_eq!(index_json::format_string_map(&keys), "{\n}\n"); + } +} diff --git a/src/key_store.rs b/src/key_store.rs index 2fdec64..68500de 100644 --- a/src/key_store.rs +++ b/src/key_store.rs @@ -1,8 +1,6 @@ use crate::error::{Context, Error, Result}; -use crate::index_json; use crate::{bail, ensure}; use sha2::{Digest, Sha256}; -use std::collections::{BTreeMap, BTreeSet}; use std::fs; use std::io::Write; use std::path::{Path, PathBuf}; @@ -11,7 +9,6 @@ use zeroize::{Zeroize, Zeroizing}; pub const RAW_KEY_LEN: usize = 32; const KEY_ID_PREFIX: &str = "sha256:"; -const INDEX_FILE: &str = "index.json"; const KEY_FILE_MAGIC: [u8; 8] = *b"GZCKEY\0\0"; const KEY_FILE_VERSION: u8 = 1; const KEY_FILE_HEADER_LEN: usize = 12; @@ -61,10 +58,6 @@ impl KeyStore { self.root.join("keys") } - pub fn index_path(&self) -> PathBuf { - self.root.join(INDEX_FILE) - } - pub fn key_path(&self, name: &str) -> Result { validate_key_name(name)?; Ok(self.keys_dir().join(format!("{name}.key"))) @@ -94,38 +87,16 @@ impl KeyStore { } pub fn indexed_keys(&self) -> Result<(Vec, Vec)> { - let index = self.read_index()?; let mut warnings = Vec::new(); let mut statuses = Vec::new(); - let mut indexed_names = BTreeSet::new(); - - for (key_id, name) in &index { - indexed_names.insert(name.clone()); - match self.read_key(name) { - Ok(key) => { - let actual = key_id_for_key_bytes(&key)?; - if actual == *key_id { - statuses.push(KeyStatus { - name: name.clone(), - key_id: key_id.clone(), - }); - } else { - warnings.push(format!( - "key index mismatch: {name} is indexed as {key_id} but computes to {actual}" - )); - } - } - Err(error) => warnings.push(format!( - "key index mismatch: {key_id} points to {name}, but the key cannot be read: {error:#}" - )), - } - } for name in self.key_names()? { - if !indexed_names.contains(&name) { - warnings.push(format!( - "key index mismatch: {name} exists but is not indexed" - )); + match self.read_key(&name) { + Ok(key) => statuses.push(KeyStatus { + name, + key_id: key_id_for_key_bytes(&key)?, + }), + Err(error) => warnings.push(format!("local key {name} cannot be read: {error:#}")), } } @@ -171,22 +142,10 @@ impl KeyStore { pub fn delete_key(&self, name: &str) -> Result<()> { let path = self.key_path(name)?; - let mut index = self.read_index()?; - let original_len = index.len(); - index.retain(|_, indexed_name| indexed_name != name); - let was_indexed = index.len() != original_len; - let key_file_exists = path.exists(); - - ensure!(key_file_exists || was_indexed, "key {name} does not exist"); - - if was_indexed { - self.write_index(&index)?; - } - if key_file_exists { - fs::remove_file(&path) - .with_context(|| format!("failed to delete key {}", path.display()))?; - sync_dir(&self.keys_dir())?; - } + ensure!(path.exists(), "key {name} does not exist"); + fs::remove_file(&path) + .with_context(|| format!("failed to delete key {}", path.display()))?; + sync_dir(&self.keys_dir())?; Ok(()) } @@ -196,21 +155,15 @@ impl KeyStore { Ok((key, key_id)) } - pub fn read_key_by_id(&self, key_id: &str) -> Result>> { + pub fn try_read_key_by_id(&self, key_id: &str) -> Result>>> { validate_key_id(key_id)?; - let index = self.read_index()?; - let name = index - .get(key_id) - .with_context(|| format!("no local key is registered for {key_id}"))?; - let key = self.read_key(name)?; - let actual = key_id_for_key_bytes(&key)?; - if actual != key_id { - eprintln!( - "warning: key index mismatch: {key_id} points to {name}, but the key computes to {actual}" - ); - bail!("key index mismatch for {key_id}"); + for name in self.key_names()? { + let key = self.read_key(&name)?; + if key_id_for_key_bytes(&key)? == key_id { + return Ok(Some(key)); + } } - Ok(key) + Ok(None) } pub fn read_key(&self, name: &str) -> Result>> { @@ -229,69 +182,15 @@ impl KeyStore { "key {name} already exists; refusing to overwrite" ); - let mut index = self.read_index()?; - ensure!( - !index.values().any(|existing| existing == name), - "key alias {name} is already registered" - ); let key_id = key_id_for_key(key); ensure!( - !index.contains_key(&key_id), + self.try_read_key_by_id(&key_id)?.is_none(), "key material is already registered as {key_id}" ); let encoded = Zeroizing::new(encode_key_file(key)); write_secret_file(&path, &encoded) - .with_context(|| format!("failed to write key {}", path.display()))?; - index.insert(key_id, name.to_owned()); - self.write_index(&index) - } - - fn read_index(&self) -> Result> { - let path = self.index_path(); - if !path.exists() { - return Ok(BTreeMap::new()); - } - - let input = fs::read_to_string(&path) - .with_context(|| format!("failed to read key index {}", path.display()))?; - let index = index_json::parse_string_map(&input) - .with_context(|| format!("failed to parse key index {}", path.display()))?; - for (key_id, name) in &index { - validate_key_id(key_id)?; - validate_key_name(name)?; - } - Ok(index) - } - - fn write_index(&self, index: &BTreeMap) -> Result<()> { - self.init()?; - let path = self.index_path(); - let temp_path = self.root.join(format!("{INDEX_FILE}.tmp")); - let json = index_json::format_string_map(index); - - { - let mut file = fs::OpenOptions::new() - .create(true) - .truncate(true) - .write(true) - .open(&temp_path) - .with_context(|| { - format!("failed to open temporary key index {}", temp_path.display()) - })?; - file.write_all(json.as_bytes())?; - file.sync_all()?; - } - - fs::rename(&temp_path, &path).with_context(|| { - format!( - "failed to replace key index {} with {}", - path.display(), - temp_path.display() - ) - })?; - sync_dir(&self.root)?; - Ok(()) + .with_context(|| format!("failed to write key {}", path.display())) } } @@ -545,7 +444,7 @@ mod tests { } #[test] - fn delete_key_removes_key_file_and_index_entry() { + fn delete_key_removes_local_key_file() { let temp = TempDir::new().expect("tempdir"); let status = Command::new("git") .arg("init") @@ -558,11 +457,19 @@ mod tests { let store = KeyStore::discover_from(temp.path())?; store.store_key("default", &[8_u8; 32])?; assert!(store.key_path("default")?.exists()); - assert!(!store.read_index()?.is_empty()); + assert!( + store + .try_read_key_by_id(&key_id_for_key(&[8_u8; 32]))? + .is_some() + ); store.delete_key("default")?; assert!(!store.key_path("default")?.exists()); - assert!(store.read_index()?.is_empty()); + assert!( + store + .try_read_key_by_id(&key_id_for_key(&[8_u8; 32]))? + .is_none() + ); store .delete_key("default") .expect_err("missing key should fail"); diff --git a/src/main.rs b/src/main.rs index e973592..1a1aa0d 100644 --- a/src/main.rs +++ b/src/main.rs @@ -9,6 +9,7 @@ mod error; mod git_config; mod index_json; mod kdf; +mod key_manifest; mod key_store; use cli::{Cli, Command}; @@ -31,6 +32,7 @@ fn run(cli: Cli) -> Result<()> { let store = key_store::KeyStore::discover()?; store.init() } + Command::InitManifest { path } => key_manifest::init_manifest(&path).map(|_| ()), Command::GenerateKey { key } => { let store = key_store::KeyStore::discover()?; store.generate_key(&key) @@ -60,26 +62,41 @@ fn run(cli: Cli) -> Result<()> { } Command::InstallFilter { key } => git_config::install_filter(&key), Command::Status => git_config::print_status(), - Command::Clean { key } => clean(&key), - Command::Smudge => smudge(), + Command::Clean { key, path } => clean(&key, &path), + Command::Smudge { path } => smudge(&path), } } -fn clean(key_name: &str) -> Result<()> { +fn clean(key_name: &str, path: &std::path::Path) -> Result<()> { let store = key_store::KeyStore::discover()?; let (key, key_id) = store.read_key_with_id(key_name)?; let input = read_stdin()?; let compressed = compression::compress(&input)?; let encrypted = crypto::encrypt(&key, &key_id, &compressed)?; + key_manifest::add_key_for_path(path, &encrypted.key_id, key_name)?; let encoded = blob::encode(&encrypted.key_id, &encrypted.nonce, &encrypted.ciphertext)?; write_stdout(&encoded) } -fn smudge() -> Result<()> { +fn smudge(path: &std::path::Path) -> Result<()> { let store = key_store::KeyStore::discover()?; let input = read_stdin()?; let encrypted = blob::decode(&input)?; - let key = store.read_key_by_id(&encrypted.key_id)?; + if !key_manifest::key_allowed_for_path(path, &encrypted.key_id)? { + crate::bail!( + "key {} is not declared for {}", + encrypted.key_id, + path.display() + ); + } + let Some(key) = store.try_read_key_by_id(&encrypted.key_id)? else { + eprintln!( + "warning: no local key is registered for {}; leaving encrypted bytes for {}", + encrypted.key_id, + path.display() + ); + return write_stdout(&input); + }; let compressed = crypto::decrypt(&key, &encrypted)?; let plaintext = compression::decompress(&compressed)?; write_stdout(&plaintext) diff --git a/tests/filter_roundtrip.rs b/tests/filter_roundtrip.rs index e77cd87..14a4f8d 100644 --- a/tests/filter_roundtrip.rs +++ b/tests/filter_roundtrip.rs @@ -77,12 +77,66 @@ fn key_id_from_blob(blob: &[u8]) -> &str { std::str::from_utf8(&blob[key_id_start..key_id_start + key_id_len]).expect("key id utf8") } +#[test] +fn init_manifest_creates_committed_key_manifest() { + let repo = init_empty_repo(); + + let root = filter(&repo, &["init-manifest"], b""); + assert!( + root.status.success(), + "{}", + String::from_utf8_lossy(&root.stderr) + ); + assert_eq!( + std::fs::read_to_string(repo.path().join("git-zcrypt-keys.json")).expect("root manifest"), + "{\n}\n" + ); + + std::fs::create_dir_all(repo.path().join("secrets/team-a")).expect("mkdir"); + let nested = filter(&repo, &["init-manifest", "--path", "secrets/team-a"], b""); + assert!( + nested.status.success(), + "{}", + String::from_utf8_lossy(&nested.stderr) + ); + assert_eq!( + std::fs::read_to_string(repo.path().join("secrets/team-a/git-zcrypt-keys.json")) + .expect("nested manifest"), + "{\n}\n" + ); +} + +#[test] +fn clean_updates_committed_key_manifest() { + let repo = init_repo(); + + let clean = filter( + &repo, + &["clean", "--key", "default", "--path", "secrets/secret.txt"], + b"secret", + ); + assert!( + clean.status.success(), + "{}", + String::from_utf8_lossy(&clean.stderr) + ); + + let manifest = + std::fs::read_to_string(repo.path().join("git-zcrypt-keys.json")).expect("read manifest"); + assert!(manifest.contains(key_id_from_blob(&clean.stdout))); + assert!(manifest.contains("default")); +} + #[test] fn raw_key_round_trip_uses_hash_prefixed_key_id() { let repo = init_repo(); let input: Vec = (0_u8..=255).chain([0, 255, 10, 13, 42]).collect(); - let clean = filter(&repo, &["clean", "--key", "default"], &input); + let clean = filter( + &repo, + &["clean", "--key", "default", "--path", "secrets/secret.txt"], + &input, + ); assert!( clean.status.success(), "{}", @@ -91,7 +145,11 @@ fn raw_key_round_trip_uses_hash_prefixed_key_id() { assert_ne!(clean.stdout, input); assert!(key_id_from_blob(&clean.stdout).starts_with("sha256:")); - let smudge = filter(&repo, &["smudge"], &clean.stdout); + let smudge = filter( + &repo, + &["smudge", "--path", "secrets/secret.txt"], + &clean.stdout, + ); assert!( smudge.status.success(), "{}", @@ -114,7 +172,11 @@ fn password_derived_key_round_trips_from_stdin_setup() { String::from_utf8_lossy(&derive.stderr) ); - let clean = filter(&repo, &["clean", "--key", "password"], b"password secret"); + let clean = filter( + &repo, + &["clean", "--key", "password", "--path", "secrets/secret.txt"], + b"password secret", + ); assert!( clean.status.success(), "{}", @@ -122,7 +184,11 @@ fn password_derived_key_round_trips_from_stdin_setup() { ); assert!(key_id_from_blob(&clean.stdout).starts_with("sha256:")); - let smudge = filter(&repo, &["smudge"], &clean.stdout); + let smudge = filter( + &repo, + &["smudge", "--path", "secrets/secret.txt"], + &clean.stdout, + ); assert!( smudge.status.success(), "{}", @@ -158,7 +224,11 @@ fn duplicate_password_derived_key_fails() { fn delete_key_removes_local_key_material() { let repo = init_repo(); - let clean = filter(&repo, &["clean", "--key", "default"], b"secret"); + let clean = filter( + &repo, + &["clean", "--key", "default", "--path", "secrets/secret.txt"], + b"secret", + ); assert!( clean.status.success(), "{}", @@ -178,8 +248,17 @@ fn delete_key_removes_local_key_material() { .exists() ); - let smudge = filter(&repo, &["smudge"], &clean.stdout); - assert!(!smudge.status.success()); + let smudge = filter( + &repo, + &["smudge", "--path", "secrets/secret.txt"], + &clean.stdout, + ); + assert!( + smudge.status.success(), + "{}", + String::from_utf8_lossy(&smudge.stderr) + ); + assert_eq!(smudge.stdout, clean.stdout); assert!(String::from_utf8_lossy(&smudge.stderr).contains("no local key is registered")); } @@ -187,14 +266,22 @@ fn delete_key_removes_local_key_material() { fn empty_input_round_trips() { let repo = init_repo(); - let clean = filter(&repo, &["clean", "--key", "default"], b""); + let clean = filter( + &repo, + &["clean", "--key", "default", "--path", "secrets/secret.txt"], + b"", + ); assert!( clean.status.success(), "{}", String::from_utf8_lossy(&clean.stderr) ); - let smudge = filter(&repo, &["smudge"], &clean.stdout); + let smudge = filter( + &repo, + &["smudge", "--path", "secrets/secret.txt"], + &clean.stdout, + ); assert!( smudge.status.success(), "{}", @@ -207,7 +294,11 @@ fn empty_input_round_trips() { fn tampered_ciphertext_fails() { let repo = init_repo(); - let clean = filter(&repo, &["clean", "--key", "default"], b"secret"); + let clean = filter( + &repo, + &["clean", "--key", "default", "--path", "secrets/secret.txt"], + b"secret", + ); assert!( clean.status.success(), "{}", @@ -218,7 +309,11 @@ fn tampered_ciphertext_fails() { let last = tampered.last_mut().expect("ciphertext byte"); *last ^= 1; - let smudge = filter(&repo, &["smudge"], &tampered); + let smudge = filter( + &repo, + &["smudge", "--path", "secrets/secret.txt"], + &tampered, + ); assert!(!smudge.status.success()); } @@ -226,7 +321,11 @@ fn tampered_ciphertext_fails() { fn unknown_key_id_fails() { let repo = init_repo(); - let clean = filter(&repo, &["clean", "--key", "default"], b"secret"); + let clean = filter( + &repo, + &["clean", "--key", "default", "--path", "secrets/secret.txt"], + b"secret", + ); assert!( clean.status.success(), "{}", @@ -237,6 +336,170 @@ fn unknown_key_id_fails() { let key_id_start = 12; unknown_key[key_id_start] = b'x'; - let smudge = filter(&repo, &["smudge"], &unknown_key); + let smudge = filter( + &repo, + &["smudge", "--path", "secrets/secret.txt"], + &unknown_key, + ); + assert!(!smudge.status.success()); +} + +fn git(repo: &std::path::Path, args: &[&str]) { + let status = Command::new("git") + .args(args) + .current_dir(repo) + .status() + .expect("git command"); + assert!(status.success(), "git {:?} failed", args); +} + +fn configure_git_identity(repo: &std::path::Path) { + git(repo, &["config", "user.email", "test@example.com"]); + git(repo, &["config", "user.name", "Test User"]); +} + +fn configure_filter(repo: &std::path::Path) { + let clean = format!("{} clean --key default --path %f", git_zcrypt()); + let smudge = format!("{} smudge --path %f", git_zcrypt()); + git( + repo, + &["config", "--local", "filter.git-zcrypt.clean", &clean], + ); + git( + repo, + &["config", "--local", "filter.git-zcrypt.smudge", &smudge], + ); + git( + repo, + &["config", "--local", "filter.git-zcrypt.required", "true"], + ); +} + +#[test] +fn clone_without_local_key_checks_out_encrypted_blob_and_restore_resmudges() { + let source = init_repo(); + configure_git_identity(source.path()); + configure_filter(source.path()); + + std::fs::create_dir_all(source.path().join("secrets")).expect("mkdir secrets"); + std::fs::write( + source.path().join(".gitattributes"), + "secrets/** filter=git-zcrypt diff=git-zcrypt\n", + ) + .expect("write attributes"); + std::fs::write(source.path().join("secrets/secret.txt"), b"clone secret\n") + .expect("write secret"); + git( + source.path(), + &["add", ".gitattributes", "secrets/secret.txt"], + ); + git(source.path(), &["add", "git-zcrypt-keys.json"]); + git(source.path(), &["commit", "-m", "add encrypted secret"]); + + let exported_key = source.path().join("default.key"); + let export = Command::new(git_zcrypt()) + .args(["export-key", "--key", "default", "--output"]) + .arg(&exported_key) + .current_dir(source.path()) + .status() + .expect("export key"); + assert!(export.success()); + + let parent = TempDir::new().expect("clone parent"); + let clone_path = parent.path().join("clone"); + let clean = format!("{} clean --key default --path %f", git_zcrypt()); + let smudge = format!("{} smudge --path %f", git_zcrypt()); + let clone_status = Command::new("git") + .arg("-c") + .arg(format!("filter.git-zcrypt.clean={clean}")) + .arg("-c") + .arg(format!("filter.git-zcrypt.smudge={smudge}")) + .arg("-c") + .arg("filter.git-zcrypt.required=true") + .arg("clone") + .arg(source.path()) + .arg(&clone_path) + .status() + .expect("git clone"); + assert!(clone_status.success()); + + let checked_out = std::fs::read(clone_path.join("secrets/secret.txt")).expect("read checkout"); + assert_ne!(checked_out, b"clone secret\n"); + assert!(checked_out.starts_with(b"GZC1\0\0\0\0")); + + configure_filter(&clone_path); + let init = Command::new(git_zcrypt()) + .arg("init") + .current_dir(&clone_path) + .status() + .expect("init clone"); + assert!(init.success()); + let import = Command::new(git_zcrypt()) + .args(["import-key", "--key", "default", "--input"]) + .arg(&exported_key) + .current_dir(&clone_path) + .status() + .expect("import key"); + assert!(import.success()); + + git( + &clone_path, + &[ + "restore", + "--source=HEAD", + "--worktree", + "--", + "secrets/secret.txt", + ], + ); + let restored = std::fs::read(clone_path.join("secrets/secret.txt")).expect("read restored"); + assert_eq!(restored, b"clone secret\n"); +} + +#[test] +fn smudge_fails_when_manifest_is_missing() { + let repo = init_repo(); + let clean = filter( + &repo, + &["clean", "--key", "default", "--path", "secrets/secret.txt"], + b"secret", + ); + assert!( + clean.status.success(), + "{}", + String::from_utf8_lossy(&clean.stderr) + ); + std::fs::remove_file(repo.path().join("git-zcrypt-keys.json")).expect("remove manifest"); + + let smudge = filter( + &repo, + &["smudge", "--path", "secrets/secret.txt"], + &clean.stdout, + ); + assert!(!smudge.status.success()); + assert!(String::from_utf8_lossy(&smudge.stderr).contains("no git-zcrypt-keys.json found")); +} + +#[test] +fn smudge_rejects_manifest_mismatch() { + let repo = init_repo(); + let clean = filter( + &repo, + &["clean", "--key", "default", "--path", "secrets/secret.txt"], + b"secret", + ); + assert!( + clean.status.success(), + "{}", + String::from_utf8_lossy(&clean.stderr) + ); + std::fs::write(repo.path().join("git-zcrypt-keys.json"), "{\n}\n").expect("clear manifest"); + + let smudge = filter( + &repo, + &["smudge", "--path", "secrets/secret.txt"], + &clean.stdout, + ); assert!(!smudge.status.success()); + assert!(String::from_utf8_lossy(&smudge.stderr).contains("is not declared")); } From 14195873bff78862150da931a6a56d0143cfbb10 Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Sun, 12 Jul 2026 09:57:23 +0900 Subject: [PATCH 5/9] fix(cli): create default manifests in current directory Why: - Running git-zcrypt init-manifest from a repository subdirectory still wrote git-zcrypt-keys.json at the worktree root. - The default path handling contradicted the documented current-directory behavior and made nested manifests awkward to initialize. What: - Resolve init-manifest paths relative to the process current directory while still requiring the result to stay inside the worktree. - Add an integration regression test that runs init-manifest from secrets/team-b and verifies the manifest is created there. Impact: - git-zcrypt init-manifest now creates git-zcrypt-keys.json in the current subdirectory by default. - Verified with cargo fmt --check, cargo test, and cargo build --release. Prompt: - git-zcrypt init-manifest in a subdirectory creates in root, whats wrong --- src/key_manifest.rs | 20 +++++++++++++++----- tests/filter_roundtrip.rs | 17 +++++++++++++++++ 2 files changed, 32 insertions(+), 5 deletions(-) diff --git a/src/key_manifest.rs b/src/key_manifest.rs index 52dba30..3a7ac58 100644 --- a/src/key_manifest.rs +++ b/src/key_manifest.rs @@ -3,6 +3,7 @@ use crate::index_json; use crate::key_store; use crate::{bail, ensure}; use std::collections::BTreeMap; +use std::env; use std::fs; use std::io::Write; use std::path::{Component, Path, PathBuf}; @@ -113,12 +114,9 @@ fn target_dir(root: &Path, target: &Path) -> Result { } fn resolve_dir(root: &Path, path: &Path) -> Result { - if path.as_os_str().is_empty() || path == Path::new(".") { - return Ok(root.to_path_buf()); - } ensure!( !path.is_absolute(), - "manifest path must be repository-relative: {}", + "manifest path must be relative: {}", path.display() ); for component in path.components() { @@ -132,7 +130,19 @@ fn resolve_dir(root: &Path, path: &Path) -> Result { ); } } - Ok(root.join(path)) + + let current_dir = env::current_dir().context("failed to get current directory")?; + let dir = if path.as_os_str().is_empty() || path == Path::new(".") { + current_dir + } else { + current_dir.join(path) + }; + ensure!( + dir.starts_with(root), + "manifest path must stay inside the repository: {}", + path.display() + ); + Ok(dir) } fn write_manifest(path: &Path, keys: &BTreeMap) -> Result<()> { diff --git a/tests/filter_roundtrip.rs b/tests/filter_roundtrip.rs index 14a4f8d..1eac1d5 100644 --- a/tests/filter_roundtrip.rs +++ b/tests/filter_roundtrip.rs @@ -104,6 +104,23 @@ fn init_manifest_creates_committed_key_manifest() { .expect("nested manifest"), "{\n}\n" ); + + std::fs::create_dir_all(repo.path().join("secrets/team-b")).expect("mkdir"); + let subdir = Command::new(git_zcrypt()) + .arg("init-manifest") + .current_dir(repo.path().join("secrets/team-b")) + .output() + .expect("git-zcrypt init-manifest in subdir"); + assert!( + subdir.status.success(), + "{}", + String::from_utf8_lossy(&subdir.stderr) + ); + assert_eq!( + std::fs::read_to_string(repo.path().join("secrets/team-b/git-zcrypt-keys.json")) + .expect("subdir manifest"), + "{\n}\n" + ); } #[test] From ef0518e095e16d17ab592d007a5376e3502c4a66 Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Sun, 26 Jul 2026 12:43:36 +0900 Subject: [PATCH 6/9] docs: add encrypted manifest migration plan Why: - Existing encrypted repositories need a planned migration path into committed key manifests. - The implementation needs explicit boundaries before code changes begin. What: - Add research for registering encrypted file key ids into manifests. - Add an implementation plan for register-file behavior, including missing-key warnings and manifest creation. - Add a feature list with scoped boundaries for each task. Impact: - No production code changes. - Planning artifacts are ready for review and explicit implementation approval. Prompt: - To migrate, I need a command that takes an encrypted file and add entry to nearest JSON whenever the key is found. --- .../feature_list.json | 93 +++++++ .../migrate-encrypted-manifest/plan.md | 230 ++++++++++++++++++ .../migrate-encrypted-manifest/research.md | 141 +++++++++++ 3 files changed, 464 insertions(+) create mode 100644 codex-notes/migrate-encrypted-manifest/feature_list.json create mode 100644 codex-notes/migrate-encrypted-manifest/plan.md create mode 100644 codex-notes/migrate-encrypted-manifest/research.md diff --git a/codex-notes/migrate-encrypted-manifest/feature_list.json b/codex-notes/migrate-encrypted-manifest/feature_list.json new file mode 100644 index 0000000..7a47425 --- /dev/null +++ b/codex-notes/migrate-encrypted-manifest/feature_list.json @@ -0,0 +1,93 @@ +{ + "features": [ + { + "id": "parse-register-file", + "description": "Add a register-file --path CLI command to src/cli.rs and usage text.", + "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact", + "passes": false, + "boundary": { + "files_dirs": [ + "src/cli.rs" + ], + "semantic_changes": "Add parsing and usage for register-file --path .", + "capability": "Edit files; run parser test." + } + }, + { + "id": "lookup-local-key-alias", + "description": "Add a key-store API that finds the local alias matching an embedded sha256 key id and errors on duplicate aliases.", + "validation": "Validate through full cargo test and targeted integration coverage.", + "passes": false, + "boundary": { + "files_dirs": [ + "src/key_store.rs" + ], + "semantic_changes": "Find local alias matching an embedded sha256 key id.", + "capability": "Edit files; run Rust tests." + } + }, + { + "id": "register-file-command", + "description": "Implement register-file so it reads encrypted file bytes, extracts the blob key id, adds a nearest-manifest entry when a matching local key exists, and creates the manifest file with a warning when no matching key exists.", + "validation": "cargo test --test filter_roundtrip register_file_updates_nearest_manifest_without_rewriting_file -- --exact", + "passes": false, + "boundary": { + "files_dirs": [ + "src/main.rs", + "src/cli.rs", + "src/key_store.rs", + "src/key_manifest.rs", + "tests/filter_roundtrip.rs" + ], + "semantic_changes": "Register found key ids; warn and create manifest when key is missing.", + "capability": "Edit files; run targeted Rust tests." + } + }, + { + "id": "register-file-missing-key-warning", + "description": "Add coverage proving register-file warns and creates the manifest file without adding a key entry when no matching local key exists.", + "validation": "cargo test --test filter_roundtrip register_file_warns_and_creates_manifest_without_matching_local_key -- --exact", + "passes": false, + "boundary": { + "files_dirs": [ + "tests/filter_roundtrip.rs", + "src/main.rs", + "src/key_store.rs", + "src/key_manifest.rs" + ], + "semantic_changes": "Warn and create manifest without entry when local key is missing.", + "capability": "Edit files; run targeted Rust tests." + } + }, + { + "id": "document-register-file", + "description": "Document register-file migration behavior in README.md and docs/data-formats.md.", + "validation": "rg -q register-file README.md docs/data-formats.md", + "passes": false, + "boundary": { + "files_dirs": [ + "README.md", + "docs/data-formats.md" + ], + "semantic_changes": "Document register-file migration behavior.", + "capability": "Edit files; run rg doc check." + } + }, + { + "id": "full-validation", + "description": "Run formatting, the full test suite, release build, binary-size measurement, and applicable validators.", + "validation": "cargo fmt --check; cargo test; cargo build --release; ruby -e 'puts File.size(%q[target/release/git-zcrypt])'", + "passes": false, + "boundary": { + "files_dirs": [ + "src", + "tests", + "README.md", + "docs" + ], + "semantic_changes": "Run validation and update passes incrementally.", + "capability": "Run fmt, tests, build, size, rg, and validator discovery." + } + } + ] +} diff --git a/codex-notes/migrate-encrypted-manifest/plan.md b/codex-notes/migrate-encrypted-manifest/plan.md new file mode 100644 index 0000000..73035ad --- /dev/null +++ b/codex-notes/migrate-encrypted-manifest/plan.md @@ -0,0 +1,230 @@ +# Plan: migrate encrypted file key ids into manifests + +## Overview + +Add a migration CLI command named `register-file`: + +```sh +git-zcrypt register-file --path +``` + +The command will read the already-encrypted blob bytes from the repository-relative file path and decode the blob header to get its embedded key id. When a matching local key alias exists, it writes that mapping to the nearest `git-zcrypt-keys.json`; when no matching local key exists, it warns and creates the nearest/root manifest file without adding an entry. It will not decrypt, re-encrypt, or rewrite the encrypted file. + +This directly supports migrating existing encrypted repositories to the new committed manifest model introduced by the clone-smudge fix. + +## Files to change + +- `src/cli.rs` + - Add `Command::RegisterFile { path: PathBuf }`. + - Parse `register-file --path ` with the existing required path parser. + - Add the command to usage text and parser tests. + +- `src/key_store.rs` + - Add an API that returns the matching local alias for a key id, likely `key_name_for_id(&self, key_id: &str) -> Result>`. + - Validate the requested key id. + - Search sorted local key names for deterministic behavior. + - Error if more than one alias maps to the same key id, because the manifest stores exactly one alias per key id and silent choice would hide a broken local key store. + +- `src/key_manifest.rs` + - Add helper to create/read the nearest manifest for a path without inserting a key entry. + +- `src/main.rs` + - Dispatch `Command::RegisterFile`. + - Implement `register_file(path: &Path)`: + - Discover the local key store. + - Read file bytes from `path` with context. + - Decode the encrypted blob with `blob::decode`. + - Find the matching local key alias through the new key-store API. + - If a matching key exists, call `key_manifest::add_key_for_path(path, &blob.key_id, &key_name)`. + - If no matching key exists, emit a warning, ensure the nearest/root manifest file exists, and do not add an entry. + +- `tests/filter_roundtrip.rs` + - Add an integration test proving the migration command updates the nearest manifest for an existing encrypted file without rewriting the file. + - Add a missing-key warning test verifying manifest creation without a key entry. + +- `README.md` + - Document the migration command in the setup/key section. + - Explain that it works on encrypted worktree files and updates only the manifest. + +- `docs/data-formats.md` + - Mention that manifest entries for legacy encrypted blobs can be populated from the embedded blob key id when the local matching key is available. + +## Detailed implementation steps + +1. Update CLI parsing in `src/cli.rs`. + + Add the enum variant: + + ```rust + RegisterFile { path: PathBuf }, + ``` + + Add parser branch: + + ```rust + "register-file" => Command::RegisterFile { + path: parse_required_path("register-file", &mut args, "--path")?, + }, + ``` + + Add usage line: + + ```text + git-zcrypt register-file --path + ``` + + Extend `parses_planned_subcommands` with `register-file`. + +2. Add local key alias lookup in `src/key_store.rs`. + + Proposed behavior: + + ```rust + pub fn key_name_for_id(&self, key_id: &str) -> Result> { + validate_key_id(key_id)?; + let mut found = None; + for name in self.key_names()? { + let key = self.read_key(&name)?; + if key_id_for_key_bytes(&key)? == key_id { + ensure!(found.is_none(), "multiple local keys match {key_id}"); + found = Some(name); + } + } + Ok(found) + } + ``` + + Keep unreadable key files fatal for this command path. That matches `try_read_key_by_id`, avoids silently missing a matching key, and prevents writing incomplete migration state from a partially broken local key store. + +3. Implement command dispatch in `src/main.rs`. + + Proposed flow: + + ```rust + Command::RegisterFile { path } => register_file(&path), + ``` + + Proposed function behavior: + + ```rust + fn register_file(path: &Path) -> Result<()> { + let store = key_store::KeyStore::discover()?; + let input = std::fs::read(path) + .with_context(|| format!("failed to read encrypted file {}", path.display()))?; + let encrypted = blob::decode(&input) + .with_context(|| format!("failed to decode encrypted file {}", path.display()))?; + if let Some(key_name) = store.key_name_for_id(&encrypted.key_id)? { + key_manifest::add_key_for_path(path, &encrypted.key_id, &key_name)?; + } else { + eprintln!( + "warning: no local key is registered for {}; leaving manifest entry absent for {}", + encrypted.key_id, + path.display() + ); + key_manifest::ensure_manifest_for_path(path)?; + } + Ok(()) + } + ``` + +4. Add integration tests. + + Primary success test: + + - Create repo and local `default` key. + - Use `clean --key default --path secrets/team-a/secret.txt` to produce encrypted bytes in memory. + - Write those encrypted bytes to `secrets/team-a/secret.txt` directly. + - Create `secrets/git-zcrypt-keys.json` as the nearest manifest boundary. + - Run `git-zcrypt register-file --path secrets/team-a/secret.txt`. + - Assert `secrets/git-zcrypt-keys.json` contains the encrypted blob key id and `default`. + - Assert root `git-zcrypt-keys.json` is absent if it was not initialized for the test. + - Assert file bytes are unchanged after running the command. + + Missing-key warning test: + + - Create repo and local `default` key. + - Produce encrypted bytes with `clean`. + - Delete the local key. + - Write encrypted bytes to a file. + - Run `register-file --path ...`. + - Assert command succeeds and warns with `no local key is registered`. + - Assert the nearest/root manifest file exists and does not contain the missing key id. + + Parser test: + + - Include `git-zcrypt register-file --path secrets/a.txt` in `parses_planned_subcommands`. + +5. Update docs. + + README wording: + + - Add a short migration paragraph near the manifest/smudge docs. + - State that `register-file` expects encrypted blob bytes at the given repository-relative path. + - State it adds a manifest entry only when a matching local key exists; otherwise it creates the manifest file and warns. + + Data-format docs: + + - Add one sentence under committed key manifests that existing encrypted blobs carry enough key-id metadata to populate manifests, but the local key alias must be known by matching a local key. + +6. Validate. + + Run: + + ```sh + cargo fmt --check + cargo test --test filter_roundtrip register_file -- --exact + cargo test + cargo build --release + ruby -e 'puts File.size("target/release/git-zcrypt")' + ``` + + Also check for applicable validators under `.codex/agents/` and `~/.codex/agents/` after implementation. + +## Alternatives considered + +- `register-key --path ` + - Rejected because it sounds like it registers a key object, not a file's embedded key id. + +- `migrate-file --path ` + - Reasonable, but less explicit about the durable side effect. `register-file` describes adding the encrypted file to the manifest model. + +- `add-manifest-entry --path ` + - Accurate but awkward and too tied to implementation detail. + +- Require `--key ` as well as `--path ` + - Rejected for this migration case because the command can discover the alias from local key material. Requiring `--key` would make the command less useful and would duplicate the risk of a user choosing an alias whose key id does not match the blob. + +- Read encrypted bytes from stdin plus `--path `. + - Deferred. It is useful for advanced workflows such as `git cat-file`, but the stated need is a command that takes an encrypted file. A file-path-only command is simpler and less ambiguous. + +- Require an existing nearest manifest and fail if none exists. + - Rejected for consistency with `clean`, which calls `add_key_for_path` and creates a root manifest when no manifest exists. Users who need narrower boundaries can create subdirectory manifests first with `init-manifest`. + +## Risks + +- If the worktree path contains plaintext rather than encrypted blob bytes, `register-file` will fail with a decode error. This is expected, but docs should be explicit. +- Local key aliases are local names. The command can record only the alias present in this clone; another clone may use a different alias for the same key unless users standardize names. +- Manually duplicated local key files could create multiple aliases for one key id. The plan treats this as an error to avoid nondeterministic manifest output. +- Existing `add_key_for_path` root fallback may create a root manifest when users expected a subdirectory manifest. This matches current clean behavior; docs should tell users to run `init-manifest` in subdirectories first when boundaries matter. +- The command decodes only the blob envelope and does not verify decryption. Matching key id proves the local key material has the expected SHA-256 hash, but the file could still have corrupted ciphertext. That is acceptable because the command's job is manifest migration, not content verification. + +## Test strategy + +- Unit/parser coverage in `src/cli.rs` for the new subcommand. +- Integration success coverage in `tests/filter_roundtrip.rs` for nearest-manifest update and byte preservation. +- Integration coverage for missing matching local key: warning, manifest file creation, and no key entry. +- Existing full suite should continue covering clean/smudge/key-store behavior. +- Release build and binary-size measurement because this changes CLI and command logic. + +## Assumptions + +- This is approved to remain in the existing `codex/fix-clone-smudge` PR because it is migration support for the same committed-manifest clone-smudge feature. +- `--path` is repository-relative, matching clean/smudge path semantics. +- If no matching local key exists, the migration command should warn, ensure the manifest file exists, and leave the key entry absent so users can add matching keys later and rerun registration. +- Creating a root manifest when no nearer manifest exists is acceptable because it matches `clean` behavior. + +## Open questions + +- Is `register-file` the accepted command name, or do you want a different name before implementation? +- Should advanced stdin support be included now, for example `register-file --path --input ` or `--stdin`, or should this stay file-path-only for the first PR? + - Note: no. this should stay file-path-only for the first PR diff --git a/codex-notes/migrate-encrypted-manifest/research.md b/codex-notes/migrate-encrypted-manifest/research.md new file mode 100644 index 0000000..c40d2a2 --- /dev/null +++ b/codex-notes/migrate-encrypted-manifest/research.md @@ -0,0 +1,141 @@ +# Research: migrate encrypted file key ids into manifests + +## Request + +The migration need is a command that takes an already-encrypted file and adds an entry to the nearest `git-zcrypt-keys.json` whenever the corresponding local key is found. + +This is related to the Issue #8 manifest work already in the `codex/fix-clone-smudge` branch: smudge now requires a committed manifest, but existing repositories may already contain encrypted blobs without matching manifest entries. + +## Relevant files and modules + +- `src/cli.rs` + - Defines the handwritten CLI parser and the `Command` enum. + - Current manifest-related command is `init-manifest [--path ]`. + - Filter commands are `clean --key --path ` and `smudge --path `. + - `parse_key_and_path` supports commands that require both `--key` and a path option. + - `parse_required_path` supports commands that require only a path option. + - Usage text must be updated for any new command. + +- `src/main.rs` + - Dispatches parsed commands. + - `clean()` reads stdin, encrypts with a named local key, calls `key_manifest::add_key_for_path(path, key_id, key_name)`, and writes encrypted bytes. + - `smudge()` reads stdin, decodes the blob, checks the nearest manifest with `key_manifest::key_allowed_for_path`, then decrypts if local key material exists. + - There is currently no command that reads an encrypted file from disk, extracts its embedded key id, finds the matching local key alias, and updates a manifest without changing the file bytes. + +- `src/blob.rs` + - `decode(input: &[u8]) -> Result` validates the encrypted blob envelope and extracts `Blob { key_id, nonce, ciphertext }`. + - The key id is embedded in the blob header. No decryption is needed to learn it. + - Decode validates magic, version, nonce length, reserved byte, UTF-8 key id, and non-empty key id. + +- `src/key_store.rs` + - Local keys live under `.git/git-zcrypt/keys/*.key`. + - `key_names()` returns sorted local key aliases. + - `read_key(name)` reads one key file. + - `read_key_with_id(name)` returns the key material plus computed `sha256:` key id. + - `try_read_key_by_id(key_id)` only returns key material, not the matching alias name. + - `indexed_keys()` returns `Vec { name, key_id }` and warnings for unreadable key files; this is the existing API that exposes alias names with computed key ids. + +- `src/key_manifest.rs` + - `add_key_for_path(path, key_id, key_name)` validates the key id and key name, locates the nearest existing `git-zcrypt-keys.json` for `path`, or falls back to the repository root manifest if none exists, then inserts the mapping. + - Existing conflict behavior: if the manifest already maps that key id to the same key name, it is a no-op; if it maps the key id to a different key name, it errors. + - Existing nearest-manifest behavior is based on `target_dir(root, path)`, where `path` must be repository-relative and must not contain `..`, root, or platform prefix components. + - `init_manifest(path)` creates a manifest directory and empty manifest. + +- `tests/filter_roundtrip.rs` + - Existing integration helpers can run the compiled `git-zcrypt` binary against temp Git repositories. + - Existing tests cover clean writing a committed manifest, smudge behavior with/without local keys, and nearest-manifest semantics indirectly through path handling. + - A migration command test can reuse `filter()` for stdin-based commands, but a command that reads a file path should probably use `Command::new(git_zcrypt())` directly. + +- `README.md` and `docs/data-formats.md` + - README explains setup, manifest behavior, clone-without-key behavior, and re-smudge after importing/deriving a key. + - Data format docs describe encrypted blob headers and manifest lookup rules. + - A migration command would need user-facing documentation because it exists specifically for repositories migrating to committed manifests. + +## Current execution flow + +### New encrypted content + +1. Git invokes the clean filter configured by `install-filter`. +2. `clean --key --path ` reads plaintext from stdin. +3. `KeyStore::discover()` finds `.git/git-zcrypt`. +4. `read_key_with_id(alias)` reads local key material and computes its `sha256:` key id. +5. Content is compressed and encrypted. +6. `key_manifest::add_key_for_path(path, encrypted.key_id, alias)` updates the nearest manifest or creates a root manifest. +7. The encrypted blob is written to stdout. + +### Checkout / clone smudge + +1. Git invokes `smudge --path ` with encrypted bytes on stdin. +2. `blob::decode()` extracts the embedded key id. +3. `key_manifest::key_allowed_for_path(path, key_id)` requires the nearest manifest to contain that key id. +4. If local key material is missing, smudge writes the original encrypted bytes and succeeds with a warning. +5. If local key material exists, smudge decrypts and decompresses. + +### Existing encrypted content without manifest entry + +Observed gap: + +1. The encrypted file already contains its key id in the blob header. +2. The local clone may have a key whose computed id matches the blob key id. +3. The repository may lack a manifest entry for the file path. +4. Existing `clean` can add a manifest entry only by re-cleaning plaintext with an explicitly named key, which changes ciphertext because nonces are random and requires plaintext recovery. +5. Existing `smudge` cannot be used to add a manifest entry; it validates the manifest before decrypting. + +## Data structures and invariants + +- Encrypted blob key ids are embedded as UTF-8 strings and should validate as current key ids (`sha256:` plus 64 lowercase hex chars) before being written to a manifest. +- Manifest entries map key id to local alias name, not to raw key material. +- Manifest files are committed and contain no raw key material. +- Local key aliases are clone-local names and must pass `validate_key_name`. +- The nearest manifest rule matters for subdirectory boundaries: updating the root manifest when a closer manifest exists would make smudge still reject files below that closer boundary. +- If no manifest exists for a path, existing `add_key_for_path` falls back to `root/git-zcrypt-keys.json`. +- Filter paths are expected to be repository-relative and cannot escape the worktree. + +## Existing architectural patterns + +- CLI parsing is manual, option names are long-form, and errors include command-specific prefixes. +- Command implementations live in `main.rs` as small functions that compose module APIs. +- File/path validation is centralized in the module that owns the behavior (`key_manifest` for manifest paths; `key_store` for key names and key ids). +- Errors use the local `Result`, `ensure!`, `bail!`, and context helpers. +- Tests are a mix of unit tests for pure parsing/format behavior and integration tests that run the compiled binary against temp Git repositories. + +## Naming conventions + +- Commands use hyphenated names: `init-manifest`, `generate-key`, `install-filter`. +- Options use explicit long names such as `--key`, `--path`, `--input`, `--output`. +- Existing path-bearing filter commands use `--path` for repository-relative filtered paths. +- Existing file-input commands use `--input` for key import; encrypted-file migration could reasonably need either a repository path option or a file input option, but the nearest-manifest requirement means the repository-relative target path is semantically required. + +## Error handling patterns + +- Missing required options return `: missing --option`. +- Unexpected options return `: unexpected option ...`. +- Invalid paths fail before filesystem mutation. +- Manifest conflicts preserve existing entries and return an error instead of overwriting. +- Local unreadable keys can be warnings in `status`, but command-specific behavior must decide whether unreadable keys should be fatal or simply ignored while searching for a matching key. + +## Potential pitfalls + +- A command that reads encrypted bytes from stdin without a path cannot know which nearest manifest to update unless it also takes `--path`. +- A command that takes a filesystem path must distinguish between the repository-relative path used for manifest lookup and the disk path used to read bytes. For normal migration these are probably the same path. +- If the worktree file is currently smudged plaintext rather than the encrypted Git blob, `blob::decode()` will fail. Migration may need users to operate on encrypted bytes from the index/HEAD or on a checked-out encrypted file left by missing-key smudge. +- If multiple local aliases somehow map to the same key material, `indexed_keys()` would return multiple names with the same key id. Existing key creation rejects duplicate key material, but legacy/manual file copies could still create this state. +- If no matching local key exists, the command should not add a manifest entry because it cannot know the local alias name to record. +- If a closer subdirectory manifest exists, updating only the root manifest is insufficient for smudge. +- Existing `add_key_for_path` can create a root manifest automatically when no manifest exists. That may or may not be desirable for a migration command, depending on whether the command should require users to initialize boundaries first. + +## Constraints + +- Keep this in the existing Issue #8 PR only if treated as part of the same clone-smudge manifest migration feature; otherwise it should be split by workflow guardrails. +- Avoid introducing new dependencies for this CLI addition. +- Preserve committed encrypted file bytes; the migration command should only update manifest JSON. +- Preserve current manifest conflict checks. +- Use existing JSON formatting/parsing so manifest output remains stable. + +## Unknowns + +- Command name is not yet chosen. Candidates should be evaluated in the plan, but no code should be written before approval. +- Exact CLI shape is open: one path option may be enough if the encrypted file path is repo-relative, but separate `--input` and `--path` may be useful for reading encrypted bytes from elsewhere while updating the manifest for a repository path. +- Behavior when no matching local key is found needs confirmation: likely a clear error and no manifest mutation. +- Behavior when multiple local aliases match the embedded key id needs confirmation: likely an ambiguity error unless existing invariants make it impossible enough to choose the first sorted alias. +- Behavior when no manifest exists needs confirmation: reuse current root fallback or require an existing manifest boundary. From c0a084c3d8ad0238b7acceee20c98d96746ce1b2 Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Sun, 26 Jul 2026 13:22:12 +0900 Subject: [PATCH 7/9] docs: revise encrypted manifest migration plan Why: - The migration plan needed to match the desired interactive workflow for registering existing encrypted files from subdirectories. - The earlier command and manifest-selection design was too verbose and included an unnecessary config default. What: - Rename the planned migration command from register-file to register. - Update the plan for cwd-relative file arguments, --manifest-dir, and multi-file registration. - Remove the rejected register manifest config feature from the implementation tracker. Impact: - No production behavior changes; this updates planning artifacts only. - Validated feature_list.json structure and checked for stale command/config references. Prompt: - To migrate, I need a command that takes an encrypted file and add entry to nearest JSON whenever the key is found. - Added notes --- .../feature_list.json | 30 ++-- .../migrate-encrypted-manifest/plan.md | 145 +++++++++++------- 2 files changed, 107 insertions(+), 68 deletions(-) diff --git a/codex-notes/migrate-encrypted-manifest/feature_list.json b/codex-notes/migrate-encrypted-manifest/feature_list.json index 7a47425..5f019ef 100644 --- a/codex-notes/migrate-encrypted-manifest/feature_list.json +++ b/codex-notes/migrate-encrypted-manifest/feature_list.json @@ -1,15 +1,15 @@ { "features": [ { - "id": "parse-register-file", - "description": "Add a register-file --path CLI command to src/cli.rs and usage text.", + "id": "parse-register", + "description": "Add a register [--manifest-dir ] ... CLI command to src/cli.rs and usage text.", "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact", "passes": false, "boundary": { "files_dirs": [ "src/cli.rs" ], - "semantic_changes": "Add parsing and usage for register-file --path .", + "semantic_changes": "Add manifest-dir option and positional multi-file parsing.", "capability": "Edit files; run parser test." } }, @@ -27,9 +27,9 @@ } }, { - "id": "register-file-command", - "description": "Implement register-file so it reads encrypted file bytes, extracts the blob key id, adds a nearest-manifest entry when a matching local key exists, and creates the manifest file with a warning when no matching key exists.", - "validation": "cargo test --test filter_roundtrip register_file_updates_nearest_manifest_without_rewriting_file -- --exact", + "id": "register-command", + "description": "Implement register so files are cwd-relative, the manifest comes from --manifest-dir or cwd, and multiple encrypted files are supported.", + "validation": "cargo test --test filter_roundtrip register_updates_selected_manifest_without_rewriting_file -- --exact", "passes": false, "boundary": { "files_dirs": [ @@ -39,14 +39,14 @@ "src/key_manifest.rs", "tests/filter_roundtrip.rs" ], - "semantic_changes": "Register found key ids; warn and create manifest when key is missing.", + "semantic_changes": "Register files into explicit or cwd manifest.", "capability": "Edit files; run targeted Rust tests." } }, { - "id": "register-file-missing-key-warning", - "description": "Add coverage proving register-file warns and creates the manifest file without adding a key entry when no matching local key exists.", - "validation": "cargo test --test filter_roundtrip register_file_warns_and_creates_manifest_without_matching_local_key -- --exact", + "id": "register-missing-key-warning", + "description": "Add coverage proving register warns and creates the selected manifest file without adding a key entry when no matching local key exists.", + "validation": "cargo test --test filter_roundtrip register_warns_and_creates_manifest_without_matching_local_key -- --exact", "passes": false, "boundary": { "files_dirs": [ @@ -55,21 +55,21 @@ "src/key_store.rs", "src/key_manifest.rs" ], - "semantic_changes": "Warn and create manifest without entry when local key is missing.", + "semantic_changes": "Warn and create selected manifest without entry.", "capability": "Edit files; run targeted Rust tests." } }, { - "id": "document-register-file", - "description": "Document register-file migration behavior in README.md and docs/data-formats.md.", - "validation": "rg -q register-file README.md docs/data-formats.md", + "id": "document-register", + "description": "Document register migration behavior in README.md and docs/data-formats.md.", + "validation": "rg -q \"git-zcrypt register\" README.md docs/data-formats.md", "passes": false, "boundary": { "files_dirs": [ "README.md", "docs/data-formats.md" ], - "semantic_changes": "Document register-file migration behavior.", + "semantic_changes": "Document paths, override, and multi-file usage.", "capability": "Edit files; run rg doc check." } }, diff --git a/codex-notes/migrate-encrypted-manifest/plan.md b/codex-notes/migrate-encrypted-manifest/plan.md index 73035ad..e4d1813 100644 --- a/codex-notes/migrate-encrypted-manifest/plan.md +++ b/codex-notes/migrate-encrypted-manifest/plan.md @@ -2,23 +2,47 @@ ## Overview -Add a migration CLI command named `register-file`: +Add a migration CLI command named `register`: +```sh +git-zcrypt register [--manifest-dir ] ... +``` + +Each `` is a current-directory-relative worktree file path, matching shell completion. The selected manifest directory is chosen in this order: explicit `--manifest-dir `, then the current directory. `--manifest-dir ` is current-directory-relative for interactive shell-completion workflows. The command resolves each file and selected manifest directory, verifies all paths stay inside the worktree, converts files to repository-relative filter paths for manifest entries, and reads encrypted bytes from the resolved worktree files. The selected manifest directory must be an ancestor of every registered file so smudge can find the manifest later. When a matching local key alias exists, it writes that mapping to the selected `git-zcrypt-keys.json`; when no matching local key exists, it warns and creates the selected manifest file without adding an entry. It will not decrypt, re-encrypt, or rewrite encrypted files. + +Example: if the current directory is `repo/a/b`, the encrypted file is `repo/a/b/c.secret`, and the desired manifest is `repo/a/git-zcrypt-keys.json`, run: ```sh -git-zcrypt register-file --path +cd .. +git-zcrypt init-manifest +git-zcrypt register b/c.secret ``` -The command will read the already-encrypted blob bytes from the repository-relative file path and decode the blob header to get its embedded key id. When a matching local key alias exists, it writes that mapping to the nearest `git-zcrypt-keys.json`; when no matching local key exists, it warns and creates the nearest/root manifest file without adding an entry. It will not decrypt, re-encrypt, or rewrite the encrypted file. +The command uses the shell-completed path from `repo/a`, creates/updates `repo/a/git-zcrypt-keys.json`, and records the repository-relative file path `a/b/c.secret`. + +To run from `repo/a/b` while still creating `repo/a/git-zcrypt-keys.json`, use the manifest override: + +```sh +git-zcrypt register --manifest-dir .. c.secret +``` + +Multiple files can be registered in one invocation: + +```sh +git-zcrypt register b/c.secret b/d.secret other/e.secret +``` + +The command processes files in argument order and writes all entries to the selected manifest. Missing local keys are warnings per file; malformed blobs, paths outside the worktree, a manifest directory that is not an ancestor of every file, manifest conflicts, and unreadable files are errors. This directly supports migrating existing encrypted repositories to the new committed manifest model introduced by the clone-smudge fix. ## Files to change - `src/cli.rs` - - Add `Command::RegisterFile { path: PathBuf }`. - - Parse `register-file --path ` with the existing required path parser. + - Add `Command::Register { manifest_dir: Option, paths: Vec }`. + - Parse `register [--manifest-dir ] ...` as an optional manifest directory plus one or more positional paths. - Add the command to usage text and parser tests. + - `src/key_store.rs` - Add an API that returns the matching local alias for a key id, likely `key_name_for_id(&self, key_id: &str) -> Result>`. - Validate the requested key id. @@ -26,20 +50,23 @@ This directly supports migrating existing encrypted repositories to the new comm - Error if more than one alias maps to the same key id, because the manifest stores exactly one alias per key id and silent choice would hide a broken local key store. - `src/key_manifest.rs` - - Add helper to create/read the nearest manifest for a path without inserting a key entry. + - Add helper to resolve cwd-relative worktree file paths to repository-relative filter paths and absolute worktree file paths. + - Add helper to resolve the selected cwd-relative manifest directory, validate that it is an ancestor of each registered file, and create/read that manifest without inserting a key entry. - `src/main.rs` - - Dispatch `Command::RegisterFile`. - - Implement `register_file(path: &Path)`: + - Dispatch `Command::Register`. + - Implement `register(manifest_dir: Option<&Path>, paths: &[PathBuf])`: - Discover the local key store. - - Read file bytes from `path` with context. - - Decode the encrypted blob with `blob::decode`. + - Select the manifest directory from explicit `--manifest-dir` or current directory. + - For each cwd-relative input path, resolve the absolute worktree file path and repository-relative filter path. + - Ensure the selected manifest directory is an ancestor of each resolved file path. + - Read file bytes from the resolved worktree file path and decode the encrypted blob with `blob::decode`. - Find the matching local key alias through the new key-store API. - - If a matching key exists, call `key_manifest::add_key_for_path(path, &blob.key_id, &key_name)`. - - If no matching key exists, emit a warning, ensure the nearest/root manifest file exists, and do not add an entry. + - If a matching key exists, add the key id/name entry to the selected manifest for `repo_relative_path`. + - If no matching key exists, emit a warning, ensure the selected manifest file exists, and do not add an entry. - `tests/filter_roundtrip.rs` - - Add an integration test proving the migration command updates the nearest manifest for an existing encrypted file without rewriting the file. + - Add an integration test proving the migration command updates the selected manifest for an existing encrypted file without rewriting the file. - Add a missing-key warning test verifying manifest creation without a key entry. - `README.md` @@ -56,24 +83,25 @@ This directly supports migrating existing encrypted repositories to the new comm Add the enum variant: ```rust - RegisterFile { path: PathBuf }, + Register { manifest_dir: Option, paths: Vec }, ``` Add parser branch: ```rust - "register-file" => Command::RegisterFile { - path: parse_required_path("register-file", &mut args, "--path")?, + "register" => { + let (manifest_dir, paths) = parse_register("register", &mut args)?; + Command::Register { manifest_dir, paths } }, ``` Add usage line: ```text - git-zcrypt register-file --path + git-zcrypt register [--manifest-dir ] ... ``` - Extend `parses_planned_subcommands` with `register-file`. + Extend `parses_planned_subcommands` with `register`. 2. Add local key alias lookup in `src/key_store.rs`. @@ -101,27 +129,34 @@ This directly supports migrating existing encrypted repositories to the new comm Proposed flow: ```rust - Command::RegisterFile { path } => register_file(&path), + Command::Register { manifest_dir, paths } => register(manifest_dir.as_deref(), &paths), ``` Proposed function behavior: ```rust - fn register_file(path: &Path) -> Result<()> { + fn register(manifest_dir: Option<&Path>, paths: &[PathBuf]) -> Result<()> { let store = key_store::KeyStore::discover()?; - let input = std::fs::read(path) - .with_context(|| format!("failed to read encrypted file {}", path.display()))?; - let encrypted = blob::decode(&input) - .with_context(|| format!("failed to decode encrypted file {}", path.display()))?; - if let Some(key_name) = store.key_name_for_id(&encrypted.key_id)? { - key_manifest::add_key_for_path(path, &encrypted.key_id, &key_name)?; - } else { - eprintln!( - "warning: no local key is registered for {}; leaving manifest entry absent for {}", - encrypted.key_id, - path.display() - ); - key_manifest::ensure_manifest_for_path(path)?; + let manifest = key_manifest::resolve_selected_manifest_dir(manifest_dir)?; + for path in paths { + let resolved = key_manifest::resolve_worktree_file(path)?; + key_manifest::ensure_manifest_covers_path(&manifest, &resolved.repo_path)?; + let input = std::fs::read(&resolved.worktree_path).with_context(|| { + format!("failed to read encrypted file {}", resolved.worktree_path.display()) + })?; + let encrypted = blob::decode(&input).with_context(|| { + format!("failed to decode encrypted file {}", resolved.input_path.display()) + })?; + if let Some(key_name) = store.key_name_for_id(&encrypted.key_id)? { + key_manifest::add_key_to_manifest(&manifest.path, &encrypted.key_id, &key_name)?; + } else { + eprintln!( + "warning: no local key is registered for {}; leaving manifest entry absent for {}", + encrypted.key_id, + resolved.repo_path.display() + ); + key_manifest::ensure_manifest(&manifest.path)?; + } } Ok(()) } @@ -134,11 +169,14 @@ This directly supports migrating existing encrypted repositories to the new comm - Create repo and local `default` key. - Use `clean --key default --path secrets/team-a/secret.txt` to produce encrypted bytes in memory. - Write those encrypted bytes to `secrets/team-a/secret.txt` directly. - - Create `secrets/git-zcrypt-keys.json` as the nearest manifest boundary. - - Run `git-zcrypt register-file --path secrets/team-a/secret.txt`. + - Create `secrets/git-zcrypt-keys.json` as the selected manifest boundary. + - Run `git-zcrypt register team-a/secret.txt` from the `secrets` directory. - Assert `secrets/git-zcrypt-keys.json` contains the encrypted blob key id and `default`. - Assert root `git-zcrypt-keys.json` is absent if it was not initialized for the test. - Assert file bytes are unchanged after running the command. + - Assert the command resolves cwd-relative input to the intended repository-relative manifest path. + - Run `git-zcrypt register --manifest-dir .. secret.txt` from a nested directory and assert it writes to the parent manifest. + - Run `git-zcrypt register a.secret b.secret` and assert both entries are attempted in one invocation. Missing-key warning test: @@ -146,21 +184,23 @@ This directly supports migrating existing encrypted repositories to the new comm - Produce encrypted bytes with `clean`. - Delete the local key. - Write encrypted bytes to a file. - - Run `register-file --path ...`. + - Run `register ` from a subdirectory. - Assert command succeeds and warns with `no local key is registered`. - - Assert the nearest/root manifest file exists and does not contain the missing key id. + - Assert the selected manifest file exists and does not contain the missing key id. Parser test: - - Include `git-zcrypt register-file --path secrets/a.txt` in `parses_planned_subcommands`. + - Include `git-zcrypt register secrets/a.txt`, `git-zcrypt register secrets/a.txt secrets/b.txt`, and `git-zcrypt register --manifest-dir secrets secrets/a.txt` in `parses_planned_subcommands`. 5. Update docs. README wording: - Add a short migration paragraph near the manifest/smudge docs. - - State that `register-file` expects encrypted blob bytes at the given repository-relative path. - - State it adds a manifest entry only when a matching local key exists; otherwise it creates the manifest file and warns. + - State that `register` expects one or more cwd-relative encrypted file paths. + - Document the default current-directory manifest and `--manifest-dir ` override. + - State the precedence: command-line override, current directory. + - State it adds a manifest entry only when a matching local key exists; otherwise it creates the selected manifest file and warns. Data-format docs: @@ -172,7 +212,7 @@ This directly supports migrating existing encrypted repositories to the new comm ```sh cargo fmt --check - cargo test --test filter_roundtrip register_file -- --exact + cargo test --test filter_roundtrip register -- --exact cargo test cargo build --release ruby -e 'puts File.size("target/release/git-zcrypt")' @@ -186,7 +226,7 @@ This directly supports migrating existing encrypted repositories to the new comm - Rejected because it sounds like it registers a key object, not a file's embedded key id. - `migrate-file --path ` - - Reasonable, but less explicit about the durable side effect. `register-file` describes adding the encrypted file to the manifest model. + - Reasonable, but less explicit about the durable side effect. `register` describes adding the encrypted file to the manifest model. - `add-manifest-entry --path ` - Accurate but awkward and too tied to implementation detail. @@ -194,24 +234,24 @@ This directly supports migrating existing encrypted repositories to the new comm - Require `--key ` as well as `--path ` - Rejected for this migration case because the command can discover the alias from local key material. Requiring `--key` would make the command less useful and would duplicate the risk of a user choosing an alias whose key id does not match the blob. -- Read encrypted bytes from stdin plus `--path `. +- Read encrypted bytes from stdin plus an explicit manifest path. - Deferred. It is useful for advanced workflows such as `git cat-file`, but the stated need is a command that takes an encrypted file. A file-path-only command is simpler and less ambiguous. -- Require an existing nearest manifest and fail if none exists. - - Rejected for consistency with `clean`, which calls `add_key_for_path` and creates a root manifest when no manifest exists. Users who need narrower boundaries can create subdirectory manifests first with `init-manifest`. +- Always use the existing upward-search manifest and fail if none exists. + - Rejected because manual migration should create/update the manifest selected by current directory or `--manifest-dir`, which matches shell-completion workflows better. ## Risks -- If the worktree path contains plaintext rather than encrypted blob bytes, `register-file` will fail with a decode error. This is expected, but docs should be explicit. +- If the worktree path contains plaintext rather than encrypted blob bytes, `register` will fail with a decode error. This is expected, but docs should be explicit. - Local key aliases are local names. The command can record only the alias present in this clone; another clone may use a different alias for the same key unless users standardize names. - Manually duplicated local key files could create multiple aliases for one key id. The plan treats this as an error to avoid nondeterministic manifest output. -- Existing `add_key_for_path` root fallback may create a root manifest when users expected a subdirectory manifest. This matches current clean behavior; docs should tell users to run `init-manifest` in subdirectories first when boundaries matter. +- A selected manifest directory that is not an ancestor of every registered file would produce a manifest smudge cannot find. The command rejects that case. - The command decodes only the blob envelope and does not verify decryption. Matching key id proves the local key material has the expected SHA-256 hash, but the file could still have corrupted ciphertext. That is acceptable because the command's job is manifest migration, not content verification. ## Test strategy - Unit/parser coverage in `src/cli.rs` for the new subcommand. -- Integration success coverage in `tests/filter_roundtrip.rs` for nearest-manifest update and byte preservation. +- Integration success coverage in `tests/filter_roundtrip.rs` for selected-manifest update and byte preservation. - Integration coverage for missing matching local key: warning, manifest file creation, and no key entry. - Existing full suite should continue covering clean/smudge/key-store behavior. - Release build and binary-size measurement because this changes CLI and command logic. @@ -219,12 +259,11 @@ This directly supports migrating existing encrypted repositories to the new comm ## Assumptions - This is approved to remain in the existing `codex/fix-clone-smudge` PR because it is migration support for the same committed-manifest clone-smudge feature. -- `--path` is repository-relative, matching clean/smudge path semantics. +- `register` arguments are cwd-relative worktree paths for shell completion; implementation converts them to repository-relative filter paths for manifest entries. +- Advanced stdin/input-path support is out of scope for the first PR; this stays file-path-only, with one or more positional file arguments and an optional `--manifest-dir ` manifest selector. - If no matching local key exists, the migration command should warn, ensure the manifest file exists, and leave the key entry absent so users can add matching keys later and rerun registration. -- Creating a root manifest when no nearer manifest exists is acceptable because it matches `clean` behavior. +- Without `--manifest-dir`, the selected manifest directory is the current directory. With `--manifest-dir `, the selected manifest directory is that cwd-relative directory. ## Open questions -- Is `register-file` the accepted command name, or do you want a different name before implementation? -- Should advanced stdin support be included now, for example `register-file --path --input ` or `--stdin`, or should this stay file-path-only for the first PR? - - Note: no. this should stay file-path-only for the first PR +- None. From 38fe486b9096bb53fa8e242c8227eddc1b3ef48f Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Sun, 26 Jul 2026 13:31:08 +0900 Subject: [PATCH 8/9] feat(cli): add encrypted file register command Why: - Existing encrypted worktree files need a migration path into committed key manifests. - Users need cwd-relative paths that match shell completion and an explicit manifest directory override when registering from subdirectories. What: - Add git-zcrypt register [--manifest-dir ] ... parsing and dispatch. - Resolve cwd-relative encrypted files to repository-relative manifest paths and update the selected manifest without rewriting files. - Add local key alias lookup by embedded key id, including duplicate-alias detection. - Cover selected manifest updates, multi-file registration, missing-key warnings, and docs. Impact: - Adds a new migration CLI command without changing clean or smudge behavior. - Missing local keys create the selected manifest and warn without adding an entry. - Verified with cargo fmt --check, cargo test, cargo build --release, docs rg check, and release binary size 616256 bytes. Prompt: - To migrate, I need a command that takes an encrypted file and add entry to nearest JSON whenever the key is found. - Thanks. if the current directory is repo/a/b, the encrypted file is repo/a/b/c.secret, and the desired manifest is repo/a/git-zcrypt-keys.json, I'd rather move to repo/a and run git-zcrypt register-file here, giving b/c.secret because it's what auto-completion gives me. Besides, what happens if I want to give multiple files? - Some people might want to maken manifests other than pwd. I want the config for this - Added notes --- README.md | 21 +++ .../feature_list.json | 12 +- docs/data-formats.md | 4 +- src/cli.rs | 88 ++++++++-- src/key_manifest.rs | 161 ++++++++++++++++-- src/key_store.rs | 41 +++++ src/main.rs | 41 ++++- tests/filter_roundtrip.rs | 126 ++++++++++++++ 8 files changed, 460 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 876aea9..09c0d56 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,27 @@ To create a narrower manifest boundary for a subdirectory, initialize one there: git-zcrypt init-manifest --path secrets/team-a ``` +To migrate existing encrypted worktree files into a manifest, run `register` +with one or more paths relative to your current directory. By default it creates +or updates `git-zcrypt-keys.json` in the current directory: + +```sh +cd secrets +git-zcrypt register team-a/secret.txt team-b/secret.txt +``` + +Use `--manifest-dir ` to select another manifest directory relative to the +current directory: + +```sh +git-zcrypt register --manifest-dir .. secret.txt +``` + +`register` reads encrypted blob metadata, adds a manifest entry only when the +matching local key is available, and never rewrites the encrypted files. If a +matching local key is missing, it creates the selected manifest file and warns +without adding an entry. + Install the local Git filter config: ```sh diff --git a/codex-notes/migrate-encrypted-manifest/feature_list.json b/codex-notes/migrate-encrypted-manifest/feature_list.json index 5f019ef..6a7f198 100644 --- a/codex-notes/migrate-encrypted-manifest/feature_list.json +++ b/codex-notes/migrate-encrypted-manifest/feature_list.json @@ -4,7 +4,7 @@ "id": "parse-register", "description": "Add a register [--manifest-dir ] ... CLI command to src/cli.rs and usage text.", "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact", - "passes": false, + "passes": true, "boundary": { "files_dirs": [ "src/cli.rs" @@ -17,7 +17,7 @@ "id": "lookup-local-key-alias", "description": "Add a key-store API that finds the local alias matching an embedded sha256 key id and errors on duplicate aliases.", "validation": "Validate through full cargo test and targeted integration coverage.", - "passes": false, + "passes": true, "boundary": { "files_dirs": [ "src/key_store.rs" @@ -30,7 +30,7 @@ "id": "register-command", "description": "Implement register so files are cwd-relative, the manifest comes from --manifest-dir or cwd, and multiple encrypted files are supported.", "validation": "cargo test --test filter_roundtrip register_updates_selected_manifest_without_rewriting_file -- --exact", - "passes": false, + "passes": true, "boundary": { "files_dirs": [ "src/main.rs", @@ -47,7 +47,7 @@ "id": "register-missing-key-warning", "description": "Add coverage proving register warns and creates the selected manifest file without adding a key entry when no matching local key exists.", "validation": "cargo test --test filter_roundtrip register_warns_and_creates_manifest_without_matching_local_key -- --exact", - "passes": false, + "passes": true, "boundary": { "files_dirs": [ "tests/filter_roundtrip.rs", @@ -63,7 +63,7 @@ "id": "document-register", "description": "Document register migration behavior in README.md and docs/data-formats.md.", "validation": "rg -q \"git-zcrypt register\" README.md docs/data-formats.md", - "passes": false, + "passes": true, "boundary": { "files_dirs": [ "README.md", @@ -77,7 +77,7 @@ "id": "full-validation", "description": "Run formatting, the full test suite, release build, binary-size measurement, and applicable validators.", "validation": "cargo fmt --check; cargo test; cargo build --release; ruby -e 'puts File.size(%q[target/release/git-zcrypt])'", - "passes": false, + "passes": true, "boundary": { "files_dirs": [ "src", diff --git a/docs/data-formats.md b/docs/data-formats.md index cfc6615..8953be0 100644 --- a/docs/data-formats.md +++ b/docs/data-formats.md @@ -53,7 +53,9 @@ manifest is read. Key names may contain only ASCII letters, digits, `_`, and For a filtered path, `git-zcrypt` uses the nearest `git-zcrypt-keys.json` found by walking from the file's directory upward toward the repository root. A root manifest can be created with `git-zcrypt init-manifest`; subdirectory manifests -can be created with `git-zcrypt init-manifest --path `. +can be created with `git-zcrypt init-manifest --path `. Existing encrypted +blobs carry the key-id metadata needed for `git-zcrypt register ...` to +populate the selected manifest when the matching local key alias is available. ## Local Key File Format diff --git a/src/cli.rs b/src/cli.rs index d8ea724..08875ee 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -13,16 +13,42 @@ pub(crate) struct Cli { pub(crate) enum Command { Help, Init, - InitManifest { path: PathBuf }, - GenerateKey { key: String }, - ImportKey { key: String, input: PathBuf }, - DeriveKey { key: String, stdin: bool }, - ExportKey { key: String, output: PathBuf }, - DeleteKey { key: String }, - InstallFilter { key: String }, + InitManifest { + path: PathBuf, + }, + GenerateKey { + key: String, + }, + ImportKey { + key: String, + input: PathBuf, + }, + DeriveKey { + key: String, + stdin: bool, + }, + ExportKey { + key: String, + output: PathBuf, + }, + DeleteKey { + key: String, + }, + InstallFilter { + key: String, + }, Status, - Clean { key: String, path: PathBuf }, - Smudge { path: PathBuf }, + Clean { + key: String, + path: PathBuf, + }, + Smudge { + path: PathBuf, + }, + Register { + manifest_dir: Option, + paths: Vec, + }, } impl Cli { @@ -83,6 +109,13 @@ impl Cli { "smudge" => Command::Smudge { path: parse_required_path("smudge", &mut args, "--path")?, }, + "register" => { + let (manifest_dir, paths) = parse_register("register", &mut args)?; + Command::Register { + manifest_dir, + paths, + } + } _ => bail!("unknown command '{command}'\n\n{}", usage()), }; Ok(Self { command }) @@ -223,6 +256,30 @@ fn parse_required_path( path.context(format!("{command}: missing {path_option}")) } +fn parse_register(command: &str, args: &mut Args) -> Result<(Option, Vec)> { + let mut manifest_dir = None; + let mut paths = Vec::new(); + while let Some(arg) = args.next() { + if arg.to_string_lossy().starts_with("--") { + let (option, inline_value) = parse_option(command, arg)?; + if option == "--manifest-dir" { + set_once( + command, + option, + &mut manifest_dir, + PathBuf::from(option_value(command, option, inline_value, args)?), + )?; + } else { + bail!("{command}: unexpected option '{option}'"); + } + } else { + paths.push(PathBuf::from(arg)); + } + } + ensure!(!paths.is_empty(), "{command}: missing "); + Ok((manifest_dir, paths)) +} + fn parse_derive_key(args: &mut Args) -> Result<(String, bool)> { let command = "derive-key"; let mut key = None; @@ -268,6 +325,7 @@ fn parse_option(command: &str, arg: OsString) -> Result<(&'static str, Option "--output", "--stdin" => "--stdin", "--path" => "--path", + "--manifest-dir" => "--manifest-dir", _ => bail!("{command}: unknown option '{name}'"), }; Ok((option, value)) @@ -318,7 +376,8 @@ pub(crate) fn usage() -> &'static str { git-zcrypt install-filter --key git-zcrypt status git-zcrypt clean --key --path - git-zcrypt smudge --path " + git-zcrypt smudge --path + git-zcrypt register [--manifest-dir ] ..." } #[cfg(test)] @@ -362,6 +421,15 @@ mod tests { "secrets/a.txt", ], vec!["git-zcrypt", "smudge", "--path", "secrets/a.txt"], + vec!["git-zcrypt", "register", "secrets/a.txt"], + vec!["git-zcrypt", "register", "secrets/a.txt", "secrets/b.txt"], + vec![ + "git-zcrypt", + "register", + "--manifest-dir", + "secrets", + "secrets/a.txt", + ], ] { Cli::try_parse_from(args).expect("subcommand should parse"); } diff --git a/src/key_manifest.rs b/src/key_manifest.rs index 3a7ac58..dd220ca 100644 --- a/src/key_manifest.rs +++ b/src/key_manifest.rs @@ -11,6 +11,19 @@ use std::process::Command; pub const MANIFEST_FILE: &str = "git-zcrypt-keys.json"; +#[derive(Debug)] +pub struct SelectedManifest { + pub path: PathBuf, + dir: PathBuf, +} + +#[derive(Debug)] +pub struct ResolvedWorktreeFile { + pub input_path: PathBuf, + pub worktree_path: PathBuf, + pub repo_path: PathBuf, +} + pub fn init_manifest(path: &Path) -> Result { let root = worktree_root()?; let dir = resolve_dir(&root, path)?; @@ -30,21 +43,7 @@ pub fn add_key_for_path(path: &Path, key_id: &str, key_name: &str) -> Result Result { Ok(keys.contains_key(key_id)) } +pub fn resolve_worktree_file(path: &Path) -> Result { + ensure!( + !path.as_os_str().is_empty(), + "register path must not be empty" + ); + ensure!( + !path.is_absolute(), + "register path must be relative: {}", + path.display() + ); + let root = worktree_root()?; + let current_dir = env::current_dir().context("failed to get current directory")?; + let worktree_path = normalize_path(¤t_dir.join(path)); + ensure!( + worktree_path.starts_with(&root), + "register path must stay inside the repository: {}", + path.display() + ); + let repo_path = worktree_path + .strip_prefix(&root) + .with_context(|| { + format!( + "register path must stay inside the repository: {}", + path.display() + ) + })? + .to_path_buf(); + ensure!( + !repo_path.as_os_str().is_empty(), + "register path must name a file" + ); + Ok(ResolvedWorktreeFile { + input_path: path.to_path_buf(), + worktree_path, + repo_path, + }) +} + +pub fn resolve_selected_manifest_dir(path: Option<&Path>) -> Result { + let root = worktree_root()?; + let dir = match path { + Some(path) => resolve_cwd_relative_dir(&root, path)?, + None => env::current_dir().context("failed to get current directory")?, + }; + let dir = normalize_path(&dir); + ensure!( + dir.starts_with(&root), + "manifest path must stay inside the repository: {}", + path.unwrap_or_else(|| Path::new(".")).display() + ); + Ok(SelectedManifest { + path: dir.join(MANIFEST_FILE), + dir, + }) +} + +pub fn ensure_manifest_covers_path(manifest: &SelectedManifest, repo_path: &Path) -> Result<()> { + let root = worktree_root()?; + let file_path = root.join(repo_path); + ensure!( + file_path.starts_with(&manifest.dir), + "manifest {} does not cover {}", + manifest.path.display(), + repo_path.display() + ); + Ok(()) +} + +pub fn ensure_manifest(path: &Path) -> Result<()> { + if path.exists() { + read_manifest(path)?; + } else { + write_manifest(path, &BTreeMap::new())?; + } + Ok(()) +} + +pub fn add_key_to_manifest(path: &Path, key_id: &str, key_name: &str) -> Result<()> { + key_store::validate_key_id(key_id)?; + key_store::validate_key_name(key_name)?; + let mut keys = if path.exists() { + read_manifest(path)? + } else { + BTreeMap::new() + }; + if let Some(existing) = keys.get(key_id) { + ensure!( + existing == key_name, + "manifest {} maps {key_id} to {existing}, not {key_name}", + path.display() + ); + return Ok(()); + } + keys.insert(key_id.to_owned(), key_name.to_owned()); + write_manifest(path, &keys) +} + pub fn read_manifest(path: &Path) -> Result> { let input = fs::read_to_string(path) .with_context(|| format!("failed to read key manifest {}", path.display()))?; @@ -145,6 +241,41 @@ fn resolve_dir(root: &Path, path: &Path) -> Result { Ok(dir) } +fn resolve_cwd_relative_dir(root: &Path, path: &Path) -> Result { + ensure!( + !path.is_absolute(), + "manifest path must be relative: {}", + path.display() + ); + let current_dir = env::current_dir().context("failed to get current directory")?; + let dir = if path.as_os_str().is_empty() || path == Path::new(".") { + current_dir + } else { + current_dir.join(path) + }; + let dir = normalize_path(&dir); + ensure!( + dir.starts_with(root), + "manifest path must stay inside the repository: {}", + path.display() + ); + Ok(dir) +} + +fn normalize_path(path: &Path) -> PathBuf { + let mut normalized = PathBuf::new(); + for component in path.components() { + match component { + Component::CurDir => {} + Component::ParentDir => { + normalized.pop(); + } + _ => normalized.push(component.as_os_str()), + } + } + normalized +} + fn write_manifest(path: &Path, keys: &BTreeMap) -> Result<()> { if let Some(parent) = path.parent() { fs::create_dir_all(parent) diff --git a/src/key_store.rs b/src/key_store.rs index 68500de..b72ae0f 100644 --- a/src/key_store.rs +++ b/src/key_store.rs @@ -166,6 +166,19 @@ impl KeyStore { Ok(None) } + pub fn key_name_for_id(&self, key_id: &str) -> Result> { + validate_key_id(key_id)?; + let mut found = None; + for name in self.key_names()? { + let key = self.read_key(&name)?; + if key_id_for_key_bytes(&key)? == key_id { + ensure!(found.is_none(), "multiple local keys match {key_id}"); + found = Some(name); + } + } + Ok(found) + } + pub fn read_key(&self, name: &str) -> Result>> { let path = self.key_path(name)?; let bytes = Zeroizing::new( @@ -479,6 +492,34 @@ mod tests { result.expect("delete key"); } + #[test] + fn key_name_for_id_finds_alias_and_rejects_duplicates() { + let temp = TempDir::new().expect("tempdir"); + let status = Command::new("git") + .arg("init") + .current_dir(temp.path()) + .status() + .expect("git init"); + assert!(status.success()); + + let result = (|| { + let store = KeyStore::discover_from(temp.path())?; + store.store_key("default", &[8_u8; 32])?; + let key_id = key_id_for_key(&[8_u8; 32]); + assert_eq!(store.key_name_for_id(&key_id)?, Some("default".to_owned())); + assert_eq!(store.key_name_for_id(&key_id_for_key(&[9_u8; 32]))?, None); + + let duplicate = fs::read(store.key_path("default")?)?; + fs::write(store.key_path("duplicate")?, duplicate)?; + store + .key_name_for_id(&key_id) + .expect_err("duplicate aliases should fail"); + Ok::<_, crate::error::Error>(()) + })(); + + result.expect("key alias lookup"); + } + #[test] fn versioned_key_files_reject_malformed_headers() { let temp = TempDir::new().expect("tempdir"); diff --git a/src/main.rs b/src/main.rs index 1a1aa0d..0a4e6c1 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,5 +1,6 @@ use crate::error::Result; use std::io::{self, Read, Write}; +use std::path::{Path, PathBuf}; mod blob; mod cli; @@ -64,10 +65,14 @@ fn run(cli: Cli) -> Result<()> { Command::Status => git_config::print_status(), Command::Clean { key, path } => clean(&key, &path), Command::Smudge { path } => smudge(&path), + Command::Register { + manifest_dir, + paths, + } => register(manifest_dir.as_deref(), &paths), } } -fn clean(key_name: &str, path: &std::path::Path) -> Result<()> { +fn clean(key_name: &str, path: &Path) -> Result<()> { let store = key_store::KeyStore::discover()?; let (key, key_id) = store.read_key_with_id(key_name)?; let input = read_stdin()?; @@ -78,7 +83,7 @@ fn clean(key_name: &str, path: &std::path::Path) -> Result<()> { write_stdout(&encoded) } -fn smudge(path: &std::path::Path) -> Result<()> { +fn smudge(path: &Path) -> Result<()> { let store = key_store::KeyStore::discover()?; let input = read_stdin()?; let encrypted = blob::decode(&input)?; @@ -102,6 +107,38 @@ fn smudge(path: &std::path::Path) -> Result<()> { write_stdout(&plaintext) } +fn register(manifest_dir: Option<&Path>, paths: &[PathBuf]) -> Result<()> { + let store = key_store::KeyStore::discover()?; + let manifest = key_manifest::resolve_selected_manifest_dir(manifest_dir)?; + for path in paths { + let resolved = key_manifest::resolve_worktree_file(path)?; + key_manifest::ensure_manifest_covers_path(&manifest, &resolved.repo_path)?; + let input = std::fs::read(&resolved.worktree_path).map_err(|error| { + crate::error::Error::msg(format!( + "failed to read encrypted file {}: {error}", + resolved.worktree_path.display() + )) + })?; + let encrypted = blob::decode(&input).map_err(|error| { + crate::error::Error::msg(format!( + "failed to decode encrypted file {}: {error:#}", + resolved.input_path.display() + )) + })?; + if let Some(key_name) = store.key_name_for_id(&encrypted.key_id)? { + key_manifest::add_key_to_manifest(&manifest.path, &encrypted.key_id, &key_name)?; + } else { + eprintln!( + "warning: no local key is registered for {}; leaving manifest entry absent for {}", + encrypted.key_id, + resolved.repo_path.display() + ); + key_manifest::ensure_manifest(&manifest.path)?; + } + } + Ok(()) +} + fn read_stdin() -> Result> { let mut input = Vec::new(); io::stdin().lock().read_to_end(&mut input)?; diff --git a/tests/filter_roundtrip.rs b/tests/filter_roundtrip.rs index 1eac1d5..6b0986b 100644 --- a/tests/filter_roundtrip.rs +++ b/tests/filter_roundtrip.rs @@ -77,6 +77,33 @@ fn key_id_from_blob(blob: &[u8]) -> &str { std::str::from_utf8(&blob[key_id_start..key_id_start + key_id_len]).expect("key id utf8") } +fn command_in(cwd: &std::path::Path, args: &[&str]) -> std::process::Output { + Command::new(git_zcrypt()) + .args(args) + .current_dir(cwd) + .output() + .expect("git-zcrypt command") +} + +fn write_encrypted_file(repo: &TempDir, path: &str, plaintext: &[u8]) -> Vec { + let clean = filter( + repo, + &["clean", "--key", "default", "--path", path], + plaintext, + ); + assert!( + clean.status.success(), + "{}", + String::from_utf8_lossy(&clean.stderr) + ); + let full_path = repo.path().join(path); + if let Some(parent) = full_path.parent() { + std::fs::create_dir_all(parent).expect("mkdir encrypted parent"); + } + std::fs::write(&full_path, &clean.stdout).expect("write encrypted file"); + clean.stdout +} + #[test] fn init_manifest_creates_committed_key_manifest() { let repo = init_empty_repo(); @@ -144,6 +171,105 @@ fn clean_updates_committed_key_manifest() { assert!(manifest.contains("default")); } +#[test] +fn register_updates_selected_manifest_without_rewriting_file() { + let repo = init_repo(); + + let encrypted = write_encrypted_file(&repo, "secrets/team-a/secret.txt", b"secret"); + let key_id = key_id_from_blob(&encrypted).to_owned(); + std::fs::remove_file(repo.path().join("git-zcrypt-keys.json")).expect("remove root manifest"); + + let init = filter(&repo, &["init-manifest", "--path", "secrets"], b""); + assert!( + init.status.success(), + "{}", + String::from_utf8_lossy(&init.stderr) + ); + + let register = command_in( + &repo.path().join("secrets"), + &["register", "team-a/secret.txt"], + ); + assert!( + register.status.success(), + "{}", + String::from_utf8_lossy(®ister.stderr) + ); + + let manifest = std::fs::read_to_string(repo.path().join("secrets/git-zcrypt-keys.json")) + .expect("read selected manifest"); + assert!(manifest.contains(&key_id)); + assert!(manifest.contains("default")); + assert!(!repo.path().join("git-zcrypt-keys.json").exists()); + assert_eq!( + std::fs::read(repo.path().join("secrets/team-a/secret.txt")).expect("read encrypted"), + encrypted + ); + + let parent_encrypted = write_encrypted_file(&repo, "secrets/team-a/parent.secret", b"parent"); + let parent_register = command_in( + &repo.path().join("secrets/team-a"), + &["register", "--manifest-dir", "..", "parent.secret"], + ); + assert!( + parent_register.status.success(), + "{}", + String::from_utf8_lossy(&parent_register.stderr) + ); + assert_eq!( + std::fs::read(repo.path().join("secrets/team-a/parent.secret")) + .expect("read parent encrypted"), + parent_encrypted + ); + + std::fs::write(repo.path().join("secrets/git-zcrypt-keys.json"), "{\n}\n") + .expect("clear selected manifest"); + let first = write_encrypted_file(&repo, "secrets/a.secret", b"a"); + let second = write_encrypted_file(&repo, "secrets/b.secret", b"b"); + std::fs::write(repo.path().join("secrets/git-zcrypt-keys.json"), "{\n}\n") + .expect("clear selected manifest again"); + let multiple = command_in( + &repo.path().join("secrets"), + &["register", "a.secret", "b.secret"], + ); + assert!( + multiple.status.success(), + "{}", + String::from_utf8_lossy(&multiple.stderr) + ); + let manifest = std::fs::read_to_string(repo.path().join("secrets/git-zcrypt-keys.json")) + .expect("read multi manifest"); + assert!(manifest.contains(key_id_from_blob(&first))); + assert!(manifest.contains(key_id_from_blob(&second))); +} + +#[test] +fn register_warns_and_creates_manifest_without_matching_local_key() { + let repo = init_repo(); + let encrypted = write_encrypted_file(&repo, "secrets/team-a/missing.secret", b"missing"); + let key_id = key_id_from_blob(&encrypted).to_owned(); + std::fs::remove_file(repo.path().join("git-zcrypt-keys.json")).expect("remove root manifest"); + std::fs::remove_file(repo.path().join(".git/git-zcrypt/keys/default.key")) + .expect("remove local key"); + + let register = command_in( + &repo.path().join("secrets/team-a"), + &["register", "missing.secret"], + ); + assert!( + register.status.success(), + "{}", + String::from_utf8_lossy(®ister.stderr) + ); + let stderr = String::from_utf8_lossy(®ister.stderr); + assert!(stderr.contains("no local key is registered")); + + let manifest = std::fs::read_to_string(repo.path().join("secrets/team-a/git-zcrypt-keys.json")) + .expect("read created manifest"); + assert_eq!(manifest, "{\n}\n"); + assert!(!manifest.contains(&key_id)); +} + #[test] fn raw_key_round_trip_uses_hash_prefixed_key_id() { let repo = init_repo(); From 0751cdef16270b1465fe2c7423adee5a968b07d0 Mon Sep 17 00:00:00 2001 From: koba-e964 <3303362+koba-e964@users.noreply.github.com> Date: Tue, 29 Sep 2026 23:37:52 +0900 Subject: [PATCH 9/9] chore: remove PR review notes and enable format hook --- .pre-commit-config.yaml | 9 + .../fix-clone-smudge/feature_list.json | 64 ----- codex-notes/fix-clone-smudge/plan.md | 218 -------------- codex-notes/fix-clone-smudge/research.md | 169 ----------- .../feature_list.json | 93 ------ .../migrate-encrypted-manifest/plan.md | 269 ------------------ .../migrate-encrypted-manifest/research.md | 141 --------- 7 files changed, 9 insertions(+), 954 deletions(-) create mode 100644 .pre-commit-config.yaml delete mode 100644 codex-notes/fix-clone-smudge/feature_list.json delete mode 100644 codex-notes/fix-clone-smudge/plan.md delete mode 100644 codex-notes/fix-clone-smudge/research.md delete mode 100644 codex-notes/migrate-encrypted-manifest/feature_list.json delete mode 100644 codex-notes/migrate-encrypted-manifest/plan.md delete mode 100644 codex-notes/migrate-encrypted-manifest/research.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..4d04aba --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,9 @@ +repos: + - repo: local + hooks: + - id: cargo-fmt + name: cargo fmt --check + entry: cargo fmt --check + language: system + types: [rust] + pass_filenames: false diff --git a/codex-notes/fix-clone-smudge/feature_list.json b/codex-notes/fix-clone-smudge/feature_list.json deleted file mode 100644 index 4bf4a7c..0000000 --- a/codex-notes/fix-clone-smudge/feature_list.json +++ /dev/null @@ -1,64 +0,0 @@ -{ - "features": [ - { - "id": "path-aware-filters", - "description": "Update installed filter commands and CLI parsing so clean and smudge receive the filtered file path.", - "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact && cargo test git_config::tests::install_filter_writes_local_git_config -- --exact", - "passes": true - }, - { - "id": "init-manifest-command", - "description": "Add git-zcrypt init-manifest with optional --path to create git-zcrypt-keys.json in the current or specified directory.", - "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact && cargo test --test filter_roundtrip init_manifest_creates_committed_key_manifest -- --exact", - "passes": true - }, - { - "id": "committed-key-manifest", - "description": "Add committed git-zcrypt-keys.json parsing, formatting, validation, initialization, and nearest-ancestor lookup.", - "validation": "cargo test key_manifest::tests", - "passes": true - }, - { - "id": "replace-local-index", - "description": "Replace .git/git-zcrypt/index.json as the durable key-id mapping with committed manifest lookup and local key scanning.", - "validation": "cargo test key_store::tests", - "passes": true - }, - { - "id": "clean-updates-manifest", - "description": "Make clean update the nearest existing committed manifest for the filtered path with the selected key id and fail clearly when none exists.", - "validation": "cargo test --test filter_roundtrip clean_updates_committed_key_manifest -- --exact", - "passes": true - }, - { - "id": "smudge-authorizes-by-manifest", - "description": "Make smudge require the blob key id to be declared by the nearest committed manifest.", - "validation": "cargo test --test filter_roundtrip smudge_rejects_manifest_mismatch -- --exact", - "passes": true - }, - { - "id": "missing-key-pass-through", - "description": "Make smudge warn and pass encrypted bytes through when the manifest authorizes the blob key id but no local key is available.", - "validation": "cargo test --test filter_roundtrip delete_key_removes_local_key_material -- --exact", - "passes": true - }, - { - "id": "clone-without-key", - "description": "Add clone/checkout coverage showing a repo with committed manifests can be checked out without local key material.", - "validation": "cargo test --test filter_roundtrip clone_without_local_key_checks_out_encrypted_blob_and_restore_resmudges -- --exact", - "passes": true - }, - { - "id": "document-manifest-flow", - "description": "Document init-manifest, committed manifests, clone-without-key behavior, and the validated re-smudge command after key setup.", - "validation": "rg -q 'git-zcrypt-keys\\.json' README.md docs/data-formats.md", - "passes": true - }, - { - "id": "full-validation", - "description": "Run formatting and the full test suite after implementation.", - "validation": "cargo fmt --check && cargo test", - "passes": true - } - ] -} diff --git a/codex-notes/fix-clone-smudge/plan.md b/codex-notes/fix-clone-smudge/plan.md deleted file mode 100644 index d68daee..0000000 --- a/codex-notes/fix-clone-smudge/plan.md +++ /dev/null @@ -1,218 +0,0 @@ -## Overview - -Fix issue 8 by making key-id metadata clone-portable. The local `.git/git-zcrypt/index.json` is non-secret but unavailable in fresh clones, so it should be replaced as the durable mapping by committed non-secret manifest files named `git-zcrypt-keys.json`. - -The manifest lookup must be path-sensitive: for a filtered file, use the nearest `git-zcrypt-keys.json` found by walking from the file's directory upward toward the repository root. To support that, installed Git filter commands must pass the filtered path to `clean` and `smudge` using Git's filter path placeholder. The implementation should verify the placeholder behavior in tests before relying on it. - -When smudge sees a well-formed encrypted blob whose key id is allowed by the committed manifest but whose local key file is not present, it should warn to stderr, write the original encrypted bytes to stdout, and exit successfully. This lets clone and checkout complete without local key material. Malformed blobs, manifest mismatches, wrong keys, and decryption failures with an available key remain hard failures. - -## Files To Change - -- `src/cli.rs` - - Add an `init-manifest` command. - - `init-manifest` should default to the current directory and accept `--path ` to initialize a manifest in a specified directory. - - Add path options to the filter commands. - - `clean` should accept `--path ` in addition to `--key `. - - `smudge` should accept `--path `. - -- `src/git_config.rs` - - Install path-aware filter commands, likely: - - `git-zcrypt clean --key --path %f` - - `git-zcrypt smudge --path %f` - - Keep `filter.git-zcrypt.required=true` initially. - - Update `status` to report committed manifest state instead of local index state. - -- `src/main.rs` - - Implement `init-manifest` by creating `git-zcrypt-keys.json` in the current or specified directory. - - Pass the target path from CLI parsing into `clean` and `smudge`. - - On clean, update the nearest committed manifest for the path with the blob key id produced for the selected key. - - On smudge, use the target path to find the nearest committed manifest and validate that the blob key id is declared there. - - If the manifest declares the blob key id but no local key material exists, warn and pass encrypted bytes through unchanged. - -- `src/key_store.rs` - - Stop using `.git/git-zcrypt/index.json` as the durable key-id mapping. - - Keep local key files under `.git/git-zcrypt/keys/`. - - Resolve local key material by computing each local key file's key id and matching it to the manifest-declared blob key id. - - Preserve duplicate-key-material detection where practical by scanning local keys. - - Remove or deprecate index write/read paths after replacement behavior is covered. - -- New module, likely `src/key_manifest.rs` - - Own committed `git-zcrypt-keys.json` parsing and formatting. - - Initialize empty manifests. - - Find the nearest manifest for a target path by walking ancestors from file directory upward. - - Update manifests atomically when clean introduces a key id. - - Reuse the existing constrained JSON map shape from `.git/git-zcrypt/index.json`. - - Validate key ids with existing `key_store::validate_key_id` and names with existing key-name validation. - -- `tests/filter_roundtrip.rs` - - Add integration coverage for path-aware filter commands. - - Add clone/checkout coverage with committed manifests but no local key material. - - Update existing missing-key expectations to pass-through behavior only when the manifest authorizes the key id. - -- `README.md` - - Document `init-manifest`, `git-zcrypt-keys.json`, nearest-ancestor lookup, clone behavior without local keys, and how to re-smudge files after importing or deriving keys. - -- `docs/data-formats.md` - - Document the committed manifest format. - -- `codex-notes/fix-clone-smudge/feature_list.json` - - Track implementation tasks and validation commands. - -## Detailed Implementation Steps - -1. Verify Git filter path placeholder behavior. - - Add a focused integration test or temporary test harness that configures a filter command containing `%f` and confirms Git passes the filtered path as an argument. - - Use the validated command shape in `install_filter`. - - If `%f` needs quoting or has path separator edge cases, encode that in tests before implementation proceeds. - -2. Add CLI parsing for manifest initialization and path-aware filters. - - Add `Command::InitManifest { path }`. - - Parse `init-manifest` with optional `--path `. - - Default `init-manifest` to the current directory when `--path` is omitted. - - Change `Command::Clean { key }` to `Command::Clean { key, path }`. - - Change `Command::Smudge` to `Command::Smudge { path }`. - - Add tests for: - - `init-manifest` - - `init-manifest --path secrets/team-a` - - `clean --key default --path secrets/a.txt` - - `smudge --path secrets/a.txt` - - duplicate/missing/unexpected options. - -3. Introduce committed manifest support. - - Use `git-zcrypt-keys.json` as the manifest filename. - - Keep the current `.git/git-zcrypt/index.json` schema instead of inventing a new one: a constrained JSON object mapping key id to key name. - - Example: - ```json - { - "sha256:<64 lowercase hex chars>": "default" - } - ``` - - Keep entries sorted lexicographically by key id for stable diffs. - - Reject malformed JSON, duplicate keys as far as the parser can detect, invalid key ids, and invalid key names. - - Add an initializer that creates an empty manifest: - ```json - {} - ``` - - Find the relevant manifest by walking ancestors of the filtered file path from deepest to shallowest. - - `clean` should update the nearest existing manifest. - - If no manifest exists anywhere in the repository, `clean` should create a root `git-zcrypt-keys.json`. - - Users create subdirectory manifests explicitly with `init-manifest --path `. - -4. Replace local index lookup with local key scanning. - - Keep `.git/git-zcrypt/keys/.key` as the local secret-key storage. - - Add a method that scans local key files, computes each key id, and returns the matching key for a requested key id. - - If no local key matches, return a typed or distinguishable missing-local-key result. - - If a local key file is malformed, surface a warning or hard error according to the command context: - - Smudge for a manifest-declared key with no matching local key should pass through only when no matching key exists. - - Smudge should still fail if it finds a matching key but decrypt/decompress fails. - -5. Update key creation commands. - - `generate-key`, `derive-key`, and `import-key` should still create local key files. - - They should update the nearest `git-zcrypt-keys.json` only when a command has enough path context; otherwise they should create local key material only and leave manifest registration to `clean`. - - They should not write `.git/git-zcrypt/index.json`. - - Duplicate key material detection should scan local keys and committed manifests rather than consult local index. - - `delete-key` should remove only local key files; it should not remove committed manifest declarations because those describe repository data, not local possession. - -6. Update clean behavior. - - Resolve selected local key alias as today. - - Compute its key id and encrypt with that id as today. - - Find the nearest applicable `git-zcrypt-keys.json` for the target path. - - If no manifest exists in any ancestor directory up to the repository root, create a root `git-zcrypt-keys.json`. - - Add the key id if absent and write the manifest with stable formatting. - - Do not write `.git/git-zcrypt/index.json`. - -7. Update smudge behavior. - - Decode the blob first; malformed blobs remain fatal. - - Find the nearest committed manifest for the target path. - - Fail if no manifest exists or if the blob key id is not listed in the manifest. - - Scan local key files for a matching key id. - - If no matching key is present, print a warning to stderr, write the original encrypted input to stdout, and return success. - - If a matching key is present, decrypt and decompress as today. - -8. Preserve `filter.git-zcrypt.required=true` unless validation shows it prevents the intended pass-through. - - The intended pass-through exits with status 0, so `required=true` should remain compatible. - - Keeping it true preserves hard failures for malformed blobs and manifest mismatches. - -9. Document recovery after key setup. - - Validate `git restore --source=HEAD --worktree -- ` for re-smudging pass-through files after the user imports or derives a key. - - Document this command if the integration test confirms it rewrites encrypted pass-through bytes to plaintext. - -10. Update data-format documentation and README. - - Explain that `git-zcrypt-keys.json` is safe to commit because it contains key ids, not raw keys. - - Explain how to create root and subdirectory manifests with `git-zcrypt init-manifest`. - - Explain nearest-ancestor lookup. - - Explain that a clone without local keys may contain encrypted pass-through bytes until keys are registered and files are re-smudged. - -## Alternatives Considered - -- Only pass through missing local key errors without a committed manifest. - - Rejected because it hides too much: a fresh clone cannot know whether the key id is expected for that path or whether the blob is unexpected repository data. - -- Commit `.git/git-zcrypt/index.json` directly. - - Rejected because files under `.git/` are not part of the worktree and cannot be committed normally. The concept is useful, but it needs a committed worktree manifest file. - -- Keep both `.git/git-zcrypt/index.json` and committed manifests. - - Rejected because two mapping sources can drift and there is no compatibility guarantee needed for this change. - -- Change the manifest schema to a versioned `{ "version": 1, "keys": [...] }` object. - - Rejected because the existing `index.json` constrained map shape is already adequate and simpler. - -- Disable `filter.git-zcrypt.required`. - - Rejected for the initial plan because a status-0 pass-through for the specific missing-local-key case should be compatible with `required=true`, while disabling it would make unrelated filter failures easier to miss. - -- Put all key ids in one root-only manifest. - - Rejected because the requested behavior allows manifests in relevant subdirectories with nearest-ancestor lookup. - -- Have `clean` automatically create subdirectory manifests. - - Rejected because automatic creation cannot know the intended subdirectory boundary. `clean` should create a root manifest only when no manifest exists, otherwise update the nearest existing manifest. `init-manifest --path ` gives users an explicit way to create subdirectory boundaries. - -## Risks - -- Git path placeholder behavior may differ from assumptions. This must be validated before implementing path-sensitive lookup. -- Existing repositories with `.git/git-zcrypt/index.json` will need a clear breakage note; no compatibility fallback is planned. -- Pass-through files are encrypted bytes in the worktree; users need a validated recovery command after key setup. -- Manifest lookup can fail if the file path is absolute, outside the worktree, or contains `..`; path normalization must be conservative. -- Clean updating a committed manifest means normal encryption can modify both the secret file and `git-zcrypt-keys.json`; docs and tests should make this expected. -- If no manifest exists before cleaning filtered files, clean will create a root manifest. Users must explicitly create subdirectory manifests when they want narrower manifest boundaries. -- Scanning all local key files for each smudge may be slower than index lookup in repositories with many keys. This is acceptable initially, but the implementation should keep the scan simple and measurable. - -## Test Strategy - -- Unit tests: - - CLI parses `init-manifest` with and without `--path`. - - CLI parses path-aware `clean` and `smudge`. - - Manifest parser accepts the existing index-style map and rejects malformed maps, invalid key ids, and invalid key names. - - Manifest formatter produces stable sorted output. - - Manifest initializer writes an empty index-style map. - - Manifest lookup chooses the nearest ancestor manifest. - - Local key scanning resolves a key by computed key id. - -- Integration tests: - - `cargo test --test filter_roundtrip raw_key_round_trip_uses_hash_prefixed_key_id -- --exact` - - New test: `init-manifest` creates `git-zcrypt-keys.json` in the current directory. - - New test: `init-manifest --path ` creates `git-zcrypt-keys.json` in a subdirectory. - - New test: clean writes/updates `git-zcrypt-keys.json` for the filtered path. - - New test: smudge fails when the manifest is missing. - - New test: smudge fails when the manifest does not list the blob key id. - - New test: smudge passes through with a warning when the manifest lists the key id but no local key exists. - - New test: clone/checkout with committed manifest and no local key succeeds and leaves encrypted bytes in the worktree. - - New test: after importing/deriving the key, `git restore --source=HEAD --worktree -- ` rewrites pass-through bytes to plaintext. - -- Full validation: - - `cargo fmt --check` - - `cargo test` - - If binary-size-sensitive changes are expected from new dependencies, avoid new dependencies; otherwise build release and report size. - -## Assumptions - -- `git-zcrypt-keys.json` is the planned manifest filename. -- The manifest contains key ids only, not raw keys. -- Users create subdirectory manifests explicitly with `git-zcrypt init-manifest --path `; root manifests can also be created explicitly, but `clean` creates the root manifest when no manifest exists. -- The local secret key files remain in `.git/git-zcrypt/keys/`. -- A manifest-declared missing local key should warn and pass through. -- A manifest mismatch should fail even if the local key exists. -- `required=true` should remain unless tests show it blocks the intended behavior. - -## Open Questions - -- Confirm `git restore --source=HEAD --worktree -- ` in implementation tests before documenting it as the recovery command. diff --git a/codex-notes/fix-clone-smudge/research.md b/codex-notes/fix-clone-smudge/research.md deleted file mode 100644 index d4dcf5a..0000000 --- a/codex-notes/fix-clone-smudge/research.md +++ /dev/null @@ -1,169 +0,0 @@ -## Relevant Files And Modules - -- `src/main.rs` - - Dispatches CLI commands and implements the filter entry points. - - `clean` loads a named local key, compresses stdin, encrypts, encodes a blob, and writes ciphertext to stdout. - - `smudge` reads stdin, decodes a blob, resolves the blob key id through local key state, decrypts, decompresses, and writes plaintext to stdout. - -- `src/key_store.rs` - - Discovers repository-local state below `.git/git-zcrypt/`. - - Stores keys under `.git/git-zcrypt/keys/`. - - Stores key-id-to-alias mappings in `.git/git-zcrypt/index.json`. - - `read_key_by_id` is the current smudge lookup path and fails if the blob key id is not registered locally. - - Review correction: `.git/git-zcrypt/index.json` is not secret, but it is local-only. The intended direction is for committed manifest files to replace this local index as the durable key-id mapping. - -- `src/git_config.rs` - - `install_filter` writes local Git config: - - `filter.git-zcrypt.clean = git-zcrypt clean --key ` - - `filter.git-zcrypt.smudge = git-zcrypt smudge` - - `filter.git-zcrypt.required = true` - - The required flag means a filter process failure blocks checkout. - - Current filter commands do not pass the target path to `clean` or `smudge`. - -- `src/blob.rs` - - Defines the committed encrypted blob format. - - `decode` validates magic, version, key id length, nonce length, reserved byte, UTF-8 key id, and non-empty key id. - -- `tests/filter_roundtrip.rs` - - Integration tests execute the built `git-zcrypt` binary. - - Existing missing-key coverage currently expects smudge to fail after deleting a key. - -- `.gitattributes` - - Applies `filter=git-zcrypt diff=git-zcrypt` to `secrets/**`. - - Does not currently identify a committed key manifest path. - -- Proposed committed key manifest, per review note - - A non-secret JSON file should be checked into the repository. - - Preferred name direction: `zit-crypt-keys.json` or similar. - - It may live at the repository root or in relevant subdirectories. - - If multiple manifests are found, file-specific lookup should use the first manifest found by walking ancestor directories from the target file directory upward. - - This committed manifest should replace the local `.git/git-zcrypt/index.json` role, not merely duplicate it. - -## Execution Flow And Call Graph - -Clean path: - -1. Git invokes `git-zcrypt clean --key `. -2. `Cli::parse_env` produces `Command::Clean`. -3. `run` calls `clean`. -4. `clean` calls `KeyStore::discover`. -5. `clean` calls `KeyStore::read_key_with_id`. -6. `clean` reads stdin, compresses, encrypts, blob-encodes, and writes stdout. - -Smudge path: - -1. Git invokes `git-zcrypt smudge`. -2. `Cli::parse_env` produces `Command::Smudge`. -3. `run` calls `smudge`. -4. `smudge` calls `KeyStore::discover`. -5. `smudge` reads stdin. -6. `smudge` calls `blob::decode`. -7. `smudge` calls `KeyStore::read_key_by_id`. -8. `read_key_by_id` validates the key id, reads `.git/git-zcrypt/index.json`, and requires a matching alias. -9. If found, it reads the key file and checks that the key computes to the requested key id. -10. `smudge` decrypts, decompresses, and writes plaintext. - -Path-sensitive committed manifest lookup is not possible with the current smudge command shape: - -1. Current Git config invokes `git-zcrypt smudge` with only blob bytes on stdin. -2. The command does not receive the target file path. -3. Without the target path, smudge cannot walk from the target file directory upward to choose the nearest committed manifest. -4. A plan that uses per-directory manifests therefore needs a way to pass the target path into the filter command, likely by changing installed filter config and CLI parsing. - -Failure observed while creating the issue worktree: - -1. Checkout reached `secrets/secret.txt`. -2. Git invoked `git-zcrypt smudge`. -3. The blob decoded with key id `sha256:a8a3cfd8a3833578e4d66ca0acc596fc0aa90df5656d354b3cf91fbd740d4f6c`. -4. No local key index entry existed in the new worktree state. -5. `read_key_by_id` returned `no local key is registered for ...`. -6. Git treated the required smudge filter failure as fatal and aborted checkout. - -## Data Structures And Invariants - -- Encrypted blob format: - - Magic: `GZC1\0\0\0\0` - - Version: `1` - - Header carries key id length, nonce length, and one reserved byte. - - Key id is authenticated metadata and must be present. - - Nonce length must be 12 bytes. - -- Key ids: - - Must be `sha256:` plus 64 lowercase hex characters. - - Are derived from the raw 32-byte key material. - - Are used in committed blobs, unlike local aliases. - -- Local key store: - - Key aliases are local names. - - `.git/git-zcrypt/index.json` maps committed key ids to local aliases. - - Key files live outside the worktree and are not committed. - - Current local index contents are not secret; the problem is clone portability, because the file is stored under `.git/` and is therefore absent from fresh clones. - -- Committed key manifest: - - Should contain only non-secret metadata safe to commit. - - Needs to identify which key ids are expected for files governed by that manifest. - - Should not contain raw key material. - - Replaces the current local key-id mapping role now handled by `.git/git-zcrypt/index.json`. - - Needs a clearly documented relationship to `.gitattributes`: the manifest controls which key ids are expected; attributes control which paths run through the filter. - -## Existing Architectural Patterns - -- Modules are small and direct: CLI parsing, Git config, key storage, blob encoding, compression, and crypto are separate. -- Errors use the repository-local `Error` type with `Context`, `bail!`, and `ensure!`. -- Secret key bytes use `Zeroizing>`. -- Tests prefer black-box integration through the compiled binary for filter behavior. - -## Naming Conventions - -- CLI commands are explicit verbs: `generate-key`, `derive-key`, `install-filter`, `delete-key`, `clean`, `smudge`. -- Key aliases are called `key` or `name`. -- Stable committed identifiers are called `key_id`. -- Tests are descriptive snake_case function names. - -## Error Handling Patterns - -- Invalid user input and malformed formats return `Error::msg`. -- `Context` wraps IO and parse failures with path or operation context. -- Existing smudge behavior treats missing local key registration as a hard error. -- Git filter failures surface through stderr and non-zero exit status. -- Review note resolved: warning text is preferred when smudge passes through because a local key is unavailable, as long as the warning does not inhibit Git filter behavior. - -## Potential Pitfalls - -- Passing through every smudge error would hide corruption or wrong-key failures. - - Review note: To address this, the repository should check in a non-secret key manifest. The preferred name is `zit-crypt-keys.json` or similar. It can be placed at the repo root or in relevant directories. If multiple manifests are found, use the first one in the target file's ancestor directories, searched from the file directory upward. -- Passing through only missing local key registration preserves validation for malformed blobs and cryptographic failures. -- If smudge succeeds without decrypting, the worktree file contains encrypted bytes. That is acceptable for clone completion but must be documented. -- Because `filter.git-zcrypt.required=true`, any non-zero smudge exit during checkout remains fatal. -- Tests that run Git checkout/clone need filter config available in the cloned repo or command-local config, since local Git config is not committed. -- If a file was checked out as encrypted pass-through bytes before keys were registered, Git will not necessarily rewrite it to plaintext merely because key state changes later. Documentation or setup flow may need to tell users how to force Git to run smudge again after registering the key. -- A manifest lookup based on ancestor directories depends on knowing the target path. The current smudge command lacks that information. -- Keeping both committed manifest files and `.git/git-zcrypt/index.json` as independent key-id mapping sources would create drift risk. The intended design should replace the local index with committed manifests rather than maintaining two durable mappings. - -## Constraints - -- The fix should keep one logical PR scope: clone/checkout with unavailable local key should not fail. -- Existing encrypted blob format should not change. -- Existing key file format should not change. -- `.git/git-zcrypt/index.json` has never been secret, but it is local-only and should be replaced by committed manifest lookup rather than kept as the durable mapping. -- Normal decryption with a registered key must keep working. -- Missing-key pass-through must not weaken tamper detection when a key is registered. -- Warning text on missing-key pass-through should be included unless testing shows it breaks Git filter behavior. -- Per-directory manifest selection requires path-aware filter invocation. - -## Unknowns - -- Whether `install-filter` should keep `required=true`. - - Review note: this is not decided yet. - - Current research implication: `required=true` is compatible with clone-safe behavior if smudge exits successfully only for the specific missing-local-key case. Disabling `required=true` globally would also let malformed blobs or other filter failures pass checkout more easily, so it needs explicit plan-level justification if chosen. -- Exact user-facing recovery command after importing or deriving the key for a clone that currently has encrypted pass-through bytes in the worktree. - - The issue is not key registration itself; it is making Git apply smudge again to files already materialized as encrypted bytes. - - Candidate commands belong in the plan/test phase, where they can be validated instead of guessed. -- Exact committed manifest schema. - - The research identifies the need for committed, non-secret key-id metadata, but schema choices belong in the plan. -- Migration/removal strategy for `.git/git-zcrypt/index.json`. - - Current commands write and read this local index. - - The plan must decide whether to delete this code path immediately, retain a compatibility fallback, or convert existing local index data into committed manifests. -- Exact installed filter command shape for passing target paths. - - The current command is insufficient for nearest-ancestor manifest lookup. - - The plan must verify the Git filter placeholder behavior locally before implementation. diff --git a/codex-notes/migrate-encrypted-manifest/feature_list.json b/codex-notes/migrate-encrypted-manifest/feature_list.json deleted file mode 100644 index 6a7f198..0000000 --- a/codex-notes/migrate-encrypted-manifest/feature_list.json +++ /dev/null @@ -1,93 +0,0 @@ -{ - "features": [ - { - "id": "parse-register", - "description": "Add a register [--manifest-dir ] ... CLI command to src/cli.rs and usage text.", - "validation": "cargo test cli::tests::parses_planned_subcommands -- --exact", - "passes": true, - "boundary": { - "files_dirs": [ - "src/cli.rs" - ], - "semantic_changes": "Add manifest-dir option and positional multi-file parsing.", - "capability": "Edit files; run parser test." - } - }, - { - "id": "lookup-local-key-alias", - "description": "Add a key-store API that finds the local alias matching an embedded sha256 key id and errors on duplicate aliases.", - "validation": "Validate through full cargo test and targeted integration coverage.", - "passes": true, - "boundary": { - "files_dirs": [ - "src/key_store.rs" - ], - "semantic_changes": "Find local alias matching an embedded sha256 key id.", - "capability": "Edit files; run Rust tests." - } - }, - { - "id": "register-command", - "description": "Implement register so files are cwd-relative, the manifest comes from --manifest-dir or cwd, and multiple encrypted files are supported.", - "validation": "cargo test --test filter_roundtrip register_updates_selected_manifest_without_rewriting_file -- --exact", - "passes": true, - "boundary": { - "files_dirs": [ - "src/main.rs", - "src/cli.rs", - "src/key_store.rs", - "src/key_manifest.rs", - "tests/filter_roundtrip.rs" - ], - "semantic_changes": "Register files into explicit or cwd manifest.", - "capability": "Edit files; run targeted Rust tests." - } - }, - { - "id": "register-missing-key-warning", - "description": "Add coverage proving register warns and creates the selected manifest file without adding a key entry when no matching local key exists.", - "validation": "cargo test --test filter_roundtrip register_warns_and_creates_manifest_without_matching_local_key -- --exact", - "passes": true, - "boundary": { - "files_dirs": [ - "tests/filter_roundtrip.rs", - "src/main.rs", - "src/key_store.rs", - "src/key_manifest.rs" - ], - "semantic_changes": "Warn and create selected manifest without entry.", - "capability": "Edit files; run targeted Rust tests." - } - }, - { - "id": "document-register", - "description": "Document register migration behavior in README.md and docs/data-formats.md.", - "validation": "rg -q \"git-zcrypt register\" README.md docs/data-formats.md", - "passes": true, - "boundary": { - "files_dirs": [ - "README.md", - "docs/data-formats.md" - ], - "semantic_changes": "Document paths, override, and multi-file usage.", - "capability": "Edit files; run rg doc check." - } - }, - { - "id": "full-validation", - "description": "Run formatting, the full test suite, release build, binary-size measurement, and applicable validators.", - "validation": "cargo fmt --check; cargo test; cargo build --release; ruby -e 'puts File.size(%q[target/release/git-zcrypt])'", - "passes": true, - "boundary": { - "files_dirs": [ - "src", - "tests", - "README.md", - "docs" - ], - "semantic_changes": "Run validation and update passes incrementally.", - "capability": "Run fmt, tests, build, size, rg, and validator discovery." - } - } - ] -} diff --git a/codex-notes/migrate-encrypted-manifest/plan.md b/codex-notes/migrate-encrypted-manifest/plan.md deleted file mode 100644 index e4d1813..0000000 --- a/codex-notes/migrate-encrypted-manifest/plan.md +++ /dev/null @@ -1,269 +0,0 @@ -# Plan: migrate encrypted file key ids into manifests - -## Overview - -Add a migration CLI command named `register`: -```sh -git-zcrypt register [--manifest-dir ] ... -``` - -Each `` is a current-directory-relative worktree file path, matching shell completion. The selected manifest directory is chosen in this order: explicit `--manifest-dir `, then the current directory. `--manifest-dir ` is current-directory-relative for interactive shell-completion workflows. The command resolves each file and selected manifest directory, verifies all paths stay inside the worktree, converts files to repository-relative filter paths for manifest entries, and reads encrypted bytes from the resolved worktree files. The selected manifest directory must be an ancestor of every registered file so smudge can find the manifest later. When a matching local key alias exists, it writes that mapping to the selected `git-zcrypt-keys.json`; when no matching local key exists, it warns and creates the selected manifest file without adding an entry. It will not decrypt, re-encrypt, or rewrite encrypted files. - -Example: if the current directory is `repo/a/b`, the encrypted file is `repo/a/b/c.secret`, and the desired manifest is `repo/a/git-zcrypt-keys.json`, run: - -```sh -cd .. -git-zcrypt init-manifest -git-zcrypt register b/c.secret -``` - -The command uses the shell-completed path from `repo/a`, creates/updates `repo/a/git-zcrypt-keys.json`, and records the repository-relative file path `a/b/c.secret`. - -To run from `repo/a/b` while still creating `repo/a/git-zcrypt-keys.json`, use the manifest override: - -```sh -git-zcrypt register --manifest-dir .. c.secret -``` - -Multiple files can be registered in one invocation: - -```sh -git-zcrypt register b/c.secret b/d.secret other/e.secret -``` - -The command processes files in argument order and writes all entries to the selected manifest. Missing local keys are warnings per file; malformed blobs, paths outside the worktree, a manifest directory that is not an ancestor of every file, manifest conflicts, and unreadable files are errors. - -This directly supports migrating existing encrypted repositories to the new committed manifest model introduced by the clone-smudge fix. - -## Files to change - -- `src/cli.rs` - - Add `Command::Register { manifest_dir: Option, paths: Vec }`. - - Parse `register [--manifest-dir ] ...` as an optional manifest directory plus one or more positional paths. - - Add the command to usage text and parser tests. - - -- `src/key_store.rs` - - Add an API that returns the matching local alias for a key id, likely `key_name_for_id(&self, key_id: &str) -> Result>`. - - Validate the requested key id. - - Search sorted local key names for deterministic behavior. - - Error if more than one alias maps to the same key id, because the manifest stores exactly one alias per key id and silent choice would hide a broken local key store. - -- `src/key_manifest.rs` - - Add helper to resolve cwd-relative worktree file paths to repository-relative filter paths and absolute worktree file paths. - - Add helper to resolve the selected cwd-relative manifest directory, validate that it is an ancestor of each registered file, and create/read that manifest without inserting a key entry. - -- `src/main.rs` - - Dispatch `Command::Register`. - - Implement `register(manifest_dir: Option<&Path>, paths: &[PathBuf])`: - - Discover the local key store. - - Select the manifest directory from explicit `--manifest-dir` or current directory. - - For each cwd-relative input path, resolve the absolute worktree file path and repository-relative filter path. - - Ensure the selected manifest directory is an ancestor of each resolved file path. - - Read file bytes from the resolved worktree file path and decode the encrypted blob with `blob::decode`. - - Find the matching local key alias through the new key-store API. - - If a matching key exists, add the key id/name entry to the selected manifest for `repo_relative_path`. - - If no matching key exists, emit a warning, ensure the selected manifest file exists, and do not add an entry. - -- `tests/filter_roundtrip.rs` - - Add an integration test proving the migration command updates the selected manifest for an existing encrypted file without rewriting the file. - - Add a missing-key warning test verifying manifest creation without a key entry. - -- `README.md` - - Document the migration command in the setup/key section. - - Explain that it works on encrypted worktree files and updates only the manifest. - -- `docs/data-formats.md` - - Mention that manifest entries for legacy encrypted blobs can be populated from the embedded blob key id when the local matching key is available. - -## Detailed implementation steps - -1. Update CLI parsing in `src/cli.rs`. - - Add the enum variant: - - ```rust - Register { manifest_dir: Option, paths: Vec }, - ``` - - Add parser branch: - - ```rust - "register" => { - let (manifest_dir, paths) = parse_register("register", &mut args)?; - Command::Register { manifest_dir, paths } - }, - ``` - - Add usage line: - - ```text - git-zcrypt register [--manifest-dir ] ... - ``` - - Extend `parses_planned_subcommands` with `register`. - -2. Add local key alias lookup in `src/key_store.rs`. - - Proposed behavior: - - ```rust - pub fn key_name_for_id(&self, key_id: &str) -> Result> { - validate_key_id(key_id)?; - let mut found = None; - for name in self.key_names()? { - let key = self.read_key(&name)?; - if key_id_for_key_bytes(&key)? == key_id { - ensure!(found.is_none(), "multiple local keys match {key_id}"); - found = Some(name); - } - } - Ok(found) - } - ``` - - Keep unreadable key files fatal for this command path. That matches `try_read_key_by_id`, avoids silently missing a matching key, and prevents writing incomplete migration state from a partially broken local key store. - -3. Implement command dispatch in `src/main.rs`. - - Proposed flow: - - ```rust - Command::Register { manifest_dir, paths } => register(manifest_dir.as_deref(), &paths), - ``` - - Proposed function behavior: - - ```rust - fn register(manifest_dir: Option<&Path>, paths: &[PathBuf]) -> Result<()> { - let store = key_store::KeyStore::discover()?; - let manifest = key_manifest::resolve_selected_manifest_dir(manifest_dir)?; - for path in paths { - let resolved = key_manifest::resolve_worktree_file(path)?; - key_manifest::ensure_manifest_covers_path(&manifest, &resolved.repo_path)?; - let input = std::fs::read(&resolved.worktree_path).with_context(|| { - format!("failed to read encrypted file {}", resolved.worktree_path.display()) - })?; - let encrypted = blob::decode(&input).with_context(|| { - format!("failed to decode encrypted file {}", resolved.input_path.display()) - })?; - if let Some(key_name) = store.key_name_for_id(&encrypted.key_id)? { - key_manifest::add_key_to_manifest(&manifest.path, &encrypted.key_id, &key_name)?; - } else { - eprintln!( - "warning: no local key is registered for {}; leaving manifest entry absent for {}", - encrypted.key_id, - resolved.repo_path.display() - ); - key_manifest::ensure_manifest(&manifest.path)?; - } - } - Ok(()) - } - ``` - -4. Add integration tests. - - Primary success test: - - - Create repo and local `default` key. - - Use `clean --key default --path secrets/team-a/secret.txt` to produce encrypted bytes in memory. - - Write those encrypted bytes to `secrets/team-a/secret.txt` directly. - - Create `secrets/git-zcrypt-keys.json` as the selected manifest boundary. - - Run `git-zcrypt register team-a/secret.txt` from the `secrets` directory. - - Assert `secrets/git-zcrypt-keys.json` contains the encrypted blob key id and `default`. - - Assert root `git-zcrypt-keys.json` is absent if it was not initialized for the test. - - Assert file bytes are unchanged after running the command. - - Assert the command resolves cwd-relative input to the intended repository-relative manifest path. - - Run `git-zcrypt register --manifest-dir .. secret.txt` from a nested directory and assert it writes to the parent manifest. - - Run `git-zcrypt register a.secret b.secret` and assert both entries are attempted in one invocation. - - Missing-key warning test: - - - Create repo and local `default` key. - - Produce encrypted bytes with `clean`. - - Delete the local key. - - Write encrypted bytes to a file. - - Run `register ` from a subdirectory. - - Assert command succeeds and warns with `no local key is registered`. - - Assert the selected manifest file exists and does not contain the missing key id. - - Parser test: - - - Include `git-zcrypt register secrets/a.txt`, `git-zcrypt register secrets/a.txt secrets/b.txt`, and `git-zcrypt register --manifest-dir secrets secrets/a.txt` in `parses_planned_subcommands`. - -5. Update docs. - - README wording: - - - Add a short migration paragraph near the manifest/smudge docs. - - State that `register` expects one or more cwd-relative encrypted file paths. - - Document the default current-directory manifest and `--manifest-dir ` override. - - State the precedence: command-line override, current directory. - - State it adds a manifest entry only when a matching local key exists; otherwise it creates the selected manifest file and warns. - - Data-format docs: - - - Add one sentence under committed key manifests that existing encrypted blobs carry enough key-id metadata to populate manifests, but the local key alias must be known by matching a local key. - -6. Validate. - - Run: - - ```sh - cargo fmt --check - cargo test --test filter_roundtrip register -- --exact - cargo test - cargo build --release - ruby -e 'puts File.size("target/release/git-zcrypt")' - ``` - - Also check for applicable validators under `.codex/agents/` and `~/.codex/agents/` after implementation. - -## Alternatives considered - -- `register-key --path ` - - Rejected because it sounds like it registers a key object, not a file's embedded key id. - -- `migrate-file --path ` - - Reasonable, but less explicit about the durable side effect. `register` describes adding the encrypted file to the manifest model. - -- `add-manifest-entry --path ` - - Accurate but awkward and too tied to implementation detail. - -- Require `--key ` as well as `--path ` - - Rejected for this migration case because the command can discover the alias from local key material. Requiring `--key` would make the command less useful and would duplicate the risk of a user choosing an alias whose key id does not match the blob. - -- Read encrypted bytes from stdin plus an explicit manifest path. - - Deferred. It is useful for advanced workflows such as `git cat-file`, but the stated need is a command that takes an encrypted file. A file-path-only command is simpler and less ambiguous. - -- Always use the existing upward-search manifest and fail if none exists. - - Rejected because manual migration should create/update the manifest selected by current directory or `--manifest-dir`, which matches shell-completion workflows better. - -## Risks - -- If the worktree path contains plaintext rather than encrypted blob bytes, `register` will fail with a decode error. This is expected, but docs should be explicit. -- Local key aliases are local names. The command can record only the alias present in this clone; another clone may use a different alias for the same key unless users standardize names. -- Manually duplicated local key files could create multiple aliases for one key id. The plan treats this as an error to avoid nondeterministic manifest output. -- A selected manifest directory that is not an ancestor of every registered file would produce a manifest smudge cannot find. The command rejects that case. -- The command decodes only the blob envelope and does not verify decryption. Matching key id proves the local key material has the expected SHA-256 hash, but the file could still have corrupted ciphertext. That is acceptable because the command's job is manifest migration, not content verification. - -## Test strategy - -- Unit/parser coverage in `src/cli.rs` for the new subcommand. -- Integration success coverage in `tests/filter_roundtrip.rs` for selected-manifest update and byte preservation. -- Integration coverage for missing matching local key: warning, manifest file creation, and no key entry. -- Existing full suite should continue covering clean/smudge/key-store behavior. -- Release build and binary-size measurement because this changes CLI and command logic. - -## Assumptions - -- This is approved to remain in the existing `codex/fix-clone-smudge` PR because it is migration support for the same committed-manifest clone-smudge feature. -- `register` arguments are cwd-relative worktree paths for shell completion; implementation converts them to repository-relative filter paths for manifest entries. -- Advanced stdin/input-path support is out of scope for the first PR; this stays file-path-only, with one or more positional file arguments and an optional `--manifest-dir ` manifest selector. -- If no matching local key exists, the migration command should warn, ensure the manifest file exists, and leave the key entry absent so users can add matching keys later and rerun registration. -- Without `--manifest-dir`, the selected manifest directory is the current directory. With `--manifest-dir `, the selected manifest directory is that cwd-relative directory. - -## Open questions - -- None. diff --git a/codex-notes/migrate-encrypted-manifest/research.md b/codex-notes/migrate-encrypted-manifest/research.md deleted file mode 100644 index c40d2a2..0000000 --- a/codex-notes/migrate-encrypted-manifest/research.md +++ /dev/null @@ -1,141 +0,0 @@ -# Research: migrate encrypted file key ids into manifests - -## Request - -The migration need is a command that takes an already-encrypted file and adds an entry to the nearest `git-zcrypt-keys.json` whenever the corresponding local key is found. - -This is related to the Issue #8 manifest work already in the `codex/fix-clone-smudge` branch: smudge now requires a committed manifest, but existing repositories may already contain encrypted blobs without matching manifest entries. - -## Relevant files and modules - -- `src/cli.rs` - - Defines the handwritten CLI parser and the `Command` enum. - - Current manifest-related command is `init-manifest [--path ]`. - - Filter commands are `clean --key --path ` and `smudge --path `. - - `parse_key_and_path` supports commands that require both `--key` and a path option. - - `parse_required_path` supports commands that require only a path option. - - Usage text must be updated for any new command. - -- `src/main.rs` - - Dispatches parsed commands. - - `clean()` reads stdin, encrypts with a named local key, calls `key_manifest::add_key_for_path(path, key_id, key_name)`, and writes encrypted bytes. - - `smudge()` reads stdin, decodes the blob, checks the nearest manifest with `key_manifest::key_allowed_for_path`, then decrypts if local key material exists. - - There is currently no command that reads an encrypted file from disk, extracts its embedded key id, finds the matching local key alias, and updates a manifest without changing the file bytes. - -- `src/blob.rs` - - `decode(input: &[u8]) -> Result` validates the encrypted blob envelope and extracts `Blob { key_id, nonce, ciphertext }`. - - The key id is embedded in the blob header. No decryption is needed to learn it. - - Decode validates magic, version, nonce length, reserved byte, UTF-8 key id, and non-empty key id. - -- `src/key_store.rs` - - Local keys live under `.git/git-zcrypt/keys/*.key`. - - `key_names()` returns sorted local key aliases. - - `read_key(name)` reads one key file. - - `read_key_with_id(name)` returns the key material plus computed `sha256:` key id. - - `try_read_key_by_id(key_id)` only returns key material, not the matching alias name. - - `indexed_keys()` returns `Vec { name, key_id }` and warnings for unreadable key files; this is the existing API that exposes alias names with computed key ids. - -- `src/key_manifest.rs` - - `add_key_for_path(path, key_id, key_name)` validates the key id and key name, locates the nearest existing `git-zcrypt-keys.json` for `path`, or falls back to the repository root manifest if none exists, then inserts the mapping. - - Existing conflict behavior: if the manifest already maps that key id to the same key name, it is a no-op; if it maps the key id to a different key name, it errors. - - Existing nearest-manifest behavior is based on `target_dir(root, path)`, where `path` must be repository-relative and must not contain `..`, root, or platform prefix components. - - `init_manifest(path)` creates a manifest directory and empty manifest. - -- `tests/filter_roundtrip.rs` - - Existing integration helpers can run the compiled `git-zcrypt` binary against temp Git repositories. - - Existing tests cover clean writing a committed manifest, smudge behavior with/without local keys, and nearest-manifest semantics indirectly through path handling. - - A migration command test can reuse `filter()` for stdin-based commands, but a command that reads a file path should probably use `Command::new(git_zcrypt())` directly. - -- `README.md` and `docs/data-formats.md` - - README explains setup, manifest behavior, clone-without-key behavior, and re-smudge after importing/deriving a key. - - Data format docs describe encrypted blob headers and manifest lookup rules. - - A migration command would need user-facing documentation because it exists specifically for repositories migrating to committed manifests. - -## Current execution flow - -### New encrypted content - -1. Git invokes the clean filter configured by `install-filter`. -2. `clean --key --path ` reads plaintext from stdin. -3. `KeyStore::discover()` finds `.git/git-zcrypt`. -4. `read_key_with_id(alias)` reads local key material and computes its `sha256:` key id. -5. Content is compressed and encrypted. -6. `key_manifest::add_key_for_path(path, encrypted.key_id, alias)` updates the nearest manifest or creates a root manifest. -7. The encrypted blob is written to stdout. - -### Checkout / clone smudge - -1. Git invokes `smudge --path ` with encrypted bytes on stdin. -2. `blob::decode()` extracts the embedded key id. -3. `key_manifest::key_allowed_for_path(path, key_id)` requires the nearest manifest to contain that key id. -4. If local key material is missing, smudge writes the original encrypted bytes and succeeds with a warning. -5. If local key material exists, smudge decrypts and decompresses. - -### Existing encrypted content without manifest entry - -Observed gap: - -1. The encrypted file already contains its key id in the blob header. -2. The local clone may have a key whose computed id matches the blob key id. -3. The repository may lack a manifest entry for the file path. -4. Existing `clean` can add a manifest entry only by re-cleaning plaintext with an explicitly named key, which changes ciphertext because nonces are random and requires plaintext recovery. -5. Existing `smudge` cannot be used to add a manifest entry; it validates the manifest before decrypting. - -## Data structures and invariants - -- Encrypted blob key ids are embedded as UTF-8 strings and should validate as current key ids (`sha256:` plus 64 lowercase hex chars) before being written to a manifest. -- Manifest entries map key id to local alias name, not to raw key material. -- Manifest files are committed and contain no raw key material. -- Local key aliases are clone-local names and must pass `validate_key_name`. -- The nearest manifest rule matters for subdirectory boundaries: updating the root manifest when a closer manifest exists would make smudge still reject files below that closer boundary. -- If no manifest exists for a path, existing `add_key_for_path` falls back to `root/git-zcrypt-keys.json`. -- Filter paths are expected to be repository-relative and cannot escape the worktree. - -## Existing architectural patterns - -- CLI parsing is manual, option names are long-form, and errors include command-specific prefixes. -- Command implementations live in `main.rs` as small functions that compose module APIs. -- File/path validation is centralized in the module that owns the behavior (`key_manifest` for manifest paths; `key_store` for key names and key ids). -- Errors use the local `Result`, `ensure!`, `bail!`, and context helpers. -- Tests are a mix of unit tests for pure parsing/format behavior and integration tests that run the compiled binary against temp Git repositories. - -## Naming conventions - -- Commands use hyphenated names: `init-manifest`, `generate-key`, `install-filter`. -- Options use explicit long names such as `--key`, `--path`, `--input`, `--output`. -- Existing path-bearing filter commands use `--path` for repository-relative filtered paths. -- Existing file-input commands use `--input` for key import; encrypted-file migration could reasonably need either a repository path option or a file input option, but the nearest-manifest requirement means the repository-relative target path is semantically required. - -## Error handling patterns - -- Missing required options return `: missing --option`. -- Unexpected options return `: unexpected option ...`. -- Invalid paths fail before filesystem mutation. -- Manifest conflicts preserve existing entries and return an error instead of overwriting. -- Local unreadable keys can be warnings in `status`, but command-specific behavior must decide whether unreadable keys should be fatal or simply ignored while searching for a matching key. - -## Potential pitfalls - -- A command that reads encrypted bytes from stdin without a path cannot know which nearest manifest to update unless it also takes `--path`. -- A command that takes a filesystem path must distinguish between the repository-relative path used for manifest lookup and the disk path used to read bytes. For normal migration these are probably the same path. -- If the worktree file is currently smudged plaintext rather than the encrypted Git blob, `blob::decode()` will fail. Migration may need users to operate on encrypted bytes from the index/HEAD or on a checked-out encrypted file left by missing-key smudge. -- If multiple local aliases somehow map to the same key material, `indexed_keys()` would return multiple names with the same key id. Existing key creation rejects duplicate key material, but legacy/manual file copies could still create this state. -- If no matching local key exists, the command should not add a manifest entry because it cannot know the local alias name to record. -- If a closer subdirectory manifest exists, updating only the root manifest is insufficient for smudge. -- Existing `add_key_for_path` can create a root manifest automatically when no manifest exists. That may or may not be desirable for a migration command, depending on whether the command should require users to initialize boundaries first. - -## Constraints - -- Keep this in the existing Issue #8 PR only if treated as part of the same clone-smudge manifest migration feature; otherwise it should be split by workflow guardrails. -- Avoid introducing new dependencies for this CLI addition. -- Preserve committed encrypted file bytes; the migration command should only update manifest JSON. -- Preserve current manifest conflict checks. -- Use existing JSON formatting/parsing so manifest output remains stable. - -## Unknowns - -- Command name is not yet chosen. Candidates should be evaluated in the plan, but no code should be written before approval. -- Exact CLI shape is open: one path option may be enough if the encrypted file path is repo-relative, but separate `--input` and `--path` may be useful for reading encrypted bytes from elsewhere while updating the manifest for a repository path. -- Behavior when no matching local key is found needs confirmation: likely a clear error and no manifest mutation. -- Behavior when multiple local aliases match the embedded key id needs confirmation: likely an ambiguity error unless existing invariants make it impossible enough to choose the first sorted alias. -- Behavior when no manifest exists needs confirmation: reuse current root fallback or require an existing manifest boundary.