fix(server): send index sec_type for per-contract index subscriptions (#878)

The per-contract WebSocket subscribe handler built `Contract::stock(symbol)` for every non-option subscribe, even when the client sent `sec_type=INDEX`. The FPSS contract wire encoding carries a load-bearing sec_type byte, so an INDEX subscription went out as a stock-typed contract: wrong instrument, no ticks. Branch on `sec_type` so INDEX builds `Contract::index(symbol)` and everything else defaults to stock, matching the wire default for a root with no security type. The selection is extracted into `non_option_contract` with unit coverage for both the index and stock arms.

Also harden the flatfile date boundary: `validate_date` now rejects filesystem path separators, and `handle_get` / `handle_post` validate `date` before it is interpolated into the temp artefact path, so path safety no longer depends solely on a downstream format validator.

Docs: correct the server README shutdown-token description (it is a 128-bit random hex token, 32 hex chars, not a UUID) and the example banner lines, fix the matching internal comment in the router, and add an Environment variables subsection documenting the three runtime env vars with the off-by-default rate-limit framing intact.

Co-authored-by: preview <noreply@anthropic.com>

Author: userFRM

tools/server/README.md

@@ -48,6 +48,16 @@ The server starts:
 
 Every request emits one `INFO` access-log line (method, URI, status, latency) by default. The startup banner prints `thetadatadx-server v<version>`.
 
+### Environment variables
+
+These runtime knobs are read from the environment, not from CLI flags. Per-IP rate limiting is off by default (matching the terminal it replaces); setting either rate-limit variable opts in. Full descriptions live in [`docs-site/docs/server/index.md`](../../docs-site/docs/server/index.md).
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `THETADATADX_RATE_LIMIT_PER_SECOND` | off | Opt into per-IP rate limiting at this many requests per second. Setting either rate-limit variable turns the limiter on. |
+| `THETADATADX_RATE_LIMIT_BURST_SIZE` | off | Burst size for the per-IP rate limiter. If only one of the two rate-limit variables is set, the other falls back to `20` req/s / `40` burst. |
+| `THETADATADX_WS_CLIENT_CAPACITY` | `4096` | Per-client WebSocket send-buffer capacity in events. A larger buffer trades memory for more headroom before a slow consumer drops events; invalid or zero values keep the default. |
+
 ## REST API
 
 All registry endpoints are auto-generated into REST routes at startup from `ENDPOINTS`, alongside the hand-written system routes.
@@ -134,7 +144,7 @@ Send JSON commands to manage subscriptions:
 
 ## Hardening
 
-- **`POST /v3/system/shutdown`** requires a random-UUID `X-Shutdown-Token` header printed once to stderr at startup. Token is compared in constant time so response latency does not leak the secret one byte at a time; no env var or CLI flag sets it externally. A route-scoped per-IP limiter caps attempts at roughly 3 per hour.
+- **`POST /v3/system/shutdown`** requires a 128-bit random hex `X-Shutdown-Token` header (32 hex chars) printed once to stderr at startup. Token is compared in constant time so response latency does not leak the secret one byte at a time; no env var or CLI flag sets it externally. A route-scoped per-IP limiter caps attempts at roughly 3 per hour.
 - **Global per-IP rate limit on non-loopback binds** via `tower_governor::GovernorLayer` keyed on `PeerIpKeyExtractor` (peer TCP socket, **not** `X-Forwarded-For`): 20 rps burst 40, rejected as `429` with the canonical error envelope and a `Retry-After` header. Loopback binds (`127.0.0.1`, `::1` — the default) disable the general limiter: every local client shares one peer-IP bucket, so parallel local workloads would throttle each other, which the legacy terminal never did. The shutdown-route limiter stays active on every bind. The server runs without a trusted reverse proxy, so forwarded-header extractors would let an attacker cycle fake IPs.
 - **256 concurrent in-flight requests** — requests past the cap queue on the layer's semaphore (they are not rejected), then queue again on the SDK's tier-sized request semaphore that matches the upstream concurrency cap. Bursts absorb as latency, not errors; see the Concurrency Model section in `docs-site/docs/server/http.md`. Upstream capacity rejections that survive the SDK's retry budget surface as `503` + `Retry-After`, not 500. **64 KiB body limit**, **4 KiB WebSocket `Message::Text` cap**.
 - **`BoundedQuery<32>` extractor** counts `&`-delimited query-string pairs BEFORE `serde_urlencoded` runs, so a `?a=1&b=2&...` flood is rejected at parse time rather than after HashMap rehashing allocates MB+.
@@ -145,9 +155,11 @@ Send JSON commands to manage subscriptions:
 Example — initiating a graceful shutdown from the same machine:
 
 ```bash
-# Server prints this line once at startup on stderr:
-#   thetadatadx-server: X-Shutdown-Token=<UUID>
-curl -X POST -H "X-Shutdown-Token: <UUID>" http://127.0.0.1:25503/v3/system/shutdown
+# Server prints these lines once at startup on stderr (TOKEN is a
+# 128-bit random hex string, 32 hex chars):
+#   Shutdown token: <TOKEN>
+#     curl -X POST http://127.0.0.1:25503/v3/system/shutdown -H 'X-Shutdown-Token: <TOKEN>'
+curl -X POST -H "X-Shutdown-Token: <TOKEN>" http://127.0.0.1:25503/v3/system/shutdown
 ```
 
 ## Architecture

tools/server/src/flatfile_routes.rs

@@ -149,6 +149,12 @@ async fn handle_get(
         Ok(f) => f,
         Err(e) => return error_response(StatusCode::BAD_REQUEST, "bad_request", &e),
     };
+    // Validate `date` at the boundary, before it is interpolated into a
+    // temp PathBuf in `flatfile_paths`. Path safety must not depend solely
+    // on the downstream format validator rejecting non-YYYYMMDD first.
+    if let Err(e) = crate::validation::validate_date(&params.date, "date") {
+        return error_response(StatusCode::BAD_REQUEST, "bad_request", &e.message);
+    }
     serve_flatfile(state, sec_type, req_type, &params.date, format).await
 }
 
@@ -165,6 +171,12 @@ async fn handle_post(state: State<AppState>, body: axum::Json<FlatfileRequestBod
         Ok(f) => f,
         Err(e) => return error_response(StatusCode::BAD_REQUEST, "bad_request", &e),
     };
+    // Validate `date` at the boundary, before it is interpolated into a
+    // temp PathBuf in `flatfile_paths`. Path safety must not depend solely
+    // on the downstream format validator rejecting non-YYYYMMDD first.
+    if let Err(e) = crate::validation::validate_date(&body.date, "date") {
+        return error_response(StatusCode::BAD_REQUEST, "bad_request", &e.message);
+    }
     serve_flatfile(state, sec_type, req_type, &body.date, format).await
 }
 

tools/server/src/router.rs

@@ -110,9 +110,9 @@ pub(crate) const GENERAL_BURST_SIZE: u32 = 40;
 /// setter instead sets the INTERVAL between token replenishments: one
 /// token per `SHUTDOWN_REPLENISH_PERIOD`. Combined with `burst_size(3)`,
 /// a single IP can issue at most three attempts before the bucket empties
-/// and must wait one full hour for each subsequent slot. UUID-v4 entropy
-/// already makes brute-force infeasible, but this pins an upper bound on
-/// guess rate regardless of token length.
+/// and must wait one full hour for each subsequent slot. The 128-bit
+/// random hex token already makes brute-force infeasible, but this pins
+/// an upper bound on guess rate regardless of token length.
 const SHUTDOWN_REPLENISH_PERIOD: Duration = Duration::from_secs(3600);
 const SHUTDOWN_BURST_SIZE: u32 = 3;
 

tools/server/src/validation.rs

@@ -139,6 +139,29 @@ pub fn ensure_no_control_chars(value: &str, field: &'static str) -> Result<(), V
     Ok(())
 }
 
+/// Reject any string containing a filesystem path separator or a parent
+/// reference.
+///
+/// Defense-in-depth for values that are later interpolated into a
+/// filesystem path (e.g. a flatfile artefact name keyed by `date`). A
+/// well-formed date or symbol never contains `/`, `\`, or `..`; rejecting
+/// them here means path safety does not depend solely on a downstream
+/// format validator running first. Runs after the control-char check, so
+/// null bytes are already gone by the time this sees the value.
+///
+/// # Errors
+/// Returns `ValidationError::invalid_content` when `value` contains `/`,
+/// `\`, or the `..` parent reference.
+pub fn ensure_no_path_separators(value: &str, field: &'static str) -> Result<(), ValidationError> {
+    if value.contains('/') || value.contains('\\') || value.contains("..") {
+        return Err(ValidationError::invalid_content(
+            field,
+            "contains a path separator",
+        ));
+    }
+    Ok(())
+}
+
 // ---------------------------------------------------------------------------
 //  Field-specific validators
 // ---------------------------------------------------------------------------
@@ -188,13 +211,15 @@ pub fn validate_symbols_list(value: &str, field: &'static str) -> Result<(), Val
 /// `thetadatadx::validate::validate_date` / `validate_expiration`.
 ///
 /// # Errors
-/// Returns a `ValidationError` when `value` exceeds [`MAX_DATE_LEN`] or
-/// contains control characters.
+/// Returns a `ValidationError` when `value` exceeds [`MAX_DATE_LEN`],
+/// contains control characters, or contains a filesystem path separator
+/// (the date is interpolated into a flatfile artefact path downstream).
 pub fn validate_date(value: &str, field: &'static str) -> Result<(), ValidationError> {
     if value.len() > MAX_DATE_LEN {
         return Err(ValidationError::too_long(field, value.len(), MAX_DATE_LEN));
     }
     ensure_no_control_chars(value, field)?;
+    ensure_no_path_separators(value, field)?;
     Ok(())
 }
 
@@ -453,6 +478,19 @@ mod tests {
         validate_date("2026-04-20", "date").unwrap();
     }
 
+    /// A `date` interpolated into a flatfile artefact path must never carry
+    /// a path separator or a parent reference, independent of any
+    /// downstream format validator.
+    #[test]
+    fn date_rejects_path_separators() {
+        for bad in ["../etc", "a/b", "a\\b", ".."] {
+            assert!(
+                validate_date(bad, "date").is_err(),
+                "must reject path-traversal date `{bad}`"
+            );
+        }
+    }
+
     #[test]
     fn right_rejects_oversized() {
         let big = "C".repeat(MAX_RIGHT_LEN + 1);

tools/server/src/ws/subscribe.rs

@@ -345,7 +345,7 @@ pub(super) async fn handle_client_message(state: &AppState, text: &str, socket:
             .map(|&is_call| Contract::option_raw(symbol, exp, is_call, strike))
             .collect::<Vec<_>>()
     } else {
-        vec![Contract::stock(symbol)]
+        vec![non_option_contract(&sec_type, symbol)]
     };
 
     let subscriptions = match subscription_plan(&req_type, &sec_type, &contracts) {
@@ -541,6 +541,22 @@ fn parse_right_sides(raw: Option<&str>) -> Result<Vec<bool>, String> {
     })
 }
 
+/// Build the per-contract contract for a non-option subscribe.
+///
+/// The FPSS contract wire encoding carries a load-bearing sec_type: an
+/// index addresses a different instrument map than a stock of the same
+/// symbol. Branch on the client `sec_type` so an `INDEX` per-contract
+/// subscribe is encoded as an index-typed contract instead of being
+/// silently sent as a stock (wrong instrument, no ticks). Options are
+/// handled upstream; any other value defaults to stock, matching the
+/// wire default for a root with no security type.
+fn non_option_contract(sec_type: &str, symbol: &str) -> Contract {
+    match sec_type {
+        "INDEX" => Contract::index(symbol),
+        _ => Contract::stock(symbol),
+    }
+}
+
 /// Translate a validated subscribe command into the FPSS subscriptions
 /// to install (or remove).
 ///
@@ -867,6 +883,28 @@ mod tests {
         assert!(kinds_ok, "both sides subscribe the same tick kind");
     }
 
+    /// A per-contract `sec_type=INDEX` subscribe builds an index-typed
+    /// contract, not a stock. The FPSS contract wire encoding carries the
+    /// sec_type, so a stock-typed contract for an index symbol addresses
+    /// the wrong instrument and yields no ticks.
+    #[test]
+    fn non_option_index_builds_index_contract() {
+        let c = non_option_contract("INDEX", "VIX");
+        assert_eq!(c.sec_type, SecType::Index, "INDEX must map to index");
+        assert_eq!(&*c.symbol, "VIX");
+    }
+
+    /// A non-option subscribe with any other `sec_type` (or none) defaults
+    /// to stock, matching the wire default for a root with no security type.
+    #[test]
+    fn non_option_defaults_to_stock_contract() {
+        for st in ["STOCK", ""] {
+            let c = non_option_contract(st, "AAPL");
+            assert_eq!(c.sec_type, SecType::Stock, "{st:?} must map to stock");
+            assert_eq!(&*c.symbol, "AAPL");
+        }
+    }
+
     /// Unknown `req_type` values return ERROR with the accepted set —
     /// the silent-OK-without-subscribing behavior is gone.
     #[test]