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.
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.
Interface previews are rendered from the checked-in redesign package with demonstration data.
| 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. |
- Drop links — private
/d/:slugreceive-only pages for originals and large batches. - Admin — one
/adminshell 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/:sluggalleries for controlled read access, plus redirect mode when a public Drive handoff is intentional.
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
The Worker is the control plane:
- It validates the link, expiry, pause state, budgets, Drive headroom, and optional PIN.
- It asks Google Drive for a file-scoped resumable upload URL.
- The browser sends chunks to Google and reports compact live progress over a WebSocket.
- The Durable Object reconciles live sessions, derives throughput and ETA, batches completion writes, and stores daily SQLite rollups.
- Google Drive remains the durable source of file truth; the app keeps only the metadata needed for operation and analytics.
- People — one profile per visitor. A first visit sets an anonymous
hd_diddevice 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.
- 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.
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.
| 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.
- 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.
For isolated share-gallery work, use the local-only fixture server:
npm run dev:fixtures
# http://127.0.0.1:8788/s/local-mediaThe 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 devuses Wrangler and the developer's configured bindings.
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 KVOn 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.
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_SECRETnpx 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_TOKENRecommended for separate signing and passwordless admin access:
npx wrangler secret put SHARE_SIGNING_KEY
npx wrangler secret put ADMIN_EMAILIf ADMIN_EMAIL is configured, add https://YOUR_HOST/api/admin/auth/callback to the Google OAuth client's redirect URIs.
npm test
npm run devIcons 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.
| 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. |
| 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. |
| 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. |
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
npm run test:fixtures
npm testThe 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-runGitHub 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 deploygit push does not update the live Worker, and wrangler deploy does not update GitHub. Read Deploy workflow before shipping.
| 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. |
- 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.filemigration 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.



