Skip to content

About

No description, website, or topics provided.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Husky Drop — direct browser-to-cloud file delivery

Husky Drop

A private, direct-to-Google-Drive dropbox for original photos, videos, and large files.
Send a link. Friends upload from any browser. You watch the transfer live.

Live site Cloudflare Workers Google Drive Vanilla JavaScript Tests passing

Husky Drop is a receive-and-share system for the files that group chats, email attachments, and compressed social uploads handle badly. It combines a friendly public uploader, a real-time operations dashboard, and private Drive-backed galleries in one Cloudflare Worker application.

File bytes move from the browser directly to Google Drive through resumable upload sessions. The Worker validates access, mints those sessions, records compact metadata, and coordinates live state—it does not proxy incoming file bytes.

Note

This is a focused personal-cloud project, not a multi-tenant file-hosting SaaS. It is designed for a trusted owner collecting from invited people.

See it in action

Husky Drop admin overview with live transfers and analytics

Public Husky Drop uploader and transfer progress
For uploaders
A clear, phone-friendly flow for originals, whole folders, huge files, pause, cancel, retry, and resume.
Husky Drop private share-link management
For collectors
Private galleries or Drive redirects with PINs, viewer attribution, analytics, ZIP delivery, pause, and expiry.

Interface previews are rendered from the checked-in redesign package with demonstration data.

Why Husky Drop

Capability What makes it useful
⚡ Direct-to-Drive uploads Incoming chunks go to Google's resumable-upload endpoint instead of being relayed through a Worker.
🔁 Real recovery Interrupted sessions are stored in IndexedDB; re-selecting the same file resumes from Drive's confirmed byte offset.
🧠 Adaptive transfer engine Automatic mode adjusts between 2–8 parallel files, grows or shrinks chunks, prewarms sessions, detects stalls, and backs off after errors.
📡 Live command center Durable Object WebSockets stream active uploaders, file progress, throughput, ETA, and recent completions to the admin.
🖼️ Private share galleries Share existing Drive folders through PIN-capable galleries with thumbnails, media viewing, signed downloads, and streaming ZIP64 archives.
🧯 Abuse containment Link budgets, expiry, pause controls, Drive-space checks, brute-force damping, and signed short-lived download tokens limit damage.
🗂️ Drive-native organization Choose a destination in the Drive browser, create per-uploader folders, or preserve uploaded relative paths in metadata.
🎨 Per-link presentation Labels, welcome copy, colors, backgrounds, logos, promo media, and calls to action can be configured per drop.
🗜️ Image archive & video previews GitHub Actions runners (free tier, no Cloudflare CPU) shrink RAW/HEIC/JPEG folders to a size target as a copy, an _archive mirror, or an in-place Drive revision, with dry-run, pause/undo, recurring rules and e-mail digests; videos get 720p previews for galleries.

One application, three experiences

  • Drop links — private /d/:slug receive-only pages for originals and large batches.
  • Admin — one /admin shell with Overview, Live transfers, Drop links, Share links, Activity, People, Image archive, Video previews, Alerts & log, link details, and New drop link flows.
  • Share links — /s/:slug galleries for controlled read access, plus redirect mode when a public Drive handoff is intentional.

How it works

flowchart LR
    U[Friend's browser] -->|Request an upload session| W[Cloudflare Worker]
    W -->|Create resumable session| G[Google Drive API]
    U ==>|Upload file chunks directly| G
    U -.->|Live progress WebSocket| D[Durable Object]
    A[Admin dashboard] <-.->|Live snapshots| D
    W <-->|Links, counters, recent history| K[Cloudflare KV]
    D -->|Batched completions and rollups| K
Loading

The Worker is the control plane:

  1. It validates the link, expiry, pause state, budgets, Drive headroom, and optional PIN.
  2. It asks Google Drive for a file-scoped resumable upload URL.
  3. The browser sends chunks to Google and reports compact live progress over a WebSocket.
  4. The Durable Object reconciles live sessions, derives throughput and ETA, batches completion writes, and stores daily SQLite rollups.
  5. Google Drive remains the durable source of file truth; the app keeps only the metadata needed for operation and analytics.

Admin observability

  • People — one profile per visitor. A first visit sets an anonymous hd_did device cookie and a FingerprintJS id; once that device signs in with Google, every past and future event from it is attributed to the account. Profiles list drop links used, shares viewed, devices with client details, a timeline, manual merge/unlink, and block buttons (account, cookie or fingerprint).
  • Activity — one card per person per day (Google account → device → fingerprint → typed name, so a mid-visit sign-in stays one card), or a flat table, or per-person totals; filters by kind, person, link, range; CSV export.
  • Alerts & log — client-side crashes on drop/share pages are posted with stack, breadcrumbs, and a state snapshot; they land in the system log and e-mail the admin (one mail per page per 15 min). Runner, image job, cron, and preview events log to the same place.

Transfer behavior

  • Automatic or fixed parallelism from 1–8 active files.
  • 8–128 MB adaptive chunks, always aligned to Drive's required upload granularity.
  • Exponential retry, dead-session replacement, and a 60-second no-progress watchdog.
  • Two prefetched Drive sessions to reduce gaps between files.
  • Bounded DOM rendering and constant-time aggregate counters for 600+ file queues.
  • Resume records kept locally for roughly six days; the uploader must re-select files because browsers cannot silently reopen local files.

For the deeper write-path and state model, read Architecture. What changed and why, newest first: Changelog.

Security model

Husky Drop assumes a private owner account and invitation links that can still leak. Its controls focus on credential safety, guessing resistance, spam containment, and keeping Drive identifiers out of public APIs.

Control Implementation
PIN storage PBKDF2-SHA256, 100,000 iterations, unique salt, constant-time comparison, and transparent migration of legacy hashes.
Guessing protection Per-IP exponential lockouts plus per-link global damping for distributed attempts.
Admin access HMAC-signed, HttpOnly, Secure, SameSite=Strict session cookie; optional allow-listed Google sign-in; bearer token retained for scripts.
Admin mutations Same-origin checks and rate-limited login.
Gallery downloads HMAC-signed tokens bound to scope, share, file, and expiry; risky executable/archive source types are blocked from public delivery.
Capacity protection Link-level byte, file, and session budgets; manual pause; automatic pause at a limit; 5 GB Drive quota reserve.
Secret handling Worker secrets or local .dev.vars; both are kept out of Git. Public metadata never exposes Drive folder IDs or PIN hashes.

The direct upload path is a performance and exposure reduction—not end-to-end encryption. Google still receives and stores the uploaded files. Antivirus scanning, Turnstile, and reduced drive.file OAuth scope are not implemented. See the complete Security model before exposing a deployment broadly.

Stack

Layer Technology
Edge application Cloudflare Workers
Static application Worker Assets, semantic HTML, CSS, vanilla JavaScript
Durable live state Cloudflare Durable Objects + WebSockets
Rollups Durable Object SQLite
Persistent metadata Cloudflare KV
File storage Google Drive resumable uploads
Authentication PBKDF2 PINs, HMAC sessions/tokens, optional Google OAuth
Notifications Optional Resend email digests
Media experience PhotoSwipe, Swiper, native media, streaming ZIP64
Validation Node.js smoke, structure, icon, workflow, and README tests

There is no frontend framework, application bundler, database server, or file-storage proxy to operate.

Quick start

Prerequisites

  • A current Node.js LTS release and npm.
  • A Cloudflare account with Workers, KV, and Durable Objects available.
  • A Google Cloud project with the Google Drive API enabled.
  • A Google OAuth web client and refresh token for the Drive account that will receive files.
  • A hostname for the Worker if you want a custom domain.

Preview a share gallery without production services

For isolated share-gallery work, use the local-only fixture server:

npm run dev:fixtures
# http://127.0.0.1:8788/s/local-media

The fixture server:

  • Serves the real browser UI with synthetic local images and videos.
  • Requires no Cloudflare account, Google token, KV namespace, .dev.vars, or live share.
  • Never contacts Cloudflare KV, Google Drive, or production analytics.
  • Adds a fixture-only CSP that blocks every off-origin browser request; fallback system fonts are expected locally.
  • Supports real byte-range responses so video seeking can be tested.
  • Is the default command for isolated share-gallery work; npm run dev uses Wrangler and the developer's configured bindings.

1. Install and create safe local configuration

git clone https://github.com/DhakadG/husky-drop.git
cd husky-drop
npm install
cp wrangler.example.jsonc wrangler.jsonc
npx wrangler kv namespace create KV

On PowerShell, use Copy-Item wrangler.example.jsonc wrangler.jsonc. Put the new KV namespace ID, route, owner display name, and optional parent Drive folder in your local wrangler.jsonc.

2. Create a Google refresh token

Add http://localhost:8765/cb as an authorized redirect URI on your Google OAuth client, then run:

node scripts/get-refresh-token.mjs YOUR_GOOGLE_CLIENT_ID YOUR_GOOGLE_CLIENT_SECRET

3. Add required secrets

npx wrangler secret put GOOGLE_CLIENT_ID
npx wrangler secret put GOOGLE_CLIENT_SECRET
npx wrangler secret put GOOGLE_REFRESH_TOKEN
npx wrangler secret put ADMIN_TOKEN

Recommended for separate signing and passwordless admin access:

npx wrangler secret put SHARE_SIGNING_KEY
npx wrangler secret put ADMIN_EMAIL

If ADMIN_EMAIL is configured, add https://YOUR_HOST/api/admin/auth/callback to the Google OAuth client's redirect URIs.

4. Validate and run locally

npm test
npm run dev

Icons come from one Lucide sprite. Add a name to UI_ICON_NAMES in public/public.js, run npm run icons to regenerate public/icons.svg, and use it as <svg class="ico"><use href="/icons.svg#name"/></svg> or uiIcon("name"). The test suite fails on any inline glyph that bypasses it.

For local API calls, create an ignored .dev.vars file containing the same required secrets. The secrets and bindings are listed in Deploy workflow.

Configuration

Worker bindings

Binding Required Purpose
ASSETS Yes Serves the application in public/.
KV Yes Stores links, stats, events, recent history, guards, and cached Drive metadata.
LIVE_TRACKER Yes Durable Object for WebSockets, batching, rate limits, and SQLite rollups.

Secrets

Name Required Purpose
GOOGLE_CLIENT_ID Yes Google OAuth client identifier.
GOOGLE_CLIENT_SECRET Yes Google OAuth client secret.
GOOGLE_REFRESH_TOKEN Yes Refresh token for the receiving Drive account.
ADMIN_TOKEN Yes Admin bootstrap login and signing-key fallback.
SHARE_SIGNING_KEY Recommended Dedicated key for share downloads, ZIP tickets, and viewer sessions.
ADMIN_EMAIL Optional Exact Google account allowed to sign in to /admin.
RESEND_API_KEY Optional Enables upload-start and session-digest email notifications.
NOTIFY_TO / NOTIFY_FROM Optional Notification recipient and verified sender used with Resend.

Non-secret variables

Name Purpose
DRIVE_PARENT_ID Parent folder under which automatically created drop folders live. Leave empty for My Drive root.
OWNER_DISPLAY_NAME Public collector name shown on drop pages.
LINK_SLUGS Optional recovery/fast-path list of existing drop slugs.
CF_BEACON_TOKEN Optional Cloudflare Web Analytics token injected into HTML.
CLARITY_PROJECT_ID Optional Microsoft Clarity project identifier injected into HTML.

Project map

husky-drop/
├── CLAUDE.md             # ground rules; points at docs/CONTEXT.md
├── src/                  # the Worker
│   ├── worker.js         # the router: every route, page serving, admin auth, cron
│   ├── util.js           # constants, normalizers, escaping. No network, no KV
│   ├── store.js          # KV state: counters, events, lockouts, notifications
│   ├── drive.js          # every Google Drive call
│   ├── auth.js           # Google sign-in for viewers; admin sessions
│   ├── applog.js         # the app log the admin Logs tab reads
│   ├── drop-api.js       # drop endpoints: preflight, sessions, progress, completion
│   ├── admin-api.js      # admin drop-link CRUD, overview, activity, Drive browsing
│   ├── live.js           # LiveTracker Durable Object: sessions, WebSockets, alarms
│   ├── live-analytics.js # DO SQLite: rollups, telemetry, activity feed
│   ├── live-completions.js, live-diagnostics.js, live-digest.js
│   ├── identity.js, people.js, stitch.js   # visitors, profiles, account stitching
│   ├── share.js          # share endpoints: meta, listing, summary, tracking
│   ├── share-admin.js    # share CRUD and Drive permission revocation
│   ├── share-token.js    # signed download tokens, download safety list
│   ├── share-media.js    # thumbnails, Range downloads, warm-on-browse
│   ├── media-cache.js    # the ladder: edge cache → R2 → Drive
│   ├── share-zip.js      # streamed ZIP64 "download all"
│   ├── share-index.js    # chunked Drive walk, folder stats, file rows, dedupe
│   ├── share-changes.js  # Drive change feed, scheduling, R2 orphan sweeps
│   ├── share-stats.js    # the endpoints that read the index
│   ├── share-previews.js # RAW/HEIC → WebP previews and WebP thumbnails
│   ├── previews.js       # 720p video previews
│   ├── images*.js        # image-archive re-encode jobs and recurring rules
│   ├── pipelines.js      # the admin Pipelines tab, one view over all of it
│   └── exif.js           # EXIF for the viewer's file-info panel
├── public/               # pages and browser modules: no bundler, no framework
│   ├── public.js         # shared globals: esc, reconcile, fmtBytes, uiIcon
│   ├── skeleton.js       # the one loading-skeleton vocabulary
│   ├── drop*.js          # the upload engine
│   ├── share*.js         # gallery, viewer, selection, telemetry
│   └── admin*.js         # one module per dashboard tab
├── scripts/              # tests (plain node + assert), runners, tools
├── .github/workflows/    # CI, PR review, and the transcoders
├── docs/                 # CONTEXT, RUNBOOK, API, ARCHITECTURE, CHANGELOG, archive
├── wrangler.example.jsonc
└── package.json

Testing

npm run test:fixtures
npm test

The test chain covers Worker behavior, authentication and security headers, Drive and share flows, UI structure, icon fidelity, admin workflows, adaptive concurrency, README claims, and local asset/link integrity.

For a deploy-shaped build without publishing:

npx wrangler deploy --dry-run

Deployment

GitHub and Cloudflare are independent release targets. Ship in this order:

# 1. verify
npm test

# 2. update source history
git add -A
git commit -m "describe the change"
git push origin main

# 3. publish the Worker and static assets
npm run deploy

git push does not update the live Worker, and wrangler deploy does not update GitHub. Read Deploy workflow before shipping.

Documentation

Document Use it for
Context Start here. What lives where, how a request flows, the conventions, and the traps already hit.
Runbook Operating the live service: health checks, re-indexing, dedupe, previews, R2 sweeps.
Deploy workflow Secrets, bindings, and the GitHub → Cloudflare release order.
Architecture Data path, Durable Object state, batching, recovery, and performance.
Security Threat model, lockouts, authentication, budgets, and non-goals.
API reference Public and admin HTTP/WebSocket endpoints.
Email notifications Optional Resend setup and delivery behavior.
Changelog Every change, newest first, with the reasoning behind it.
Archive Documents that were true once, kept for provenance.

Known limits

  • This is a single-owner personal service, not an isolated multi-tenant platform.
  • Upload recovery requires the sender to re-select the same local files; browsers do not let a page reopen files silently.
  • Gallery safety filtering is metadata-based and is not malware scanning.
  • Redirect-mode share links grant anyone-with-the-link Drive reader access while active; use gallery mode for private material.
  • Drive OAuth currently uses a broad Drive scope; a reduced drive.file migration is future hardening work.
  • Turnstile and client-side file encryption are not implemented.
  • Active transfer state is ephemeral if the Durable Object restarts, but Google-owned resumable uploads continue and completed files remain in Drive.

Built for the moment after a trip when everyone has the originals—and nobody wants another compressed group-chat upload.

About

No description, website, or topics provided.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages