docs: define env key rotation, recovery, and lost-key handling flows - #28
docs: define env key rotation, recovery, and lost-key handling flows#28roodboi wants to merge 2 commits into
Conversation
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c345c9fb0e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | Situation | Correct action | Why | | ||
| | --- | --- | --- | | ||
| | The underlying secret changed | Value rotation | The trust anchor can stay the same while publishing a new immutable value snapshot | | ||
| | A teammate left or a new teammate joined | Share rotation | Membership changed, but the current project key may still be trusted | |
There was a problem hiding this comment.
In the offboarding case where a teammate has already applied the current bundle, Share rotation is not a sufficient “correct action”: the sharing rules in docs/plans/2026-03-13-env-portability-and-secret-management-design.md:246-249 explicitly say revocation only blocks fresh unwraps and does not remove old local materializations. As written, this matrix will push the CLI/broker toward a flow that leaves the departed user with still-valid DB/API credentials until operators also rotate the affected secret values.
Useful? React with 👍 / 👎.
|
|
||
| 1. rotate the project key | ||
| 2. re-wrap the latest active bundle keys to the new project key | ||
| 3. regenerate all active recipient and recovery shares |
There was a problem hiding this comment.
This compromise-handling flow rotates the project key and recreates shares, but it never reissues encrypted recovery packages. That breaks the case where a recovery package is the only remaining recovery path, because the new section later ties packages to a specific project key identifier in docs/plans/2026-03-13-env-portability-and-secret-management-design.md:367-376; after rotation, the old package can no longer unwrap the new key even though the guardrails still count a package as valid recovery. The rotation flow needs to explicitly regenerate or invalidate recovery packages to avoid silently stranding the project.
Useful? React with 👍 / 👎.
| Expected flow: | ||
|
|
||
| 1. rotate the project key | ||
| 2. re-wrap the latest active bundle keys to the new project key |
There was a problem hiding this comment.
Re-wrapping only the “latest active bundle keys” is not enough for a compromised-project-key scenario, because the design elsewhere keeps bundle versions immutable and fetchable by version (docs/plans/2026-03-06-remote-encrypted-project-env-portability-plan.md:158-160). Any older bundle that remains wrapped by the superseded project key is still decryptable by the attacker, so compromise rotation would leave historical secret snapshots exposed and still applicable. This flow needs to cover all retained bundle versions or explicitly retire old history.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6add36f3d2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 1. authenticate as an authorized owner or designated recovery recipient | ||
| 2. unwrap the current project key through the remaining recovery path | ||
| 3. re-apply the latest active portable bundle to new local compatibility storage | ||
| 4. reissue recipient shares for replacement devices as needed |
There was a problem hiding this comment.
When the surviving authority is a designated recovery recipient, this Case 1 flow lets that backup-only identity complete step 4 and mint fresh recipient shares. That effectively promotes recovery holders into share administrators, even though manual sharing is described as the trust boundary earlier in this doc (docs/plans/2026-03-13-env-portability-and-secret-management-design.md:219-251). In a lost-laptop recovery, a designated recovery recipient could re-grant access to any user or device unless the reissue step is limited to owners/admins or requires explicit re-approval.
Useful? React with 👍 / 👎.
| 1. verify that the recipient is still entitled to access | ||
| 2. mint a fresh wrapped project-key share for that recipient | ||
| 3. preserve existing bundle versions and project-key lineage |
There was a problem hiding this comment.
Case 2 assumes we can "mint a fresh wrapped project-key share for that recipient", but the only key-share schema defined here records recipient.id plus wrapMethod/wrappedProjectKey and nothing about which public key or device the share targets (docs/plans/2026-03-13-env-portability-and-secret-management-design.md:223-240). In the normal lost-key scenario where the user creates a replacement keypair, the broker has no stable key identity to encrypt to or supersede, so this recovery flow cannot be implemented reliably without adding recipient key metadata.
Useful? React with 👍 / 👎.
1 participant
Motivation
Description
docs/env.mdthat documents value rotation, share rotation, project-key rotation, recovery rules, lost-key scenarios, and CLI/desktop UX expectations.docs/plans/2026-03-13-env-portability-and-secret-management-design.mdwith an operator decision matrix, detailed lost-key vs compromised-key handling flows, and minimum metadata requirements for encrypted recovery packages.docs/plans/2026-03-13-env-portability-and-secret-management-plan.mdto require tests and CLI/broker command work to distinguish lost-key recovery/share reissue from compromised-key rotation.T-YZP66GA9P5to track the implementation work (CLI/broker commands, storage, and tests) required to enforce the documented guardrails.Testing
bun x ultracite checkwhich completed but reported pre-existing repository complexity warnings unrelated to these documentation-only changes.Codex Task