Skip to content

docs: plan v2.0 Metadata and Sharing Refactor milestone #574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FSM1 merged 5 commits into from
Jun 27, 2026
Merged

docs: plan v2.0 Metadata and Sharing Refactor milestone #574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6c314bf
docs: start milestone v2.0 Metadata and Sharing Refactor
FSM1 Jun 27, 2026
57d732c
docs: define milestone v2.0 requirements
FSM1 Jun 27, 2026
7bc9a30
docs: create milestone v2.0 roadmap (9 phases)
FSM1 Jun 27, 2026
efd9269
docs: v2.0 architecture and pitfalls research
FSM1 Jun 27, 2026
19fced9
docs: tag 1 pending todo with resolves_phase after milestone v2.0 roa…
FSM1 Jun 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 18 additions & 14 deletions .planning/MILESTONES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,32 +187,36 @@

## Active Milestone

### Milestone 3: IPFS Infrastructure v1.1 (in progress)
### Milestone 4: v2.0 Metadata and Sharing Refactor (in progress)

**Goal:** Make CipherBox IPFS-native -- replace delegated-ipfs.dev, migrate server-side state to IPFS/IPNS, add BYO-IPFS node support, and establish performance baselines
**Depends on:** Milestone 2
**Phases:** 18-22
**Requirements:** 25 (4 IPNS + 6 VAULT + 7 BYO + 8 PERF)
**Goal:** Replace the DB-driven share_keys sharing model with metadata-driven read key-chaining (node/v3), and close the two confirmed revocation gaps -- lazy/unsound read-revocation and un-rotatable write delegation.
**Depends on:** Milestone 3 (v1.1 — shipped 2026-06-27)
**Phases:** 61-69
**Requirements:** 39 (3 CRYPTO + 6 NODE + 5 READ + 7 ROT + 4 WRITE + 7 TEE + 4 DATA + 3 TEST)

**Phase structure:**

- Phase 18: Performance Instrumentation (PERF-01 to PERF-04)
- Phase 19: IPNS Resolution Improvement (IPNS-01 to IPNS-04)
- Phase 20: Vault Migration (VAULT-01 to VAULT-06)
- Phase 21: BYO-IPFS Node Support (BYO-01 to BYO-07)
- Phase 22: Performance Baselines Completion (PERF-05 to PERF-08)
- Phase 61: AAD-Bound Seal Primitive and Cross-Language KAT (CRYPTO-01..03, TEST-02)
- Phase 62: Unified Node Codec — Core Keystone (NODE-01..06)
- Phase 63: Read-Chain Navigation and Rotation Core (READ-01..05, ROT-01..02)
- Phase 64: Rotation Soundness — Revocation Guarantees (ROT-03..06, TEST-01)
- Phase 65: SDK Write-Chain, Bin Re-link, and Invite Claim (WRITE-01..04)
- Phase 66: API Schema Cutover, Publish Gate, and Tombstone (DATA-01..04, TEE-04, TEE-05, TEE-07)
- Phase 67: TEE Lease-Renewer Contract Rewrite (TEE-01..03, TEE-06)
- Phase 68: Web Integration — Rotation UX and Durable Client State (ROT-07)
- Phase 69: FUSE and WinFsp — Rust Integration and Grant-Root Awareness (TEST-03)

---

## Future Milestones

### Milestone 4: Encrypted Productivity Suite (planned)
### Milestone 5: Encrypted Productivity Suite (planned)

**Goal:** Full encrypted productivity suite -- docs/sheets/slides editors, team accounts, billing (Stripe or crypto), secure document signing, AWS Nitro TEE
**Depends on:** Milestone 3
**Phases:** 23+
**Depends on:** Milestone 4
**Phases:** 70+

---

Created: 2026-02-11
Last updated: 2026-03-07 after v1.1 IPFS Infrastructure roadmap created
Last updated: 2026-06-27 after v2.0 Metadata and Sharing Refactor roadmap created
64 changes: 60 additions & 4 deletions .planning/PROJECT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,28 @@ CipherBox is a production-grade, privacy-first encrypted cloud storage platform

**Zero-knowledge privacy**: Files are encrypted client-side before leaving the device, and encryption keys exist only in client memory. The server is cryptographically unable to access user data.

## Current Milestone: v2.0 Metadata and Sharing Refactor

**Goal:** Replace the DB-driven `share_keys` sharing model with metadata-driven read key-chaining (`node/v3`), and close the two confirmed revocation gaps — lazy/unsound read-revocation and un-rotatable write delegation.

**Target features:**

- Unified `Node` metadata model (folder/file/root) with two independently sealed bodies (read-body + write-body) and content self-sealing — replaces `FolderMetadata`/`FileMetadata`/`FilePointer`/`FolderEntry` and enables single-file shares
- AAD-bound AES-GCM seal primitive (`sealAesGcmAad`/`unsealAesGcmAad` + `buildNodeAad`) with a frozen byte encoding and a TS↔Rust cross-language KAT
- Read key-chaining: one ECIES at the share-root, then `O(depth)` symmetric AES down the tree — no `share_keys` fan-out, `O(recipients)` grant rows only
- Resumable read-rotation engine (`rotateReadFromNode`) backing read-revoke and every scope-exit mutation — crash-safe, idempotent, with CRIT-1 content-key rotation, M1 generation downgrade defense, HIGH-3 multi-rooted grant re-mint, HIGH-4 add-during-rotation merge
- Unified scope-exit rule (rotate iff a node leaves a grantee's reachable scope; no covering grant ⇒ pure relink) across delete/move/rename, including bin re-link and invite claim re-wrap
- Write-revocation via (c) full Ed25519 rotation (ADR 0001) with rotated-out IPNS name tombstoning
- Resolve/republish/TEE contract rewrite: DB-canonical resolve with `generation` + seq-floor as anti-rollback authority, TEE as a record-lease-renewer (no CID origination, no sequence increment), atomic publish CAS, hardened enclave bindings
- Schema/DB cutover: delete `share_keys`, slim `shares` to `readDescriptorRef`/`writeDescriptorRef`, rename `folder_ipns` → `ipns_records`, drop `folder_ipns.public_key`

**Source of truth:** `.planning/design/2026-06-26-sharing-read-keychaining-design.md`, [`docs/adr/0001`](../docs/adr/0001-write-revocation-full-ed25519-rotation.md), [`docs/adr/0002`](../docs/adr/0002-read-revocation-protects-future-content-only.md), and the [`CONTEXT.md`](../CONTEXT.md) glossary. Greenfield — no production data, staging wiped — so `node/v3` is the sole codec (no dual-codec bridge, terminology renamed cleanly).

## Current State

**v1.1 IPFS Infrastructure — SHIPPED 2026-06-27** (Milestone 3; 45 phases, 198 plans). All 77 requirements (66 formal v1.1 + 11 HARD) code-satisfied; integration 12/12 WIRED, E2E flows 4/4 INTACT. Delivered self-hosted Someguy IPNS routing (replacing delegated-ipfs.dev), vault blob v2 with DB crypto columns dropped, BYO-IPFS server-relay support, performance baselines + instrumentation, TS+Rust SDK extraction, writable shares, and a cross-layer fail-closed IPNS signature-verify hardening block. See `.planning/milestones/v1.1-MILESTONE-AUDIT.md` for the close-out verdict.

**Next up:** Milestone 4 — Encrypted Productivity Suite (v2.0). Not yet scoped. Fresh requirements come from `/gsd-new-milestone`.
**Next up:** Milestone 4 — v2.0 Metadata and Sharing Refactor (in planning). Scope locked to Tier 1 (read chain + rotation) + Tier 2 (write-revocation + TEE/resolve contract) of the read key-chaining design; Tier 3 capability layer and the Encrypted Productivity Suite are deferred. Requirements derived from the design in `/gsd-new-milestone`.
Comment on lines +11 to +32

@coderabbitai coderabbitai Bot Jun 27, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Fix version inconsistency: "v2.1" should be "v2.0"

Line 32 says "Milestone 4 — v2.1 Metadata and Sharing Refactor" but the "Current Milestone" header (line 11) and MILESTONES.md both identify this as v2.0. Align line 32 with "v2.0" to prevent confusion in downstream workflow parsing.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.planning/PROJECT.md around lines 11 - 32, The milestone version label is
inconsistent: the “Next up” section in PROJECT.md uses v2.1 while the current
milestone header and MILESTONES.md use v2.0. Update the milestone text in the
affected section to match v2.0, keeping the “Milestone 4 — Metadata and Sharing
Refactor” wording aligned with the rest of the document so downstream parsing
sees a single version.


## Requirements

Expand Down Expand Up @@ -60,13 +77,27 @@ Full requirement IDs archived in `.planning/milestones/v1.1-REQUIREMENTS.md` (77

### Active

- [ ] Phase 39 D-02 — add a confirmation dialog before permanent/hard delete (data-safety UX gap; captured todo)
v2.0 Metadata and Sharing Refactor — full requirement list with REQ-IDs in `.planning/REQUIREMENTS.md` (NODE / CRYPTO / READ / ROT / WRITE / TEE / DATA categories). Scope: Tier 1 + Tier 2 of the read key-chaining design.

Carried from v1.1 (deferred, not yet retired):

- [ ] Phase 39 D-02 — add a confirmation dialog before permanent/hard delete (data-safety UX gap; captured todo). Note: the bin re-link rework under `node/v3` (DATA-/ROT-) touches this surface.
- [ ] Phase 39 D-06 — remove or document the residual server-side `RECYCLE_BIN_RETENTION_DAYS` endpoint/env var (dead backend surface)
- [ ] HARD-11 — complete the Phase 60 staging operational smoke-test (D-12 lockstep checkpoint), or accept as an infra-limited override

### Out of Scope (Milestone 4 — v2.0)

- Tier 3 capability layer (read-side TTL, op-count caps, `capabilityId`) — read-side TTL/op-caps are cryptographically unenforceable; do not add `ttl`/`opCap`/`capabilityId` to `Node` or `SealedChildRef`
- Data migration / dual-codec bridge — greenfield (no prod data, staging wiped); `node/v3` is the sole codec
- Mediated write signing — approach (a)/(d) `POST /ipns/sign` endpoint — runner-up only; (c) full Ed25519 rotation is ratified (ADR 0001)
- Retroactive content protection — read-revoke protects future content/navigation only; already-distributed CIDs and prior versions stay readable (ADR 0002)
- Lazy rotation *walk* (rotate-on-next-write across a subtree) — eager walk is the committed model; the `rotateOne` primitive stays amortizable later
- SEED-001 Phala TEE on-demand cost cycling — separable infra-cost optimization; deferred to a future infra milestone (stays dormant in `.planning/seeds/`)
- Encrypted Productivity Suite (billing, teams, doc editors, signing) — deferred to a later milestone (was tentatively v2.0; v2.0 is now the sharing refactor)

### Out of Scope (Milestone 3 — v1.1)

- Encrypted Productivity Suite (billing, teams, doc editors, signing) — deferred to Milestone 4 (v2.0)
- Encrypted Productivity Suite (billing, teams, doc editors, signing) — deferred to a post-v2.0 milestone
- Mobile apps (iOS/Android) — deferred to Milestone 4+
- Real-time collaborative editing — deferred to Milestone 4+
- Offline write queue / selective sync — deferred to Milestone 4+
Expand Down Expand Up @@ -131,7 +162,32 @@ Full requirement IDs archived in `.planning/milestones/v1.1-REQUIREMENTS.md` (77
| Vault blob v2 — zero DB crypto | rootFolderKey in IPFS blob, all DB crypto columns dropped | ✓ |
| Monorepo SDK extraction (TS + Rust) | Reusable core shared across web, desktop, recovery tooling | ✓ |
| Strict fail-closed IPNS verified-resolver | Single signature-verify chokepoint across all layers | ✓ |
| Metadata-driven read key-chaining (node/v3) | One ECIES at share-root + O(depth) AES; kills share_keys fan-out | — Pending |
| Two sealed bodies per node (read + write) | Structural read/write separation; read grant never conveys signing key | — Pending |
| Write-revocation = (c) full Ed25519 rotation | No new TEE/relay trust; key-possession auth (ADR 0001) | — Pending |
| Read-revoke protects future content only | IPFS is content-addressed; honest threat model (ADR 0002) | — Pending |
| TEE = record-lease-renewer (no CID, no seq++) | Closes republisher stale-CID rollback structurally | — Pending |
| Greenfield node/v3 sole codec | No prod data, staging wiped; no dual-codec/migration bridge | — Pending |

## Evolution

This document evolves at phase transitions and milestone boundaries.

**After each phase transition** (via `/gsd-transition`):

1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd-complete-milestone`):

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-06-27 after v1.1 milestone. v1.1 IPFS Infrastructure (Milestone 3) shipped — 45 phases / 198 plans, 77/77 requirements code-satisfied (66 formal + 11 HARD), integration 12/12, flows 4/4. Remaining carried items: Phase 39 D-02 permanent-delete confirmation (captured todo), D-06 residual server env-var, and the HARD-11 staging operational smoke-test. Next milestone (4 — Encrypted Productivity Suite) not yet scoped; run `/gsd-new-milestone`. See `.planning/milestones/v1.1-MILESTONE-AUDIT.md`.
Last updated: 2026-06-27 — Milestone 4 (v2.0 Metadata and Sharing Refactor) started. Scope locked to Tier 1 (read key-chaining + resumable read-rotation) + Tier 2 (write-revocation via ADR 0001 full Ed25519 rotation + resolve/republish/TEE contract rewrite). Tier 3 capability layer and SEED-001 TEE cost-cycling deferred. Greenfield `node/v3` sole codec. Requirements in `.planning/REQUIREMENTS.md`; design source of truth in `.planning/design/2026-06-26-sharing-read-keychaining-design.md` + ADR 0001/0002 + `CONTEXT.md`. v1.1 carried items (Phase 39 D-02/D-06, HARD-11 staging smoke-test) remain open.
Loading
Loading