Skip to content

feat(storage): filesystem StorageProvider - #7

Merged
deckyfx merged 2 commits into
mainfrom
feat/storage-fs
Jun 28, 2026
Merged

deckyfx merged 2 commits into
mainfrom
feat/storage-fs

Conversation

@deckyfx

@deckyfx deckyfx commented Jun 28, 2026 •

Copy link
Copy Markdown
Owner

FilesystemStorageProvider (storage thrust, part 1)

First concrete StorageProvider — the foundation the upload pipeline (next PR) stores bytes through. Per the Storage Rule, Core never touches the FS directly; it depends only on the interface.

What

  • createFilesystemStorageProvider({ root }) over Bun's native file APIs, implementing the full contract: store / delete / exists / stream / copy / move / getPublicUrl.
  • Path confinement: every key resolves against root and is validated with relative() (correct even when root is /, where startsWith(root + sep) breaks). Rejects ../ traversal, absolute keys, and the root itself — on every key-taking path (source + destination of copy/move, plus read/delete).
  • Guarantee scoped honestly: it confines key-based traversal (keys are app-generated content paths like assets/ab/cd/<sha256>, root is app-owned). Attacker-planted symlinks inside root are out of scope (they'd need FS write access already); realpath hardening is noted for any future untrusted-root use.
  • getPublicUrl → null: a private FS backend has no inherent URL; the API serves bytes via its own route (next PR).
  • Interface extracted to provider.ts to avoid an index ↔ impl import cycle.

Tests (13)

Round-trip store/stream/exists/delete/copy/move (Uint8Array + ReadableStream), getPublicUrl null, and path-traversal rejection across source/destination/read/delete — including that a rejected move leaves the source intact.

Validation

typecheck 0 · 78 tests total · boundaries 0 · pre-reviewed with the CodeRabbit CLI (relative()-check, expanded traversal tests, scoped docs all applied).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Added a private local filesystem storage option for Bun-based apps, supporting save, stream-read, copy, move, existence checks, and deletion.
    • Added a standardized storage backend contract for consistent provider behavior.
  • Bug Fixes
    • Hardened key/path validation to block absolute paths and traversal attempts, preventing access outside the configured storage root.
    • Improved safety around copy/move so invalid operations don’t leave behind partial destination data.
  • Tests
    • Added a Bun test suite covering core storage behaviors, privacy expectations, and path-safety scenarios.

Implement FilesystemStorageProvider over Bun's file APIs, satisfying the
StorageProvider contract (store/delete/exists/stream/copy/move/getPublicUrl).
Keys are confined to the storage root via a relative()-based traversal check
(correct even when root is "/"); the guarantee is scoped to key-based traversal
(keys are app-generated content paths, root is app-owned). getPublicUrl returns
null — a private FS backend has no inherent URL; the API serves bytes via its
own route. The StorageProvider interface moves to provider.ts to avoid an
index<->impl import cycle.

Tests: round-trip store/stream/exists/delete/copy/move + path-traversal
rejection on every key-taking path (source + destination, read + delete), and
the source survives a rejected move.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Jun 28, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 353704a5-5233-4fe5-aa43-4983f90177a5

📥 Commits

Reviewing files that changed from the base of the PR and between 39656a5 and cc688fc.

📒 Files selected for processing (2)
  • packages/storage/src/filesystem.ts
  • packages/storage/test/filesystem.test.ts
🚧 Files skipped from review as they are similar to previous changes (2)
  • packages/storage/src/filesystem.ts
  • packages/storage/test/filesystem.test.ts

📝 Walkthrough

Walkthrough

Adds a standalone StorageProvider contract, a Bun-backed filesystem provider with path safety checks, re-exports the storage API from the package entry point, and adds tests for storage behavior and invalid path handling.

Changes

Filesystem StorageProvider

Layer / File(s) Summary
Storage contract and exports
packages/storage/src/provider.ts, packages/storage/src/filesystem.ts, packages/storage/src/index.ts
StorageProvider moves into its own module, FilesystemStorageConfig is added, and index.ts re-exports the public storage symbols.
Filesystem provider implementation
packages/storage/src/filesystem.ts
createFilesystemStorageProvider normalizes the configured root, resolves keys under that root, and implements store, delete, exists, stream, copy, move, and getPublicUrl using Bun and node:fs.
Filesystem provider tests
packages/storage/test/filesystem.test.ts
Tests cover storing, streaming, existence checks, delete idempotence, copy, move, getPublicUrl, and rejection of escaping or absolute keys across operations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐇 Hop hop, the paths are neat,
Keys stay safe beneath my feet.
I store, I stream, I copy, move,
No tricky ../ can disprove.
Bun lights the burrow, bright and true,
Files stay snug in paths I knew.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title is concise and accurately describes the main change: adding a filesystem-backed StorageProvider.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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.
✨ 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/storage-fs

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

Comment @coderabbitai help to get the list of available commands.

@deckyfx

deckyfx commented Jun 28, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 28, 2026 •

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
packages/storage/test/filesystem.test.ts (1)

78-103: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Cover the remaining root-escape cases in the security matrix.

Line 100 only checks stream() and delete(), but exists() also resolves through resolveKey, and packages/storage/src/filesystem.ts:30-58 has a separate guard for the storage root itself. A regression that stops rejecting exists("../x") or "" / "." keys would still pass this suite today.

Proposed test additions
   it("rejects traversal on read and delete paths", async () => {
+    await expect(storage.exists("../escape.txt")).rejects.toThrow(/escape/);
     await expect(storage.stream("../escape.txt")).rejects.toThrow(/escape/);
     await expect(storage.delete("../escape.txt")).rejects.toThrow(/escape/);
   });
+
+  it("rejects the storage root itself as a key", async () => {
+    for (const key of ["", "."]) {
+      await expect(storage.store(key, bytes("x"))).rejects.toThrow(/escape/);
+      await expect(storage.exists(key)).rejects.toThrow(/escape/);
+    }
+  });
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/storage/test/filesystem.test.ts` around lines 78 - 103, Extend the
path-traversal safety test matrix in filesystem.test.ts to cover the remaining
root-escape cases that also flow through resolveKey and the filesystem root
guard in FilesystemStorage. Add assertions around exists() rejecting traversal
inputs like "../x", and include empty or "." keys so the suite fails if the
root-path validation regresses. Keep the checks alongside the existing
storage.store/copy/move/stream/delete cases so all public methods in
FilesystemStorage are covered consistently.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/storage/src/filesystem.ts`:
- Around line 41-45: The resolveKey helper in filesystem.ts is still allowing
absolute keys because it only validates the path after calling resolve/relative.
Update resolveKey to reject absolute inputs up front before any path
normalization, then keep the existing escape checks for the resolved relative
path. Use the resolveKey function and its root/key handling to ensure absolute
keys are rejected consistently, including when root is "/".
- Around line 79-88: Validate the source key before mutating the destination
side in `copy` and `move` within `filesystem.ts`. Resolve and validate `from`
first using `resolveKey` (and fail fast if it escapes) before calling `mkdir` on
`to`, so rejected operations do not leave empty directories behind under the
storage root. Keep the destination directory creation and file transfer only
after `from` has been successfully validated.

---

Nitpick comments:
In `@packages/storage/test/filesystem.test.ts`:
- Around line 78-103: Extend the path-traversal safety test matrix in
filesystem.test.ts to cover the remaining root-escape cases that also flow
through resolveKey and the filesystem root guard in FilesystemStorage. Add
assertions around exists() rejecting traversal inputs like "../x", and include
empty or "." keys so the suite fails if the root-path validation regresses. Keep
the checks alongside the existing storage.store/copy/move/stream/delete cases so
all public methods in FilesystemStorage are covered consistently.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 945e2e32-49c4-4dd1-86a6-821c32a7ea3d

📥 Commits

Reviewing files that changed from the base of the PR and between 6bf0e7e and 39656a5.

📒 Files selected for processing (4)
  • packages/storage/src/filesystem.ts
  • packages/storage/src/index.ts
  • packages/storage/src/provider.ts
  • packages/storage/test/filesystem.test.ts

Comment thread packages/storage/src/filesystem.ts Resolved
Comment thread packages/storage/src/filesystem.ts Resolved
…e before mkdir

- resolveKey rejects isAbsolute(key) before relativizing, so an absolute key that
  points inside root (always when root === "/") no longer slips past the check.
- copy/move resolve the source key before creating destination dirs — a rejected
  escaping source no longer leaves empty directories behind.
- tests: absolute-key-inside-root rejection; no destination dirs on invalid source.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@deckyfx

deckyfx commented Jun 28, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 28, 2026 •

Copy link
Copy Markdown
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant