sdocs-dev 1.6.2 → 1.12.0

package/lib/safe.js

@@ -0,0 +1,200 @@
+// `sdoc safe` — verify the SDocs host is serving the bytes GitHub
+// published for its claimed commit.
+//
+//   1. Ask the host (`/trust/manifest`) what commit it is running.
+//   2. Fetch the authoritative fingerprint list for that commit from
+//      raw.githubusercontent.com/.../trust-manifests/<sha>.json.
+//   3. Download each file from the host, SHA-256 it, compare.
+//
+// Bytes come from the host. Fingerprints come from GitHub. The host
+// cannot produce a match it did not already publish to GitHub.
+//
+// Server-side request handling still cannot be verified by hashing.
+// `--audit` prints GitHub links to the files an auditor needs to read.
+
+const https  = require('https');
+const http   = require('http');
+const crypto = require('crypto');
+
+const { DEFAULT_URL } = require('./constants');
+
+// Server-side files an auditor needs to read to review what `sdoc safe`
+// cannot prove by hashing. Kept small on purpose.
+const AUDIT_SOURCE_FILES = [
+  'server.js',
+  'short-links/db.js',
+  'short-links/rate-limit.js',
+  'analytics/db.js',
+  'analytics/query.js',
+];
+
+const TRUST_RAW_BASE = 'https://raw.githubusercontent.com/espressoplease/SDocs/trust-manifests';
+
+function fetchJson(url) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const mod = u.protocol === 'https:' ? https : http;
+    mod.get(u, { timeout: 8000 }, (res) => {
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        reject(new Error('HTTP ' + res.statusCode + ' for ' + url));
+        res.resume();
+        return;
+      }
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try { resolve(JSON.parse(body)); } catch (e) { reject(new Error('invalid JSON from ' + url)); }
+      });
+    }).on('error', reject).on('timeout', function () { this.destroy(new Error('timeout')); });
+  });
+}
+
+function fetchBuffer(url) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const mod = u.protocol === 'https:' ? https : http;
+    mod.get(u, { timeout: 15000 }, (res) => {
+      if (res.statusCode < 200 || res.statusCode >= 300) {
+        reject(new Error('HTTP ' + res.statusCode));
+        res.resume();
+        return;
+      }
+      const chunks = [];
+      res.on('data', (c) => { chunks.push(c); });
+      res.on('end', () => { resolve(Buffer.concat(chunks)); });
+    }).on('error', reject).on('timeout', function () { this.destroy(new Error('timeout')); });
+  });
+}
+
+async function runSafe(opts) {
+  const base = (opts.url || process.env.SDOCS_URL || DEFAULT_URL).replace(/\/$/, '');
+  const jsonOut = !!opts.jsonFlag;
+  const audit = !!opts.auditFlag;
+  const rawBase = (opts.rawBase || process.env.SDOCS_TRUST_RAW || TRUST_RAW_BASE).replace(/\/$/, '');
+
+  let serverReport;
+  try {
+    serverReport = await fetchJson(base + '/trust/manifest');
+  } catch (e) {
+    if (jsonOut) { console.log(JSON.stringify({ ok: false, error: 'server_fetch_failed', message: e.message })); }
+    else { console.error('sdoc safe: could not fetch ' + base + '/trust/manifest - ' + e.message); }
+    process.exit(2);
+  }
+  const commit = serverReport.commit;
+  if (!commit || commit === 'unknown') {
+    if (jsonOut) { console.log(JSON.stringify({ ok: false, error: 'no_commit_reported' })); }
+    else { console.error('sdoc safe: host did not report a commit.'); }
+    process.exit(2);
+  }
+
+  const manifestUrl = rawBase + '/' + commit + '.json';
+  let manifest;
+  try {
+    manifest = await fetchJson(manifestUrl);
+  } catch (e) {
+    const pending = /HTTP 404/.test(e.message);
+    if (jsonOut) {
+      console.log(JSON.stringify({
+        ok: false,
+        error: pending ? 'manifest_not_yet_published' : 'manifest_fetch_failed',
+        host: base, commit, manifestUrl, message: e.message,
+      }));
+    } else if (pending) {
+      console.error('sdoc safe: no fingerprint list published on GitHub for commit ' + commit.slice(0, 7) + ' yet.');
+      console.error('           (publish-manifest.yml runs on push to main; give it a minute.)');
+      console.error('           looked for: ' + manifestUrl);
+    } else {
+      console.error('sdoc safe: could not fetch ' + manifestUrl + ' - ' + e.message);
+    }
+    process.exit(pending ? 2 : 3);
+  }
+
+  if (!Array.isArray(manifest.files) || manifest.files.length === 0) {
+    if (jsonOut) { console.log(JSON.stringify({ ok: false, error: 'manifest_has_no_files', manifestUrl })); }
+    else { console.error('sdoc safe: GitHub manifest at ' + manifestUrl + ' has no files array.'); }
+    process.exit(3);
+  }
+
+  const results = [];
+  let ok = 0, fail = 0;
+  for (const file of manifest.files) {
+    const fileUrl = base + '/public' + file.path;
+    try {
+      const buf = await fetchBuffer(fileUrl);
+      const got = crypto.createHash('sha256').update(buf).digest('hex');
+      const match = got === file.sha256;
+      results.push({ path: file.path, bytes: file.bytes, expected: file.sha256, got, match });
+      if (match) ok++; else fail++;
+    } catch (e) {
+      results.push({ path: file.path, bytes: file.bytes, expected: file.sha256, error: e.message, match: false });
+      fail++;
+    }
+  }
+
+  const repo = manifest.repo || 'https://github.com/espressoplease/SDocs';
+  const auditLinks = audit ? AUDIT_SOURCE_FILES.map(f => ({
+    file: f,
+    url: repo + '/blob/' + commit + '/' + f,
+  })) : null;
+
+  if (jsonOut) {
+    console.log(JSON.stringify({
+      ok: fail === 0,
+      host: base,
+      commit,
+      builtAt: manifest.builtAt,
+      manifestUrl,
+      totals: { ok, fail, total: results.length },
+      files: results,
+      audit: auditLinks,
+      unverified: {
+        note: 'Server-side code (request handling, storage) cannot be verified by hashing. Read the source files listed under audit to review what a malicious operator could theoretically modify.',
+        files: AUDIT_SOURCE_FILES,
+      },
+    }, null, 2));
+  } else {
+    console.log('');
+    console.log('  sdoc safe - verifying ' + base);
+    console.log('  commit    ' + commit);
+    console.log('  built at  ' + (manifest.builtAt || '?'));
+    console.log('  tree      ' + repo + '/tree/' + commit);
+    console.log('  list      ' + manifestUrl);
+    console.log('');
+    for (const r of results) {
+      const glyph = r.match ? '✓' : '✗';
+      const line = '  ' + glyph + ' ' + r.path.padEnd(32) + ' ' + (r.match ? 'match' : (r.error || 'MISMATCH'));
+      console.log(line);
+    }
+    console.log('');
+    if (fail === 0) {
+      console.log('  ✓ ' + ok + ' / ' + results.length + ' files match the list GitHub published for this commit.');
+      console.log('    Bytes came from this host; fingerprints came from GitHub.');
+    } else {
+      console.log('  ✗ ' + fail + ' / ' + results.length + ' files FAILED to match GitHub\'s list for this commit.');
+      console.log('    The host is serving different bytes than GitHub published for ' + commit.slice(0, 7) + '.');
+    }
+    console.log('');
+    console.log('  What this does not prove:');
+    console.log('    Server-side request handling cannot be verified by hashing alone.');
+    console.log('    The only way to audit it is to read the source. Start here:');
+    console.log('');
+    for (const f of AUDIT_SOURCE_FILES) {
+      console.log('    ' + repo + '/blob/' + commit + '/' + f);
+    }
+    console.log('');
+    if (!audit) {
+      console.log('  Re-run with --audit for machine-readable audit pointers, or --json for full output.');
+      console.log('');
+    }
+  }
+
+  process.exit(fail === 0 ? 0 : 1);
+}
+
+module.exports = {
+  AUDIT_SOURCE_FILES,
+  TRUST_RAW_BASE,
+  fetchJson,
+  fetchBuffer,
+  runSafe,
+};

package/lib/setup.js

@@ -0,0 +1,332 @@
+// `sdoc setup`, `sdoc refresh`, `sdoc auto-update`, and the implicit
+// post-command refresh that keeps agent files in sync as new sdoc
+// versions ship.
+//
+// runSetup: first-run interactive flow. Detects agent configs, writes
+//   the block into the ones the user agrees to.
+// runRefresh: unconditional refresh of every agent file that already
+//   has a recognised block.
+// runAutoUpdateSubcommand: flips state.autoInstallUpdates.
+// maybeAutoRefresh: called after every successful command. Quiet, only
+//   touches files whose existing block we already manage.
+
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+
+const {
+  AGENT_BLOCK_VERSION,
+  AGENT_BLOCK_BODY,
+  compareVersions,
+  readSetupState,
+  writeSetupState,
+  implicitConsentState,
+} = require('./agent-block');
+
+const { upgradeCommand } = require('./update-check');
+
+const {
+  detectAgents,
+  fileHasBlock,
+  writeBookendedBlock,
+  refreshAllAgentFiles,
+  printRefreshSummary,
+} = require('./agent-files');
+
+const { VERSION, AGENT_CHANGES_URL } = require('./constants');
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, a => { rl.close(); resolve(a.trim().toLowerCase()); });
+  });
+}
+
+async function askAutoInstallConsent() {
+  console.log('\nAuto-install sdoc updates when available?');
+  console.log('');
+  console.log('This runs `' + upgradeCommand() + '` on your behalf when a new');
+  console.log('version ships. The output includes a source-diff link so you');
+  console.log('(or your agent) can verify what was installed.');
+  console.log('');
+  console.log('Recommended if you mostly use sdoc through coding agents.');
+  console.log('');
+  console.log('Change any time with `sdoc auto-update on` / `sdoc auto-update off`.\n');
+  const a = await ask('Enable? [Y/n] ');
+  return !a || a === 'y' || a === 'yes';
+}
+
+async function askAutoRefreshConsent() {
+  console.log('\nKeep this block updated on future sdoc upgrades?');
+  console.log('');
+  console.log('When sdoc adds a feature we sometimes update this section so');
+  console.log('your agent learns about it. Each time the block changes we');
+  console.log(`print a notice with a link to ${AGENT_CHANGES_URL}`);
+  console.log('showing the exact delta - the new wording, and why it changed.');
+  console.log('');
+  console.log('Re-run `sdoc setup` any time to change this.\n');
+  const a = await ask('Enable? [Y/n] ');
+  return !a || a === 'y' || a === 'yes';
+}
+
+async function runSetup({ force = false, yes = false } = {}) {
+  if (!force) {
+    if (!process.stdout.isTTY || !process.stdin.isTTY) return;
+    if (process.env.CI || process.env.SDOCS_NO_SETUP) return;
+    if (readSetupState()) return;
+  }
+
+  // ── --yes (non-interactive) path ───────────────────────────
+  // Pulled out of the detection branch so this is the SINGLE place that
+  // handles every --yes case: fresh install, old block (upgrade), legacy
+  // open-marker (migration), already-current (no-op), no agents at all.
+  // Idempotent by design - an agent or user can re-paste the install prompt
+  // any number of times and the result is a current block in every detected
+  // config, or a clean "nothing to do".
+  if (yes) {
+    // Step 1: refresh any existing outdated / legacy blocks. This is what
+    // closes the gap where re-running setup --yes used to silently no-op
+    // on a stale install.
+    const refreshResults = refreshAllAgentFiles();
+    const refreshedFiles = refreshResults.filter(r => r.changed).map(r => r.path);
+    if (refreshResults.some(r => r.changed)) printRefreshSummary(refreshResults);
+
+    // Step 2: any agent whose config dir exists but doesn't yet have a
+    // block gets one written. Re-detect after refresh because the refresh
+    // step may have flipped some files from "needs block" to "has block".
+    const stillMissing = detectAgents().filter(t => !fileHasBlock(t.filePath));
+    const writtenTo = [];
+    for (const t of stillMissing) {
+      try { writeBookendedBlock(t.filePath); writtenTo.push(t.filePath); console.log(`✓ ${t.name}: ${t.filePath}`); }
+      catch (e) { console.error(`✗ ${t.name}: ${e.message}`); }
+    }
+
+    const affected = [...new Set([...writtenTo, ...refreshedFiles])];
+
+    if (affected.length === 0) {
+      const anyAgentDir = detectAgents().length > 0;
+      writeSetupState({
+        setupCompleted: new Date().toISOString(),
+        writtenTo: [], declined: !anyAgentDir,
+        autoRefreshAgentFiles: anyAgentDir,
+        autoInstallUpdates: false,
+        lastRunVersion: VERSION,
+      });
+      if (anyAgentDir) {
+        console.log('All SDocs agent blocks already at current version. Nothing to do.');
+      } else {
+        console.log('No coding-agent configs detected. Nothing to write.');
+        console.log('Re-run `sdoc setup` (interactive) if you want to include opencode.');
+      }
+      return;
+    }
+
+    writeSetupState({
+      setupCompleted: new Date().toISOString(),
+      writtenTo: affected, declined: false,
+      autoRefreshAgentFiles: true,
+      autoInstallUpdates: false,
+      lastRunVersion: VERSION,
+    });
+    const n = affected.length;
+    const verb = writtenTo.length && refreshedFiles.length
+      ? 'Wrote/refreshed'
+      : (writtenTo.length ? 'Wrote' : 'Refreshed');
+    console.log(`\nDone. ${verb} SDocs block in ${n} ${n === 1 ? 'file' : 'files'}.`);
+    return;
+  }
+
+  const detected = detectAgents().filter(t => !fileHasBlock(t.filePath));
+
+  if (detected.length === 0) {
+    const opencodeAlreadyDone = fileHasBlock(path.join(os.homedir(), '.config', 'opencode', 'AGENTS.md'));
+    if (opencodeAlreadyDone) {
+      writeSetupState({
+        setupCompleted: new Date().toISOString(),
+        writtenTo: [], declined: false,
+        autoRefreshAgentFiles: true, autoInstallUpdates: false,
+        lastRunVersion: VERSION,
+      });
+      console.log('\nSDocs is already set up in all detected agent configs. Nothing to do.');
+      return;
+    }
+    console.log('\n✨─────── SDocs setup ───────✨');
+    console.log('First run only - wire SDocs into your CLI coding agents.\n');
+    console.log('No coding-agent configs detected.');
+    const a = await ask('Do you use opencode? [y/N] ');
+    const writtenTo = [];
+    let autoRefresh = false;
+    let autoInstall = false;
+    if (a === 'y' || a === 'yes') {
+      const target = path.join(os.homedir(), '.config', 'opencode', 'AGENTS.md');
+      try { writeBookendedBlock(target); writtenTo.push(target); console.log(`✓ Wrote SDocs section to ${target}`); }
+      catch (e) { console.error(`Failed to write ${target}: ${e.message}`); }
+      autoRefresh = await askAutoRefreshConsent();
+      autoInstall = await askAutoInstallConsent();
+      console.log('Done. Run `sdoc setup` any time to revisit.');
+    } else {
+      console.log('Skipped. Run `sdoc setup` any time to revisit.');
+    }
+    writeSetupState({
+      setupCompleted: new Date().toISOString(),
+      writtenTo, declined: writtenTo.length === 0,
+      autoRefreshAgentFiles: autoRefresh,
+      autoInstallUpdates: autoInstall,
+      lastRunVersion: VERSION,
+    });
+    return;
+  }
+
+  console.log('\n✨─────── SDocs setup ───────✨');
+  console.log('First run only - wire SDocs into your CLI coding agents.\n');
+  console.log('Detected: ' + detected.map(t => t.name).join(', '));
+  console.log('\nWill append a short SDocs section to:');
+  for (const t of detected) console.log('  ' + t.filePath);
+  console.log('\nThese files are loaded into every conversation across all your');
+  console.log('projects, so SDocs becomes available no matter where you\'re working.');
+  console.log('');
+  console.log('You can ask your agent things like:');
+  console.log('  "write up the plan and sdoc it to me"');
+  console.log('  "explain async/await to me in a sdoc"');
+  console.log('  "draft the release notes as a sdoc I can share"');
+  console.log('');
+  console.log('This is the best way to work with SDocs');
+  const RULE = '═'.repeat(36);
+  console.log(`\n═══════════ Block to add ═══════════`);
+  console.log(AGENT_BLOCK_BODY.trim());
+  console.log(RULE);
+
+  const a = await ask('\nAdd to all? [Y/n/skip] ');
+  const skipped = a === 'skip' || (a && a !== 'y' && a !== 'yes');
+  if (skipped) {
+    writeSetupState({
+      setupCompleted: new Date().toISOString(),
+      writtenTo: [], declined: true,
+      autoRefreshAgentFiles: false, autoInstallUpdates: false,
+      lastRunVersion: VERSION,
+    });
+    console.log('Skipped. Run `sdoc setup` any time to revisit.');
+    return;
+  }
+
+  const writtenTo = [];
+  for (const t of detected) {
+    try { writeBookendedBlock(t.filePath); writtenTo.push(t.filePath); console.log(`✓ ${t.name}: ${t.filePath}`); }
+    catch (e) { console.error(`✗ ${t.name}: ${e.message}`); }
+  }
+
+  const autoRefresh = writtenTo.length > 0 ? await askAutoRefreshConsent() : false;
+  const autoInstall = writtenTo.length > 0 ? await askAutoInstallConsent() : false;
+
+  writeSetupState({
+    setupCompleted: new Date().toISOString(),
+    writtenTo, declined: false,
+    autoRefreshAgentFiles: autoRefresh,
+    autoInstallUpdates: autoInstall,
+    lastRunVersion: VERSION,
+  });
+  console.log('\nDone. Run `sdoc setup` any time to revisit.');
+}
+
+// Auto-refresh existing agent files when the binary version is newer than the
+// version that last ran. No prompt: the user already consented during setup.
+// Bails on downgrades (block version > shipped version), errors, or partial
+// failures (lastRunVersion only advances when every changed file succeeded).
+async function maybeAutoRefresh() {
+  if (process.env.SDOCS_NO_REFRESH) return;
+  let state = readSetupState();
+
+  // Implicit-consent migration for users who have a recognised SDocs block in
+  // an agent file but no `~/.sdocs/setup.json`. This is the pre-1.5.0 install
+  // path. `refreshContent` only signals `changed` for a block whose exact
+  // shape we wrote (legacy JoshInLisbon terminator, or our bookend markers);
+  // anything else is left untouched, so a user who deleted the block or
+  // hand-edited it doesn't get state silently created.
+  if (!state) {
+    const results = refreshAllAgentFiles();
+    const next = implicitConsentState(results, VERSION);
+    if (!next) return;
+    printRefreshSummary(results);
+    writeSetupState(next);
+    return;
+  }
+
+  if (!state.autoRefreshAgentFiles) return;
+  if (compareVersions(VERSION, state.lastRunVersion) <= 0) return;
+
+  const results = refreshAllAgentFiles();
+  const anyChanged = results.some(r => r.changed);
+  if (anyChanged) printRefreshSummary(results);
+
+  const anyError = results.some(r => r.error);
+  if (!anyError) {
+    writeSetupState({ ...state, lastRunVersion: VERSION });
+  }
+}
+
+// `sdoc refresh` — unconditional agent-block refresh. Useful for users whose
+// setup.json was never written (pre-1.5.0 installs) or has been deleted, and
+// for agents that want to trigger the migration explicitly without going
+// through the interactive setup flow.
+async function runRefresh() {
+  const existing = readSetupState();
+  const results = refreshAllAgentFiles();
+  const changed = results.filter(r => r.changed);
+  const errors  = results.filter(r => r.error);
+  const current = results.filter(r => r.reason === 'current');
+  const blocksPresent = changed.length + current.length;
+
+  printRefreshSummary(results);
+
+  if (changed.length === 0 && errors.length === 0) {
+    if (blocksPresent === 0) {
+      console.log('No SDocs blocks found in any agent file. Run `sdoc setup` to add one.');
+      return;
+    }
+    console.log(`All SDocs agent blocks already at v${AGENT_BLOCK_VERSION}.`);
+  }
+
+  if (errors.length > 0) return;
+
+  if (blocksPresent === 0 && !existing) return;
+
+  writeSetupState({
+    setupCompleted: existing?.setupCompleted || new Date().toISOString(),
+    writtenTo: [...changed, ...current].map(r => r.path),
+    declined: false,
+    autoRefreshAgentFiles: existing ? existing.autoRefreshAgentFiles !== false : true,
+    autoInstallUpdates: existing?.autoInstallUpdates ?? false,
+    lastRunVersion: VERSION,
+  });
+}
+
+// `sdoc auto-update on|off|status` — flips state.autoInstallUpdates.
+function runAutoUpdateSubcommand(arg) {
+  let state = readSetupState();
+  if (!state) {
+    console.log('Run `sdoc setup` first to configure auto-update.');
+    return;
+  }
+  if (arg === 'on') {
+    writeSetupState({ ...state, autoInstallUpdates: true });
+    console.log('✓ Auto-install of sdoc updates: on');
+    return;
+  }
+  if (arg === 'off') {
+    writeSetupState({ ...state, autoInstallUpdates: false });
+    console.log('✓ Auto-install of sdoc updates: off');
+    return;
+  }
+  console.log(`Auto-install of sdoc updates: ${state.autoInstallUpdates ? 'on' : 'off'}`);
+  console.log('Use `sdoc auto-update on` or `sdoc auto-update off` to change.');
+}
+
+module.exports = {
+  ask,
+  askAutoInstallConsent,
+  askAutoRefreshConsent,
+  runSetup,
+  runRefresh,
+  runAutoUpdateSubcommand,
+  maybeAutoRefresh,
+};

package/lib/short-link.js

@@ -0,0 +1,105 @@
+// Encrypted short links: /s/<id>#k=<key>.
+//
+// The CLI compresses + encrypts the document with a freshly generated
+// AES-256-GCM key, POSTs the ciphertext to /api/short, then assembles a
+// URL whose key lives in the fragment (which browsers don't send to
+// servers). The key never leaves this process. Trade-offs vs the
+// default `#md=` form are documented in HELP.
+
+const https  = require('https');
+const http   = require('http');
+const zlib   = require('zlib');
+const crypto = require('crypto');
+
+const SDocYaml   = require('../shared/sdocs-yaml.js');
+const SDocStyles = require('../shared/sdocs-styles.js');
+const { slugify } = require('../shared/sdocs-slugify.js');
+
+const { toBase64Url } = require('./url');
+const { DEFAULT_URL } = require('./constants');
+
+// The blob format (nonce(12) + ciphertext + tag(16)) matches the browser.
+function compressAndEncrypt(content) {
+  const compressed = zlib.brotliCompressSync(Buffer.from(content, 'utf-8'), {
+    params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 11 }
+  });
+  const keyBytes = crypto.randomBytes(32);
+  const nonce = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', keyBytes, nonce);
+  const ct = Buffer.concat([cipher.update(compressed), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  const blob = Buffer.concat([nonce, ct, tag]);
+  return { keyBytes, cipherB64url: toBase64Url(blob) };
+}
+
+function uploadShortLink(ciphertextB64, baseUrl) {
+  return new Promise((resolve, reject) => {
+    const u = new URL('/api/short', baseUrl);
+    const isHttps = u.protocol === 'https:';
+    const mod = isHttps ? https : http;
+    const payload = JSON.stringify({ ciphertext: ciphertextB64 });
+    const req = mod.request({
+      method: 'POST',
+      protocol: u.protocol,
+      hostname: u.hostname,
+      port: u.port || (isHttps ? 443 : 80),
+      path: u.pathname,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+      },
+      timeout: 10000,
+    }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        let json;
+        try { json = JSON.parse(body); } catch (_) { json = null; }
+        if (res.statusCode >= 200 && res.statusCode < 300 && json && json.id) {
+          resolve(json.id);
+        } else {
+          const err = (json && json.error) || ('http_' + res.statusCode);
+          reject(new Error(err));
+        }
+      });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(new Error('timeout')); });
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function buildShortUrl(content, opts) {
+  if (!content) throw new Error('short link requires file content');
+
+  // Mirror the hash-build's default-stripping so the encrypted payload is
+  // identical to what the browser would encode.
+  const parsed = SDocYaml.parseFrontMatter(content);
+  if (parsed.meta && parsed.meta.styles) {
+    const stripped = SDocStyles.stripStyleDefaults(parsed.meta.styles);
+    if (Object.keys(stripped).length > 0) parsed.meta.styles = stripped;
+    else delete parsed.meta.styles;
+    content = SDocYaml.serializeFrontMatter(parsed.meta) + '\n' + parsed.body;
+  }
+
+  const baseUrl = opts.url || process.env.SDOCS_URL || DEFAULT_URL;
+  const { keyBytes, cipherB64url } = compressAndEncrypt(content);
+  const id = await uploadShortLink(cipherB64url, baseUrl);
+  const keyB64 = toBase64Url(keyBytes);
+
+  const params = new URLSearchParams();
+  params.set('k', keyB64);
+  const mode = opts.mode;
+  if (mode && mode !== 'read') params.set('mode', mode);
+  if (opts.theme) params.set('theme', opts.theme);
+  if (opts.section) params.set('sec', slugify(opts.section));
+
+  return `${baseUrl}/s/${id}#${params.toString()}`;
+}
+
+module.exports = {
+  compressAndEncrypt,
+  uploadShortLink,
+  buildShortUrl,
+};