futu_rest/

auth.rs

//! REST API 的 Bearer Token 鉴权
//!
//! 两种模式：
//! - **未配置 KeyStore**：只读 `/api/*` 保持 legacy 无鉴权；写交易/admin 路径
//!   仍返回 401（v1.4.86 SEC-003 Q4）
//! - **配置了 KeyStore**：所有 `/api/*` 请求必须带 `Authorization: Bearer <plaintext>`，
//!   且对应 key 必须满足 route 对应的 scope
//!
//! 路由 → scope 映射由 `futu-surface-spec` 的 `EndpointSpec` 派生，未知
//! `/api/*` path fail-closed。新增 REST route 必须先登记 EndpointSpec，
//! 这样 CLI / REST / MCP / Gateway / gRPC 的可见性和权限契约才能共用同一
//! source of truth。
//!
//! 写类交易 endpoint 在 middleware 层使用 `Scope::Trade` super-scope，
//! 允许 `trade:real` / `trade:simulate` / `trade:unlock` 进入对应 handler；
//! middleware 不为该动态 write 类提前提交 rate，handler 先依据解码后的
//! env 做精确 scope 校验，再且仅再提交一次 rate。

use std::sync::Arc;

use axum::Json;
use axum::body::Body;
use axum::extract::State;
use axum::extract::connect_info::ConnectInfo;
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（限额）
///
/// 非动态 endpoint 的 middleware scope 检查会按既有路径运行
/// `check_and_commit`。real/simulate write 因需要先解析 body 的 `trd_env`，
/// 改由 handler 在 exact scope 通过后跑同一次全局 rate/hours 闸门。
/// 精细化检查（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 仅供 `scope_satisfied_*` unit tests
/// 验证语义不变.
#[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();
    let audit_ctx = audit_context_from_request(&req);

    // ── Step 1: Legacy mode + mutating-write block (REST 专属, v1.4.86 SEC-003 Q4) ─
    if legacy_mode {
        if is_mutating_write_path(&path) {
            audit(
                &audit_ctx,
                &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 / /livez /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(
            &audit_ctx,
            &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(
            &audit_ctx,
            &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,
        // Trade write 必须先从 body 得到 exact real/simulate scope，避免错误
        // scope 的请求先消耗 rate 或先返回 429；handler 随后提交恰好一次。
        // 其他 endpoint 保持既有 middleware rate 时序。
        commit_rate: needed != Scope::Trade,
        audit_emit: true,
    };

    let rec = match futu_auth::audit::with_context(audit_ctx.clone(), || {
        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
}

fn audit_context_from_request(req: &Request<Body>) -> futu_auth::audit::AuditContext {
    let remote_addr = req
        .extensions()
        .get::<ConnectInfo<std::net::SocketAddr>>()
        .map(|ConnectInfo(addr)| addr.to_string());
    let session_id = header_str(req, "x-request-id")
        .or_else(|| header_str(req, "x-futu-session-id"))
        .map(str::to_string);
    futu_auth::audit::AuditContext::new(remote_addr.as_deref(), session_id.as_deref())
}

fn header_str<'a>(req: &'a Request<Body>, name: &str) -> Option<&'a str> {
    let value = req.headers().get(name)?.to_str().ok()?.trim();
    if value.is_empty() { None } else { Some(value) }
}

/// 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 已含细节
                drop(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 => {
                drop(reason);
                (
                    StatusCode::INTERNAL_SERVER_ERROR,
                    Json(serde_json::json!({ "error": "internal error" })),
                )
                    .into_response()
            }
        }
    }
}

fn audit(
    ctx: &futu_auth::audit::AuditContext,
    path: &str,
    key_id: Option<&str>,
    result: &str,
    reason: &str,
) {
    let key_id = key_id.unwrap_or("<none>");
    futu_auth::audit::with_context(ctx.clone(), || {
        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;