futu_rest/

auth.rs

//! REST API 的 Bearer Token 鉴权
//!
//! 两种模式：
//! - **未配置 KeyStore**：完全不鉴权（保持旧行为，启动日志 warn）
//! - **配置了 KeyStore**：所有 `/api/*` 请求必须带 `Authorization: Bearer <plaintext>`，
//!   且对应 key 必须有下表要求的 scope
//!
//! 路由 → scope 映射（硬编码，后续可做成配置）：
//!
//! | 路径前缀 | 所需 scope |
//! |---|---|
//! | `/api/global-state`, `/api/user-info`, `/api/quote-rights`, `/api/delay-statistics`, `/api/market-state` | `qot:read` |
//! | `/api/quote` / `/api/kline` / `/api/orderbook` / `/api/broker` / `/api/ticker` / `/api/rt` / `/api/snapshot` / `/api/static-info` / `/api/plate-*` / `/api/reference` / `/api/owner-plate` / `/api/option-chain` / `/api/warrant` / `/api/capital-*` / `/api/user-security` / `/api/stock-filter` / `/api/ipo-list` / `/api/future-info` / `/api/history-kline` / `/api/subscribe` / `/api/sub-info` | `qot:read` |
//! | `/api/accounts` / `/api/funds` / `/api/positions` / `/api/orders` / `/api/order-fills` / `/api/history-orders` / `/api/history-order-fills` / `/api/max-trd-qtys` / `/api/margin-ratio` / `/api/order-fee` / `/api/sub-acc-push` | `acc:read` |
//! | `/api/order` (POST = 下单) / `/api/modify-order` / `/api/unlock-trade` | `trade` (super-scope, v1.4.90 P1-A) |
//!
//! v1.4.90 P1-A: TRADE 列从硬编码 `Scope::TradeReal` 改为 super-scope
//! `Scope::Trade`。middleware 用 [`scope_satisfied`] 接受持有
//! `TradeReal/TradeSimulate/TradeUnlock` 任一即过，handler 层再用真实
//! scopes 二次校验 env (sim 不允许下真实单等)。修 `trade:simulate` /
//! `trade:unlock` key 调对应 endpoint 被 403 误拒。

use std::sync::Arc;

use axum::Json;
use axum::body::Body;
use axum::extract::State;
use axum::http::{Request, StatusCode};
use axum::middleware::Next;
use axum::response::{IntoResponse, Response};
use futu_auth::{KeyStore, RuntimeCounters, Scope};

/// REST auth middleware 的组合 state：KeyStore（谁能进）+ RuntimeCounters（限额）
///
/// 从 v1.0 起 middleware 除了 scope 检查还会在 `trade:real` 请求上跑一次
/// `check_and_commit` —— CheckCtx 里 market/symbol/side/value 全空，只挂
/// rate limit + 时段窗口两个全局闸门。精细化检查（daily / per_order /
/// side / 具体 market）留给下游 handler。
#[derive(Clone)]
pub struct AuthState {
    /// keys.json 热可替换 key store（共享同一 [`KeyStore`] 确保 /reload 生效）
    pub key_store: Arc<KeyStore>,
    /// 日累计 / 速率窗口 / rate-limit 的全局计数器；REST / gRPC / MCP 应共用
    /// 同一实例才能保证限额跨接口一致
    pub counters: Arc<RuntimeCounters>,
}

impl AuthState {
    /// 构造 AuthState。`key_store` 和 `counters` 都是 [`Arc`] 共享，调用方
    /// 负责在多个接口（REST / gRPC / MCP）之间保持同一实例。
    pub fn new(key_store: Arc<KeyStore>, counters: Arc<RuntimeCounters>) -> Self {
        Self {
            key_store,
            counters,
        }
    }
}

/// 根据 URI 路径推断所需 scope
///
/// **Fail-closed**：未知的 `/api/*` 路径返回 None，middleware 会拒绝请求。
/// REST path 只从 `futu-surface-spec` 的 EndpointSpec 派生；新增 REST route
/// 必须先声明 spec，否则 cross-surface invariant 会失败。
fn scope_for_path(path: &str) -> Option<Scope> {
    futu_surface_spec::lookup_endpoint_by_rest_path(path).map(rest_scope_for_spec)
}

fn rest_scope_for_spec(spec: &'static futu_surface_spec::EndpointSpec) -> Scope {
    match spec.runtime.scope {
        // REST keeps a trade super-scope at middleware level so trade:real,
        // trade:simulate, and trade:unlock keys can reach the handler, where
        // env-specific checks still happen against the decoded request.
        Scope::TradeReal | Scope::TradeSimulate => {
            if spec.runtime.side_effects == futu_surface_spec::SideEffectKind::Write {
                Scope::Trade
            } else {
                spec.runtime.scope
            }
        }
        other => other,
    }
}

/// v1.4.90 P1-A: scope satisfaction check.
///
/// - `needed = Scope::Trade` (super-scope) → held 含 `trade_super_members`
///   任一即过 (TradeReal / TradeSimulate / TradeUnlock).
/// - 其他 needed → 严格 `held.contains(&needed)`.
///
/// **不要**把 `Scope::Trade` 写进 keys.json 真实持有 set —— super-scope
/// 仅作 needed 侧占位语义。如果一把 key 持有 `Scope::Trade`（理论上不
/// 应该），它也只能"匹配 needed=Scope::Trade"路径，不会绕过严格 scope。
///
/// v1.4.104 阶段 5: 真实 middleware 路径已委托给 `futu_auth_pipeline` 的
/// 内部 `scope_satisfied`. 本地 fn 仅供 unit test (`v1_4_90_scope_satisfied_*`)
/// 验证语义不变.
#[cfg(test)]
fn scope_satisfied(held: &std::collections::HashSet<Scope>, needed: Scope) -> bool {
    if needed == Scope::Trade {
        return Scope::trade_super_members()
            .iter()
            .any(|s| held.contains(s));
    }
    held.contains(&needed)
}

/// v1.4.86 SEC-003 Q4: path 是否属于 "mutating write" 类 (legacy 模式下必须
/// 拦截). 返 true = 强制要求 auth, 不走 legacy fall-through.
///
/// 当前包含:
/// - trade:real (下单 / 改单 / 撤单 / 解锁 / reconfirm)
/// - admin (shutdown / reload / status — status 虽然 read-only 但含 daemon
///   内部状态, legacy 下也不应暴露给任意 local process)
fn is_mutating_write_path(path: &str) -> bool {
    // v1.4.90 P1-A: TRADE 列现返 super-scope `Scope::Trade`，原 TradeReal/
    // TradeSimulate 直接经路径表已不会出现，但保留兼容判断防未来漂移。
    // v1.4.104 codex F1 P1: /api/unlock-trade 现单独 TradeUnlock, 仍属 mutating.
    matches!(
        scope_for_path(path),
        Some(Scope::Trade)
            | Some(Scope::TradeReal)
            | Some(Scope::TradeSimulate)
            | Some(Scope::TradeUnlock)
            | Some(Scope::Admin)
    )
}

/// axum middleware：Bearer Token + scope 校验
///
/// **v1.4.86 SEC-003 Q4 真 fix**: legacy 模式 (未配 keys.json) 下, **仍然
/// 拦截** mutating endpoint (place-order / modify-order / cancel-all-order /
/// unlock-trade / reconfirm-order / admin/*) 未经 auth 的访问. 只读 endpoint
/// (行情 / 账户 read-only) 继续 legacy 允许 (backward compat 大部分用户).
///
/// 理由: 本机任何 skill / agent / 脚本可以无 auth `curl POST /api/order` 下单,
/// 这是安全风险. v1.4.84 stderr warn 不够, v1.4.86 作硬门禁.
///
/// ## v1.4.104 阶段 5: pipeline 委托
///
/// transport-only 逻辑 (legacy mutating-block / `/api/*` 路由 / Bearer 头解析 /
/// 404 unknown route / KeyRecord 注入 extensions) 仍在本地. **scope 检查 +
/// expiry + super-scope semantics + rate gate + audit emit** 全 委托给
/// [`futu_auth_pipeline::authenticate_request`] (跨 surface 共享同一份).
/// LoC 减 ~80 行. 行为 byte-identical:
/// - 401 Unauthenticated (含 `WWW-Authenticate` header) on missing Bearer
/// - 401 on invalid/expired key (pipeline reason)
/// - 404 on unknown `/api/*` route (REST-specific fail-closed)
/// - 403 generic "forbidden" body on scope miss / acc_id whitelist (BUG-011 不泄 key_id/scope)
/// - 429 with limit reason on rate fail
pub async fn bearer_auth(
    State(auth): State<AuthState>,
    mut req: Request<Body>,
    next: Next,
) -> Response {
    use futu_auth_pipeline::{
        AuthDecision, AuthEnvelope, Credential, Endpoint, SurfaceId, authenticate_request,
    };

    let path = req.uri().path().to_string();
    let legacy_mode = !auth.key_store.is_configured();

    // ── Step 1: Legacy mode + mutating-write block (REST 专属, v1.4.86 SEC-003 Q4) ─
    if legacy_mode {
        if is_mutating_write_path(&path) {
            audit(
                &path,
                None,
                "reject",
                "legacy mode (no keys.json) blocks mutating endpoint",
            );
            return (
                StatusCode::UNAUTHORIZED,
                [("www-authenticate", "Bearer realm=\"futu-rest\"")],
                Json(serde_json::json!({
                    "error": format!(
                        "mutating endpoint {path:?} requires API key. \
                         Run `futucli gen-key --id my-key --scopes trade:real` to \
                         create one, then `--rest-keys-file /path/to/keys.json` \
                         on daemon restart."
                    ),
                    "hint": "legacy no-auth mode only allows read-only endpoints. \
                            See https://www.futuapi.com/guide/auth/"
                })),
            )
                .into_response();
        }
        // legacy + read-only → 放行 (backward compat)
        return next.run(req).await;
    }

    // ── Step 2: 非 /api 路由 (含 /ws / /health / /metrics) 不走 auth middleware
    if !path.starts_with("/api/") {
        return next.run(req).await;
    }

    // ── Step 3: 提取 Bearer token (REST-specific 401 + WWW-Authenticate) ─────────
    //
    // v1.4.90 P2-G: scheme 大小写不敏感 (RFC 7235 §2.1).
    // v1.4.104 阶段 7-3: 走 `futu_auth_pipeline::parse_bearer_scheme` 共享 helper
    // (4 surface 同源, gRPC / WS / REST / MCP 一致解析).
    let token = req
        .headers()
        .get("authorization")
        .and_then(|v| v.to_str().ok())
        .and_then(|v| futu_auth_pipeline::parse_bearer_scheme(v).map(|t| t.to_string()));

    let Some(token) = token else {
        audit(&path, None, "reject", "missing Authorization: Bearer");
        return (
            StatusCode::UNAUTHORIZED,
            [("www-authenticate", "Bearer realm=\"futu-rest\"")],
            Json(serde_json::json!({ "error": "missing Authorization: Bearer <api-key>" })),
        )
            .into_response();
    };

    // ── Step 4: Unknown /api route → 404 fail-closed (REST-specific UX) ─────────
    //
    // 在 pipeline 之前做这个检查, 防止 pipeline 用 needed_scope=None 误放行 unknown
    // route (pipeline 的 None scope 视作 "公开 endpoint", 但 REST 把它当 unknown).
    let Some(needed) = scope_for_path(&path) else {
        // 注意 401/403 都不返: key 是有效的, 只是接口未知; 避免泄漏 "接口是否
        // 存在" 信息. 这里需要先 verify key 才能记 audit, 但不需要 scope check.
        let key_id = auth
            .key_store
            .verify(&token)
            .map(|r| r.id.clone())
            .unwrap_or_else(|| "<invalid>".to_string());
        audit(&path, Some(&key_id), "reject", "unknown /api route");
        return (
            StatusCode::NOT_FOUND,
            Json(serde_json::json!({
                "error": format!("unknown API route {path:?}")
            })),
        )
            .into_response();
    };

    // ── Step 5: Pipeline auth (scope + expiry + super-scope + rate + audit) ─────
    let env = AuthEnvelope {
        surface: SurfaceId::Rest,
        endpoint: Endpoint::HttpPath(&path),
        needed_scope: Some(needed),
        credential: Credential::Bearer(&token),
        proto_id: None, // REST middleware 层尚未解析 body, 不做 body-aware
        body: &[],
        explicit_acc_id: None,
        explicit_ctx: None,
        commit_rate: true, // REST middleware 层是 trade rate 闸门唯一一处
        audit_emit: true,
    };

    let rec = match authenticate_request(&auth.key_store, &auth.counters, env) {
        AuthDecision::Allow { rec, .. } => rec, // pipeline 已 audit allow
        AuthDecision::Reject { kind, reason, .. } => {
            // pipeline 已 audit reject; v1.4.106 D1 5a: 走 SurfaceAdapter trait
            // (RestAdapter::translate_reject), 跨 surface 一致.
            use futu_auth_pipeline::SurfaceAdapter;
            return RestAdapter::translate_reject(kind, reason);
        }
    };

    // v1.2: KeyRecord 塞 request extensions, 下游 handler 用 `Extension<Arc<KeyRecord>>`
    // 取出来跑 handler 层 full CheckCtx (acc_id / market / value 等细粒度).
    if let Some(rec) = rec {
        req.extensions_mut().insert(rec);
    }

    next.run(req).await
}

/// v1.4.106 D1 5a: REST surface adapter — 把 pipeline `AuthDecision::Reject`
/// 翻成 axum `Response`.
///
/// **历史**: v1.4.104 阶段 5 把"翻 reject 为 HTTP response"作 free fn
/// `reject_to_http_response` 写在本文件; v1.4.106 D1 把 4 surface 的同类
/// translate fn 收敛到 [`futu_auth_pipeline::SurfaceAdapter`] trait, 让 4
/// surface 一致, 防 sibling-route 不一致 regression (codex round 3 F1 教训).
///
/// **HTTP body 泛化策略** (v1.4.102 BUG-011 fix):
/// - 401: 保留 reason (让 client 知道 missing token / invalid bearer 类提示)
///   + 加 `WWW-Authenticate: Bearer` header (RFC 7235 §3.1)
/// - 403 / 500: body 泛化 (不泄 key_id / scope / 内部 bug 信息), audit log 已含细节
/// - 429: 保留 reason (client 需 backoff 决策)
/// - 404: 保留 reason (REST 专属, unknown route 用)
pub struct RestAdapter;

impl futu_auth_pipeline::SurfaceAdapter for RestAdapter {
    type WireResponse = Response;

    fn surface_id() -> futu_auth_pipeline::SurfaceId {
        futu_auth_pipeline::SurfaceId::Rest
    }

    fn translate_reject(
        kind: futu_auth_pipeline::RejectKind,
        reason: String,
    ) -> Self::WireResponse {
        use futu_auth_pipeline::RejectKind;
        match kind {
            RejectKind::Unauthenticated => (
                StatusCode::UNAUTHORIZED,
                [("www-authenticate", "Bearer realm=\"futu-rest\"")],
                Json(serde_json::json!({ "error": reason })),
            )
                .into_response(),
            RejectKind::Forbidden => {
                // BUG-011: body 泛化 "forbidden" 不泄 scope/key_id; audit log 已含细节
                let _ = reason;
                (
                    StatusCode::FORBIDDEN,
                    Json(serde_json::json!({ "error": "forbidden" })),
                )
                    .into_response()
            }
            RejectKind::RateLimited => (
                StatusCode::TOO_MANY_REQUESTS,
                Json(serde_json::json!({ "error": format!("limit check failed: {reason}") })),
            )
                .into_response(),
            RejectKind::NotFound => (
                StatusCode::NOT_FOUND,
                Json(serde_json::json!({ "error": reason })),
            )
                .into_response(),
            RejectKind::InternalError => {
                let _ = reason;
                (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    Json(serde_json::json!({ "error": "internal error" })),
                )
                    .into_response()
            }
        }
    }
}

fn audit(path: &str, key_id: Option<&str>, result: &str, reason: &str) {
    let key_id = key_id.unwrap_or("<none>");
    if result == "reject" {
        futu_auth::audit::reject("rest", path, key_id, reason);
    } else {
        futu_auth::audit::allow("rest", path, key_id, Some(reason));
    }
}

#[cfg(test)]
mod tests;