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

- [ ] **Missing Cobra usage printing after errors**: Commands should print usage information when they fail due to incorrect arguments or usage. Need to configure `SilenceUsage: false` and `SilenceErrors: false` on cobra commands.

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

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

- [ ] **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

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

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

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

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

### Security Issues

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

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

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

## Important (Should be fixed before release)

### User Interface Improvements

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

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

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

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

### Command Implementation Gaps

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

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

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

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

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

### Configuration and Environment

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

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

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

### PGP Integration Issues

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

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

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

### Cross-Platform Issues

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

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

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

## Trivial (Nice to have)

### Code Quality

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

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

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

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

### Performance Optimizations

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

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

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

### User Experience Enhancements

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

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

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

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

### Additional Features

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

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

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

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

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

### Documentation

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

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

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

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

## Architecture Improvements

### Code Structure

- [ ] **Consistent interface implementation**: Ensure all unlock key types properly implement the UnlockKey interface.

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

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

### Testing Infrastructure

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

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

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

## Technical Debt

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

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

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

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

## Development Workflow

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

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

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

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

---

## Priority Assessment

**Critical items** block the 1.0 release and must be fixed for basic functionality and security.

**Important items** should be addressed for a polished user experience but don't block the release.

**Trivial items** are enhancements that can be addressed in future releases.

## Estimated Timeline

- Critical: 2-3 weeks
- Important: 3-4 weeks  
- Trivial: Ongoing post-1.0

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