aegis-mcp-server 0.1.0

package/src/services/enforcement-engine.ts

@@ -0,0 +1,322 @@
+/**
+ * EnforcementEngine — Validates agent actions against loaded policy.
+ *
+ * All validation happens in Node.js process memory. The agent never sees
+ * the policy files. It only sees the verdict: allowed, or blocked with reason.
+ *
+ * Two-layer enforcement:
+ * Layer 1 (skeleton): permissions.boundaries, scope paths, override_protocol
+ * Layer 2 (extensions): sensitive_patterns, cross_domain_rules, sensitivity_tiers
+ */
+
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join, relative, isAbsolute } from 'node:path';
+import { minimatch } from 'minimatch';
+import type {
+  PolicyState,
+  ResolvedRole,
+  EnforcementVerdict,
+  OverrideLogEntry,
+} from '../types.js';
+
+export class EnforcementEngine {
+  constructor(
+    private state: PolicyState,
+    private activeRole: ResolvedRole
+  ) {}
+
+  /**
+   * Update references when policy reloads.
+   */
+  updateState(state: PolicyState, role: ResolvedRole): void {
+    this.state = state;
+    this.activeRole = role;
+  }
+
+  // ─── Write Validation ─────────────────────────────────────────────────────
+
+  /**
+   * Check if a write to the given path is allowed.
+   * Checks in order: governance forbidden → role excluded → role writable scope.
+   */
+  validateWrite(targetPath: string): EnforcementVerdict {
+    const relPath = this.toRelativePath(targetPath);
+
+    // 1. Governance-level forbidden paths (highest priority)
+    const forbidden = this.state.governance.permissions.boundaries.forbidden;
+    if (forbidden && this.matchesAny(relPath, forbidden)) {
+      return {
+        allowed: false,
+        reason: `Path "${relPath}" is in the forbidden list. This path must never be read or modified.`,
+        policy_ref: 'governance.json > permissions > boundaries > forbidden',
+        immutable: true,
+      };
+    }
+
+    // 2. Governance-level read_only paths
+    const readOnly = this.state.governance.permissions.boundaries.read_only;
+    if (readOnly && this.matchesAny(relPath, readOnly)) {
+      return {
+        allowed: false,
+        reason: `Path "${relPath}" is read-only per governance policy.`,
+        policy_ref: 'governance.json > permissions > boundaries > read_only',
+        immutable: false,
+      };
+    }
+
+    // 3. Role excluded paths
+    if (this.activeRole.excluded_paths.length > 0 &&
+        this.matchesAny(relPath, this.activeRole.excluded_paths)) {
+      return {
+        allowed: false,
+        reason: `Path "${relPath}" is excluded for role "${this.activeRole.id}".`,
+        policy_ref: `roles/${this.activeRole.id}.json > scope > excluded_paths`,
+        immutable: false,
+      };
+    }
+
+    // 4. Role writable scope — must be in writable_paths or secondary_paths
+    if (this.activeRole.writable_paths.length > 0) {
+      const inWritable = this.matchesAny(relPath, this.activeRole.writable_paths);
+      const inSecondary = this.activeRole.secondary_paths.length > 0 &&
+        this.matchesAny(relPath, this.activeRole.secondary_paths);
+
+      if (!inWritable && !inSecondary) {
+        return {
+          allowed: false,
+          reason: `Path "${relPath}" is outside the writable scope of role "${this.activeRole.id}".`,
+          policy_ref: `roles/${this.activeRole.id}.json > scope`,
+          immutable: false,
+        };
+      }
+    }
+
+    // 5. Governance-level writable whitelist (if defined, path must match)
+    const writable = this.state.governance.permissions.boundaries.writable;
+    if (writable && writable.length > 0 && !this.matchesAny(relPath, writable)) {
+      return {
+        allowed: false,
+        reason: `Path "${relPath}" is not in the governance writable list.`,
+        policy_ref: 'governance.json > permissions > boundaries > writable',
+        immutable: false,
+      };
+    }
+
+    return { allowed: true };
+  }
+
+  // ─── Read Validation ──────────────────────────────────────────────────────
+
+  /**
+   * Check if a read of the given path is allowed.
+   */
+  validateRead(targetPath: string): EnforcementVerdict {
+    const relPath = this.toRelativePath(targetPath);
+
+    // Governance-level forbidden
+    const forbidden = this.state.governance.permissions.boundaries.forbidden;
+    if (forbidden && this.matchesAny(relPath, forbidden)) {
+      return {
+        allowed: false,
+        reason: `Path "${relPath}" is forbidden. This path must never be read or modified.`,
+        policy_ref: 'governance.json > permissions > boundaries > forbidden',
+        immutable: true,
+      };
+    }
+
+    // Role excluded paths block reads too
+    if (this.activeRole.excluded_paths.length > 0 &&
+        this.matchesAny(relPath, this.activeRole.excluded_paths)) {
+      return {
+        allowed: false,
+        reason: `Path "${relPath}" is excluded for role "${this.activeRole.id}".`,
+        policy_ref: `roles/${this.activeRole.id}.json > scope > excluded_paths`,
+        immutable: false,
+      };
+    }
+
+    // Role readable scope — if defined, must match
+    if (this.activeRole.readable_paths.length > 0 &&
+        !this.matchesAny(relPath, this.activeRole.readable_paths)) {
+      return {
+        allowed: false,
+        reason: `Path "${relPath}" is outside the readable scope of role "${this.activeRole.id}".`,
+        policy_ref: `roles/${this.activeRole.id}.json > paths > read`,
+        immutable: false,
+      };
+    }
+
+    return { allowed: true };
+  }
+
+  // ─── Content Scanning ─────────────────────────────────────────────────────
+
+  /**
+   * Scan proposed file content for sensitive patterns.
+   * Uses governance.permissions.sensitive_patterns when present.
+   */
+  scanContent(content: string, targetPath: string): EnforcementVerdict {
+    const patterns = this.state.governance.permissions.sensitive_patterns;
+    if (!patterns || patterns.length === 0) return { allowed: true };
+
+    for (const sp of patterns) {
+      const regex = this.compilePattern(sp.pattern);
+      if (!regex) continue;
+
+      if (regex.test(content)) {
+        return {
+          allowed: false,
+          reason: `Content for "${targetPath}" contains a sensitive pattern: ${sp.reason}`,
+          policy_ref: 'governance.json > permissions > sensitive_patterns',
+          immutable: false,
+        };
+      }
+    }
+
+    return { allowed: true };
+  }
+
+  // ─── Cross-Domain Validation ──────────────────────────────────────────────
+
+  /**
+   * Validate that a cross-domain import respects boundaries.
+   * Uses governance.cross_domain_rules when present (extension field).
+   */
+  validateCrossDomain(sourcePath: string, importPath: string): EnforcementVerdict {
+    const rules = this.state.governance.cross_domain_rules;
+    if (!rules || !rules.shared_interfaces_path) return { allowed: true };
+
+    const domains = this.state.constitution.project.domains;
+    if (!domains || domains.length === 0) return { allowed: true };
+
+    const sourceDomain = this.getDomain(sourcePath, domains);
+    const importDomain = this.getDomain(importPath, domains);
+
+    // Same domain or can't determine — allow
+    if (!sourceDomain || !importDomain || sourceDomain === importDomain) {
+      return { allowed: true };
+    }
+
+    // Cross-domain — must go through shared interfaces
+    if (!importPath.includes(rules.shared_interfaces_path)) {
+      return {
+        allowed: false,
+        reason: `Cross-domain import from "${sourceDomain}" to "${importDomain}" must go through "${rules.shared_interfaces_path}". Direct import of "${importPath}" is not allowed.`,
+        policy_ref: 'governance.json > cross_domain_rules',
+        immutable: false,
+      };
+    }
+
+    return { allowed: true };
+  }
+
+  // ─── Override Protocol ────────────────────────────────────────────────────
+
+  /**
+   * Determine how to handle a policy violation based on the override protocol.
+   */
+  getOverrideBehavior(policyRef: string): {
+    behavior: 'block_and_log' | 'warn_confirm_and_log' | 'log_only';
+    isImmutable: boolean;
+  } {
+    const protocol = this.state.governance.override_protocol;
+    const behavior = protocol?.behavior ?? 'warn_confirm_and_log';
+    const immutable = protocol?.immutable_policies ?? [];
+
+    const isImmutable = immutable.some((p) => policyRef.includes(p));
+
+    return {
+      behavior: isImmutable ? 'block_and_log' : behavior,
+      isImmutable,
+    };
+  }
+
+  /**
+   * Log an override to the append-only overrides.jsonl file.
+   */
+  async logOverride(entry: OverrideLogEntry): Promise<void> {
+    const logPath = join(this.state.policyDir, 'state', 'overrides.jsonl');
+    await mkdir(dirname(logPath), { recursive: true });
+    const line = JSON.stringify(entry) + '\n';
+    await appendFile(logPath, line, 'utf-8');
+  }
+
+  // ─── Quality Gates ────────────────────────────────────────────────────────
+
+  /**
+   * Build the list of commands to run for quality gate validation.
+   * Maps pre_commit booleans to build_commands from constitution or governance.
+   */
+  getQualityGateCommands(): Array<{ name: string; command: string }> {
+    const gates = this.state.governance.quality_gate.pre_commit;
+    const commands = this.state.constitution.build_commands ??
+                     this.state.governance.build_commands ??
+                     {};
+
+    const result: Array<{ name: string; command: string }> = [];
+
+    if (gates.must_pass_tests && commands.test) {
+      result.push({ name: 'tests', command: commands.test });
+    }
+    if (gates.must_pass_lint && commands.lint) {
+      result.push({ name: 'lint', command: commands.lint });
+    }
+    if (gates.must_pass_typecheck && commands.typecheck) {
+      result.push({ name: 'typecheck', command: commands.typecheck });
+    }
+
+    // Custom checks from quality gate
+    if (gates.custom_checks) {
+      for (const check of gates.custom_checks) {
+        result.push({ name: check.name, command: check.command });
+      }
+    }
+
+    return result;
+  }
+
+  // ─── Private Helpers ──────────────────────────────────────────────────────
+
+  private matchesAny(path: string, patterns: string[]): boolean {
+    return patterns.some((pattern) => {
+      // Normalize: "compliance/" should match "compliance/src/index.ts"
+      const normalized = pattern.endsWith('/')
+        ? pattern + '**'
+        : pattern;
+      return minimatch(path, normalized, { dot: true });
+    });
+  }
+
+  private toRelativePath(targetPath: string): string {
+    if (isAbsolute(targetPath)) {
+      return relative(this.state.projectRoot, targetPath);
+    }
+    return targetPath;
+  }
+
+  private getDomain(
+    filePath: string,
+    domains: Array<{ name: string; path: string }>
+  ): string | null {
+    for (const domain of domains) {
+      const domainPath = domain.path.replace(/\/$/, '');
+      if (filePath.startsWith(domainPath + '/') || filePath.startsWith(domainPath)) {
+        return domain.name;
+      }
+    }
+    return null;
+  }
+
+  private compilePattern(pattern: string): RegExp | null {
+    try {
+      return new RegExp(pattern, 'gi');
+    } catch {
+      this.log(`Invalid regex in sensitive_patterns: ${pattern}`);
+      return null;
+    }
+  }
+
+  private log(message: string): void {
+    process.stderr.write(`[aegis-enforce] ${message}\n`);
+  }
+}

package/src/services/policy-loader.ts

@@ -0,0 +1,255 @@
+/**
+ * PolicyLoader — Reads .agentpolicy/ files into process memory.
+ *
+ * Core of the zero-token-overhead design. All governance files are loaded
+ * into Node.js process memory on startup. The agent never sees these files —
+ * it only sees tool call results (allowed/blocked).
+ *
+ * Role resolution merges the skeleton fields (role.name, scope.primary_paths)
+ * with extension fields (paths.read/write, forbidden_actions) into a single
+ * ResolvedRole for fast enforcement lookups.
+ */
+
+import { readFile, readdir, access } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { watch } from 'chokidar';
+import type {
+  PolicyState,
+  Constitution,
+  Governance,
+  RoleFile,
+  ResolvedRole,
+  AegisMcpConfig,
+} from '../types.js';
+
+export class PolicyLoader {
+  private state: PolicyState | null = null;
+  private watcher: ReturnType<typeof watch> | null = null;
+  private onReload?: () => void;
+
+  constructor(private config: AegisMcpConfig) {}
+
+  /**
+   * Load all policy files into memory. Call once on startup.
+   */
+  async load(): Promise<PolicyState> {
+    const policyDir = this.resolvePolicyDir();
+    await this.assertExists(policyDir, 'Policy directory');
+
+    const constitution = await this.loadJson<Constitution>(
+      join(policyDir, 'constitution.json'),
+      'constitution.json'
+    );
+
+    const governance = await this.loadJson<Governance>(
+      join(policyDir, 'governance.json'),
+      'governance.json'
+    );
+
+    const roles = await this.loadRoles(join(policyDir, 'roles'));
+
+    this.state = {
+      constitution,
+      governance,
+      roles,
+      projectRoot: this.config.projectRoot,
+      policyDir,
+    };
+
+    this.log(`Policy loaded: ${roles.size} role(s)`);
+    return this.state;
+  }
+
+  /**
+   * Get current policy state. Throws if not loaded.
+   */
+  getState(): PolicyState {
+    if (!this.state) {
+      throw new Error('Policy not loaded. Call load() first.');
+    }
+    return this.state;
+  }
+
+  /**
+   * Start watching .agentpolicy/ for changes and auto-reload.
+   */
+  startWatching(onReload?: () => void): void {
+    this.onReload = onReload;
+    const policyDir = this.resolvePolicyDir();
+
+    this.watcher = watch(policyDir, {
+      ignoreInitial: true,
+      awaitWriteFinish: { stabilityThreshold: 300 },
+    });
+
+    this.watcher.on('change', (path) => this.handleChange(path));
+    this.watcher.on('add', (path) => this.handleChange(path));
+    this.watcher.on('unlink', (path) => this.handleChange(path));
+
+    this.log('Watching policy directory for changes');
+  }
+
+  /**
+   * Stop watching and clean up.
+   */
+  async stopWatching(): Promise<void> {
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = null;
+    }
+  }
+
+  /**
+   * Get the resolved role for the configured agent, falling back to default.
+   */
+  getActiveRole(): ResolvedRole {
+    const state = this.getState();
+    const roleId = this.config.role;
+
+    const role = state.roles.get(roleId);
+    if (role) return role;
+
+    const defaultRole = state.roles.get('default');
+    if (defaultRole) {
+      this.log(`Role "${roleId}" not found, using default`);
+      return defaultRole;
+    }
+
+    // Synthesize a permissive default if no role files exist
+    this.log('No role files found, using synthesized permissive default');
+    return {
+      id: 'default',
+      name: 'default',
+      purpose: 'Synthesized default role — no role files found',
+      writable_paths: ['**/*'],
+      secondary_paths: [],
+      excluded_paths: [],
+      readable_paths: ['**/*'],
+      autonomy: 'advisory',
+      forbidden_actions: [],
+    };
+  }
+
+  // ─── Private ────────────────────────────────────────────────────────────────
+
+  private resolvePolicyDir(): string {
+    return join(
+      this.config.projectRoot,
+      this.config.policyDir ?? '.agentpolicy'
+    );
+  }
+
+  private async loadJson<T>(path: string, label: string): Promise<T> {
+    await this.assertExists(path, label);
+    const raw = await readFile(path, 'utf-8');
+    try {
+      return JSON.parse(raw) as T;
+    } catch (err) {
+      throw new Error(
+        `Failed to parse ${label}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  private async loadRoles(rolesDir: string): Promise<Map<string, ResolvedRole>> {
+    const roles = new Map<string, ResolvedRole>();
+
+    try {
+      await access(rolesDir);
+    } catch {
+      return roles;
+    }
+
+    const entries = await readdir(rolesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+
+      const roleId = basename(entry.name, '.json');
+      const raw = await this.loadJson<RoleFile>(
+        join(rolesDir, entry.name),
+        `roles/${entry.name}`
+      );
+
+      roles.set(roleId, this.resolveRole(roleId, raw));
+    }
+
+    return roles;
+  }
+
+  /**
+   * Merge skeleton and extension fields into a single ResolvedRole.
+   *
+   * Skeleton: role.name, role.purpose, scope.primary_paths/secondary_paths/excluded_paths
+   * Extensions: paths.read/write, forbidden_actions, autonomy (flat string)
+   *
+   * For writable paths: scope.primary_paths takes precedence; paths.write used as fallback.
+   * For readable paths: paths.read used when present; otherwise derived from writable + secondary.
+   */
+  private resolveRole(id: string, raw: RoleFile): ResolvedRole {
+    // Role identity — skeleton nested object, or flat string + description
+    const name = typeof raw.role === 'object' ? raw.role.name : String(raw.role);
+    const purpose = typeof raw.role === 'object'
+      ? raw.role.purpose
+      : (raw.description ?? '');
+
+    // Writable paths — skeleton primary_paths, or extension paths.write
+    const writable_paths = raw.scope?.primary_paths?.length
+      ? raw.scope.primary_paths
+      : (raw.paths?.write ?? []);
+
+    // Secondary paths
+    const secondary_paths = raw.scope?.secondary_paths ?? [];
+
+    // Excluded paths
+    const excluded_paths = raw.scope?.excluded_paths ?? [];
+
+    // Readable paths — extension paths.read, or all writable + secondary
+    const readable_paths = raw.paths?.read?.length
+      ? raw.paths.read
+      : [...writable_paths, ...secondary_paths];
+
+    // Autonomy — flat extension string or skeleton override
+    const autonomy = raw.autonomy
+      ? String(raw.autonomy)
+      : 'advisory';
+
+    // Forbidden actions
+    const forbidden_actions = raw.forbidden_actions ?? [];
+
+    return {
+      id,
+      name,
+      purpose,
+      writable_paths,
+      secondary_paths,
+      excluded_paths,
+      readable_paths,
+      autonomy,
+      forbidden_actions,
+    };
+  }
+
+  private async handleChange(path: string): Promise<void> {
+    this.log(`Policy file changed: ${path}`);
+    try {
+      await this.load();
+      this.onReload?.();
+    } catch (err) {
+      this.log(
+        `Failed to reload policy: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+
+  private async assertExists(path: string, label: string): Promise<void> {
+    try {
+      await access(path);
+    } catch {
+      throw new Error(`${label} not found at: ${path}`);
+    }
+  }
+
+  private log(message: string): void {
+    process.stderr.write(`[aegis-mcp] ${message}\n`);
+  }
+}