@gotgenes/pi-permission-system 5.4.0 → 5.5.0

package/src/policy-loader.ts

@@ -0,0 +1,350 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+import { extractFrontmatter, parseSimpleYamlMap, toRecord } from "./common";
+import {
+  loadUnifiedConfig,
+  normalizeUnifiedConfig,
+  stripJsonComments,
+} from "./config-loader";
+import { getGlobalConfigPath } from "./config-paths";
+import type { ScopeConfig } from "./types";
+
+// ---------------------------------------------------------------------------
+// File-stamp helper
+// ---------------------------------------------------------------------------
+
+function getFileStamp(path: string): string {
+  try {
+    return String(statSync(path).mtimeMs);
+  } catch {
+    return "missing";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MCP server-name reading helpers
+// ---------------------------------------------------------------------------
+
+function readConfiguredMcpServerNamesFromConfigPath(
+  configPath: string,
+): string[] {
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(stripJsonComments(raw)) as unknown;
+    const root = toRecord(parsed);
+    const serverRecord = toRecord(root.mcpServers ?? root["mcp-servers"]);
+
+    return Object.keys(serverRecord)
+      .map((name) => name.trim())
+      .filter((name) => name.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+function getConfiguredMcpServerNamesFromPaths(
+  paths: readonly string[],
+): string[] {
+  const seen = new Set<string>();
+
+  for (const path of paths) {
+    for (const name of readConfiguredMcpServerNamesFromConfigPath(path)) {
+      seen.add(name);
+    }
+  }
+
+  return [...seen].sort(
+    (left, right) => right.length - left.length || left.localeCompare(right),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Resolved policy paths
+// ---------------------------------------------------------------------------
+
+export interface ResolvedPolicyPaths {
+  globalConfigPath: string;
+  globalConfigExists: boolean;
+  projectConfigPath: string | null;
+  projectConfigExists: boolean;
+  agentsDir: string;
+  agentsDirExists: boolean;
+  projectAgentsDir: string | null;
+  projectAgentsDirExists: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// PolicyLoader interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Abstraction over file I/O for loading permission policy from disk.
+ * Implementations handle caching, path resolution, and config-issue
+ * accumulation.  `PermissionManager` depends on this interface so that
+ * merge + evaluation logic can be tested with an in-memory stub.
+ */
+export interface PolicyLoader {
+  loadGlobalConfig(): ScopeConfig;
+  loadProjectConfig(): ScopeConfig;
+  loadAgentConfig(agentName?: string): ScopeConfig;
+  loadProjectAgentConfig(agentName?: string): ScopeConfig;
+  getConfiguredMcpServerNames(): readonly string[];
+  /** Combined mtime stamp for cache invalidation. */
+  getCacheStamp(agentName?: string): string;
+  /** Accumulated config-parse issues across all loads. */
+  getConfigIssues(): string[];
+  /** Resolved paths for the /permission-system show command. */
+  getResolvedPolicyPaths(): ResolvedPolicyPaths;
+}
+
+// ---------------------------------------------------------------------------
+// Default path factories (deferred until call-time, not module scope)
+// ---------------------------------------------------------------------------
+
+function defaultGlobalConfigPath(): string {
+  return getGlobalConfigPath(getAgentDir());
+}
+function defaultAgentsDir(): string {
+  return join(getAgentDir(), "agents");
+}
+function defaultGlobalMcpConfigPath(): string {
+  return join(getAgentDir(), "mcp.json");
+}
+
+// ---------------------------------------------------------------------------
+// File cache helper type
+// ---------------------------------------------------------------------------
+
+type FileCacheEntry<TValue> = {
+  stamp: string;
+  value: TValue;
+};
+
+// ---------------------------------------------------------------------------
+// Options shared between FilePolicyLoader and the backward-compat
+// PermissionManager constructor.
+// ---------------------------------------------------------------------------
+
+export interface PolicyLoaderOptions {
+  globalConfigPath?: string;
+  agentsDir?: string;
+  projectGlobalConfigPath?: string;
+  projectAgentsDir?: string;
+  globalMcpConfigPath?: string;
+  mcpServerNames?: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// FilePolicyLoader — the production implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Production `PolicyLoader` that reads config files from disk with
+ * mtime-based caching.
+ */
+export class FilePolicyLoader implements PolicyLoader {
+  private readonly globalConfigPath: string;
+  private readonly agentsDir: string;
+  private readonly projectGlobalConfigPath: string | null;
+  private readonly projectAgentsDir: string | null;
+  private readonly globalMcpConfigPath: string;
+  private readonly configuredMcpServerNamesOverride: readonly string[] | null;
+
+  private globalConfigCache: FileCacheEntry<ScopeConfig> | null = null;
+  private projectGlobalConfigCache: FileCacheEntry<ScopeConfig> | null = null;
+  private readonly agentConfigCache = new Map<
+    string,
+    FileCacheEntry<ScopeConfig>
+  >();
+  private readonly projectAgentConfigCache = new Map<
+    string,
+    FileCacheEntry<ScopeConfig>
+  >();
+  private configuredMcpServerNamesCache: FileCacheEntry<
+    readonly string[]
+  > | null = null;
+  private accumulatedConfigIssues: string[] = [];
+
+  constructor(options: PolicyLoaderOptions = {}) {
+    this.globalConfigPath =
+      options.globalConfigPath || defaultGlobalConfigPath();
+    this.agentsDir = options.agentsDir || defaultAgentsDir();
+    this.projectGlobalConfigPath = options.projectGlobalConfigPath || null;
+    this.projectAgentsDir = options.projectAgentsDir || null;
+    this.globalMcpConfigPath =
+      options.globalMcpConfigPath || defaultGlobalMcpConfigPath();
+    this.configuredMcpServerNamesOverride = options.mcpServerNames
+      ? [
+          ...new Set(
+            options.mcpServerNames
+              .map((name) => name.trim())
+              .filter((name) => name.length > 0),
+          ),
+        ]
+      : null;
+  }
+
+  // ── Config issue accumulation ────────────────────────────────────────
+
+  private accumulateConfigIssues(issues: string[]): void {
+    for (const issue of issues) {
+      if (!this.accumulatedConfigIssues.includes(issue)) {
+        this.accumulatedConfigIssues.push(issue);
+      }
+    }
+  }
+
+  getConfigIssues(): string[] {
+    return [...this.accumulatedConfigIssues];
+  }
+
+  // ── Scope loaders ────────────────────────────────────────────────────
+
+  loadGlobalConfig(): ScopeConfig {
+    const stamp = getFileStamp(this.globalConfigPath);
+    if (this.globalConfigCache?.stamp === stamp) {
+      return this.globalConfigCache.value;
+    }
+
+    const { config, issues } = loadUnifiedConfig(this.globalConfigPath);
+    this.accumulateConfigIssues(issues);
+
+    const value: ScopeConfig = {
+      permission: config.permission,
+    };
+
+    this.globalConfigCache = { stamp, value };
+    return value;
+  }
+
+  loadProjectConfig(): ScopeConfig {
+    if (!this.projectGlobalConfigPath) {
+      return {};
+    }
+
+    const stamp = getFileStamp(this.projectGlobalConfigPath);
+    if (this.projectGlobalConfigCache?.stamp === stamp) {
+      return this.projectGlobalConfigCache.value;
+    }
+
+    const { config, issues } = loadUnifiedConfig(this.projectGlobalConfigPath);
+    this.accumulateConfigIssues(issues);
+
+    const value: ScopeConfig = {
+      permission: config.permission,
+    };
+
+    this.projectGlobalConfigCache = { stamp, value };
+    return value;
+  }
+
+  private loadScopeConfigFrom(
+    dir: string | null,
+    cache: Map<string, FileCacheEntry<ScopeConfig>>,
+    agentName?: string,
+  ): ScopeConfig {
+    if (!dir || !agentName) {
+      return {};
+    }
+
+    const filePath = join(dir, `${agentName}.md`);
+    const stamp = getFileStamp(filePath);
+    const cached = cache.get(agentName);
+    if (cached?.stamp === stamp) {
+      return cached.value;
+    }
+
+    let value: ScopeConfig;
+    try {
+      const markdown = readFileSync(filePath, "utf-8");
+      const frontmatter = extractFrontmatter(markdown);
+      if (!frontmatter) {
+        value = {};
+      } else {
+        const parsed = parseSimpleYamlMap(frontmatter);
+        const { config, issues } = normalizeUnifiedConfig(parsed);
+        this.accumulateConfigIssues(issues);
+        value = { permission: config.permission };
+      }
+    } catch {
+      value = {};
+    }
+
+    cache.set(agentName, { stamp, value });
+    return value;
+  }
+
+  loadAgentConfig(agentName?: string): ScopeConfig {
+    return this.loadScopeConfigFrom(
+      this.agentsDir,
+      this.agentConfigCache,
+      agentName,
+    );
+  }
+
+  loadProjectAgentConfig(agentName?: string): ScopeConfig {
+    return this.loadScopeConfigFrom(
+      this.projectAgentsDir,
+      this.projectAgentConfigCache,
+      agentName,
+    );
+  }
+
+  // ── MCP server names ─────────────────────────────────────────────────
+
+  getConfiguredMcpServerNames(): readonly string[] {
+    if (this.configuredMcpServerNamesOverride) {
+      return this.configuredMcpServerNamesOverride;
+    }
+
+    const paths = [this.globalMcpConfigPath];
+    const stamp = paths
+      .map((path) => `${path}:${getFileStamp(path)}`)
+      .join("|");
+    if (this.configuredMcpServerNamesCache?.stamp === stamp) {
+      return this.configuredMcpServerNamesCache.value;
+    }
+
+    const value = getConfiguredMcpServerNamesFromPaths(paths);
+    this.configuredMcpServerNamesCache = { stamp, value };
+    return value;
+  }
+
+  // ── Cache stamp ───────────────────────────────────────────────────────
+
+  getCacheStamp(agentName?: string): string {
+    const agentStamp = agentName
+      ? getFileStamp(join(this.agentsDir, `${agentName}.md`))
+      : "missing";
+    const projectStamp = this.projectGlobalConfigPath
+      ? getFileStamp(this.projectGlobalConfigPath)
+      : "none";
+    const projectAgentStamp =
+      this.projectAgentsDir && agentName
+        ? getFileStamp(join(this.projectAgentsDir, `${agentName}.md`))
+        : "none";
+
+    return `${getFileStamp(this.globalConfigPath)}|${projectStamp}|${agentStamp}|${projectAgentStamp}`;
+  }
+
+  // ── Resolved paths ────────────────────────────────────────────────────
+
+  getResolvedPolicyPaths(): ResolvedPolicyPaths {
+    return {
+      globalConfigPath: this.globalConfigPath,
+      globalConfigExists: existsSync(this.globalConfigPath),
+      projectConfigPath: this.projectGlobalConfigPath,
+      projectConfigExists: this.projectGlobalConfigPath
+        ? existsSync(this.projectGlobalConfigPath)
+        : false,
+      agentsDir: this.agentsDir,
+      agentsDirExists: existsSync(this.agentsDir),
+      projectAgentsDir: this.projectAgentsDir,
+      projectAgentsDirExists: this.projectAgentsDir
+        ? existsSync(this.projectAgentsDir)
+        : false,
+    };
+  }
+}

package/tests/permission-manager-unified.test.ts

@@ -661,3 +661,322 @@ describe("checkPermission — rule origin provenance", () => {
     expect(result.origin).toBe("builtin");
   });
 });
+
+// ---------------------------------------------------------------------------
+// In-memory PolicyLoader stub tests — no filesystem required
+// ---------------------------------------------------------------------------
+
+import type { PolicyLoader } from "../src/permission-manager";
+import type { ResolvedPolicyPaths } from "../src/policy-loader";
+import type { ScopeConfig } from "../src/types";
+
+/**
+ * Minimal in-memory PolicyLoader for testing merge + evaluation logic
+ * without touching the filesystem.
+ */
+function createInMemoryPolicyLoader(
+  scopes: {
+    global?: ScopeConfig;
+    project?: ScopeConfig;
+    agent?: Record<string, ScopeConfig>;
+    projectAgent?: Record<string, ScopeConfig>;
+  } = {},
+  mcpServerNames: readonly string[] = [],
+): PolicyLoader {
+  const issues: string[] = [];
+  return {
+    loadGlobalConfig: () => scopes.global ?? {},
+    loadProjectConfig: () => scopes.project ?? {},
+    loadAgentConfig: (name?: string) => (name && scopes.agent?.[name]) || {},
+    loadProjectAgentConfig: (name?: string) =>
+      (name && scopes.projectAgent?.[name]) || {},
+    getConfiguredMcpServerNames: () => mcpServerNames,
+    getCacheStamp: () => "in-memory",
+    getConfigIssues: () => issues,
+    getResolvedPolicyPaths: (): ResolvedPolicyPaths => ({
+      globalConfigPath: "/in-memory/config.json",
+      globalConfigExists: true,
+      projectConfigPath: null,
+      projectConfigExists: false,
+      agentsDir: "/in-memory/agents",
+      agentsDirExists: false,
+      projectAgentsDir: null,
+      projectAgentsDirExists: false,
+    }),
+  };
+}
+
+/** Create a PermissionManager backed by an in-memory PolicyLoader. */
+function makeInMemoryManager(
+  scopes: Parameters<typeof createInMemoryPolicyLoader>[0] = {},
+  mcpServerNames: readonly string[] = [],
+): PermissionManager {
+  return new PermissionManager({
+    policyLoader: createInMemoryPolicyLoader(scopes, mcpServerNames),
+  });
+}
+
+describe("PermissionManager with in-memory PolicyLoader", () => {
+  describe("universal fallback", () => {
+    it("defaults to ask when no config is provided", () => {
+      const manager = makeInMemoryManager();
+      const result = manager.checkPermission("read", {});
+      expect(result.state).toBe("ask");
+      expect(result.origin).toBe("builtin");
+    });
+
+    it("respects permission['*'] = 'allow' from global config", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "allow" } },
+      });
+      const result = manager.checkPermission("read", {});
+      expect(result.state).toBe("allow");
+      expect(result.origin).toBe("global");
+    });
+
+    it("respects permission['*'] = 'deny' from global config", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "deny" } },
+      });
+      const result = manager.checkPermission("write", {});
+      expect(result.state).toBe("deny");
+    });
+  });
+
+  describe("surface routing", () => {
+    it("bash surface routes correctly", () => {
+      const manager = makeInMemoryManager({
+        global: {
+          permission: { "*": "ask", bash: { "git *": "allow" } },
+        },
+      });
+      const result = manager.checkPermission("bash", {
+        command: "git status",
+      });
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("bash");
+      expect(result.matchedPattern).toBe("git *");
+    });
+
+    it("tool surface routes correctly for built-in tools", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "deny", read: "allow" } },
+      });
+      const result = manager.checkPermission("read", {});
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("tool");
+    });
+
+    it("skill surface routes correctly", () => {
+      const manager = makeInMemoryManager({
+        global: {
+          permission: { "*": "ask", skill: { librarian: "allow" } },
+        },
+      });
+      const result = manager.checkPermission("skill", { name: "librarian" });
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("skill");
+    });
+
+    it("mcp surface routes correctly", () => {
+      const manager = makeInMemoryManager(
+        {
+          global: {
+            permission: { "*": "ask", mcp: { exa_search: "allow" } },
+          },
+        },
+        ["exa"],
+      );
+      const result = manager.checkPermission("mcp", {
+        tool: "exa:search",
+        server: "exa",
+      });
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("mcp");
+    });
+
+    it("external_directory surface routes correctly", () => {
+      const manager = makeInMemoryManager({
+        global: {
+          permission: {
+            "*": "ask",
+            external_directory: { "/trusted/*": "allow" },
+          },
+        },
+      });
+      const result = manager.checkPermission("external_directory", {
+        path: "/trusted/repo",
+      });
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("special");
+    });
+
+    it("extension tools use 'default' source when no config rule matches", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "ask" } },
+      });
+      const result = manager.checkPermission("my_custom_tool", {});
+      expect(result.state).toBe("ask");
+      expect(result.source).toBe("default");
+    });
+  });
+
+  describe("multi-scope merge", () => {
+    it("project overrides global", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { read: "ask" } },
+        project: { permission: { read: "allow" } },
+      });
+      const result = manager.checkPermission("read", {});
+      expect(result.state).toBe("allow");
+      expect(result.origin).toBe("project");
+    });
+
+    it("agent overrides project", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { read: "ask" } },
+        project: { permission: { read: "allow" } },
+        agent: { coder: { permission: { read: "deny" } } },
+      });
+      const result = manager.checkPermission("read", {}, "coder");
+      expect(result.state).toBe("deny");
+      expect(result.origin).toBe("agent");
+    });
+
+    it("project-agent overrides agent", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { read: "deny" } },
+        agent: { coder: { permission: { read: "deny" } } },
+        projectAgent: { coder: { permission: { read: "allow" } } },
+      });
+      const result = manager.checkPermission("read", {}, "coder");
+      expect(result.state).toBe("allow");
+      expect(result.origin).toBe("project-agent");
+    });
+
+    it("deep-shallow merge preserves patterns from different scopes", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { bash: { "git *": "allow" } } },
+        project: { permission: { bash: { "rm *": "deny" } } },
+      });
+      const gitResult = manager.checkPermission("bash", {
+        command: "git status",
+      });
+      expect(gitResult.state).toBe("allow");
+      expect(gitResult.origin).toBe("global");
+
+      const rmResult = manager.checkPermission("bash", {
+        command: "rm -rf /",
+      });
+      expect(rmResult.state).toBe("deny");
+      expect(rmResult.origin).toBe("project");
+    });
+
+    it("string replaces object in override scope", () => {
+      const manager = makeInMemoryManager({
+        global: {
+          permission: { bash: { "git *": "ask", "npm *": "ask" } },
+        },
+        project: { permission: { bash: "allow" } },
+      });
+      const result = manager.checkPermission("bash", { command: "anything" });
+      expect(result.state).toBe("allow");
+      expect(result.origin).toBe("project");
+    });
+  });
+
+  describe("session rule composition", () => {
+    it("session rule wins over config", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "deny" } },
+      });
+      const sessionRules: Ruleset = [sessionAllow("read", "*")];
+      const result = manager.checkPermission(
+        "read",
+        {},
+        undefined,
+        sessionRules,
+      );
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("session");
+    });
+
+    it("session rule does not bleed across surfaces", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "ask" } },
+      });
+      const sessionRules: Ruleset = [sessionAllow("bash", "git *")];
+      const bashResult = manager.checkPermission(
+        "bash",
+        { command: "git status" },
+        undefined,
+        sessionRules,
+      );
+      expect(bashResult.state).toBe("allow");
+
+      const readResult = manager.checkPermission(
+        "read",
+        {},
+        undefined,
+        sessionRules,
+      );
+      expect(readResult.state).toBe("ask");
+    });
+  });
+
+  describe("origin tracking", () => {
+    it("universal fallback from project carries origin 'project'", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "ask" } },
+        project: { permission: { "*": "allow" } },
+      });
+      const result = manager.checkPermission("read", {});
+      expect(result.state).toBe("allow");
+      expect(result.origin).toBe("project");
+    });
+
+    it("session origin is 'session'", () => {
+      const manager = makeInMemoryManager();
+      const sessionRules: Ruleset = [sessionAllow("read", "*")];
+      const result = manager.checkPermission(
+        "read",
+        {},
+        undefined,
+        sessionRules,
+      );
+      expect(result.origin).toBe("session");
+    });
+  });
+
+  describe("getToolPermission", () => {
+    it("returns tool-level state for built-in tools", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "deny", read: "allow" } },
+      });
+      expect(manager.getToolPermission("read")).toBe("allow");
+      expect(manager.getToolPermission("write")).toBe("deny");
+    });
+
+    it("returns tool-level state for bash surface", () => {
+      const manager = makeInMemoryManager({
+        global: { permission: { "*": "deny", bash: "allow" } },
+      });
+      expect(manager.getToolPermission("bash")).toBe("allow");
+    });
+  });
+
+  describe("getComposedConfigRules", () => {
+    it("returns only config-layer rules", () => {
+      const manager = makeInMemoryManager({
+        global: {
+          permission: { "*": "ask", bash: { "git *": "allow" } },
+        },
+      });
+      const rules = manager.getComposedConfigRules();
+      expect(rules.every((r) => r.layer === "config")).toBe(true);
+      expect(
+        rules.some((r) => r.surface === "bash" && r.pattern === "git *"),
+      ).toBe(true);
+    });
+  });
+});