feat(sdk): self-bootstrap folder tree from root IPNS key

[FSM1]

Summary

The SDK client owned folder state (folderTree) but its config carried only rootIpnsName + rootFolderKey, not the root IPNS signing key. So the client could not resolve/publish root or lazy-load folders on its own — the web app had to pre-seed folderTree via ensureFolderRegistered before every folderTree-dependent method. That asymmetry is the root cause of the whole "Folder not loaded" class.

Most visibly: restoring a recycle-bin item after a reload threw Target folder not loaded when the item's subfolder parent was never navigated to that session (only root is re-seeded on reload). Pre-existing since #296; recycle-bin.spec.ts misses it because it uploads in-session and never reloads.

This PR gives the client the root IPNS keypair so it can self-bootstrap: walk the folder tree from root, unwrapping each subfolder's keys with the vault keypair, until the target is loaded.

Changes

• CipherBoxClientConfig.rootIpnsKeypair (optional, Ed25519) — defensively copied in the constructor and zeroed in destroy(), mirroring vaultKeypair/rootFolderKey.
• CipherBoxClient.ensureFolderLoaded(target) — when a root keypair is configured, DFS-walks from root (early exit), ECIES-unwrapping each subfolder's folderKeyEncrypted/ipnsPrivateKeyEncrypted and loading metadata until the target is registered. Caches the whole path; a corrupt sibling entry is skipped, not fatal. Returns null before any crypto when no keypair is configured, preserving the prior Folder not loaded behavior.
• requireFolder(ipnsName, label) chokepoint — the 11 folderTree-dependent mutations (create/rename/move/delete/upload(s)/replace/version ops/share) and the 2 bin wrappers (deleteToBin/restoreFromBin) all route through one get-or-self-load-or-throw helper, so a new method can't silently drop the self-heal fallback (the #494 drift class).
• Web — initSdkClient now passes vaultStore.rootIpnsKeypair (already guaranteed non-null by the existing guard).

Security

No new crypto primitives — only ECIES-unwraps existing keys and loads metadata via the unchanged sdk-core AES-256-GCM path. No key logging, no new storage, no server transmission. Reviewed (independent security-reviewer pass + CodeRabbit, both clean): no key transposition, correct ECIES recipient key, cycles bounded by a visited set, errors leak no key bytes, destroy() zeroization consistent with the existing pattern. The root IPNS key already lived client-side in vaultStore; this only hands a defensive copy to the SDK, which already holds equivalent key material.

Testing

• SDK unit — new ensure-folder-loaded.test.ts (7 cases): already-loaded no-op, no-keypair null, root-as-target, deep walk + path caching, unreachable target, skip-no-IPNS-record, skip-corrupt-sibling. Full SDK suite green (179 passing, 3 live-API skipped under CI).
• Web E2E — new bin-restore-after-reload.spec.ts: restore a subfolder item after reload without navigating into the subfolder (the scenario recycle-bin.spec.ts misses). Note: web-e2e runs only on main-push.
• pnpm typecheck clean (full chain + web tsc -b); ESLint clean.

Follow-ups (not in this PR)

• The web ensureFolderRegistered calls (~16 sites) are now redundant no-ops (the SDK self-heals) and the web useFolderNavigation unwrap path duplicates the SDK's — both can be deleted once self-heal proves out.
• A per-target negative cache, only if upstream adds retry loops on unresolvable targets.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • SDK now supports self-bootstrapping folder metadata using a configured root IPNS keypair.
  • Folder and file operations can recover and work after page reloads without requiring pre-seeded folder state.
  • SDK automatically lazy-loads the folder tree during operations when needed.

• Tests

  • Added regression test for recycle bin file restore after page reload.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4737e9a1-4bfd-43c3-9257-b896158c78fb

📥 Commits

Reviewing files that changed from the base of the PR and between 898fbdc and 040c015.

📒 Files selected for processing (8)

• .planning/STATE.md
• .planning/todos/completed/2026-06-16-sdk-client-self-bootstrap-folder-tree-from-root-ipns-key.md
• apps/web/src/hooks/useAuth.ts
• packages/sdk/src/__tests__/ensure-folder-loaded.test.ts
• packages/sdk/src/client.ts
• packages/sdk/src/types.ts
• release-please-config.json
• tests/web-e2e/tests/bin-restore-after-reload.spec.ts

---

Walkthrough

CipherBoxClientConfig gains an optional rootIpnsKeypair field enabling CipherBoxClient to DFS-walk the folder hierarchy via ensureFolderLoaded, unwrapping subfolder keys until the target is found. All folder-dependent operations now go through a requireFolder chokepoint, useAuth wires the keypair in, and an E2E regression spec covers the bin-restore-after-reload path.

Changes

SDK Client Self-Bootstrap

Layer / File(s)	Summary
CipherBoxClientConfig contract packages/sdk/src/types.ts	Adds optional rootIpnsKeypair?: { publicKey: Uint8Array; privateKey: Uint8Array } to CipherBoxClientConfig with JSDoc describing lazy self-bootstrap semantics and backwards compatibility.
Client state, constructor, and destroy packages/sdk/src/client.ts	Imports unwrapKey/hexToBytes, adds internal internalRootIpnsKeypair field, constructor copies the optional keypair defensively, and destroy() zeroizes both key buffers when present.
ensureFolderLoaded DFS walk and requireFolder packages/sdk/src/client.ts	ensureFolderLoaded performs DFS from root IPNS, unwrapping subfolder keys and loading metadata into folderTree until the target is reached or determined unreachable, with partial cache preservation and corrupt-entry skipping. requireFolder wraps it and throws a labeled error on failure.
requireFolder callsite updates packages/sdk/src/client.ts	All folder-dependent operations (createFolder, renameItem, moveItem, deleteItem, uploadFile, uploadFiles, replaceFile, restoreFileVersion, deleteFileVersion, deleteToBin, restoreFromBin, shareFolder) switch from direct folderTree.get() calls to requireFolder.
useAuth wiring apps/web/src/hooks/useAuth.ts	Passes vaultState.rootIpnsKeypair into initSdkClient alongside rootIpnsName with comments on self-bootstrap behavior.
Unit tests for ensureFolderLoaded packages/sdk/src/__tests__/ensure-folder-loaded.test.ts	Vitest suite with mocked loadFolderMetadata and unwrapKey covering cache hits, missing keypair, root bootstrap, deep DFS caching, unreachable targets, null-metadata subtree skipping, and unwrap-failure isolation.
E2E regression, planning, and release tests/web-e2e/tests/bin-restore-after-reload.spec.ts, .planning/STATE.md, release-please-config.json	Playwright serial spec reproduces the bin-restore-after-reload failure and verifies the self-bootstrap fix. Planning doc marks the todo completed. Release versions bumped to 0.43.0 (apps/web) and 0.35.0 (packages/sdk).

Sequence Diagram(s)

sequenceDiagram
  participant useAuth
  participant CipherBoxClient
  participant ensureFolderLoaded
  participant loadFolderMetadata
  participant unwrapKey

  useAuth->>CipherBoxClient: new CipherBoxClient({ rootIpnsKeypair, ... })
  note over CipherBoxClient: stores internalRootIpnsKeypair

  CipherBoxClient->>ensureFolderLoaded: restoreFromBin(targetFolderIpnsName)
  ensureFolderLoaded->>CipherBoxClient: folderTree.get(target) → miss
  ensureFolderLoaded->>loadFolderMetadata: rootIpnsName
  loadFolderMetadata-->>ensureFolderLoaded: root FolderMetadata (children list)
  loop each subfolder
    ensureFolderLoaded->>unwrapKey: encryptedKey, vaultPrivateKey
    unwrapKey-->>ensureFolderLoaded: folderKey
    ensureFolderLoaded->>loadFolderMetadata: subfolder.ipnsName
    loadFolderMetadata-->>ensureFolderLoaded: FolderMetadata
    ensureFolderLoaded->>CipherBoxClient: folderTree.register(subfolder)
  end
  ensureFolderLoaded-->>CipherBoxClient: FolderState (target found)
  CipherBoxClient-->>useAuth: restore operation proceeds

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• FSM1/cipher-box#496: Addresses the same "Folder not loaded" failure mode by patching web hooks to call ensureFolderRegistered before file/version operations, where this PR instead adds SDK-level self-bootstrap via ensureFolderLoaded/requireFolder.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(sdk): self-bootstrap folder tree from root IPNS key' accurately and concisely describes the main change: enabling the SDK to self-bootstrap the folder tree using the root IPNS keypair, eliminating the need for pre-seeding via external APIs.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/sdk-client-self-bootstrap-folder-tree

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Release Preview

Package	Bump	Label	Source
sdk	minor	release:sdk:feat	Direct (feat commit)
web	minor	release:web:feat	Direct (feat commit)

[codecov]

Codecov Report

❌ Patch coverage is 89.87342% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.80%. Comparing base (88c12ac) to head (040c015).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/sdk/src/client.ts	89.87%	7 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #498      +/-   ##
==========================================
+ Coverage   63.59%   63.80%   +0.21%     
==========================================
  Files         140      140              
  Lines       10577    10633      +56     
  Branches     1157     1175      +18     
==========================================
+ Hits         6726     6784      +58     
+ Misses       3612     3610       -2     
  Partials      239      239              

Flag	Coverage Δ
api	85.29% <89.87%> (+0.16%)	⬆️
api-client	85.29% <89.87%> (+0.16%)	⬆️
core	85.29% <89.87%> (+0.16%)	⬆️
crypto	85.29% <89.87%> (+0.16%)	⬆️
sdk	85.29% <89.87%> (+0.16%)	⬆️
sdk-core	85.29% <89.87%> (+0.16%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/sdk/src/client.ts	83.57% <89.87%> (+0.93%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.