@openparachute/agent 0.1.0

package/src/modules/mount-security/index.ts

@@ -0,0 +1,448 @@
+/**
+ * Mount Security Module for parachute-agent
+ *
+ * Validates additional mounts against an allowlist stored OUTSIDE the project root.
+ * This prevents container agents from modifying security configuration.
+ *
+ * Allowlist location: ~/.config/parachute-agent/mount-allowlist.json
+ * (pre-0.1.0 installs auto-migrate from ~/.config/paraclaw/ on startup —
+ * see migrateLegacyAllowlistDir below).
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { ALLOWLIST_DIR, LEGACY_ALLOWLIST_DIR, MOUNT_ALLOWLIST_PATH } from '../../config.js';
+import { log } from '../../log.js';
+
+export interface AdditionalMount {
+  hostPath: string;
+  containerPath?: string;
+  readonly?: boolean;
+}
+
+export interface MountAllowlist {
+  allowedRoots: AllowedRoot[];
+  blockedPatterns: string[];
+}
+
+export interface AllowedRoot {
+  path: string;
+  allowReadWrite: boolean;
+  description?: string;
+}
+
+// Cache the allowlist in memory - only reloads on process restart
+let cachedAllowlist: MountAllowlist | null = null;
+let allowlistLoadError: string | null = null;
+
+/**
+ * Default blocked patterns - paths that should never be mounted
+ */
+const DEFAULT_BLOCKED_PATTERNS = [
+  '.ssh',
+  '.gnupg',
+  '.gpg',
+  '.aws',
+  '.azure',
+  '.gcloud',
+  '.kube',
+  '.docker',
+  'credentials',
+  '.env',
+  '.netrc',
+  '.npmrc',
+  '.pypirc',
+  'id_rsa',
+  'id_ed25519',
+  'private_key',
+  '.secret',
+];
+
+/**
+ * Load the mount allowlist from the external config location.
+ * Returns null if the file doesn't exist or is invalid.
+ * Result is cached in memory for the lifetime of the process.
+ */
+export function loadMountAllowlist(): MountAllowlist | null {
+  if (cachedAllowlist !== null) {
+    return cachedAllowlist;
+  }
+
+  if (allowlistLoadError !== null) {
+    // Already tried and failed, don't spam logs
+    return null;
+  }
+
+  try {
+    if (!fs.existsSync(MOUNT_ALLOWLIST_PATH)) {
+      // Do NOT cache this as an error — file may be created later without restart.
+      // Only parse/structural errors are permanently cached.
+      log.warn(
+        'Mount allowlist not found - additional mounts will be BLOCKED. Create the file to enable additional mounts.',
+        { path: MOUNT_ALLOWLIST_PATH },
+      );
+      return null;
+    }
+
+    const content = fs.readFileSync(MOUNT_ALLOWLIST_PATH, 'utf-8');
+    const allowlist = JSON.parse(content) as MountAllowlist;
+
+    // Validate structure
+    if (!Array.isArray(allowlist.allowedRoots)) {
+      throw new Error('allowedRoots must be an array');
+    }
+
+    if (!Array.isArray(allowlist.blockedPatterns)) {
+      throw new Error('blockedPatterns must be an array');
+    }
+
+    // Merge with default blocked patterns
+    const mergedBlockedPatterns = [...new Set([...DEFAULT_BLOCKED_PATTERNS, ...allowlist.blockedPatterns])];
+    allowlist.blockedPatterns = mergedBlockedPatterns;
+
+    cachedAllowlist = allowlist;
+    log.info('Mount allowlist loaded successfully', {
+      path: MOUNT_ALLOWLIST_PATH,
+      allowedRoots: allowlist.allowedRoots.length,
+      blockedPatterns: allowlist.blockedPatterns.length,
+    });
+
+    return cachedAllowlist;
+  } catch (err) {
+    allowlistLoadError = err instanceof Error ? err.message : String(err);
+    log.error('Failed to load mount allowlist - additional mounts will be BLOCKED', {
+      path: MOUNT_ALLOWLIST_PATH,
+      error: allowlistLoadError,
+    });
+    return null;
+  }
+}
+
+/**
+ * Expand ~ to home directory and resolve to absolute path
+ */
+function expandPath(p: string): string {
+  const homeDir = process.env.HOME || os.homedir();
+  if (p.startsWith('~/')) {
+    return path.join(homeDir, p.slice(2));
+  }
+  if (p === '~') {
+    return homeDir;
+  }
+  return path.resolve(p);
+}
+
+/**
+ * Get the real path, resolving symlinks.
+ * Returns null if the path doesn't exist.
+ */
+function getRealPath(p: string): string | null {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if a path matches any blocked pattern
+ */
+function matchesBlockedPattern(realPath: string, blockedPatterns: string[]): string | null {
+  const pathParts = realPath.split(path.sep);
+
+  for (const pattern of blockedPatterns) {
+    // Check if any path component matches the pattern
+    for (const part of pathParts) {
+      if (part === pattern || part.includes(pattern)) {
+        return pattern;
+      }
+    }
+
+    // Also check if the full path contains the pattern
+    if (realPath.includes(pattern)) {
+      return pattern;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if a real path is under an allowed root
+ */
+function findAllowedRoot(realPath: string, allowedRoots: AllowedRoot[]): AllowedRoot | null {
+  for (const root of allowedRoots) {
+    const expandedRoot = expandPath(root.path);
+    const realRoot = getRealPath(expandedRoot);
+
+    if (realRoot === null) {
+      // Allowed root doesn't exist, skip it
+      continue;
+    }
+
+    // Check if realPath is under realRoot
+    const relative = path.relative(realRoot, realPath);
+    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+      return root;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Validate the container path to prevent escaping /workspace/extra/
+ */
+function isValidContainerPath(containerPath: string): boolean {
+  // Must not contain .. to prevent path traversal
+  if (containerPath.includes('..')) {
+    return false;
+  }
+
+  // Must not be absolute (it will be prefixed with /workspace/extra/)
+  if (containerPath.startsWith('/')) {
+    return false;
+  }
+
+  // Must not be empty
+  if (!containerPath || containerPath.trim() === '') {
+    return false;
+  }
+
+  // Must not contain colons — prevents Docker -v option injection (e.g., "repo:rw")
+  if (containerPath.includes(':')) {
+    return false;
+  }
+
+  return true;
+}
+
+export interface MountValidationResult {
+  allowed: boolean;
+  reason: string;
+  realHostPath?: string;
+  resolvedContainerPath?: string;
+  effectiveReadonly?: boolean;
+}
+
+/**
+ * Validate a single additional mount against the allowlist.
+ * Returns validation result with reason.
+ */
+export function validateMount(mount: AdditionalMount): MountValidationResult {
+  const allowlist = loadMountAllowlist();
+
+  // If no allowlist, block all additional mounts
+  if (allowlist === null) {
+    return {
+      allowed: false,
+      reason: `No mount allowlist configured at ${MOUNT_ALLOWLIST_PATH}`,
+    };
+  }
+
+  // Derive containerPath from hostPath basename if not specified
+  const containerPath = mount.containerPath || path.basename(mount.hostPath);
+
+  // Validate container path (cheap check)
+  if (!isValidContainerPath(containerPath)) {
+    return {
+      allowed: false,
+      reason: `Invalid container path: "${containerPath}" - must be relative, non-empty, and not contain ".."`,
+    };
+  }
+
+  // Expand and resolve the host path
+  const expandedPath = expandPath(mount.hostPath);
+  const realPath = getRealPath(expandedPath);
+
+  if (realPath === null) {
+    return {
+      allowed: false,
+      reason: `Host path does not exist: "${mount.hostPath}" (expanded: "${expandedPath}")`,
+    };
+  }
+
+  // Check against blocked patterns
+  const blockedMatch = matchesBlockedPattern(realPath, allowlist.blockedPatterns);
+  if (blockedMatch !== null) {
+    return {
+      allowed: false,
+      reason: `Path matches blocked pattern "${blockedMatch}": "${realPath}"`,
+    };
+  }
+
+  // Check if under an allowed root
+  const allowedRoot = findAllowedRoot(realPath, allowlist.allowedRoots);
+  if (allowedRoot === null) {
+    return {
+      allowed: false,
+      reason: `Path "${realPath}" is not under any allowed root. Allowed roots: ${allowlist.allowedRoots
+        .map((r) => expandPath(r.path))
+        .join(', ')}`,
+    };
+  }
+
+  // Determine effective readonly status.
+  // RW is only granted if the mount explicitly requests it AND the allowed
+  // root permits it. Otherwise it's forced read-only.
+  const requestedReadWrite = mount.readonly === false;
+  let effectiveReadonly = true;
+
+  if (requestedReadWrite) {
+    if (!allowedRoot.allowReadWrite) {
+      log.info('Mount forced to read-only - root does not allow read-write', {
+        mount: mount.hostPath,
+        root: allowedRoot.path,
+      });
+    } else {
+      effectiveReadonly = false;
+    }
+  }
+
+  return {
+    allowed: true,
+    reason: `Allowed under root "${allowedRoot.path}"${allowedRoot.description ? ` (${allowedRoot.description})` : ''}`,
+    realHostPath: realPath,
+    resolvedContainerPath: containerPath,
+    effectiveReadonly,
+  };
+}
+
+/**
+ * Validate all additional mounts for a group.
+ * Returns array of validated mounts (only those that passed validation).
+ * Logs warnings for rejected mounts.
+ */
+export function validateAdditionalMounts(
+  mounts: AdditionalMount[],
+  groupName: string,
+): Array<{
+  hostPath: string;
+  containerPath: string;
+  readonly: boolean;
+}> {
+  const validatedMounts: Array<{
+    hostPath: string;
+    containerPath: string;
+    readonly: boolean;
+  }> = [];
+
+  for (const mount of mounts) {
+    const result = validateMount(mount);
+
+    if (result.allowed) {
+      validatedMounts.push({
+        hostPath: result.realHostPath!,
+        containerPath: `/workspace/extra/${result.resolvedContainerPath}`,
+        readonly: result.effectiveReadonly!,
+      });
+
+      log.debug('Mount validated successfully', {
+        group: groupName,
+        hostPath: result.realHostPath,
+        containerPath: result.resolvedContainerPath,
+        readonly: result.effectiveReadonly,
+        reason: result.reason,
+      });
+    } else {
+      log.warn('Additional mount REJECTED', {
+        group: groupName,
+        requestedPath: mount.hostPath,
+        containerPath: mount.containerPath,
+        reason: result.reason,
+      });
+    }
+  }
+
+  return validatedMounts;
+}
+
+/**
+ * One-shot move of `~/.config/paraclaw/{mount,sender}-allowlist.json` to the
+ * `~/.config/parachute-agent/` dir. Called early at host startup so a 0.1.0
+ * install picks up an operator's existing allowlist without a manual `mv`.
+ *
+ * Idempotent — moves a file only when the legacy file exists and the new
+ * path is absent. The legacy directory itself is left in place: the operator
+ * may have other files there, and a missing-but-empty legacy dir on the next
+ * boot is a harmless no-op. Best-effort: rename failures (permission / race)
+ * log and continue. Drop in 0.2.0 along with the rest of the paraclaw-era
+ * compat sweep.
+ *
+ * Args default to the canonical `~/.config/{paraclaw,parachute-agent}` pair;
+ * the test injects scratch dirs.
+ */
+export function migrateLegacyAllowlistDir(
+  legacyDir: string = LEGACY_ALLOWLIST_DIR,
+  currentDir: string = ALLOWLIST_DIR,
+): void {
+  let legacyDirExists: boolean;
+  try {
+    legacyDirExists = fs.statSync(legacyDir).isDirectory();
+  } catch {
+    return;
+  }
+  if (!legacyDirExists) return;
+
+  try {
+    fs.mkdirSync(currentDir, { recursive: true });
+  } catch (err) {
+    log.warn('Could not create parachute-agent allowlist dir', { dir: currentDir, err });
+    return;
+  }
+
+  const filenames = ['mount-allowlist.json', 'sender-allowlist.json'];
+  for (const name of filenames) {
+    const legacy = path.join(legacyDir, name);
+    const current = path.join(currentDir, name);
+
+    let legacyFileExists: boolean;
+    try {
+      legacyFileExists = fs.statSync(legacy).isFile();
+    } catch {
+      continue;
+    }
+    if (!legacyFileExists) continue;
+    if (fs.existsSync(current)) continue;
+
+    try {
+      fs.renameSync(legacy, current);
+      log.info('Allowlist migrated from legacy dir', { from: legacy, to: current });
+    } catch (err) {
+      log.warn('Could not migrate legacy allowlist file', { from: legacy, to: current, err });
+    }
+  }
+}
+
+/**
+ * Generate a template allowlist file for users to customize
+ */
+export function generateAllowlistTemplate(): string {
+  const template: MountAllowlist = {
+    allowedRoots: [
+      {
+        path: '~/projects',
+        allowReadWrite: true,
+        description: 'Development projects',
+      },
+      {
+        path: '~/repos',
+        allowReadWrite: true,
+        description: 'Git repositories',
+      },
+      {
+        path: '~/Documents/work',
+        allowReadWrite: false,
+        description: 'Work documents (read-only)',
+      },
+    ],
+    blockedPatterns: [
+      // Additional patterns beyond defaults
+      'password',
+      'secret',
+      'token',
+    ],
+  };
+
+  return JSON.stringify(template, null, 2);
+}

package/src/modules/mount-security/migrate.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `migrateLegacyAllowlistDir` — idempotent move of
+ * `~/.config/paraclaw/{mount,sender}-allowlist.json` to
+ * `~/.config/parachute-agent/` at host startup. Tests use injected scratch
+ * dirs (the function accepts overrides) so we don't touch the real
+ * `$HOME/.config`.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { migrateLegacyAllowlistDir } from './index.js';
+
+let scratchRoot: string;
+let legacyDir: string;
+let currentDir: string;
+
+beforeEach(() => {
+  scratchRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-allowlist-migrate-'));
+  legacyDir = path.join(scratchRoot, 'paraclaw');
+  currentDir = path.join(scratchRoot, 'parachute-agent');
+});
+
+afterEach(() => {
+  fs.rmSync(scratchRoot, { recursive: true, force: true });
+});
+
+describe('migrateLegacyAllowlistDir', () => {
+  it('moves both legacy allowlist files to the new dir when present', () => {
+    fs.mkdirSync(legacyDir, { recursive: true });
+    fs.writeFileSync(path.join(legacyDir, 'mount-allowlist.json'), '{"mount":1}\n');
+    fs.writeFileSync(path.join(legacyDir, 'sender-allowlist.json'), '{"sender":1}\n');
+
+    migrateLegacyAllowlistDir(legacyDir, currentDir);
+
+    expect(fs.readFileSync(path.join(currentDir, 'mount-allowlist.json'), 'utf8')).toBe('{"mount":1}\n');
+    expect(fs.readFileSync(path.join(currentDir, 'sender-allowlist.json'), 'utf8')).toBe('{"sender":1}\n');
+    expect(fs.existsSync(path.join(legacyDir, 'mount-allowlist.json'))).toBe(false);
+    expect(fs.existsSync(path.join(legacyDir, 'sender-allowlist.json'))).toBe(false);
+  });
+
+  it('is a no-op when the legacy dir does not exist (fresh install)', () => {
+    fs.mkdirSync(currentDir, { recursive: true });
+    fs.writeFileSync(path.join(currentDir, 'mount-allowlist.json'), '{"fresh":1}\n');
+
+    migrateLegacyAllowlistDir(legacyDir, currentDir);
+
+    expect(fs.readFileSync(path.join(currentDir, 'mount-allowlist.json'), 'utf8')).toBe('{"fresh":1}\n');
+    expect(fs.existsSync(legacyDir)).toBe(false);
+  });
+
+  it('does not clobber existing files in the new dir (post-migration coexistence)', () => {
+    // The operator may have populated the new dir before re-running an
+    // installer that triggers another migration pass. Treat the new file
+    // as canonical and leave the legacy orphan alone — the operator
+    // deletes it deliberately.
+    fs.mkdirSync(legacyDir, { recursive: true });
+    fs.mkdirSync(currentDir, { recursive: true });
+    fs.writeFileSync(path.join(legacyDir, 'mount-allowlist.json'), '{"orphan":1}\n');
+    fs.writeFileSync(path.join(currentDir, 'mount-allowlist.json'), '{"live":1}\n');
+
+    migrateLegacyAllowlistDir(legacyDir, currentDir);
+
+    expect(fs.readFileSync(path.join(currentDir, 'mount-allowlist.json'), 'utf8')).toBe('{"live":1}\n');
+    expect(fs.readFileSync(path.join(legacyDir, 'mount-allowlist.json'), 'utf8')).toBe('{"orphan":1}\n');
+  });
+
+  it('handles only one of the two legacy files existing', () => {
+    fs.mkdirSync(legacyDir, { recursive: true });
+    fs.writeFileSync(path.join(legacyDir, 'sender-allowlist.json'), '{"sender":1}\n');
+
+    migrateLegacyAllowlistDir(legacyDir, currentDir);
+
+    expect(fs.existsSync(path.join(currentDir, 'mount-allowlist.json'))).toBe(false);
+    expect(fs.readFileSync(path.join(currentDir, 'sender-allowlist.json'), 'utf8')).toBe('{"sender":1}\n');
+  });
+
+  it('creates the new dir when it does not yet exist', () => {
+    fs.mkdirSync(legacyDir, { recursive: true });
+    fs.writeFileSync(path.join(legacyDir, 'mount-allowlist.json'), '{"m":1}\n');
+
+    expect(fs.existsSync(currentDir)).toBe(false);
+
+    migrateLegacyAllowlistDir(legacyDir, currentDir);
+
+    expect(fs.statSync(currentDir).isDirectory()).toBe(true);
+    expect(fs.readFileSync(path.join(currentDir, 'mount-allowlist.json'), 'utf8')).toBe('{"m":1}\n');
+  });
+});

package/src/modules/permissions/access.ts

@@ -0,0 +1,28 @@
+/**
+ * Access control.
+ *
+ * Privilege is user-level, not group-level. A user holds zero or more roles
+ * (owner | admin) via `user_roles`, and is optionally "known" in specific
+ * agent groups via `agent_group_members`. Admins are implicitly members of
+ * the groups they administer.
+ *
+ * Approver-picking (`pickApprover`, `pickApprovalDelivery`) lives in the
+ * approvals module — see `src/modules/approvals/primitive.ts`.
+ */
+import { isMember } from './db/agent-group-members.js';
+import { isAdminOfAgentGroup, isGlobalAdmin, isOwner } from './db/user-roles.js';
+import { getUser } from './db/users.js';
+
+export type AccessDecision =
+  | { allowed: true; reason: 'owner' | 'global_admin' | 'admin_of_group' | 'member' }
+  | { allowed: false; reason: 'unknown_user' | 'not_member' };
+
+/** Can this user interact with this agent group? */
+export function canAccessAgentGroup(userId: string, agentGroupId: string): AccessDecision {
+  if (!getUser(userId)) return { allowed: false, reason: 'unknown_user' };
+  if (isOwner(userId)) return { allowed: true, reason: 'owner' };
+  if (isGlobalAdmin(userId)) return { allowed: true, reason: 'global_admin' };
+  if (isAdminOfAgentGroup(userId, agentGroupId)) return { allowed: true, reason: 'admin_of_group' };
+  if (isMember(userId, agentGroupId)) return { allowed: true, reason: 'member' };
+  return { allowed: false, reason: 'not_member' };
+}