flint-agent 1.14.0

package/src/security/content-validator.js

@@ -0,0 +1,132 @@
+// Content Validator — detects real content type by magic bytes
+// Identifies images, audio, video, executables, archives, documents regardless of claimed type
+
+// Magic byte signatures — [offset, bytes, type, subtype]
+const SIGNATURES = [
+  // Images
+  [0, [0xFF, 0xD8, 0xFF], "image", "jpeg"],
+  [0, [0x89, 0x50, 0x4E, 0x47], "image", "png"],
+  [0, [0x47, 0x49, 0x46, 0x38], "image", "gif"],
+  [0, [0x42, 0x4D], "image", "bmp"],
+  [0, [0x49, 0x49, 0x2A, 0x00], "image", "tiff"],
+  [0, [0x4D, 0x4D, 0x00, 0x2A], "image", "tiff"],
+  [0, [0x52, 0x49, 0x46, 0x46], "container", "riff"], // WEBP, AVI, WAV
+  // PDF
+  [0, [0x25, 0x50, 0x44, 0x46], "document", "pdf"],
+  // Executables
+  [0, [0x4D, 0x5A], "executable", "pe"],          // Windows PE (.exe, .dll)
+  [0, [0x7F, 0x45, 0x4C, 0x46], "executable", "elf"],  // Linux ELF
+  [0, [0xCF, 0xFA, 0xED, 0xFE], "executable", "macho"], // macOS Mach-O
+  [0, [0xFE, 0xED, 0xFA, 0xCE], "executable", "macho"], // macOS Mach-O (reverse)
+  [0, [0xFE, 0xED, 0xFA, 0xCF], "executable", "macho64"],
+  // Archives
+  [0, [0x50, 0x4B, 0x03, 0x04], "archive", "zip"],     // ZIP, DOCX, XLSX, JAR
+  [0, [0x1F, 0x8B], "archive", "gzip"],
+  [0, [0x42, 0x5A, 0x68], "archive", "bzip2"],
+  [0, [0xFD, 0x37, 0x7A, 0x58, 0x5A], "archive", "xz"],
+  [0, [0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C], "archive", "7z"],
+  [0, [0x52, 0x61, 0x72, 0x21, 0x1A, 0x07], "archive", "rar"],
+  // Audio
+  [0, [0x49, 0x44, 0x33], "audio", "mp3-id3"],          // MP3 with ID3
+  [0, [0xFF, 0xFB], "audio", "mp3"],
+  [0, [0xFF, 0xF3], "audio", "mp3"],
+  [0, [0x66, 0x4C, 0x61, 0x43], "audio", "flac"],
+  [0, [0x4F, 0x67, 0x67, 0x53], "audio", "ogg"],
+  // Video
+  [4, [0x66, 0x74, 0x79, 0x70], "video", "mp4"],        // MP4/MOV (ftyp at offset 4)
+  [0, [0x1A, 0x45, 0xDF, 0xA3], "video", "webm"],       // WebM/MKV
+  [0, [0x00, 0x00, 0x01, 0xBA], "video", "mpeg"],
+  // Databases
+  [0, [0x53, 0x51, 0x4C, 0x69, 0x74, 0x65], "database", "sqlite"],
+  // Java
+  [0, [0xCA, 0xFE, 0xBA, 0xBE], "executable", "java-class"],
+  // WebAssembly
+  [0, [0x00, 0x61, 0x73, 0x6D], "executable", "wasm"],
+];
+
+/**
+ * Detect content type from raw bytes (Buffer or Uint8Array).
+ * @param {Buffer|Uint8Array} data - Raw binary data (at least first 16 bytes)
+ * @returns {{ type: string, subtype: string } | null}
+ */
+export function detectByMagicBytes(data) {
+  if (!data || data.length < 2) return null;
+
+  for (const [offset, bytes, type, subtype] of SIGNATURES) {
+    if (data.length < offset + bytes.length) continue;
+    let match = true;
+    for (let i = 0; i < bytes.length; i++) {
+      if (data[offset + i] !== bytes[i]) {
+        match = false;
+        break;
+      }
+    }
+    if (match) {
+      // RIFF container — check for WEBP/AVI/WAV
+      if (subtype === "riff" && data.length >= 12) {
+        const fourcc = String.fromCharCode(data[8], data[9], data[10], data[11]);
+        if (fourcc === "WEBP") return { type: "image", subtype: "webp" };
+        if (fourcc === "AVI ") return { type: "video", subtype: "avi" };
+        if (fourcc === "WAVE") return { type: "audio", subtype: "wav" };
+        return { type: "container", subtype: "riff-" + fourcc.trim() };
+      }
+      return { type, subtype };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if content is likely text (not binary).
+ * @param {Buffer|Uint8Array} data
+ * @returns {boolean}
+ */
+export function isLikelyText(data) {
+  if (!data || !data.length) return true;
+  const check = Math.min(data.length, 8192);
+  let nullCount = 0;
+  for (let i = 0; i < check; i++) {
+    if (data[i] === 0) nullCount++;
+  }
+  // More than 1% null bytes → binary
+  return nullCount / check < 0.01;
+}
+
+/**
+ * Check if a base64 string contains binary content.
+ * @param {string} b64 - Base64-encoded string
+ * @returns {{ isBinary: boolean, detected: { type: string, subtype: string } | null }}
+ */
+export function detectBase64Content(b64) {
+  if (!b64 || typeof b64 !== "string") return { isBinary: false, detected: null };
+  try {
+    const buf = Buffer.from(b64, "base64");
+    const detected = detectByMagicBytes(buf);
+    return { isBinary: detected !== null, detected };
+  } catch {
+    return { isBinary: false, detected: null };
+  }
+}
+
+/**
+ * Validate claimed type matches actual content.
+ * @param {string} claimedType - MIME type or extension (e.g., "image/png", ".txt")
+ * @param {Buffer|Uint8Array} data - Raw data
+ * @returns {{ valid: boolean, actual: { type: string, subtype: string } | null, mismatch: boolean }}
+ */
+export function validateContentType(claimedType, data) {
+  const actual = detectByMagicBytes(data);
+  if (!actual) return { valid: true, actual: null, mismatch: false };
+
+  const claimed = (claimedType || "").toLowerCase();
+
+  // Check for dangerous mismatches: claimed text/image but actually executable
+  if (actual.type === "executable") {
+    if (!claimed.includes("executable") && !claimed.includes("application/octet")) {
+      return { valid: false, actual, mismatch: true };
+    }
+  }
+
+  return { valid: true, actual, mismatch: false };
+}

package/src/security/index.js

@@ -0,0 +1,143 @@
+// Security module entry point — orchestrates all security hooks and services
+
+import { loadPolicy, dangerousPatternsThatAsk, DEFAULT_ONBOARDING_LEVEL } from "./policies.js";
+import { createPathGuardHook } from "./path-guard.js";
+import { createContentFenceHook, generateSessionDelimiter } from "./content-fence.js";
+import { createCommandGuardHook } from "./command-guard.js";
+import { createNetworkGuardHook } from "./network-guard.js";
+import { masterTokenIfEnabled, createAuthMiddleware } from "./api-auth.js";
+import { initAudit, auditLog, createAuditBeforeHook, createAuditAfterHook } from "./audit.js";
+import { startWatchdog } from "./watchdog.js";
+import { ALLOW_SECURITY_DISABLE } from "./safety-constants.js";
+import { createChildPolicyHook } from "./child-policy.js";
+import { addBeforeHook, addAfterHook, getOnboardingAnswer } from "../tools/permissions.js";
+import { getCommandApproval } from "../tools/command-approvals.js";
+
+let securityApi = null;
+
+/**
+ * The level used until the onboarding question has been answered.
+ *
+ * Now DEFAULT_ONBOARDING_LEVEL from policies.js, next to LEVELS and
+ * levelOptions(). It used to be a second copy of "normal" living in this file,
+ * which meant the guard and the first-run menu each named the default on their
+ * own and nothing checked that they still named the same one.
+ */
+const DEFAULT_LEVEL = DEFAULT_ONBOARDING_LEVEL;
+
+/**
+ * Initialize the security module.
+ * Registers hooks, starts watchdog, generates API token.
+ *
+ * @param {object} store - Zustand store
+ * @param {object} config - App config
+ * @returns {object} securityApi — { token, delimiter, authMiddleware, stopWatchdog, policy }
+ */
+export function initSecurity(store, config) {
+  // Opt-out via env var — only allowed in test mode
+  if (process.env.AGENT_SECURITY_DISABLE === "1" && ALLOW_SECURITY_DISABLE) {
+    securityApi = {
+      token: null,
+      delimiter: null,
+      authMiddleware: null,
+      stopWatchdog: () => {},
+      policy: null,
+      disabled: true,
+    };
+    return securityApi;
+  }
+
+  try {
+    // Load policy
+    const policy = loadPolicy(config);
+
+    // Initialize audit logging
+    initAudit(config);
+
+    // Generate session-unique delimiter for content fencing
+    const delimiter = generateSessionDelimiter();
+
+    // The token-file key only with FLINT_API_TOKEN_FILE=1; otherwise null and
+    // programs get into the HTTP API by pairing (see masterTokenIfEnabled).
+    const token = masterTokenIfEnabled();
+    const authMiddleware = createAuthMiddleware(token);
+
+    // Register beforeHooks in order:
+    // 1. path-guard — blocks access to critical paths
+    addBeforeHook(createPathGuardHook(policy));
+
+    // 2. command-guard — blocks dangerous shell commands
+    //
+    // The patterns that ASK are the ones the chosen level names, not the ones
+    // the loaded profile carries. Those are two different axes that happen to
+    // share a word: loadPolicy keys on the security profile
+    // (strict/normal/permissive) while the onboarding question asks about the
+    // level (safe/normal/permissive). Wiring the guard to the profile meant the
+    // answer the operator gave had no effect on any command — the level
+    // decided prompts in tests and decided nothing in the app, which is exactly
+    // the shape of bug a suite full of direct unit calls cannot see.
+    //
+    // Unanswered falls back to normal, the documented default. Stated here
+    // rather than left implicit, because a guard handed no patterns at all is a
+    // guard that has silently stopped guarding.
+    // Read per call, not once at boot, so /careful takes effect at once.
+    const guardPolicy = { ...policy };
+    Object.defineProperty(guardPolicy, "dangerousCommandPatterns", {
+      enumerable: true,
+      get: () => dangerousPatternsThatAsk(getOnboardingAnswer() || DEFAULT_LEVEL),
+    });
+    addBeforeHook(createCommandGuardHook(Object.assign(guardPolicy, {
+      // The guard asks this rather than importing it, so the guard stays a pure
+      // function of (policy, command) and the file that owns persistence stays
+      // replaceable in a test.
+      // Named explicitly, not by shorthand: the policy field is called
+      // readCommandApproval and the function is called getCommandApproval, and
+      // a shorthand here made it a reference to an undefined binding — which
+      // initSecurity caught and turned into process.exit(78) at boot.
+      readCommandApproval: getCommandApproval,
+    })));
+
+    // 3. network-guard — blocks private IPs, rate limits
+    addBeforeHook(createNetworkGuardHook(policy, config.port));
+
+    // 4. child-policy — enforces max agent depth
+    addBeforeHook(createChildPolicyHook(policy));
+
+    // 5. audit before hook — logs all tool calls (last, so it logs even if others deny)
+    addBeforeHook(createAuditBeforeHook());
+
+    // Register afterHooks:
+    // 1. content-fence — escapes delimiters, redacts secrets, detects injections
+    addAfterHook(createContentFenceHook(delimiter, policy, { auditLog }));
+
+    // 2. audit after hook — logs tool results
+    addAfterHook(createAuditAfterHook());
+
+    // Start watchdog
+    const stopWatchdog = startWatchdog(store, config, { auditLog });
+
+    securityApi = {
+      token,
+      delimiter,
+      authMiddleware,
+      stopWatchdog,
+      policy,
+      disabled: false,
+    };
+
+    return securityApi;
+  } catch (err) {
+    // SECURITY: Never silently degrade — fail hard if security can't init
+    console.error(`[CRITICAL] Security init failed: ${err.message}`);
+    console.error("[CRITICAL] Agent cannot run without security hooks. Exiting.");
+    process.exit(78); // EX_CONFIG — configuration error
+  }
+}
+
+/**
+ * Get the cached security API (after initSecurity has been called).
+ * @returns {object|null} securityApi
+ */
+export function getSecurityApi() {
+  return securityApi;
+}

package/src/security/network-guard.js

@@ -0,0 +1,126 @@
+// Network guard — beforeHook that blocks private IPs and rate-limits requests
+
+/**
+ * Parse a URL and check if it targets a private/internal IP range.
+ */
+function isPrivateIP(hostname) {
+  // Handle IPv4
+  const ipv4Match = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (ipv4Match) {
+    const [, a, b, c, d] = ipv4Match.map(Number);
+    // 10.0.0.0/8
+    if (a === 10) return true;
+    // 172.16.0.0/12
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    // 192.168.0.0/16
+    if (a === 192 && b === 168) return true;
+    // 127.0.0.0/8 (loopback)
+    if (a === 127) return true;
+    // 169.254.0.0/16 (link-local)
+    if (a === 169 && b === 254) return true;
+    // 0.0.0.0
+    if (a === 0 && b === 0 && c === 0 && d === 0) return true;
+  }
+
+  // Handle common hostnames that resolve to private IPs
+  if (hostname === "localhost") return true;
+
+  // IPv6 loopback
+  if (hostname === "::1" || hostname === "[::1]") return true;
+
+  return false;
+}
+
+/**
+ * Sliding-window rate limiter.
+ */
+function createRateLimiter(maxPerMinute, windowMs) {
+  const timestamps = [];
+
+  return function checkRate() {
+    const now = Date.now();
+    const cutoff = now - windowMs;
+
+    // Remove expired entries
+    while (timestamps.length > 0 && timestamps[0] < cutoff) {
+      timestamps.shift();
+    }
+
+    if (timestamps.length >= maxPerMinute) {
+      return false; // rate limited
+    }
+
+    timestamps.push(now);
+    return true; // allowed
+  };
+}
+
+/**
+ * Create a network-guard beforeHook.
+ * @param {object} policy - Security policy from policies.js
+ * @param {number} [agentPort] - Agent's own port (excluded from private IP block)
+ * @returns {Function} beforeHook(name, args)
+ */
+export function createNetworkGuardHook(policy, agentPort) {
+  const networkPolicy = policy.network || {};
+  const rateLimiter = networkPolicy.rateLimit
+    ? createRateLimiter(networkPolicy.rateLimit.maxPerMinute, networkPolicy.rateLimit.windowMs)
+    : null;
+
+  return function networkGuardHook(name, args) {
+    if (name !== "web_fetch" && name !== "web_search") return null;
+
+    // web_search doesn't have a user-provided URL to validate
+    if (name === "web_search") {
+      // Just apply rate limiting
+      if (rateLimiter && !rateLimiter()) {
+        return { deny: true, reason: "rate limited: too many network requests per minute" };
+      }
+      return null;
+    }
+
+    // web_fetch — validate URL
+    const url = args.url;
+    if (!url || typeof url !== "string") return null;
+
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return { deny: true, reason: `invalid URL: "${url}"` };
+    }
+
+    // Block non-http(s) protocols
+    if (networkPolicy.blockNonHttpProtocols) {
+      const protocol = parsed.protocol.toLowerCase();
+      if (protocol !== "http:" && protocol !== "https:") {
+        return { deny: true, reason: `blocked protocol: ${protocol} (only http/https allowed)` };
+      }
+    }
+
+    // Block private IPs
+    if (networkPolicy.blockPrivateIPs) {
+      const hostname = parsed.hostname;
+      if (isPrivateIP(hostname)) {
+        // Allow agent's own port on localhost
+        const port = parseInt(parsed.port, 10) || (parsed.protocol === "https:" ? 443 : 80);
+        if (hostname === "localhost" || hostname === "127.0.0.1") {
+          if (agentPort && port === agentPort) {
+            // Allow self-requests (e.g., timer callbacks)
+          } else {
+            return { deny: true, reason: `blocked private IP: ${hostname}:${port}` };
+          }
+        } else {
+          return { deny: true, reason: `blocked private IP: ${hostname}` };
+        }
+      }
+    }
+
+    // Rate limiting
+    if (rateLimiter && !rateLimiter()) {
+      return { deny: true, reason: "rate limited: too many network requests per minute" };
+    }
+
+    return null;
+  };
+}

package/src/security/pairing.js

@@ -0,0 +1,180 @@
+// Agent pairing protocol — PIN-based authentication for peer agents
+
+import crypto from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const MAX_ATTEMPTS = 3;
+const MAX_SESSIONS = 5;
+const PIN_EXPIRY_MS = 180_000; // 3 minutes
+
+/** @type {Map<string, object>} */
+const sessions = new Map();
+
+// Paired programs, kept across restarts (owner, 2026-10-02): pairing is the
+// only way into the HTTP API by default, so it has to be once per program,
+// not once per run. Only a SHA-256 of each token is written, so the file
+// grants nothing to whoever reads it. The path is resolved per call, so a
+// test's sandboxed home is honoured.
+const flintDir = () => join(homedir(), ".flint");
+const pairedFile = () => join(flintDir(), "paired-clients.json");
+
+/** @type {Array<{ hash: string, name: string, address: string, pairedAt: string }>|null} */
+let clients = null;
+
+const hashOf = (token) => crypto.createHash("sha256").update(String(token)).digest("hex");
+
+function loadClients() {
+  if (clients) return clients;
+  try {
+    const raw = existsSync(pairedFile()) ? JSON.parse(readFileSync(pairedFile(), "utf-8")) : [];
+    clients = Array.isArray(raw) ? raw.filter((c) => c && typeof c.hash === "string") : [];
+  } catch {
+    clients = [];
+  }
+  return clients;
+}
+
+function saveClients() {
+  mkdirSync(flintDir(), { recursive: true });
+  const tmp = pairedFile() + ".tmp";
+  writeFileSync(tmp, JSON.stringify(clients, null, 2), { encoding: "utf-8", mode: 0o600 });
+  renameSync(tmp, pairedFile());
+}
+
+export function generatePin() {
+  return String(crypto.randomInt(0, 1_000_000)).padStart(6, "0");
+}
+
+export function createPairingSession(fromAddress) {
+  cleanExpiredSessions();
+  if (sessions.size >= MAX_SESSIONS) {
+    return { error: "Too many active pairing sessions" };
+  }
+
+  const sessionId = crypto.randomUUID();
+  const pin = generatePin();
+  const expiresAt = Date.now() + PIN_EXPIRY_MS;
+
+  sessions.set(sessionId, {
+    pin,
+    attempts: 0,
+    expiresAt,
+    fromAddress,
+    invalidated: false,
+  });
+
+  return { sessionId, pin, expiresAt };
+}
+
+/**
+ * @param {string} sessionId
+ * @param {string} candidatePin
+ * @param {{ name?: string, address?: string }} [who] - Kept with the pairing, for /paired
+ */
+export function verifyPin(sessionId, candidatePin, who = {}) {
+  const session = sessions.get(sessionId);
+
+  if (!session || session.invalidated) {
+    return { valid: false, error: "Invalid or expired session" };
+  }
+
+  if (Date.now() > session.expiresAt) {
+    sessions.delete(sessionId);
+    return { valid: false, error: "Session expired" };
+  }
+
+  session.attempts++;
+
+  // Constant-time comparison
+  const expected = Buffer.from(session.pin, "utf-8");
+  const received = Buffer.from(String(candidatePin).padStart(6, "0"), "utf-8");
+  const match =
+    expected.length === received.length &&
+    crypto.timingSafeEqual(expected, received);
+
+  if (!match) {
+    if (session.attempts >= MAX_ATTEMPTS) {
+      session.invalidated = true;
+      sessions.delete(sessionId);
+      return { valid: false, error: "Max attempts exceeded, session invalidated" };
+    }
+    return {
+      valid: false,
+      error: `Invalid PIN (${MAX_ATTEMPTS - session.attempts} attempts remaining)`,
+    };
+  }
+
+  // Success — generate bearer token
+  const token = crypto.randomBytes(32).toString("hex");
+  loadClients().push({
+    hash: hashOf(token),
+    name: String(who.name || "unnamed").slice(0, 60),
+    address: String(who.address || session.fromAddress || "unknown"),
+    pairedAt: new Date().toISOString(),
+  });
+  saveClients();
+  sessions.delete(sessionId);
+  return { valid: true, token };
+}
+
+export function cleanExpiredSessions() {
+  const now = Date.now();
+  for (const [id, s] of sessions) {
+    if (now > s.expiresAt || s.invalidated) {
+      sessions.delete(id);
+    }
+  }
+}
+
+export function isPairedToken(token) {
+  if (!token) return false;
+  const h = Buffer.from(hashOf(token), "hex");
+  return loadClients().some((c) => {
+    const k = Buffer.from(c.hash, "hex");
+    return k.length === h.length && crypto.timingSafeEqual(k, h);
+  });
+}
+
+/** Paired programs, without their hashes. */
+export function listPairedClients() {
+  return loadClients().map(({ name, address, pairedAt }) => ({ name, address, pairedAt }));
+}
+
+/**
+ * Revoke the pairings of one program by name, or every pairing with "all".
+ * @returns {number} How many were revoked
+ */
+export function revokePairedClients(nameOrAll) {
+  const before = loadClients().length;
+  clients = nameOrAll === "all" ? [] : clients.filter((c) => c.name !== nameOrAll);
+  const n = before - clients.length;
+  if (n > 0 || nameOrAll === "all") saveClients();
+  return n;
+}
+
+export function revokePairedToken(token) {
+  const h = hashOf(token);
+  const before = loadClients().length;
+  clients = clients.filter((c) => c.hash !== h);
+  if (clients.length === before) return false;
+  saveClients();
+  return true;
+}
+
+export function revokeAllPairedTokens() {
+  revokePairedClients("all");
+}
+
+export function getActiveSessions() {
+  cleanExpiredSessions();
+  return sessions.size;
+}
+
+// For testing
+export function _reset() {
+  sessions.clear();
+  clients = [];
+  saveClients();
+}