safedrop-cli 1.0.0

package/src/api.js

@@ -0,0 +1,170 @@
+// api.js
+//
+// Thin client for the public SafeDrop HTTP API. Only the endpoints the CLI
+// needs are implemented here. See API.md for the full contract.
+//
+// `baseUrl` must include any path prefix the deployment uses (the production
+// web app uses ".../api"). The default points at a local dev backend.
+
+export const DEFAULT_API_BASE = 'https://safedrop.ma/api';
+
+export class SafeDropApiError extends Error {
+  constructor(statusCode, message, details) {
+    super(message);
+    this.name = 'SafeDropApiError';
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+}
+
+/** Turn raw fetch/network failures into a human-readable message. */
+function describeNetworkError(err, url) {
+  const code = err?.cause?.code || err?.code;
+  if (code === 'ECONNREFUSED') {
+    return `Could not connect to the SafeDrop server at ${url}. Is the URL correct and the server reachable?`;
+  }
+  if (code === 'ENOTFOUND') {
+    return `Could not resolve the SafeDrop server host for ${url}.`;
+  }
+  if (code === 'ETIMEDOUT' || err?.name === 'TimeoutError') {
+    return `The connection to ${url} timed out.`;
+  }
+  if (code === 'CERT_HAS_EXPIRED' || code === 'UNABLE_TO_VERIFY_LEAF_SIGNATURE') {
+    return `TLS certificate problem connecting to ${url}: ${code}.`;
+  }
+  return `Network error contacting ${url}: ${err?.message || err}`;
+}
+
+export class SafeDropApi {
+  constructor(baseUrl = DEFAULT_API_BASE) {
+    this.baseUrl = String(baseUrl).replace(/\/+$/, '');
+  }
+
+  async #json(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    let res;
+    try {
+      res = await fetch(url, {
+        ...options,
+        headers: { 'Content-Type': 'application/json', ...(options.headers || {}) },
+      });
+    } catch (err) {
+      throw new SafeDropApiError(0, describeNetworkError(err, url));
+    }
+    const text = await res.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : {};
+    } catch {
+      body = { raw: text };
+    }
+    if (!res.ok) {
+      const message = body?.error || body?.errors?.[0]?.msg || `Request failed (HTTP ${res.status}).`;
+      throw new SafeDropApiError(res.status, message, body);
+    }
+    return body;
+  }
+
+  /** POST /initiate-upload */
+  initiateUpload({ customExpirationSeconds } = {}) {
+    const body = {};
+    if (customExpirationSeconds && customExpirationSeconds > 0) {
+      body.customExpirationSeconds = Math.floor(customExpirationSeconds);
+    }
+    return this.#json('/initiate-upload', { method: 'POST', body: JSON.stringify(body) });
+  }
+
+  /** PUT to the presigned storage URL with raw encrypted bytes. */
+  async uploadBytes(presignedUrl, bytes) {
+    let res;
+    try {
+      res = await fetch(presignedUrl, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/octet-stream' },
+        body: bytes,
+      });
+    } catch (err) {
+      throw new SafeDropApiError(0, describeNetworkError(err, 'storage'));
+    }
+    if (!res.ok) {
+      throw new SafeDropApiError(res.status, `Failed to upload encrypted bytes to storage (HTTP ${res.status}).`);
+    }
+  }
+
+  /** POST /upload/:uploadCode/finalize */
+  finalizeUpload(uploadCode, encryptedFilename, senderToken) {
+    return this.#json(`/upload/${uploadCode}/finalize`, {
+      method: 'POST',
+      body: JSON.stringify({ encryptedFilename, senderToken }),
+    });
+  }
+
+  /** DELETE /upload/:uploadCode  (sender cancellation) */
+  cancelUpload(uploadCode, senderToken) {
+    return this.#json(`/upload/${uploadCode}`, {
+      method: 'DELETE',
+      body: JSON.stringify({ senderToken }),
+    });
+  }
+
+  /** POST /handshake/initiate */
+  initiateHandshake(uploadCode) {
+    return this.#json('/handshake/initiate', {
+      method: 'POST',
+      body: JSON.stringify({ uploadCode }),
+    });
+  }
+
+  /** POST /handshake/authorize */
+  authorizeHandshake(uploadCode, handshakeCode) {
+    return this.#json('/handshake/authorize', {
+      method: 'POST',
+      body: JSON.stringify({ uploadCode, handshakeCode }),
+    });
+  }
+
+  /**
+   * GET /handshake/token/:uploadCode
+   * Returns { downloadToken } once the sender authorizes; 404 until then.
+   * Throws SafeDropApiError(404) while still pending — callers poll on this.
+   */
+  getDownloadToken(uploadCode, recipientToken) {
+    return this.#json(`/handshake/token/${uploadCode}`, {
+      headers: { Authorization: `Bearer ${recipientToken}` },
+    });
+  }
+
+  /** DELETE /handshake/:uploadCode  (recipient cancellation) */
+  cancelHandshake(uploadCode, token) {
+    return this.#json(`/handshake/${uploadCode}`, {
+      method: 'DELETE',
+      headers: { Authorization: `Bearer ${token}` },
+    });
+  }
+
+  /**
+   * GET /upload/:uploadCode  (download)
+   * Returns { bytes: Buffer, encryptedFilename: string|null }.
+   * The server deletes its copy as soon as the response finishes streaming.
+   */
+  async downloadFile(uploadCode, downloadToken) {
+    const url = `${this.baseUrl}/upload/${uploadCode}`;
+    let res;
+    try {
+      res = await fetch(url, { headers: { Authorization: `Bearer ${downloadToken}` } });
+    } catch (err) {
+      throw new SafeDropApiError(0, describeNetworkError(err, url));
+    }
+    if (!res.ok) {
+      let message = `Download failed (HTTP ${res.status}).`;
+      try {
+        const body = await res.json();
+        if (body?.error) message = body.error;
+      } catch { /* non-JSON error body */ }
+      throw new SafeDropApiError(res.status, message);
+    }
+    const encryptedFilename = res.headers.get('x-encrypted-filename');
+    const bytes = Buffer.from(await res.arrayBuffer());
+    return { bytes, encryptedFilename };
+  }
+}

package/src/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// cli.js — argument parsing and command dispatch for `safedrop`.
+
+import { runSend } from './send.js';
+import { runReceive } from './receive.js';
+import { DEFAULT_API_BASE } from './api.js';
+import { log, style } from './ui.js';
+
+const VERSION = '1.0.0';
+
+const HELP = `${style.bold('safedrop')} — zero-knowledge encrypted file transfer from your terminal
+
+${style.bold('Usage:')}
+  safedrop send <file> [options]
+  safedrop receive <code-or-link> [options]
+
+${style.bold('Send options:')}
+  --ttl <minutes>     How long the transfer stays available (default 15, max 1440).
+  --secure            Enable full-security mode (out-of-band safety-code check).
+  --api <base-url>    SafeDrop API base URL (default ${DEFAULT_API_BASE}).
+
+${style.bold('Receive options:')}
+  --output, -o <path> Where to save the file: a directory or a file path.
+  --api <base-url>    SafeDrop API base URL (default ${DEFAULT_API_BASE}).
+
+${style.bold('Other:')}
+  --help, -h          Show this help.
+  --version, -v       Show the version.
+
+${style.bold('Examples:')}
+  safedrop send ./report.pdf
+  safedrop send ./report.pdf --ttl 60 --secure
+  safedrop send ./report.pdf --api https://safedrop.ma/api
+  safedrop receive eyJ1cGxvYWRDb2RlIjoi...
+  safedrop receive "https://safedrop.ma/#code=eyJ1cGxv..." -o ~/Downloads/
+`;
+
+/**
+ * Tiny flag parser. Supports "--flag value", "--flag=value", short aliases,
+ * and boolean flags. Unknown flags are reported.
+ */
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = {};
+  const aliases = { '-o': '--output', '-h': '--help', '-v': '--version' };
+  const booleans = new Set(['--secure', '--help', '--version']);
+
+  for (let i = 0; i < argv.length; i++) {
+    let arg = argv[i];
+    if (arg.startsWith('-')) {
+      let value;
+      const eq = arg.indexOf('=');
+      if (eq !== -1) { value = arg.slice(eq + 1); arg = arg.slice(0, eq); }
+      const name = aliases[arg] || arg;
+      if (booleans.has(name)) {
+        flags[name.slice(2)] = true;
+      } else {
+        if (value === undefined) value = argv[++i];
+        if (value === undefined) throw new Error(`Missing value for ${name}.`);
+        flags[name.slice(2)] = value;
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { positionals, flags };
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+  const { positionals, flags } = parsed;
+  const command = positionals[0];
+
+  if (flags.version) { console.log(VERSION); return; }
+  if (flags.help || !command) { console.log(HELP); return; }
+
+  const api = flags.api || process.env.SAFEDROP_API || DEFAULT_API_BASE;
+
+  if (command === 'send') {
+    const file = positionals[1];
+    if (!file) { log.error('Usage: safedrop send <file> [--ttl <minutes>] [--secure] [--api <url>]'); process.exit(1); }
+
+    let ttlMinutes;
+    if (flags.ttl !== undefined) {
+      ttlMinutes = Number(flags.ttl);
+      if (!Number.isFinite(ttlMinutes) || ttlMinutes <= 0) { log.error('--ttl must be a positive number of minutes.'); process.exit(1); }
+      if (ttlMinutes > 1440) { log.error('--ttl cannot exceed 1440 minutes (24 hours).'); process.exit(1); }
+    }
+    await runSend(file, { api, ttlMinutes, fullSecurity: !!flags.secure });
+    return;
+  }
+
+  if (command === 'receive') {
+    const codeOrLink = positionals[1];
+    if (!codeOrLink) { log.error('Usage: safedrop receive <code-or-link> [--output <path>] [--api <url>]'); process.exit(1); }
+    await runReceive(codeOrLink, { api, output: flags.output });
+    return;
+  }
+
+  log.error(`Unknown command: ${command}`);
+  console.log(`\n${HELP}`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  log.error(err?.message || String(err));
+  process.exit(1);
+});

package/src/code.js

@@ -0,0 +1,104 @@
+// code.js
+//
+// Combined-code and share-link handling. Byte-for-byte compatible with the
+// browser client:
+//
+//   combinedCode = base64( JSON.stringify({ uploadCode, key, fullSecurity }) )
+//   shareLink    = `${origin}/#code=${combinedCode}`
+//
+// The browser puts the code in the URL *fragment* (#...), never the query
+// string, so the secret key is never sent to any server during navigation.
+
+const UPLOAD_CODE_LENGTH = 16;
+
+/**
+ * Build the combined share code from its parts.
+ * @returns {string} base64 JSON code
+ */
+export function encodeCombinedCode({ uploadCode, key, fullSecurity = false }) {
+  if (!uploadCode || !key) {
+    throw new Error('uploadCode and key are required to build a share code.');
+  }
+  const json = JSON.stringify({ uploadCode, key, fullSecurity: !!fullSecurity });
+  return Buffer.from(json, 'utf8').toString('base64');
+}
+
+/**
+ * Build the browser share link, with the code in the URL fragment.
+ * @param {string} combinedCode
+ * @param {string} origin e.g. "https://safedrop.ma"
+ */
+export function encodeShareLink(combinedCode, origin) {
+  const base = String(origin || '').replace(/\/+$/, '');
+  return `${base}/#code=${combinedCode}`;
+}
+
+/**
+ * Extract the raw combined code from arbitrary user input: a bare combined
+ * code, a full SafeDrop link (fragment or query form), or a code with
+ * surrounding whitespace.
+ *
+ * Mirrors the browser's hash/query handling:
+ *   new URLSearchParams(hash).get('code') || query.get('code')
+ *
+ * @param {string} input
+ * @returns {string} the bare combined (base64) code
+ */
+export function extractCombinedCode(input) {
+  if (typeof input !== 'string' || !input.trim()) {
+    throw new Error('No code or link provided.');
+  }
+  const raw = input.trim();
+
+  // Looks like a URL? Pull `code` from the fragment first, then the query.
+  if (/^https?:\/\//i.test(raw) || raw.includes('#code=') || raw.includes('?code=')) {
+    let url;
+    try {
+      url = new URL(raw);
+    } catch {
+      // Not a parseable URL but may contain a #code= / ?code= chunk.
+      const m = raw.match(/[#?&]code=([^&\s]+)/);
+      if (m) return decodeURIComponent(m[1]);
+      throw new Error('Could not parse the SafeDrop link.');
+    }
+    const fragment = url.hash.replace(/^#/, '');
+    const fromFragment = new URLSearchParams(fragment).get('code');
+    const fromQuery = url.searchParams.get('code');
+    const code = fromFragment || fromQuery;
+    if (!code) throw new Error('Link does not contain a SafeDrop code.');
+    return code;
+  }
+
+  // Otherwise treat the whole thing as a bare combined code.
+  return raw;
+}
+
+/**
+ * Decode a combined code (or link) into its parts.
+ * @param {string} input bare code or full link
+ * @returns {{ uploadCode: string, key: string, fullSecurity: boolean }}
+ */
+export function decodeCombinedCode(input) {
+  const combined = extractCombinedCode(input);
+
+  let data;
+  try {
+    const json = Buffer.from(combined, 'base64').toString('utf8');
+    data = JSON.parse(json);
+  } catch {
+    throw new Error('Invalid SafeDrop code: could not decode.');
+  }
+
+  const { uploadCode, key } = data;
+  // Browser defaults fullSecurity to true when the field is absent.
+  const fullSecurity = data.fullSecurity ?? true;
+
+  if (typeof uploadCode !== 'string' || uploadCode.length !== UPLOAD_CODE_LENGTH) {
+    throw new Error('Invalid SafeDrop code: bad upload code.');
+  }
+  if (typeof key !== 'string' || !/^[0-9a-fA-F]{64}$/.test(key)) {
+    throw new Error('Invalid SafeDrop code: bad encryption key.');
+  }
+
+  return { uploadCode, key, fullSecurity: !!fullSecurity };
+}

package/src/crypto.js

@@ -0,0 +1,82 @@
+// crypto.js
+//
+// SafeDrop encryption primitives — byte-for-byte compatible with the browser
+// client (frontend/utils/crypto.ts), which uses the Web Crypto API.
+//
+// Wire format (identical in both directions):
+//
+//   payload = IV (12 bytes) || ciphertext || GCM auth tag (16 bytes)
+//
+// Web Crypto's `encrypt()` appends the 16-byte auth tag to the ciphertext, so
+// the browser produces exactly this layout. Node's crypto exposes the tag
+// separately via getAuthTag(), so we concatenate it to match.
+//
+// Keys are 256-bit, represented as a 64-character lowercase hex string.
+//
+// IMPORTANT: strings (e.g. filenames) are encoded as UTF-16LE, NOT UTF-8.
+// The browser's str2ab() writes charCodeAt() values into a Uint16Array, which
+// is little-endian on all common platforms. We must match that exactly or
+// filenames will not round-trip across browser <-> CLI.
+
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+const ALGORITHM = 'aes-256-gcm';
+
+/** Generate a fresh AES-256 key, returned as a 64-char hex string. */
+export function generateKeyHex() {
+  return randomBytes(32).toString('hex');
+}
+
+function keyFromHex(keyHex) {
+  if (!/^[0-9a-fA-F]{64}$/.test(keyHex)) {
+    throw new Error('Invalid encryption key (expected 64 hex characters).');
+  }
+  return Buffer.from(keyHex, 'hex');
+}
+
+/**
+ * Encrypt a binary buffer.
+ * Returns { payload: Buffer, keyHex: string }. If keyHex is omitted, a new key
+ * is generated (matching the browser's encryptBuffer behaviour).
+ */
+export function encryptBuffer(plain, keyHex = generateKeyHex()) {
+  const key = keyFromHex(keyHex);
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const enc = Buffer.concat([cipher.update(plain), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return { payload: Buffer.concat([iv, enc, tag]), keyHex };
+}
+
+/** Decrypt a binary payload (IV || ciphertext || tag) back to a Buffer. */
+export function decryptBuffer(payload, keyHex) {
+  const key = keyFromHex(keyHex);
+  const data = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+  if (data.length < IV_LENGTH + TAG_LENGTH) {
+    throw new Error('Ciphertext is too short to be valid.');
+  }
+  const iv = data.subarray(0, IV_LENGTH);
+  const tag = data.subarray(data.length - TAG_LENGTH);
+  const ct = data.subarray(IV_LENGTH, data.length - TAG_LENGTH);
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]);
+}
+
+/**
+ * Encrypt a UTF-16LE string, returning base64 (matches browser encryptString).
+ * Used for filenames.
+ */
+export function encryptString(plainText, keyHex) {
+  const ptBuf = Buffer.from(String(plainText), 'utf16le');
+  const { payload } = encryptBuffer(ptBuf, keyHex);
+  return payload.toString('base64');
+}
+
+/** Decrypt a base64 string payload back to a UTF-16LE string. */
+export function decryptString(base64Payload, keyHex) {
+  const payload = Buffer.from(base64Payload, 'base64');
+  return decryptBuffer(payload, keyHex).toString('utf16le');
+}

package/src/index.js

@@ -0,0 +1,25 @@
+// index.js — library entry point.
+//
+// Exposes the auditable building blocks so the CLI's behaviour can be reused or
+// tested programmatically. No secrets are ever logged by these functions.
+
+export {
+  generateKeyHex,
+  encryptBuffer,
+  decryptBuffer,
+  encryptString,
+  decryptString,
+} from './crypto.js';
+
+export {
+  encodeCombinedCode,
+  encodeShareLink,
+  extractCombinedCode,
+  decodeCombinedCode,
+} from './code.js';
+
+export { generateSAS } from './sas.js';
+export { sanitizeFilename, resolveOutputPath, dedupePath } from './paths.js';
+export { SafeDropApi, SafeDropApiError, DEFAULT_API_BASE } from './api.js';
+export { runSend } from './send.js';
+export { runReceive } from './receive.js';

package/src/paths.js

@@ -0,0 +1,95 @@
+// paths.js
+//
+// Safe handling of the decrypted output path. The filename comes from an
+// encrypted blob the *sender* controls, so after decryption it is untrusted
+// input. We must:
+//   - strip any directory components from the sender-supplied name
+//   - refuse names that try to escape the chosen output directory
+//   - never silently overwrite an existing local file
+
+import path from 'node:path';
+
+/**
+ * Reduce a sender-supplied filename to a safe basename.
+ * Removes directory separators, drive letters, leading dots-only names, and
+ * control characters. Falls back to a default when nothing usable remains.
+ */
+export function sanitizeFilename(name, fallback = 'safedrop-file') {
+  if (typeof name !== 'string') return fallback;
+
+  // Take the last path segment under both POSIX and Windows separators.
+  let base = name.split(/[\\/]/).pop() || '';
+
+  // Drop NUL and control characters, and Windows-illegal characters.
+  // eslint-disable-next-line no-control-regex
+  base = base.replace(/[\x00-\x1f<>:"|?*]/g, '').trim();
+
+  // Reject pure-dot names (".", "..") and empties.
+  if (!base || /^\.+$/.test(base)) return fallback;
+
+  // Avoid Windows reserved device names (CON, PRN, NUL, COM1, ...).
+  const stem = base.replace(/\.[^.]*$/, '');
+  if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(stem)) {
+    return `_${base}`;
+  }
+  return base;
+}
+
+/**
+ * Resolve the final absolute output path from the user's --output option and
+ * the (sanitized) sender filename, then verify it does not escape its parent
+ * directory.
+ *
+ * Rules:
+ *   - no --output  -> sanitized filename in the current working directory
+ *   - --output dir/  (or existing directory) -> sanitized filename inside it
+ *   - --output file  -> that exact path (its basename is still sanitized)
+ *
+ * @returns {string} absolute, validated output path
+ */
+export function resolveOutputPath(senderFilename, outputOption, { cwd = process.cwd(), isDirectory } = {}) {
+  const safeName = sanitizeFilename(senderFilename);
+
+  let target;
+  if (!outputOption) {
+    target = path.resolve(cwd, safeName);
+  } else {
+    const resolvedOpt = path.resolve(cwd, outputOption);
+    // A trailing separator is an explicit "this is a directory" intent and wins
+    // even if the directory does not exist yet. Otherwise probe the filesystem.
+    const endsWithSep = /[\\/]$/.test(outputOption);
+    const looksLikeDir =
+      endsWithSep || (typeof isDirectory === 'function' && isDirectory(resolvedOpt));
+    if (looksLikeDir) {
+      target = path.join(resolvedOpt, safeName);
+    } else {
+      // Treat as a file path, but sanitize the basename the user gave.
+      target = path.join(path.dirname(resolvedOpt), sanitizeFilename(path.basename(resolvedOpt)));
+    }
+  }
+
+  // Containment check: the final basename must stay within its parent dir.
+  const parent = path.dirname(target);
+  const rel = path.relative(parent, target);
+  if (rel.startsWith('..') || path.isAbsolute(rel) || rel.includes(path.sep)) {
+    throw new Error(`Refusing to write outside the target directory: ${senderFilename}`);
+  }
+
+  return target;
+}
+
+/**
+ * Pick a non-clobbering path by appending " (1)", " (2)", ... before the
+ * extension. Used when the user declines to overwrite.
+ */
+export function dedupePath(target, exists) {
+  if (!exists(target)) return target;
+  const dir = path.dirname(target);
+  const ext = path.extname(target);
+  const stem = path.basename(target, ext);
+  for (let i = 1; i < 10000; i++) {
+    const candidate = path.join(dir, `${stem} (${i})${ext}`);
+    if (!exists(candidate)) return candidate;
+  }
+  throw new Error('Could not find an available filename.');
+}