智能体多租户安全与治理规范 (Agent Governance & Multi-Tenant Security)

当大语言模型具备自主调用企业后端写操作的能力时，安全防线面临全新维度的挑战：

租户数据越权：恶意的提示词注入（Prompt Injection）诱导模型越过当前租户边界，调用其他租户的敏感情报；
非授权工具滥用：租户未付费购买某些高级业务模块（如风控或跨境支付），却被模型发现并调用了对应工具；
并发风暴与 DoS：智能体进入死循环推理，短时间内对单点端点发起成百上千次密集工具调用；
高危破坏性动作：模型自行决定执行大额转账、清空案件数据或撤销生效合同。

BitzOrcas.Modern 构建了一套纵深防御、默认失败闭合（Fail-Closed）的智能体治理架构，确保所有 AI 行为受到与人类操作同等、甚至更为严密的防护。

1. 租户级总闸门：`McpTenantAccessGate`

在任何 MCP JSON-RPC 请求抵达工具聚合器之前，McpTenantAccessRequirement 会在 ASP.NET Core 授权中间件阶段拦截请求：

using BitzOrcas.Application.Tenancy;
using Microsoft.AspNetCore.Authorization;

namespace BitzOrcas.Infrastructure.Mcp;

/// <summary>
/// 租户级 MCP 访问总闸授权处理器 (Fail-Closed)
/// </summary>
public sealed class McpTenantAccessAuthorizationHandler : AuthorizationHandler<McpTenantAccessRequirement>
{
    private readonly ITenantContext _tenantContext;
    private readonly ITenantFeatureEvaluator _featureEvaluator;

    public McpTenantAccessAuthorizationHandler(
        ITenantContext tenantContext,
        ITenantFeatureEvaluator featureEvaluator)
    {
        _tenantContext = tenantContext;
        _featureEvaluator = featureEvaluator;
    }

    protected override async Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        McpTenantAccessRequirement requirement)
    {
        // 1. 验证用户主体是否已经通过 JWT / 凭据合法认证
        if (context.User.Identity?.IsAuthenticated != true)
        {
            context.Fail();
            return;
        }

        // 2. 验证租户上下文是否存在且有效
        if (!_tenantContext.HasActiveTenant)
        {
            context.Fail();
            return;
        }

        // 3. 验证当前租户是否开通了 MCP 智能体访问 Feature 权益
        var isEntitled = await _featureEvaluator.IsFeatureEnabledAsync("mcp.access");
        if (!isEntitled)
        {
            context.Fail();
            return;
        }

        context.Succeed(requirement);
    }
}

未开通 mcp.access Feature 的租户，端点直接返回 403 Forbidden，不进入任何工具发现或执行逻辑。

2. 工具动态可见性过滤 (`McpToolListVisibilityFilter`)

大模型在交互之初会发起 tools/list 请求以获知有哪些可用工具。如果将全量工具暴露给模型，不仅消耗巨量 Token，还会暴露未授权的系统拓扑。

BitzOrcas 实现了按租户与权限动态修剪工具树的机制：

using BitzOrcas.Application.Authorization;
using BitzOrcas.Mcp.Abstractions;

namespace BitzOrcas.Infrastructure.Mcp;

/// <summary>
/// 基于租户已购 Feature 与调用者 RBAC 权限修剪工具列表
/// </summary>
public sealed class McpToolListVisibilityFilter
{
    private readonly IPermissionEvaluator _permissionEvaluator;

    public McpToolListVisibilityFilter(IPermissionEvaluator permissionEvaluator)
    {
        _permissionEvaluator = permissionEvaluator;
    }

    public async Task<IReadOnlyList<McpToolDefinition>> FilterVisibleToolsAsync(
        IReadOnlyList<McpToolDefinition> allTools,
        CancellationToken cancellationToken)
    {
        var visibleTools = new List<McpToolDefinition>(allTools.Count);

        foreach (var tool in allTools)
        {
            // 如果工具绑定了特定业务权限，校验当前调用者是否满足
            if (tool.RequiredPermission is not null)
            {
                var hasPermission = await _permissionEvaluator.HasPermissionAsync(tool.RequiredPermission, cancellationToken);
                if (!hasPermission)
                {
                    continue; // 无权限则对智能体完全隐形，不出现在 tools/list 响应中
                }
            }

            visibleTools.Add(tool);
        }

        return visibleTools;
    }
}

3. 全量调用审计追踪 (`McpToolInvocationAuditor`)

所有智能体触发的写操作必须具备完整且不可篡改的法律级审计链。

McpToolInvocationAuditor 记录如下核心事实：

调用会话标识：模型推理请求关联的 TraceId 与 Client Session Token；
入参指纹：对请求 payload 计算稳定的 SHA256 哈希，防止敏感 PII 明文污染审计日志；
性能开销：执行耗时毫秒级度量；
业务判定：成功执行或触发的领域异常编码（ErrorCode）。

using System.Diagnostics;
using System.Security.Cryptography;
using System.Text;
using BitzOrcas.Application.Tenancy;
using Microsoft.Extensions.Logging;

namespace BitzOrcas.Infrastructure.Mcp;

/// <summary>
/// MCP 工具调用独立审计执行器
/// </summary>
public sealed class McpToolInvocationAuditor
{
    private readonly ILogger<McpToolInvocationAuditor> _logger;
    private readonly ITenantContext _tenantContext;

    public McpToolInvocationAuditor(ILogger<McpToolInvocationAuditor> logger, ITenantContext tenantContext)
    {
        _logger = logger;
        _tenantContext = tenantContext;
    }

    public async Task RecordInvocationAsync(
        string toolName,
        string rawJsonPayload,
        bool isSuccess,
        long elapsedMilliseconds,
        string? failureReason)
    {
        var payloadHash = Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(rawJsonPayload)));

        _logger.LogInformation(
            "MCP Tool Invocation Audit: [Tenant: {TenantId}] [Tool: {ToolName}] [Success: {Success}] [Elapsed: {Elapsed}ms] [PayloadHash: {Hash}] [Error: {Reason}]",
            _tenantContext.TenantId,
            toolName,
            isSuccess,
            elapsedMilliseconds,
            payloadHash,
            failureReason ?? "None");

        await Task.CompletedTask;
    }
}

4. 人机协同复核机制 (Human-in-the-Loop)

对于标的额巨大、产生不可逆物理删除或触发重要法定义务的操作，框架禁止模型直接完成最终提交。

推荐的黄金模式为：两阶段审批绑定（Prepare & Confirm Pattern）：

第一阶段 (Prepare)：大模型调用 prepare_financial_payout 工具，生成待办工单与支付摘要预览，系统返回 PendingReview 状态及工单编号 PO-2026-0901；
第二阶段 (Review & Confirm)：
- 智能体向人类提问：“已为您准备好标的金额为 ¥1,200,000 的付款工单 PO-2026-0901，请问是否确认批准？”
- 人类用户通过系统 UI 或 MFA 步进认证确认后，由专员触发最终写操作，杜绝任何“幻觉扣费”。

决策依据：ADR 0503：签名商业运行时许可策略
两阶段授权：步进认证（Step-Up Authentication）与高危挑战
客户端指引：Cursor 与 Claude Desktop 接入指南