Share HTML

Share HTML

Usage research is available at /report/0923. The September 23, 2026 report uses a frozen snapshot and publishes only aggregated findings and anonymized use cases.

First-party analytics separates browser reports, HTTP/MCP business outcomes, acquisition signals, and bot evidence. See the measurement contract and operations guide for analytics preferences, data limits, retention, and GA4 configuration. Apply the analytics migrations before deploying with ANALYTICS_ENABLED=true. Browser analytics is enabled by default when the service is enabled and can be turned off in Analytics preferences; existing opt-outs, DNT/GPC, and unreadable preference storage prevent collection. Eligible browser events use the separate Share HTML GA4 property; enhanced measurement is disabled and private share pages do not send Google events.

Upload one HTML file, then share a sandboxed preview as an unlisted public link or an access-key-protected private link.

Links

• Live app: https://sharehtml.zhenjia.dev
• GitHub repo: https://github.com/lifeodyssey/share-html
• Workers fallback: https://share-html.zhenjiazhou0127.workers.dev

Project Docs

• Product and system spec: docs/project/spec.md
• Current progress: docs/project/progress.md
• Roadmap: docs/project/roadmap.md

What It Does

Share HTML is a small Cloudflare-hosted tool for sharing self-contained HTML files. It is useful for quick prototypes, mockups, receipts, tiny demos, and one-off pages that need a URL without setting up a site.

• Anonymous upload flow with a 365-day expiry.
• Supabase magic-link sign-in for keeping and deleting shares, with auth email delivery handled by Cloudflare Email Service.
• Claim token flow for attaching an anonymous upload to an account later.
• Public-unlisted and access-key-protected private-link visibility modes.
• Share page with status, risk score, and embedded preview after any required private-link unlock.
• Direct preview URL for opening the uploaded HTML by itself.
• Lightweight scanner for suspicious HTML patterns.
• Report API and admin moderation endpoints.

URL Model

Share HTML intentionally exposes two different URL surfaces after upload:

• Share URL opens the wrapper page at /s/:slug. This is the best link to send because it includes status, safety context, the report action, and the embedded preview.
• Preview URL opens the sandboxed HTML render at /v/:slug/. For a private link it requires the short-lived preview cookie created during unlock.
• Claim token is private. Use it with the share ID after signing in if you want to move an anonymous upload into your account.

Each upload also chooses one visibility:

• `public_unlisted` is the default. Anyone who knows the URL can read its metadata and open its preview. Share and preview routes are marked noindex and never added to sitemap.xml, but unlisted is not the same as authenticated.
• `private_link` returns a 32-byte base64url accessKey. The returned share.share_url carries the key in a client-side #key= fragment so the initial HTTP request does not send it to the server. Treat the complete private URL as a secret.

claimToken and accessKey are deliberately different capabilities: the first transfers ownership after sign-in; the second opens a private link and does not grant ownership.

HTTP API

Create a public-unlisted share (the default):

curl -X POST https://sharehtml.zhenjia.dev/api/shares \

-F 'file=@page.html' \ -F 'title=My page'

Create a private link:

curl -X POST https://sharehtml.zhenjia.dev/api/shares \

-F 'file=@page.html' \ -F 'visibility=private_link'

Both success responses use the same shape:

{

"share": { "id": "...", "slug": "...", "share_url": "...", "preview_url": "..." }, "claimToken": "... or null", "accessKey": "... or null", "message": "Uploaded." }

accessKey is null for public_unlisted. To unlock a private link without the browser wrapper:

curl -X POST https://sharehtml.zhenjia.dev/api/shares/SLUG/access \

-H 'content-type: application/json' \ --data '{"accessKey":"PRIVATE_ACCESS_KEY"}'

Success returns { "share": ... } and sets two short-lived, host-only HttpOnly grants: one scoped to /v/:slug for the preview and one scoped to the exact unlock endpoint so a refresh can restore metadata after the browser removes #key from its address bar. A bare GET /api/public/shares/:slug for a private link returns 401 with code: "share_access_required"; a wrong key returns 403 with code: "invalid_share_access_key". Never move the key into a query parameter or expose the complete private URL in logs, issue reports, or public output.

An authenticated owner can replace a lost or exposed private key with POST /api/shares/:id/access-key. Rotation returns the new key once and immediately invalidates metadata and preview grants issued for the previous key.

Agent Access

Share HTML is built to be discoverable and usable by AI agents, not just humans:

• `llms.txt` — AI-readable site guide (also served from / when the request sends Accept: text/markdown).
• `openapi.json` — machine-readable HTTP API description, including both visibility modes and the private unlock/cookie flow. The homepage HTML also embeds static content + JSON-LD so non-JS agents can read what the site is and how to call it.
• MCP machine endpoint — https://share-html.zhenjiazhou0127.workers.dev/mcp exposes describe_share_html, get_public_share, and create_share. It uses the same production Worker as the branded site while avoiding zone-level browser-bot policy on machine-to-machine traffic. The page exposes the same tools in-browser via WebMCP (navigator.modelContext).
• `/a2a` — A2A 1.0 JSON-RPC endpoint with an implemented describe_share_html skill; its card intentionally advertises only that executable A2A capability.
• WebMCP `create_share` lets an agent choose public_unlisted or private_link; `access_private_share` exchanges an access key for metadata plus the scoped metadata and preview grants. Both run through the normal HTTP API.
• MCP `create_share` supports both public_unlisted and private_link. It runs through the same anonymous rate limit and risk scanner as the web upload — there is no bypass path, and private creation returns its key once.
• Discovery files: robots.txt (with explicit AI-bot rules), sitemap.xml, auth.md, and /.well-known/ resources (api-catalog, mcp/server-card.json, webmcp.json, agent-skills, agent-card.json, OAuth/OIDC metadata, security.txt). Unknown /.well-known/ paths return 404 rather than the SPA shell.

The first-party homepage and discovery documentation opt into search indexing and real-time AI input while opting out of AI training through a response-level Content-Signal. User-supplied share metadata and previews send the stricter search=no, ai-input=no, ai-train=no, use=immediate, are noindex, and never appear in the sitemap. This response-level split keeps first-party GEO permissions from being applied to uploaded content on the same host.

Acquisition Loop

The product now has four crawlable, first-party entry pages rather than relying on discovery files alone:

• /html-preview explains the single-file preview boundary and includes an upload CTA.
• /private-html-sharing explains access-key privacy and its limits.
• /examples offers three self-contained files that can be preloaded into the uploader.
• /agents provides working MCP, HTTP, OpenAPI, WebMCP, Skill, and A2A entry points.

Only these pages and the homepage are submitted in sitemap.xml. Uploaded /s/:slug and /v/:slug/ URLs remain noindex and are excluded from every discovery submission. Wrapper pages include a visible “Share your HTML” CTA; its source=shared_preview value is stored only in the existing created event metadata alongside visibility, which makes product-led activation measurable without adding a new tracking service.

The canonical official MCP Registry identity is `dev.zhenjia/share-html`, authenticated by an Ed25519 public key published in zhenjia.dev DNS. Its descriptor is server.json, and its homepage link points agents to the live integration guide at /agents. The remote itself stays on the production workers.dev machine endpoint; human-facing pages and canonical URLs remain on sharehtml.zhenjia.dev. This split prevents Free-plan Bot Fight Mode on the branded zone from rejecting legitimate data-center MCP clients.

The manual Publish MCP Registry metadata workflow verifies the live manifest and MCP tool list, publishes the branded identity with the production Environment secret MCP_REGISTRY_PRIVATE_KEY, verifies the exact Registry projection, and only then marks the legacy io.github.lifeodyssey/share-html identity as deprecated with a migration message. Registry versions cannot currently be unpublished, so the workflow is deliberately idempotent and requires typing publish-dev-zhenjia after the production endpoint has been deployed and verified. Never place the DNS authentication private key in the repository, Worker configuration, logs, or workflow artifacts.

IndexNow uses an explicit first-party allowlist rather than Cloudflare Crawler Hints, because this hostname also serves private and unlisted URLs:

npm run growth:indexnow:dry-run

printf '%s' '<8-to-128-character-key>' | npx wrangler secret put INDEXNOW_KEY INDEXNOW_KEY=' ' npm run growth:indexnow

The Worker serves /{INDEXNOW_KEY}.txt only when that environment value is configured. The submit script refuses /s/, /v/, /api/, and cross-origin URLs before contacting the global IndexNow endpoint.

Stack

• Cloudflare Workers Static Assets for the app shell and API.
• Cloudflare R2 for uploaded HTML objects.
• Cloudflare Email Service for branded auth email delivery.
• Supabase Auth for magic-link users.
• Supabase Postgres for metadata, reports, events, and moderation state.
• React, Vite, and TypeScript for the frontend.

Local Setup

npm install

cp .env.example .dev.vars npm run build npm run dev

Set