html-cloud 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# html-cloud
+
+Share an HTML file privately from the command line — encrypted in your own
+process before anything is uploaded. No account, no project setup, no public URL.
+
+```sh
+npx html-cloud ./report.html
+```
+
+```
+Share link (anyone with this can view):
+  https://html.cloud/v/kT4eN7xQ#b3FvXyJq…
+
+Edit link (keep private — replace, change expiry, delete):
+  https://html.cloud/e/kT4eN7xQ#9dKw2mPv…
+```
+
+Pipe straight from a generator:
+
+```sh
+my-report-tool | npx html-cloud -
+```
+
+## Why this exists
+
+AI tools (Claude, ChatGPT, Gemini) produce self-contained HTML — presentations,
+reports, dashboards, prototypes. Sending one to a client or colleague usually
+means a public deploy or a clunky attachment. `html-cloud` gives you a private
+link in one command.
+
+## How the encryption works
+
+- The file is encrypted with **AES-256-GCM** locally, in this process.
+- The decryption key is placed after the `#` in the share link. URL fragments
+  are never sent to servers — by the browser or by this tool.
+- The server stores **only ciphertext**. It cannot read your file; nobody can
+  without your link. This is the same zero-knowledge model as the
+  [html.cloud](https://html.cloud) website, using the same
+  [open-source crypto module](https://github.com/viljamilaurila/html-cloud).
+
+Read the full explainer: [html.cloud/security](https://html.cloud/security)
+
+## Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--expires <7\|30\|never>` | Days until the link expires | `30` |
+| `--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 |
+
+In interactive use the share link is copied to your clipboard (`pbcopy`,
+`wl-copy`/`xclip`/`xsel`, or `clip`, whichever your OS has). When output is
+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.
+
+## Honest threat model
+
+Anyone who has the share link can read the file — link handling is on you.
+The server can delete or expire ciphertext but can never read it. For details
+and limitations, see [html.cloud/security](https://html.cloud/security).
+
+Requires Node 20+. MIT licensed.

package/bin/html-cloud.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * npx html-cloud ./file.html
+ *
+ * Encrypts an HTML file locally (AES-256-GCM) and uploads only the
+ * ciphertext to html.cloud. Keys are generated here and printed as URL
+ * fragments — they are never sent to the server.
+ */
+
+import { spawnSync } from 'node:child_process';
+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
+
+const HELP = `
+html-cloud — private HTML file sharing, encrypted before upload
+
+Usage:
+  npx html-cloud <file.html> [options]
+  cat page.html | npx html-cloud -
+
+Options:
+  --expires <7|30|never>  Days until the link expires (default: 30)
+  --url <base>            Server base URL (default: https://html.cloud,
+                          or $HTML_CLOUD_URL)
+  --no-copy               Don't copy the share link to the clipboard
+  -h, --help              Show this help
+
+The file is encrypted with AES-256-GCM in this process. The decryption
+key is placed after the # in the link — browsers never send that part
+to servers, and html.cloud stores only ciphertext.
+`.trim();
+
+function fail(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+/** Copy text via the OS clipboard command. Returns true on success. */
+function copyToClipboard(text) {
+  const candidates = process.platform === 'darwin' ? [['pbcopy']]
+    : process.platform === 'win32' ? [['clip']]
+    : [['wl-copy'], ['xclip', '-selection', 'clipboard'], ['xsel', '--clipboard', '--input']];
+  for (const [cmd, ...cmdArgs] of candidates) {
+    const r = spawnSync(cmd, cmdArgs, { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+    if (!r.error && r.status === 0) return true;
+  }
+  return false;
+}
+
+let args;
+try {
+  args = parseArgs({
+    allowPositionals: true,
+    options: {
+      expires:   { type: 'string', default: '30' },
+      url:       { type: 'string' },
+      'no-copy': { type: 'boolean', default: false },
+      help:      { type: 'boolean', short: 'h', default: false },
+    },
+  });
+} catch (err) {
+  fail(err.message);
+}
+
+if (args.values.help || args.positionals.length === 0) {
+  console.log(HELP);
+  process.exit(args.values.help ? 0 : 1);
+}
+
+const input = args.positionals[0];
+const expires = args.values.expires;
+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')
+  .replace(/\/+$/, '');
+
+let plaintext;
+if (input === '-') {
+  plaintext = new Uint8Array(readFileSync(0));
+} else {
+  if (!/\.html?$/i.test(input)) fail(`expected an .html or .htm file (got "${basename(input)}")`);
+  try {
+    plaintext = new Uint8Array(readFileSync(input));
+  } catch {
+    fail(`cannot read ${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;
+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})`);
+}
+
+const { id } = await res.json();
+const shareLink = `${baseUrl}/v/${id}#${b64url(viewKeyRaw)}`;
+
+// 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`;
+console.log(`
+Share link (anyone with this can view)${copied ? ' — copied to clipboard' : ''}:
+  ${shareLink}
+
+Edit link (keep private — replace, change expiry, delete):
+  ${baseUrl}/e/${id}#${b64url(editKeyRaw)}
+
+Encrypted locally with AES-256-GCM · ${expiryNote} · the server never saw the keys
+`.trim());

package/crypto.js

@@ -0,0 +1,121 @@
+/**
+ * Zero-knowledge crypto helpers using Web Crypto API.
+ *
+ * Key model:
+ *  viewKey  — AES-256-GCM CryptoKey used to encrypt/decrypt the HTML content.
+ *  editKey  — 32 random bytes. Encrypts the viewKey (stored server-side).
+ *             SHA-256(editKey) is stored as editAuth for authorization.
+ *
+ * URL model:
+ *  /v/{id}#{base64url(viewKey raw bytes)}
+ *  /e/{id}#{base64url(editKey)}
+ *
+ * The server sees only:
+ *  - Encrypted content blob
+ *  - viewKey encrypted with editKey (so edit page can re-derive viewKey)
+ *  - SHA-256(editKey) for authorization
+ */
+
+const ENC = 'AES-GCM';
+const KEY_LEN = 256;
+const IV_LEN = 12; // bytes for AES-GCM nonce
+
+export function b64url(bytes) {
+  // Chunked to avoid "maximum call stack" when spreading large arrays into String.fromCharCode
+  let str = '';
+  const CHUNK = 8192;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    str += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(str).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+export function b64urlDecode(str) {
+  str = str.replace(/-/g, '+').replace(/_/g, '/');
+  const pad = (4 - str.length % 4) % 4;
+  return Uint8Array.from(atob(str + '='.repeat(pad)), c => c.charCodeAt(0));
+}
+
+export async function generateViewKey() {
+  return crypto.subtle.generateKey({ name: ENC, length: KEY_LEN }, true, ['encrypt', 'decrypt']);
+}
+
+export async function generateEditKey() {
+  return crypto.getRandomValues(new Uint8Array(32));
+}
+
+export async function exportViewKey(key) {
+  const raw = await crypto.subtle.exportKey('raw', key);
+  return new Uint8Array(raw);
+}
+
+export async function importViewKey(rawBytes) {
+  return crypto.subtle.importKey('raw', rawBytes, { name: ENC }, false, ['encrypt', 'decrypt']);
+}
+
+/** Encrypt plaintext bytes → {iv, ciphertext} both as Uint8Array */
+export async function encryptBytes(viewKey, plaintext) {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const buf = await crypto.subtle.encrypt({ name: ENC, iv }, viewKey, plaintext);
+  return { iv, ciphertext: new Uint8Array(buf) };
+}
+
+/** Decrypt → Uint8Array */
+export async function decryptBytes(viewKey, iv, ciphertext) {
+  const buf = await crypto.subtle.decrypt({ name: ENC, iv }, viewKey, ciphertext);
+  return new Uint8Array(buf);
+}
+
+/**
+ * Encrypt the viewKey raw bytes using the editKey (raw bytes) as a password-derived AES key.
+ * Returns base64url string suitable for storing on the server.
+ */
+export async function encryptViewKeyWithEditKey(viewKeyRaw, editKeyRaw) {
+  const wrapKey = await crypto.subtle.importKey(
+    'raw', editKeyRaw, { name: ENC }, false, ['encrypt']
+  );
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LEN));
+  const enc = await crypto.subtle.encrypt({ name: ENC, iv }, wrapKey, viewKeyRaw);
+  // Store as iv:ciphertext base64url
+  const combined = new Uint8Array(IV_LEN + enc.byteLength);
+  combined.set(iv);
+  combined.set(new Uint8Array(enc), IV_LEN);
+  return b64url(combined);
+}
+
+/**
+ * Decrypt the viewKey using the editKey.
+ * Returns raw viewKey bytes.
+ */
+export async function decryptViewKeyWithEditKey(encryptedViewKeyB64, editKeyRaw) {
+  const combined = b64urlDecode(encryptedViewKeyB64);
+  const iv = combined.slice(0, IV_LEN);
+  const data = combined.slice(IV_LEN);
+  const wrapKey = await crypto.subtle.importKey(
+    'raw', editKeyRaw, { name: ENC }, false, ['decrypt']
+  );
+  const raw = await crypto.subtle.decrypt({ name: ENC, iv }, wrapKey, data);
+  return new Uint8Array(raw);
+}
+
+/** SHA-256(editKey) → hex string for server-side authorization */
+export async function computeEditAuth(editKeyRaw) {
+  const hash = await crypto.subtle.digest('SHA-256', editKeyRaw);
+  return Array.from(new Uint8Array(hash)).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Pack iv+ciphertext into a single base64url blob for wire transfer.
+ * Format: [12 bytes IV][N bytes ciphertext]
+ */
+export function packCiphertext(iv, ciphertext) {
+  const out = new Uint8Array(IV_LEN + ciphertext.length);
+  out.set(iv);
+  out.set(ciphertext, IV_LEN);
+  return b64url(out);
+}
+
+export function unpackCiphertext(packed) {
+  const bytes = b64urlDecode(packed);
+  return { iv: bytes.slice(0, IV_LEN), ciphertext: bytes.slice(IV_LEN) };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "html-cloud",
+  "version": "0.1.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": {
+    "html-cloud": "bin/html-cloud.js"
+  },
+  "files": [
+    "bin/",
+    "crypto.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "html",
+    "share",
+    "encrypted",
+    "zero-knowledge",
+    "private",
+    "claude-artifact",
+    "ai-generated"
+  ],
+  "homepage": "https://html.cloud",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/viljamilaurila/html-cloud.git",
+    "directory": "cli"
+  },
+  "license": "MIT"
+}