@gotgenes/pi-permission-system 3.11.0 → 4.0.0

package/src/permission-manager.ts

@@ -9,21 +9,23 @@ import {
   parseSimpleYamlMap,
   toRecord,
 } from "./common";
-import { loadUnifiedConfig, stripJsonComments } from "./config-loader";
+import {
+  loadUnifiedConfig,
+  normalizeUnifiedConfig,
+  stripJsonComments,
+} from "./config-loader";
 import { getGlobalConfigPath } from "./config-paths";
-import { mergeDefaults } from "./defaults";
-import { normalizeConfig } from "./normalize";
-import type { Ruleset } from "./rule";
+import { normalizeFlatConfig } from "./normalize";
+import type { Rule, Ruleset } from "./rule";
 import { evaluate } from "./rule";
 import {
   composeRuleset,
   synthesizeBaseline,
   synthesizeDefaults,
-  synthesizeOverrides,
 } from "./synthesize";
 import type {
+  FlatPermissionConfig,
   PermissionCheckResult,
-  PermissionDefaultPolicy,
   PermissionState,
   ScopeConfig,
 } from "./types";
@@ -48,71 +50,37 @@ const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "ls",
 ]);
 const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
-const DEFAULT_POLICY: PermissionDefaultPolicy = {
-  tools: "ask",
-  bash: "ask",
-  mcp: "ask",
-  skills: "ask",
-  special: "ask",
-};
-
-function normalizePolicy(value: unknown): PermissionDefaultPolicy {
-  const record = toRecord(value);
-  return {
-    tools: isPermissionState(record.tools)
-      ? record.tools
-      : DEFAULT_POLICY.tools,
-    bash: isPermissionState(record.bash) ? record.bash : DEFAULT_POLICY.bash,
-    mcp: isPermissionState(record.mcp) ? record.mcp : DEFAULT_POLICY.mcp,
-    skills: isPermissionState(record.skills)
-      ? record.skills
-      : DEFAULT_POLICY.skills,
-    special: isPermissionState(record.special)
-      ? record.special
-      : DEFAULT_POLICY.special,
-  };
-}
-
-function normalizePartialPolicy(
-  value: unknown,
-): Partial<PermissionDefaultPolicy> {
-  const record = toRecord(value);
-  const normalized: Partial<PermissionDefaultPolicy> = {};
-
-  if (isPermissionState(record.tools)) {
-    normalized.tools = record.tools;
-  }
-
-  if (isPermissionState(record.bash)) {
-    normalized.bash = record.bash;
-  }
-
-  if (isPermissionState(record.mcp)) {
-    normalized.mcp = record.mcp;
-  }
-
-  if (isPermissionState(record.skills)) {
-    normalized.skills = record.skills;
-  }
 
-  if (isPermissionState(record.special)) {
-    normalized.special = record.special;
-  }
-
-  return normalized;
-}
-
-function normalizePermissionRecord(
-  value: unknown,
-): Record<string, PermissionState> {
-  const record = toRecord(value);
-  const normalized: Record<string, PermissionState> = {};
-  for (const [key, state] of Object.entries(record)) {
-    if (isPermissionState(state)) {
-      normalized[key] = state;
+/** Universal fallback when permission["*"] is absent from all scopes. */
+const DEFAULT_UNIVERSAL_FALLBACK: PermissionState = "ask";
+
+/**
+ * Deep-shallow merge two flat permission configs.
+ * Both objects → shallow-merge the pattern maps.
+ * Otherwise → override replaces base.
+ */
+function mergeFlatPermissions(
+  base: FlatPermissionConfig,
+  override: FlatPermissionConfig,
+): FlatPermissionConfig {
+  const merged: FlatPermissionConfig = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const baseVal = merged[key];
+    if (
+      typeof baseVal === "object" &&
+      baseVal !== null &&
+      typeof value === "object" &&
+      value !== null
+    ) {
+      merged[key] = {
+        ...(baseVal as Record<string, PermissionState>),
+        ...(value as Record<string, PermissionState>),
+      };
+    } else {
+      merged[key] = value;
     }
   }
-  return normalized;
+  return merged;
 }
 
 function readConfiguredMcpServerNamesFromConfigPath(
@@ -148,208 +116,6 @@ function getConfiguredMcpServerNamesFromPaths(
   );
 }
 
-const DEPRECATED_SPECIAL_KEYS: ReadonlySet<string> = new Set([
-  "doom_loop",
-  "tool_call_limit",
-]);
-
-export interface NormalizeResult {
-  permissions: ScopeConfig;
-  configIssues: string[];
-}
-
-export function normalizeRawPermission(raw: unknown): NormalizeResult {
-  const record = toRecord(raw);
-  const configIssues: string[] = [];
-  const normalizedTools = normalizePermissionRecord(record.tools);
-
-  const normalized: ScopeConfig = {
-    defaultPolicy: normalizePartialPolicy(record.defaultPolicy),
-    tools: normalizedTools,
-    bash: normalizePermissionRecord(record.bash),
-    mcp: normalizePermissionRecord(record.mcp),
-    skills: normalizePermissionRecord(record.skills),
-    special: normalizePermissionRecord(record.special),
-  };
-
-  // Detect deprecated keys in the raw special sub-object before discarding.
-  const rawSpecial = toRecord(record.special);
-  for (const key of DEPRECATED_SPECIAL_KEYS) {
-    if (key in rawSpecial) {
-      configIssues.push(
-        `special.${key} is deprecated and ignored — remove it from your policy file.`,
-      );
-      // Ensure the key is stripped even if its value was a valid PermissionState.
-      if (normalized.special) {
-        delete normalized.special[key];
-      }
-    }
-  }
-
-  for (const [key, value] of Object.entries(record)) {
-    if (!isPermissionState(value)) {
-      continue;
-    }
-
-    if (BUILT_IN_TOOL_PERMISSION_NAMES.has(key)) {
-      normalized.tools = { ...(normalized.tools || {}), [key]: value };
-      continue;
-    }
-
-    if (SPECIAL_PERMISSION_KEYS.has(key)) {
-      normalized.special = { ...(normalized.special || {}), [key]: value };
-    }
-  }
-
-  return { permissions: normalized, configIssues };
-}
-
-function parseQualifiedMcpToolName(
-  value: string,
-): { server: string; tool: string } | null {
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return null;
-  }
-
-  const colonIndex = trimmed.indexOf(":");
-  if (colonIndex <= 0 || colonIndex >= trimmed.length - 1) {
-    return null;
-  }
-
-  const server = trimmed.slice(0, colonIndex).trim();
-  const tool = trimmed.slice(colonIndex + 1).trim();
-  if (!server || !tool) {
-    return null;
-  }
-
-  return { server, tool };
-}
-
-function addDerivedMcpServerTargets(
-  toolName: string,
-  configuredServerNames: readonly string[],
-  pushTarget: (value: string | null) => void,
-): void {
-  const trimmedToolName = toolName.trim();
-  if (!trimmedToolName) {
-    return;
-  }
-
-  for (const serverName of configuredServerNames) {
-    const trimmedServerName = serverName.trim();
-    if (!trimmedServerName) {
-      continue;
-    }
-
-    if (!trimmedToolName.endsWith(`_${trimmedServerName}`)) {
-      continue;
-    }
-
-    if (trimmedToolName.startsWith(`${trimmedServerName}_`)) {
-      continue;
-    }
-
-    pushTarget(`${trimmedServerName}_${trimmedToolName}`);
-    pushTarget(`${trimmedServerName}:${trimmedToolName}`);
-    pushTarget(trimmedServerName);
-  }
-}
-
-function pushMcpToolPermissionTargets(
-  rawReference: string,
-  serverHint: string | null,
-  configuredServerNames: readonly string[],
-  pushTarget: (value: string | null) => void,
-): void {
-  const qualified = parseQualifiedMcpToolName(rawReference);
-  const resolvedServer = serverHint ?? qualified?.server ?? null;
-  const resolvedTool = qualified?.tool ?? rawReference;
-
-  if (resolvedServer) {
-    pushTarget(`${resolvedServer}_${resolvedTool}`);
-    pushTarget(`${resolvedServer}:${resolvedTool}`);
-    pushTarget(resolvedServer);
-  } else {
-    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, pushTarget);
-  }
-
-  pushTarget(resolvedTool);
-  pushTarget(rawReference);
-}
-
-function createMcpPermissionTargets(
-  input: unknown,
-  configuredServerNames: readonly string[] = [],
-): string[] {
-  const record = toRecord(input);
-  const tool = getNonEmptyString(record.tool);
-  const server = getNonEmptyString(record.server);
-  const connect = getNonEmptyString(record.connect);
-  const describe = getNonEmptyString(record.describe);
-  const search = getNonEmptyString(record.search);
-
-  const targets: string[] = [];
-  const pushTarget = (value: string | null) => {
-    if (!value) {
-      return;
-    }
-    if (!targets.includes(value)) {
-      targets.push(value);
-    }
-  };
-
-  if (tool) {
-    pushMcpToolPermissionTargets(
-      tool,
-      server,
-      configuredServerNames,
-      pushTarget,
-    );
-    pushTarget("mcp_call");
-    return targets;
-  }
-
-  if (connect) {
-    pushTarget(`mcp_connect_${connect}`);
-    pushTarget(connect);
-    pushTarget("mcp_connect");
-    return targets;
-  }
-
-  if (describe) {
-    pushMcpToolPermissionTargets(
-      describe,
-      server,
-      configuredServerNames,
-      pushTarget,
-    );
-    pushTarget("mcp_describe");
-    return targets;
-  }
-
-  if (search) {
-    if (server) {
-      pushTarget(`mcp_server_${server}`);
-      pushTarget(server);
-    }
-
-    pushTarget(search);
-    pushTarget("mcp_search");
-    return targets;
-  }
-
-  if (server) {
-    pushTarget(`mcp_server_${server}`);
-    pushTarget(server);
-    pushTarget("mcp_list");
-    return targets;
-  }
-
-  pushTarget("mcp_status");
-  return targets;
-}
-
 export interface ResolvedPolicyPaths {
   globalConfigPath: string;
   globalConfigExists: boolean;
@@ -363,7 +129,7 @@ export interface ResolvedPolicyPaths {
 
 type ResolvedPermissions = {
   /**
-   * Fully composed ruleset: synthesized defaults → baseline → overrides → config.
+   * Fully composed ruleset: synthesized defaults → baseline → config.
    * Session rules are appended at call-time inside checkPermission().
    */
   composedRules: Ruleset;
@@ -460,12 +226,7 @@ export class PermissionManager {
     this.accumulateConfigIssues(issues);
 
     const value: ScopeConfig = {
-      defaultPolicy: normalizePolicy(config.defaultPolicy),
-      tools: config.tools || {},
-      bash: config.bash || {},
-      mcp: config.mcp || {},
-      skills: config.skills || {},
-      special: config.special || {},
+      permission: config.permission,
     };
 
     this.globalConfigCache = { stamp, value };
@@ -486,12 +247,7 @@ export class PermissionManager {
     this.accumulateConfigIssues(issues);
 
     const value: ScopeConfig = {
-      defaultPolicy: config.defaultPolicy,
-      tools: config.tools,
-      bash: config.bash,
-      mcp: config.mcp,
-      skills: config.skills,
-      special: config.special,
+      permission: config.permission,
     };
 
     this.projectGlobalConfigCache = { stamp, value };
@@ -522,9 +278,11 @@ export class PermissionManager {
         value = {};
       } else {
         const parsed = parseSimpleYamlMap(frontmatter);
-        const result = normalizeRawPermission(parsed.permission);
-        value = result.permissions;
-        this.accumulateConfigIssues(result.configIssues);
+        // Re-use the config-loader normalizer so the flat permission shape
+        // is validated the same way as on-disk config files.
+        const { config, issues } = normalizeUnifiedConfig(parsed);
+        this.accumulateConfigIssues(issues);
+        value = { permission: config.permission };
       }
     } catch {
       value = {};
@@ -595,48 +353,46 @@ export class PermissionManager {
     const agentConfig = this.loadScopeConfig(agentName);
     const projectAgentConfig = this.loadProjectScopeConfig(agentName);
 
-    // Tag config rules with layer "config" so checkPermission() can derive
-    // the result source and matchedPattern without positional arithmetic.
-    const tagConfig = (r: import("./rule").Rule) => ({
-      ...r,
-      layer: "config" as const,
-    });
-    const configRules: Ruleset = [
-      ...normalizeConfig(globalConfig).map(tagConfig),
-      ...normalizeConfig(projectConfig).map(tagConfig),
-      ...normalizeConfig(agentConfig).map(tagConfig),
-      ...normalizeConfig(projectAgentConfig).map(tagConfig),
-    ];
-
-    // Merge defaultPolicy across scopes (shallow spread, same precedence).
-    const defaults = mergeDefaults(
-      globalConfig.defaultPolicy,
-      projectConfig.defaultPolicy,
-      agentConfig.defaultPolicy,
-      projectAgentConfig.defaultPolicy,
+    // Merge permission objects across scopes (lowest → highest precedence).
+    let mergedPermission: FlatPermissionConfig = {};
+    for (const scope of [
+      globalConfig,
+      projectConfig,
+      agentConfig,
+      projectAgentConfig,
+    ]) {
+      if (scope.permission) {
+        mergedPermission = mergeFlatPermissions(
+          mergedPermission,
+          scope.permission,
+        );
+      }
+    }
+
+    // Extract the universal fallback from permission["*"].
+    // The "*" key feeds synthesizeDefaults() only — it is NOT included as a
+    // config rule so that extension tools fall through to source:"default".
+    const universalFallback = isPermissionState(mergedPermission["*"])
+      ? (mergedPermission["*"] as PermissionState)
+      : DEFAULT_UNIVERSAL_FALLBACK;
+
+    // Build config rules from everything except the universal "*" key.
+    const permissionWithoutUniversal: FlatPermissionConfig = Object.fromEntries(
+      Object.entries(mergedPermission).filter(([k]) => k !== "*"),
     );
 
-    // tools.bash / tools.mcp overrides: per-scope, lowest-priority first so
-    // that later scopes win via last-match-wins in synthesizeOverrides.
-    const overrideScopes = [
-      { bash: globalConfig.tools?.bash, mcp: globalConfig.tools?.mcp },
-      { bash: projectConfig.tools?.bash, mcp: projectConfig.tools?.mcp },
-      { bash: agentConfig.tools?.bash, mcp: agentConfig.tools?.mcp },
-      {
-        bash: projectAgentConfig.tools?.bash,
-        mcp: projectAgentConfig.tools?.mcp,
-      },
-    ];
+    // Normalize to config rules, tagged with "config" layer.
+    const configRules: Ruleset = normalizeFlatConfig(
+      permissionWithoutUniversal,
+    ).map((r): Rule => ({ ...r, layer: "config" }));
 
     const composedRules = composeRuleset(
-      synthesizeDefaults(defaults),
+      synthesizeDefaults(universalFallback),
       synthesizeBaseline(configRules),
-      synthesizeOverrides(overrideScopes),
       configRules,
     );
 
     const value: ResolvedPermissions = { composedRules };
-
     this.resolvedPermissionsCache.set(cacheKey, { stamp, value });
     return value;
   }
@@ -660,31 +416,20 @@ export class PermissionManager {
   }
 
   /**
-   * Get the tool-level permission state for a tool, without considering command-level rules.
-   * This is used for tool injection decisions where we need to know if a tool is allowed/denied
-   * at the tool level before checking specific command permissions.
-   *
-   * With tool-name-as-surface normalization, tools.bash becomes a bash catch-all
-   * { surface: "bash", pattern: "*", action } so getToolPermission("bash")
-   * naturally picks it up via evaluate("bash", "*", rules).
-   *
-   * @param toolName - The name of the tool (for example "bash", "read", or a third-party tool name)
-   * @param agentName - Optional agent name to check agent-specific permissions
-   * @returns The permission state for the tool at the tool level
+   * Get the tool-level permission state for a tool, without considering
+   * command-level rules. Used for tool injection decisions.
    */
   getToolPermission(toolName: string, agentName?: string): PermissionState {
     const { composedRules } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
-    // Special surfaces: evaluate via the "special" surface used by config rules
-    // and the synthesized special default.
+    // Special surfaces (external_directory): evaluate directly by surface name.
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      return evaluate("special", normalizedToolName, composedRules).action;
+      return evaluate(normalizedToolName, "*", composedRules).action;
     }
 
-    // For bash, mcp, skill: evaluate with "*" value against composedRules.
-    // The synthesized override/default rules are catch-alls (pattern "*") that
-    // respond correctly to a "*" lookup without matching specific patterns.
+    // Bash, MCP, skill: evaluate with "*" value — the per-surface catch-all
+    // (or universal default) handles this correctly.
     if (normalizedToolName === "bash") {
       return evaluate("bash", "*", composedRules).action;
     }
@@ -709,12 +454,11 @@ export class PermissionManager {
     const normalizedToolName = toolName.trim();
 
     // --- Special surfaces (external_directory) ---
-    // Config/default rules use surface "special"; session rules use surface
-    // "external_directory" with path patterns. Check each independently.
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      // Session check: match by specific normalized path.
       const record = toRecord(input);
       const pathValue = typeof record.path === "string" ? record.path : null;
+
+      // Session check: match by specific normalized path.
       if (pathValue && sessionRules && sessionRules.length > 0) {
         const sessionRule = evaluate(
           "external_directory",
@@ -730,8 +474,13 @@ export class PermissionManager {
           };
         }
       }
+
       // Config/default check.
-      const rule = evaluate("special", normalizedToolName, composedRules);
+      const rule = evaluate(
+        normalizedToolName,
+        pathValue ?? "*",
+        composedRules,
+      );
       return {
         toolName,
         state: rule.action,
@@ -778,10 +527,7 @@ export class PermissionManager {
       ];
       const fallbackTarget = mcpTargets[0] || "mcp";
 
-      // Try each candidate target. Stop on the first non-default match
-      // (config, override, or baseline rule). Default rules are catch-alls
-      // that would fire on every target — skip them so more-specific targets
-      // can be checked first.
+      // Try each candidate target. Stop on the first non-default match.
       for (const target of mcpTargets) {
         const rule = evaluate("mcp", target, composedRules);
         if (rule.layer !== "default") {
@@ -808,8 +554,6 @@ export class PermissionManager {
     // --- Tools (read, write, edit, grep, find, ls, extension tools) ---
     const rule = evaluate(normalizedToolName, "*", composedRules);
 
-    // Built-in tools always report source "tool" regardless of which layer
-    // supplied the decision (matches current behaviour).
     if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
       return {
         toolName,
@@ -818,8 +562,6 @@ export class PermissionManager {
       };
     }
 
-    // Extension tools: "default" layer → source "default"; any explicit rule
-    // (config or override) → source "tool".
     return {
       toolName,
       state: rule.action,
@@ -827,3 +569,157 @@ export class PermissionManager {
     };
   }
 }
+
+// ---------------------------------------------------------------------------
+// MCP target derivation helpers (unchanged)
+// ---------------------------------------------------------------------------
+
+function parseQualifiedMcpToolName(
+  value: string,
+): { server: string; tool: string } | null {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const colonIndex = trimmed.indexOf(":");
+  if (colonIndex <= 0 || colonIndex >= trimmed.length - 1) {
+    return null;
+  }
+
+  const server = trimmed.slice(0, colonIndex).trim();
+  const tool = trimmed.slice(colonIndex + 1).trim();
+  if (!server || !tool) {
+    return null;
+  }
+
+  return { server, tool };
+}
+
+function addDerivedMcpServerTargets(
+  toolName: string,
+  configuredServerNames: readonly string[],
+  pushTarget: (value: string | null) => void,
+): void {
+  const trimmedToolName = toolName.trim();
+  if (!trimmedToolName) {
+    return;
+  }
+
+  for (const serverName of configuredServerNames) {
+    const trimmedServerName = serverName.trim();
+    if (!trimmedServerName) {
+      continue;
+    }
+
+    if (!trimmedToolName.endsWith(`_${trimmedServerName}`)) {
+      continue;
+    }
+
+    if (trimmedToolName.startsWith(`${trimmedServerName}_`)) {
+      continue;
+    }
+
+    pushTarget(`${trimmedServerName}_${trimmedToolName}`);
+    pushTarget(`${trimmedServerName}:${trimmedToolName}`);
+    pushTarget(trimmedServerName);
+  }
+}
+
+function pushMcpToolPermissionTargets(
+  rawReference: string,
+  serverHint: string | null,
+  configuredServerNames: readonly string[],
+  pushTarget: (value: string | null) => void,
+): void {
+  const qualified = parseQualifiedMcpToolName(rawReference);
+  const resolvedServer = serverHint ?? qualified?.server ?? null;
+  const resolvedTool = qualified?.tool ?? rawReference;
+
+  if (resolvedServer) {
+    pushTarget(`${resolvedServer}_${resolvedTool}`);
+    pushTarget(`${resolvedServer}:${resolvedTool}`);
+    pushTarget(resolvedServer);
+  } else {
+    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, pushTarget);
+  }
+
+  pushTarget(resolvedTool);
+  pushTarget(rawReference);
+}
+
+function createMcpPermissionTargets(
+  input: unknown,
+  configuredServerNames: readonly string[] = [],
+): string[] {
+  const record = toRecord(input);
+  const tool = getNonEmptyString(record.tool);
+  const server = getNonEmptyString(record.server);
+  const connect = getNonEmptyString(record.connect);
+  const describe = getNonEmptyString(record.describe);
+  const search = getNonEmptyString(record.search);
+
+  const targets: string[] = [];
+  const pushTarget = (value: string | null) => {
+    if (!value) {
+      return;
+    }
+    if (!targets.includes(value)) {
+      targets.push(value);
+    }
+  };
+
+  if (tool) {
+    pushMcpToolPermissionTargets(
+      tool,
+      server,
+      configuredServerNames,
+      pushTarget,
+    );
+    pushTarget("mcp_call");
+    return targets;
+  }
+
+  if (connect) {
+    pushTarget(`mcp_connect_${connect}`);
+    pushTarget(connect);
+    pushTarget("mcp_connect");
+    return targets;
+  }
+
+  if (describe) {
+    pushMcpToolPermissionTargets(
+      describe,
+      server,
+      configuredServerNames,
+      pushTarget,
+    );
+    pushTarget("mcp_describe");
+    return targets;
+  }
+
+  if (search) {
+    if (server) {
+      pushTarget(`mcp_server_${server}`);
+      pushTarget(server);
+    }
+
+    pushTarget(search);
+    pushTarget("mcp_search");
+    return targets;
+  }
+
+  if (server) {
+    pushTarget(`mcp_server_${server}`);
+    pushTarget(server);
+    pushTarget("mcp_list");
+    return targets;
+  }
+
+  pushTarget("mcp_status");
+  return targets;
+}
+
+// Keep isPermissionState and toRecord available for convenience — they are
+// used directly in some handler files that import from permission-manager.
+export { isPermissionState, toRecord };