config-audit/scanners/lib/permission-rules.mjs

/**
 * Permission rule matching — shared by the DIS scanner (dead-allow detection)
 * and the CNF conflict-detector (cross-scope allow/deny conflicts).
 *
 * Claude Code permission rules are either bare (`Tool`) or param-qualified
 * (`Tool(param)`): `Bash`, `Bash(npm:*)`, `Agent(model:opus)`,
 * `WebFetch(domain:*)`. CC 2.1.178 made `Tool(param:value)` matching
 * meaningful and 2.1.172 added `domain:` rules, so rule identity must be
 * param-aware — `Agent(model:opus)` and `Agent(model:sonnet)` are DISTINCT,
 * not "the same tool".
 *
 * Two distinct predicates are exported because the scanners ask different
 * questions:
 *   - DIS asks "is this allow entry dead?" → does some deny fully COVER it
 *     (`dominates`). A bare allow survives a specific deny.
 *   - CNF asks "do these two cross-scope rules conflict?" → do their match
 *     sets INTERSECT (`rulesIntersect`). A bare allow conflicts with a
 *     specific deny, because the denied case is a real contradiction.
 *
 * Zero external dependencies.
 */

/**
 * Split a permission entry into its bare tool name and optional param.
 *   `Bash`        → { tool: 'Bash', param: null }
 *   `Bash(npm:*)` → { tool: 'Bash', param: 'npm:*' }
 * @param {string} entry
 * @returns {{ tool: string|null, param: string|null }}
 */
export function parseRule(entry) {
  if (typeof entry !== 'string') return { tool: null, param: null };
  const idx = entry.indexOf('(');
  if (idx === -1) return { tool: entry.trim() || null, param: null };
  const tool = entry.slice(0, idx).trim();
  let param = entry.slice(idx + 1).trim();
  if (param.endsWith(')')) param = param.slice(0, -1).trim();
  return { tool: tool || null, param };
}

/**
 * Glob match a permission param against a concrete value. `*` matches any run
 * of characters; everything else is literal. Anchored (full-string) match.
 * @param {string} pattern
 * @param {string} value
 * @returns {boolean}
 */
export function paramMatches(pattern, value) {
  if (typeof pattern !== 'string' || typeof value !== 'string') return false;
  if (pattern === value) return true;
  const rx = '^' + pattern
    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
    .replace(/\\\*/g, '.*') + '$';
  return new RegExp(rx).test(value);
}

/**
 * Does the deny entry fully cover the allow entry, making the allow dead config?
 * Used by DIS. Bare deny — and the equivalent `Tool(*)` deny-all glob — covers
 * everything (including a bare allow); a specific deny only covers the matching
 * (or wildcard-subsumed) param and does NOT kill a bare allow.
 *
 * CC: "`Bash(*)` is equivalent to `Bash` ... As a deny rule, both forms remove
 * the tool from Claude's context." (code.claude.com/docs/en/permissions)
 * @param {string} denyEntry
 * @param {string} allowEntry
 * @returns {boolean}
 */
export function dominates(denyEntry, allowEntry) {
  const d = parseRule(denyEntry);
  const a = parseRule(allowEntry);
  if (!d.tool || !a.tool || d.tool !== a.tool) return false;
  if (d.param === null || d.param === '*') return true; // bare / Tool(*) deny covers all params
  if (a.param === null) return false;  // specific deny does not kill a bare allow
  if (d.param === a.param) return true;
  return paramMatches(d.param, a.param); // wildcard deny covers a matching literal allow
}

/**
 * Do two permission rules' match sets intersect (genuine cross-scope conflict)?
 * Used by CNF. A bare rule intersects any same-tool rule; param rules intersect
 * when equal or when either wildcard-matches the other.
 * @param {string} ruleA
 * @param {string} ruleB
 * @returns {boolean}
 */
export function rulesIntersect(ruleA, ruleB) {
  const a = parseRule(ruleA);
  const b = parseRule(ruleB);
  if (!a.tool || !b.tool || a.tool !== b.tool) return false;
  if (a.param === null || b.param === null) return true; // bare ∩ anything (same tool)
  if (a.param === b.param) return true;
  return paramMatches(a.param, b.param) || paramMatches(b.param, a.param);
}

/**
 * Is this `permissions.allow` entry an UNANCHORED tool-name glob that Claude
 * Code silently skips? CC accepts tool-name globs in an ALLOW rule only after a
 * literal `mcp__<server>__` prefix (the server segment must be glob-free).
 * Unanchored globs like `*`, `B*`, or `mcp__*` are skipped with a warning and
 * auto-approve nothing — dead config the author believes is granting access.
 *
 * Tool-name globs apply to the bare-name form only (no `(...)` specifier); a
 * glob INSIDE a specifier such as `Bash(npm run *)` is normal and valid.
 *
 * CC: "An unanchored allow glob such as `"*"`, `"B*"`, or `"mcp__*"` is skipped
 * with a warning and does not auto-approve anything."
 * (code.claude.com/docs/en/permissions — "Tool name wildcards")
 *
 * NOTE: deny/ask rules DO accept tool-name globs, so this predicate is for the
 * allow list only.
 * @param {string} entry
 * @returns {boolean}
 */
export function isIneffectiveAllowGlob(entry) {
  if (typeof entry !== 'string') return false;
  if (entry.includes('(')) return false; // specifier form — glob lives inside the param
  if (!entry.includes('*')) return false; // no glob — a normal match-all-tool allow
  if (entry.startsWith('mcp__')) {
    const rest = entry.slice(5); // after 'mcp__'
    const sep = rest.indexOf('__');
    // mcp__<server>__<rest> with a glob-free server segment is anchored & valid
    if (sep > 0 && !rest.slice(0, sep).includes('*')) return false;
  }
  return true;
}

/**
 * Tools whose canonicalizing input field collides with `Tool(param:value)`
 * matching. CC ignores a rule whose param key is the tool's own field and
 * emits a startup warning, because the rule would be bypassable (e.g. a
 * compound command defeats `Bash(command:rm *)`).
 *
 * CC: "Fields that a tool already matches with its own canonicalizing rules are
 * not matchable this way: `command` for Bash and PowerShell, `file_path` for
 * Read, Edit, and Write, `path` for Grep and Glob, `notebook_path` for
 * NotebookEdit, and `url` for WebFetch."
 * (code.claude.com/docs/en/permissions — "Match by input parameter")
 */
const FORBIDDEN_PARAMS = Object.freeze({
  Bash: 'command',
  PowerShell: 'command',
  Read: 'file_path',
  Edit: 'file_path',
  Write: 'file_path',
  Grep: 'path',
  Glob: 'path',
  NotebookEdit: 'notebook_path',
  WebFetch: 'url',
});

/** Correct specifier syntax to suggest in place of the forbidden param form. */
const FORBIDDEN_PARAM_HINT = Object.freeze({
  Bash: 'Bash(rm *)',
  PowerShell: 'PowerShell(Remove-Item *)',
  Read: 'Read(./path)',
  Edit: 'Edit(/src/**)',
  Write: 'Write(/src/**)',
  Grep: 'a Read rule (covers Grep)',
  Glob: 'a Read rule (covers Glob)',
  NotebookEdit: 'Edit(/notebooks/**)',
  WebFetch: 'WebFetch(domain:host)',
});

/**
 * Is this entry a `Tool(param:value)` rule whose param KEY is the tool's own
 * canonicalizing field? CC silently ignores these (any list) and emits a
 * startup warning. Returns `{ tool, key, hint }` or `null`.
 *
 * Only the `param:value` form (a colon present) is forbidden — `Bash(command)`
 * is a literal command-prefix match and stays valid. The key must equal the
 * tool's forbidden field, so `Bash(npm:*)`, `WebFetch(domain:x)`, and
 * `Agent(model:opus)` are NOT flagged.
 * @param {string} entry
 * @returns {{ tool: string, key: string, hint: string }|null}
 */
export function forbiddenParamRule(entry) {
  const { tool, param } = parseRule(entry);
  if (!tool || param === null) return null;
  const forbidden = FORBIDDEN_PARAMS[tool];
  if (!forbidden) return null;
  const colon = param.indexOf(':');
  if (colon === -1) return null; // no `param:value` — literal specifier, valid
  const key = param.slice(0, colon).trim();
  if (key !== forbidden) return null;
  return { tool, key, hint: FORBIDDEN_PARAM_HINT[tool] };
}