docs: define env key rotation, recovery, and lost-key handling flows

docs/env.md

@@ -41,6 +41,8 @@ Planned direction:
 - Portable env values will live in an immutable encrypted bundle artifact.
 - Bundle access will be controlled through explicit project-key sharing.
 - Applying a bundle will still write values back into `.hack/.env` and the configured local secret backend so existing runtime behavior stays intact.
+- Key lifecycle operations will stay split into value rotation, share rotation, and project-key rotation so operators can change trust without accidentally rewriting secrets.
+- Portable env projects will need an explicit recovery path before the last owner or recovery share can be removed.
 
 See `docs/plans/2026-03-13-env-portability-and-secret-management-design.md` for the full portable env and key-sharing model.
 
@@ -166,6 +168,111 @@ This behavior is design intent for the managed artifact workflow; it is not full
 
 See [docs/plans/2026-03-13-portable-project-env-artifact-schema-design.md](plans/2026-03-13-portable-project-env-artifact-schema-design.md) for the full design rationale and implementation boundary.
 
+## Planned portable key lifecycle flows
+
+Portable env management needs distinct operator flows because the actor intent is different in each case:
+
+| Operator goal | Planned flow | Expected crypto effect | Expected operator impact |
+| --- | --- | --- | --- |
+| Change one or more env values | Value rotation | New immutable bundle version and new bundle key | Recipients keep the same project key access unless the operator also changes sharing |
+| Add or remove recipients | Share rotation | Update wrapped project-key shares only | Existing bundle contents stay unchanged |
+| Recover from suspected key compromise or re-anchor trust | Project-key rotation | Mint a new project key and re-wrap active bundle keys | Every active recipient share must be regenerated and reapproved |
+
+### Value rotation
+
+Use value rotation when the secret itself changed, such as a new API token or database password.
+
+Planned rules:
+
+- publish a new bundle version instead of mutating an old one
+- mint a fresh bundle key for the new version
+- keep project-key lineage stable unless the operator separately requests project-key rotation
+- preserve audit metadata linking the new bundle to the superseded version
+
+### Share rotation
+
+Use share rotation when the set of people or teams with access changed, but the underlying values do not need to change.
+
+Planned rules:
+
+- add or revoke recipient-specific key-share records
+- do not rewrite bundle ciphertext just because membership changed
+- do not require republishing values unless the operator explicitly wants a clean post-change snapshot
+- treat revocation as preventing fresh unwrap operations, not as proof that an old local copy was erased
+
+### Project-key rotation
+
+Use project-key rotation when the project key may be compromised, when a prior owner device is no longer trusted, or when the owner wants a stronger trust reset than share updates alone provide.
+
+Planned rules:
+
+- mint a new project key with a new durable key identifier
+- re-wrap the latest active bundle keys to that new project key
+- require every still-valid recipient share to be recreated against the new project key
+- record lineage so audit logs can explain which key superseded which predecessor
+
+## Recovery and lost-key handling
+
+Hack should not rely on silent plaintext escrow. Recovery must stay explicit, operator-visible, and auditable.
+
+### Required recovery guardrail
+
+Before portable env custody can become the only authority, there must be at least one recovery path:
+
+- an encrypted recovery package exported by the owner
+- a second owner or admin share
+- a designated recovery recipient share created on purpose
+
+If no recovery path remains, Hack should block destructive actions unless the operator uses an explicit forced override.
+
+### Lost-key situations
+
+#### 1. Lost local machine, but another trusted recovery path exists
+
+Planned recovery behavior:
+
+- authenticate as the same Hack owner or another authorized recovery holder
+- unwrap the active project key through the remaining recovery path
+- re-apply the portable bundle into fresh local compatibility storage
+- mint replacement recipient shares for any devices or operators that should keep access
+
+This is a recovery event, not a value rotation event. The secrets stay the same unless compromise is suspected.
+
+#### 2. A recipient loses their local key material
+
+Planned recovery behavior:
+
+- leave bundle versions unchanged
+- reissue that recipient's wrapped project-key share after authorization checks
+- require a full project-key rotation only if the old recipient device is considered untrusted or compromised
+
+#### 3. The project key may be compromised
+
+Planned recovery behavior:
+
+- stop treating simple share reissue as sufficient
+- require project-key rotation
+- regenerate all active recipient and recovery shares from the new key
+- preserve old-key lineage in audit history
+
+#### 4. The final recovery path would be removed
+
+Planned handling:
+
+- reject deleting the last owner or recovery share during normal operations
+- reject project-key rotation that would leave no valid recipient or recovery package
+- require a loud, explicit forced override for destructive break-glass actions and emit an audit event
+
+### UX expectations
+
+The eventual CLI and desktop UX should explain which state the operator is in:
+
+- `Rotate values`: secret contents changed
+- `Update access`: recipients changed
+- `Rotate project key`: trust anchor changed or may be compromised
+- `Recover access`: local key material was lost but a valid recovery path still exists
+- `Reconnect or recreate secrets`: no valid recovery path remains, so operator action must happen outside the portable recovery flow
+
 ## CLI
 
 - `hack env list [--json] [--show-secrets]`

docs/plans/2026-03-13-env-portability-and-secret-management-design.md

@@ -285,6 +285,17 @@ Behavior:
 - require explicit regeneration of all active key-share records
 - keep prior project-key lineage in audit metadata
 
+### Operator decision matrix
+
+The CLI and broker should treat these as different intents, not synonyms:
+
+| 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 |
+| A device was stolen, an owner key may be compromised, or the operator wants a hard trust reset | Project-key rotation | The trust anchor itself must change |
+| A user lost local key material but another valid recovery path remains | Recovery / share reissue | Access must be restored without forcing unnecessary secret churn |
+
 ### Recovery policy
 
 Hack should not silently escrow plaintext secrets. Recovery must be explicit.
@@ -305,6 +316,67 @@ Unsafe behavior to reject:
 - rotating the project key while leaving no valid recipient or backup
 - revoking the last usable recovery share without an explicit forced override
 
+### Lost-key handling flows
+
+The design needs to distinguish between `lost access` and `compromised access`.
+
+#### Case 1: Lost local machine, trusted recovery still exists
+
+Expected flow:
+
+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
+
+This should be logged as recovery, not as key compromise. Values and bundle history stay intact.
+
+#### Case 2: Recipient lost local key material
+
+Expected flow:
+
+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
+
+This is basically share repair. It should not force value rotation or project-key rotation on its own.
+
+#### Case 3: Owner or project key suspected compromised
+
+Expected flow:
+
+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
+4. record the superseded key lineage and reason in audit metadata
+
+If an operator cannot prove which recipient or device was affected, assume compromise and require project-key rotation instead of share repair.
+
+#### Case 4: No valid recovery path remains
+
+Expected flow:
+
+1. block normal revoke or rotate actions that would strand the project
+2. require explicit break-glass override semantics for destructive changes
+3. present a user-facing message that portable recovery is no longer possible without recreating authority
+
+The system should fail closed here. Hack must not pretend that remote recovery is available when no wrapped recovery authority exists.
+
+### Recovery package expectations
+
+An encrypted recovery package is an allowed recovery path, but it must stay metadata-rich enough to be usable later.
+
+Minimum metadata:
+
+- project binding identifier
+- project key identifier
+- creation timestamp
+- creating actor
+- encryption method / wrapping scheme identifier
+- optional human description supplied by the operator
+
+The package must not be treated as silent escrow. Operators should create it deliberately, store it deliberately, and understand that losing every recovery package plus every valid owner share means portable recovery is no longer possible.
+
 ## `.env` Compatibility And Backend UX
 
 Portability should preserve the current local runtime model instead of replacing it.

docs/plans/2026-03-13-env-portability-and-secret-management-plan.md

@@ -194,14 +194,15 @@ Add coverage for:
 - recovery package export metadata
 - preventing deletion of the last recovery path
 - preventing revocation of the last owner share without force
+- lost-key recovery versus compromised-key rotation handling
 
 **Step 2: Run test to verify it fails**
 
 Run: `bun test --cwd services/auth-broker tests/index.test.ts && bun test tests/env-command.test.ts` Expected: FAIL because rotation and recovery guardrails are not yet implemented.
 
 **Step 3: Write minimal implementation**
 
-Implement separate commands for value rotation, share changes, and project-key rotation, plus explicit recovery-path validation before destructive actions are allowed.
+Implement separate commands for value rotation, share changes, and project-key rotation, plus explicit recovery-path validation before destructive actions are allowed. Make the operator flow distinguish lost-key recovery/share reissue from compromised-key rotation.
 
 **Step 4: Run test to verify it passes**