---
phase: 12-user-key-input
plan: 01
subsystem: crypto
tags: [clap, hex, aes-256, key-management, cli]

# Dependency graph
requires:
  - phase: 08-rust-directory-archiver
    provides: "pack/unpack/inspect with hardcoded key"
provides:
  - "CLI --key (hex) and --key-file (raw) key input for pack/unpack"
  - "inspect works without key (header only) or with key (full TOC listing)"
  - "KeySource enum and resolve_key() in key.rs"
  - "All archive functions parameterized by user-provided key"
affects: [12-02-PLAN, kotlin-decoder]

# Tech tracking
tech-stack:
  added: [hex 0.4]
  patterns: [key-parameterized archive API, clap arg group for mutually exclusive key sources]

key-files:
  created: []
  modified:
    - Cargo.toml
    - src/cli.rs
    - src/key.rs
    - src/archive.rs
    - src/main.rs
    - src/crypto.rs
    - tests/round_trip.rs
    - tests/golden.rs

key-decisions:
  - "KeyArgs as top-level clap flatten (not per-subcommand) so --key goes before subcommand"
  - "inspect accepts optional key: without key shows header only, with key shows full TOC"
  - "LEGACY_KEY kept as #[cfg(test)] constant for golden vectors"
  - "Password option uses Option<Option<String>> for future interactive prompt support"

patterns-established:
  - "Key threading: all archive functions accept explicit key parameter instead of global state"
  - "cmd_with_key() test helper for CLI integration tests"

requirements-completed: [KEY-01, KEY-02, KEY-07]

# Metrics
duration: 5min
completed: 2026-02-26
---

# Phase 12 Plan 01: User Key Input Summary

**CLI key input via --key (hex) and --key-file (raw bytes), replacing hardcoded constant, with inspect working keyless for header metadata**

## Performance

- **Duration:** 5 min
- **Started:** 2026-02-26T20:47:52Z
- **Completed:** 2026-02-26T20:53:36Z
- **Tasks:** 2
- **Files modified:** 8

## Accomplishments
- Removed hardcoded KEY constant from production code; all archive functions now parameterized by key
- Added --key (64-char hex) and --key-file (32-byte raw file) as mutually exclusive CLI args
- inspect works without a key (shows header metadata + "TOC is encrypted" message) and with a key (full entry listing)
- All 47 tests pass: 25 unit + 7 golden + 15 integration (6 new tests added)

## Task Commits

Each task was committed atomically:

1. **Task 1: Add CLI key args and refactor key.rs + archive.rs signatures** - `acff31b` (feat)
2. **Task 2: Update tests and verify round-trip with explicit key** - `551e499` (test)

## Files Created/Modified
- `Cargo.toml` - Added hex 0.4 dependency
- `src/cli.rs` - Added KeyArgs struct with --key, --key-file, --password as clap arg group
- `src/key.rs` - Replaced hardcoded KEY with KeySource enum and resolve_key() function
- `src/archive.rs` - Refactored pack/unpack/inspect to accept key parameter
- `src/main.rs` - Wired CLI key args to key resolution and archive functions
- `src/crypto.rs` - Updated tests to use local TEST_KEY constant
- `tests/golden.rs` - Updated to use local KEY constant instead of imported
- `tests/round_trip.rs` - All tests updated with --key, 6 new tests added

## Decisions Made
- KeyArgs placed at top-level Cli struct (not per-subcommand) so --key goes BEFORE the subcommand name
- inspect accepts optional key: without key shows only header fields, with key decrypts and shows full TOC
- LEGACY_KEY kept as #[cfg(test)] constant in key.rs for golden test vector compatibility
- Password field uses `Option<Option<String>>` to support both `--password mypass` and `--password` (future interactive prompt)

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Fixed wrong-key test assertion**
- **Found during:** Task 2 (test_rejects_wrong_key)
- **Issue:** Wrong key causes TOC decryption failure ("invalid padding or wrong key") before HMAC check on individual files. The test expected "HMAC" or "verification" in stderr.
- **Fix:** Broadened assertion to also accept "Decryption failed" or "wrong key" in error message
- **Files modified:** tests/round_trip.rs
- **Verification:** Test passes with actual error behavior
- **Committed in:** 551e499 (Task 2 commit)

---

**Total deviations:** 1 auto-fixed (1 bug fix in test)
**Impact on plan:** Trivial test assertion fix. No scope creep.

## Issues Encountered
None

## User Setup Required
None - no external service configuration required.

## Next Phase Readiness
- Key input foundation complete for Plan 02 (Argon2 password-based key derivation)
- --password CLI arg already accepted (returns "not yet implemented" error)
- KeySource::Password variant ready for Plan 02 implementation

## Self-Check: PASSED

All 9 files verified present. Both task commits (acff31b, 551e499) found in git log.

---
*Phase: 12-user-key-input*
*Completed: 2026-02-26*