feat: add file-sharing example with shareable download links by erhnysr · Pull Request #32 · shelby/examples

erhnysr · 2026-05-23T12:36:54Z

Summary

This PR adds a new example application demonstrating decentralized file sharing built on the Shelby SDK.

What it does

Upload any file → receive a unique shareable link → anyone can download it directly from Shelby. Every file is SHA-256 hashed locally before upload, providing verifiable integrity on Aptos blockchain.

Think of it as a decentralized alternative to WeTransfer.

How it works

User uploads a file via the web UI (multipart/form-data)
Server computes SHA-256 hash locally for integrity verification
File is pushed to Shelby via client.upload()
A unique drop ID is generated and metadata stored in drops.json
Anyone with the share link hits /drop/:id/download to stream the file from Shelby via client.download()

API endpoints

Method	Path	Description
POST	/upload	Upload a file
GET	/drop/:id	Get drop metadata
GET	/drop/:id/download	Download file from Shelby
GET	/drops	List all drops

Tech stack

TypeScript (strict mode)
Shelby Node SDK
Express.js
Aptos ts-sdk

Testing

Tested on Shelby testnet with successful uploads and downloads. Live demo: https://shelby-vibe-storage-production.up.railway.app

Checklist

TypeScript — zero errors
Follows repo structure (same as upload-blob, download-blob)
README with setup instructions
.env.example included
pnpm-lock.yaml updated

Note

Low Risk
Additive demo app only; no changes to core SDK or production services, though the example accepts arbitrary uploads and uses server-side Shelby credentials as documented for local/testnet use.

Overview
Adds a new apps/file-sharing example: a small Express + static HTML app that uploads files to Shelby testnet, stores drop metadata in local drops.json, and exposes shareable /d/:id links with /drop/:id/download streaming from the SDK.

Upload flow hashes files with SHA-256 before client.upload(), assigns short UUID-based drop IDs, and sets a 30-day blob TTL. The UI toggles between upload and drop views; the server serializes drops.json writes with a simple mutex and increments download counts on fetch.

Also ships .env.example, README, package.json (Express, multer, @shelby-protocol/sdk latest), tsconfig.json, and pnpm-lock.yaml entries for the new workspace package.

^{Reviewed by Cursor Bugbot for commit b049735. Bugbot is set up for automated code reviews on this repo. Configure here.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ba3a19abfe

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-23T12:39:53Z

+    const db = loadDB();
+    db[id] = drop;
+    saveDB(db);


Make drops.json updates atomic across concurrent requests

Avoid read-modify-write on drops.json without synchronization: /upload reads the file, mutates it, and writes it back after an await, so two overlapping uploads can each start from the same snapshot and the later write will silently discard the earlier drop record. The same pattern is used for download counters, so concurrent downloads can undercount. This causes real data loss/inaccurate metadata under normal parallel traffic.

Useful? React with 👍 / 👎.

Addressed in f660210 with a write lock around drops.json updates. A follow-up in the latest commit keeps that lock usable after a failed update (see the Bugbot thread on updateDB).

chatgpt-codex-connector · 2026-05-23T12:39:53Z

+const app = express();
+
+app.use(express.json());
+app.use(express.static(path.join(import.meta.dirname, "..", "public")));


Serve an actual landing page for browser-based uploads

This middleware mounts ../public, but this commit does not add any apps/file-sharing/public files and there is no explicit GET / handler, so visiting http://localhost:3000 returns 404 and the documented browser upload flow is unavailable. Either include the frontend assets in this app or provide a route that returns an upload page.

Useful? React with 👍 / 👎.

You were right, and my earlier reply that this was resolved was wrong: f660210 added the /d/:id route but no public directory was ever committed, so / and every share link returned 404. The latest commit adds public/index.html, an upload form that shows the share link and SHA-256, and the download page for /d/:id that reads /drop/:id. Checked locally: / and /d/:id now return the page, and the drop page renders a seeded drop with its hash and download link.

…der errors

erhnysr · 2026-05-23T13:01:06Z

Addressed the two issues flagged by Cursor Bugbot:

Content-Disposition header injection — added sanitizeFilename() that strips non-safe characters before setting the header
Download error after headers sent — moved header writes before the stream starts and added res.headersSent guard in the catch block

Both fixes are in commit ea2c1b6.

…/d/:id routes

erhnysr · 2026-05-23T13:03:36Z

Follow-up fixes based on Codex suggestions:

Race condition on drops.json — added a simple async mutex (dbWriteLock) so concurrent reads/writes are serialized via promise chaining
Landing page for /d/:id routes — added a route that serves index.html so shareable drop links work correctly in the browser

All 4 issues are now resolved. PR is ready for review.

cursor

Stale Bugbot comment from a previous run.

…ock usable after an error The app served ../public and sent public/index.html for /d/:id links, but no public directory was committed, so / and every share link returned 404. Add public/index.html: an upload form that shows the share link and SHA-256, and the download page for /d/:id that reads /drop/:id. updateDB chained each update onto the previous promise, so one failed update (a corrupt drops.json, for example) left the lock rejected and every later update was skipped without running. The caller still gets its own error, but the lock now always settles. The download counter also no longer throws when the drop is missing from the file. Use sanitizeFilename for the blob name instead of a second copy of the same regex, apply the formatting biome check asks for, and list SHELBY_ACCOUNT_ADDRESS in the README, which the server requires.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 38b4ac7. Configure here.}

… slash Express serves index.html for /d/:id/ as well as /d/:id, but the page only matched the unslashed path, so a link with a trailing slash showed the upload form instead of the file.

feat: add file-sharing example with shareable download links

ba3a19a

cursor Bot reviewed May 23, 2026

View reviewed changes

Comment thread apps/file-sharing/src/server.ts

Comment thread apps/file-sharing/src/server.ts Outdated

chatgpt-codex-connector Bot reviewed May 23, 2026

View reviewed changes

fix: sanitize Content-Disposition filename and guard against post-hea…

ea2c1b6

…der errors

fix: add async write mutex for drops.json and serve landing page for …

f660210

…/d/:id routes

cursor Bot reviewed May 23, 2026

View reviewed changes

Comment thread apps/file-sharing/src/server.ts

Comment thread apps/file-sharing/src/server.ts Outdated

cursor Bot reviewed Oct 9, 2026

View reviewed changes

Comment thread apps/file-sharing/public/index.html

fix(file-sharing): open the drop page for share links with a trailing…

b049735

… slash Express serves index.html for /d/:id/ as well as /d/:id, but the page only matched the unslashed path, so a link with a trailing slash showed the upload form instead of the file.

Navigation Menu

Repository navigation

feat: add file-sharing example with shareable download links - #32

feat: add file-sharing example with shareable download links#32
erhnysr wants to merge 5 commits into
shelby:mainfrom
erhnysr:feat/file-sharing-example

erhnysr commented May 23, 2026 •

edited by cursor Bot

Loading

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 23, 2026

Uh oh!

erhnysr Oct 9, 2026

Uh oh!

chatgpt-codex-connector Bot May 23, 2026

Uh oh!

erhnysr Oct 9, 2026

Uh oh!

erhnysr commented May 23, 2026

Uh oh!

erhnysr commented May 23, 2026

Uh oh!

cursor Bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

erhnysr commented May 23, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What it does

How it works

API endpoints

Tech stack

Testing

Checklist

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 23, 2026

Choose a reason for hiding this comment

Uh oh!

erhnysr Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot May 23, 2026

Choose a reason for hiding this comment

Uh oh!

erhnysr Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

erhnysr commented May 23, 2026

Uh oh!

erhnysr commented May 23, 2026

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

erhnysr commented May 23, 2026 •

edited by cursor Bot

Loading

cursor Bot left a comment •

edited

Loading