html-cloud 0.1.0 → 0.2.0

package/README.md

@@ -21,6 +21,13 @@ Pipe straight from a generator:
 my-report-tool | npx html-cloud -
 ```
 
+Changed the file? Update it in place — the share link you already sent out
+now shows the new version:
+
+```sh
+npx html-cloud ./report.html --update "https://html.cloud/e/kT4eN7xQ#9dKw2mPv…"
+```
+
 ## Why this exists
 
 AI tools (Claude, ChatGPT, Gemini) produce self-contained HTML — presentations,
@@ -45,6 +52,7 @@ Read the full explainer: [html.cloud/security](https://html.cloud/security)
 | Option | Description | Default |
 |---|---|---|
 | `--expires <7\|30\|never>` | Days until the link expires | `30` |
+| `--update <edit-link>` | Replace the content behind an existing share (pass the edit link a previous run printed). The share link stays the same; expiry is unchanged | — |
 | `--url <base>` | Server base URL (or `$HTML_CLOUD_URL`) | `https://html.cloud` |
 | `--no-copy` | Don't copy the share link to the clipboard | copy is on |
 
@@ -55,6 +63,10 @@ piped or scripted, the clipboard is never touched.
 Limits: one `.html`/`.htm` file (or stdin), max 10 MB. Expiry can be changed
 later from the edit link.
 
+An update never changes the keys: the edit key unwraps the document's existing
+view key locally, the new file is encrypted under that same key, and only the
+ciphertext is replaced. That is why the old share link keeps working.
+
 ## Honest threat model
 
 Anyone who has the share link can read the file — link handling is on you.

package/bin/html-cloud.js

@@ -12,13 +12,7 @@ import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { parseArgs } from 'node:util';
 
-import {
-  generateViewKey, generateEditKey, exportViewKey,
-  encryptBytes, encryptViewKeyWithEditKey, computeEditAuth,
-  packCiphertext, b64url,
-} from '../crypto.js';
-
-const MAX_SIZE = 10 * 1024 * 1024; // 10 MB, matches the server limit
+import { shareDocument, updateDocument, parseEditLink, MAX_SIZE } from '../share-core.js';
 
 const HELP = `
 html-cloud — private HTML file sharing, encrypted before upload
@@ -26,9 +20,13 @@ html-cloud — private HTML file sharing, encrypted before upload
 Usage:
   npx html-cloud <file.html> [options]
   cat page.html | npx html-cloud -
+  npx html-cloud <file.html> --update <edit-link>
 
 Options:
   --expires <7|30|never>  Days until the link expires (default: 30)
+  --update <edit-link>    Replace the content behind an existing share. Pass
+                          the private edit link a previous run printed; the
+                          share link stays the same
   --url <base>            Server base URL (default: https://html.cloud,
                           or $HTML_CLOUD_URL)
   --no-copy               Don't copy the share link to the clipboard
@@ -61,7 +59,8 @@ try {
   args = parseArgs({
     allowPositionals: true,
     options: {
-      expires:   { type: 'string', default: '30' },
+      expires:   { type: 'string' },
+      update:    { type: 'string' },
       url:       { type: 'string' },
       'no-copy': { type: 'boolean', default: false },
       help:      { type: 'boolean', short: 'h', default: false },
@@ -77,11 +76,26 @@ if (args.values.help || args.positionals.length === 0) {
 }
 
 const input = args.positionals[0];
-const expires = args.values.expires;
+
+// --update replaces an existing document: the edit link names the server and
+// the document, and expiry is left untouched (change it from the edit page).
+let editLink = null;
+if (args.values.update !== undefined) {
+  try {
+    editLink = parseEditLink(args.values.update);
+  } catch (err) {
+    fail(err.message.toLowerCase().replace(/\.$/, ''));
+  }
+  if (args.values.expires !== undefined) {
+    fail('--expires cannot be combined with --update (expiry is unchanged by an update)');
+  }
+}
+
+const expires = args.values.expires ?? '30';
 if (!['7', '30', 'never'].includes(expires)) {
   fail(`--expires must be 7, 30 or never (got "${expires}")`);
 }
-const baseUrl = (args.values.url ?? process.env.HTML_CLOUD_URL ?? 'https://html.cloud')
+const baseUrl = (args.values.url ?? editLink?.baseUrl ?? process.env.HTML_CLOUD_URL ?? 'https://html.cloud')
   .replace(/\/+$/, '');
 
 let plaintext;
@@ -98,54 +112,36 @@ if (input === '-') {
 if (plaintext.length === 0) fail('input is empty');
 if (plaintext.length > MAX_SIZE) fail('file is too large (max 10 MB)');
 
-// 1. Generate keys locally — these never leave this process except inside the printed links.
-const viewKey    = await generateViewKey();
-const editKeyRaw = await generateEditKey();
-const viewKeyRaw = await exportViewKey(viewKey);
-
-// 2. Encrypt content and wrap the view key with the edit key.
-const { iv, ciphertext } = await encryptBytes(viewKey, plaintext);
-const packed             = packCiphertext(iv, ciphertext);
-const encryptedViewKey   = await encryptViewKeyWithEditKey(viewKeyRaw, editKeyRaw);
-const editAuth           = await computeEditAuth(editKeyRaw);
-
-// 3. Upload ciphertext only.
-let res;
+// Encrypt locally and upload ciphertext only — shared with the website and the
+// browser extension via share-core.js. Keys are generated inside and returned
+// as URL fragments; they never leave this process except in the printed links.
+// An update re-uses the document's existing view key (unwrapped locally with
+// the edit key) so the share link that is already out there keeps working.
+let id, viewFrag, editFrag;
 try {
-  res = await fetch(`${baseUrl}/api/documents`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      ciphertext:         packed,
-      encrypted_view_key: encryptedViewKey,
-      edit_auth:          editAuth,
-      expires_in:         expires,
-      size:               plaintext.length,
-    }),
-  });
-} catch {
-  fail(`could not reach ${baseUrl}`);
-}
-
-if (!res.ok) {
-  if (res.status === 429) fail('too many uploads — please wait a few minutes and try again');
-  const err = await res.json().catch(() => ({}));
-  fail(err.error || err.message || `upload failed (HTTP ${res.status})`);
+  ({ id, viewFrag, editFrag } = editLink
+    ? await updateDocument(editLink.id, editLink.editFrag, plaintext, { baseUrl })
+    : await shareDocument(plaintext, { expiresIn: expires, baseUrl }));
+} catch (err) {
+  // fetch throws a TypeError when the host is unreachable; anything else is an
+  // Error we raised with a ready-to-print message (server error, rate limit…).
+  if (err instanceof TypeError) fail(`could not reach ${baseUrl}`);
+  fail(err.message.toLowerCase());
 }
 
-const { id } = await res.json();
-const shareLink = `${baseUrl}/v/${id}#${b64url(viewKeyRaw)}`;
+const shareLink = `${baseUrl}/v/${id}#${viewFrag}`;
 
 // Copy only in interactive use — never alter the clipboard from scripts/pipes.
 const copied = !args.values['no-copy'] && process.stdout.isTTY && copyToClipboard(shareLink);
 
-const expiryNote = expires === 'never' ? 'never expires' : `expires in ${expires} days`;
+const expiryNote = editLink ? 'content replaced, expiry unchanged'
+  : expires === 'never' ? 'never expires' : `expires in ${expires} days`;
 console.log(`
-Share link (anyone with this can view)${copied ? ' — copied to clipboard' : ''}:
+Share link (${editLink ? 'unchanged — ' : ''}anyone with this can view)${copied ? ' — copied to clipboard' : ''}:
   ${shareLink}
 
-Edit link (keep private — replace, change expiry, delete):
-  ${baseUrl}/e/${id}#${b64url(editKeyRaw)}
+Edit link (keep private — update, change expiry, delete):
+  ${baseUrl}/e/${id}#${editFrag}
 
 Encrypted locally with AES-256-GCM · ${expiryNote} · the server never saw the keys
 `.trim());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-cloud",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Share an HTML file privately from the command line. Encrypted with AES-256-GCM before upload — the server stores only ciphertext. No account.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "bin/",
     "crypto.js",
+    "share-core.js",
     "README.md"
   ],
   "engines": {
@@ -17,7 +18,10 @@
   "keywords": [
     "html",
     "share",
+    "file-sharing",
+    "cli",
     "encrypted",
+    "end-to-end-encryption",
     "zero-knowledge",
     "private",
     "claude-artifact",

package/share-core.js

@@ -0,0 +1,198 @@
+/**
+ * The one place that defines what "uploading a document" means.
+ *
+ * Browser (homepage), CLI (`npx html-cloud`) and the Chrome extension all share
+ * this single encrypt-then-upload sequence so the zero-knowledge wire contract
+ * can never silently diverge between clients — exactly like crypto.js.
+ *
+ * Lives in cli/ (next to crypto.js) so the npm package can ship it; the browser
+ * re-exports it via resources/js/share-core.js.
+ */
+
+import {
+  generateViewKey, generateEditKey, exportViewKey, importViewKey,
+  encryptBytes, encryptViewKeyWithEditKey, decryptViewKeyWithEditKey,
+  computeEditAuth, packCiphertext, b64url, b64urlDecode,
+} from './crypto.js';
+
+export const MAX_SIZE = 10 * 1024 * 1024; // 10 MB — also enforced server-side
+
+/**
+ * Cosmetic, URL-safe slug from a filename. It rides in the share link purely so
+ * previews show a title — never stored, never used to look up the document.
+ */
+export function slugify(name) {
+  return name
+    .replace(/\.html?$/i, '')
+    .normalize('NFKD').replace(/[̀-ͯ]/g, '') // strip accents: ä -> a
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60)
+    .replace(/-+$/, '');
+}
+
+/** Build the viewer path. A slug, when present, makes the link self-describing. */
+export function viewPath(id, slug) {
+  return slug ? `/v/${id}/${slug}` : `/v/${id}`;
+}
+
+/**
+ * Split an edit link (`https://host/e/{id}#{editKey}`) into the pieces a
+ * client needs to talk to the server about that document. The key stays in
+ * the fragment, exactly where the link carries it — it is never sent anywhere
+ * except as the `edit_key` proof inside an authorized write.
+ *
+ * @param {string} link
+ * @returns {{ baseUrl: string, id: string, editFrag: string }}
+ */
+export function parseEditLink(link) {
+  let url;
+  try {
+    url = new URL(String(link).trim());
+  } catch {
+    throw new Error('Not a valid edit link.');
+  }
+  const match    = url.pathname.match(/^\/e\/([A-Za-z0-9]+)\/?$/);
+  const editFrag = url.hash.slice(1);
+  if (!match || !editFrag) {
+    throw new Error('Not an edit link — expected the private https://html.cloud/e/{id}#{key} link.');
+  }
+  return { baseUrl: url.origin, id: match[1], editFrag };
+}
+
+/**
+ * Encrypt plaintext bytes into the server wire payload plus the two URL-fragment
+ * keys. Pure crypto, no network — keys are generated here and never leave except
+ * inside the returned fragment strings.
+ *
+ * @param {Uint8Array} plaintext
+ * @returns {{ payload: object, viewFrag: string, editFrag: string }}
+ */
+export async function encryptDocument(plaintext) {
+  const viewKey    = await generateViewKey();
+  const editKeyRaw = await generateEditKey();
+  const viewKeyRaw = await exportViewKey(viewKey);
+
+  const { iv, ciphertext } = await encryptBytes(viewKey, plaintext);
+
+  return {
+    payload: {
+      ciphertext:         packCiphertext(iv, ciphertext),
+      encrypted_view_key: await encryptViewKeyWithEditKey(viewKeyRaw, editKeyRaw),
+      edit_auth:          await computeEditAuth(editKeyRaw),
+      size:               plaintext.length,
+    },
+    viewFrag: b64url(viewKeyRaw),
+    editFrag: b64url(editKeyRaw),
+  };
+}
+
+/**
+ * Encrypt + upload a document. Returns the server id and the two fragment keys.
+ * The caller owns everything after this: building links, copying, remembering.
+ *
+ * @param {Uint8Array} plaintext
+ * @param {object}   [opts]
+ * @param {string}   [opts.expiresIn='30']  '7' | '30' | 'never'
+ * @param {boolean}  [opts.sensitive]       omitted from the body when undefined
+ * @param {string}   [opts.baseUrl='']      '' = same-origin; absolute for CLI/extension
+ * @param {object}   [opts.headers={}]      extra request headers (extension, CLI)
+ * @param {Function} [opts.fetchImpl=fetch] injectable fetch (background worker / Node)
+ * @returns {Promise<{ id: string, viewFrag: string, editFrag: string }>}
+ */
+export async function shareDocument(plaintext, {
+  expiresIn = '30',
+  sensitive,
+  baseUrl = '',
+  headers = {},
+  fetchImpl = fetch,
+} = {}) {
+  const { payload, viewFrag, editFrag } = await encryptDocument(plaintext);
+
+  const body = { ...payload, expires_in: expiresIn };
+  if (sensitive !== undefined) body.sensitive = sensitive;
+
+  const res = await fetchImpl(`${baseUrl}/api/documents`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    if (res.status === 429) {
+      throw new Error('Too many uploads — please wait a few minutes and try again.');
+    }
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.error || err.message || `Upload failed (HTTP ${res.status})`);
+  }
+
+  const { id } = await res.json();
+  return { id, viewFrag, editFrag };
+}
+
+/**
+ * Replace the content of an existing document. The new plaintext is encrypted
+ * under the document's *existing* view key (unwrapped locally with the edit
+ * key), so every share link already handed out keeps working unchanged. Only
+ * the edit-key holder can do this; the server still sees only ciphertext.
+ *
+ * @param {string}     id         Document id from the edit link.
+ * @param {string}     editFrag   base64url edit key from after the # in the edit link.
+ * @param {Uint8Array} plaintext
+ * @param {object}     [opts]                  Same transport options as shareDocument.
+ * @param {string}     [opts.baseUrl='']
+ * @param {object}     [opts.headers={}]
+ * @param {Function}   [opts.fetchImpl=fetch]
+ * @returns {Promise<{ id: string, viewFrag: string, editFrag: string }>}
+ */
+export async function updateDocument(id, editFrag, plaintext, {
+  baseUrl = '',
+  headers = {},
+  fetchImpl = fetch,
+} = {}) {
+  let editKeyRaw;
+  try {
+    editKeyRaw = b64urlDecode(editFrag);
+  } catch {
+    throw new Error('Invalid edit key.');
+  }
+
+  const current = await fetchImpl(`${baseUrl}/api/documents/${id}`, { headers });
+  if (current.status === 404) {
+    throw new Error('Document not found — it may have expired or been deleted.');
+  }
+  if (!current.ok) {
+    throw new Error(`Could not load document (HTTP ${current.status})`);
+  }
+  const { encrypted_view_key: encryptedViewKey } = await current.json();
+
+  let viewKeyRaw;
+  try {
+    viewKeyRaw = await decryptViewKeyWithEditKey(encryptedViewKey, editKeyRaw);
+  } catch {
+    throw new Error('Invalid edit key for this document.');
+  }
+
+  const viewKey = await importViewKey(viewKeyRaw);
+  const { iv, ciphertext } = await encryptBytes(viewKey, plaintext);
+
+  const res = await fetchImpl(`${baseUrl}/api/documents/${id}`, {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify({
+      ciphertext:         packCiphertext(iv, ciphertext),
+      encrypted_view_key: await encryptViewKeyWithEditKey(viewKeyRaw, editKeyRaw),
+      edit_key:           b64url(editKeyRaw),
+      size:               plaintext.length,
+    }),
+  });
+
+  if (!res.ok) {
+    if (res.status === 403) throw new Error('Invalid edit key for this document.');
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.error || err.message || `Update failed (HTTP ${res.status})`);
+  }
+
+  return { id, viewFrag: b64url(viewKeyRaw), editFrag: b64url(editKeyRaw) };
+}