secret/TODO.md

Workflow

• branch (from main)
• do the work in Next Step
• move Next Step to the top of Completed Steps
• move the top item of Future Steps into Next Step
• commit (TODO.md changes in the same commit as the work)
• merge to main if the branch is not protected, otherwise open a PR
• push

Status

pre-1.0. No git tags. TODO.md carries open 1.0 security blockers. Work in flight on branch secure-enclave-unlocker (clean tree as of 2026-07-06).

Next Step

Bring the repo into policy compliance in one commit:

• Add fmt-check and hooks targets to the Makefile (test/lint/fmt/check/ docker already exist).
• Add REPO_POLICIES.md and .editorconfig.
• Add .gitea/workflows/check.yml running make check.
• Verify Dockerfile base images are pinned by sha256.

Completed Steps

• 2026-08-07: Updated golangci-lint to v2.12.2 with the canonical .golangci.yml (all linters enabled minus the standard disable list, lll 88, tests linted); bumped the Dockerfile lint-stage image to the tagged v2.12.2 Debian digest; fixed all ~1550 new findings across internal/ and pkg/ (line wrapping, wsl_v5 blank lines, sentinel errors for err113, t.Parallel() where safe, _test package conversions, complexity/dupl helper extraction) on branch golangci-v2.12.2.
• 2026-07-07 Adopted scripts-to-rule-them-all: script/ entrypoints, Makefile shims, README Entrypoints section
• 2026-03-11: Secure Enclave unlocker for hardware-backed secret protection, plus review fixes (stub panics, derivation index, tests, README) on branch secure-enclave-unlocker.
• 2026-02-28: Repo cleanup, removed stale .cursorrules and coverage.out.
• Audit fix wave (issues #1, #2, #3, #13, #14): skip unlockers with missing metadata, allow uppercase secret names, fix hardcoded derivation index, validate names in GetSecretVersion against path traversal, return errors instead of panicking, add Warn() on silent anomalies.
• Memory security hardening: LockedBuffer used through encrypt/decrypt paths (Save/EncryptWithPassphrase/GetValue/gpg helpers), deprecated bare-[]byte APIs removed.
• Per-secret keypair architecture, vault package refactor, versioning with --version, comprehensive test suite with in-memory filesystem.
• Debug logging system (slog, GODEBUG flag, TTY-aware output).
• Renamed SEP unlocker to Keychain, reorganized import commands.
• 2025-05-28: Initial implementation (vault, age encryption, mnemonic, CLI).

Future Steps

• Compliance (after Next Step lands): keep main green under the new .gitea workflow; run make check before every merge.
• Implement version-number shell completion for the second arg of secret version promote and secret version rm (internal/cli/version.go; was an in-code TODO removed for godox).
• Cover mnemonic-vs-xprv identity consistency in pkg/agehd/agehd_test.go TestMnemonicVsXPRVConsistency (was an in-code FIXME removed for godox).
• Darwin-gated files (internal/secret/keychainunlocker.go, seunlocker_darwin.go, internal/macse/macse_darwin.go, related tests) are not linted on the Linux CI runner and still contain lines over the new 88-column limit; they will surface if lint ever runs on macOS.
• Merge secure-enclave-unlocker to main once review is done.
• 1.0 critical security blockers (from repo TODO.md):
  • Command injection: GPG key IDs passed unescaped to exec.Command (pgpunlocker.go:323-327); data.String() passed unescaped to the security command (keychainunlocker.go:472-476).
  • Memory security: KeychainData stores AgePrivKeyPassphrase as a plain string (keychainunlocker.go:342,393-396); age identity .String() creates unprotected copies (keychainunlocker.go:356, pgpunlocker.go:256, version.go:155); age secret key held in a plain string in cli/crypto.go:86,91,113; private keys exposed via buffer.Bytes() to GPGEncryptFunc and EncryptWithPassphrase.
  • Race conditions: no file locking in vault/secrets.go:142-176; non-atomic writes can leave the vault inconsistent.
  • Input validation: dots in secret names risk path traversal (vault/secrets.go:75-99); no maximum secret size (DoS).
  • Timing attacks: bytes.Equal passphrase compare (cli/init.go: 209-216); non-constant-time public key compare (vault.go:95-100).
• High priority:
  • Return errors instead of panicking on corrupted metadata (pgpunlocker.go:116, keychainunlocker.go:141).
  • Secure temporary file handling and cleanup.
  • Print cobra usage only for argument errors, not internal failures.
  • Initialize a default unlock key at vault creation.
  • Confirmation prompts for destructive operations (keys rm, vault deletion).
  • Add secret rm and vault deletion commands.
• Medium priority:
  • Standardize error messages; stop leaking internals.
  • Graceful handling of corrupted or missing key files with recovery suggestions.
  • Validate GPG key existence before creating PGP unlock keys.
  • Split oversized CLI functions.
  • Document env var security (SB_UNLOCK_PASSPHRASE, SB_SECRET_MNEMONIC); clear after use.
  • mlock/munlock for sensitive allocations.
• Cleanups: read statedir from environment or default instead of passing it around.
• Enhancements: help examples, shell completion, colored output, --quiet flag, name suggestions on miss, audit logging, hardware integration tests (Keychain, GPG), naming consistency, vault export/import, batch operations, search, secret metadata (descriptions, tags).