futu_mcp/

guard.rs

//! Scope 守卫 + 限额检查 + 审计日志
//!
//! 两种模式：
//! - **scope 模式**（`state.is_scope_mode()`）：必须持有 api-key，且 scope 匹配
//! - **legacy 模式**（没配 keys-file）：读工具全放行；写工具走 `enable_trading` /
//!   `allow_real_trading` 两级开关

#[cfg(test)]
use std::sync::Arc;

#[cfg(test)]
use chrono::Utc;
use futu_auth::Scope;
#[cfg(test)]
use futu_auth::{CheckCtx, KeyRecord};
use sha2::{Digest, Sha256};

#[cfg(test)]
use crate::state::ServerState;

/// 从 KeyStore 里按 id 取**当前**的 KeyRecord（对齐 SIGHUP 热重载 + machine binding）。
///
/// 如果 startup 时的 authed_key 已被 remove_key 删掉，返回 None → 调用方拒绝。
/// 否则返回存储中最新版的 KeyRecord（scope / limits / expires_at / machine binding 全新鲜）。
///
/// v1.4.106 codex 0608 F2 (P1): 用 `get_by_id_for_current_machine` 替代裸
/// `get_by_id`, 让 SIGHUP 收紧 `allowed_machines` 后能立即 reject (避免
/// silent-unrestricted, 反模式 D / pitfall #45).
#[cfg(test)]
fn current_authed_key(state: &ServerState) -> Option<Arc<KeyRecord>> {
    let startup = state.authed_key.as_ref()?;
    // legacy 模式下 key_store 是 empty()，get_by_id_for_current_machine 返回 None，
    // 但 legacy 模式在 guard 入口就分支出去了，不会走到这里
    state.key_store.get_by_id_for_current_machine(&startup.id)
}

/// 工具需要的 scope 类别
///
/// Read 类的 scope（qot:read / acc:read）是静态确定的；Trade 类在运行时根据
/// `env=real/simulate` 派发到 `Scope::TradeReal` / `Scope::TradeSimulate`。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ToolScope {
    /// 只读工具需要的 scope
    Read(Scope),
    /// 交易写工具（具体派发由 `require_trading` 根据 env 决定）
    Trade,
}

/// 工具名 → 所需 scope。
///
/// v1.4.110 Surface Spec v2: MCP scope 完全由 `EndpointSpec` 派生。
/// 新加 `#[tool]` 时必须先声明 `surface_names.mcp_tool`，否则这里返回 None，
/// handler 会 fail-closed 地拒绝请求（"unknown MCP tool"），并由
/// `cross_surface_consistency` 的反向 invariant 在测试期拦住。
pub fn scope_for_tool(tool: &str) -> Option<ToolScope> {
    let spec = futu_surface_spec::lookup_endpoint_by_mcp_tool(tool)?;
    Some(match spec.runtime.scope {
        futu_auth::Scope::TradeReal | futu_auth::Scope::TradeSimulate => ToolScope::Trade,
        scope => ToolScope::Read(scope),
    })
}

/// 基于注册表的只读 scope 守卫;若工具未登记则 fail-closed 拒绝.
///
/// 仅对 `ToolScope::Read(_)` 生效;Trade 类工具仍然走 `require_trading()`.
///
/// v1.4.104 codex round 1 F2 (P1) 后, 生产路径已迁 `tools.rs::require_acc_read_with_acc_id`
/// (caller-specific via Bearer/api_key). 本 fn 只剩 unit test refs.
#[cfg(test)]
pub fn require_tool_scope(state: &ServerState, tool: &'static str) -> GuardOutcome {
    match scope_for_tool(tool) {
        Some(ToolScope::Read(s)) => require_scope(state, tool, s),
        Some(ToolScope::Trade) => {
            // 防御性分支：调用方错把 trade 工具丢到 require_tool_scope 里。
            audit(tool, None, "reject", "internal: trade tool misrouted");
            GuardOutcome::Reject(format!(
                "internal error: {tool} is a trade tool, must use require_trading"
            ))
        }
        None => {
            audit(tool, None, "reject", "unknown MCP tool");
            GuardOutcome::Reject(format!("unknown MCP tool {tool:?}"))
        }
    }
}

#[cfg(test)]
/// 守卫结果：Allow 或携带拒绝原因的 JSON
#[non_exhaustive]
pub enum GuardOutcome {
    /// 鉴权 / scope / 限额全过，handler 可以继续执行
    Allow,
    /// 拒绝放行，`String` 为可直接返给 MCP 客户端的 JSON error payload
    Reject(String),
}

#[cfg(test)]
impl GuardOutcome {
    /// 把 `Reject(msg)` 转成 `Some(msg)`;`Allow` 返 `None`. 供 handler
    /// 直接 `.into_err_json()?` 做早 return.
    ///
    /// v1.4.109 后仅保留在 `#[cfg(test)]` reference guard 中，作为旧
    /// guard 输出 shape 的漂移报警；production 鉴权走 `tool_auth`.
    pub fn into_err_json(self) -> Option<String> {
        match self {
            GuardOutcome::Allow => None,
            // MED-NEW-2（2nd review）：加 `status: error` 让 scope-reject error shape
            // 与 `tool_err` / `client_or_err` 对齐（所有 error JSON 都含 error + status）
            GuardOutcome::Reject(msg) => {
                Some(serde_json::json!({ "error": msg, "status": "error" }).to_string())
            }
        }
    }
}

/// 基础 scope 守卫(用于只读工具)
///
/// 返回 `GuardOutcome::Allow` 表示放行. legacy 模式下只读工具全放行.
///
/// v1.4.104 codex round 1 F2 (P1) 后只剩 unit test refs (regression guard).
#[cfg(test)]
pub fn require_scope(state: &ServerState, tool: &'static str, needed: Scope) -> GuardOutcome {
    if !state.is_scope_mode() {
        // legacy 行为：只读工具不检查（旧用户兼容）
        audit(tool, None, "allow", "legacy mode, no keys configured");
        return GuardOutcome::Allow;
    }

    if state.authed_key.is_none() {
        audit(tool, None, "reject", "no API key provided");
        return GuardOutcome::Reject(
            "API key required: set FUTU_MCP_API_KEY to a plaintext key listed in keys.json"
                .to_string(),
        );
    }

    // SIGHUP 热重载后用 id 重新 lookup，拿最新 scope/limits/expiry
    let Some(key) = current_authed_key(state) else {
        let id = state
            .authed_key
            .as_ref()
            .map(|k| k.id.clone())
            .unwrap_or_default();
        audit(
            tool,
            Some(&id),
            "reject",
            "key revoked (not in current keys.json)",
        );
        return GuardOutcome::Reject(format!(
            "API key {id:?} has been revoked (not in current keys.json)"
        ));
    };

    // 过期再查一次（防止启动后过期，或 SIGHUP 后 expires_at 被改小）
    if key.is_expired(Utc::now()) {
        audit(tool, Some(&key.id), "reject", "key expired");
        return GuardOutcome::Reject(format!(
            "API key {:?} has expired (expires_at={:?})",
            key.id, key.expires_at
        ));
    }

    if !key.scopes.contains(&needed) {
        audit(
            tool,
            Some(&key.id),
            "reject",
            &format!("missing scope {}", needed),
        );
        return GuardOutcome::Reject(format!(
            "API key {:?} missing required scope {:?}",
            key.id,
            needed.as_str()
        ));
    }

    audit(tool, Some(&key.id), "allow", "scope ok");
    GuardOutcome::Allow
}

/// 交易写守卫：scope + legacy 兼容 + （可选）限额检查 + （可选）per-call key 覆盖
///
/// `env`：`"real"` / `"simulate"`；`ctx` 为 Some 时跑限额检查（下单路径）。
///
/// `override_key` 为 Some 时，本次调用使用这个 key（`KeyStore::verify` 一次性
/// 拿最新 record）而不是 `state.authed_key`；典型用法：MCP 多租户，让 LLM 客户端
/// 每个 tool call 带自己的 key。验证失败 → reject，不回落。若为 None → 用启动时
/// 捕获的 `state.authed_key`（SIGHUP-aware fresh lookup）。
/// v1.4.104 阶段 7-4: 生产路径已委托 `tools.rs::require_trading` →
/// `futu_auth_pipeline::authenticate_request`. 本函数保留作:
///
/// 1. 21 个 unit test 的 reference 实现 (regression guard 防 pipeline 漂移)
/// 2. 历史文档 (legacy 2 级开关 + per-call override + scope/expiry/rate
///    具体逻辑可读)
///
/// 删除条件：`tool_auth` / auth-pipeline 的 integration coverage 能等价覆盖上述
/// reference 行为；删除前必须同步删掉依赖本函数的 regression tests。
#[cfg(test)]
pub fn require_trading(
    state: &ServerState,
    tool: &'static str,
    env: &str,
    ctx: Option<CheckCtx>,
    override_key: Option<&str>,
) -> GuardOutcome {
    let is_real = crate::handlers::trade_write::is_real_env(env);
    let needed_scope = if is_real {
        Scope::TradeReal
    } else {
        Scope::TradeSimulate
    };

    if !state.is_scope_mode() {
        // legacy：两级开关
        if !state.enable_trading {
            audit(tool, None, "reject", "legacy: --enable-trading off");
            return GuardOutcome::Reject(
                "trading tools are disabled. Start futu-mcp with --enable-trading to enable."
                    .to_string(),
            );
        }
        if is_real && !state.allow_real_trading {
            audit(
                tool,
                None,
                "reject",
                "legacy: real env but --allow-real-trading off",
            );
            return GuardOutcome::Reject(
                "real trading is not allowed. Use env=\"simulate\" or restart futu-mcp with --allow-real-trading."
                    .to_string(),
            );
        }
        // legacy 下 override_key 被忽略（没有 KeyStore 可 verify），
        // 但这种配置本身就是"信任所有调用方"，覆盖不覆盖不影响安全语义
        audit(tool, None, "allow", "legacy trading allowed");
        return GuardOutcome::Allow;
    }

    // scope 模式：先解析用哪把 key
    let key = if let Some(plaintext) = override_key.filter(|p| !p.is_empty()) {
        // per-call override：用传入的 plaintext 实时 verify，不走 startup 快照
        match state.key_store.verify(plaintext) {
            Some(rec) => rec,
            None => {
                audit(tool, None, "reject", "per-call api_key invalid");
                return GuardOutcome::Reject(
                    "per-call api_key is invalid (not in keys.json or expired/bound to wrong machine)"
                        .to_string(),
                );
            }
        }
    } else {
        if state.authed_key.is_none() {
            audit(tool, None, "reject", "no API key");
            return GuardOutcome::Reject(
                "API key required for trading tools (set FUTU_MCP_API_KEY, or pass api_key in the tool call)"
                    .to_string(),
            );
        }
        // 同样走 SIGHUP-aware 的 fresh lookup
        match current_authed_key(state) {
            Some(k) => k,
            None => {
                let id = state
                    .authed_key
                    .as_ref()
                    .map(|k| k.id.clone())
                    .unwrap_or_default();
                audit(tool, Some(&id), "reject", "key revoked");
                return GuardOutcome::Reject(format!("API key {id:?} has been revoked"));
            }
        }
    };

    if key.is_expired(Utc::now()) {
        audit(tool, Some(&key.id), "reject", "key expired");
        return GuardOutcome::Reject(format!("API key {:?} has expired", key.id));
    }

    if !key.scopes.contains(&needed_scope) {
        audit(
            tool,
            Some(&key.id),
            "reject",
            &format!("missing scope {}", needed_scope),
        );
        return GuardOutcome::Reject(format!(
            "API key {:?} missing scope {:?}",
            key.id,
            needed_scope.as_str()
        ));
    }

    // 限额检查（仅在提供了 ctx 时执行）
    // v1.4.36 Bug #1：Reject variant 拆成 Throughput / Whitelist / Value，
    // 用 `reason()` helper 统一获取消息。MCP 没有 HTTP status 概念，所有
    // reject 统一返 GuardOutcome::Reject（客户端显示原因字符串）。
    if let Some(ctx) = ctx {
        let outcome = state
            .counters
            .check_and_commit(&key.id, &key.limits(), &ctx, Utc::now());
        if outcome.is_allow() {
            audit(tool, Some(&key.id), "allow", "scope + limits ok");
        } else {
            let reason = outcome
                .reason()
                .unwrap_or_else(|| "limit check failed".to_string());
            audit(tool, Some(&key.id), "reject", &format!("limit: {reason}"));
            return GuardOutcome::Reject(format!("limit check failed: {reason}"));
        }
    } else {
        audit(tool, Some(&key.id), "allow", "scope ok (no limits ctx)");
    }

    GuardOutcome::Allow
}

/// 审计日志：key_id / tool / result / reason
#[cfg(test)]
fn audit(tool: &str, key_id: Option<&str>, result: &str, reason: &str) {
    let key_id = key_id.unwrap_or("<none>");
    if result == "reject" {
        futu_auth::audit::reject("mcp", tool, key_id, reason);
    } else {
        futu_auth::audit::allow("mcp", tool, key_id, Some(reason));
    }
}

/// 计算 args 的短哈希（前 8 hex），用于审计日志（不存原始敏感字段）
pub fn args_short_hash(args: &impl serde::Serialize) -> String {
    let j = match serde_json::to_vec(args) {
        Ok(v) => v,
        Err(_) => return "n/a".into(),
    };
    let h = Sha256::digest(&j);
    hex::encode(&h[..4])
}

/// 交易工具执行完后的审计事件：解析 handler 返回的 JSON，success / failure
/// 写入 audit JSONL。`key_id = None` 时用 "<none>" 占位（legacy 模式）。
pub fn emit_trade_outcome(tool: &'static str, key_id: Option<&str>, args_hash: &str, result: &str) {
    let key_id = key_id.unwrap_or("<none>");
    let (outcome, reason) = match serde_json::from_str::<serde_json::Value>(result) {
        Ok(v) => match v.get("error").and_then(|e| e.as_str()) {
            Some(err) => ("failure", Some(err.to_string())),
            None => ("success", None),
        },
        Err(_) => ("unknown", Some("non-json response".to_string())),
    };
    futu_auth::audit::trade("mcp", tool, key_id, args_hash, outcome, reason.as_deref());
}

#[cfg(test)]
mod tests;