@openparachute/agent 0.1.2 → 0.2.0

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

@@ -1,459 +0,0 @@
-/**
- * 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: `<HOME>/.config/parachute-agent/mount-allowlist.json`
- * (pre-0.1.0 installs auto-migrate from `<HOME>/.config/paraclaw/` on startup —
- * see migrateLegacyAllowlistDir below). Path stays under `<HOME>/.config/`,
- * NOT under `PARACHUTE_DIR`, because mount-allowlist is operator-host policy
- * rather than per-install runtime state — see the doc-block on `ALLOWLIST_DIR`
- * in src/config.ts (paraclaw#99).
- *
- * `HOME_DIR` is imported from src/config.ts so the precedence rule
- * (`process.env.HOME` → `os.homedir()`) lives in one place. expandPath uses
- * the same HOME_DIR for `~`-expansion in operator-supplied paths inside the
- * allowlist (`~/projects` etc.), ensuring expansion agrees with the rest of
- * the host process.
- */
-import fs from 'fs';
-import path from 'path';
-import { ALLOWLIST_DIR, HOME_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. `HOME_DIR` comes
- * from src/config.ts so a future change to the precedence rule
- * (`HOME` → `os.homedir()`) is one edit upstream rather than redrawn here.
- * Exported for direct test coverage of the expansion (paraclaw#99); not
- * intended for use outside this module.
- */
-export function expandPath(p: string): string {
-  if (p.startsWith('~/')) {
-    return path.join(HOME_DIR, p.slice(2));
-  }
-  if (p === '~') {
-    return HOME_DIR;
-  }
-  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

@@ -1,91 +0,0 @@
-/**
- * `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

@@ -1,28 +0,0 @@
-/**
- * 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' };
-}