futu_mcp/

tool_auth.rs

//! MCP caller-auth helper types and pure policy decisions.
//!
//! This module deliberately avoids concrete `#[tool]` handlers.  It keeps the
//! reusable identity snapshot / Bearer parsing / early trade-scope policy out of
//! `tools.rs`, while `tools.rs` remains the thin dispatch surface.

use crate::tools::FutuServer;
use crate::{guard, handlers};
use futu_auth::CheckCtx;
use rmcp::{RoleServer, service::RequestContext};

mod policy;
pub(crate) use policy::{
    CallerSnapshot, EarlyTradeScopeDecision, decide_early_trade_scope, http_bearer_token,
    outcome_key_id_from_snapshot, same_reusable_identity,
};
use policy::{audit_reject_with_context, mcp_audit_context, scope_label};

impl FutuServer {
    // v1.4.58 Phase C3 删除：`Self::err` + `Self::wrap` v1.4.42 遗留的 JSON
    // `"isError": true` content-marker hack。所有 tool handler 已迁移到
    // `Result<String, String>` 返回类型，rmcp 自动 set MCP spec 的
    // `CallToolResult.is_error = Some(true)` on Err variant（top-level
    // envelope 字段，对齐 MCP 协议）。用 `Self::tool_err` / `Self::wrap_result`
    // 取代。
    //
    // v1.4.89 #7 "MCP isError 根治" 确认已落地 in-place —— 无需改 signature
    // 到 `Result<CallToolResult, McpError>`。rmcp 1.4.0 提供 blanket
    // `impl<T: IntoCallToolResult, E: IntoCallToolResult> IntoCallToolResult
    // for Result<T, E>`（见 rmcp src/handler/server/tool.rs:100-112），
    // `Err(String)` 分支自动 set `result.is_error = Some(true)` + content
    // 保留 JSON body（老 client 兼容"error"/"status"字段双信号）。v1.4.89
    // 回归测试同时锁定协议层 is_error 与兼容 JSON 契约。

    /// v1.4.58 Phase C1: 新 helper — 返 `Result<String, String>` 让 rmcp 自动
    /// set top-level `CallToolResult.is_error = Some(true)`（对齐 MCP spec）。
    ///
    /// 迁移策略（C1/C2/C3 拆 3 commit，都进 v1.4.58 一个版本）：
    /// - **C1**：加此 helper + 迁移 5-10 pilot handlers
    /// - **C2**：批量迁移剩余 70+ handlers
    /// - **C3**：删除 `Self::err` / `Self::wrap` String hack（v1.4.42 遗留）
    ///
    /// Client 双信号（向后兼容）：
    /// - Top-level `is_error: true`（MCP spec 正确方式）
    /// - Content JSON 里仍含 `{"error": msg, ...}`（老 client 兼容）
    ///
    /// rmcp `IntoCallToolResult for Result<T, E>` impl 自动把 Err 转成
    /// `CallToolResult { is_error: Some(true), content: [msg.into_contents()] }`。
    pub(crate) fn tool_err(msg: impl std::fmt::Display) -> std::result::Result<String, String> {
        Err(serde_json::json!({
            "error": msg.to_string(),
            "status": "error",
        })
        .to_string())
    }

    /// v1.4.106 D1 5d: MCP-specific reject translator (rich context: tool + audit_key_id).
    ///
    /// MCP 返 JSON-encoded `String` (rmcp `Err(String)` → 自动 `CallToolResult
    /// { is_error: Some(true), ... }`, 见 `tool_err` 注释).
    ///
    /// **rich context 路径** (require_acc_read_with_acc_id / require_trading 等):
    /// 把 `kind` + `reason` + `tool` + `audit_key_id` 翻成 user-friendly
    /// MCP error JSON. 这里保留 tool name + audit_key_id, 让 LLM agent 知道
    /// 是哪个 tool 哪把 key.
    ///
    /// **不变量** (与 v1.4.105 byte-identical):
    /// - Unauthenticated → "API key required for {tool}: ..."
    /// - Forbidden → "API key {audit_key_id:?} forbidden: {reason}"
    ///   (注意: reason 在 MCP 路径**保留**, 与 REST/gRPC generic 不同; MCP 是
    ///   LLM agent 调试场景, 反推风险低 + agent 需要清晰 hint 来纠正参数)
    /// - RateLimited → "rate limit: {reason}"
    /// - 其他 → reason
    fn mcp_reject_to_json(
        kind: futu_auth_pipeline::RejectKind,
        reason: String,
        tool: &str,
        audit_key_id: &str,
    ) -> String {
        use futu_auth_pipeline::RejectKind;
        let prefix = match kind {
            RejectKind::Unauthenticated => format!(
                "API key required for {tool}: provide via tool args api_key, \
                 HTTP Authorization Bearer, or set FUTU_MCP_API_KEY"
            ),
            RejectKind::Forbidden => {
                // scope 不够 OR acc_id 不在白名单 — pipeline reason 已含细节.
                // MCP 路径保留 reason (LLM agent 调试用), 不同 REST/gRPC 的 generic.
                format!("API key {audit_key_id:?} forbidden: {reason}")
            }
            RejectKind::RateLimited => format!("rate limit: {reason}"),
            _ => reason.clone(),
        };
        serde_json::json!({
            "error": prefix,
            "status": "error",
        })
        .to_string()
    }

    /// v1.4.58 Phase C1: `wrap` 新版 —— 返 `Result<String, String>`。C2 批量迁移时使用。
    pub(crate) fn wrap_result<E: std::fmt::Display>(
        res: std::result::Result<String, E>,
    ) -> std::result::Result<String, String> {
        match res {
            Ok(s) => Ok(s),
            Err(e) => Self::tool_err(e),
        }
    }

    /// v1.4.58 Phase C2: 从 `Result<String, String>` 抽 string content 作 &str。
    /// 用于 `guard::emit_trade_outcome` 等接受 &str 的 side-effect observers —
    /// 无论 Ok/Err 都有 string 可引用。
    pub(crate) fn result_as_str(r: &std::result::Result<String, String>) -> &str {
        match r {
            Ok(s) | Err(s) => s.as_str(),
        }
    }

    pub(crate) async fn client_or_err(
        &self,
    ) -> std::result::Result<std::sync::Arc<futu_net::client::FutuClient>, String> {
        self.state.client().await.map_err(|e| {
            // MED-1 修（code review）：error 返 JSON 格式和 tool_err 对齐，
            // 让 agent 看到的 error shape 一致（tool_err / scope reject / connect
            // 三类 error 都是 JSON with "error" + "status" fields）
            serde_json::json!({
                "error": format!("gateway connect failed: {e}"),
                "status": "error",
            })
            .to_string()
        })
    }

    /// Common MCP read path: caller-specific guard first, then gateway client.
    ///
    /// Used by read-only tools that do not need the returned caller snapshot for
    /// account/card filtering. Account-specific tools still call
    /// `require_acc_read_with_acc_id` directly so they can pass the same snapshot
    /// into account locator / response filtering.
    pub(crate) async fn read_client_or_err(
        &self,
        tool: &'static str,
        req_ctx: &RequestContext<RoleServer>,
        api_key_override: Option<&str>,
        acc_id: Option<u64>,
    ) -> std::result::Result<std::sync::Arc<futu_net::client::FutuClient>, String> {
        self.require_acc_read_with_acc_id(tool, req_ctx, api_key_override, acc_id)?;
        self.client_or_err().await
    }

    /// v1.4.103 (codex 51 F1 / 52 F1 / 53 F1 / 54 F4 / 58 F1 — B5 + B6):
    /// per-request **caller-specific** scope 守卫 + acc_id 白名单 check.
    ///
    /// 旧 `require_tool_scope` 只看 process-wide `state.authed_key` (startup
    /// 捕获), HTTP 客户端带窄权限 Bearer 时 read tool 仍按 startup key 放行 —
    /// **跨账户 leak**.
    ///
    /// 本方法接 `req_ctx` (rmcp request context) + 可选 `api_key_override`
    /// (tool args 里的 api_key 字段, 与 trade write tools 一致) + 可选 `acc_id`,
    /// 优先级: api_key_override > HTTP Authorization Bearer > startup key.
    ///
    /// 解析得到 caller-specific KeyRecord 后:
    /// 1. 检查 scope (基于 caller 的 scope, 不是 startup 的)
    /// 2. 若 acc_id 提供 + caller key 有 allowed_acc_ids → 检查 acc_id ∈ allowed
    ///
    /// stdio mode (无 Bearer) + 无 api_key_override → fall back 到 startup key
    /// 行为, 不破坏 stdio 用户体验.
    ///
    /// 返 Some(error_json) 拒绝, None 放行.
    ///
    /// ## v1.4.104 阶段 4: pipeline 委托
    ///
    /// caller-specific KeyRecord 解析 + Bearer 不存在的 fail-closed 仍在本地
    /// (要保留 v1.4.103 codex F4 verbose error message). scope check + acc_id
    /// 白名单 + audit emit 委托给 [`futu_auth_pipeline::authenticate_request`]
    /// (跨 surface 共享: gRPC server.rs / WS ws_listener.rs / REST auth.rs 同源).
    /// LoC 减 ~80 行, 行为与 v1.4.103 byte-identical.
    pub(crate) fn require_acc_read_with_acc_id(
        &self,
        tool: &'static str,
        req_ctx: &RequestContext<RoleServer>,
        api_key_override: Option<&str>,
        acc_id: Option<u64>,
    ) -> Result<CallerSnapshot, String> {
        let needed_scope = match guard::scope_for_tool(tool) {
            Some(guard::ToolScope::Read(scope)) => scope,
            Some(guard::ToolScope::Trade) => {
                return Err(serde_json::json!({
                    "error": format!(
                        "internal error: {tool} is a trade tool, must use require_trading"
                    ),
                    "status": "error",
                })
                .to_string());
            }
            None => {
                return Err(serde_json::json!({
                    "error": format!("unknown MCP tool {tool:?}"),
                    "status": "error",
                })
                .to_string());
            }
        };
        self.authenticate_mcp_read(tool, needed_scope, req_ctx, api_key_override, acc_id, false)
    }

    /// Re-authenticate a long-lived 2026 resource operation against a stable
    /// transport identity. HTTP requires the request Bearer; stdio requires the
    /// startup key id. Tool-argument overrides are intentionally excluded: they
    /// cannot be reproduced by later resources/read or subscriptions/listen.
    pub(crate) fn require_push_continuation(
        &self,
        operation: &'static str,
        req_ctx: &RequestContext<RoleServer>,
    ) -> Result<CallerSnapshot, String> {
        self.authenticate_mcp_read(
            operation,
            futu_auth::Scope::AccRead,
            req_ctx,
            None,
            None,
            true,
        )
    }

    /// Read-only capability probe for MCP 2026 resource continuations.
    ///
    /// Discovery must not spend quota or emit an allow/reject audit record. It
    /// therefore resolves only the transport-stable identity and applies the
    /// same machine/expiry/`acc:read` facts used by the enforcing continuation
    /// path. The actual resource method re-authenticates and audits immediately
    /// before touching queue/listener state.
    pub(crate) fn has_reusable_push_identity(&self, req_ctx: &RequestContext<RoleServer>) -> bool {
        let is_http = req_ctx.extensions.get::<http::request::Parts>().is_some();
        let record = if is_http {
            http_bearer_token(req_ctx)
                .filter(|token| !token.is_empty())
                .and_then(|token| self.state.key_store().verify(&token))
        } else {
            self.state.authed_key().and_then(|startup| {
                self.state
                    .key_store()
                    .get_by_id_for_current_machine(&startup.id)
            })
        };

        record.is_some_and(|record| {
            !record.is_expired(chrono::Utc::now())
                && record.scopes.contains(&futu_auth::Scope::AccRead)
        })
    }

    /// Prove that the identity used by `futu_sub_acc_push` can be reproduced by
    /// later resource requests. This is evaluated before gateway connection and
    /// daemon dispatch, so mismatch cannot leave a remote orphan subscription.
    pub(crate) fn require_same_push_continuation_identity(
        &self,
        req_ctx: &RequestContext<RoleServer>,
        tool_snapshot: &CallerSnapshot,
    ) -> Result<CallerSnapshot, String> {
        let continuation = self.require_push_continuation("futu_sub_acc_push", req_ctx)?;
        if !same_reusable_identity(
            tool_snapshot.key_id.as_deref(),
            continuation.key_id.as_deref(),
        ) {
            return Err(serde_json::json!({
                "error": "futu_sub_acc_push: api_key identity differs from the reusable HTTP Bearer / stdio startup identity",
                "status": "error",
                "hint": "use the same API key for registration and subsequent resources/read or subscriptions/listen requests",
            })
            .to_string());
        }
        Ok(continuation)
    }

    fn authenticate_mcp_read(
        &self,
        operation: &'static str,
        needed_scope: futu_auth::Scope,
        req_ctx: &RequestContext<RoleServer>,
        api_key_override: Option<&str>,
        acc_id: Option<u64>,
        require_stable_identity: bool,
    ) -> Result<CallerSnapshot, String> {
        // v1.4.106 D1 5d: RejectKind 已移到 mcp_reject_to_json (rich-context),
        // 此 fn 内不再直接 match RejectKind.
        use futu_auth_pipeline::{
            AuthDecision, AuthEnvelope, Credential, Endpoint, SurfaceId, authenticate_request,
        };

        let audit_ctx = mcp_audit_context(req_ctx);
        let header_token = http_bearer_token(req_ctx);
        let is_http = req_ctx.extensions.get::<http::request::Parts>().is_some();
        let plaintext_override = if require_stable_identity {
            header_token.as_deref().filter(|s| !s.is_empty())
        } else {
            api_key_override
                .filter(|s| !s.is_empty())
                .or(header_token.as_deref())
                .filter(|s| !s.is_empty())
        };

        if require_stable_identity && is_http && plaintext_override.is_none() {
            audit_reject_with_context(
                &audit_ctx,
                operation,
                "<missing-bearer>",
                "modern push continuation requires HTTP Bearer",
            );
            return Err(serde_json::json!({
                "error": format!("{operation}: HTTP Bearer required for modern push continuation"),
                "status": "error",
            })
            .to_string());
        }

        // v1.4.103 codex F4 (P1) fail-closed: caller-supplied Bearer/api_key
        // verify 失败 → **立即 reject** 不 fall back 到 startup key (跨租户 leak).
        // 这一段保留在本地 (不进 pipeline) 是为了保留 v1.4.103 verbose error JSON
        // (LLM agent 看到 "v1.4.103 codex F4 fail-closed" 等明确指引).
        //
        // v1.4.104 codex round 1 F3 (P2) fix: 同时 capture caller's KeyRecord
        // snapshot (Option<Arc<KeyRecord>>), 后续放进 CallerSnapshot 让 call
        // sites 用同一身份做 response filter / push subscriber ownership /
        // visibility — 不再 re-resolve from Bearer/startup (TOCTOU + drift risk).
        let resolved_rec: Option<std::sync::Arc<futu_auth::KeyRecord>> = match plaintext_override {
            Some(p) => match self.state.key_store().verify(p) {
                Some(rec) => Some(rec),
                None => {
                    audit_reject_with_context(
                        &audit_ctx,
                        operation,
                        "<bearer-invalid>",
                        "invalid HTTP Bearer / api_key — fail-closed (no fallback to startup key)",
                    );
                    return Err(serde_json::json!({
                        "error": format!(
                            "{operation}: invalid Bearer token / api_key argument. \
                             v1.4.103 codex F4 fail-closed — daemon does NOT fall back \
                             to startup key when caller-supplied auth fails verification."
                        ),
                        "status": "error",
                    })
                    .to_string());
                }
            },
            // v1.4.106 codex 0608 F2 (P1): startup fallback 用
            // `get_by_id_for_current_machine` 替代裸 `get_by_id`, 让 SIGHUP
            // 收紧 allowed_machines 后能立即 reject (与 Bearer 路径 verify
            // 自带 machine 校验行为对称).
            None => self
                .state
                .authed_key()
                .and_then(|k| self.state.key_store().get_by_id_for_current_machine(&k.id)),
        };
        let credential: Credential<'_> = match &resolved_rec {
            Some(rec) => Credential::PreVerified(rec.clone()),
            None => Credential::None,
        };

        if require_stable_identity && resolved_rec.is_none() {
            audit_reject_with_context(
                &audit_ctx,
                operation,
                "<missing-stable-identity>",
                "modern push continuation requires a configured reusable identity",
            );
            return Err(serde_json::json!({
                "error": format!("{operation}: reusable API key identity required for modern push continuation"),
                "status": "error",
            })
            .to_string());
        }

        // Pipeline: scope check + expiry + acc_id 白名单 + audit emit 一处.
        // - explicit_acc_id: MCP tool args 直接给 (跳 body decode, MCP 无 raw proto body)
        // - commit_rate=false: read tool 不 commit rate (rate gate 是 trade write 专属)
        let env = AuthEnvelope {
            surface: SurfaceId::Mcp,
            endpoint: Endpoint::McpTool(operation),
            needed_scope: Some(needed_scope),
            credential,
            proto_id: None,
            body: &[],
            explicit_acc_id: acc_id,
            explicit_ctx: None,
            commit_rate: false,
            audit_emit: true,
        };

        match futu_auth::audit::with_context(audit_ctx.clone(), || {
            authenticate_request(self.state.key_store(), self.state.counters(), env)
        }) {
            AuthDecision::Allow {
                allowed_acc_ids, ..
            } => {
                // v1.4.104 codex F3 (P2): 返 caller snapshot 让 call sites
                // 用同一身份做 response filter / push ownership.
                Ok(CallerSnapshot {
                    key_id: resolved_rec.as_ref().map(|r| r.id.clone()),
                    rec: resolved_rec,
                    allowed_acc_ids,
                })
            }
            AuthDecision::Reject {
                kind,
                reason,
                audit_key_id,
            } => {
                // pipeline 已 audit reject; v1.4.106 D1 5d: 走 rich-context
                // helper, 翻成 MCP-specific JSON.
                Err(Self::mcp_reject_to_json(
                    kind,
                    reason,
                    operation,
                    &audit_key_id,
                ))
            }
        }
    }

    /// 交易写守卫;ctx=Some 时同时做限额检查;override_key=Some 时优先用该 plaintext.
    ///
    /// ## v1.4.104 阶段 7-4: pipeline 委托
    ///
    /// 把 `guard::require_trading` 165 LoC 折叠为 ~70 LoC 调用 pipeline:
    /// - **legacy 2 级开关 (`enable_trading` / `allow_real_trading`) 仍在本地**
    ///   (MCP-specific, pipeline 不知 daemon 启动 flag).
    /// - per-call `override_key` 仍在本地 verify (保留 v1.4.103 codex F4
    ///   verbose error message: "per-call api_key invalid").
    /// - **scope check + expiry + rate gate + body-aware ctx + audit** 全
    ///   委托 `authenticate_request` (与 4 surface unified).
    pub(crate) fn require_trading(
        &self,
        tool: &'static str,
        env: &str,
        ctx: Option<CheckCtx>,
        override_key: Option<&str>,
    ) -> Option<String> {
        use futu_auth_pipeline::{
            AuthDecision, AuthEnvelope, Credential, Endpoint, RejectKind, SurfaceId,
            authenticate_request,
        };

        let is_real = handlers::trade_write::is_real_env(env);
        let needed_scope = futu_auth::trade_scope_for_env_is_real(is_real);

        // ── Legacy 2 级开关 (MCP-specific, 不进 pipeline) ────────────────────────
        if !self.state.is_scope_mode() {
            if !self.state.enable_trading() {
                futu_auth::audit::reject("mcp", tool, "<legacy>", "legacy: --enable-trading off");
                return Some(
                    serde_json::json!({
                        "error": "trading tools are disabled. Start futu-mcp with --enable-trading to enable.",
                        "status": "error",
                    })
                    .to_string(),
                );
            }
            if is_real && !self.state.allow_real_trading() {
                futu_auth::audit::reject(
                    "mcp",
                    tool,
                    "<legacy>",
                    "legacy: real env but --allow-real-trading off",
                );
                return Some(
                    serde_json::json!({
                        "error": "real trading is not allowed. Use env=\"simulate\" or restart futu-mcp with --allow-real-trading.",
                        "status": "error",
                    })
                    .to_string(),
                );
            }
            futu_auth::audit::allow("mcp", tool, "<legacy>", Some("legacy trading allowed"));
            return None;
        }

        // ── Resolve credential (per-call override or startup) ─────────────────────
        // per-call override 失败 → MCP-specific verbose reject (与 v1.4.103 兼容).
        let credential: Credential<'_> = if let Some(plaintext) =
            override_key.filter(|p| !p.is_empty())
        {
            match self.state.key_store().verify(plaintext) {
                Some(rec) => Credential::PreVerified(rec),
                None => {
                    futu_auth::audit::reject(
                        "mcp",
                        tool,
                        "<override-invalid>",
                        "per-call api_key invalid",
                    );
                    return Some(
                        serde_json::json!({
                            "error": "per-call api_key is invalid (not in keys.json or expired/bound to wrong machine)",
                            "status": "error",
                        })
                        .to_string(),
                    );
                }
            }
        } else {
            let startup = self.state.authed_key();
            if let Some(startup) = startup.as_ref() {
                // SIGHUP-aware fresh lookup + machine binding 校验
                // v1.4.106 codex 0608 F2 (P1): get_by_id_for_current_machine 替代裸
                // get_by_id, machine binding 失败也按 "key revoked" 处理.
                match self
                    .state
                    .key_store()
                    .get_by_id_for_current_machine(&startup.id)
                {
                    Some(rec) => Credential::PreVerified(rec),
                    None => {
                        futu_auth::audit::reject("mcp", tool, &startup.id, "key revoked");
                        return Some(
                            serde_json::json!({
                                "error": format!("API key {:?} has been revoked", startup.id),
                                "status": "error",
                            })
                            .to_string(),
                        );
                    }
                }
            } else {
                futu_auth::audit::reject("mcp", tool, "<none>", "no API key");
                return Some(
                    serde_json::json!({
                        "error": "API key required for trading tools (set FUTU_MCP_API_KEY, or pass api_key in the tool call)",
                        "status": "error",
                    })
                    .to_string(),
                );
            }
        };

        // ── Pipeline: scope check + expiry + rate gate (commit) + ctx-aware ──────
        // commit_rate=true: trade write 是 MCP rate gate (与 v1.4.103
        // `state.counters.check_and_commit(ctx, ...)` 行为对齐, 模拟 + 真单都
        // commit rate, 防 simulate flood backend).
        // explicit_ctx: 全 ctx 走 body-aware loop (market/symbol/value/side/acc_id 全检查).
        let env_envelope = AuthEnvelope {
            surface: SurfaceId::Mcp,
            endpoint: Endpoint::McpTool(tool),
            needed_scope: Some(needed_scope),
            credential,
            proto_id: None,
            body: &[],
            explicit_acc_id: None,
            explicit_ctx: ctx.clone(),
            commit_rate: true,
            audit_emit: true,
        };

        match authenticate_request(self.state.key_store(), self.state.counters(), env_envelope) {
            AuthDecision::Allow { .. } => None,
            AuthDecision::Reject {
                kind,
                reason,
                audit_key_id,
            } => {
                // v1.4.106 D1 5d: 走 rich-context helper.
                // **行为差异 (intentional)**: trade 路径 Unauthenticated 文案
                // 与 require_acc_read_with_acc_id 不同 — read 路径强调"提供 key",
                // trade 路径强调"key expired/revoked" (caller 已知有 key 但 verify
                // 后 expired/revoked, e.g. SIGHUP reload 后 key 失效).
                // 这里 inline match 保留, 不进 mcp_reject_to_json.
                let prefix = match kind {
                    RejectKind::Unauthenticated => {
                        format!("API key {audit_key_id:?} expired or revoked: {reason}")
                    }
                    RejectKind::Forbidden => {
                        format!("API key {audit_key_id:?} forbidden: {reason}")
                    }
                    RejectKind::RateLimited => format!("rate limit: {reason}"),
                    _ => reason.clone(),
                };
                Some(
                    serde_json::json!({
                        "error": prefix,
                        "status": "error",
                    })
                    .to_string(),
                )
            }
        }
    }

    // v1.4.106 codex round 1 F4 (P2): `current_key_id(&self, Option<&str>)`
    // 已废弃删除. 之前 5 处 emit_trade_outcome 用它做 daemon dispatch 后的
    // audit attribution, 但 SIGHUP reload 在 dispatch 中途 revoke caller 的
    // key 时, 该 helper 会 silent fallback 到 startup key → audit 记录被错
    // 归属. 现统一用 [`outcome_key_id_from_snapshot`] 取 precheck 时的
    // snapshot — race-free.
    //
    // 历史调用点 (全部已迁移):
    // - futu_place_order / futu_modify_order / futu_cancel_order /
    //   futu_reconfirm_order / futu_cancel_all_order / futu_unlock_trade
    //   (6 处 emit_trade_outcome)
    //
    // 没有其他 surface caller (grep 全 workspace 已确认).

    /// v1.4.105 D12 contract-hardening 补丁: 拿当前 caller 的 KeyRecord (per-call key
    /// 优先 > startup key). legacy mode (无 keys.json) 返 None.
    /// 用于 trade tool 调 resolve_acc_id_with_card_num 时获取
    /// `allowed_card_nums` 做 string-level whitelist 校验.
    /// codex round 1 F2 (P2) v1.4.105 移除老的 `current_key_rec` —
    /// 改用下面 `require_caller_key_strict` (fail-closed). 移除原因: invalid
    /// override 时 silent fallback startup → 给 backend resolve_acc_id_with_card_num
    /// 探测 leak. legacy mode 仍由 strict helper Ok(None) 返回处理.
    ///
    /// codex round 1 F2 (P2) v1.4.105: 在 trade write 路径里**先**验证 caller
    /// key + fail-closed, **再** resolve_acc_id_with_card_num. 防 invalid
    /// Bearer 仍触发 daemon GetAccList + 用 startup key 的 `allowed_card_nums`
    /// 做 resolution (探测 leakage).
    ///
    /// 与 `current_key_rec` 区别:
    /// - `current_key_rec`: invalid override → silent fallback startup key →
    ///   resolve 已 side-effect.
    /// - **`require_caller_key_strict`**: invalid override → 立即 Err 返 reject
    ///   JSON, **绝不 fallback**. 也保护 legacy mode (返 Ok(None)) 不破.
    ///
    /// Return:
    /// - `Ok(Some(rec))`: caller key 已验, 用其 `allowed_card_nums` 做 resolve
    /// - `Ok(None)`: scope mode 关闭 (legacy), require_trading 后续会处理
    /// - `Err(json_str)`: invalid override / no key / startup key revoked,
    ///   立即 abort
    pub(crate) fn require_caller_key_strict(
        &self,
        tool: &'static str,
        override_key: Option<&str>,
    ) -> std::result::Result<Option<std::sync::Arc<futu_auth::KeyRecord>>, String> {
        // legacy 模式 (无 keys.json) 不强制 — 后续 require_trading 仍会过 legacy
        // toggle, 此处放行 (返 Ok(None)) 保持向后兼容
        if !self.state.is_scope_mode() {
            return Ok(None);
        }

        if let Some(pt) = override_key.filter(|p| !p.is_empty()) {
            // 显式传 override_key → 验证, 无 fallback 防 leak
            match self.state.key_store().verify(pt) {
                Some(rec) => Ok(Some(rec)),
                None => {
                    futu_auth::audit::reject(
                        "mcp",
                        tool,
                        "<override-invalid>",
                        "per-call api_key invalid (pre-resolve fail-closed)",
                    );
                    Err(serde_json::json!({
                        "error": "per-call api_key is invalid (not in keys.json or expired/bound to wrong machine)",
                        "status": "error",
                    })
                    .to_string())
                }
            }
        } else {
            let startup = self.state.authed_key();
            if let Some(startup) = startup.as_ref() {
                // 无 override → 用 startup key (SIGHUP-aware fresh lookup + machine 校验)
                // v1.4.106 codex 0608 F2 (P1): get_by_id_for_current_machine 替代裸
                // get_by_id, machine 失败 / id 失踪都按 "key revoked" 处理.
                match self
                    .state
                    .key_store()
                    .get_by_id_for_current_machine(&startup.id)
                {
                    Some(rec) => Ok(Some(rec)),
                    None => {
                        futu_auth::audit::reject(
                            "mcp",
                            tool,
                            &startup.id,
                            "key revoked (pre-resolve fail-closed)",
                        );
                        Err(serde_json::json!({
                            "error": format!("API key {:?} has been revoked", startup.id),
                            "status": "error",
                        })
                        .to_string())
                    }
                }
            } else {
                // scope 模式但无 startup key 也无 override → 立即 reject
                futu_auth::audit::reject(
                    "mcp",
                    tool,
                    "<none>",
                    "no API key (pre-resolve fail-closed)",
                );
                Err(serde_json::json!({
                    "error": "API key required for trading tools (set FUTU_MCP_API_KEY, or pass api_key in the tool call)",
                    "status": "error",
                })
                .to_string())
            }
        }
    }

    /// codex round 2 F1 (P2) v1.4.105: trade write 路径 **早期 trade-scope
    /// 校验** — 在 `client_or_err` + `resolve_acc_id_with_card_num` 之前.
    ///
    /// 与 `require_trading` (full ctx body-aware) 区别:
    /// - `require_trading`: 完整 scope + acc_id whitelist + market/symbol/value
    ///   + rate gate (最终 gate, 在 resolve 之后).
    /// - **`require_trading_scope_only`**: 只 verify caller key 含 `trade:real`
    ///   或 `trade:simulate` scope. **不**检查 acc_id / market / symbol /
    ///   value (这些 final gate 仍由 `require_trading` 后做).
    ///
    /// **目标**: 防 valid 但**非-trade key** (e.g. `qot:read` only) 触发 daemon
    /// `GetAccList` + `card_num` resolution → 探测 not-found / ambiguous /
    /// existence timing & messages, 之后才被 final `require_trading` 拒绝.
    /// 早期 scope check 让此类 key 在 resolve 之前 fail-closed.
    ///
    /// **不替代** `require_trading` — 只前置一个轻量 scope guard. 后续 final
    /// gate (含 ctx) 仍跑.
    pub(crate) fn require_trading_scope_only(
        &self,
        tool: &'static str,
        env: &str,
        caller_key_rec: Option<&std::sync::Arc<futu_auth::KeyRecord>>,
    ) -> Option<String> {
        match decide_early_trade_scope(env, self.state.is_scope_mode(), caller_key_rec) {
            EarlyTradeScopeDecision::Allow => None,
            EarlyTradeScopeDecision::RejectMissingCallerKey => {
                futu_auth::audit::reject(
                    "mcp",
                    tool,
                    "<no-caller-key>",
                    "early-trade-scope: caller key snapshot missing (defensive)",
                );
                Some(
                    serde_json::json!({
                        "error": "internal: caller key missing for early trade-scope check",
                        "status": "error",
                    })
                    .to_string(),
                )
            }
            EarlyTradeScopeDecision::RejectMissingScope { needed, key_id } => {
                futu_auth::audit::reject(
                    "mcp",
                    tool,
                    &key_id,
                    &format!("early-trade-scope: missing {needed:?} — pre-resolve fail-closed"),
                );
                Some(
                    serde_json::json!({
                        "error": format!(
                            "API key {:?} forbidden — needs {} scope",
                            key_id, scope_label(needed)
                        ),
                        "status": "error",
                    })
                    .to_string(),
                )
            }
        }
    }
}

#[cfg(test)]
mod tests;