Plans and encryption
What is encrypted for plans, where plaintext appears, and what sharing requires.
Plans can be either normal collaborative documents or trusted-edge encrypted artifacts. Treat those as two different modes.
Alpha behavior
Hook-created plan drafts use the trusted-edge encrypted path. Browser-local plan keys are not a supported collaboration mode. Hosted-browser viewing still means the loaded web app can see plaintext while it renders.
The two plan modes
| Mode | Server visibility | Best for |
|---|---|---|
| Plaintext collaborative plan | Body, comments, anchors, metadata | Low-sensitive plans where search, comments, and simple sharing matter most. |
| Trusted-edge encrypted plan | Ciphertext body, wrapped key grants, metadata | Sensitive agent-created plans that should not be readable from the platform database. |
The platform always sees some metadata: owner, workspace, resource id, timestamps, share state, inbox state, and audit rows. Encrypted plan mode protects the plan body and encrypted feedback bodies. It does not make every surrounding workflow invisible.
Hook-created drafts
When a Claude or Codex hook captures a plan locally, the daemon encrypts the body before saving the draft:
The durable record is stored on the platform as ciphertext plus metadata. The body key is held by the trusted edge and can be wrapped to approved recipients.
The web app must present a short-lived, scoped command capability when it asks a trusted edge to decrypt a plan body, decrypt an encrypted feedback field, encrypt a new feedback field, or wrap the body key for sharing. A capability for one plan is not valid for another plan. Hosted web should not call 127.0.0.1 or a VPS daemon HTTP port directly for plan plaintext.
Manual unlock uses vpd unlock <id>. Auto-unlock can skip that paste step for machines you explicitly marked as trusted during pairing or in Settings. The auto-unlock session is still short-lived, bound to an online install, and routed through the same trusted-edge command path.
Sharing encrypted plans
Encrypted plan sharing needs two layers:
- ACL sharing, so the recipient can discover the plan.
- A cryptographic body-key grant, so the recipient's trusted edge can decrypt it.
The platform stores the wrapped grant but not the raw body key. A recipient who has ACL access but no active user/team epoch grant can discover the plan but cannot decrypt the encrypted body.
Comments and anchors
Comments need anchors: a heading, block id, selected quote, or position. That is where privacy and collaboration collide.
| Model | Privacy | Collaboration |
|---|---|---|
| Plaintext comments and anchors | Lowest | Easiest |
| Encrypted comments, plaintext structural anchors | Balanced | Practical |
| Encrypted comments and encrypted anchors | Highest | Hardest |
Viewport's encrypted-plan path uses the balanced model. Sensitive comment and suggestion bodies can be encrypted through the trusted edge. Structural anchors may remain server-readable so the interface can place comments reliably. For high-sensitivity plans, assume metadata and anchors can reveal some structure even when the body is encrypted.
Browser trust
If the hosted web app renders plaintext, plaintext exists in browser memory. That still protects against database leaks, backend logs, and relay operators, but it does not remove all trust in the web app code that was delivered to the browser.
For the strongest posture, use a local or self-built trusted-edge viewer for decrypt/render. Moving the sensitive viewer code into the open-source viewport surface is part of the security backlog.
Revocation
Revocation is soft. Removing a recipient stops future access and future grants, but it cannot prove that a device forgot content it already decrypted. Key rotation can protect future revisions, not past plaintext.
Current limits
- Plaintext plan mode may still exist for ordinary collaboration, but hook-created drafts and sensitive plan sharing should use trusted-edge encryption.
- Encrypted sharing only works for recipients with active user/team crypto epochs and enrolled trusted edges.
- The platform still sees plan metadata, ACLs, audit rows, and inbox state.
- Hosted-browser plaintext is not the same as daemon-only plaintext.
- Browser-local legacy plan keys are unsupported.
- Hard delete, hard revocation, and customer-managed keys are not available yet.