futu_auth/

scope.rs

//! Scope: 能力分组

use std::fmt;
use std::str::FromStr;

use futu_core::proto_id;
use serde::{Deserialize, Serialize};

/// API Key 能力分组
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "String", into = "String")]
#[non_exhaustive]
pub enum Scope {
    /// 行情只读（11 个工具）
    QotRead,
    /// 行情/用户数据写。v1.8 起新 QOT mutation 必须使用；历史写接口在
    /// breaking migration 前可同时接受 qot:read。
    QotWrite,
    /// 账户只读（5 个工具）
    AccRead,
    /// 模拟交易写
    TradeSimulate,
    /// 真实交易写
    TradeReal,
    /// 允许自动 unlock_trade（从 keychain 读密码）
    TradeUnlock,
    /// v1.4.32+ daemon 管理 (`/api/admin/status|reload|shutdown`)。
    /// 权限危险，只给运维 / 监控 key；LLM key 永远不要加这个。
    Admin,
    /// v1.4.90 P1-A: trade 类 super-scope。**仅在 REST middleware
    /// `scope_for_path` 用作"需要任意 trade* scope"的占位需求**：持有
    /// [`Scope::TradeReal`] / [`Scope::TradeSimulate`] / [`Scope::TradeUnlock`]
    /// 任一即满足。**不应**写入 keys.json（KeyRecord.scopes 里出现
    /// `Scope::Trade` 没意义，等价于不分 sim/real/unlock 的旧式权限）。
    /// env 是 sim 还是 real 由 handler 层用 KeyRecord 真实 scopes 二次校验。
    Trade,
    /// v1.4.106 codex 0542 F1 [P2 SECURITY]: `/metrics` 端点 scope-gated 的
    /// 专用 scope. default secure — 不再像 v1.4.105 之前那样无 auth 暴露
    /// `key_id` 标签 (= API key id 明文 cardinality enumeration channel,
    /// 任意本机 process / agent skill 都能 fingerprint).
    ///
    /// **行为**:
    /// - 持 `MetricsRead` 的 key → `/metrics` 通过, `key_id=` label 仍 redact
    ///   为 `kh_<8hex>` (短 SHA256 hash, 反查 key id 需要离线 dictionary 攻击)
    /// - 不持 `MetricsRead` → 401 (legacy 模式) 或 403
    /// - **opt-out**: 老用户 dashboard 依赖明文 key_id 时设
    ///   `FUTU_METRICS_PUBLIC=1` 环境变量回退 v1.4.105 行为 (无 auth + 明文
    ///   key_id). 此为 backward-compat 边界 trade-off — secure default + 明示
    ///   opt-out, 而非 opt-in.
    ///
    /// 与 [`Scope::Admin`] 区别: Admin 含 mutating endpoint (shutdown/reload),
    /// MetricsRead 仅 read-only Prometheus 抓取. dashboard / Prometheus
    /// scraper 应持 MetricsRead 而不是 Admin.
    MetricsRead,
    /// Pre-login authentication setup, including Verification(1006).
    /// This scope grants no quote/account/trade capability.
    AuthSetup,
}

impl Scope {
    pub const ALL: &'static [Scope] = &[
        Scope::QotRead,
        Scope::QotWrite,
        Scope::AccRead,
        Scope::TradeSimulate,
        Scope::TradeReal,
        Scope::TradeUnlock,
        Scope::Admin,
        Scope::MetricsRead,
        Scope::AuthSetup,
    ];

    #[must_use]
    pub fn as_str(&self) -> &'static str {
        match self {
            Scope::QotRead => "qot:read",
            Scope::QotWrite => "qot:write",
            Scope::AccRead => "acc:read",
            Scope::TradeSimulate => "trade:simulate",
            Scope::TradeReal => "trade:real",
            Scope::TradeUnlock => "trade:unlock",
            Scope::Admin => "admin",
            Scope::Trade => "trade",
            Scope::MetricsRead => "metrics:read",
            Scope::AuthSetup => "auth:setup",
        }
    }

    /// v1.4.90 P1-A: super-scope `Scope::Trade` 的成员集合。REST
    /// middleware 在 mutating trade endpoint 的需求侧用 `Scope::Trade`
    /// 占位，持有任一成员即视为满足；handler 层再用真实 scopes
    /// 二次校验 env (sim/real/unlock).
    #[must_use]
    pub fn trade_super_members() -> &'static [Scope] {
        &[Scope::TradeReal, Scope::TradeSimulate, Scope::TradeUnlock]
    }
}

/// 将交易环境的 real/simulate 事实映射为唯一的写权限 scope。
///
/// Transport adapter 仍负责按自身 wire shape 解析环境；解析成功后必须调用
/// 本函数，避免 REST、gRPC 与 MCP 各自维护一份映射。
#[must_use]
pub const fn trade_scope_for_env_is_real(is_real: bool) -> Scope {
    if is_real {
        Scope::TradeReal
    } else {
        Scope::TradeSimulate
    }
}

impl fmt::Display for Scope {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

#[derive(Debug, thiserror::Error)]
#[error(
    "unknown scope {0:?} (valid: qot:read, qot:write, acc:read, trade:simulate, trade:real, trade:unlock, admin, metrics:read, auth:setup)"
)]
pub struct ScopeParseError(pub String);

impl FromStr for Scope {
    type Err = ScopeParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "qot:read" => Ok(Scope::QotRead),
            "qot:write" => Ok(Scope::QotWrite),
            "acc:read" => Ok(Scope::AccRead),
            "trade:simulate" => Ok(Scope::TradeSimulate),
            "trade:real" => Ok(Scope::TradeReal),
            "trade:unlock" => Ok(Scope::TradeUnlock),
            "admin" => Ok(Scope::Admin),
            // 注意：`"trade"` 仅作为 super-scope 内部占位 (Scope::Trade)，
            // 不允许从 keys.json / CLI --scopes 解析，避免用户误以为
            // bare trade 会授予 trade:real / trade:simulate / trade:unlock。
            // v1.4.106 codex 0542 F1 [P2 SECURITY]: /metrics 端点专用 scope.
            "metrics:read" => Ok(Scope::MetricsRead),
            "auth:setup" => Ok(Scope::AuthSetup),
            other => Err(ScopeParseError(other.to_string())),
        }
    }
}

impl TryFrom<String> for Scope {
    type Error = ScopeParseError;
    fn try_from(value: String) -> Result<Self, Self::Error> {
        value.parse()
    }
}

impl From<Scope> for String {
    fn from(s: Scope) -> String {
        s.as_str().to_string()
    }
}

/// Futu API protocol id → 所需 scope 的**通用映射**
///
/// gRPC 和核心 WS 都用这个函数做 scope 检查。proto_id 常量定义在 futu-core
/// （circular dep 顾虑下这里手动枚举）；新增 proto 时必须同步更新这里的 match
/// 分支，否则落到 catch-all `TradeReal` 被拒（fail-closed）。
///
/// **v1.4.104 codex round 1 F4 (P2) fix**: 显式 trade/acc protos 用
/// [`SCOPED_TRADE_REAL_PROTOS`] / [`SCOPED_TRADE_UNLOCK_PROTOS`] /
/// [`SCOPED_ACC_READ_PROTOS`] 暴露给 invariant test, 让
/// `body_aware::build_check_ctxs` + `response_filter::FilterRegistry` 共同
/// 覆盖. 加新 scoped proto 时:
/// 1. match 分支加 → 让 scope check 知道新 proto
/// 2. 把 proto_id 加到对应的 `SCOPED_*_PROTOS` const list (机械 enumeration)
/// 3. 其中 一处 (body_aware OR response_filter OR EXPLICIT_NO_ACC_ID_PROTOS)
///    必须 cover, 否则 cross_surface_invariants test 挂.
///
/// | proto_id 范围 | 所需 scope |
/// |---|---|
/// | 1xxx 系统（InitConnect / GetGlobalState / KeepAlive / …） | 无（放行） |
/// | 3xxx 行情（含 push updates） | `qot:read` |
/// | 2005 UnlockTrade | `trade:unlock`（v1.4.104 codex F1 P1 fix） |
/// | 2202 PlaceOrder / 2205 ModifyOrder / 2227 PlaceComboOrder / 2237 ReconfirmOrder | `trade:real` |
/// | 2xxx 账户只读（AccList / Funds / Positions / Orders / Deals / 费率 / push） | `acc:read` |
/// | 其他 | catch-all `trade:real`（fail-closed） |
pub fn scope_for_proto_id(proto_id: u32) -> Option<Scope> {
    match proto_id {
        // v1.4.110 GetUsedQuota / v1.4.98 T2-8 GET_TOKEN_STATE 落在 1xxx
        // 范围, 但有明确业务权限语义. 单独前置, 避免被下面
        // 1000..=1999 => None 兜住.
        1010 => Some(Scope::QotRead),
        1006 => Some(Scope::AuthSetup),
        // NN+MM token 状态查询, unlock-trade 失败时第一线诊断.
        // 否则被下面 1000..=1999 => None 兜住.
        1326 => Some(Scope::AccRead),
        // v1.8 exact trading-session local extensions are read-only QOT surfaces.
        proto_id::QOT_GET_SECURITY_TRADING_SESSIONS
        | proto_id::QOT_GET_MARKET_TRADING_SESSIONS
        | proto_id::QOT_GET_HOT_NEWS
        | proto_id::QOT_GET_LATEST_NEWS
        | proto_id::QOT_GET_WATCHLIST_NEWS
        | proto_id::QOT_GET_WATCHLIST_ANNOUNCEMENT
        | proto_id::QOT_GET_WATCHLIST_RATING
        | proto_id::QOT_GET_STOCK_NEWS
        | proto_id::QOT_GET_KLINE_PATTERN
        | proto_id::QOT_GET_KLINE_PATTERN_STATISTICS
        | proto_id::QOT_GET_KLINE_PATTERN_STOCKS
        | proto_id::QOT_GET_KLINE_PATTERN_PERFORMANCE
        | proto_id::QOT_GET_KLINE_PATTERN_CATALOG => Some(Scope::QotRead),
        proto_id::QOT_ETF_SCREEN
        | proto_id::QOT_FUND_SCREEN
        | proto_id::QOT_FUTURE_SCREEN
        | proto_id::QOT_BOND_SCREEN => Some(Scope::QotRead),
        proto_id::QOT_GET_STOCK_NOTE_LABELS
        | proto_id::QOT_GET_STOCK_NOTES
        | proto_id::QOT_UPDATE_STOCK_NOTE => Some(Scope::AccRead),
        proto_id::QOT_MODIFY_USER_SECURITY
        | proto_id::QOT_SET_PRICE_REMINDER
        | proto_id::QOT_SET_OPTION_EVENT_ALERT
        | proto_id::QOT_SET_STOCK_NOTE => Some(Scope::QotWrite),
        proto_id::TRD_PREVIEW_ORDER_IMPACT
        | proto_id::TRD_GET_ASSET_TREND
        | proto_id::TRD_GET_YIELD_TREND
        | proto_id::TRD_GET_RETURN_CALENDAR
        | proto_id::TRD_GET_ORDER_RELATIONS
        | proto_id::TRD_GET_POSITION_CORPORATE_ACTIONS
        | proto_id::TRD_GET_ALGO_ORDER_LOGS => Some(Scope::AccRead),
        proto_id::TRD_PLACE_ORDER_GROUP
        | proto_id::TRD_MODIFY_ORDER_GROUP
        | proto_id::TRD_CANCEL_ORDER_GROUP
        | proto_id::TRD_DELETE_ORDER_GROUP
        | proto_id::TRD_PLACE_ALGO_ORDER
        | proto_id::TRD_MODIFY_ALGO_ORDER
        | proto_id::TRD_REVERSE_POSITION
        | proto_id::TRD_ROLL_POSITION
        | proto_id::TRD_CLEAR_FUTURES_POSITIONS
        | proto_id::TRD_BATCH_CLOSE_POSITIONS => Some(Scope::TradeReal),

        // 1xxx 系统 / 连接管理：InitConnect / GlobalState / KeepAlive / UserInfo ...
        1000..=1999 => None,

        // 3xxx 全部行情（请求 + push 全挂 qot:read）
        3000..=3999 => Some(Scope::QotRead),

        // v1.4.115 financial / IPO calendar: mobile-driven read-only quote
        // endpoints live outside the legacy 3xxx quote range, so they need
        // explicit QotRead coverage before the 2xxx trade/account branches.
        20025 | 20426 => Some(Scope::QotRead),

        // 2005 UnlockTrade —— v1.4.104 codex round 1 F1 (P1) fix:
        // 之前 mapping 是 TradeReal (推理 "未解锁不能下单, 视同 trade:real"
        // 是错的). UnlockTrade 是独立 scope:caller 持 trade:unlock 才能解锁,
        // 不应让 trade:real 通过. v1.4.103 codex F5.3 已让 MCP futu_unlock_trade
        // 走 trade:unlock, 但 gRPC/raw WS 直调 proto 2005 时仍走 TradeReal —
        // narrow Bearer (trade:real only, 无 trade:unlock) 可绕过 unlock scope.
        // v1.4.104 阶段 7-5 改 MCP futu_unlock_trade 走 caller-specific
        // pipeline (TradeUnlock check), 但 proto 2005 mapping 还是 TradeReal —
        // codex round 1 F1 抓出 silent gap. 现统一改 TradeUnlock 关闭 4 surface
        // 一致.
        2005 => Some(Scope::TradeUnlock),

        // 2202 PlaceOrder / 2205 ModifyOrder / 2227 PlaceComboOrder / 2237 ReconfirmOrder
        2202 | 2205 | 2227 | 2237 => Some(Scope::TradeReal),

        // 2xxx 账户只读：list / funds / positions / orders / deals / push / 费率
        2001
        | 2008
        | proto_id::TRD_UNSUB_ACC_PUSH_LOCAL
        | 2101
        | 2102
        | 2111
        | 2112
        | 2201
        | 2208
        | 2211
        | 2218
        | 2221
        | 2222
        | 2223
        | 2225
        | 2226
        | 2240 => Some(Scope::AccRead),

        // v1.4.94 / v1.4.95 Tier M (mobile-driven extensions, 22701-22710):
        // 全 only-read 性质 (账户资金 / 业务分组 / margin / 合规 / 债券 holdings) →
        // acc:read scope 统一. 不显式覆盖会 fall-through 到 TradeReal,
        // 让 acc:read-only 的 LLM agent 调不到这些 endpoint.
        //
        // | proto_id | endpoint                  | 含义              |
        // |----------|---------------------------|-------------------|
        // | 22701    | TRD_GET_CASH_LOG          | v1.4.94 M1        |
        // | 22702    | TRD_GET_CASH_DETAIL       | v1.4.94 M1        |
        // | 22703    | TRD_GET_BIZ_GROUP         | v1.4.94 M1        |
        // | 22704    | TRD_GET_MARGIN_INFO       | v1.4.95 U2-D      |
        // | 22705    | TRD_GET_ACCOUNT_FLAG      | v1.4.95 U2-A      |
        // | 22706    | TRD_GET_BOND_TOTAL_ASSET  | v1.4.95 U2-B      |
        // | 22707    | TRD_GET_BOND_SINGLE_ASSET | v1.4.95 U2-B      |
        // | 22708    | TRD_GET_BOND_POSITION_LIST| v1.4.95 U2-B      |
        // | 22709    | TRD_GET_BOND_ANSWER_STATE | v1.4.95 U2-B      |
        // | 22710    | TRD_GET_BOND_TRADE_REMIND | v1.4.95 U2-B      |
        22701..=22710 => Some(Scope::AccRead),

        // v1.4.98 T2-* (mobile-source-audit Phase 2): quote 类 read-only endpoint.
        // - 6503 QOT_GET_SPREAD_TABLE: 摆盘步长
        // - 20231 QOT_GET_RISK_FREE_RATE: 无风险利率 (期权定价)
        // - 6365 / 6366 QOT_GET_TICKER_STATISTIC: 逐笔统计 + push
        // (cmd 1326 GET_TOKEN_STATE 已前置 acc:read, 避免 1xxx None 兜底)
        6503 | 6365 | 6366 | 20231 => Some(Scope::QotRead),

        // 未覆盖 → fail-closed，统一拒（返回 TradeReal 让上游 check_scope 比对最严格）
        _ => Some(Scope::TradeReal),
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// v1.4.104 codex round 1 F4 (P2) fix: scoped proto_id 机械枚举
//
// 让 `futu-auth-pipeline::body_aware` / `response_filter` / 显式 exception
// list 通过 `coverage_invariant` 测试**机械**对齐 — 加新 scoped proto 时
// 漏一处必挂. 与 v1.4.103/104 之前 hand-maintained covered vec 不同, 现
// 不再依赖人记忆.
// ─────────────────────────────────────────────────────────────────────────────

/// 显式 enumerate 所有需要 acc_id 白名单或响应 filter 的 trade write proto_id.
/// `body_aware::build_check_ctxs` 必须 decode 这些 proto.
pub const SCOPED_TRADE_REAL_PROTOS: &[u32] = &[
    2202, // TRD_PLACE_ORDER
    2205, // TRD_MODIFY_ORDER
    2227, // TRD_PLACE_COMBO_ORDER
    2237, // TRD_RECONFIRM_ORDER
    proto_id::TRD_PLACE_ORDER_GROUP,
    proto_id::TRD_MODIFY_ORDER_GROUP,
    proto_id::TRD_CANCEL_ORDER_GROUP,
    proto_id::TRD_DELETE_ORDER_GROUP,
    proto_id::TRD_PLACE_ALGO_ORDER,
    proto_id::TRD_MODIFY_ALGO_ORDER,
    proto_id::TRD_REVERSE_POSITION,
    proto_id::TRD_ROLL_POSITION,
    proto_id::TRD_CLEAR_FUTURES_POSITIONS,
    proto_id::TRD_BATCH_CLOSE_POSITIONS,
];

/// 显式 enumerate trade unlock proto_id (caller-specific TradeUnlock scope).
/// v1.4.104 codex F1 (P1) 加.
pub const SCOPED_TRADE_UNLOCK_PROTOS: &[u32] = &[
    2005, // TRD_UNLOCK_TRADE
];

/// 显式 enumerate acc:read proto_id. 大多数走 `body_aware` decode acc_id
/// whitelist. 例外见 [`EXPLICIT_NO_ACC_ID_PROTOS`].
pub const SCOPED_ACC_READ_PROTOS: &[u32] = &[
    1326,                               // GET_TOKEN_STATE — 无 acc_id, 走 explicit exception
    2001,                               // TRD_GET_ACC_LIST — request 无 acc_id, 走 response-filter
    2008,                               // TRD_SUB_ACC_PUSH (multi acc_id_list)
    proto_id::TRD_UNSUB_ACC_PUSH_LOCAL, // Rust-daemon local public unsub (multi acc_id_list)
    2101,
    2102,
    2111,
    2112, // funds / positions / max_trd_qtys / combo_max_trd_qtys
    2201,
    2208,
    2211,
    2218, // order list / order_update push / fill list / fill_update push
    2221,
    2222, // history orders / history fills
    2223,
    2225,
    2226, // margin ratio / order fee / flow summary
    2240, // notify push
    // Tier M (v1.4.94/95)
    22701,
    22702,
    22703, // cash log / detail / biz group
    22704, // margin info
    22705, // account flag
    22706,
    22707,
    22708,
    22709,
    22710, // bond × 5
    proto_id::TRD_PREVIEW_ORDER_IMPACT,
    proto_id::TRD_GET_ASSET_TREND,
    proto_id::TRD_GET_YIELD_TREND,
    proto_id::TRD_GET_RETURN_CALENDAR,
    proto_id::TRD_GET_ORDER_RELATIONS,
    proto_id::TRD_GET_POSITION_CORPORATE_ACTIONS,
    proto_id::TRD_GET_ALGO_ORDER_LOGS,
];

/// **v1.4.106 ζ28 redo (codex 0532 F4 P3)**: typed coverage exception kind
/// — 替代无类型 `EXPLICIT_NO_BODY_AWARE_PROTOS` 数组. 每个 exception 必须
/// 显式分类, 让 "为什么这个 proto 不走 body_aware" 的意图保留在代码里
/// (而非靠注释推).
///
/// 4 个 variant 涵盖所有 "非 body-aware" 场景:
///
/// - [`Self::ResponseFiltered`] — request 无 acc_id, 但 response 含 acc_list[]
///   走 [`futu_auth_pipeline::FilterRegistry`] (e.g. 2001 TRD_GET_ACC_LIST).
/// - [`Self::PushOnly`] — push event 不是 request, 无 request-side body
///   (e.g. 2208 TRD_UPDATE_ORDER / 2218 TRD_UPDATE_ORDER_FILL / 2240 TRD_NOTIFY).
///   pipeline 不应 dispatch push proto 作 request, 但 scope check 仍跑.
/// - [`Self::MetaNoAccount`] — meta query 无 acc_id 概念 (e.g. 1326
///   GET_TOKEN_STATE NN/MM token 状态).
/// - [`Self::InternalOnly`] — daemon-internal proto_id (高位 0x8000_0000 bit),
///   不应从公开 surface 进入 (gRPC / raw WS / raw TCP). v1.4.106 codex 0532 F3
///   public surface 显式 reject (见 [`is_internal_proto_id`]).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum CoverageException {
    ResponseFiltered,
    PushOnly,
    MetaNoAccount,
    InternalOnly,
}

/// `(proto_id, CoverageException)` 显式分类表 — v1.4.106 ζ28 替代无类型
/// `EXPLICIT_NO_BODY_AWARE_PROTOS`.
///
/// 每个 entry 在 invariant test 强制 match 某个 variant, 不允许 hand-roll
/// "我加进去就行" 漏类型.
pub const COVERAGE_EXCEPTIONS: &[(u32, CoverageException)] = &[
    // ResponseFiltered — request 无 acc_id, response s2c.acc_list[] 走 FilterRegistry
    (2001, CoverageException::ResponseFiltered),
    // PushOnly — push event 不是 request
    (2208, CoverageException::PushOnly),
    (2218, CoverageException::PushOnly),
    (2240, CoverageException::PushOnly),
    // MetaNoAccount — meta query 无 acc_id 概念
    (1326, CoverageException::MetaNoAccount),
];

/// 列出本 daemon 所有 proto_id → exception 映射表的 proto_id 集合.
/// 与 [`COVERAGE_EXCEPTIONS`] 同步 (v1.4.106 ζ28 起 source-of-truth 是
/// `COVERAGE_EXCEPTIONS`, 此 const 仅作 backward compat alias).
///
/// **保留供 backward compat**: `body_aware::extract_coverage` 用此 set
/// 判 NoAccIdConcept 还是 NotRegistered. 加新 exception 走
/// [`COVERAGE_EXCEPTIONS`] 自动反映在此.
pub const EXPLICIT_NO_BODY_AWARE_PROTOS: &[u32] = &[
    1326, // GET_TOKEN_STATE — meta query (NN/MM token state, 无 acc_id)
    2001, // TRD_GET_ACC_LIST — 走 response-side filter (FilterRegistry)
    2208, // TRD_UPDATE_ORDER push — 不是 request, 无 body_aware
    2218, // TRD_UPDATE_ORDER_FILL push
    2240, // TRD_NOTIFY push
];

/// **v1.4.106 ζ28 redo (codex 0532 F3 P2)**: 判一个 proto_id 是否是
/// daemon-internal (高位 `0x8000_0000` bit set).
///
/// daemon-internal proto_id (e.g. `TRD_UNSUB_ACC_PUSH_INTERNAL = 0x8000_0000 |
/// 2008` v1.4.102 codex 44 F1 fix) **绝不应**从公开 surface (gRPC / raw WS /
/// raw TCP) 进入 — 仅 REST `/api/unsub-acc-push` handler 内部合成给 router.
///
/// 公开 surface 看到此 bit set 立即 reject (`Forbidden` 等价 wire error)
/// 防探测 daemon 内部 routing.
#[must_use]
pub fn is_internal_proto_id(proto_id: u32) -> bool {
    (proto_id & 0x8000_0000) != 0
}

#[cfg(test)]
mod tests;