Skip to content
harsh-foundPublic

About

🚒 High-Performance Anonymous File Drop & Ephemeral Sharing Utility built with React 19, TypeScript & Vite

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

1 Commit

Folders and files

Repository files navigation

🚒 Ferry

High-Performance Anonymous File Drop & Ephemeral Sharing Utility

React TypeScript Vite Tailwind CSS Framer Motion Cloudflare Pages License: MIT

No accounts. No trackers. Zero friction.
Drag, drop, set auto-expiration, generate QR codes, and share files with cryptographic SHA-256 verification in milliseconds.

Key Features β€’ Architecture β€’ Directory Structure β€’ Getting Started β€’ Deployment β€’ Keyboard Shortcuts


🌟 Overview

Ferry is a sleek, privacy-first web application designed for fast, hassle-free ephemeral file transfers. Built with modern web primitives, Ferry bridges the gap between quick scratchpad uploads and enterprise-grade file management without forcing users through a login wall.

Whether sending an APK to an Android TV, sharing a large PDF document with a classmate, or generating a temporary download link with a countdown timer, Ferry handles uploads up to 100 MB with multi-provider redundancy, real-time speed monitoring, cryptographic verification, and instant mobile handoff.


✨ Key Features

1. ⚑ Instant & Anonymous Drops

  • Zero Registration: Start uploading immediately. No email, password, or OAuth required.
  • Up to 100 MB per File: Upload documents, videos, source code archives, firmware, and images.
  • Auto-Expiration Policies: Pick custom lifespans: 1 Hour, 6 Hours, 24 Hours, 48 Hours, or Forever (∞) (provider-dependent).

2. 🌐 Multi-Provider Hosting Backend

Ferry integrates with battle-tested storage hosts with automated fallback and provider selection:

  • tmpfiles.org: Ultra-fast temporary file hosting with automated timed expiration (1h to 48h).
  • OnlyFiles: High-capacity hosting with permanent storage options, 500 uploads/hr, and 5,000 uploads/day limits.

3. πŸ”’ Client-Side Cryptographic Verification

  • SHA-256 Fingerprinting: Calculates cryptographic file hashes locally using the Web Crypto API (crypto.subtle.digest) before and during transmission.
  • Data Integrity: Guarantees that downloaded content matches the exact byte sequence uploaded.

4. πŸ“± Instant Mobile Handoff (QR Engine)

  • Real-time QR Codes: Generates high-contrast QR codes directly in the browser using the qrcode engine.
  • Seamless Cross-Device Sharing: Scan from your phone or tablet camera to instantly trigger the download without copy-pasting long URLs.

5. πŸ“Š Real-Time Upload Engine

  • Concurrent Chunked Queue: Queue multiple files simultaneously with distinct lifecycle stages: Queued β†’ Preparing β†’ Uploading β†’ Done.
  • Telemetry & Speed Meter: Live transfer rate calculation (MB/s or KB/s), byte counters, upload progress bars, and ETA calculations.
  • Actionable Controls: Cancel in-flight transfers, retry failed uploads, or copy URLs instantly upon completion.

6. πŸ—ƒοΈ Personal Local Library

  • 100% Client-Side History: Upload history is persisted in localStorage. Nothing is tracked on external analytics servers.
  • Metadata & Organization: Add custom labels, markdown notes, tags, and bookmark important files (Pinned).
  • Category Auto-Detection: Automatically sorts files into Image, Video, Audio, Document, Archive, Code, and Other.
  • Export & Import: Export your full file ledger to JSON or restore it on any device.

7. ⌨️ Command Palette (⌘K / Ctrl+K)

  • Global modal palette with fuzzy search across all active and historic uploads, quick navigation, provider switching, and batch actions.

πŸ—οΈ Architecture & How It Works

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                       Client Browser                        β”‚
β”‚                                                             β”‚
β”‚   [File Drop] ───► [Web Crypto API] ───► SHA-256 Digest     β”‚
β”‚          β”‚                                                  β”‚
β”‚          β–Ό                                                  β”‚
β”‚   [Upload Queue Manager (XHR + Progress Event)]             β”‚
β”‚          β”‚                                                  β”‚
β”‚          β”œβ”€β”€β–Ί Provider: tmpfiles.org (1h - 48h)             β”‚
β”‚          └──► Provider: OnlyFiles (Permanent / Multi-tier)  β”‚
β”‚                                                             β”‚
β”‚   [Response Parser] ──► Direct CDN Download Link            β”‚
β”‚          β”‚                                                  β”‚
β”‚          β”œβ”€β”€β–Ί [QR Generator] (Canvas/SVG for mobile)        β”‚
β”‚          └──► [Local Storage Ledger] (Tags, notes, expiry)  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  1. Local Intake: When files are dropped, Ferry extracts MIME metadata, computes local preview thumbnails (for images/videos), and calculates the SHA-256 checksum in an asynchronous worker thread.
  2. Streaming Dispatch: Uses native XMLHttpRequest to allow granular byte-level upload progress tracking, upload speed computation, and network cancellation triggers.
  3. Ledger Update: Upon receiving 200 OK, Ferry registers the remote URL in the local store along with expiration timestamps.

πŸ“ Directory Structure

web/Ferry/
β”œβ”€β”€ public/                       # Static public assets & icons
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ assets/                   # Vector graphics and bundled illustrations
β”‚   β”œβ”€β”€ components/               # Modular UI component tree
β”‚   β”‚   β”œβ”€β”€ CommandPalette.tsx    # ⌘K power-user search and action menu
β”‚   β”‚   β”œβ”€β”€ FileDrawer.tsx        # Slide-over inspector for file details, QR & notes
β”‚   β”‚   β”œβ”€β”€ FileVisual.tsx        # Dynamic file type icons and thumbnail renderer
β”‚   β”‚   β”œβ”€β”€ Header.tsx            # Navigation bar, live stats badge & palette trigger
β”‚   β”‚   β”œβ”€β”€ HowItWorks.tsx        # Explanatory onboarding accordion and guide
β”‚   β”‚   β”œβ”€β”€ Library.tsx           # History view with category tabs, search & filters
β”‚   β”‚   β”œβ”€β”€ Stats.tsx             # Aggregate usage telemetry (total MB, active files)
β”‚   β”‚   └── UploadPanel.tsx       # Drag-and-drop zone, expiry selectors & queue view
β”‚   β”œβ”€β”€ lib/                      # Core business logic & utilities
β”‚   β”‚   β”œβ”€β”€ format.ts             # Human-readable file sizes, speeds, countdowns
β”‚   β”‚   β”œβ”€β”€ hooks.ts              # Custom React hooks (interval timers, keyboard)
β”‚   β”‚   β”œβ”€β”€ media.ts              # Client-side thumbnail generator & image dimensions
β”‚   β”‚   β”œβ”€β”€ providers.ts          # Storage provider definitions (tmpfiles, onlyfiles)
β”‚   β”‚   β”œβ”€β”€ search.ts             # Multi-field filtering and fuzzy search logic
β”‚   β”‚   β”œβ”€β”€ store.tsx             # React Context & LocalStorage state persistence
β”‚   β”‚   β”œβ”€β”€ types.ts              # Strong TypeScript interfaces & constants
β”‚   β”‚   β”œβ”€β”€ ui.tsx                # Toast notifications & theme providers
β”‚   β”‚   └── upload.ts             # Native XHR file dispatch and progress tracking
β”‚   β”œβ”€β”€ App.tsx                   # Main layout container and view coordinator
β”‚   β”œβ”€β”€ index.css                 # Tailwind CSS v4 directives and design tokens
β”‚   └── main.tsx                  # Application bootstrap entry point
β”œβ”€β”€ eslint.config.js              # ESLint flat config with TypeScript rules
β”œβ”€β”€ index.html                    # Single Page Application HTML5 entry point
β”œβ”€β”€ package.json                  # Dependencies, scripts and package metadata
β”œβ”€β”€ tsconfig.json                 # TypeScript compiler configuration root
β”œβ”€β”€ tsconfig.app.json             # App-specific TS rules
β”œβ”€β”€ tsconfig.node.json            # Node/Vite specific TS rules
└── vite.config.ts                # Vite 7 build configuration with Tailwind plugin

πŸš€ Getting Started

Prerequisites

  • Node.js: v20.x or later (tested on Node v22)
  • Package Manager: npm, pnpm, or bun

Installation

  1. Navigate to the project directory:

    cd /home/code/projects/web/Ferry
  2. Install dependencies:

    npm install
    # or
    pnpm install
  3. Start the development server:

    npm run dev

    The application will be live at http://localhost:5173.


πŸ› οΈ Build & Scripts

Command Description
npm run dev Starts Vite development server with Hot Module Replacement (HMR).
npm run build Compiles TypeScript and builds production-optimized static bundle to dist/.
npm run preview Previews the production build locally via Cloudflare Wrangler dev server.
npm run lint Runs ESLint 9 checks across all source files.
npm run deploy Builds the project and deploys directly to Cloudflare Pages via Wrangler.

☁️ Deployment

Deploy to Cloudflare Pages (Recommended)

Ferry is pre-configured with @cloudflare/vite-plugin and wrangler for seamless edge hosting.

# 1. Login to Cloudflare
npx wrangler login

# 2. Build and deploy
npm run deploy

Alternatively, push to GitHub and link the repository in the Cloudflare Pages Dashboard:

  • Framework Preset: Vite
  • Build Command: npm run build
  • Build Output Directory: dist

⌨️ Keyboard Shortcuts

Shortcut Action
⌘K / Ctrl+K Open / Close Command Palette
Esc Close slide-over drawer / Command Palette
U Scroll to upload panel & focus file picker
L Jump to files library

πŸ”’ Security & Privacy Notice

  • Ferry does not route files through proprietary proxy servers. Uploads stream directly from the user's browser to the selected hosting provider.
  • File records, notes, tags, and pinned statuses live exclusively in the user's local browser storage (localStorage). Clearing browser cache purges the local ledger completely.

Crafted with precision for private, fast, and frictionless web sharing.

About

🚒 High-Performance Anonymous File Drop & Ephemeral Sharing Utility built with React 19, TypeScript & Vite

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages