FSM1 · FSM1 · Jan 17, 2026 · Jan 17, 2026 · Jan 17, 2026 · Jan 17, 2026
diff --git a/.claude/claude.md b/.claude/claude.md
@@ -16,7 +16,7 @@ CipherBox is a **technology demonstrator** for privacy-first encrypted cloud sto
 
 ## Version Management
 
-**Current Version:** 1.7.0
+**Current Version:** 1.8.0
 
 ### Version Bump Rule
 

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -2,7 +2,7 @@
 
 ## Version Management
 
-**Current Documentation Version:** 1.7.0
+**Current Documentation Version:** 1.8.0
 
 ### Version Bump Rule
 

diff --git a/.gitignore b/.gitignore
@@ -1 +1,5 @@
 .DS_Store
+
+/**/dist
+/**/node_modules
+/**/.env
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,3 @@
+{
+  "recommendations": ["bierner.markdown-mermaid"]
+}
diff --git a/00_START_HERE.md b/00_START_HERE.md
@@ -79,6 +79,12 @@ Server stores **only encrypted keys** - never plaintext
 
 ***
 
+## 🧪 Console PoC Harness (Validation-First)
+
+To de-risk the crypto and IPFS/IPNS assumptions, a single-user Node.js console harness runs the full file/folder flow end-to-end without Web3Auth or backend dependencies. Each run publishes metadata to IPFS/IPNS, verifies correctness via IPNS resolution, measures propagation delay, and unpins all created CIDs during teardown.
+
+***
+
 ## 📋 MVP Scope (v1.0)
 
 ### ✅ **Included**

diff --git a/Documentation/CLIENT_SPECIFICATION.md b/Documentation/CLIENT_SPECIFICATION.md
@@ -1,6 +1,6 @@
 ---
-version: 1.7.0
-last_updated: 2026-01-16
+version: 1.8.0
+last_updated: 2026-01-17
 status: Active
 ai_context: Client application specifications for CipherBox. Contains Web UI and Desktop app requirements. For system design see TECHNICAL_ARCHITECTURE.md.
 ---
@@ -9,7 +9,7 @@ ai_context: Client application specifications for CipherBox. Contains Web UI and
 
 **Document Type:** Client Application Specification  
 **Status:** Active  
-**Last Updated:** January 16, 2026  
+**Last Updated:** January 17, 2026  
 
 ---
 
@@ -19,6 +19,7 @@ ai_context: Client application specifications for CipherBox. Contains Web UI and
 2. [Desktop Application](#2-desktop-application)
 3. [Shared Components](#3-shared-components)
 4. [Outstanding Questions](#4-outstanding-questions)
+5. [Console PoC Harness](#5-console-poc-harness)
 
 ---
 
@@ -501,6 +502,33 @@ interface VaultModule {
 
 ---
 
+## 5. Console PoC Harness
+
+**Goal:** Provide a single-user, online test harness to validate IPFS/IPNS flows without Web3Auth or the backend.
+
+**Environment:** Node.js (TypeScript), local IPFS daemon, optional Pinata API keys for pin/unpin.
+
+**Behavior:**
+
+1. Load `privateKey` from `.env` (never logged)
+2. Generate `rootFolderKey` and root IPNS key
+3. Create folders and publish IPNS updates
+4. Upload, modify, rename, move, delete a file
+5. Verify each step by resolving IPNS and decrypting metadata/content
+6. Measure IPNS propagation delay per publish
+7. Teardown: unpin all created CIDs (files + folder metadata) and remove IPNS keys
+
+**Persistence:**
+- `rootFolderKey` and `rootIpnsName` are persisted to disk during the run
+- Private keys remain in memory only
+
+**Non-goals:**
+- Web UI or desktop UI
+- Web3Auth integration
+- Vault export or recovery workflows
+
+---
+
 ## Related Documents
 
 - [PRD.md](./PRD.md) - Product requirements and user journeys

diff --git a/Documentation/DATA_FLOWS.md b/Documentation/DATA_FLOWS.md
@@ -1,6 +1,6 @@
 ---
-version: 1.7.0
-last_updated: 2026-01-16
+version: 1.8.0
+last_updated: 2026-01-17
 status: Active
 ai_context: Data flow diagrams and test vectors for CipherBox. Contains Mermaid sequence diagrams for all major operations. For system design see TECHNICAL_ARCHITECTURE.md.
 ---
@@ -9,7 +9,7 @@ ai_context: Data flow diagrams and test vectors for CipherBox. Contains Mermaid
 
 **Document Type:** Implementation Reference  
 **Status:** Active  
-**Last Updated:** January 16, 2026  
+**Last Updated:** January 17, 2026  
 
 ---
 
@@ -22,6 +22,7 @@ ai_context: Data flow diagrams and test vectors for CipherBox. Contains Mermaid
 5. [Vault Export & Recovery Flow](#5-vault-export--recovery-flow)
 6. [Write Operations](#6-write-operations)
 7. [Test Vectors](#7-test-vectors)
+8. [Console PoC Harness Flow](#8-console-poc-harness-flow)
 
 ---
 
@@ -593,6 +594,52 @@ Verification:
   ✓ result == fileKey
   ✓ Different privateKey causes failure
   ✓ Same publicKey/privateKey pair always works
+
+---
+
+## 8. Console PoC Harness Flow
+
+The console PoC is a single-user, online test harness that executes a full filesystem flow per run and measures IPNS propagation delays. It does not use Web3Auth or the backend.
+
+```mermaid
+sequenceDiagram
+    participant H as PoC Harness
+    participant IPFS as IPFS Network
+
+    Note over H: Bootstrap
+    H->>H: Load privateKey from .env
+    H->>H: Generate rootFolderKey
+    H->>H: Generate root IPNS key (local IPFS keystore)
+    H->>IPFS: Add encrypted root metadata
+    H->>IPFS: Pin metadata CID
+    H->>IPFS: Publish IPNS (root)
+
+    Note over H: Folder Operations
+    H->>H: Create subfolder keys + IPNS key
+    H->>IPFS: Add + pin subfolder metadata
+    H->>IPFS: Publish subfolder IPNS
+    H->>IPFS: Update root metadata, publish root IPNS
+
+    Note over H: File Operations
+    H->>H: Encrypt file (AES-GCM), wrap key (ECIES)
+    H->>IPFS: Add + pin encrypted file
+    H->>IPFS: Update folder metadata, publish folder IPNS
+    H->>IPFS: Resolve IPNS, fetch metadata, decrypt and verify
+
+    Note over H: Modify / Rename / Move / Delete
+    H->>IPFS: Publish after each metadata change
+    H->>IPFS: Unpin replaced or deleted file CIDs
+
+    Note over H: Teardown
+    H->>IPFS: Unpin all file + metadata CIDs
+    H->>IPFS: Remove IPNS keys from local keystore
+```
+
+**Verification checkpoints:**
+- IPNS resolves to expected metadata CID after each publish (poll-until-resolved)
+- Metadata decrypts correctly with expected entries
+- File decrypts correctly after upload, update, rename, move
+- All created CIDs are unpinned during teardown
 ```
 
 ---

diff --git a/Documentation/IMPLEMENTATION_ROADMAP.md b/Documentation/IMPLEMENTATION_ROADMAP.md
@@ -1,3 +1,10 @@
+---
+version: 1.8.0
+last_updated: 2026-01-17
+status: Active
+ai_context: Implementation roadmap for CipherBox v1.0. Includes week-by-week plan, deliverables, and testing milestones.
+---
+
 <img src="https://r2cdn.perplexity.ai/pplx-full-logo-primary-dark%402x.png" style="height:64px;margin-right:32px"/>
 
 # CipherBox v1.0 - Implementation Roadmap
@@ -32,6 +39,7 @@
 ✅ PRD reviewed by team
 ✅ Dev environments working (Node.js, PostgreSQL, Docker)
 ✅ Crypto libraries evaluated (Web Crypto API, libsodium.js)
+✅ Console PoC harness spike (single-user IPFS/IPNS + pin/unpin)
 ✅ Web3Auth dashboard setup + group connections configured
 ✅ Pinata API test account
 ✅ Database schema migration scripts

diff --git a/Documentation/PRD.md b/Documentation/PRD.md
@@ -1,6 +1,6 @@
 ---
-version: 1.7.0
-last_updated: 2026-01-16
+version: 1.8.0
+last_updated: 2026-01-17
 status: Active
 ai_context: Product requirements for CipherBox. Tech demonstrator - not commercial. See TECHNICAL_ARCHITECTURE.md for implementation details, API_SPECIFICATION.md for backend contract, DATA_FLOWS.md for sequences.
 ---
@@ -11,7 +11,7 @@ ai_context: Product requirements for CipherBox. Tech demonstrator - not commerci
 **Type:** Technology Demonstrator  
 **Status:** Specification Document  
 **Created:** January 14, 2026  
-**Last Updated:** January 16, 2026  
+**Last Updated:** January 17, 2026  
 
 ---
 
@@ -186,6 +186,17 @@ Core pillars:
 | Max folder depth | 20 levels | Traversal performance |
 | Sync latency | ~30 seconds | IPNS polling interval |
 
+### 4.4 PoC Validation Harness
+
+To de-risk the key hierarchy, IPNS publishing, and file system flows, the project includes a **single-user console PoC harness** that runs end-to-end against live IPFS/IPNS (no Web3Auth and no backend). The PoC:
+
+- Loads `privateKey` from a local `.env` file (client-only, never logged)
+- Persists `rootFolderKey` and `rootIpnsName` to disk during the run
+- Executes a full flow per run: create folders → upload → modify → rename → move → delete
+- Verifies each step by resolving IPNS and decrypting metadata/content
+- Measures IPNS propagation delay per publish
+- Tears down by unpinning **all** created CIDs (files + folder metadata) and removing generated IPNS keys
+
 ---
 
 ## 5. Success Criteria
@@ -214,6 +225,15 @@ See [TECHNICAL_ARCHITECTURE.md](./TECHNICAL_ARCHITECTURE.md#acceptance-criteria)
 | P4 | IPNS resolution (cached) | <200ms | Integration test |
 | P5 | FUSE mount startup | <3s | Manual test |
 
+### 5.4 PoC Validation Criteria
+
+| ID | Criterion | Validation |
+|----|-----------|------------|
+| C1 | PoC completes full flow without errors | Single-run harness test |
+| C2 | IPNS resolves to expected metadata after each publish | Poll-until-resolved check |
+| C3 | File decrypts correctly after upload, update, rename, move | Round-trip checks |
+| C4 | Teardown unpins all created CIDs | Pin audit in harness logs |
+
 ---
 
 ## 6. Roadmap

diff --git a/Documentation/TECHNICAL_ARCHITECTURE.md b/Documentation/TECHNICAL_ARCHITECTURE.md
@@ -1,6 +1,6 @@
 ---
-version: 1.7.0
-last_updated: 2026-01-16
+version: 1.8.0
+last_updated: 2026-01-17
 status: Active
 ai_context: Technical architecture for CipherBox. Contains encryption specs, key hierarchy, auth flows, and system design. For API details see API_SPECIFICATION.md, for sequences see DATA_FLOWS.md.
 ---
@@ -9,7 +9,7 @@ ai_context: Technical architecture for CipherBox. Contains encryption specs, key
 
 **Document Type:** Technical Specification  
 **Status:** Active  
-**Last Updated:** January 16, 2026  
+**Last Updated:** January 17, 2026  
 
 ---
 
@@ -374,6 +374,21 @@ File Keys (AES-256, one per file)
 4. Clear all cached folder keys
 5. Clear all tokens
 
+### 4.4 PoC Local Key Bootstrap (Console Harness)
+
+The console PoC bypasses Web3Auth and the backend. It uses a locally provided `privateKey` and persists only the minimum vault state to disk for the duration of the run.
+
+**PoC bootstrap rules:**
+- Load `privateKey` from `.env` (client-only, never logged)
+- Derive `publicKey` locally (secp256k1)
+- Generate `rootFolderKey` and store on disk for the run
+- Generate per-folder IPNS keys on the local IPFS node
+- Store the IPNS key **name** encrypted with ECIES in folder metadata (stand-in for `ipnsPrivateKey`), while the actual IPNS private key remains in the local IPFS keystore
+
+**Teardown:**
+- Unpin all file and folder metadata CIDs created during the run
+- Remove any IPNS keys created in the local IPFS keystore
+
 ---
 
 ## 5. IPFS & IPNS Architecture

diff --git a/README.md b/README.md
@@ -25,6 +25,8 @@
 - **React web UI** + **FUSE desktop mount** (macOS v1)
 - **Automatic multi-device sync** via IPNS polling
 
+**PoC Focus:** A single-user, console-based harness validates IPFS/IPNS flows end-to-end without Web3Auth or backend dependencies. Each run performs a full file/folder flow, verifies correctness via IPNS resolution, measures propagation delay, and unpins all created CIDs during teardown.
+
 **Target:** Developers and technical users interested in cryptography, IPFS, and privacy-preserving architectures.
 
 ***

diff --git a/poc/.env.example b/poc/.env.example
@@ -0,0 +1,25 @@
+# Required
+ECDSA_PRIVATE_KEY=hex_without_0x
+
+# Optional: IPFS API endpoint
+IPFS_API_URL=http://127.0.0.1:5001
+
+# Optional: IPFS gateway URL for reads (if needed)
+IPFS_GATEWAY_URL=http://127.0.0.1:8080
+
+# Optional: Pinata API keys (used for pin/unpin in addition to IPFS node pinning)
+# Set PINATA_ENABLED=true to enable. Leave false to use local Kubo pinning only.
+PINATA_ENABLED=false
+PINATA_API_KEY=
+PINATA_API_SECRET=
+
+# Optional: State directory for local persistence
+POC_STATE_DIR=./state
+
+# Optional: IPNS polling settings (ms)
+IPNS_POLL_INTERVAL_MS=1500
+IPNS_POLL_TIMEOUT_MS=120000
+
+# Optional: stress test a folder with many children (metadata size check)
+STRESS_CHILDREN_COUNT=0
+STRESS_CHILD_TYPE=file
diff --git a/poc/README.md b/poc/README.md
@@ -0,0 +1,36 @@
+# CipherBox Console PoC Harness
+
+Single-user, online test harness that exercises CipherBox file system flows directly on IPFS/IPNS (no Web3Auth, no backend). Each run initializes a new vault, executes a full flow, verifies correctness via IPNS/IPFS, then unpins all created CIDs during teardown.
+
+## Requirements
+
+- Node.js 20+
+- Local IPFS daemon (Kubo) with the HTTP API enabled
+- Optional: Pinata API keys for remote pin/unpin
+
+## Setup
+
+1. Copy the env template:
+   - `cp .env.example .env`
+2. Set `ECDSA_PRIVATE_KEY` to a 32-byte hex string (no `0x`).
+3. Ensure your IPFS API is reachable at `IPFS_API_URL`.
+
+## Run
+
+- `npm install`
+- `npm start`
+
+## What the harness does
+
+- Initializes a new vault (root folder key + root IPNS key)
+- Creates folders
+- Uploads a file, downloads and verifies content
+- Modifies, renames, moves, and deletes a file
+- Publishes all metadata to IPFS and IPNS
+- Measures IPNS propagation delay per publish
+- Teardown: unpins all file and metadata CIDs, removes IPNS keys
+
+## Notes
+
+- IPNS resolution is eventually consistent; the harness polls until the expected CID appears.
+- Unpinning removes pins from configured services but does not guarantee deletion from the public IPFS network.
diff --git a/poc/package.json b/poc/package.json
@@ -0,0 +1,24 @@
+{
+  "name": "cipherbox-poc",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "gen:key": "tsx scripts/gen-private-key.ts",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts"
+  },
+  "dependencies": {
+    "@noble/secp256k1": "^2.1.0",
+    "dotenv": "^16.4.5",
+    "eciesjs": "^0.4.7",
+    "ipfs-http-client": "^60.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.30",
+    "eslint": "^8.57.0",
+    "tsx": "^4.7.1",
+    "typescript": "^5.4.2"
+  }
+}
diff --git a/poc/scripts/gen-private-key.ts b/poc/scripts/gen-private-key.ts
@@ -0,0 +1,4 @@
+import { randomBytes } from "crypto";
+
+const key = randomBytes(32).toString("hex");
+console.log(`${key}\n`);