futu_rest/

strict_fields.rs

//! v1.4.93 P0-2 (BUG-002): REST unknown-field validation for strict POST routes.
//!
//! ## Problem
//!
//! REST endpoint typo fields (e.g. `xyzzy_bogus` / `begin_timme`) can otherwise
//! be silently accepted by generated proto JSON structs.
//!
//! Root cause (CLAUDE.md pitfall #30): proto-build attaches `#[serde(default)]`
//! globally to all messages -> serde silently drops unknown fields. typo doesn't
//! 400, daemon executes with default zero values, returns ret_type=0 + empty data
//! (silent-success anti-pattern, pitfall #45).
//!
//! ## Fix
//!
//! Axum middleware that intercepts request body for strict validator registry paths,
//! deserializes to typed Request struct, re-serializes to canonical JSON, and
//! recursively walks both Values to detect any keys in user input not in the
//! re-serialized typed shape. Unknown -> 400 BAD_REQUEST with explanatory hint.
//!
//! The contract source is the strict validator registry below. Regression tests
//! require all `EndpointSpec`-declared POST routes registered by REST server code
//! to appear in this registry. We intentionally keep validation in the adapter
//! layer instead of changing generated prost structs globally, because that would
//! alter every generated message's JSON acceptance semantics at once.
//!
//! ## Limitations
//!
//! - Vec/repeated fields cannot be schema-validated for inner keys when default
//!   instantiated (default Vec is empty). Top-level + first-level nested object
//!   typos (the BUG-002 case) ARE caught.
//! - Validation runs AFTER `normalize_json_keys_snake_case` /
//!   `apply_known_field_aliases` (replicated here to mimic adapter pre-processing)
//!   so camelCase/aliased names don't false-trigger.

use axum::Json;
use axum::body::Body;
use axum::extract::Request;
use axum::http::StatusCode;
use axum::middleware::Next;
use axum::response::{IntoResponse, Response};
use prost::Message;
use serde::de::DeserializeOwned;
use serde_json::Value;

use crate::adapter::{
    apply_known_field_aliases, expand_symbol_shorthand, maybe_expand_flat_trd_header,
    maybe_wrap_flat_body_as_c2s, normalize_json_keys_snake_case,
};

type StrictValidator = fn(&Value) -> Result<(), Vec<String>>;

// v1.4.104 codex round 2 F2 + P1-001 follow-up: list-style endpoints
// (security_list 主字段) 让 adapter 的 single-symbol shorthand path 生成
// c2s.security + c2s.owner orphan objects. 这些是 adapter 生成的副产品，
// 不应当按用户 typo 拒绝。
const LIST_STYLE_IGNORE: &[&str] = &["c2s.security", "c2s.owner"];

fn strict_unknown_fields_error_body(path: &str, unknown_paths: Vec<String>) -> Value {
    let message = format!(
        "REST {} rejects unknown field(s): {}. Check for typos. \
         v1.4.93 BUG-002 strict validation.",
        path,
        unknown_paths.join(", ")
    );
    serde_json::json!({
        "ret_type": -1,
        "ret_msg": message,
        "error": message,
        "unknown_fields": unknown_paths,
    })
}

fn validate_qot_sub_list_style(value: &Value) -> Result<(), Vec<String>> {
    validate_for_path_with_ignore::<futu_proto::qot_sub::Request>(value, LIST_STYLE_IGNORE)
}

fn validate_basic_qot_list_style(value: &Value) -> Result<(), Vec<String>> {
    validate_for_path_with_ignore::<futu_proto::qot_get_basic_qot::Request>(
        value,
        LIST_STYLE_IGNORE,
    )
}

fn validate_snapshot_list_style(value: &Value) -> Result<(), Vec<String>> {
    validate_for_path_with_ignore::<futu_proto::qot_get_security_snapshot::Request>(
        value,
        LIST_STYLE_IGNORE,
    )
}

fn validate_static_info_list_style(value: &Value) -> Result<(), Vec<String>> {
    validate_for_path_with_ignore::<futu_proto::qot_get_static_info::Request>(
        value,
        LIST_STYLE_IGNORE,
    )
}

pub fn validate_flow_summary_strict(user_value: &Value) -> Result<(), Vec<String>> {
    validate_for_path_with_ignore::<futu_proto::trd_flow_summary::Request>(
        user_value,
        &["c2s.begin_date", "c2s.end_date"],
    )
}

/// Return the strict unknown-field validator for a REST path.
///
/// v1.4.110 surface-spec runtime enforcement: this replaces the old parallel
/// `STRICT_PATHS` list. `is_strict_path` and the middleware now share the same
/// registry, while tests assert every `EndpointSpec` REST POST route is covered.
fn strict_validator_for_path(path: &str) -> Option<StrictValidator> {
    match path {
        // qot endpoints
        "/api/history-kline" => {
            Some(validate_for_path::<futu_proto::qot_request_history_kl::Request>)
        }
        "/api/subscribe" | "/api/unsubscribe" => Some(validate_qot_sub_list_style),
        "/api/query-subscription" => {
            Some(validate_for_path::<futu_proto::qot_get_sub_info::Request>)
        }
        "/api/quote" => Some(validate_basic_qot_list_style),
        "/api/snapshot" => Some(validate_snapshot_list_style),
        "/api/kline" => Some(validate_for_path::<futu_proto::qot_get_kl::Request>),
        "/api/orderbook" => Some(validate_for_path::<futu_proto::qot_get_order_book::Request>),
        "/api/broker" => Some(validate_for_path::<futu_proto::qot_get_broker::Request>),
        "/api/ticker" => Some(validate_for_path::<futu_proto::qot_get_ticker::Request>),
        "/api/rt" => Some(validate_for_path::<futu_proto::qot_get_rt::Request>),
        "/api/static-info" => Some(validate_static_info_list_style),
        "/api/plate-set" | "/api/list-plates" => {
            Some(validate_for_path::<futu_proto::qot_get_plate_set::Request>)
        }
        "/api/plate-security" => {
            Some(validate_for_path::<futu_proto::qot_get_plate_security::Request>)
        }
        "/api/reference" | "/api/get-reference" => {
            Some(validate_for_path::<futu_proto::qot_get_reference::Request>)
        }
        "/api/owner-plate" => Some(validate_for_path::<futu_proto::qot_get_owner_plate::Request>),
        "/api/option-chain" => Some(validate_for_path::<futu_proto::qot_get_option_chain::Request>),
        "/api/warrant" => Some(validate_for_path::<futu_proto::qot_get_warrant::Request>),
        "/api/capital-flow" => Some(validate_for_path::<futu_proto::qot_get_capital_flow::Request>),
        "/api/capital-distribution" => {
            Some(validate_for_path::<futu_proto::qot_get_capital_distribution::Request>)
        }
        "/api/user-security" => {
            Some(validate_for_path::<futu_proto::qot_get_user_security::Request>)
        }
        "/api/stock-filter" => Some(validate_for_path::<futu_proto::qot_stock_filter::Request>),
        "/api/ipo-list" => Some(validate_for_path::<futu_proto::qot_get_ipo_list::Request>),
        "/api/future-info" => Some(validate_for_path::<futu_proto::qot_get_future_info::Request>),
        "/api/market-state" => Some(validate_for_path::<futu_proto::qot_get_market_state::Request>),
        "/api/trading-days" => {
            Some(validate_for_path::<futu_proto::qot_request_trade_date::Request>)
        }
        "/api/rehab" => Some(validate_for_path::<futu_proto::qot_request_rehab::Request>),
        "/api/suspend" => Some(validate_for_path::<futu_proto::qot_get_suspend::Request>),
        "/api/history-kl-quota" => {
            Some(validate_for_path::<futu_proto::qot_request_history_kl_quota::Request>)
        }
        "/api/used-quota" => Some(validate_for_path::<futu_proto::used_quota::Request>),
        "/api/holding-change" => {
            Some(validate_for_path::<futu_proto::qot_get_holding_change_list::Request>)
        }
        "/api/modify-user-security" => {
            Some(validate_for_path::<futu_proto::qot_modify_user_security::Request>)
        }
        "/api/code-change" => Some(validate_for_path::<futu_proto::qot_get_code_change::Request>),
        "/api/set-price-reminder" => {
            Some(validate_for_path::<futu_proto::qot_set_price_reminder::Request>)
        }
        "/api/price-reminder" => {
            Some(validate_for_path::<futu_proto::qot_get_price_reminder::Request>)
        }
        "/api/option-expiration-date" => {
            Some(validate_for_path::<futu_proto::qot_get_option_expiration_date::Request>)
        }
        "/api/delay-statistics" => {
            Some(validate_for_path::<futu_proto::get_delay_statistics::Request>)
        }
        "/api/token-state" => Some(
            validate_for_path::<
                futu_backend::proto_internal::futu_token_state::DaemonGetTokenStateReq,
            >,
        ),
        "/api/risk-free-rate" => Some(
            validate_for_path::<
                futu_backend::proto_internal::risk_free_rate::DaemonGetRiskFreeRateReq,
            >,
        ),
        "/api/spread-table" => Some(
            validate_for_path::<
                futu_backend::proto_internal::spread_table_6503::DaemonGetSpreadTableReq,
            >,
        ),
        "/api/ticker-statistic" => Some(validate_ticker_statistic_strict),
        "/api/ticker-statistic-detail" => Some(validate_ticker_statistic_detail_strict),

        // trade endpoints
        "/api/funds" => Some(validate_for_path::<futu_proto::trd_get_funds::Request>),
        "/api/positions" => Some(validate_for_path::<futu_proto::trd_get_position_list::Request>),
        "/api/orders" => Some(validate_for_path::<futu_proto::trd_get_order_list::Request>),
        "/api/order-fills" => {
            Some(validate_for_path::<futu_proto::trd_get_order_fill_list::Request>)
        }
        "/api/max-trd-qtys" => Some(validate_for_path::<futu_proto::trd_get_max_trd_qtys::Request>),
        "/api/margin-ratio" => Some(validate_for_path::<futu_proto::trd_get_margin_ratio::Request>),
        "/api/order" => Some(validate_for_path::<futu_proto::trd_place_order::Request>),
        "/api/order-fee" => Some(validate_for_path::<futu_proto::trd_get_order_fee::Request>),
        "/api/history-orders" => {
            Some(validate_for_path::<futu_proto::trd_get_history_order_list::Request>)
        }
        "/api/history-order-fills" => {
            Some(validate_for_path::<futu_proto::trd_get_history_order_fill_list::Request>)
        }
        "/api/sub-acc-push" | "/api/unsub-acc-push" => {
            Some(validate_for_path::<futu_proto::trd_sub_acc_push::Request>)
        }
        "/api/modify-order" | "/api/cancel-all-order" => {
            Some(validate_for_path::<futu_proto::trd_modify_order::Request>)
        }
        "/api/unlock-trade" => Some(validate_for_path::<futu_proto::trd_unlock_trade::Request>),
        "/api/reconfirm-order" => {
            Some(validate_for_path::<futu_proto::trd_reconfirm_order::Request>)
        }
        "/api/flow-summary" | "/api/acc-cash-flow" => Some(validate_flow_summary_strict),
        "/api/cash-log" => Some(
            validate_for_path::<
                futu_backend::proto_internal::realtime_asset_log::DaemonGetCashLogReq,
            >,
        ),
        "/api/cash-detail" => Some(
            validate_for_path::<
                futu_backend::proto_internal::realtime_asset_log::DaemonGetCashDetailReq,
            >,
        ),
        "/api/biz-group" => Some(
            validate_for_path::<
                futu_backend::proto_internal::realtime_asset_log::DaemonGetBizGroupReq,
            >,
        ),
        "/api/margin-info" => Some(
            validate_for_path::<
                futu_backend::proto_internal::risk_user_account_info::DaemonGetMarginInfoReq,
            >,
        ),
        "/api/account-flag" => Some(
            validate_for_path::<futu_backend::proto_internal::account_flag::DaemonGetAccountFlagReq>,
        ),
        "/api/bond-total-asset" => Some(
            validate_for_path::<
                futu_backend::proto_internal::bond_client_view::DaemonGetBondTotalAssetReq,
            >,
        ),
        "/api/bond-single-asset" => Some(
            validate_for_path::<
                futu_backend::proto_internal::bond_client_view::DaemonGetBondSingleAssetReq,
            >,
        ),
        "/api/bond-position-list" => Some(
            validate_for_path::<
                futu_backend::proto_internal::bond_client_view::DaemonGetBondPositionListReq,
            >,
        ),
        "/api/bond-answer-state" => Some(
            validate_for_path::<
                futu_backend::proto_internal::bond_client_view::DaemonGetBondAnswerStateReq,
            >,
        ),
        "/api/bond-trade-reminder" => Some(
            validate_for_path::<
                futu_backend::proto_internal::bond_client_view::DaemonGetBondTradeReminderReq,
            >,
        ),

        // daemon-local admin POST endpoints.
        "/api/admin/shutdown" | "/api/admin/reload" => Some(validate_admin_empty_body),
        _ => None,
    }
}

/// Public test helper: returns true iff `path` is in the strict-validation list.
pub fn is_strict_path(path: &str) -> bool {
    strict_validator_for_path(path).is_some()
}

/// Body size cap for body-buffering middleware (10 MiB; same order as proto
/// max-size guard elsewhere in adapter). Larger bodies bypass strict validation
/// and fall through to handler — handler still applies its own size limits.
const MAX_BODY_BYTES: usize = 10 * 1024 * 1024;

/// Axum middleware: validate POST body against the typed Request schema for
/// strict paths. Non-strict paths and non-POST methods pass through unmodified.
pub async fn strict_field_validation_middleware(req: Request, next: Next) -> Response {
    if req.method() != axum::http::Method::POST {
        return next.run(req).await;
    }
    let path = req.uri().path().to_owned();
    let Some(validator) = strict_validator_for_path(path.as_str()) else {
        return next.run(req).await;
    };

    let (parts, body) = req.into_parts();
    let bytes = match axum::body::to_bytes(body, MAX_BODY_BYTES).await {
        Ok(b) => b,
        Err(e) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({
                    "error": format!("failed to read request body: {e}")
                })),
            )
                .into_response();
        }
    };

    // Empty body: handler will use Req::default(); no fields to validate.
    if bytes.is_empty() {
        let req = Request::from_parts(parts, Body::from(bytes));
        return next.run(req).await;
    }

    // Parse user input as Value
    let mut user_value: Value = match serde_json::from_slice(&bytes) {
        Ok(v) => v,
        Err(e) => {
            return (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({
                    "error": format!("invalid JSON body: {e}")
                })),
            )
                .into_response();
        }
    };

    // v1.4.97 codex audit fix: rename OTP aliases BEFORE strict validation.
    // Earlier v1.4.96 BUG #008 fix did the rename inside `unlock_trade`
    // handler, but `/api/unlock-trade` is in the strict validator registry so this middleware
    // runs first — it would see `otp` / `token` / `one_time_password` as
    // unknown fields against `trd_unlock_trade::Request` schema and reject
    // with 400 BEFORE the handler's rename logic can run. Apply rename
    // pre-validation so user-friendly aliases pass strict validation.
    // Handler still calls `apply_unlock_trade_otp_aliases` again (idempotent
    // — sec_otp already present so alias strip is a no-op).
    if path == "/api/unlock-trade" {
        crate::routes::trd::apply_unlock_trade_otp_aliases(&mut user_value);
    }

    let validation_err = validator(&user_value);

    if let Err(unknown_paths) = validation_err {
        return (
            StatusCode::BAD_REQUEST,
            Json(strict_unknown_fields_error_body(&path, unknown_paths)),
        )
            .into_response();
    }

    // Restore body for downstream handler
    let req = Request::from_parts(parts, Body::from(bytes));
    next.run(req).await
}

/// Validate `user_value` against the typed `Req` schema. Returns `Err(unknown_paths)`
/// if any user keys are not present after a deserialize -> reserialize roundtrip.
///
/// Mimics adapter pre-processing: `normalize_json_keys_snake_case` ->
/// `apply_known_field_aliases` -> `maybe_wrap_flat_body_as_c2s` ->
/// `maybe_expand_flat_trd_header` -> `expand_symbol_shorthand` -> from_value -> to_value.
fn validate_for_path<Req>(user_value: &Value) -> Result<(), Vec<String>>
where
    Req: Message + Default + DeserializeOwned + serde::Serialize,
{
    validate_for_path_with_ignore::<Req>(user_value, &[])
}

/// Same as `validate_for_path` but tolerates a list of dot-separated paths
/// (e.g. `["c2s.owner"]`) — these will not be flagged as unknown even if they
/// appear in `normalized` post-adapter-expansion but are absent from the typed
/// `Req` shape.
///
/// **Use case** (codex F3 fix 2026-04-27): `/api/ticker-statistic` route uses
/// codex 14th-round Finding 5 (P3, 2026-04-28 02:09): testable extracted
/// branch for `/api/ticker-statistic` strict validation. Let unit test 调
/// 真 branch 而不是手写 if/else (pitfall #54 schema-only fix).
///
/// 行为: 检查 user-supplied body 是否显式含 owner (4 path):
/// (a) flat snake_case `{"owner": ...}`
/// (b) flat PascalCase `{"Owner": ...}` (post-normalize 同 (a))
/// (c) nested snake_case `{"c2s": {"owner": ...}}`
/// (d) nested PascalCase `{"c2s": {"Owner": ...}}` (post-normalize 同 (c))
///
/// 任一命中 → loud reject `c2s.owner` / `owner`. 否 → 走 generic validator
/// 容忍 adapter expand 后注入的 `c2s.owner`.
pub fn validate_ticker_statistic_strict(user_value: &Value) -> Result<(), Vec<String>> {
    let mut normalized_for_check = user_value.clone();
    normalize_json_keys_snake_case(&mut normalized_for_check);
    let nested_owner = normalized_for_check
        .get("c2s")
        .and_then(|c| c.get("owner"))
        .is_some();
    let flat_owner = normalized_for_check.get("owner").is_some();
    if nested_owner || flat_owner {
        let path = if nested_owner { "c2s.owner" } else { "owner" };
        return Err(vec![path.to_string()]);
    }
    // adapter shorthand 注入的 owner 在 normalized 中存在 (post-
    // expand_symbol_shorthand), 但 daemon proto 没 owner field.
    // 用 ignore_paths 让 validator 不计 c2s.owner 为 unknown.
    //
    // v1.4.104 codex round 2 F2 + P1-001 follow-up: array shorthand path 也会
    // 在用户传 `c2s.symbol` 时生成 `c2s.security_list` (1-element). ticker-
    // statistic proto 没 security_list field, 同样需 ignore.
    validate_for_path_with_ignore::<
        futu_backend::proto_internal::ticker_statistic_daemon::DaemonGetTickerStatisticReq,
    >(user_value, &["c2s.owner", "c2s.security_list"])
}

/// v1.4.106 codex 0500 ζ23-redo: 同 `validate_ticker_statistic_strict` —
/// `/api/ticker-statistic-detail` 走 security shorthand 路径 (adapter
/// `expand_symbol_shorthand` 在 validator 之前展开), 同样需:
///   1. 显式 reject user-supplied `owner` (4 path: nested/flat × snake/Pascal)
///   2. 容忍 adapter 注入的 `c2s.owner` / `c2s.security_list` (proto 没此字段)
///   3. 调 generic validator 验证 strict 字段拼写 (typo guard)
pub fn validate_ticker_statistic_detail_strict(user_value: &Value) -> Result<(), Vec<String>> {
    let mut normalized_for_check = user_value.clone();
    normalize_json_keys_snake_case(&mut normalized_for_check);
    let nested_owner = normalized_for_check
        .get("c2s")
        .and_then(|c| c.get("owner"))
        .is_some();
    let flat_owner = normalized_for_check.get("owner").is_some();
    if nested_owner || flat_owner {
        let path = if nested_owner { "c2s.owner" } else { "owner" };
        return Err(vec![path.to_string()]);
    }
    validate_for_path_with_ignore::<
        futu_backend::proto_internal::ticker_statistic_daemon::DaemonGetTickerStatisticDetailReq,
    >(user_value, &["c2s.owner", "c2s.security_list"])
}

/// v1.4.106 codex 0554 F2 [P2]: admin control-plane POST endpoints
/// (`/api/admin/shutdown` + `/api/admin/reload`) 不带 proto request struct —
/// handler 完全无视 body. 但 strict middleware 必须 reject 任何 user-supplied
/// 字段, 避免 `{"force": true}` / `{"reason": "..."}` 之类 silent-accept (用户
/// 以为生效, 实际 server 完全无视).
///
/// 行为: empty body / `{}` / `null` → OK; 任何 non-empty object / array /
/// scalar → reject 列出 unknown 字段名.
///
/// 注意: middleware 顶层已对 empty bytes early-return; 本 fn 处理 `{}` 和
/// `{"foo": 1}` 区分.
pub fn validate_admin_empty_body(user_value: &Value) -> Result<(), Vec<String>> {
    match user_value {
        // `{}` / nullable → 通过
        Value::Object(map) if map.is_empty() => Ok(()),
        Value::Null => Ok(()),
        // 非空 object → 列出所有 key
        Value::Object(map) => Err(map.keys().cloned().collect()),
        // 非 object (array / scalar) → 不允许 (admin endpoint 仅接受 `{}`/empty)
        Value::Array(_) => Err(vec!["<root: array not allowed>".to_string()]),
        Value::String(_) | Value::Number(_) | Value::Bool(_) => {
            Err(vec!["<root: scalar not allowed>".to_string()])
        }
    }
}

/// adapter shorthand which injects `c2s.owner` (for endpoints like option-chain
/// that need owner). ticker-statistic schema doesn't have owner, but injected
/// owner shouldn't be flagged unknown. Caller path is responsible for rejecting
/// **explicit user-supplied** owner *before* calling this fn.
fn validate_for_path_with_ignore<Req>(
    user_value: &Value,
    ignore_paths: &[&str],
) -> Result<(), Vec<String>>
where
    Req: Message + Default + DeserializeOwned + serde::Serialize,
{
    let mut normalized = user_value.clone();
    normalize_json_keys_snake_case(&mut normalized);
    apply_known_field_aliases(&mut normalized);
    maybe_wrap_flat_body_as_c2s(&mut normalized);
    maybe_expand_flat_trd_header(&mut normalized);
    // expand_symbol_shorthand returns Result<(), String>; ignore here — if it
    // fails, downstream handler will return its own 400. We're only checking
    // unknown-field cases, not symbol shape.
    let _ = expand_symbol_shorthand(&mut normalized);

    // Try to deserialize. If deserialize fails (e.g. type mismatch), let
    // downstream handler return its own typed error — not our concern.
    let req: Req = match serde_json::from_value(normalized.clone()) {
        Ok(r) => r,
        Err(_) => return Ok(()),
    };
    let canonical = match serde_json::to_value(&req) {
        Ok(v) => v,
        Err(_) => return Ok(()),
    };

    let mut unknown = Vec::new();
    collect_unknown_field_paths(&normalized, &canonical, "", &mut unknown);
    // codex F3 fix: filter out ignore_paths (e.g. adapter-injected `c2s.owner`).
    if !ignore_paths.is_empty() {
        unknown.retain(|p| !ignore_paths.contains(&p.as_str()));
    }
    if unknown.is_empty() {
        Ok(())
    } else {
        Err(unknown)
    }
}

/// Recursively walk `orig` (user input post-normalization) vs `accepted`
/// (canonical re-serialized typed-struct value). Push any path in `orig`
/// that's missing from `accepted` to `out`.
fn collect_unknown_field_paths(
    orig: &Value,
    accepted: &Value,
    prefix: &str,
    out: &mut Vec<String>,
) {
    match (orig, accepted) {
        (Value::Object(o), Value::Object(a)) => {
            for (k, v) in o {
                let path = if prefix.is_empty() {
                    k.clone()
                } else {
                    format!("{prefix}.{k}")
                };
                match a.get(k) {
                    Some(av) => collect_unknown_field_paths(v, av, &path, out),
                    None => out.push(path),
                }
            }
        }
        (Value::Array(o_arr), Value::Array(a_arr)) => {
            // For Vec<T> typed fields, default-instantiated proto Request has
            // empty Vec -> a_arr is []. We can only validate inner keys when
            // a_arr has at least one element (rare for Request shapes).
            if let Some(a_first) = a_arr.first() {
                for (i, o_item) in o_arr.iter().enumerate() {
                    let path = format!("{prefix}[{i}]");
                    collect_unknown_field_paths(o_item, a_first, &path, out);
                }
            }
        }
        // Primitive vs anything: not a key-set check; OK.
        _ => {}
    }
}

#[cfg(test)]
mod tests;