secret/TODO.md

# TODO for 1.0 Release

This document outlines the bugs, issues, and improvements that need to be addressed before the 1.0 release of the secret manager.

## Critical (Blockers for Release)

### Error Handling and User Experience

- [ ] **1. Inappropriate Cobra usage printing**: Commands currently print usage information for all errors, including internal program failures. Usage should only be printed when the user provides incorrect arguments or invalid commands, not when the program encounters internal errors (like file system issues, crypto failures, etc.).

- [ ] **2. Inconsistent error messages**: Error messages need standardization and should be user-friendly. Many errors currently expose internal implementation details.

- [x] **3. Missing validation for vault names**: Vault names should be validated against a safe character set to prevent filesystem issues.

- [ ] **4. No graceful handling of corrupted state**: If key files are corrupted or missing, the tool should provide clear error messages and recovery suggestions.

### Core Functionality Bugs

- [x] **5. Multiple vaults using the same mnemonic will derive the same long-term keys**: Adding additional vaults with the same mnemonic should increment the index value used. The mnemonic should be double sha256 hashed and the hash value stored in the vault metadata along with the index value (starting at zero) and when additional vaults are added with the same mnemonic (as determined by hash) then the index value should be incremented. The README should be updated to document this behavior.

- [x] **6. Directory structure inconsistency**: The README and test script reference different directory structures:
  - Current code uses `unlockers.d/` but documentation shows `unlock-keys.d/`
  - Secret files use inconsistent naming (`secret.age` vs `value.age`)

- [x] **7. Symlink handling on non-Unix systems**: The symlink resolution in `resolveVaultSymlink()` may fail on Windows or in certain environments.

- [ ] **8. Missing current unlock key initialization**: When creating vaults, no default unlock key is selected, which can cause operations to fail.

- [ ] **9. Race conditions in file operations**: Multiple concurrent operations could corrupt the vault state due to lack of file locking.

### Security Issues

- [ ] **10. Insecure temporary file handling**: Temporary files containing sensitive data may not be properly cleaned up or secured.

- [ ] **11. Missing secure memory clearing**: Sensitive data in memory (passphrases, keys) should be cleared after use.

- [x] **12. Weak default permissions**: Some files may be created with overly permissive default permissions.

## Important (Should be fixed before release)

### User Interface Improvements

- [ ] **13. Add confirmation prompts for destructive operations**: Operations like `keys rm` and vault deletion should require confirmation.

- [ ] **14. Improve progress indicators**: Long operations (key generation, encryption) should show progress.

- [x] **15. Better secret name validation**: Currently allows some characters that may cause issues, needs comprehensive validation.

- [ ] **16. Add `--help` examples**: Command help should include practical examples for each operation.

### Command Implementation Gaps

- [x] **17. `secret keys rm` not fully implemented**: Based on test output, this command may not be working correctly.

- [x] **18. `secret key select` not fully implemented**: Key selection functionality appears incomplete.

- [ ] **19. Missing vault deletion command**: No way to delete vaults that are no longer needed.

- [ ] **20. No secret deletion command**: Missing `secret rm <secret-name>` functionality.

- [ ] **21. Missing secret history/versioning**: No way to see previous versions of secrets or restore old values.

### Configuration and Environment

- [ ] **22. Global configuration not fully implemented**: The `configuration.json` file structure exists but isn't used consistently.

- [ ] **23. Missing environment variable validation**: Environment variables should be validated for format and security.

- [ ] **24. No configuration file validation**: JSON configuration files should be validated against schemas.

### PGP Integration Issues

- [x] **25. Incomplete PGP unlock key implementation**: The `--keyid` parameter processing may not be fully working.

- [ ] **26. Missing GPG agent integration**: Should detect and use existing GPG agent when available.

- [ ] **27. No validation of GPG key existence**: Should verify the specified GPG key exists before creating PGP unlock keys.

### Cross-Platform Issues

- [ ] **28. macOS Keychain error handling**: Better error messages when biometric authentication fails or isn't available.

- [ ] **29. Windows path handling**: File paths may not work correctly on Windows systems.

- [ ] **30. XDG compliance on Linux**: Should respect `XDG_CONFIG_HOME` and other XDG environment variables.

## Trivial (Nice to have)

### Code Quality

- [ ] **31. Add more comprehensive unit tests**: Current test coverage could be improved, especially for error conditions.

- [ ] **32. Reduce code duplication**: Several functions have similar patterns that could be refactored.

- [ ] **33. Improve function documentation**: Many functions lack proper Go documentation comments.

- [ ] **34. Add static analysis**: Integrate tools like `staticcheck`, `golangci-lint` with more linters.

### Performance Optimizations

- [ ] **35. Cache unlock key operations**: Avoid re-reading unlock key metadata on every operation.

- [ ] **36. Optimize file I/O**: Batch file operations where possible to reduce syscalls.

- [ ] **37. Add connection pooling for HSM operations**: For hardware security module operations.

### User Experience Enhancements

- [ ] **38. Add shell completion**: Bash/Zsh completion for commands and secret names.

- [ ] **39. Colored output**: Use colors to improve readability of lists and error messages.

- [ ] **40. Add `--quiet` flag**: Option to suppress non-essential output.

- [ ] **41. Smart secret name suggestions**: When a secret name is not found, suggest similar names.

### Additional Features

- [ ] **42. Secret templates**: Predefined templates for common secret types (database URLs, API keys, etc.).

- [ ] **43. Bulk operations**: Import/export multiple secrets at once.

- [ ] **44. Secret sharing**: Secure sharing of secrets between vaults or users.

- [ ] **45. Audit logging**: Log all secret access and modifications.

- [ ] **46. Integration tests for hardware features**: Automated testing of Keychain and GPG functionality.

### Documentation

- [ ] **47. Man pages**: Generate and install proper Unix man pages.

- [ ] **48. API documentation**: Document the internal API for potential library use.

- [ ] **49. Migration guide**: Document how to migrate from other secret managers.

- [ ] **50. Security audit documentation**: Document security assumptions and threat model.

## Architecture Improvements

### Code Structure

- [ ] **51. Consistent interface implementation**: Ensure all unlocker types properly implement the Unlocker interface.

- [ ] **52. Better separation of concerns**: Some functions in CLI do too much and should be split.

- [ ] **53. Improved error types**: Create specific error types instead of using generic `fmt.Errorf`.

### Testing Infrastructure

- [x] **54. Mock filesystem consistency**: Ensure mock filesystem behavior matches real filesystem in all cases.

- [x] **55. Integration test isolation**: Tests should not affect each other or the host system.

- [ ] **56. Performance benchmarks**: Add benchmarks for crypto operations and file I/O.

## Technical Debt

- [ ] **57. Remove unused code**: Clean up any dead code or unused imports.

- [ ] **58. Standardize JSON schemas**: Create proper JSON schemas for all configuration files.

- [ ] **59. Improve error propagation**: Many functions swallow important context in error messages.

- [ ] **60. Consistent naming conventions**: Some variables and functions use inconsistent naming.

## Development Workflow

- [ ] **61. Add pre-commit hooks**: Ensure code quality and formatting before commits.

- [ ] **62. Continuous integration**: Set up CI/CD pipeline with automated testing.

- [ ] **63. Release automation**: Automate the build and release process.

- [ ] **64. Dependency management**: Regular updates and security scanning of dependencies.

---

## Priority Assessment

**Critical items** (1-12) block the 1.0 release and must be fixed for basic functionality and security.

**Important items** (13-30) should be addressed for a polished user experience but don't block the release.

**Trivial items** (31-50) are enhancements that can be addressed in future releases.

**Architecture and Infrastructure** (51-64) are longer-term improvements for maintainability and development workflow.

## Estimated Timeline

- Critical (1-12): 2-3 weeks
- Important (13-30): 3-4 weeks  
- Trivial (31-50): Ongoing post-1.0
- Architecture/Infrastructure (51-64): Ongoing post-1.0

Total estimated time to 1.0: 5-7 weeks with focused development effort. 

### Architecture Issues
- **Need to refactor unlock key hierarchy**: Current implementation has confusion between the top-level concepts. Fix in progress.
- Current code uses `unlockers.d/` but documentation shows `unlock-keys.d/`
- Need to settle on consistent naming: "unlock keys" vs "unlockers" throughout the codebase

- [ ] **51. Consistent interface implementation**: Ensure all unlocker types properly implement the Unlocker interface.