docs: plan v2.0 Metadata and Sharing Refactor milestone#574
Conversation
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SDNQVLoAw4DbPrPvtQPobh Entire-Checkpoint: a307f55733df
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SDNQVLoAw4DbPrPvtQPobh Entire-Checkpoint: e8164a5861c9
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SDNQVLoAw4DbPrPvtQPobh Entire-Checkpoint: e1a3fb8e78f2
Architecture + Pitfalls research for the node/v3 sharing refactor; archive v1.1 top-level research under _v1.1-archive/. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SDNQVLoAw4DbPrPvtQPobh Entire-Checkpoint: 6c3c2756738d
…dmap Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SDNQVLoAw4DbPrPvtQPobh Entire-Checkpoint: aecd4e95cb28
WalkthroughThe PR replaces the planning and research materials for the v2.0 metadata and sharing refactor, updates milestone and state tracking to Phase 61, adds a new requirements and roadmap set, and rewrites the v2.0 research docs while archiving the prior v1.1 research set. Changesv2.0 Planning and Research Refresh
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Release PreviewNo version bumps detected. All changes are in unversioned paths or use exempt commit types. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
.planning/research/_v1.1-archive/ARCHITECTURE.md (1)
1-6: 📐 Maintainability & Code Quality | 🔵 TrivialAdd archive notice to document header.
The path (
_v1.1-archive/) indicates this is archived, but readers who encounter the file out of context (e.g., via search, deep links, or future copy-paste) may not realize it is superseded by v2.0 planning. Add a prominent header note that this document is archived v1.1 research and that current planning is in.planning/research/(v2.0).# Architecture: IPFS Infrastructure v1.1 + > **ARCHIVED:** This is v1.1 research, preserved for historical reference. + > Current planning: see `.planning/research/ARCHITECTURE.md` (v2.1). + **Domain:** IPNS reliability, database minimization, BYO-IPFS, performance baselines **Researched:** 2026-03-07 **Confidence:** HIGH (existing codebase analyzed; Kubo APIs verified against official docs)🤖 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/research/_v1.1-archive/ARCHITECTURE.md around lines 1 - 6, Add a prominent archive notice to the top of the ARCHITECTURE.md document so readers immediately see that this is archived v1.1 research and has been superseded by v2.0 planning. Update the document header near the existing title/metadata section, and reference the current planning location in `.planning/research/` so the archived status is clear even when the file is viewed out of context.Source: Learnings
.planning/research/_v1.1-archive/SUMMARY.md (1)
1-7: 📐 Maintainability & Code Quality | 🔵 TrivialAdd archive notice to document header.
Same rationale as the other archived files: declare archived status in the document body for out-of-context readers.
# Project Research Summary + > **ARCHIVED:** This is v1.1 research, preserved for historical reference. + > Current planning: see `.planning/research/SUMMARY.md` (v2.1). + **Project:** CipherBox v1.1 -- IPFS Infrastructure **Domain:** IPFS/IPNS reliability, database minimization, BYO-IPFS node support, performance baselines **Researched:** 2026-03-07 **Confidence:** HIGH🤖 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/research/_v1.1-archive/SUMMARY.md around lines 1 - 7, Add an archived-status notice to the SUMMARY.md header so out-of-context readers immediately know it is no longer active; update the document body near the existing Project Research Summary metadata, keeping the change aligned with this archived research file’s header content and overall archive pattern used in the _v1.1-archive section.Source: Learnings
.planning/research/_v1.1-archive/PITFALLS.md (1)
1-6: 📐 Maintainability & Code Quality | 🔵 TrivialAdd archive notice to document header.
Same rationale as ARCHITECTURE.md: the
_v1.1-archive/path is clear, but the document itself should declare its archived status for readers who find it via search or deep links.# Pitfalls Research + > **ARCHIVED:** This is v1.1 research, preserved for historical reference. + > Current planning: see `.planning/research/PITFALLS.md` (v2.1). + **Domain:** IPFS infrastructure improvements -- replacing delegated routing, migrating DB state to IPFS/IPNS, BYO-IPFS node support, and performance baselines for an existing zero-knowledge encrypted storage app **Researched:** 2026-03-07 **Confidence:** HIGH for routing/migration pitfalls (verified against codebase + IPFS docs), MEDIUM for BYO-IPFS (fewer production precedents), MEDIUM for instrumentation (well-understood domain but CipherBox-specific interactions need validation)🤖 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/research/_v1.1-archive/PITFALLS.md around lines 1 - 6, Add an archived-status notice to the top of the PITFALLS.md header so readers immediately see it is not current, even when reaching it via search or deep links. Update the document header near the existing “Pitfalls Research” title and metadata, keeping the notice consistent with the archive wording used elsewhere in the _v1.1-archive_ docs.Source: Learnings
🤖 Prompt for all review comments with 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.
Inline comments:
In @.planning/PROJECT.md:
- Around line 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.
---
Nitpick comments:
In @.planning/research/_v1.1-archive/ARCHITECTURE.md:
- Around line 1-6: Add a prominent archive notice to the top of the
ARCHITECTURE.md document so readers immediately see that this is archived v1.1
research and has been superseded by v2.0 planning. Update the document header
near the existing title/metadata section, and reference the current planning
location in `.planning/research/` so the archived status is clear even when the
file is viewed out of context.
In @.planning/research/_v1.1-archive/PITFALLS.md:
- Around line 1-6: Add an archived-status notice to the top of the PITFALLS.md
header so readers immediately see it is not current, even when reaching it via
search or deep links. Update the document header near the existing “Pitfalls
Research” title and metadata, keeping the notice consistent with the archive
wording used elsewhere in the _v1.1-archive_ docs.
In @.planning/research/_v1.1-archive/SUMMARY.md:
- Around line 1-7: Add an archived-status notice to the SUMMARY.md header so
out-of-context readers immediately know it is no longer active; update the
document body near the existing Project Research Summary metadata, keeping the
change aligned with this archived research file’s header content and overall
archive pattern used in the _v1.1-archive section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 13da5f9f-b2a9-42d5-a2a3-36313de90ef3
📒 Files selected for processing (14)
.planning/MILESTONES.md.planning/PROJECT.md.planning/REQUIREMENTS.md.planning/ROADMAP.md.planning/STATE.md.planning/research/ARCHITECTURE.md.planning/research/PITFALLS.md.planning/research/SUMMARY.md.planning/research/_v1.1-archive/ARCHITECTURE.md.planning/research/_v1.1-archive/FEATURES.md.planning/research/_v1.1-archive/PITFALLS.md.planning/research/_v1.1-archive/STACK.md.planning/research/_v1.1-archive/SUMMARY.md.planning/todos/pending/2026-06-23-bin-delete-and-empty-bin-leak-content-and-version-cid-pins.md
| ## 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`. |
There was a problem hiding this comment.
🎯 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.
Greptile SummaryPlanning-only PR that establishes the v2.0 Metadata and Sharing Refactor milestone: 39 requirements (CRYPTO/NODE/READ/ROT/WRITE/TEE/DATA/TEST), a 9-phase linear roadmap (phases 61–69), refreshed research documents, and v1.1 history archived. No product code is changed.
Confidence Score: 4/5Safe to merge — no product code changes, all 39 requirements are covered, and the dependency chain is sound. The traceability table claims each requirement maps to exactly one phase, but TEE-04 and WRITE-04 both have implementation steps split across two consecutive phases — the table will show them complete one phase before they actually are. These gaps don't block merge but will need to be corrected before the affected phases are signed off. .planning/REQUIREMENTS.md traceability entries for TEE-04 (line 138) and WRITE-04 (line 133); the resolves_phase: 65 frontmatter in the bin-delete todo. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
P60[Phase 60: v1.1 Complete] --> P61
P61[Phase 61: AAD-Bound Seal Primitive\nCRYPTO-01/02/03, TEST-02] --> P62
P62[Phase 62: Unified Node Codec\nNODE-01..06] --> P63
P63[Phase 63: Read-Chain Navigation\nREAD-01..05, ROT-01/02] --> P64
P64[Phase 64: Rotation Soundness\nROT-03..06, TEST-01] --> P65
P65[Phase 65: SDK Write-Chain + Bin Re-link\nWRITE-01..04] --> P66
P66[Phase 66: API Schema Cutover\nDATA-01..04, TEE-04/05/07] --> P67
P67[Phase 67: TEE Lease-Renewer Rewrite\nTEE-01/02/03/06] --> P68
P68[Phase 68: Web Integration\nROT-07] --> P69
P69[Phase 69: FUSE + WinFsp\nTEST-03]
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
P60[Phase 60: v1.1 Complete] --> P61
P61[Phase 61: AAD-Bound Seal Primitive\nCRYPTO-01/02/03, TEST-02] --> P62
P62[Phase 62: Unified Node Codec\nNODE-01..06] --> P63
P63[Phase 63: Read-Chain Navigation\nREAD-01..05, ROT-01/02] --> P64
P64[Phase 64: Rotation Soundness\nROT-03..06, TEST-01] --> P65
P65[Phase 65: SDK Write-Chain + Bin Re-link\nWRITE-01..04] --> P66
P66[Phase 66: API Schema Cutover\nDATA-01..04, TEE-04/05/07] --> P67
P67[Phase 67: TEE Lease-Renewer Rewrite\nTEE-01/02/03/06] --> P68
P68[Phase 68: Web Integration\nROT-07] --> P69
P69[Phase 69: FUSE + WinFsp\nTEST-03]
Reviews (1): Last reviewed commit: "docs: tag 1 pending todo with resolves_p..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| | TEE-04 | Phase 66 | Pending | | ||
| | TEE-05 | Phase 66 | Pending | | ||
| | TEE-07 | Phase 66 | Pending | |
There was a problem hiding this comment.
TEE-04 is mapped exclusively to Phase 66, but the second half of its definition — "the EOL-only renewal is guarded identically so it can never regress latestCid/sequenceNumber" — is implemented by Phase 67 success criterion #4 ("The EOL-only renewal uses the same atomic CAS guard"). If Phase 66 is signed off using only the traceability table, TEE-04 will appear complete while the TEE worker's renewal guard hasn't landed yet. Consider mapping TEE-04 to both Phase 66 and Phase 67 (split as TEE-04a / TEE-04b), or add a note at Phase 66's TEE-04 entry clarifying that the EOL renewal guard is deferred to Phase 67.
| | WRITE-04 | Phase 65 | Pending | | ||
| | DATA-01 | Phase 66 | Pending | |
There was a problem hiding this comment.
WRITE-04 ("the publish gate rejects all writes to it including the EOL-only renewal, resolve returns a tombstone/410") is mapped to Phase 65, but the API-level enforcement of that gate is Phase 66 success criterion #5 ("A tombstoned ipns_records row is rejected at the publish gate (403/410) and at the EOL-only renewal; resolve returns a 410 marker for tombstoned names"). Phase 65 covers SDK-side tombstone creation; Phase 66 is where the server rejects writes to a tombstoned name. Signing off WRITE-04 at Phase 65 would mean the API gate is still missing. Same resolution as TEE-04: split the requirement or add a cross-phase note.
| - apps/api/src/shares/shares.service.ts | ||
| - apps/api/src/shares/shares.controller.ts | ||
| - apps/api/src/shares/dto/revoke-for-items.dto.ts | ||
| resolves_phase: 65 |
There was a problem hiding this comment.
resolves_phase: 65 signals that Phase 65 closes this todo, but the two remaining deferred items — (3) CAS superseded-metadata-blob unpin on every publish and (5) one-off staging remediation of the existing 442 MB — appear nowhere in Phase 65's success criteria. Phase 65 SC #4 covers the BinEntry re-link architecture but not the metadata-blob unpin or the staging cleanup. If Phase 65 is signed off against its stated criteria, these deferred items risk being silently dropped. Consider either adding an explicit SC bullet to Phase 65 for the metadata-blob unpin, or splitting item 5 into a separate ops todo that doesn't depend on resolves_phase: 65.
| **Phase to address:** | ||
| Crypto primitive phase (Phase 1 / `packages/crypto`). The KAT must be committed and passing before any downstream phase begins. Every subsequent phase that adds a new `role` byte must extend the KAT fixture. |
There was a problem hiding this comment.
"Phase to address: Crypto primitive phase (Phase 1 / packages/crypto)" — the roadmap uses Phase 61, not Phase 1. Appears to be a leftover from when the research was drafted with relative numbering before the 61–69 range was finalized. Same pattern applies to any other pitfall that still uses a relative phase number. Minor, but could be confusing when cross-referencing during Phase 61 planning.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
1 participant
Summary
Milestone planning for v2.0 Metadata and Sharing Refactor — replaces the DB-driven
share_keyssharing model with metadata-driven read key-chaining (node/v3) and closes the two confirmed revocation gaps: lazy/unsound read-revocation and un-rotatable write delegation.This PR contains planning artifacts only (no product code). Generated via
/gsd:new-milestonefrom the implementation-ready design.Scope: Tier 1 (read chain + resumable rotation) + Tier 2 (write-revocation via full Ed25519 rotation + resolve/republish/TEE contract rewrite). Tier 3 capability layer and SEED-001 TEE cost-cycling are deferred. Greenfield — no prod data, staging wiped — so
node/v3is the sole codec (no migration, no dual-codec bridge).Source of truth (already on
main):.planning/design/2026-06-26-sharing-read-keychaining-design.md+docs/adr/0001-write-revocation-full-ed25519-rotation.md+docs/adr/0002-read-revocation-protects-future-content-only.md+ theCONTEXT.mdglossary.What's in this PR
PROJECT.mdREQUIREMENTS.mdROADMAP.mdresearch/_v1.1-archive/STATE.md/MILESTONES.mdRoadmap (Phases 61–69)
Strict dependency chain — nothing below
packages/coretypechecks until the codec lands:Nodecodec keystoneThe silent-failure guards — CRIT-1 (fileKey mint), M1 (durable generation high-water), HIGH-3 (multi-rooted re-mint), HIGH-4 (add-during-rotation), republisher seq-increment, atomic publish CAS — are each gated by a named test from the design's §7.3 test strategy in the owning phase's success criteria.
Notes
resolves_phase: 65(bin-delete CID-pin leak — lives in the exact files Phase 65 rewrites).Next step
After merge:
/gsd:discuss-phase 61(recommended — Phase 61 freezes a byte encoding every later phase depends on) or/gsd:plan-phase 61.🤖 Generated with Claude Code
https://claude.ai/code/session_01SDNQVLoAw4DbPrPvtQPobh
Summary by CodeRabbit