Skip to content

docs: comprehensive documentation update for phases 28-37 #419

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 19 commits into from
Mar 31, 2026
+596 −209
Merged

docs: comprehensive documentation update for phases 28-37 #419

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
c5ecb54
docs: update project documentation for phases 28-37
FSM1 Mar 30, 2026
9edbe40
chore: move Web Worker encryption todo to done
FSM1 Mar 30, 2026
2f680d6
docs: clean up DEFERRED.md — remove implemented and out-of-scope items
FSM1 Mar 30, 2026
ebd6a11
docs: remove FUSE unit tests from deferred items -- won't fix
FSM1 Mar 30, 2026
9ae9bd6
docs: remove vault v1 column DROP from deferred items
FSM1 Mar 30, 2026
4551427
docs: thorough audit of DEFERRED.md -- remove 6 more implemented items
FSM1 Mar 30, 2026
3517be2
docs: restore user-configurable bin retention as deferred
FSM1 Mar 30, 2026
81fd0ee
docs: move remote log shipping to implemented -- Grafana Faro
FSM1 Mar 30, 2026
3bbce98
docs: prune code quality items, add phases 38-39 to roadmap
FSM1 Mar 30, 2026
9edb696
docs: add crypto->core circular dep removal to Phase 38
FSM1 Mar 30, 2026
dd49b8e
docs: expand Phase 39 scope -- versioning defaults, delete behavior
FSM1 Mar 30, 2026
a8917ee
docs: add Phase 39 vault settings to feature matrix
FSM1 Mar 30, 2026
53dd0da
docs: add Linux as supported platform, update stale references
FSM1 Mar 30, 2026
8a68b41
docs: clarify all CLI access methods for FUSE mounts
FSM1 Mar 30, 2026
4ffe96f
docs: include audio in AES-CTR streaming media types
FSM1 Mar 30, 2026
7d202ff
docs: fix incorrect claim that uploads always use AES-GCM
FSM1 Mar 30, 2026
72894f3
docs: update codebase CONCERNS.md and TESTING.md maps
FSM1 Mar 30, 2026
49d1d72
docs: address PR review comments on docs PR
FSM1 Mar 30, 2026
e42e876
docs: mark web app unit test gap as won't-fix
FSM1 Mar 31, 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
21 changes: 10 additions & 11 deletions .claude/claude.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,13 @@ CipherBox is a **technology demonstrator** for privacy-first encrypted cloud sto

## Documentation Structure

| Document | Purpose |
| ------------------------------------------------------------ | ------------------------------------------ |
| `00-Preliminary-R&D/Documentation/PRD.md` | Product requirements, user journeys, scope |
| `00-Preliminary-R&D/Documentation/TECHNICAL_ARCHITECTURE.md` | Encryption, key hierarchy, system design |
| `00-Preliminary-R&D/Documentation/API_SPECIFICATION.md` | Backend endpoints, database schema |
| `00-Preliminary-R&D/Documentation/DATA_FLOWS.md` | Sequence diagrams, test vectors |
| `00-Preliminary-R&D/Documentation/CLIENT_SPECIFICATION.md` | Web UI, desktop app specs |
| `00-Preliminary-R&D/Documentation/IMPLEMENTATION_ROADMAP.md` | Week-by-week development plan |
| Document | Purpose |
| ----------------------------------------------------------------- | ------------------------------------------ |
| `.planning/milestones/m0/Documentation/PRD.md` | Product requirements, user journeys, scope |
| `.planning/milestones/m0/Documentation/TECHNICAL_ARCHITECTURE.md` | Encryption, key hierarchy, system design |
| `.planning/milestones/m0/Documentation/API_SPECIFICATION.md` | Backend endpoints, database schema |
| `.planning/milestones/m0/Documentation/DATA_FLOWS.md` | Sequence diagrams, test vectors |
| `.planning/milestones/m0/Documentation/CLIENT_SPECIFICATION.md` | Web UI, desktop app specs |

## Finalized Specifications

Expand All @@ -22,12 +21,12 @@ CipherBox is a **technology demonstrator** for privacy-first encrypted cloud sto

### ⚠️ IMPORTANT: Do Not Edit Preliminary/Documentation Files

All files in `00-Preliminary-R&D/Documentation/` are **FINALIZED** specifications (version 1.10.0, status: Finalized). These documents represent the agreed-upon design and should **NOT** be modified.
All files in `.planning/milestones/m0/Documentation/` are **FINALIZED** specifications (version 1.10.0, status: Finalized). These documents represent the agreed-upon design and should **NOT** be modified.
**If you need to make changes:**

- New implementation documentation should be created in a separate location
- Working notes and updates belong in `.planning/` or project-specific directories
- Do not modify version numbers or content in `00-Preliminary-R&D/Documentation/` unless explicityly authorized.
- Do not modify version numbers or content in `.planning/milestones/m0/Documentation/` unless explicitly authorized.

## Terminology Standards

Expand Down Expand Up @@ -91,7 +90,7 @@ When generating code for CipherBox:
- **Encryption:** Client-side only, server is zero-knowledge
- **Sync:** IPNS polling (30s interval), no push infrastructure
- **Desktop:** FUSE mount for transparent file access
- **TEE Republishing:** Phala Cloud (primary) / AWS Nitro (fallback) for automatic IPNS republishing every 3 hours
- **TEE Republishing:** Phala Cloud CVM for automatic IPNS republishing every 6 hours
- **Key Epochs:** TEE public keys rotate with 4-week grace period for seamless migration

## Out of Scope (v1.0)
Expand Down
143 changes: 83 additions & 60 deletions .planning/DEFERRED.md
View file
Open in desktop

Large diffs are not rendered by default.

61 changes: 50 additions & 11 deletions .planning/FEATURES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CipherBox Feature Matrix

**Last updated:** 2026-03-28
**Last updated:** 2026-03-30

## Platform Feature Matrix

Expand All @@ -22,9 +22,10 @@
| Link/unlink auth methods | Y | - | Y | - | - |
| **File Operations** | | | | | |
| Upload (single file) | Y | Y | Y | Y | full-workflow |
| Upload (batch pipeline) | Y | - | Y | Y | batch-upload (SDK) |
| Upload (drag-and-drop) | Y | - | - | - | full-workflow |
| Download (single) | Y | Y | Y | Y | full-workflow |
| Download (batch zip) | Y | - | - | - | - |
| Download (batch selection) | Y | - | - | - | batch-download |
| Rename | Y | Y | - | Y | full-workflow |
| Delete (to bin) | Y | Y | - | Y | recycle-bin |
| Move (between folders) | Y | Y | - | Y | full-workflow |
Expand Down Expand Up @@ -69,10 +70,10 @@
| Cmd/Ctrl+K shortcut | Y | - | - | - | search-workflow |
| Keyboard navigation | Y | - | - | - | search-workflow |
| **Media Preview** | | | | | |
| Image preview | Y | - | - | - | full-workflow |
| PDF viewer | Y | - | - | - | - |
| Video player (streaming) | Y | - | - | - | - |
| Audio player | Y | - | - | - | - |
| Image preview | Y | - | - | - | media-preview |
| PDF viewer | Y | - | - | - | media-preview |
| Video player (streaming CTR) | Y | - | - | - | streaming-playback |
| Audio player | Y | - | - | - | media-preview |
| **Sync** | | | | | |
| IPNS polling (30s) | Y | Y | - | Y | conflict-detection |
| Conflict detection (409) | Y | Y | Y | Y | conflict-detection |
Expand All @@ -84,19 +85,30 @@
| OS keychain storage | - | Y | - | - | - |
| Auto-updater | - | Y | - | - | - |
| Dev-key mode (headless) | - | Y | - | - | desktop-e2e |
| **Vault Settings (Phase 39)** | | | | | |
| Bin retention period | - | - | - | - | - |
| Delete behavior (soft/hard) | - | - | - | - | - |
| Max versions per file | - | - | - | - | - |
| Version cooldown period | - | - | - | - | - |
| **Encryption** | | | | | |
| Web Worker encryption | Y | - | - | - | - |
| AES-CTR streaming decryption | Y | - | - | Y | streaming-playback |
| **Infrastructure** | | | | | |
| TEE IPNS republishing | - | - | Y | - | - |
| BYO IPFS node support | - | - | Y | - | sdk-e2e |
| Pin migration (provider switch) | - | - | Y | - | - |
| Prometheus metrics | - | - | Y | - | - |
| Vault recovery tool | Y | - | - | - | recovery |
| Performance baselines | - | - | Y | - | journey-timing |
| Structured logging (web) | Y | - | - | - | - |

## E2E Test Suites

### Web E2E (`tests/web-e2e/`)

| Suite | File | Coverage |
| ------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------- |
| Full Workflow | `full-workflow.spec.ts` | Login, vault init, folders, files, edit, rename, move, delete, versioning, media preview |
| Full Workflow | `full-workflow.spec.ts` | Login, vault init, folders, files, edit, rename, move, delete, versioning |
| Sharing | `sharing-workflow.spec.ts` | Direct shares, multi-recipient, revocation, key rotation, hide |
| Writable Shares | `writable-shares.spec.ts` | Write permission, recipient uploads/mkdir/rename/delete, permission upgrade/downgrade, file editing |
| Invite Links | `invite-link-workflow.spec.ts` | Create invite, claim, revoke, landing page |
Expand All @@ -107,17 +119,44 @@
| Recovery | `recovery.spec.ts` | Vault recovery tool via IPFS-direct v2 blob path |
| Conflict Detection | `conflict-detection.spec.ts` | Multi-device conflicts, auto-resync |
| Journey Timing | `journey-timing.spec.ts` | Performance benchmarks for critical paths |
| Load Test | `load-test.spec.ts` | Concurrent operations stress testing |
| Batch Download | `batch-download.spec.ts` | Multi-file selection, sequential individual downloads |
| Media Preview | `media-preview.spec.ts` | Image, PDF, video, audio preview dialogs |
| Streaming Playback | `streaming-playback.spec.ts` | AES-CTR streaming for large videos, GCM fallback for small videos |

### SDK E2E (`tests/sdk-e2e/`)

| Suite | File | Coverage |
| --------------------- | ------------------------------- | --------------------------------------------- |
| Vault Lifecycle | `vault-lifecycle.test.ts` | Init, key derivation, destroy |
| Folder CRUD | `folder-crud.test.ts` | Create, rename, move, delete folders |
| File Operations | `file-operations.test.ts` | Upload, download, rename, delete files |
| Batch Upload | `batch-upload.test.ts` | `uploadFiles()` multi-file pipeline |
| Bin Operations | `bin-operations.test.ts` | Soft delete, restore, permanent delete, empty |
| Share Operations | `share-operations.test.ts` | Direct shares, revocation, key re-wrapping |
| Invite Link | `invite-link.test.ts` | Create, claim, revoke invite links |
| Concurrent Operations | `concurrent-operations.test.ts` | Parallel uploads, downloads, folder ops |
| Data Integrity | `data-integrity.test.ts` | Round-trip encryption/decryption verification |
| Error Cases | `error-cases.test.ts` | Invalid inputs, network failures, edge cases |
| IPNS Consistency | `ipns-consistency.test.ts` | Sequence numbers, conflict detection |

### Load Tests (`tests/load/`)

| Type | Coverage |
| -------------- | ------------------------------------------ |
| Spike Test | Sudden burst of concurrent operations |
| Throughput | Sustained upload/download rate measurement |
| Mixed Workload | Combined CRUD operations under load |
| Sustained Load | Extended duration stability testing |
| BYO Ceiling | BYO-IPFS provider capacity limits |

## Features Without E2E Coverage

- PDF viewer, video player, audio player (manual testing only)
- Batch download (zip)
- Link/unlink auth methods
- Device registry sync
- OS keychain storage
- Auto-updater
- TEE republishing
- Pin migration
- Web Worker encryption (unit tested, not E2E)

<!-- Feature matrix: 2026-03-28 -->
<!-- Feature matrix: 2026-03-30 -->
24 changes: 22 additions & 2 deletions .planning/ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -466,6 +466,10 @@ Phases execute in numeric order: 18 -> 19 -> 19.1 -> 19.2 -> 20 -> 21 -> 22 -> 2
| 33. Windows Async FilePointer Resolution | v1.1 | 2/2 | Complete | 2026-03-28 |
| 34. E2E Test Expansion & Baselines | v1.1 | 4/4 | Complete | 2026-03-29 |
| 35. Phala Testnet TEE Migration | v1.1 | 6/6 | Complete | 2026-03-29 |
| 36. Inline Upload Progress | post-v1.1 | 2/2 | Complete | 2026-03-29 |
| 37. Parallel Batch Upload Pipeline | post-v1.1 | 2/2 | Complete | 2026-03-30 |
| 38. Retire Deprecated Web Services | post-v1.1 | - | Planned | - |
| 39. User-Configurable Vault Parameters | post-v1.1 | - | Planned | - |

### Phase 27: Writable Shares (PoC)

Expand Down Expand Up @@ -513,8 +517,24 @@ Plans:
- [x] 37-01-PLAN.md -- SDK batch uploadFiles() method with p-limit concurrency pool, stale-children re-read, partial failure handling
- [x] 37-02-PLAN.md -- Web Worker encryption offloading, EncryptionWorkerService wrapper, useDropUpload rewire to batch API

### Phase 38: Retire deprecated web services

**Goal:** Remove `folder.service.ts` (1,059 lines) and `bin.service.ts` (971 lines) by migrating all remaining callers to `@cipherbox/sdk` methods, eliminating the deprecated service layer. Also remove the circular devDependency from `@cipherbox/crypto` on `@cipherbox/core` by refactoring the vault-ipns test to use hardcoded test vectors instead of cross-package imports.
**Requirements**: None (tech debt cleanup, deferred from Phase 31)
**Depends on:** Phase 37

Plans: _not yet planned_

### Phase 39: User-configurable vault parameters

**Goal:** Add end-user vault settings stored in encrypted vault metadata, giving users control over: recycle bin retention period (default 30 days), delete behavior (soft delete to bin vs hard delete), and file versioning defaults (max versions per file, version cooldown period). Settings UI in the web app with sensible defaults matching current hardcoded values.
**Requirements**: None (deferred items from Phases 13, 17)
**Depends on:** Phase 38

Plans: _not yet planned_

---

_Roadmap created: 2026-03-07_
_Last updated: 2026-03-30_
_Total M1.1 phases: 18 (18-35 complete) | Concern resolution: 5 phases_
_Last updated: 2026-03-31_
_Total M1.1 phases: 18 (18-35 complete) | Concern resolution: 5 phases | Post-milestone: 4 phases (36-39)_
Loading