cloudflare-drop: publish a static site as a shareable link

Turn a finished static page into a live URL with one command. Cloudflare serves it from its edge at https://<name>.<account>.workers.dev in seconds.

Two hosting modes, and the skill picks the one that will actually work:

The mode is detected, not guessed, and always reported back — so you never hand someone a link believing it's permanent when it dies in an hour.

Protection contract

When the user asks for password protection, use -otp on a permanent deployment. Temporary previews and renew reject it before upload. Never omit the flag on retry, change hosting mode silently, embed the report behind a client-side password form, or fall back to publishing an unprotected copy. An explicit --permanent uses the operator's Cloudflare account and requires authentication. Without -otp, behavior is unchanged.

Stage only intended deliverables in a dedicated input folder: the existing helper copies sibling files too. Keep CSV exports, credentials, source repositories and unrelated reports out of that folder. A protected share authorizes access to all its staged assets after login. Use a fresh worker name when moving previously public content behind a password; old downloads and cached public copies cannot be revoked. Every deploy now prints the staging review described below before it uploads — read it, and say something to the user if it flags a file.

What is about to become public

Staging copies the page's whole sibling directory, recursively, because a multi-file page renders broken without its assets. node_modules, .git, __MACOSX and every dotfile (so .env too) were already excluded. What was never visible is the ordinarily-named file — secrets.json, credentials.txt, backup.sql, id_rsa — and this skill's whole job is to turn a folder into a public URL.

So every run prints, on stderr, before the upload:

STAGED_FILES 7
STAGED_REVIEW 4 of 7 staged files are outside HTML/CSS/JS/images/fonts. …
  SENSITIVE_NAME  secrets.json  (312 bytes)
  UNEXPECTED_TYPE  backup.sql  (24 bytes)

A clean run prints STAGED_FILES n and STAGED_REVIEW ok — the headline is printed on every path, so its absence means the review did not run, not that there was nothing to say.

This never blocks a deploy (discipline #3). It is a report. When it flags something, the fixes are: re-stage from a folder holding only the deliverable, or re-run with --assets-only, which stages only recognised static assets and prints STAGED_SKIPPED naming every file it left behind. Relay the flagged names to the user rather than deciding for them — a data.sql someone means to publish is their call.

The one command

node references/deploy.mjs <page.html> [--ttl 30m] [--name my-report] [--permanent] [--assets-only]

It resolves the countdown window → stages the page as index.html at a clean root → deploys via Wrangler → curl-verifies HTTP 200 → prints:

RESULT_URL   https://my-report.ethereal-composer.workers.dev
MODE         temporary
CLAIM_LINK   https://dash.cloudflare.com/claim-preview?claimToken=…
EXPIRY_EPOCH 1785499999

It never prints a URL it didn't verify, and never invents one. The verify is content, not just status: after the 200 backoff, the served page must match the source's byte size (within the injected countdown's growth) and carry a body sentinel — a blank/truncated page that still 200s fails as URL_UNVERIFIED.

URL_UNVERIFIED = deploy failed — do NOT deliver that URL; fall back to the file. If the script prints URL_UNVERIFIED (no 200, or a blank/truncated page that didn't match the content self-verify), the deploy did not succeed. Never hand that URL to the user — treat it as a failure, say so plainly, and offer the HTML file instead (fail-open, discipline #3).

Why Wrangler and not the browser dropzone: cloudflare.com/drop's own "For AI agents" section instructs agents to prefer Wrangler for local CLI workflows. The packaged playwright path was removed in 2.0.0 — the dropzone DOM changed and it silently returned no URL. v1 predicted this switch; this is it.

Flags

What the deploy subprocess can see

Wrangler is a third-party CLI running on your machine, so two things are pinned rather than left floating:

• A fixed version. The deploy runs wrangler@4.134.0, not wrangler@latest. Bumping it is a reviewed change to references/wrangler.mjs, not something that happens silently on the next npm publish.
• An allowlisted environment. It receives PATH/HOME/TMPDIR and their Windows equivalents, the proxy variables, NODE_EXTRA_CA_CERTS, the Cloudflare credential variables (CLOUDFLARE_API_TOKEN, CF_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, CF_ACCOUNT_ID, CLOUDFLARE_API_KEY, CF_API_KEY, CLOUDFLARE_EMAIL, CF_EMAIL), WRANGLER_HOME/XDG_CONFIG_HOME/ XDG_CACHE_HOME, and CI. Every other variable is withheld, including other vendors' API keys and CLOUDFLARE_API_BASE_URL (which would redirect your Cloudflare token to another host). The count withheld is printed as a NOTE.

If a deploy needs a variable that is not on the list, add it by name:

CLOUDFLARE_DROP_ENV_PASSTHROUGH="WRANGLER_LOG,CLOUDFLARE_API_BASE_URL" \
  node references/deploy.mjs report.html

The names it forwarded are printed back, so the widening is never silent.

Optional six-digit access code

node references/deploy.mjs ./publish/report.html --permanent -otp --name private-report

Requires an authenticated Cloudflare account supporting Workers Static Assets and SQLite Durable Objects. Wrangler provisions the limiter through a migration; the token must also permit that deployment. No token is required for ordinary temporary previews. Check node --version and npm --version (install Node.js with npm if missing); Wrangler is obtained automatically via npm.

After successful protected verification, deliver RESULT_URL and OTP_CODE as separate values to the requesting user. Never put the code in a URL, report, screenshot, public log, claim link, or index. Do not guess or log it again on failure. This flag means a shared access code, not email/SMS delivery, TOTP, or a single-use code: readers may reuse it, and every protected redeploy generates a new code and invalidates old sessions. Permanent deployments do not use preview renewal or archival.

All HTML and static assets pass through server-side authentication before their bytes are sent. Anonymous responses contain only the standalone verification screen; viewing source cannot reveal the report. Correct input sets a signed, host-bound HttpOnly, Secure, SameSite=Strict cookie for one hour. Responses are private, no-store. The Worker enforces a durable 15-minute attempt budget: 10 per client IP and 100 across the deployment (including successful logins). Limits can temporarily block legitimate readers sharing an IP; there is no insecure fallback. Once authorized, a reader can view source and save content normally.

Protected verification checks anonymous paths, rejects a wrong code, and checks the exact original HTML with an authenticated session. If verification or deployment fails, report failure and keep the local deliverable; do not publish it without protection. Server configuration lives outside the assets directory in a private temporary folder, which is removed after the protected deployment attempt. Technical review and tests: OTP security review.

The TTL is a display, not a lifetime

The countdown baked into the page says how long the link is expected to be useful. It does not control the real lifetime — Cloudflare does:

• On a temporary preview, Cloudflare hard-expires at 60 minutes. A longer TTL is clamped down and TTL_CLAMPED is printed. The page must never promise three hours on a link that dies in one.
• On a permanent deploy, no countdown is injected at all — a countdown on a link that never dies is the same lie in the other direction.

The default is 60m for exactly this reason. A longer default would be dead configuration: previews clamp it away, permanent deploys drop it entirely, so it would never once reach a reader's screen. --ttl is therefore for shortening the window ("this is only good for the next 30 minutes"), not extending it.

Want a link that outlives the hour? That's not a TTL problem — set CLOUDFLARE_API_TOKEN and deploy permanently, or claim the preview.

The OAuth trap (why --no-pause-oauth exists)

Wrangler refuses --temporary when it detects any existing auth, but a non-interactive shell can't complete an OAuth login either. A machine with a browser-based wrangler login therefore deadlocks: too authenticated for a preview, not authenticated enough to deploy.

The escape is to move the OAuth config aside for the duration of the deploy. This touches the user's credential file, so it is:

• opt-out-able (--no-pause-oauth),
• restored in a finally block — even if the deploy crashes,
• covered by a test that asserts restoration after a thrown deploy.

If you want the permanent path instead, set CLOUDFLARE_API_TOKEN (Workers Scripts: Edit is enough) and the pause never happens.

Renewing an expired preview

node references/deploy.mjs renew <old-url|id> [--ttl 30m]

What it does: resolves the id from the url (the worker name — the first *.workers.dev host label; legacy drop-{id} urls stay recognised) → reads the deploy index → takes the archived HTML copy → strips the stale countdown and re-injects a fresh one → redeploys via Wrangler under the ORIGINAL worker name (so the renewed link stays recognisable) → self-verifies the full content is live (size + sentinel, not just a 200) → records renewed_from (the chain back to the original) → prints the NEW url, expiry, RENEWED_FROM, and RENEW_COUNT.

Expectation honesty — renew returns a new url, not the original. Drop cannot revive a dead link; a renew is a fresh deploy of the same content, so the *.workers.dev address changes. Say this plainly when you deliver a renewed link. If the id was never archived (deployed before indexing, or from another machine), renew fails loudly — it won't guess or invent a link.

Claim etiquette — offer the permanent link only at the 3rd renew (U1b). Most deliveries are just the new link + a one-line expiry reminder, nothing else, like a normal person — no "claim it to keep it forever" pitch on every message. The command gates this for you: it prints RENEW_COUNT and only surfaces a CLAIM_LINK once the same content has been renewed 3 times (RENEW_COUNT >= 3); before that it prints CLAIM_OFFER none. Follow that signal — deliver just the link + expiry on the first delivery and the first two renews, and mention claiming only when the tool surfaces the claim link (a page renewed three times is one the viewer keeps returning to, so keeping it permanently is finally worth raising).

The deploy index, briefly

• Home resolves in exactly two portable layers: $CLOUDFLARE_DROP_HOME > (standalone) ~/.cloudflare-drop/. It is never the skill dir or a session workspace — those get committed or cleaned up, so an index there would dangle. The skill carries no host-app awareness; an embedding app points the index at an instance-specific dir purely by setting CLOUDFLARE_DROP_HOME in the deploy environment (there is no baked-in middle layer).
• index.jsonl — one line per deploy, keyed on the drop id (title/summary/deploy-time/expires_at/claim_url/sha256/renewed_from).
• artifacts/<sha256>.html — a content-addressed copy of the deployed page; identical content is stored once (sha256 dedupe).
• Pruning (keep it small, don't over-build a GC): artifacts are content-addressed, so it's safe to periodically delete old files — find <home>/artifacts -mtime +2 -delete. An expired drop can't be renewed once its content is gone anyway, and a fresh deploy re-archives.

When NOT to use

• The deliverable isn't a static site (a server app, an image, a PDF to download) → wrong tool.
• You have no Node/npm → can't run Wrangler; offer the file instead.

Delivery discipline

1. Always state the mode. Permanent → say it's permanent. Temporary → say it expires in ~60 minutes and offer the claim link.
2. Upload the whole folder for multi-file pages. A lone index.html that references style.css renders broken. The stager copies siblings automatically.
3. Fail open, never fabricate. No URL, failed verify, no Node? Say so plainly and offer the HTML file: "I couldn't publish it just now — want the file?" A made-up workers.dev link is worse than an honest failure.
4. Check the content before publishing. Deploying makes it publicly reachable by URL; don't publish credentials or someone else's private data.

Anti-patterns

• Handing back a preview URL without the 60-minute caveat — it silently breaks an hour later.
• Inventing a *.workers.dev link, or reporting one that never returned 200.
• Passing --ttl 3h and then telling the user the link lasts 3 hours — the clamp exists precisely because it doesn't. Only a permanent deploy outlives the hour.
• Leaving the user's OAuth config parked (only possible if you bypass the CLI and call deployWithWrangler yourself without the finally).
• Using this for something that must persist without setting a token — use the permanent path or Pages/Workers.
• Uploading a page without its assets — a lone index.html that references style.css/app.js/images renders broken.
• Ignoring a STAGED_REVIEW that flagged something. It is a report, not a gate, so the deploy succeeded and the file is already public. Say what was flagged.