Skip to content

Share-Snapshot.md

Latest commit

 

History

History
124 lines (85 loc) · 6.77 KB

Share-Snapshot.md

File metadata and controls

124 lines (85 loc) · 6.77 KB
Raw

Share Snapshot

Share Snapshot creates a point-in-time copy of the active Document. Use it when a recipient needs to read or edit a copy without joining a Live Share room.

Share Snapshot is not real-time collaboration. Changes made by the sender or recipient after link creation do not synchronize.

Create a Snapshot

  1. Open the Document you want to share.
  2. Select Share Snapshot.
  3. Choose View only or Can edit.
  4. Select Share.
  5. Copy the generated URL and send it through a channel you trust.

The application selects URL-hash or Cloudflare KV storage automatically according to content size and encoded URL length.

Privacy: A Share Snapshot is a bearer link. Anyone who obtains the complete URL can open the capability it contains. There is no account check or recipient allowlist.

Access Modes

Mode Recipient experience What it does not provide
View only Opens a temporary tab in Preview with editing actions blocked Authentication, access revocation, or protection against link forwarding
Can edit Opens a temporary tab in Split view and lets the recipient edit that local copy Real-time synchronization or write access to the sender's original Document

The recipient's temporary snapshot tab is not written into normal Workspace tab storage. Closing or reloading can discard edits unless the recipient exports the Markdown.

The application blocks creating another Share Snapshot from a temporary snapshot. Only the host can create a snapshot from a Live Share Document.

Storage Modes

Property URL-hash snapshot Stored snapshot
URL form #share=<compressed-content> #id=<snapshot-id>
Selection rule Used when Markdown is below 3,000 UTF-8 bytes and the encoded URL is no longer than 4,096 characters Used at 3,000 bytes or more, or when the encoded URL exceeds 4,096 characters
Content location Compressed and base64url-encoded inside the link Cloudflare KV through /api/share
Retention No server-side record created by Markdown Viewer; the copied URL itself remains usable 90 days
Maximum content Constrained by practical browser, clipboard, and URL handling 8,000,000 characters
Early deletion Delete every copy of the link that you control Available through the API only when the caller retained the creation deletion token
Server request when opening The URL hash is not part of the normal HTTP request; the page processes it locally The application requests /api/share/<id>

The URL-hash title and access flag are also stored in the fragment. Hash fragments can still be exposed through copied messages, browser synchronization/history, extensions, screenshots, logs from surrounding tools, or a person who forwards the URL.

Stored Snapshot Record

The Share API stores:

  • Markdown content;
  • access mode;
  • sanitized title;
  • creation time;
  • character count; and
  • a hash of the deletion token.

The record is written to SHARE_KV with a 90-day time to live. The API response uses Cache-Control: no-store.

Creating a stored snapshot returns:

  • a random snapshot id;
  • a deletion token; and
  • the expiry duration.

The deletion token is returned only at creation. The stored record contains its SHA-256 hash, not the original token.

Delete a Stored Snapshot

The API supports:

DELETE /api/share/<id>
Content-Type: application/json

{"deleteToken":"<token returned at creation>"}

Important: The current Markdown Viewer UI does not display or export the deletion token and does not provide a Delete snapshot action. It keeps the token only in page memory while the generated link state exists. Closing/resetting the modal or leaving the session loses normal UI access to it.

An API client that needs early deletion must call POST /api/share, securely capture the deleteToken from the response, keep it separate from the shared URL, and later submit it to the DELETE route. Without the token, wait for the 90-day expiry.

Deleting a snapshot does not delete managed images, GIFs, or videos referenced by the Markdown. Managed media has separate content-addressed records and its own 90-day expiry.

Images and Other External Content

Share Snapshot copies Markdown, not every referenced resource.

  • Managed media remains available through its public-by-link URL until that media record expires.
  • External images, media, fonts, and links are requested from their original hosts.
  • Legacy inline data images increase the snapshot size and can force stored-snapshot mode.
  • Review comments and suggestions are not included.
  • A remote diagram fence is re-rendered by the recipient's browser and can send its source to a renderer.

Security Boundaries

  • Snapshot ids and encoded content are difficult to guess but are not authentication.
  • View only is enforced by the client interface; it does not encrypt or hide the Markdown from someone who controls their browser.
  • Origin checks restrict supported browser origins for API creation and access, but requests without an Origin header are accepted and bearer-link secrecy remains essential.
  • Allowed application origins include the production site, HTTPS *.markdownviewer.pages.dev previews, null, and local localhost/127.0.0.1 development origins.
  • Stored snapshots are not end-to-end encrypted by the application.
  • Cloudflare and the deployer can process normal platform and request logs.

Do not use Share Snapshot as a confidential-document access-control system.

Failure and Recovery

Symptom Likely cause Action
“Failed to create share link” Pako or /api/share unavailable, missing SHARE_KV, disallowed origin, network error, or oversized content Check the console/network request, configuration, origin, and 8,000,000-character limit
Stored link returns not found Invalid id, early deletion, or 90-day expiry Ask the sender for a new snapshot
Can edit copy disappeared Snapshot tabs are temporary Export Markdown before closing or reloading
Image is missing Managed-media expiry, unavailable external host, or blocked request Replace the resource and create a new snapshot
Remote diagram is missing Renderer unavailable, CSP restriction, or invalid source Check the renderer network request and fence syntax

See Troubleshooting for broader diagnostics.

API Summary

Method and route Purpose
POST /api/share Create a stored snapshot
GET /api/share/<id> Load a stored snapshot
DELETE /api/share/<id> Delete a stored snapshot with its deletion token
OPTIONS /api/share[/<id>] CORS preflight

Deployment details are in Configuration. For the product-wide data boundary, see Privacy and Security.