Skip to content

feat(durable): add zeph durable rotate-key for AEAD payload key rotation#6452

Merged
bug-ops merged 1 commit into
mainfrom
feat/issue-6447/durable-hwm-key-rotation
Jul 18, 2026
Merged

feat(durable): add zeph durable rotate-key for AEAD payload key rotation#6452
bug-ops merged 1 commit into
mainfrom
feat/issue-6447/durable-hwm-key-rotation

Conversation

@bug-ops

@bug-ops bug-ops commented Jul 18, 2026

Copy link
Copy Markdown
Owner

Summary

Closes #6447

Test plan

  • cargo +nightly fmt --check
  • cargo clippy --profile ci --workspace --all-targets --features "desktop,ide,server,chat,pdf,scheduler,testing" -- -D warnings
  • cargo nextest run --config-file .github/nextest.toml --workspace --features "desktop,ide,server,chat,pdf,scheduler" --lib --bins (14418 passed, 35 skipped)
  • RUSTFLAGS="-D warnings" RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc --no-deps --workspace --features "desktop,ide,server,chat,pdf,scheduler"
  • gitleaks protect --staged --no-banner --redact
  • 15 new tests in src/commands/durable.rs (guard sequence, fail-closed branch at the bootstrap layer, round-trip through the real CLI+backend, R5 error-mapping end-to-end) + unit/doc-test coverage across zeph-config, zeph-core, zeph-durable
  • Independent security audit (0 critical/high/medium) and performance review (clean, non-hot-path) — see PR discussion for handoff references
  • .local/testing/playbooks/durable-key-rotation.md and .local/testing/coverage-status.md updated
  • Live CLI smoke test against a real vault+config (recommended as the next CI cycle's live-session scenario — see playbook Scenario 4)

Issue #6447 originally described an operational-tooling gap for a
high-water-mark key-rotation primitive credited to #6360. That primitive
does not exist in the codebase and #6360 is an unimplemented, open
research issue, so this PR rescopes #6447 to the real analogous gap:
XChaCha20Poly1305Cipher::with_previous existed but was never wired to
an operator-facing surface.

Adds zeph durable rotate-key to open and close a rotation window for
the durable execution layer's AEAD payload key (ZEPH_DURABLE_KEY).
[durable] gains key_id (operator-controlled current-key selector) and
previous_key_id (rotation-window state), both config-driven so rotation
no longer requires a recompile. load_durable_cipher, the single
chokepoint shared by the agent write path, scheduler-daemon write
path, and CLI/--reveal read path, builds the cipher from both fields
and hard-errors if previous_key_id is set but the vault secret is
missing.

Design went through two adversarial critique rounds before
implementation: the first caught that vault-first write ordering
(originally proposed) leaves a crash window that silently mis-decrypts
every pre-rotation payload, and that a second rotation while a window
is open would silently orphan the first previous key's blobs given the
cipher's single previous-key slot. The shipped design writes
config-first then vault, refuses a second rotation while one is open,
enforces a shared-DB acknowledgment gate (rotating also re-derives the
control-entry HMAC key, which has no rotation window of its own), and
defaults --drop-previous to a blob-scan verification before discarding
the previous key. A post-implementation critique and independent
tester pass both found the same coverage gap (the fail-closed branch
was untested at the layer every normal process bootstrap actually
calls through, not just the CLI's own guard) and it was closed with a
follow-up round of tests before this went to review.

zeph --init's existing key-replacement wizard step is unchanged in
behavior but now labels itself as a destructive reset with no rotation
window, pointing operators to rotate-key for the safe alternative.

HMAC rotation windows on shared databases and a TUI passive rotation
indicator are explicitly out of scope and filed as follow-ups (#6450,
#6451).

Closes #6447
@github-actions github-actions Bot added documentation Improvements or additions to documentation rust Rust code changes core zeph-core crate enhancement New feature or request size/XL Extra large PR (500+ lines) labels Jul 18, 2026
@bug-ops
bug-ops merged commit e5c832a into main Jul 18, 2026
47 checks passed
@bug-ops
bug-ops deleted the feat/issue-6447/durable-hwm-key-rotation branch July 18, 2026 12:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core zeph-core crate documentation Improvements or additions to documentation enhancement New feature or request rust Rust code changes size/XL Extra large PR (500+ lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

wire durable high-water-mark key rotation (with_previous_hwm_key) into --init/a CLI command

1 participant