FSM1 · FSM1 · Jan 18, 2026 · Jan 18, 2026 · Jan 18, 2026 · Jan 18, 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.8.0
+**Current Version:** 1.9.0
 
 ### Version Bump Rule
 
@@ -75,7 +75,7 @@ When generating code for CipherBox:
 ## Architecture Decisions
 
 - **Auth:** Web3Auth for key derivation, CipherBox backend for tokens
-- **Storage:** IPFS via Pinata for files, IPNS for metadata
+- **Storage:** IPFS via Pinata for files, IPNS for metadata (all relayed via CipherBox API)
 - **Encryption:** Client-side only, server is zero-knowledge
 - **Sync:** IPNS polling (30s interval), no push infrastructure
 - **Desktop:** FUSE mount for transparent file access

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -2,7 +2,7 @@
 
 ## Version Management
 
-**Current Documentation Version:** 1.8.0
+**Current Documentation Version:** 1.9.0
 
 ### Version Bump Rule
 
@@ -55,7 +55,7 @@ CipherBox uses a **mandatory two-phase auth flow** that must be understood befor
 ```
 User Auth → Web3Auth → ECDSA Private Key (client RAM only, never transmitted)
                     ├─ Used for ECIES decryption of all data keys
-                    ├─ Used for IPNS entry signing
+                    ├─ Used to decrypt IPNS signing keys (Ed25519)
                     └─ Destroyed on logout
 
 ECDSA Public Key (stored on server, identifies user)

diff --git a/00_START_HERE.md b/00_START_HERE.md
@@ -17,8 +17,8 @@ A **production-grade, comprehensive specification** for building CipherBox v1.0
 This is **not a preliminary design document**—it's a **complete blueprint** with:
 
 - ✅ **5 complete user journeys** (signup → auth → sync → export → recovery)
-- ✅ **18 API endpoints** fully specified
-- ✅ **8 database tables** with schema
+- ✅ **15 API endpoints** fully specified
+- ✅ **6 database tables** (users, refresh_tokens, auth_nonces, vaults, volume_audit, pinned_cids) with schema
 - ✅ **6 encryption algorithms** with implementation details
 - ✅ **100+ acceptance criteria**
 - ✅ **3 key derivation test vectors**
@@ -69,9 +69,9 @@ Layer 3: Folder metadata (AES-256-GCM per folder)
 
 Each folder has its own IPNS entry (enables v2+ sharing)
 
-### 4. **IPNS Polling Sync** (~30s)
+### 4. **IPFS/IPNS Relay + Polling Sync** (~30s)
 
-No push infrastructure (MVP appropriate, scalable)
+Signed IPNS records relayed by CipherBox API; no direct client publishing
 
 ### 5. **User-Held Keys** (Zero-Knowledge)
 

diff --git a/Documentation/API_SPECIFICATION.md b/Documentation/API_SPECIFICATION.md
@@ -1,5 +1,6 @@
-version: 1.7.0
-last_updated: 2026-01-16
+---
+version: 1.9.0
+last_updated: 2026-01-18
 status: Active
 ai_context: API specification for CipherBox backend. Contains all endpoints, request/response formats, database schema, and rate limits. For system design see TECHNICAL_ARCHITECTURE.md.
 ---
@@ -8,7 +9,7 @@ ai_context: API specification for CipherBox backend. Contains all endpoints, req
 
 **Document Type:** API Specification  
 **Status:** Active  
-**Last Updated:** January 16, 2026  
+**Last Updated:** January 18, 2026  
 **Base URL:** `https://api.cipherbox.io`
 
 ---
@@ -51,11 +52,12 @@ The CipherBox backend provides:
 - Vault management (encrypted key storage)
 - File upload to IPFS (via Pinata)
 - Storage quota tracking
+- IPFS/IPNS relay for encrypted metadata and signed IPNS records
 
 The backend **never** handles:
 - Plaintext files
 - Unencrypted keys
-- IPNS publishing (client-side only)
+- Client private keys or unsigned IPNS records
 
 ### 1.2 Authentication Flow
 
@@ -464,6 +466,118 @@ Authorization: Bearer <accessToken>
 
 ---
 
+### 3.4 IPFS/IPNS Relay Endpoints
+
+All relay endpoints require `Authorization: Bearer <accessToken>`.
+
+#### POST /ipfs/add
+
+Add encrypted metadata (or any encrypted content) to IPFS via backend relay.
+
+**Headers:**
+```
+Authorization: Bearer <accessToken>
+Content-Type: application/octet-stream
+```
+
+**Request Body:**
+Raw bytes (encrypted content)
+
+**Response (201):**
+```json
+{
+  "cid": "QmXxxx...",
+  "size": 2048
+}
+```
+
+**Errors:**
+- `400 Bad Request` - Invalid payload
+- `429 Too Many Requests` - Rate limited
+- `502 Bad Gateway` - IPFS relay failed
+
+---
+
+#### GET /ipfs/cat
+
+Fetch encrypted content by CID via backend relay.
+
+**Query:**
+```
+?cid=QmXxxx...
+```
+
+**Response (200):**
+```
+<raw bytes>
+```
+
+**Errors:**
+- `400 Bad Request` - Invalid CID
+- `404 Not Found` - CID not found
+- `429 Too Many Requests` - Rate limited
+- `502 Bad Gateway` - IPFS relay failed
+
+---
+
+#### GET /ipns/resolve
+
+Resolve IPNS name to current CID via backend relay.
+
+**Query:**
+```
+?ipnsName=k51qzi5uqu5dlvj55...
+```
+
+**Response (200):**
+```json
+{
+  "cid": "QmXxxx...",
+  "resolvedAt": "2026-01-18T12:00:00Z"
+}
+```
+
+**Errors:**
+- `400 Bad Request` - Invalid IPNS name
+- `404 Not Found` - IPNS name not found
+- `429 Too Many Requests` - Rate limited
+- `502 Bad Gateway` - IPNS relay failed
+
+---
+
+#### POST /ipns/publish
+
+Relay a client-signed IPNS record to the IPFS/IPNS network.
+
+**Request:**
+```json
+{
+  "ipnsName": "k51qzi5uqu5dlvj55...",
+  "ipnsRecord": "BASE64_ENCODED_SIGNED_RECORD",
+  "sequenceNumber": 42,
+  "ttlSeconds": 3600
+}
+```
+
+**Response (200):**
+```json
+{
+  "published": true,
+  "ipnsName": "k51qzi5uqu5dlvj55...",
+  "sequenceNumber": 42,
+  "publishedAt": "2026-01-18T12:00:00Z"
+}
+```
+
+**Errors:**
+- `400 Bad Request` - Invalid record or malformed request
+- `401 Unauthorized` - Invalid access token
+- `409 Conflict` - Sequence number too low
+- `429 Too Many Requests` - Rate limited
+- `502 Bad Gateway` - IPNS relay failed
+
+---
+
 ## 4. Database Schema
 
 ### 4.1 Users Table
@@ -594,6 +708,10 @@ CREATE INDEX idx_pinned_cids_user_id ON pinned_cids(user_id);
 | POST /vault/upload | 60 | per minute | Batch upload support |
 | GET /my-vault | 120 | per minute | Polling + normal access |
 | DELETE /user/account | 1 | per hour | Prevent accidental deletion |
+| POST /ipfs/add | 120 | per minute | Metadata relay |
+| GET /ipfs/cat | 300 | per minute | Encrypted content relay |
+| GET /ipns/resolve | 240 | per minute | Sync polling |
+| POST /ipns/publish | 120 | per minute | Signed-record relay |
 
 ### 5.2 Rate Limit Headers
 
@@ -651,6 +769,8 @@ All errors follow this format:
 | `FILE_TOO_LARGE` | 413 | File exceeds 100MB limit |
 | `RATE_LIMIT_EXCEEDED` | 429 | Too many requests |
 | `QUOTA_EXCEEDED` | 507 | Storage quota exceeded |
+| `IPFS_RELAY_FAILED` | 502 | IPFS relay failed |
+| `IPNS_RELAY_FAILED` | 502 | IPNS relay failed |
 | `INTERNAL_ERROR` | 500 | Unexpected server error |
 
 ---

diff --git a/Documentation/CLIENT_SPECIFICATION.md b/Documentation/CLIENT_SPECIFICATION.md
@@ -1,6 +1,6 @@
 ---
-version: 1.8.0
-last_updated: 2026-01-17
+version: 1.9.0
+last_updated: 2026-01-18
 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 17, 2026  
+**Last Updated:** January 18, 2026  
 
 ---
 
@@ -44,7 +44,7 @@ ai_context: Client application specifications for CipherBox. Contains Web UI and
 | Styling | Tailwind CSS |
 | State Management | React Context + Hooks |
 | Encryption | Web Crypto API |
-| IPFS Client | kubo-rpc-client |
+| IPFS Relay | CipherBox API (/ipfs/*, /ipns/*) |
 | Auth | @web3auth/modal |
 | HTTP Client | Axios |
 
@@ -272,10 +272,10 @@ interface AppState {
 | `getattr` | Return file attributes from metadata |
 | `open` | Fetch from IPFS, decrypt, return handle |
 | `read` | Return decrypted content from cache |
-| `write` | Encrypt, upload, update IPNS |
-| `create` | Generate keys, encrypt, upload, update IPNS |
+| `write` | Encrypt, upload, relay IPNS publish |
+| `create` | Generate keys, encrypt, upload, relay IPNS publish |
 | `unlink` | Unpin CID, update parent IPNS |
-| `mkdir` | Generate folder keys, create IPNS, update parent |
+| `mkdir` | Generate folder keys, create IPNS, relay publish |
 | `rmdir` | Unpin folder IPNS, update parent |
 | `rename` | Update metadata in source and destination |
 
@@ -331,7 +331,7 @@ class SyncDaemon {
   async poll() {
     try {
       // Resolve root IPNS
-      const currentCid = await ipfs.name.resolve(rootIpnsName);
+      const { cid: currentCid } = await api.get(`/ipns/resolve?ipnsName=${rootIpnsName}`);
 
       if (currentCid !== this.cachedRootCid) {
         // Changes detected
@@ -374,7 +374,7 @@ class SyncDaemon {
 | D1 | FUSE mount succeeds in <3s | Performance test |
 | D2 | File read latency <500ms (cached) | Benchmark |
 | D3 | File read latency <2s (uncached) | Benchmark |
-| D4 | File write triggers IPNS publish in <5s | Integration test |
+| D4 | File write triggers IPNS relay publish in <5s | Integration test |
 | D5 | Multi-platform builds work | CI/CD test |
 | D6 | No plaintext on disk (except temp decrypted reads) | Security audit |
 | D7 | Logout unmounts FUSE and clears keys | Manual test |
@@ -419,7 +419,7 @@ interface IpfsModule {
 
   // IPNS operations
   resolveIpns(name: string): Promise<string>; // Returns CID
-  publishIpns(cid: string, privateKey: Uint8Array): Promise<void>;
+  publishIpnsRecord(base64IpnsRecord: string, ipnsName: string, sequenceNumber: number, ttlSeconds: number): Promise<void>; // base64IpnsRecord is BASE64-encoded signed IPNS record
 }
 ```
 
@@ -438,7 +438,7 @@ interface VaultModule {
   createFolder(name: string, parentFolder: FolderNode): Promise<FolderEntry>;
 
   // IPNS publishing
-  publishFolderUpdate(folder: FolderNode): Promise<void>;
+  publishFolderUpdate(folder: FolderNode): Promise<void>; // sign locally, relay via /ipns/publish
 }
 ```
 
@@ -450,7 +450,7 @@ interface VaultModule {
 
 | Question | Context | Priority |
 |----------|---------|----------|
-| What does user see when IPFS gateway is unavailable? | Network errors | High |
+| What does user see when IPFS relay is unavailable? | Network errors | High |
 | How to handle IPNS publish failures? | Write operations | High |
 | What timeout thresholds for file operations? | Performance UX | Medium |
 | Should failed uploads be queued for retry? | Reliability | Medium |
@@ -500,12 +500,25 @@ interface VaultModule {
 | System notification permissions? | Desktop UX | Medium |
 | Auto-update mechanism? | Distribution | High |
 
+### 4.7 Desktop Client (FUSE Semantics)
+
+| Question | Context | Priority |
+|----------|---------|----------|
+| What is the write model (streaming vs temp-file commit)? | File IO correctness | High |
+| How are partial writes and truncates handled? | File IO correctness | High |
+| What is the atomic rename strategy for updates? | Consistency | High |
+| How are concurrent edits resolved across devices? | Conflict policy | Medium |
+| When is encrypted cache invalidated on IPNS updates? | Cache consistency | Medium |
+| What is the offline write queue behavior? | Reliability | Medium |
+
 ---
 
 ## 5. Console PoC Harness
 
 **Goal:** Provide a single-user, online test harness to validate IPFS/IPNS flows without Web3Auth or the backend.
 
+> ⚠️ **Warning:** The PoC publishes directly to IPFS/IPNS and is intentionally separate from the production relay model. Section 8 of DATA_FLOWS.md describes the PoC-only flow and should not be used as a reference for production client implementation.
+
 **Environment:** Node.js (TypeScript), local IPFS daemon, optional Pinata API keys for pin/unpin.
 
 **Behavior:**