Share HTML

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.