第 19 章权限系统与远程权限回灌AI 安全的最后一道防线

// types/permissions.ts:16-22
export const EXTERNAL_PERMISSION_MODES = [
  'acceptEdits',
  'bypassPermissions',
  'default',
  'dontAsk',
  'plan',
] as const

// types/permissions.ts:28-29
export type InternalPermissionMode = ExternalPermissionMode | 'auto' | 'bubble'
export type PermissionMode = InternalPermissionMode

// types/permissions.ts:33-36
export const INTERNAL_PERMISSION_MODES = [
  ...EXTERNAL_PERMISSION_MODES,
  ...(feature('TRANSCRIPT_CLASSIFIER') ? (['auto'] as const) : ([] as const)),
] as const satisfies readonly PermissionMode[]

// utils/permissions/getNextPermissionMode.ts:34-78
export function getNextPermissionMode(
  toolPermissionContext: ToolPermissionContext,
): PermissionMode {
  switch (toolPermissionContext.mode) {
    case 'default':
      // 内部用户跳过 acceptEdits 和 plan — auto 模式替代了它们
      if (process.env.USER_TYPE === 'ant') {
        if (toolPermissionContext.isBypassPermissionsModeAvailable) {
          return 'bypassPermissions'
        }
        if (canCycleToAuto(toolPermissionContext)) {
          return 'auto'
        }
        return 'default'
      }
      return 'acceptEdits'

    case 'acceptEdits':
      return 'plan'

    case 'plan':
      if (toolPermissionContext.isBypassPermissionsModeAvailable) {
        return 'bypassPermissions'
      }
      // ...
      return 'default'

    // ...
  }
}

// types/permissions.ts:75-79
export type PermissionRule = {
  source: PermissionRuleSource       // 规则来自哪里
  ruleBehavior: PermissionBehavior   // allow | deny | ask
  ruleValue: PermissionRuleValue     // 匹配哪个工具/操作
}

// types/permissions.ts:67-70
export type PermissionRuleValue = {
  toolName: string       // 工具名称，如 "Bash", "FileEdit", "mcp__server1"
  ruleContent?: string   // 可选的内容匹配，如 "npm install", "python:*"
}

// permissions.ts:109-114
const PERMISSION_RULE_SOURCES = [
  ...SETTING_SOURCES,  // userSettings, projectSettings, localSettings,
                       // flagSettings, policySettings（后覆盖前）
  'cliArg',            // 命令行参数 --allowedTools
  'command',           // 斜杠命令设置
  'session',           // 当前会话中用户的临时授权
] as const satisfies readonly PermissionRuleSource[]

{
  "permissions": {
    "allow": [
      "Bash(npm install:*)",
      "Bash(git status)",
      "FileEdit",
      "mcp__server1"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl:*)"
    ],
    "ask": [
      "Bash(npm publish:*)"
    ]
  }
}

// utils/permissions/permissionRuleParser.ts:93-133
export function permissionRuleValueFromString(
  ruleString: string,
): PermissionRuleValue {
  const openParenIndex = findFirstUnescapedChar(ruleString, '(')
  if (openParenIndex === -1) {
    return { toolName: normalizeLegacyToolName(ruleString) }
  }
  // ... 解析 "Bash(npm install)" => { toolName: 'Bash', ruleContent: 'npm install' }
  const toolName = ruleString.substring(0, openParenIndex)
  const rawContent = ruleString.substring(openParenIndex + 1, closeParenIndex)
  const ruleContent = unescapeRuleContent(rawContent)
  return { toolName: normalizeLegacyToolName(toolName), ruleContent }
}

// utils/permissions/permissionsLoader.ts:120-133
export function loadAllPermissionRulesFromDisk(): PermissionRule[] {
  // 企业管控模式：只使用 policySettings 中的规则
  if (shouldAllowManagedPermissionRulesOnly()) {
    return getPermissionRulesForSource('policySettings')
  }

  // 普通模式：从所有启用的源加载
  const rules: PermissionRule[] = []
  for (const source of getEnabledSettingSources()) {
    rules.push(...getPermissionRulesForSource(source))
  }
  return rules
}

// utils/permissions/shellRuleMatching.ts:25-37
export type ShellPermissionRule =
  | { type: 'exact'; command: string }      // 精确匹配: "git status"
  | { type: 'prefix'; prefix: string }      // 前缀匹配: "npm:*"（传统语法）
  | { type: 'wildcard'; pattern: string }   // 通配符匹配: "git *"

// utils/permissions/shellRuleMatching.ts:90-154
export function matchWildcardPattern(
  pattern: string, command: string, caseInsensitive = false,
): boolean {
  // 1. 处理 \* 和 \\ 转义序列
  // 2. 转义正则特殊字符
  // 3. 将 * 转换为 .*
  // 特殊优化：当模式以 ' *' 结尾且只有一个通配符时，
  // 使 trailing space-and-args 可选，让 'git *' 同时匹配 'git add' 和 'git'
  const unescapedStarCount = (processed.match(/\*/g) || []).length
  if (regexPattern.endsWith(' .*') && unescapedStarCount === 1) {
    regexPattern = regexPattern.slice(0, -3) + '( .*)?'
  }
  const regex = new RegExp(`^${regexPattern}$`, flags)
  return regex.test(command)
}

// types/permissions.ts:241-246
export type PermissionDecision =
  | PermissionAllowDecision   // behavior: 'allow' — 允许执行
  | PermissionAskDecision     // behavior: 'ask'   — 需要用户确认
  | PermissionDenyDecision    // behavior: 'deny'  — 直接拒绝

// types/permissions.ts:251-266
export type PermissionResult =
  | PermissionDecision
  | {
      behavior: 'passthrough'
      message: string
      // ...
    }

async function hasPermissionsToUseToolInner(
  tool, input, context,
): Promise<PermissionDecision> {
  let appState = context.getAppState()

  // === 阶段 1：规则检查（deny > ask > 工具内部 > safety）===

  // 1a. 整工具被 deny 规则封禁
  const denyRule = getDenyRuleForTool(appState.toolPermissionContext, tool)
  if (denyRule) {
    return { behavior: 'deny', /* ... */ }
  }

  // 1b. 整工具被 ask 规则标记
  const askRule = getAskRuleForTool(appState.toolPermissionContext, tool)
  if (askRule) {
    // 特殊处理：沙箱模式下的 Bash 可以跳过
    const canSandboxAutoAllow = tool.name === BASH_TOOL_NAME
      && SandboxManager.isSandboxingEnabled()
      && SandboxManager.isAutoAllowBashIfSandboxedEnabled()
      && shouldUseSandbox(input)
    if (!canSandboxAutoAllow) {
      return { behavior: 'ask', /* ... */ }
    }
  }

  // 1c. 委托工具实现检查（每个工具可以有自己的权限逻辑）
  let toolPermissionResult: PermissionResult = { behavior: 'passthrough', /* ... */ }
  try {
    const parsedInput = tool.inputSchema.parse(input)
    toolPermissionResult = await tool.checkPermissions(parsedInput, context)
  } catch (e) { /* ... */ }

  // 1d. 工具实现返回 deny
  if (toolPermissionResult?.behavior === 'deny') return toolPermissionResult

  // 1e. 工具需要用户交互（即使 bypass 模式也不跳过）
  if (tool.requiresUserInteraction?.() && toolPermissionResult?.behavior === 'ask') {
    return toolPermissionResult
  }

  // 1f. 内容级 ask 规则（如 Bash(npm publish:*)），bypass 模式也不跳过
  if (toolPermissionResult?.behavior === 'ask'
    && toolPermissionResult.decisionReason?.type === 'rule'
    && toolPermissionResult.decisionReason.rule.ruleBehavior === 'ask') {
    return toolPermissionResult
  }

  // 1g. Safety check — 写入 .git/、.claude/、.vscode/ 等危险路径
  // bypass 模式不跳过此步骤
  if (toolPermissionResult?.behavior === 'ask'
    && toolPermissionResult.decisionReason?.type === 'safetyCheck') {
    return toolPermissionResult
  }

  // === 阶段 2：模式检查 ===

  // 2a. bypassPermissions 模式 — 跳过剩余检查
  appState = context.getAppState()  // 重新获取最新状态！
  const shouldBypassPermissions =
    appState.toolPermissionContext.mode === 'bypassPermissions'
    || (appState.toolPermissionContext.mode === 'plan'
      && appState.toolPermissionContext.isBypassPermissionsModeAvailable)
  if (shouldBypassPermissions) {
    return { behavior: 'allow', /* ... */ }
  }

  // 2b. 整工具被 allow 规则覆盖
  const alwaysAllowedRule = toolAlwaysAllowedRule(appState.toolPermissionContext, tool)
  if (alwaysAllowedRule) {
    return { behavior: 'allow', /* ... */ }
  }

  // === 阶段 3：默认 → ask ===
  // passthrough 转换为 ask，让用户决定
  return toolPermissionResult.behavior === 'passthrough'
    ? { ...toolPermissionResult, behavior: 'ask' }
    : toolPermissionResult
}

// permissions.ts:473-956（简化版）
export const hasPermissionsToUseTool = async (tool, input, context, ...) => {
  const result = await hasPermissionsToUseToolInner(tool, input, context)

  // allow 时重置连续拒绝计数
  if (result.behavior === 'allow') { /* ... */ return result }

  // 对 ask 结果进行模式变换
  if (result.behavior === 'ask') {
    const mode = appState.toolPermissionContext.mode

    // dontAsk 模式：ask → deny（不弹对话框，直接拒绝）
    if (mode === 'dontAsk') {
      return { behavior: 'deny', message: DONT_ASK_REJECT_MESSAGE(tool.name) }
    }

    // auto 模式：ask → 调用 AI Classifier 判断
    if (mode === 'auto') {
      // ... 详见下一节
    }

    // headless/后台 agent：ask → 先尝试 Hook，否则 deny
    if (appState.toolPermissionContext.shouldAvoidPermissionPrompts) {
      const hookDecision = await runPermissionRequestHooksForHeadlessAgent(...)
      if (hookDecision) return hookDecision
      return { behavior: 'deny', message: AUTO_REJECT_MESSAGE(tool.name) }
    }
  }

  return result
}

// permissions.ts:600-686（简化版）

// 快速通道 1：acceptEdits 模拟
// 如果操作在 acceptEdits 模式下会被允许（如工作目录内的文件编辑），直接放行
if (tool.name !== AGENT_TOOL_NAME && tool.name !== REPL_TOOL_NAME) {
  const acceptEditsResult = await tool.checkPermissions(parsedInput, {
    ...context,
    getAppState: () => ({
      ...state,
      toolPermissionContext: { ...state.toolPermissionContext, mode: 'acceptEdits' },
    }),
  })
  if (acceptEditsResult.behavior === 'allow') {
    // 直接放行，不调用 Classifier
    return { behavior: 'allow', decisionReason: { type: 'mode', mode: 'auto' } }
  }
}

// 快速通道 2：安全工具白名单
if (classifierDecisionModule.isAutoModeAllowlistedTool(tool.name)) {
  return { behavior: 'allow', /* ... */ }
}

// 快速通道 3：不符合快速通道 → 调用 Classifier
const classifierResult = await classifyYoloAction(context.messages, action, ...)

// utils/permissions/classifierDecision.ts:56-80
const SAFE_YOLO_ALLOWLISTED_TOOLS = new Set([
  FILE_READ_TOOL_NAME,      // 读文件——只读操作
  GREP_TOOL_NAME,           // 搜索——只读
  GLOB_TOOL_NAME,           // 文件查找——只读
  TODO_WRITE_TOOL_NAME,     // TODO 管理——元数据
  TASK_CREATE_TOOL_NAME,    // 任务创建——元数据
  ASK_USER_QUESTION_TOOL_NAME,  // 问用户问题——UI 交互
  ENTER_PLAN_MODE_TOOL_NAME,    // 进入 Plan 模式——模式切换
  // ...
])

// utils/permissions/denialTracking.ts:1-45
export type DenialTrackingState = {
  consecutiveDenials: number
  totalDenials: number
}

export const DENIAL_LIMITS = {
  maxConsecutive: 3,    // 连续拒绝 3 次 → 回退到用户确认（CLI）或 abort（headless）
  maxTotal: 20,         // 总拒绝 20 次 → 回退到用户确认（CLI）或 abort（headless）
} as const

export function shouldFallbackToPrompting(state: DenialTrackingState): boolean {
  return (
    state.consecutiveDenials >= DENIAL_LIMITS.maxConsecutive ||
    state.totalDenials >= DENIAL_LIMITS.maxTotal
  )
}

export function recordSuccess(state: DenialTrackingState): DenialTrackingState {
  if (state.consecutiveDenials === 0) return state  // 无变化时返回同一引用（优化）
  return { ...state, consecutiveDenials: 0 }
}

// permissions.ts:845-876
if (classifierResult.unavailable) {
  if (getFeatureValue_CACHED_WITH_REFRESH(
    'tengu_iron_gate_closed', true, 30 * 60 * 1000,
  )) {
    // Fail closed：拒绝操作
    return { behavior: 'deny', message: buildClassifierUnavailableMessage(...) }
  }
  // Fail open：回退到正常权限处理（让用户确认）
  return result
}

// utils/permissions/pathValidation.ts:141-263（简化版）
export function isPathAllowed(
  resolvedPath, context, operationType, precomputedPathsToCheck?,
): PathCheckResult {
  // 1. Deny 规则优先（最高优先级）
  const denyRule = matchingRuleForInput(resolvedPath, context, permissionType, 'deny')
  if (denyRule) return { allowed: false, decisionReason: { type: 'rule', rule: denyRule } }

  // 2. 内部可编辑路径（plan 文件、scratchpad、agent memory）
  if (operationType !== 'read') {
    const internalEditResult = checkEditableInternalPath(resolvedPath, {})
    if (internalEditResult.behavior === 'allow') return { allowed: true, /* ... */ }
  }

  // 2.5. 写操作安全检查（Windows 路径、Claude 配置文件、危险文件）
  if (operationType !== 'read') {
    const safetyCheck = checkPathSafetyForAutoEdit(resolvedPath, ...)
    if (!safetyCheck.safe) return { allowed: false, /* ... */ }
  }

  // 3. 工作目录检查
  if (pathInAllowedWorkingPath(resolvedPath, context, ...)) {
    if (operationType === 'read' || context.mode === 'acceptEdits') {
      return { allowed: true }
    }
  }

  // 3.7. 沙箱写白名单（工作目录外的额外允许写入目录）
  if (operationType !== 'read' && !isInWorkingDir
    && isPathInSandboxWriteAllowlist(resolvedPath)) {
    return { allowed: true, /* ... */ }
  }

  // 4. Allow 规则
  const allowRule = matchingRuleForInput(resolvedPath, context, permissionType, 'allow')
  if (allowRule) return { allowed: true, /* ... */ }

  // 5. 默认拒绝
  return { allowed: false }
}

// utils/permissions/pathValidation.ts:373-463
export function validatePath(path, cwd, toolPermissionContext, operationType) {
  const cleanPath = expandTilde(path.replace(/^['"]|['"]$/g, ''))

  // SECURITY: 阻止 UNC 路径（可能泄漏凭证）
  if (containsVulnerableUncPath(cleanPath)) {
    return { allowed: false, reason: 'UNC network paths require manual approval' }
  }

  // SECURITY: 拒绝 ~user、~+、~- 等 tilde 变体
  // expandTilde 只处理 ~ 和 ~/，其他变体会导致验证与 shell 执行路径不一致
  if (cleanPath.startsWith('~')) {
    return { allowed: false, reason: 'Tilde expansion variants require manual approval' }
  }

  // SECURITY: 拒绝包含 shell 展开语法的路径
  // $VAR, ${VAR}, $(cmd), %VAR% 在验证时是字面量，但 shell 执行时会展开
  if (cleanPath.includes('$') || cleanPath.includes('%') || cleanPath.startsWith('=')) {
    return { allowed: false, reason: 'Shell expansion syntax requires manual approval' }
  }

  // SECURITY: 写操作不允许 glob 模式
  // 写工具使用字面路径，但验证只检查 glob 的基目录 → 可能绕过检查
  if (GLOB_PATTERN_REGEX.test(cleanPath) && (operationType === 'write' || 'create')) {
    return { allowed: false, reason: 'Glob patterns are not allowed in write operations' }
  }
  // ...
}

// utils/permissions/pathValidation.ts:331-367
export function isDangerousRemovalPath(resolvedPath: string): boolean {
  // 通配符删除: *, /path/*
  if (forwardSlashed === '*' || forwardSlashed.endsWith('/*')) return true
  // 根目录
  if (normalizedPath === '/') return true
  // Windows 驱动器根: C:\, D:\
  if (WINDOWS_DRIVE_ROOT_REGEX.test(normalizedPath)) return true
  // 家目录
  if (normalizedPath === normalizedHome) return true
  // 根目录的直接子节点: /usr, /tmp, /etc
  if (dirname(normalizedPath) === '/') return true
  // Windows 驱动器直接子节点: C:\Windows, C:\Users
  if (WINDOWS_DRIVE_CHILD_REGEX.test(normalizedPath)) return true
  return false
}

// utils/permissions/permissionSetup.ts:94-147
export function isDangerousBashPermission(
  toolName: string, ruleContent: string | undefined,
): boolean {
  if (toolName !== BASH_TOOL_NAME) return false

  // 工具级 allow（无内容）= 允许所有命令 → 危险！
  if (ruleContent === undefined || ruleContent === '' || ruleContent === '*') {
    return true
  }

  // 检查危险模式：python:*, node:*, bash:*, ssh:*, sudo:* 等
  for (const pattern of DANGEROUS_BASH_PATTERNS) {
    if (content === lowerPattern) return true       // 精确匹配
    if (content === `${lowerPattern}:*`) return true // 前缀语法
    if (content === `${lowerPattern}*`) return true  // 通配符
    if (content === `${lowerPattern} *`) return true // 空格通配
    if (content.startsWith(`${lowerPattern} -`) && content.endsWith('*')) return true
  }
  return false
}

// utils/permissions/dangerousPatterns.ts:18-42
export const CROSS_PLATFORM_CODE_EXEC = [
  'python', 'python3', 'python2',   // 脚本解释器
  'node', 'deno', 'tsx',
  'ruby', 'perl', 'php', 'lua',
  'npx', 'bunx',                     // 包运行器
  'npm run', 'yarn run', 'pnpm run', 'bun run',
  'bash', 'sh',                      // Shell
  'ssh',                             // 远程执行
] as const

export const DANGEROUS_BASH_PATTERNS: readonly string[] = [
  ...CROSS_PLATFORM_CODE_EXEC,
  'zsh', 'fish', 'eval', 'exec',
  'env', 'xargs', 'sudo',
  // 内部用户还包括：gh, curl, wget, git, kubectl, aws, gcloud 等
]

// permissions.ts:400-471
async function runPermissionRequestHooksForHeadlessAgent(
  tool, input, toolUseID, context, ...
): Promise<PermissionDecision | null> {
  // 尝试通过 PermissionRequest Hook 获取决策
  for await (const hookResult of executePermissionRequestHooks(
    tool.name, toolUseID, input, context, ...
  )) {
    if (hookResult.permissionRequestResult?.behavior === 'allow') {
      // Hook 允许 → 放行（并持久化权限更新）
      return { behavior: 'allow', /* ... */ }
    }
    if (hookResult.permissionRequestResult?.behavior === 'deny') {
      // Hook 拒绝 → 如果设置了 interrupt，还会中断整个 Agent
      if (decision.interrupt) {
        context.abortController.abort()
      }
      return { behavior: 'deny', /* ... */ }
    }
  }
  // 没有 Hook 提供决策 → 返回 null，调用者自动拒绝
  return null
}

bridgeCallbacks: feature("BRIDGE_MODE") ? appState.replBridgePermissionCallbacks : undefined,

if (!isResolved()) {
  await doSomething()   // ← 危险：这段窗口里，别人可能先 resolve 了
  resolve(answer)
}

// 简化语义示意：claim 是个原子的"先检查后置位"
let claimed = false
function claim(): boolean {
  if (claimed) return false
  claimed = true
  return true
}

// interactiveHandler.ts:204-231（节选示意）
async recheckPermission() {
  if (isResolved()) return
  const fresh = await hasPermissionsToUseTool(/* ... */)
  if (fresh.behavior === 'allow') {
    if (!claim()) return       // ← 关键：await 之后再抢一次
    bridgeCallbacks?.cancelRequest(bridgeRequestId)
    resolveOnce(ctx.buildAllow(/* ... */))
  }
}

// remote/remotePermissionBridge.ts:53-78（节选）
{
  isReadOnly: () => false,        // 一定走完整权限管线
  needsPermissions: () => true,   // 始终需要用户确认
  call: async () => ({ data: '' }) // 占位：本地不会真的执行
}