sdocs-dev 1.15.0 → 1.19.2

package/lib/cloud-credentials.js

@@ -0,0 +1,380 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync, spawnSync } = require('child_process');
+
+const KEYCHAIN_SERVICE = 'org.smalldocs.cloud';
+const KEYCHAIN_RECORD_VERSION = 2;
+const KEYCHAIN_EXPECT = [
+  'log_user 0',
+  'set timeout 15',
+  'set secret [gets stdin]',
+  'spawn security add-generic-password -U -s "' + KEYCHAIN_SERVICE + '" -a "$env(SDOCS_KEYCHAIN_ACCOUNT)" -w',
+  'expect -re {password.*item.*:}',
+  'send -- "$secret\\r"',
+  'expect -re {retype.*item.*:}',
+  'send -- "$secret\\r"',
+  'expect eof',
+  'catch wait result',
+  'exit [lindex $result 3]',
+].join('\n');
+const DPAPI_PROTECT = [
+  '$ErrorActionPreference = "Stop"',
+  'Add-Type -AssemblyName System.Security',
+  '$plain = [Console]::In.ReadToEnd()',
+  '$bytes = [Text.Encoding]::UTF8.GetBytes($plain)',
+  '$cipher = [Security.Cryptography.ProtectedData]::Protect($bytes, $null, [Security.Cryptography.DataProtectionScope]::CurrentUser)',
+  '[Console]::Out.Write([Convert]::ToBase64String($cipher))',
+].join('; ');
+const DPAPI_UNPROTECT = [
+  '$ErrorActionPreference = "Stop"',
+  'Add-Type -AssemblyName System.Security',
+  '$encoded = [Console]::In.ReadToEnd()',
+  '$cipher = [Convert]::FromBase64String($encoded)',
+  '$plain = [Security.Cryptography.ProtectedData]::Unprotect($cipher, $null, [Security.Cryptography.DataProtectionScope]::CurrentUser)',
+  '[Console]::Out.Write([Text.Encoding]::UTF8.GetString($plain))',
+].join('; ');
+
+function cloudDir() {
+  return path.join(process.env.SDOCS_HOME || path.join(os.homedir(), '.sdocs'), 'cloud');
+}
+
+function credentialFile() { return path.join(cloudDir(), 'credentials.json'); }
+function dpapiCredentialFile(origin) {
+  if (!origin) return path.join(cloudDir(), 'credentials.dpapi');
+  const id = crypto.createHash('sha256').update(origin).digest('hex');
+  return path.join(cloudDir(), 'credentials-' + id + '.dpapi');
+}
+function encryptedCredentialFile(origin, generation) {
+  const id = crypto.createHash('sha256').update(origin).digest('hex');
+  return path.join(cloudDir(), 'credentials-' + id +
+    (generation ? '-' + generation : '') + '.enc');
+}
+
+function atomicWriteRaw(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(path.dirname(file), 0o700); } catch (_) {}
+  const temporary = file + '.tmp-' + process.pid + '-' + crypto.randomBytes(4).toString('hex');
+  fs.writeFileSync(temporary, value, { mode: 0o600 });
+  try { fs.chmodSync(temporary, 0o600); } catch (_) {}
+  fs.renameSync(temporary, file);
+}
+
+function atomicWrite(file, value) {
+  atomicWriteRaw(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+function readJson(file) {
+  try {
+    const value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch (_) { return {}; }
+}
+
+function readFileStore() { return readJson(credentialFile()); }
+
+function keychainAccount(origin) {
+  return Buffer.from(origin).toString('base64url');
+}
+
+function keychainReadAccount(account) {
+  try {
+    return execFileSync('security', ['find-generic-password', '-s', KEYCHAIN_SERVICE,
+      '-a', account, '-w'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch (error) {
+    if (error && Number(error.status) === 44) return null;
+    throw new Error('Could not read the SmallDocs Cloud credential key from macOS Keychain.');
+  }
+}
+
+function keychainWriteAccount(account, value, execute) {
+  const run = execute || spawnSync;
+  const result = run('/usr/bin/expect', ['-c', KEYCHAIN_EXPECT], {
+    input: value + '\n',
+    encoding: 'utf8',
+    env: Object.assign({}, process.env, { SDOCS_KEYCHAIN_ACCOUNT: account }),
+    stdio: ['pipe', 'ignore', 'ignore'],
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error('Could not save the Cloud credential key to macOS Keychain.');
+  }
+}
+
+function keychainDeleteAccount(account) {
+  try {
+    execFileSync('security', ['delete-generic-password', '-s', KEYCHAIN_SERVICE,
+      '-a', account], { stdio: 'ignore' });
+  } catch (_) {}
+}
+
+function keychainOperations(operations) {
+  if (operations && typeof operations === 'object') return operations;
+  if (typeof operations === 'function') {
+    return {
+      read() { return null; },
+      write(account, value) { keychainWriteAccount(account, value, operations); },
+      remove() {},
+    };
+  }
+  return {
+    read: keychainReadAccount,
+    write(account, value) { keychainWriteAccount(account, value); },
+    remove: keychainDeleteAccount,
+  };
+}
+
+function parseKeychainRecord(raw) {
+  if (!raw) return null;
+  try {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+    if (value.v === KEYCHAIN_RECORD_VERSION && typeof value.key === 'string') {
+      const key = Buffer.from(value.key, 'base64url');
+      const generation = value.file == null ? null : String(value.file);
+      if (key.length !== 32 || key.toString('base64url') !== value.key ||
+          (generation != null && !/^[a-f0-9]{16}$/.test(generation))) return null;
+      return { type: 'key', key, generation };
+    }
+    return { type: 'legacy', credential: value };
+  } catch (_) { return null; }
+}
+
+function encryptCredential(credential, key) {
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(JSON.stringify(credential), 'utf8'),
+    cipher.final(),
+  ]);
+  return JSON.stringify({
+    v: 1,
+    iv: iv.toString('base64url'),
+    tag: cipher.getAuthTag().toString('base64url'),
+    ciphertext: ciphertext.toString('base64url'),
+  }) + '\n';
+}
+
+function decryptCredential(value, key) {
+  const envelope = JSON.parse(value);
+  if (!envelope || envelope.v !== 1 || typeof envelope.iv !== 'string' ||
+      typeof envelope.tag !== 'string' || typeof envelope.ciphertext !== 'string') return null;
+  const iv = Buffer.from(envelope.iv, 'base64url');
+  const tag = Buffer.from(envelope.tag, 'base64url');
+  if (iv.length !== 12 || tag.length !== 16) return null;
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
+  decipher.setAuthTag(tag);
+  const plain = Buffer.concat([
+    decipher.update(Buffer.from(envelope.ciphertext, 'base64url')),
+    decipher.final(),
+  ]).toString('utf8');
+  const credential = JSON.parse(plain);
+  return credential && typeof credential === 'object' && !Array.isArray(credential) ? credential : null;
+}
+
+function keychainLoad(origin, operations) {
+  const ops = keychainOperations(operations);
+  const record = parseKeychainRecord(ops.read(keychainAccount(origin)));
+  if (!record) return null;
+  if (record.type === 'legacy') return record.credential;
+  try {
+    return decryptCredential(fs.readFileSync(
+      encryptedCredentialFile(origin, record.generation), 'utf8'), record.key);
+  } catch (_) { return null; }
+}
+
+function keychainSave(origin, credential, operations) {
+  const ops = keychainOperations(operations);
+  const account = keychainAccount(origin);
+  const current = parseKeychainRecord(ops.read(account));
+  const key = current && current.type === 'key' ? current.key : crypto.randomBytes(32);
+  const generation = current && current.type === 'key'
+    ? current.generation : crypto.randomBytes(8).toString('hex');
+  const file = encryptedCredentialFile(origin, generation);
+  atomicWriteRaw(file, encryptCredential(credential, key));
+  if (!current || current.type !== 'key') {
+    const record = JSON.stringify({ v: KEYCHAIN_RECORD_VERSION,
+      key: key.toString('base64url'), file: generation });
+    try { ops.write(account, record); }
+    catch (error) {
+      try { fs.unlinkSync(file); } catch (_) {}
+      throw error;
+    }
+  }
+}
+
+function keychainDelete(origin, operations) {
+  const ops = keychainOperations(operations);
+  const record = parseKeychainRecord(ops.read(keychainAccount(origin)));
+  ops.remove(keychainAccount(origin));
+  const file = encryptedCredentialFile(origin,
+    record && record.type === 'key' ? record.generation : null);
+  try { fs.unlinkSync(file); } catch (_) {}
+}
+
+function removeFileCredential(origin) {
+  const values = readFileStore();
+  delete values[origin];
+  if (Object.keys(values).length) atomicWrite(credentialFile(), values);
+  else {
+    try { fs.unlinkSync(credentialFile()); }
+    catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
+  }
+}
+
+function retryFileCredentialCleanup(origin) {
+  try { removeFileCredential(origin); } catch (_) {}
+}
+
+function macLoad(origin, operations) {
+  const credential = keychainLoad(origin, operations);
+  if (credential) {
+    if (readFileStore()[origin]) retryFileCredentialCleanup(origin);
+    return credential;
+  }
+  const legacy = readFileStore()[origin] || null;
+  if (!legacy) return null;
+  keychainSave(origin, legacy, operations);
+  retryFileCredentialCleanup(origin);
+  return legacy;
+}
+
+function macSave(origin, credential, operations) {
+  keychainSave(origin, credential, operations);
+  retryFileCredentialCleanup(origin);
+}
+
+function macRemove(origin, operations) {
+  keychainDelete(origin, operations);
+  removeFileCredential(origin);
+}
+
+function runDpapi(script, input, execute) {
+  const run = execute || spawnSync;
+  const result = run('powershell.exe', ['-NoLogo', '-NoProfile', '-NonInteractive',
+    '-Command', script], {
+    input,
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: ['pipe', 'pipe', 'ignore'],
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0 || typeof result.stdout !== 'string' || !result.stdout.trim()) {
+    throw new Error('Windows could not protect the SmallDocs Cloud credential.');
+  }
+  return result.stdout.trim();
+}
+
+function validBase64(value) {
+  if (!value || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return false;
+  try {
+    const decoded = Buffer.from(value, 'base64');
+    return decoded.length > 0 && decoded.toString('base64') === value;
+  } catch (_) { return false; }
+}
+
+function readDpapiCredential(origin, execute) {
+  const file = dpapiCredentialFile(origin);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const plain = runDpapi(DPAPI_UNPROTECT, fs.readFileSync(file, 'utf8').trim(), execute);
+    const value = JSON.parse(plain);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid store');
+    return value;
+  } catch (_) {
+    throw new Error('Could not read the Windows-protected SmallDocs Cloud credential.');
+  }
+}
+
+function writeDpapiCredential(origin, credential, execute) {
+  const encrypted = runDpapi(DPAPI_PROTECT, JSON.stringify(credential), execute);
+  if (!validBase64(encrypted)) {
+    throw new Error('Windows returned an invalid protected SmallDocs Cloud credential.');
+  }
+  atomicWriteRaw(dpapiCredentialFile(origin), encrypted + '\n');
+}
+
+function windowsLoad(origin, execute) {
+  const protectedCredential = readDpapiCredential(origin, execute);
+  if (protectedCredential) {
+    if (readFileStore()[origin]) retryFileCredentialCleanup(origin);
+    return protectedCredential;
+  }
+  const legacy = readFileStore()[origin] || null;
+  if (!legacy) return null;
+  writeDpapiCredential(origin, legacy, execute);
+  retryFileCredentialCleanup(origin);
+  return legacy;
+}
+
+function windowsSave(origin, credential, execute) {
+  writeDpapiCredential(origin, credential, execute);
+  retryFileCredentialCleanup(origin);
+}
+
+function windowsRemove(origin) {
+  try { fs.unlinkSync(dpapiCredentialFile(origin)); }
+  catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
+  removeFileCredential(origin);
+}
+
+function forceFileCredentials() {
+  return process.env.SDOCS_CLOUD_FILE_CREDENTIALS === '1';
+}
+
+function useKeychain() {
+  return process.platform === 'darwin' && !forceFileCredentials();
+}
+
+function useDpapi() {
+  return process.platform === 'win32' && !forceFileCredentials();
+}
+
+function load(origin) {
+  if (useKeychain()) return macLoad(origin);
+  if (useDpapi()) return windowsLoad(origin);
+  return readFileStore()[origin] || null;
+}
+
+function save(origin, credential) {
+  if (useKeychain()) return macSave(origin, credential);
+  if (useDpapi()) return windowsSave(origin, credential);
+  const values = readFileStore();
+  values[origin] = credential;
+  atomicWrite(credentialFile(), values);
+}
+
+function remove(origin) {
+  if (useKeychain()) return macRemove(origin);
+  if (useDpapi()) return windowsRemove(origin);
+  const values = readFileStore();
+  delete values[origin];
+  atomicWrite(credentialFile(), values);
+}
+
+module.exports = {
+  cloudDir,
+  credentialFile,
+  dpapiCredentialFile,
+  encryptedCredentialFile,
+  atomicWrite,
+  load,
+  save,
+  remove,
+  useKeychain,
+  useDpapi,
+  keychainLoad,
+  keychainSave,
+  keychainDelete,
+  macLoad,
+  macSave,
+  macRemove,
+  readDpapiCredential,
+  writeDpapiCredential,
+  windowsLoad,
+  windowsSave,
+  windowsRemove,
+  DPAPI_PROTECT,
+  DPAPI_UNPROTECT,
+};

package/lib/commands.js

@@ -44,6 +44,7 @@ async function finishUrl(opts, content, local, defaults) {
     try {
       const url = await buildShortUrl(content, {
         url: opts.url, mode: opts.mode, theme: opts.theme, section: opts.section,
+        source: opts.sourceFlag, placement: opts.placementFlag,
       });
       return { url, contentPresent: !!content };
     } catch (e) {
@@ -89,6 +90,36 @@ async function prepareCodewalkUrl(opts) {
   return finishUrl(opts, content, null, defaults);
 }
 
+function isMarkdownPath(file) {
+  return /\.(?:md|markdown|mdown|mkd)$/i.test(String(file || ''));
+}
+
+function frontMatterLineOffset(content) {
+  const match = String(content || '').match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  return match ? (match[0].match(/\n/g) || []).length : 0;
+}
+
+// A regular Markdown file uses the same line annotation syntax as a source
+// file. `docwalk: true` tells the reader to resolve those source lines against
+// rendered prose and rich blocks instead of offering them to the code viewer.
+function applyDocumentWalkthrough(meta, file, annotations, lineOffset) {
+  if (!isMarkdownPath(file) || !Array.isArray(annotations) || !annotations.length) {
+    return false;
+  }
+  const offset = Math.max(0, parseInt(lineOffset, 10) || 0);
+  meta.docwalk = true;
+  meta.annotations = annotations.flatMap(({ file: _file, ...rest }) => {
+    const sourceLine = parseInt(rest.line, 10);
+    const parsedEnd = parseInt(rest.endLine, 10);
+    const sourceEnd = parsedEnd >= sourceLine ? parsedEnd : sourceLine;
+    if (!(sourceLine >= 1) || sourceEnd <= offset) return [];
+    const line = Math.max(1, sourceLine - offset);
+    const endLine = Math.max(line, sourceEnd - offset);
+    return [{ ...rest, line, endLine }];
+  });
+  return true;
+}
+
 async function prepareUrl(opts) {
   // Annotations render as a walkthrough: a tabbed tour for 2+ files, a single-
   // tab stepper for one. A plain `sdoc app.py` with no annotations stays the
@@ -101,6 +132,7 @@ async function prepareUrl(opts) {
   }
 
   let content = await readContent(opts.file);
+  const documentLineOffset = frontMatterLineOffset(content);
   const defaults = loadDefaultStyles();
   if (content && defaults) {
     content = applyDefaultStyles(content);
@@ -115,7 +147,10 @@ async function prepareUrl(opts) {
     const parsed = SDocYaml.parseFrontMatter(content);
     let changed = false;
     if (!parsed.meta.file) { parsed.meta.file = path.basename(opts.file); changed = true; }
-    if (opts.annotations && opts.annotations.length) {
+    if (applyDocumentWalkthrough(
+      parsed.meta, opts.file, opts.annotations, documentLineOffset)) {
+      changed = true;
+    } else if (opts.annotations && opts.annotations.length) {
       // A single file needs no per-annotation `file` binding — drop it so the
       // serialized shape stays {line, endLine, text}. (Multi-file keeps it, in
       // prepareCodewalkUrl.)
@@ -152,7 +187,7 @@ async function prepareUrl(opts) {
 // The non-blocking, share-by-URL case is `sdoc share <file>`.
 async function openCommand(opts) {
   const { url } = await prepareUrl(opts);
-  openBrowser(url);
+  if (!opts.noOpenFlag) openBrowser(url);
   console.log(`SDocs → ${url.length > 80 ? url.slice(0, 77) + '...' : url}`);
   await postCommandHooks();
 }
@@ -238,6 +273,7 @@ function newCommand(opts) {
 //   sdoc slides list                -> built-in template registry
 //   sdoc slides custom-shapes       -> raw-shape reference
 //   sdoc slides icons [query]       -> Lucide icon name listing
+//   sdoc slides verify <file>        -> handled by slides-verify in the router
 function slidesCommand(opts) {
   const helpText = require('./help-text');
   const sub = opts.file;
@@ -255,9 +291,11 @@ function presentCommand(opts) {
 }
 
 function printSlideStdlib() {
-  // Require lazily so the browser-side slide stdlib (which uses window
-  // globals) is only loaded when this command actually runs.
-  const SDocSlideStdlib = require('../../public/sdocs-slide-stdlib.js');
+  // The registry lives inside the published CLI package and is symlinked
+  // into public/ for the browser. Reaching through ../../public works from
+  // a repository checkout but fails after npm or URL installation because
+  // the server-side public/ directory is not part of the CLI tarball.
+  const SDocSlideStdlib = require('../shared/sdocs-slide-stdlib.js');
   const names = SDocSlideStdlib.names || Object.keys(SDocSlideStdlib.templates || {});
   const slots = SDocSlideStdlib.slots || {};
   console.log('Built-in slide templates');
@@ -329,6 +367,9 @@ function printIconList(query) {
 }
 
 module.exports = {
+  applyDocumentWalkthrough,
+  frontMatterLineOffset,
+  isMarkdownPath,
   prepareUrl,
   openCommand,
   shareCommand,