@xortex/xcode 3.0.0

package/utils/permissions/permissionsLoader.ts

@@ -0,0 +1,296 @@
+import { readFileSync } from '../fileRead.js'
+import { getFsImplementation, safeResolvePath } from '../fsOperations.js'
+import { safeParseJSON } from '../json.js'
+import { logError } from '../log.js'
+import {
+  type EditableSettingSource,
+  getEnabledSettingSources,
+  type SettingSource,
+} from '../settings/constants.js'
+import {
+  getSettingsFilePathForSource,
+  getSettingsForSource,
+  updateSettingsForSource,
+} from '../settings/settings.js'
+import type { SettingsJson } from '../settings/types.js'
+import type {
+  PermissionBehavior,
+  PermissionRule,
+  PermissionRuleSource,
+  PermissionRuleValue,
+} from './PermissionRule.js'
+import {
+  permissionRuleValueFromString,
+  permissionRuleValueToString,
+} from './permissionRuleParser.js'
+
+/**
+ * Returns true if allowManagedPermissionRulesOnly is enabled in managed settings (policySettings).
+ * When enabled, only permission rules from managed settings are respected.
+ */
+export function shouldAllowManagedPermissionRulesOnly(): boolean {
+  return (
+    getSettingsForSource('policySettings')?.allowManagedPermissionRulesOnly ===
+    true
+  )
+}
+
+/**
+ * Returns true if "always allow" options should be shown in permission prompts.
+ * When allowManagedPermissionRulesOnly is enabled, these options are hidden.
+ */
+export function shouldShowAlwaysAllowOptions(): boolean {
+  return !shouldAllowManagedPermissionRulesOnly()
+}
+
+const SUPPORTED_RULE_BEHAVIORS = [
+  'allow',
+  'deny',
+  'ask',
+] as const satisfies PermissionBehavior[]
+
+/**
+ * Lenient version of getSettingsForSource that doesn't fail on ANY validation errors.
+ * Simply parses the JSON and returns it as-is without schema validation.
+ *
+ * Used when loading settings to append new rules (avoids losing existing rules
+ * due to validation failures in unrelated fields like hooks).
+ *
+ * FOR EDITING ONLY - do not use this for reading settings for execution.
+ */
+function getSettingsForSourceLenient_FOR_EDITING_ONLY_NOT_FOR_READING(
+  source: SettingSource,
+): SettingsJson | null {
+  const filePath = getSettingsFilePathForSource(source)
+  if (!filePath) {
+    return null
+  }
+
+  try {
+    const { resolvedPath } = safeResolvePath(getFsImplementation(), filePath)
+    const content = readFileSync(resolvedPath)
+    if (content.trim() === '') {
+      return {}
+    }
+
+    const data = safeParseJSON(content, false)
+    // Return raw parsed JSON without validation to preserve all existing settings
+    // This is safe because we're only using this for reading/appending, not for execution
+    return data && typeof data === 'object' ? (data as SettingsJson) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Converts permissions JSON to an array of PermissionRule objects
+ * @param data The parsed permissions data
+ * @param source The source of these rules
+ * @returns Array of PermissionRule objects
+ */
+function settingsJsonToRules(
+  data: SettingsJson | null,
+  source: PermissionRuleSource,
+): PermissionRule[] {
+  if (!data || !data.permissions) {
+    return []
+  }
+
+  const { permissions } = data
+  const rules: PermissionRule[] = []
+  for (const behavior of SUPPORTED_RULE_BEHAVIORS) {
+    const behaviorArray = permissions[behavior]
+    if (behaviorArray) {
+      for (const ruleString of behaviorArray) {
+        rules.push({
+          source,
+          ruleBehavior: behavior,
+          ruleValue: permissionRuleValueFromString(ruleString),
+        })
+      }
+    }
+  }
+  return rules
+}
+
+/**
+ * Loads all permission rules from all relevant sources (managed and project settings)
+ * @returns Array of all permission rules
+ */
+export function loadAllPermissionRulesFromDisk(): PermissionRule[] {
+  // If allowManagedPermissionRulesOnly is set, only use managed permission rules
+  if (shouldAllowManagedPermissionRulesOnly()) {
+    return getPermissionRulesForSource('policySettings')
+  }
+
+  // Otherwise, load from all enabled sources (backwards compatible)
+  const rules: PermissionRule[] = []
+
+  for (const source of getEnabledSettingSources()) {
+    rules.push(...getPermissionRulesForSource(source))
+  }
+  return rules
+}
+
+/**
+ * Loads permission rules from a specific source
+ * @param source The source to load from
+ * @returns Array of permission rules from that source
+ */
+export function getPermissionRulesForSource(
+  source: SettingSource,
+): PermissionRule[] {
+  const settingsData = getSettingsForSource(source)
+  return settingsJsonToRules(settingsData, source)
+}
+
+export type PermissionRuleFromEditableSettings = PermissionRule & {
+  source: EditableSettingSource
+}
+
+// Editable sources that can be modified (excludes policySettings and flagSettings)
+const EDITABLE_SOURCES: EditableSettingSource[] = [
+  'userSettings',
+  'projectSettings',
+  'localSettings',
+]
+
+/**
+ * Deletes a rule from the project permissions file
+ * @param rule The rule to delete
+ * @returns Promise resolving to a boolean indicating success
+ */
+export function deletePermissionRuleFromSettings(
+  rule: PermissionRuleFromEditableSettings,
+): boolean {
+  // Runtime check to ensure source is actually editable
+  if (!EDITABLE_SOURCES.includes(rule.source as EditableSettingSource)) {
+    return false
+  }
+
+  const ruleString = permissionRuleValueToString(rule.ruleValue)
+  const settingsData = getSettingsForSource(rule.source)
+
+  // If there's no settings data or permissions, nothing to do
+  if (!settingsData || !settingsData.permissions) {
+    return false
+  }
+
+  const behaviorArray = settingsData.permissions[rule.ruleBehavior]
+  if (!behaviorArray) {
+    return false
+  }
+
+  // Normalize raw settings entries via roundtrip parse→serialize so legacy
+  // names (e.g. "KillShell") match their canonical form ("TaskStop").
+  const normalizeEntry = (raw: string): string =>
+    permissionRuleValueToString(permissionRuleValueFromString(raw))
+
+  if (!behaviorArray.some(raw => normalizeEntry(raw) === ruleString)) {
+    return false
+  }
+
+  try {
+    // Keep a copy of the original permissions data to preserve unrecognized keys
+    const updatedSettingsData = {
+      ...settingsData,
+      permissions: {
+        ...settingsData.permissions,
+        [rule.ruleBehavior]: behaviorArray.filter(
+          raw => normalizeEntry(raw) !== ruleString,
+        ),
+      },
+    }
+
+    const { error } = updateSettingsForSource(rule.source, updatedSettingsData)
+    if (error) {
+      // Error already logged inside updateSettingsForSource
+      return false
+    }
+
+    return true
+  } catch (error) {
+    logError(error)
+    return false
+  }
+}
+
+function getEmptyPermissionSettingsJson(): SettingsJson {
+  return {
+    permissions: {},
+  }
+}
+
+/**
+ * Adds rules to the project permissions file
+ * @param ruleValues The rule values to add
+ * @returns Promise resolving to a boolean indicating success
+ */
+export function addPermissionRulesToSettings(
+  {
+    ruleValues,
+    ruleBehavior,
+  }: {
+    ruleValues: PermissionRuleValue[]
+    ruleBehavior: PermissionBehavior
+  },
+  source: EditableSettingSource,
+): boolean {
+  // When allowManagedPermissionRulesOnly is enabled, don't persist new permission rules
+  if (shouldAllowManagedPermissionRulesOnly()) {
+    return false
+  }
+
+  if (ruleValues.length < 1) {
+    // No rules to add
+    return true
+  }
+
+  const ruleStrings = ruleValues.map(permissionRuleValueToString)
+  // First try the normal settings loader which validates the schema
+  // If validation fails, fall back to lenient loading to preserve existing rules
+  // even if some fields (like hooks) have validation errors
+  const settingsData =
+    getSettingsForSource(source) ||
+    getSettingsForSourceLenient_FOR_EDITING_ONLY_NOT_FOR_READING(source) ||
+    getEmptyPermissionSettingsJson()
+
+  try {
+    // Ensure permissions object exists
+    const existingPermissions = settingsData.permissions || {}
+    const existingRules = existingPermissions[ruleBehavior] || []
+
+    // Filter out duplicates - normalize existing entries via roundtrip
+    // parse→serialize so legacy names match their canonical form.
+    const existingRulesSet = new Set(
+      existingRules.map(raw =>
+        permissionRuleValueToString(permissionRuleValueFromString(raw)),
+      ),
+    )
+    const newRules = ruleStrings.filter(rule => !existingRulesSet.has(rule))
+
+    // If no new rules to add, return success
+    if (newRules.length === 0) {
+      return true
+    }
+
+    // Keep a copy of the original settings data to preserve unrecognized keys
+    const updatedSettingsData = {
+      ...settingsData,
+      permissions: {
+        ...existingPermissions,
+        [ruleBehavior]: [...existingRules, ...newRules],
+      },
+    }
+    const result = updateSettingsForSource(source, updatedSettingsData)
+
+    if (result.error) {
+      throw result.error
+    }
+
+    return true
+  } catch (error) {
+    logError(error)
+    return false
+  }
+}

package/utils/permissions/shadowedRuleDetection.ts

@@ -0,0 +1,234 @@
+import type { ToolPermissionContext } from '../../Tool.js'
+import { BASH_TOOL_NAME } from '../../tools/BashTool/toolName.js'
+import type { PermissionRule, PermissionRuleSource } from './PermissionRule.js'
+import {
+  getAllowRules,
+  getAskRules,
+  getDenyRules,
+  permissionRuleSourceDisplayString,
+} from './permissions.js'
+
+/**
+ * Type of shadowing that makes a rule unreachable
+ */
+export type ShadowType = 'ask' | 'deny'
+
+/**
+ * Represents an unreachable permission rule with explanation
+ */
+export type UnreachableRule = {
+  rule: PermissionRule
+  reason: string
+  shadowedBy: PermissionRule
+  shadowType: ShadowType
+  fix: string
+}
+
+/**
+ * Options for detecting unreachable rules
+ */
+export type DetectUnreachableRulesOptions = {
+  /**
+   * Whether sandbox auto-allow is enabled for Bash commands.
+   * When true, tool-wide Bash ask rules from personal settings don't block
+   * specific Bash allow rules because sandboxed commands are auto-allowed.
+   */
+  sandboxAutoAllowEnabled: boolean
+}
+
+/**
+ * Result of checking if a rule is shadowed.
+ * Uses discriminated union for type safety.
+ */
+type ShadowResult =
+  | { shadowed: false }
+  | { shadowed: true; shadowedBy: PermissionRule; shadowType: ShadowType }
+
+/**
+ * Check if a permission rule source is shared (visible to other users).
+ * Shared settings include:
+ * - projectSettings: Committed to git, shared with team
+ * - policySettings: Enterprise-managed, pushed to all users
+ * - command: From slash command frontmatter, potentially shared
+ *
+ * Personal settings include:
+ * - userSettings: User's global ~/.claude settings
+ * - localSettings: Gitignored per-project settings
+ * - cliArg: Runtime CLI arguments
+ * - session: In-memory session rules
+ * - flagSettings: From --settings flag (runtime)
+ */
+export function isSharedSettingSource(source: PermissionRuleSource): boolean {
+  return (
+    source === 'projectSettings' ||
+    source === 'policySettings' ||
+    source === 'command'
+  )
+}
+
+/**
+ * Format a rule source for display in warning messages.
+ */
+function formatSource(source: PermissionRuleSource): string {
+  return permissionRuleSourceDisplayString(source)
+}
+
+/**
+ * Generate a fix suggestion based on the shadow type.
+ */
+function generateFixSuggestion(
+  shadowType: ShadowType,
+  shadowingRule: PermissionRule,
+  shadowedRule: PermissionRule,
+): string {
+  const shadowingSource = formatSource(shadowingRule.source)
+  const shadowedSource = formatSource(shadowedRule.source)
+  const toolName = shadowingRule.ruleValue.toolName
+
+  if (shadowType === 'deny') {
+    return `Remove the "${toolName}" deny rule from ${shadowingSource}, or remove the specific allow rule from ${shadowedSource}`
+  }
+  return `Remove the "${toolName}" ask rule from ${shadowingSource}, or remove the specific allow rule from ${shadowedSource}`
+}
+
+/**
+ * Check if a specific allow rule is shadowed (unreachable) by an ask rule.
+ *
+ * An allow rule is unreachable when:
+ * 1. There's a tool-wide ask rule (e.g., "Bash" in ask list)
+ * 2. And a specific allow rule (e.g., "Bash(ls:*)" in allow list)
+ *
+ * The ask rule takes precedence, making the specific allow rule unreachable
+ * because the user will always be prompted first.
+ *
+ * Exception: For Bash with sandbox auto-allow enabled, tool-wide ask rules
+ * from PERSONAL settings don't shadow specific allow rules because:
+ * - Sandboxed commands are auto-allowed regardless of ask rules
+ * - This only applies to personal settings (userSettings, localSettings, etc.)
+ * - Shared settings (projectSettings, policySettings) always warn because
+ *   other team members may not have sandbox enabled
+ */
+function isAllowRuleShadowedByAskRule(
+  allowRule: PermissionRule,
+  askRules: PermissionRule[],
+  options: DetectUnreachableRulesOptions,
+): ShadowResult {
+  const { toolName, ruleContent } = allowRule.ruleValue
+
+  // Only check allow rules that have specific content (e.g., "Bash(ls:*)")
+  // Tool-wide allow rules cannot be shadowed by ask rules
+  if (ruleContent === undefined) {
+    return { shadowed: false }
+  }
+
+  // Find any tool-wide ask rule for the same tool
+  const shadowingAskRule = askRules.find(
+    askRule =>
+      askRule.ruleValue.toolName === toolName &&
+      askRule.ruleValue.ruleContent === undefined,
+  )
+
+  if (!shadowingAskRule) {
+    return { shadowed: false }
+  }
+
+  // Special case: Bash with sandbox auto-allow from personal settings
+  // The sandbox exception is based on the ASK rule's source, not the allow rule's source.
+  // If the ask rule is from personal settings, the user's own sandbox will auto-allow.
+  // If the ask rule is from shared settings, other team members may not have sandbox enabled.
+  if (toolName === BASH_TOOL_NAME && options.sandboxAutoAllowEnabled) {
+    if (!isSharedSettingSource(shadowingAskRule.source)) {
+      return { shadowed: false }
+    }
+    // Fall through to mark as shadowed - shared settings should always warn
+  }
+
+  return { shadowed: true, shadowedBy: shadowingAskRule, shadowType: 'ask' }
+}
+
+/**
+ * Check if an allow rule is shadowed (completely blocked) by a deny rule.
+ *
+ * An allow rule is unreachable when:
+ * 1. There's a tool-wide deny rule (e.g., "Bash" in deny list)
+ * 2. And a specific allow rule (e.g., "Bash(ls:*)" in allow list)
+ *
+ * Deny rules are checked first in the permission evaluation order,
+ * so the allow rule will never be reached - the tool is always denied.
+ * This is more severe than ask-shadowing because the rule is truly blocked.
+ */
+function isAllowRuleShadowedByDenyRule(
+  allowRule: PermissionRule,
+  denyRules: PermissionRule[],
+): ShadowResult {
+  const { toolName, ruleContent } = allowRule.ruleValue
+
+  // Only check allow rules that have specific content (e.g., "Bash(ls:*)")
+  // Tool-wide allow rules conflict with tool-wide deny rules but are not "shadowed"
+  if (ruleContent === undefined) {
+    return { shadowed: false }
+  }
+
+  // Find any tool-wide deny rule for the same tool
+  const shadowingDenyRule = denyRules.find(
+    denyRule =>
+      denyRule.ruleValue.toolName === toolName &&
+      denyRule.ruleValue.ruleContent === undefined,
+  )
+
+  if (!shadowingDenyRule) {
+    return { shadowed: false }
+  }
+
+  return { shadowed: true, shadowedBy: shadowingDenyRule, shadowType: 'deny' }
+}
+
+/**
+ * Detect all unreachable permission rules in the given context.
+ *
+ * Currently detects:
+ * - Allow rules shadowed by tool-wide deny rules (more severe - completely blocked)
+ * - Allow rules shadowed by tool-wide ask rules (will always prompt)
+ */
+export function detectUnreachableRules(
+  context: ToolPermissionContext,
+  options: DetectUnreachableRulesOptions,
+): UnreachableRule[] {
+  const unreachable: UnreachableRule[] = []
+
+  const allowRules = getAllowRules(context)
+  const askRules = getAskRules(context)
+  const denyRules = getDenyRules(context)
+
+  // Check each allow rule for shadowing
+  for (const allowRule of allowRules) {
+    // Check deny shadowing first (more severe)
+    const denyResult = isAllowRuleShadowedByDenyRule(allowRule, denyRules)
+    if (denyResult.shadowed) {
+      const shadowSource = formatSource(denyResult.shadowedBy.source)
+      unreachable.push({
+        rule: allowRule,
+        reason: `Blocked by "${denyResult.shadowedBy.ruleValue.toolName}" deny rule (from ${shadowSource})`,
+        shadowedBy: denyResult.shadowedBy,
+        shadowType: 'deny',
+        fix: generateFixSuggestion('deny', denyResult.shadowedBy, allowRule),
+      })
+      continue // Don't also report ask-shadowing if deny-shadowed
+    }
+
+    // Check ask shadowing
+    const askResult = isAllowRuleShadowedByAskRule(allowRule, askRules, options)
+    if (askResult.shadowed) {
+      const shadowSource = formatSource(askResult.shadowedBy.source)
+      unreachable.push({
+        rule: allowRule,
+        reason: `Shadowed by "${askResult.shadowedBy.ruleValue.toolName}" ask rule (from ${shadowSource})`,
+        shadowedBy: askResult.shadowedBy,
+        shadowType: 'ask',
+        fix: generateFixSuggestion('ask', askResult.shadowedBy, allowRule),
+      })
+    }
+  }
+
+  return unreachable
+}