feat: Phase 9 — Tauri desktop client with FUSE mount

.coderabbit.yaml

@@ -60,6 +60,22 @@ reviews:
         Focus on test coverage, edge cases, and test quality.
         Ensure tests are meaningful and not just for coverage metrics.
 
+    - path: '**/*.md'
+      instructions: |
+        Markdown files are documentation and learnings. Use them for context
+        when reviewing related code, but do NOT flag markdown formatting,
+        linting, or style issues (these are handled by markdownlint).
+
+    - path: '.planning/**'
+      instructions: |
+        Planning documents provide context for the current development phase.
+        Use for understanding intent, but do not review for style or formatting.
+
+    - path: '.learnings/**'
+      instructions: |
+        Agent learning documents capture development insights. Use for context
+        when reviewing related code, but do not review for style or formatting.
+
   # Paths to ignore in reviews
   path_filters:
     - '!**/node_modules/**'
@@ -68,13 +84,10 @@ reviews:
     - '!**/.next/**'
     - '!**/coverage/**'
     - '!**/pnpm-lock.yaml'
-    - '!**/*.lock'
     - '!**/generated/**'
     - '!.claude/agents/**'
     - '!.claude/commands/**'
     - '!.claude/get-shit-done/**'
-    - '!.learnings/**'
-    - '!.planning/**'
 
 chat:
   # Enable chat interactions in PR comments

.github/workflows/ci.yml

@@ -180,5 +180,5 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Build all packages
-        run: pnpm build
+      - name: Build packages (excluding desktop)
+        run: pnpm --filter @cipherbox/crypto --filter @cipherbox/api --filter @cipherbox/web build

.github/workflows/e2e.yml

@@ -77,8 +77,8 @@ jobs:
           npm install
           npm run build
 
-      - name: Build packages
-        run: pnpm build
+      - name: Build packages (excluding desktop)
+        run: pnpm --filter @cipherbox/crypto --filter @cipherbox/api --filter @cipherbox/web build
         env:
           VITE_WEB3AUTH_CLIENT_ID: ${{ secrets.VITE_WEB3AUTH_CLIENT_ID }}
           VITE_API_URL: http://localhost:3000

.learnings/2026-02-07-rust-typescript-data-model-fidelity.md

@@ -0,0 +1,28 @@
+# Rust-TypeScript Data Model Fidelity in Cross-Language Ports
+
+**Date:** 2026-02-07
+
+## Original Prompt
+
+> /gsd:plan-phase (Phase 9: Desktop Client — Tauri app with FUSE mount, porting existing TypeScript crypto/data models to Rust)
+
+## What I Learned
+
+- **Every field matters when porting TypeScript types to Rust structs.** The plan checker caught that `FolderEntry` was missing `ipnsPrivateKeyEncrypted` and `VaultResponse` was missing `encryptedRootIpnsPrivateKey` + `rootIpnsPublicKey`. These aren't cosmetic omissions — without them, IPNS record signing (required for every write operation) would silently fail at runtime.
+- **Encrypted key fields are the most dangerous to miss.** They don't show up in happy-path read operations (you can browse files fine), but every mutation path breaks. Easy to miss during planning because reads work without them.
+- **Serde `rename_all = "camelCase"` is essential** when Rust structs deserialize from TypeScript-generated JSON. The TypeScript types use camelCase (`ipnsPrivateKeyEncrypted`), Rust convention is snake_case (`ipns_private_key_encrypted`). Without the Serde attribute, deserialization silently drops fields.
+- **Desktop auth can't use HTTP-only cookies.** Tauri apps run on `tauri://localhost` which doesn't participate in the browser cookie jar. The API needs a body-based refresh token path for desktop clients.
+- **System browser redirect is wrong for key extraction.** Passing private keys as URL parameters (deep link callback) is a security risk — URLs appear in browser history, process lists, and logs. Revised to run Web3Auth inside the Tauri webview with IPC key transfer instead.
+
+## What Would Have Helped
+
+- A checklist of ALL fields from the TypeScript types before writing Rust equivalents (the planner initially just grabbed the "obvious" fields)
+- Knowing upfront that fuser's macOS support is "untested" — this is the highest-risk integration point and should be proven with a PoC before any detailed planning
+- Understanding that FUSE-T has specific limitations (no file locking, readdir must return all entries in one pass, timestamps can't be set independently) — these constrain the FUSE implementation design
+
+## Key Files
+
+- `packages/crypto/src/folder/types.ts` — TypeScript FolderEntry/FileEntry types (source of truth for Rust ports)
+- `apps/api/src/vault/vault.service.ts` — VaultResponse shape (what the API actually returns)
+- `packages/crypto/src/ipns/` — IPNS record creation (must be replicated exactly in Rust)
+- `.planning/phases/09-desktop-client/09-RESEARCH.md` — FUSE-T limitations and Tauri patterns

.learnings/2026-02-08-desktop-testing-strategy.md

@@ -0,0 +1,59 @@
+# Desktop Client Testing Strategy
+
+**Date:** 2026-02-08
+
+## Original Prompt
+
+> Phase 9 UAT revealed that every test required manual human interaction because Web3Auth login cannot be automated. This makes CI/CD and agent-driven testing impossible.
+
+## What I Learned
+
+### The Web3Auth Testing Wall
+
+- Web3Auth login requires a real browser interaction (Google OAuth, email OTP, etc.). There is no headless/programmatic bypass in the SDK.
+- Every UAT test required a human to: click Login in tray, complete Web3Auth flow, wait for FUSE mount, then test the actual feature.
+- This made iterative debugging painfully slow — each fix required a full rebuild + manual login cycle.
+- Agent-assisted development (Claude) could diagnose issues from logs and write fixes, but could never verify them independently.
+
+### Proposed Solution: Auth Bypass for Development
+
+A `--dev-key <hex-private-key>` CLI argument that bypasses Web3Auth entirely:
+
+1. Accept a secp256k1 private key via CLI arg or environment variable (`CIPHERBOX_DEV_KEY`)
+2. Derive the public key from it
+3. Call the API's `/auth/login` endpoint directly (the API already accepts `{ publicKey, loginType: "desktop" }`)
+4. Store the resulting JWT and proceed to FUSE mount
+
+This enables:
+
+- **Automated testing:** Playwright/script can launch app with `--dev-key`, test FUSE operations, quit
+- **Agent-driven UAT:** Claude can launch the app, verify FUSE behavior via `ls`/`cat`/`echo`, and iterate without human intervention
+- **CI integration:** Spin up API + app with test key, run filesystem operation tests
+- **Faster debugging:** Skip the 15-second Web3Auth flow on every iteration
+
+### Implementation Notes
+
+- Gate behind `#[cfg(debug_assertions)]` or a `dev` feature flag — never ship in release builds
+- The test account's private key can live in `tests/e2e/.env` alongside existing test credentials
+- Key derivation: `secp256k1::SecretKey::from_slice(&hex::decode(key))` -> compressed public key -> `/auth/login`
+- After auth, the flow joins the normal path: fetch vault metadata, mount FUSE, start sync
+
+### What Else Would Help
+
+- **FUSE unit tests:** Test the `CipherBoxFS` struct directly without mounting. Mock the API client, call `lookup()`, `readdir()`, `read()` etc. as method calls. This tests all the NFS-sensitive logic (inode stability, cache behavior, platform file filtering) without needing a real mount.
+- **Integration test script:** A shell script that exercises FUSE operations after mount: `ls`, `cat`, `echo >`, `mkdir`, `mv`, `rm`, and verifies results. Combined with `--dev-key`, this gives end-to-end coverage.
+- **Snapshot testing for inode table:** Serialize the inode table state after `populate_folder()`, compare against known-good snapshots. Catches inode stability regressions.
+
+### Testing Priorities for Linux/Windows Ports
+
+1. **Start with the auth bypass** — get FUSE mounting testable without UI interaction
+2. **Port the FUSE unit tests first** — the inode table and cache logic is shared
+3. **Platform-specific tests:** Linux FUSE has different behavior (multithreaded, no NFS translation). Windows WinFSP has its own quirks. Each needs platform-specific test coverage.
+4. **The channel-based prefetch pattern** should have its own test — verify that content arrives via channel and cache is populated correctly
+
+## Key Files
+
+- `apps/desktop/src-tauri/src/main.rs` — CLI argument parsing (add `--dev-key` here)
+- `apps/desktop/src-tauri/src/commands.rs` — `handle_auth_complete` (the flow to join after bypass auth)
+- `apps/desktop/src-tauri/src/api/auth.rs` — API auth calls
+- `tests/e2e/.env` — Test credentials

.learnings/2026-02-08-fuse-t-nfs-macos.md

@@ -0,0 +1,87 @@
+# FUSE-T NFS on macOS — Hard-Won Lessons
+
+**Date:** 2026-02-08
+
+## Original Prompt
+
+> Phase 9: Build a Tauri desktop client with FUSE mount for transparent file access to CipherBox vault.
+
+We chose FUSE-T (userspace NFS) over macFUSE (kernel extension) because Apple deprecated kexts. This introduced a whole class of NFS-specific issues that don't exist with kernel FUSE.
+
+## What I Learned
+
+### The Single-Thread Rule
+
+- **ALL FUSE-T NFS callbacks run on a single thread.** Any blocking call — even 500ms — stalls the entire filesystem and causes macOS NFS client to report "server connection interrupted."
+- `read()` is the most dangerous callback. IPFS fetches take 1-3s. A naive `block_on(fetch)` inside `read()` will kill the mount within seconds.
+- **Solution:** Channel-based prefetch architecture. `open()` fires a background IPFS fetch via `content_tx`. `read()` drains `content_rx` into cache non-blocking. On cache miss, return `EIO` — NFS retries automatically.
+- This pattern applies to ANY async I/O in FUSE callbacks: never block, always defer to background tasks and drain results opportunistically.
+
+### Inode Stability is Sacred
+
+- NFS clients cache inode numbers aggressively. If `populate_folder()` allocates new ino numbers for children that already exist (same name, same content), NFS returns "stale file handle" errors and Finder disconnects.
+- **Solution:** `populate_folder()` must check `find_child(parent_ino, &name)` and reuse the existing ino. Only allocate new inos for genuinely new children.
+- Also preserve the `children` list and `children_loaded` state of existing folder inodes — don't reset them on refresh.
+
+### READDIR Cache is Permanent (Practically)
+
+- macOS NFS client caches READDIR results and does NOT re-fetch even when the directory's mtime changes via GETATTR. There is no server-side mechanism to invalidate this cache.
+- `acdirmin`/`acdirmax` mount options could help, but FUSE-T doesn't expose them from the server side.
+- **Consequence:** The FIRST READDIR response for any directory must be correct. There are no second chances.
+- **Solution:** Pre-populate all immediate subfolders during mount (before the FUSE event loop starts), so the first READDIR returns real children, not empty results.
+- Files created via CLI (`echo > ~/CipherBox/folder/file.txt`) will appear in `ls` but NOT in Finder until a new Finder window is opened. This is a known limitation of NFS on macOS — no FSEvents on NFS mounts.
+
+### READDIR Deduplication
+
+- NFS calls `readdir` twice per directory listing: once at offset=0 and once at offset=N (continuation). Both calls trigger the same background refresh logic.
+- **Solution:** Only fire background refresh on `offset == 0`. The offset=N call will use whatever data is already cached.
+
+### Directory mtime Matters
+
+- NFS uses directory mtime to decide if READDIR cache is valid (even though it doesn't always re-fetch).
+- `populate_folder()` must detect when children actually changed and bump parent `mtime`+`ctime` to `SystemTime::now()`.
+- Similarly, mutation callbacks (create, mkdir, unlink, rmdir, rename) must bump parent mtime.
+- Use `DIR_TTL=0` for directories (always re-validate via GETATTR) and `FILE_TTL=60s` for files.
+
+### Lookup Consistency
+
+- NFS client does LOOKUP for every entry returned by READDIR, including "." and "..". Returning ENOENT for ".." causes an immediate NFS disconnect.
+- **Solution:** Handle "." and ".." explicitly in `lookup()`, returning the current and parent inode respectively.
+
+### FUSE-T Rename Truncation
+
+- FUSE-T truncates the filename in rename callbacks by exactly 8 bytes. A file named `document.txt` might arrive as `docu` in the rename callback's `newname` parameter.
+- **Solution:** Suffix-match fallback — if exact match fails, find the child whose name ends with the (truncated) new name.
+
+### Platform Special Files
+
+- macOS generates `.DS_Store`, `.Spotlight-V100`, `.Trashes`, `.fseventsd`, `._*` resource forks, `.localized`, `Icon\r` on every directory access.
+- These MUST be filtered: ENOENT in lookup, filtered from readdir, EACCES on create/mkdir, excluded from rename.
+- Centralize in an `is_platform_special()` helper — the list is long and you'll need it everywhere.
+
+### Mutation Cooldown
+
+- Background metadata refreshes (IPNS resolve) can overwrite local mutations before they propagate through IPNS (which is eventually consistent, ~30s).
+- **Solution:** Track `mutated_folders` with timestamps. Skip background refreshes for 30 seconds after any local mutation to that folder.
+
+## What Would Have Helped
+
+- A document explaining FUSE-T's NFS translation layer behavior — none exists. We learned everything through trial and error.
+- Understanding upfront that FUSE-T != kernel FUSE. Every assumption about FUSE behavior needs re-verification under NFS semantics.
+- A test harness that could exercise FUSE callbacks without requiring a full mount (unit-test the filesystem struct directly).
+- Knowing that macOS NFS READDIR caching is essentially permanent would have led us to eager pre-population from the start.
+
+## Key Files
+
+- `apps/desktop/src-tauri/src/fuse/mod.rs` — CipherBoxFS struct, mount/unmount, drain helpers, pre-population
+- `apps/desktop/src-tauri/src/fuse/operations.rs` — All FUSE callbacks (lookup, getattr, readdir, read, write, create, mkdir, rename, unlink, rmdir)
+- `apps/desktop/src-tauri/src/fuse/inode.rs` — Inode table, populate_folder with ino reuse
+- `apps/desktop/src-tauri/src/fuse/cache.rs` — Metadata and content caches with TTL
+- `apps/desktop/src-tauri/.cargo/config.toml` — FUSE-T pkg-config override
+- `apps/desktop/src-tauri/pkg-config/fuse.pc` — Custom fuse.pc pointing to FUSE-T headers
+
+## Implications for Linux/Windows
+
+- **Linux:** Can use kernel FUSE (libfuse) directly. Most NFS-specific issues disappear. Inode stability still matters. No READDIR caching issue. No rename truncation. No single-thread constraint (FUSE supports multithreaded mode). The channel-based prefetch architecture is still beneficial for performance.
+- **Windows:** WinFSP or Dokan. Different callback model entirely. The async/non-blocking architecture translates well. Platform special files will be different (desktop.ini, Thumbs.db, etc.). Inode concept replaced by file IDs — same stability requirement.
+- **Shared code:** The `InodeTable`, `MetadataCache`, `ContentCache`, and the channel-based prefetch pattern are platform-agnostic. The FUSE callback implementations will need per-platform variants, but the data structures and async patterns can be reused.

.learnings/2026-02-08-macos-system-integration.md

@@ -0,0 +1,39 @@
+# macOS System Integration Gotchas
+
+**Date:** 2026-02-08
+
+## Original Prompt
+
+> Phase 9 UAT: Desktop client with FUSE mount, tray icon, keychain persistence.
+
+## What I Learned
+
+### Keychain (keyring crate)
+
+- `keyring::set_password()` fails with "already exists" error if the item already exists in macOS Keychain. The crate doesn't upsert.
+- **Workaround:** Always `delete_credential()` before `set_password()`. But this still fails intermittently — possibly a timing issue with Keychain's internal locking or access group conflicts.
+- The intermittent nature suggests a race condition in Keychain Services itself, or possibly Keychain Access app holding a read lock.
+
+### Force Unmount
+
+- `umount(path)` fails with "Resource busy" when Finder has open handles on the mount point (common — Finder reads `.DS_Store` and metadata eagerly).
+- `diskutil unmount path` also fails in this case.
+- `diskutil unmount force path` works reliably. This is the equivalent of `umount -f` but goes through DiskArbitration framework.
+- **Always** use force unmount as the fallback, not just `diskutil unmount`.
+
+### Stale Mount Point
+
+- After a crash or ungraceful exit, `~/CipherBox` may contain `.DS_Store`, `.metadata_never_index`, and potentially cached Finder metadata.
+- FUSE-T mount on a non-empty directory works but can behave unexpectedly.
+- **Solution:** On startup, if the mount directory exists, remove all its contents before mounting.
+
+### Spotlight Indexing
+
+- Without mitigation, Spotlight will try to index the FUSE mount, generating constant read traffic.
+- Creating `.metadata_never_index` in the mount root prevents this.
+- Must be created AFTER cleaning stale files but BEFORE mounting FUSE.
+
+## Key Files
+
+- `apps/desktop/src-tauri/src/fuse/mod.rs` — Mount point cleanup, Spotlight suppression, force unmount
+- `apps/desktop/src-tauri/src/api/auth.rs` — Keychain token storage with delete-before-set

.learnings/2026-02-08-replace-esm-only-ipns-with-inline-protobuf.md

@@ -0,0 +1,28 @@
+# Replace ESM-only `ipns` package with inline protobuf decoder
+
+**Date:** 2026-02-08
+
+## Original Prompt
+
+> Implement the following plan: Replace `ipns` package in API with inline protobuf decoder. The `ipns` npm package (v10.1.3) is ESM-only, which doesn't play nicely with NestJS's CommonJS compilation. This forced a dynamic `await import('ipns')` hack that broke Jest mocking, which led to a cascade of test/behavior changes that ultimately broke the desktop FUSE client (502 errors hanging the NFS thread).
+
+## What I Learned
+
+- **ESM-only packages in CJS NestJS are poison**: The `ipns` package forced a dynamic `import()` hack, which broke Jest mocking (can't mock dynamic imports easily), which forced a `moduleNameMapper` workaround, which created a fragile test mock that masked real behavior differences.
+- **Only extract what you need from protobuf**: The API used ONE function (`unmarshalIPNSRecord`) and read TWO fields (`value` string, `sequence` bigint). That's fields 1 and 5 in the protobuf wire format. ~65 lines of inline varint/length-delimited parsing replaced an entire dependency tree.
+- **Protobuf wire format is simple for read-only**: Varint tags encode `(field_number << 3) | wire_type`. Wire type 0 = varint, 2 = length-delimited. Skip everything else. No schema compilation needed.
+- **`resolveRecord` re-throw behavior was the real FUSE killer**: The old code would re-throw `BAD_GATEWAY` when DB cache was empty. The FUSE NFS client would block on this 502, stalling the single NFS thread and disconnecting Finder. Returning `null` (→ 404) is gracefully handled.
+- **Test expectations must match behavioral changes**: When changing from "throw on failure" to "return null on failure", 7 tests needed updating. The plan only anticipated 2 (the ones already modified in the working tree). Always count ALL tests that assert `rejects.toThrow` for the changed code path.
+
+## What Would Have Helped
+
+- The plan's test change count (2 tests) was based on the already-modified working tree, not the full set of tests affected by the behavioral change. Should have grepped for `rejects.toThrow` in the resolve tests before starting.
+- Understanding that `parseIpnsRecordBytes` throws `HttpException(BAD_GATEWAY)` which IS caught by `resolveRecord`'s BAD_GATEWAY handler — so parse errors also fall through to DB cache now.
+
+## Key Files
+
+- `apps/api/src/ipns/ipns-record-parser.ts` — inline protobuf decoder (new)
+- `apps/api/src/ipns/ipns.service.ts` — uses inline parser, no more dynamic import
+- `apps/api/src/ipns/ipns.service.spec.ts` — 44 tests, 7 updated for null-return behavior
+- `apps/api/package.json` — `ipns` removed from dependencies
+- `apps/api/jest.config.js` — `ipns` moduleNameMapper removed