工具权限控制

// src/permissions/roles.ts
export type UserRole = 'user' | 'support' | 'admin'
 
export const rolePermissions: Record<UserRole, {
  tools: string[]
  dataScope: 'self' | 'all'
}> = {
  user: {
    tools: ['query_orders', 'query_logistics', 'submit_refund'],
    dataScope: 'self'
  },
  support: {
    tools: [
      'query_orders', 'query_logistics', 'submit_refund',
      'view_user_info', 'manual_refund'
    ],
    dataScope: 'all'
  },
  admin: {
    tools: [
      'query_orders', 'query_logistics', 'submit_refund',
      'view_user_info', 'manual_refund',
      'delete_order', 'update_product', 'batch_operation'
    ],
    dataScope: 'all'
  }
}

// src/permissions/levels.ts
export type PermissionLevel = 'public' | 'authenticated' | 'restricted' | 'admin'

// src/tools/types.ts
import type { PermissionLevel } from '../permissions/levels'
import type { UserRole } from '../permissions/roles'
 
export interface ToolDefinition {
  name: string
  description: string
  inputSchema: Record<string, unknown>
  permission: {
    level: PermissionLevel
    // restricted 级别时，指定允许的角色列表
    allowedRoles?: UserRole[]
  }
}

// src/tools/order-tools.ts
export const queryOrdersTool: ToolDefinition = {
  name: 'query_orders',
  description: '查询订单列表。支持按状态、日期筛选。',
  inputSchema: { /* ... */ },
  permission: { level: 'authenticated' }  // 登录就能查
}
 
export const deleteOrderTool: ToolDefinition = {
  name: 'delete_order',
  description: '删除指定订单。此操作不可逆，仅管理员可使用。',
  inputSchema: { /* ... */ },
  permission: { level: 'admin' }  // 只有管理员能删
}
 
export const manualRefundTool: ToolDefinition = {
  name: 'manual_refund',
  description: '手动触发退款，将款项退回用户原支付账户。',
  inputSchema: { /* ... */ },
  permission: {
    level: 'restricted',
    allowedRoles: ['support', 'admin']  // 客服和管理员都能操作
  }
}

// src/middleware/auth.ts
import { createMiddleware } from 'hono/factory'
import { verify } from 'hono/jwt'
import type { UserRole } from '../permissions/roles'
 
export const authMiddleware = createMiddleware<{
  Bindings: { JWT_SECRET: string }
  Variables: { user: { id: string; role: UserRole } | null }
}>(async (c, next) => {
  const header = c.req.header('Authorization')
  if (!header?.startsWith('Bearer ')) {
    c.set('user', null)
    await next()
    return
  }
  try {
    const payload = await verify(header.slice(7), c.env.JWT_SECRET)
    c.set('user', { id: payload.sub as string, role: payload.role as UserRole })
  } catch {
    c.set('user', null)
  }
  await next()
})

// src/permissions/checker.ts
import type { ToolDefinition } from '../tools/types'
import type { UserRole } from './roles'
 
export interface PermissionResult {
  allowed: boolean
  reason?: string
}
 
export function checkPermission(
  user: { id: string; role: UserRole } | null,
  tool: ToolDefinition
): PermissionResult {
  const { level, allowedRoles } = tool.permission
 
  if (level === 'public') return { allowed: true }
 
  if (!user) {
    return { allowed: false, reason: '此工具需要登录才能使用，请先让用户登录。' }
  }
  if (level === 'authenticated') return { allowed: true }
 
  if (level === 'admin' && user.role !== 'admin') {
    return {
      allowed: false,
      reason: `此工具仅限管理员使用，当前用户角色为「${user.role}」，权限不足。`
    }
  }
 
  if (level === 'restricted' && !allowedRoles?.includes(user.role)) {
    return {
      allowed: false,
      reason: `此工具仅对以下角色开放：${allowedRoles?.join('、') ?? '无'}，当前角色为「${user.role}」。`
    }
  }
 
  return { allowed: true }
}

// src/tools/executor.ts
export async function executeTool(
  toolName: string,
  input: Record<string, unknown>,
  user: { id: string; role: string } | null
): Promise<{ success: boolean; result?: unknown; error?: string }> {
  const tool = toolRegistry.get(toolName)
  if (!tool) return { success: false, error: `未找到名为「${toolName}」的工具。` }
 
  // 权限检查——在实际执行之前
  const perm = checkPermission(user, tool)
  if (!perm.allowed) return { success: false, error: perm.reason }
 
  const handler = toolHandlers.get(toolName)
  if (!handler) return { success: false, error: `工具「${toolName}」尚未注册执行函数。` }
 
  try {
    const result = await handler(input, { userId: user?.id ?? null })
    return { success: true, result }
  } catch (err) {
    return { success: false, error: err instanceof Error ? err.message : '工具执行失败' }
  }
}

// src/tools/visibility.ts
import type { ToolDefinition } from './types'
import { checkPermission } from '../permissions/checker'
 
export function getVisibleTools(
  allTools: ToolDefinition[],
  user: { id: string; role: string } | null
): ToolDefinition[] {
  return allTools.filter((tool) => checkPermission(user, tool).allowed)
}
 
export function toAnthropicToolFormat(tools: ToolDefinition[]) {
  return tools.map((t) => ({
    name: t.name,
    description: t.description,
    input_schema: t.inputSchema
  }))
}

// src/routes/agent.ts
app.post('/api/agent/chat', authMiddleware, async (c) => {
  const user = c.get('user')
  const { message } = await c.req.json()
 
  // 根据权限过滤工具列表，LLM 不知道被过滤掉的工具存在
  const visible = getVisibleTools(allTools, user)
  const response = await callAnthropic(message, toAnthropicToolFormat(visible))
 
  if (response.toolUse) {
    const result = await executeTool(response.toolUse.name, response.toolUse.input, user)
    // 把结果返回给 LLM 继续对话
  }
  return c.json({ reply: response.text })
})

// 权限不通过时返回给 LLM 的 tool_result
return {
  success: false,
  error: '权限不足：delete_order 工具仅限管理员使用，当前用户角色为「user」。如需删除订单，请告知用户联系管理员。'
}

// 在 checkPermission 不通过时
console.warn(JSON.stringify({
  event: 'permission_denied',
  userId: user?.id ?? 'anonymous',
  tool: tool.name,
  requiredLevel: tool.permission.level,
  timestamp: new Date().toISOString()
}))

// src/middleware/tool-permission.ts
import { createMiddleware } from 'hono/factory'
import { checkPermission } from '../permissions/checker'
import type { ToolDefinition } from '../tools/types'
 
export const toolPermissionMiddleware = createMiddleware<{
  Variables: {
    user: { id: string; role: string } | null
    currentTool: ToolDefinition
  }
}>(async (c, next) => {
  const user = c.get('user')
  const tool = c.get('currentTool')
  if (!tool) { await next(); return }
 
  const result = checkPermission(user, tool)
  if (!result.allowed) {
    return c.json({ error: 'permission_denied', message: result.reason }, 403)
  }
  await next()
})

// src/routes/tools.ts
app.post('/api/tools/delete-order',
  async (c, next) => { c.set('currentTool', deleteOrderTool); await next() },
  toolPermissionMiddleware,
  async (c) => {
    // 走到这里说明权限已通过，直接写业务逻辑
    const body = await c.req.json()
    // ...
  }
)