vellum 0.0.16 → 0.2.0

package/src/bundler/bundle-scanner.ts

@@ -0,0 +1,535 @@
+/**
+ * BundleScanner — Security validation and static analysis for .vellumapp bundles.
+ *
+ * Validates zip bundles before they are opened, returning structured results
+ * with block-level (reject) and warn-level (flag) findings.
+ */
+
+import JSZip from "jszip";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ScanFinding {
+  category: "archive" | "html" | "asset";
+  code: string;
+  message: string;
+  level: "block" | "warn";
+}
+
+export interface ScanResult {
+  passed: boolean;
+  findings: ScanFinding[];
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MAX_DECOMPRESSED_SIZE = 25 * 1024 * 1024; // 25 MB
+const MAX_FILE_COUNT = 50;
+const MAX_COMPRESSION_RATIO = 100;
+const OBFUSCATION_LINE_LENGTH = 10_000; // 10 KB single line threshold
+
+const BLOCKED_EXTENSIONS = new Set([
+  ".exe",
+  ".sh",
+  ".command",
+  ".app",
+  ".dylib",
+  ".so",
+  ".scpt",
+]);
+
+const REQUIRED_MANIFEST_FIELDS = [
+  "format_version",
+  "name",
+  "created_at",
+  "created_by",
+  "entry",
+  "capabilities",
+] as const;
+
+// Magic byte signatures for image validation
+const IMAGE_SIGNATURES: Record<string, { bytes: number[]; offset?: number }[]> = {
+  ".png": [{ bytes: [0x89, 0x50, 0x4e, 0x47] }], // \x89PNG
+  ".jpg": [{ bytes: [0xff, 0xd8, 0xff] }],
+  ".jpeg": [{ bytes: [0xff, 0xd8, 0xff] }],
+  ".gif": [{ bytes: [0x47, 0x49, 0x46, 0x38] }], // GIF8
+  ".webp": [
+    { bytes: [0x52, 0x49, 0x46, 0x46] }, // RIFF at offset 0
+    // bytes 8-11 should be WEBP — checked separately
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function scanBundle(zipPath: string): Promise<ScanResult> {
+  const findings: ScanFinding[] = [];
+
+  const fileData = await Bun.file(zipPath).arrayBuffer();
+  let zip: JSZip;
+  try {
+    zip = await JSZip.loadAsync(fileData);
+  } catch {
+    findings.push({
+      category: "archive",
+      code: "invalid_zip",
+      message: "File is not a valid zip archive",
+      level: "block",
+    });
+    return { passed: false, findings };
+  }
+
+  // Run all scan phases
+  const manifest = await scanArchiveStructure(zip, fileData.byteLength, findings);
+  if (manifest) {
+    await scanHtmlEntry(zip, manifest.entry as string, findings);
+  }
+  const entryName = manifest ? (manifest.entry as string | undefined) : undefined;
+  await scanAssets(zip, findings, entryName);
+
+  const passed = !findings.some((f) => f.level === "block");
+  return { passed, findings };
+}
+
+// ---------------------------------------------------------------------------
+// Phase 1: Archive structure scan
+// ---------------------------------------------------------------------------
+
+async function scanArchiveStructure(
+  zip: JSZip,
+  compressedSize: number,
+  findings: ScanFinding[],
+): Promise<Record<string, unknown> | null> {
+  const entries = Object.keys(zip.files);
+  const fileEntries = entries.filter((e) => !zip.files[e].dir);
+
+  // File count check
+  if (fileEntries.length > MAX_FILE_COUNT) {
+    findings.push({
+      category: "archive",
+      code: "too_many_files",
+      message: `Bundle contains ${fileEntries.length} files (max ${MAX_FILE_COUNT})`,
+      level: "block",
+    });
+  }
+
+  // Path traversal & blocked extensions
+  for (const name of entries) {
+    if (name.includes("../") || name.startsWith("/")) {
+      findings.push({
+        category: "archive",
+        code: "path_traversal",
+        message: `Zip entry contains path traversal: ${name}`,
+        level: "block",
+      });
+    }
+
+    const lowerName = name.toLowerCase();
+    for (const ext of BLOCKED_EXTENSIONS) {
+      if (lowerName.endsWith(ext)) {
+        findings.push({
+          category: "archive",
+          code: "blocked_file_type",
+          message: `Blocked file type ${ext}: ${name}`,
+          level: "block",
+        });
+        break;
+      }
+    }
+  }
+
+  // Compute total decompressed size and compression ratio (bail out early to
+  // avoid decompressing the entire archive if limits are exceeded).
+  let totalDecompressed = 0;
+  for (const name of fileEntries) {
+    const entry = zip.files[name];
+    const data = await entry.async("uint8array");
+    totalDecompressed += data.byteLength;
+    if (totalDecompressed > MAX_DECOMPRESSED_SIZE) break;
+    if (compressedSize > 0 && totalDecompressed / compressedSize > MAX_COMPRESSION_RATIO) break;
+  }
+
+  if (totalDecompressed > MAX_DECOMPRESSED_SIZE) {
+    findings.push({
+      category: "archive",
+      code: "too_large",
+      message: `Total decompressed size ${(totalDecompressed / 1024 / 1024).toFixed(1)} MB exceeds ${MAX_DECOMPRESSED_SIZE / 1024 / 1024} MB limit`,
+      level: "block",
+    });
+  }
+
+  if (compressedSize > 0 && totalDecompressed / compressedSize > MAX_COMPRESSION_RATIO) {
+    findings.push({
+      category: "archive",
+      code: "zip_bomb",
+      message: `Compression ratio ${(totalDecompressed / compressedSize).toFixed(0)}:1 exceeds ${MAX_COMPRESSION_RATIO}:1 limit`,
+      level: "block",
+    });
+  }
+
+  // Manifest validation
+  const manifestFile = zip.file("manifest.json");
+  if (!manifestFile) {
+    findings.push({
+      category: "archive",
+      code: "manifest_missing",
+      message: "manifest.json is missing from the bundle",
+      level: "block",
+    });
+    return null;
+  }
+
+  let manifest: Record<string, unknown>;
+  try {
+    const manifestText = await manifestFile.async("text");
+    manifest = JSON.parse(manifestText) as Record<string, unknown>;
+  } catch {
+    findings.push({
+      category: "archive",
+      code: "manifest_malformed",
+      message: "manifest.json is not valid JSON",
+      level: "block",
+    });
+    return null;
+  }
+
+  for (const field of REQUIRED_MANIFEST_FIELDS) {
+    if (!(field in manifest)) {
+      findings.push({
+        category: "archive",
+        code: "manifest_malformed",
+        message: `manifest.json is missing required field: ${field}`,
+        level: "block",
+      });
+    }
+  }
+
+  // Entry file check
+  const entryName = manifest.entry;
+  if (typeof entryName === "string" && !zip.file(entryName)) {
+    findings.push({
+      category: "archive",
+      code: "entry_missing",
+      message: `Entry file "${entryName}" specified in manifest is missing`,
+      level: "block",
+    });
+  }
+
+  return manifest;
+}
+
+// ---------------------------------------------------------------------------
+// Phase 2: HTML / JS static analysis
+// ---------------------------------------------------------------------------
+
+async function scanHtmlEntry(
+  zip: JSZip,
+  entryName: string,
+  findings: ScanFinding[],
+): Promise<void> {
+  const entryFile = zip.file(entryName);
+  if (!entryFile) return;
+
+  const html = await entryFile.async("text");
+
+  // --- Block-level: external resource references ---
+
+  // <script src="..."> with external origin (quoted and unquoted)
+  const scriptSrcRe = /<script[^>]+src\s*=\s*(?:["']([^"']+)["']|([^\s>]+))/gi;
+  for (const m of html.matchAll(scriptSrcRe)) {
+    const url = m[1] ?? m[2];
+    if (isExternalUrl(url)) {
+      findings.push({
+        category: "html",
+        code: "external_script",
+        message: `External script source: ${url}`,
+        level: "block",
+      });
+    }
+  }
+
+  // <link href="..."> with external origin (quoted and unquoted)
+  const linkHrefRe = /<link[^>]+href\s*=\s*(?:["']([^"']+)["']|([^\s>]+))/gi;
+  for (const m of html.matchAll(linkHrefRe)) {
+    const url = m[1] ?? m[2];
+    if (isExternalUrl(url)) {
+      findings.push({
+        category: "html",
+        code: "external_link",
+        message: `External link href: ${url}`,
+        level: "block",
+      });
+    }
+  }
+
+  // <iframe src="..."> with external origin (quoted and unquoted)
+  const iframeSrcRe = /<iframe[^>]+src\s*=\s*(?:["']([^"']+)["']|([^\s>]+))/gi;
+  for (const m of html.matchAll(iframeSrcRe)) {
+    const url = m[1] ?? m[2];
+    if (isExternalUrl(url)) {
+      findings.push({
+        category: "html",
+        code: "external_iframe",
+        message: `External iframe source: ${url}`,
+        level: "block",
+      });
+    }
+  }
+
+  // <meta http-equiv="refresh"> with external URL
+  const metaRefreshRe = /<meta[^>]+http-equiv\s*=\s*["']refresh["'][^>]+content\s*=\s*["'][^"']*url\s*=\s*([^"'\s;]+)/gi;
+  for (const m of html.matchAll(metaRefreshRe)) {
+    if (isExternalUrl(m[1])) {
+      findings.push({
+        category: "html",
+        code: "external_meta_refresh",
+        message: `Meta refresh redirects to external URL: ${m[1]}`,
+        level: "block",
+      });
+    }
+  }
+
+  // --- Block-level: iframe srcdoc ---
+  if (/srcdoc\s*=/i.test(html)) {
+    findings.push({
+      category: "html",
+      code: "iframe_srcdoc",
+      message: "iframe srcdoc attribute can embed executable HTML",
+      level: "block",
+    });
+  }
+
+  // --- Block-level: formaction attribute ---
+  if (/formaction\s*=\s*["']https?:\/\//i.test(html)) {
+    findings.push({
+      category: "html",
+      code: "formaction_external",
+      message: "formaction attribute with external URL bypasses form restrictions",
+      level: "block",
+    });
+  }
+
+  // --- Warn-level: suspicious JS patterns ---
+
+  const warnPatterns: { pattern: RegExp; code: string; message: string }[] = [
+    { pattern: /\bfetch\s*\(/g, code: "network_fetch", message: "Uses fetch() for network requests \u2014 could send or receive data from external servers" },
+    { pattern: /\bXMLHttpRequest\b/g, code: "network_xhr", message: "Uses XMLHttpRequest for network requests \u2014 could send or receive data from external servers" },
+    { pattern: /\bnew\s+WebSocket\b/g, code: "network_websocket", message: "Uses WebSocket connections \u2014 could maintain persistent communication with a server" },
+    { pattern: /\bEventSource\b/g, code: "network_eventsource", message: "Uses server-sent events \u2014 could receive live data from a server" },
+    { pattern: /\bdocument\.cookie\b/g, code: "cookie_access", message: "Accesses browser cookies \u2014 could read or store tracking data" },
+    { pattern: /\beval\s*\(/g, code: "eval_usage", message: "Uses eval() for dynamic code execution \u2014 could run code not visible in the source" },
+    { pattern: /\bFunction\s*\(/g, code: "function_constructor", message: "Uses Function() constructor for dynamic code execution \u2014 could run code not visible in the source" },
+    {
+      pattern: /\bsetTimeout\s*\(\s*["'`]/g,
+      code: "settimeout_string",
+      message: "Uses setTimeout() with string for code execution \u2014 could run code not visible in the source",
+    },
+    {
+      pattern: /\bsetInterval\s*\(\s*["'`]/g,
+      code: "setinterval_string",
+      message: "Uses setInterval() with string for code execution \u2014 could run code not visible in the source",
+    },
+    { pattern: /\bwindow\.open\s*\(/g, code: "window_open", message: "Opens new windows \u2014 could navigate to external sites" },
+    {
+      pattern: /\bwindow\.location\s*=/g,
+      code: "window_location_assign",
+      message: "Redirects the page \u2014 could navigate away from the app",
+    },
+    {
+      pattern: /\bon(?:error|load|focus|blur|mouseover|mouseout|click|dblclick|submit|input|change|keydown|keyup|keypress)\s*=/g,
+      code: "html_event_handler",
+      message: "Uses inline event handlers \u2014 standard for interactive apps",
+    },
+    {
+      pattern: /@import\s+(?:url\s*\(|['"]https?:\/\/)/g,
+      code: "css_import",
+      message: "Loads external stylesheet \u2014 could connect to an external server",
+    },
+    {
+      pattern: /url\s*\(\s*['"]?https?:\/\//g,
+      code: "css_external_url",
+      message: "References external URL in CSS \u2014 could load resources from an external server",
+    },
+    {
+      pattern: /(?:src|href)\s*=\s*["']data:/g,
+      code: "data_uri",
+      message: "Uses embedded data URI \u2014 contains inline encoded content",
+    },
+    {
+      pattern: /(?:href|src|action)\s*=\s*["']javascript:/g,
+      code: "javascript_uri",
+      message: "Uses javascript: URI \u2014 could execute code on interaction",
+    },
+  ];
+
+  for (const { pattern, code, message } of warnPatterns) {
+    if (pattern.test(html)) {
+      findings.push({ category: "html", code, message, level: "warn" });
+    }
+  }
+
+  // Obfuscation detection: single lines > 10KB or high hex/unicode escape density
+  const lines = html.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.length > OBFUSCATION_LINE_LENGTH) {
+      findings.push({
+        category: "html",
+        code: "obfuscated_js",
+        message: `Possible obfuscated JS: line ${i + 1} is ${(line.length / 1024).toFixed(1)} KB`,
+        level: "warn",
+      });
+      break; // one finding is enough
+    }
+  }
+
+  // High density of hex/unicode escapes
+  const escapeMatches = html.match(/\\x[0-9a-fA-F]{2}|\\u[0-9a-fA-F]{4}|\\u\{[0-9a-fA-F]+\}/g);
+  if (escapeMatches && escapeMatches.length > 50) {
+    findings.push({
+      category: "html",
+      code: "obfuscated_js",
+      message: `High density of hex/unicode escapes detected (${escapeMatches.length} occurrences)`,
+      level: "warn",
+    });
+  }
+}
+
+function isExternalUrl(url: string): boolean {
+  const lower = url.toLowerCase();
+  return lower.startsWith("http://") || lower.startsWith("https://") || url.startsWith("//");
+}
+
+// ---------------------------------------------------------------------------
+// Phase 3: Asset scan
+// ---------------------------------------------------------------------------
+
+async function scanAssets(zip: JSZip, findings: ScanFinding[], manifestEntry?: string): Promise<void> {
+  const allowedRootFiles = new Set(["index.html", "manifest.json", "signature.json"]);
+  if (manifestEntry) {
+    allowedRootFiles.add(manifestEntry);
+  }
+
+  for (const [name, entry] of Object.entries(zip.files)) {
+    if (entry.dir) continue;
+
+    // Double extension check — only flag when a known content/media extension
+    // appears before the final extension (e.g. file.jpg.exe, file.png.sh),
+    // which is a common technique to disguise executables. Legitimate multi-dot
+    // filenames like app.min.js or vendor.module.css are not flagged.
+    const basename = name.split("/").pop() ?? name;
+    const dotParts = basename.split(".");
+    if (dotParts.length > 2) {
+      const suspiciousInnerExts = new Set([
+        "jpg", "jpeg", "png", "gif", "webp", "svg", "bmp", "ico",
+        "pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx",
+        "html", "htm", "txt", "rtf", "zip", "tar", "gz",
+      ]);
+      // Check if any non-final extension segment is a known content type
+      const innerParts = dotParts.slice(1, -1); // extensions between first dot and last dot
+      const hasSuspiciousInner = innerParts.some((p) => suspiciousInnerExts.has(p.toLowerCase()));
+      if (hasSuspiciousInner) {
+        findings.push({
+          category: "asset",
+          code: "double_extension",
+          message: `File has suspicious double extension: ${name}`,
+          level: "block",
+        });
+      }
+    }
+
+    // Files outside assets/ that aren't allowed root files
+    if (!name.startsWith("assets/") && !allowedRootFiles.has(name)) {
+      findings.push({
+        category: "asset",
+        code: "unexpected_file",
+        message: `Unexpected file outside assets/ directory: ${name}`,
+        level: "warn",
+      });
+    }
+
+    // Magic bytes validation for image files
+    const ext = getExtension(name);
+    const signatures = IMAGE_SIGNATURES[ext];
+    if (signatures) {
+      const data = await entry.async("uint8array");
+      const valid = validateImageMagicBytes(data, ext);
+      if (!valid) {
+        findings.push({
+          category: "asset",
+          code: "magic_bytes_mismatch",
+          message: `File ${name} has extension ${ext} but magic bytes don't match`,
+          level: "block",
+        });
+      }
+    }
+
+    // SVG: should start with < or <?xml
+    if (ext === ".svg") {
+      const data = await entry.async("text");
+      const trimmed = data.trimStart();
+      if (!trimmed.startsWith("<")) {
+        findings.push({
+          category: "asset",
+          code: "magic_bytes_mismatch",
+          message: `File ${name} has extension .svg but does not appear to be valid SVG`,
+          level: "block",
+        });
+      }
+
+      // SVG <script> tags — block-level
+      if (/<script/i.test(data)) {
+        findings.push({
+          category: "asset",
+          code: "svg_script",
+          message: `SVG file contains <script> tag: ${name}`,
+          level: "block",
+        });
+      }
+
+      // SVG event handlers — warn-level
+      if (/\bon\w+\s*=/i.test(data)) {
+        findings.push({
+          category: "asset",
+          code: "svg_event_handler",
+          message: `SVG file contains event handler attribute: ${name}`,
+          level: "warn",
+        });
+      }
+    }
+  }
+}
+
+function getExtension(name: string): string {
+  const dot = name.lastIndexOf(".");
+  if (dot === -1) return "";
+  return name.slice(dot).toLowerCase();
+}
+
+function validateImageMagicBytes(data: Uint8Array, ext: string): boolean {
+  const sigs = IMAGE_SIGNATURES[ext];
+  if (!sigs) return true;
+
+  // Check primary signature
+  const primary = sigs[0];
+  if (data.length < primary.bytes.length) return false;
+  for (let i = 0; i < primary.bytes.length; i++) {
+    if (data[i] !== primary.bytes[i]) return false;
+  }
+
+  // WebP needs additional check: bytes 8-11 should be "WEBP"
+  if (ext === ".webp") {
+    if (data.length < 12) return false;
+    const webp = [0x57, 0x45, 0x42, 0x50]; // WEBP
+    for (let i = 0; i < 4; i++) {
+      if (data[8 + i] !== webp[i]) return false;
+    }
+  }
+
+  return true;
+}

package/src/bundler/bundle-signer.ts

@@ -0,0 +1,124 @@
+/**
+ * Bundle signing for .vellumapp archives.
+ *
+ * Computes content hashes, constructs a canonical signing payload,
+ * and requests an Ed25519 signature from the Swift client via IPC.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import JSZip from 'jszip';
+
+export interface SignatureJson {
+  algorithm: 'ed25519';
+  signer: {
+    key_id: string;
+    display_name: string;
+    account?: string;
+  };
+  content_hashes: Record<string, string>;
+  signature: string; // base64-encoded
+}
+
+/**
+ * Callback type for requesting a signature from the Swift client via IPC.
+ * The caller provides this so the signer doesn't need to know about IPC details.
+ */
+export type SigningCallback = (payload: string) => Promise<{
+  signature: string; // base64-encoded
+  keyId: string;
+  publicKey: string;
+}>;
+
+/**
+ * Recursively sort object keys alphabetically for canonical JSON.
+ */
+function sortKeysDeep(obj: unknown): unknown {
+  if (obj === null || obj === undefined || typeof obj !== 'object') {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(sortKeysDeep);
+  }
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj as Record<string, unknown>).sort()) {
+    sorted[key] = sortKeysDeep((obj as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+/**
+ * Compute SHA-256 hashes of all files in a zip archive, excluding signature.json.
+ */
+async function computeContentHashes(zip: JSZip): Promise<Record<string, string>> {
+  const hashes: Record<string, string> = {};
+  const entries: string[] = [];
+
+  zip.forEach((relativePath, _file) => {
+    if (relativePath !== 'signature.json') {
+      entries.push(relativePath);
+    }
+  });
+
+  // Sort for deterministic ordering
+  entries.sort();
+
+  for (const entryPath of entries) {
+    const file = zip.file(entryPath);
+    if (!file || file.dir) continue;
+    const content = await file.async('nodebuffer');
+    const hash = createHash('sha256').update(content).digest('hex');
+    hashes[entryPath] = hash;
+  }
+
+  return hashes;
+}
+
+/**
+ * Sign a .vellumapp bundle.
+ *
+ * @param bundlePath - Path to the .vellumapp zip archive.
+ * @param requestSignature - Callback to request a signature from the Swift client.
+ * @returns The SignatureJson to embed in the archive.
+ */
+export async function signBundle(
+  bundlePath: string,
+  requestSignature: SigningCallback,
+): Promise<SignatureJson> {
+  const zipBuffer = await readFile(bundlePath);
+  const zip = await JSZip.loadAsync(zipBuffer);
+
+  // 1. Compute content hashes
+  const contentHashes = await computeContentHashes(zip);
+
+  // 2. Read manifest
+  const manifestFile = zip.file('manifest.json');
+  if (!manifestFile) {
+    throw new Error('Bundle is missing manifest.json');
+  }
+  const manifestText = await manifestFile.async('text');
+  const manifest = JSON.parse(manifestText) as Record<string, unknown>;
+
+  // 3. Construct canonical signing payload with sorted keys
+  const signingPayload = sortKeysDeep({
+    content_hashes: contentHashes,
+    manifest,
+  });
+  const canonicalPayload = JSON.stringify(signingPayload);
+
+  // 4. Request signature from Swift via IPC
+  const { signature, keyId } = await requestSignature(canonicalPayload);
+
+  // 5. Build SignatureJson
+  const signatureJson: SignatureJson = {
+    algorithm: 'ed25519',
+    signer: {
+      key_id: keyId,
+      display_name: 'Local Signer',
+    },
+    content_hashes: contentHashes,
+    signature,
+  };
+
+  return signatureJson;
+}

package/src/bundler/manifest.ts

@@ -0,0 +1,21 @@
+/**
+ * Types and serialization for .vellumapp manifest files.
+ */
+
+export interface AppManifest {
+  format_version: number; // always 1
+  name: string;
+  description?: string;
+  icon?: string; // single emoji
+  preview?: string; // base64-encoded PNG thumbnail, max ~50KB
+  created_at: string; // ISO 8601
+  created_by: string; // "vellum-assistant/{version}"
+  entry: string; // "index.html"
+  capabilities: string[]; // empty for MVP
+  version?: string; // semver, defaults to "1.0.0"
+  content_id?: string; // SHA-256 of "created_by:name", 16 hex chars
+}
+
+export function serializeManifest(manifest: AppManifest): string {
+  return JSON.stringify(manifest, null, 2);
+}