feat: token as header

- update readme
- add tests
- add token validation

Author: mahiarirani

README.md

@@ -9,7 +9,8 @@ High-performance JSON-RPC reverse proxy written in Rust. Designed as a drop-in r
 - **Smart caching** — method-aware TTLs (immutable data cached for 1 hour, chain-tip data for configurable TTL)
 - **Request coalescing** — deduplicates identical in-flight requests to reduce upstream load
 - **Stale block detection** — backends reporting blocks far behind the best known block are marked degraded
-- **URL path token auth** — optional token as URL path (like GetBlock) so clients that can only provide a URL (e.g. Bee) can authenticate
+- **URL path token auth** — optional token as URL path so clients that can only provide a URL (e.g. Bee) can authenticate
+- **Bearer token auth** — standard `Authorization: Bearer <token>` header support
 - **Batch JSON-RPC** — full support for batched requests
 - **Verbose mode** — toggle between detailed debug logs and quiet production logging
 - **Docker ready** — multi-arch image with built-in `HEALTHCHECK`
@@ -24,7 +25,8 @@ Pre-built binaries for Linux, macOS, and Windows are attached to each [GitHub Re
 # Example: Linux amd64
 curl -LO https://github.com/MetaProvide/rpcproxy/releases/latest/download/rpcproxy-linux-amd64
 chmod +x rpcproxy-linux-amd64
-./rpcproxy-linux-amd64 --targets https://rpc.gnosis.gateway.fm --verbose
+mv rpcproxy-linux-amd64 rpcproxy
+./rpcproxy --targets https://rpc.gnosis.gateway.fm --verbose
 ```
 
 ### Docker
@@ -94,27 +96,24 @@ services:
 
 | Endpoint | Method | Auth | Description |
 |----------|--------|------|-------------|
-| `POST /` | POST | No | JSON-RPC proxy when no token is set |
-| `POST /<token>` | POST | Yes | JSON-RPC proxy when `--token` is set |
+| `POST /` | POST | Bearer | JSON-RPC proxy when `--token` is set |
+| `POST /<token>` | POST | Path | JSON-RPC proxy when `--token` is set |
 | `/health` | GET | No | Returns `200 ok` if ≥1 backend has real block data, else `503` |
 | `/readiness` | GET | Bearer | JSON response with backend details and overall status |
 | `/status` | GET | Bearer | Detailed JSON: all backends, states, request counts, cache stats |
 
 ### Authentication
 
-When `--token` is set, the token becomes a **URL path segment**. This design lets
-clients that can only provide a URL (like Bee nodes) authenticate without custom headers,
-similar to how [GetBlock](https://getblock.io) works:
+When `--token` is set, RPC requests can authenticate in two ways:
 
-```text
-# No token set → open access
-curl -X POST http://localhost:9000 -d '{...}'
-
-# Token set → must use path
+**1. URL Path Token**
+```bash
 curl -X POST http://localhost:9000/my-secret-token -d '{...}'
+```
 
-# Without token path → 401 Unauthorized
-curl -X POST http://localhost:9000 -d '{...}'
+**2. Bearer Header**
+```bash
+curl -X POST http://localhost:9000 -H "Authorization: Bearer my-secret-token" -d '{...}'
 ```
 
 The `/health` endpoint is **not** protected (for Docker HEALTHCHECK).

src/config.rs

@@ -32,9 +32,11 @@ pub struct Config {
     #[arg(long, env = "RPCPROXY_CACHE_MAX_SIZE", default_value = "10000")]
     pub cache_max_size: u64,
 
-    /// Bearer token for authenticating RPC requests. If set, all RPC requests
-    /// must be sent to `POST /<token>`. The `/readiness` and `/status` endpoints
-    /// require `Authorization: Bearer <token>`. The `/health` endpoint is not protected.
+    /// Token for authenticating requests. If set, RPC requests require either
+    /// the token in the URL path (`POST /<token>`) or a Bearer header
+    /// (`Authorization: Bearer <token>`). The `/readiness` and `/status` endpoints
+    /// require the Bearer header. The `/health` endpoint is not protected.
+    /// Token must contain only alphanumeric, -, _, ., or ~ characters.
     #[arg(long, env = "RPCPROXY_TOKEN")]
     pub token: Option<String>,
 
@@ -44,3 +46,20 @@ pub struct Config {
     #[arg(short, long, env = "RPCPROXY_VERBOSE", default_value = "false")]
     pub verbose: bool,
 }
+
+pub fn validate_token(token: &str) -> Result<(), String> {
+    if token.is_empty() {
+        return Err("token cannot be empty".to_string());
+    }
+    let invalid: String = token
+        .chars()
+        .filter(|c| !c.is_ascii_alphanumeric() && !matches!(c, '-' | '_' | '.' | '~'))
+        .collect();
+    if !invalid.is_empty() {
+        return Err(format!(
+            "token contains invalid characters: '{}'. Only alphanumeric, -, _, ., and ~ are allowed",
+            invalid
+        ));
+    }
+    Ok(())
+}

src/handler/rpc.rs

@@ -1,44 +1,52 @@
 use std::sync::Arc;
 
 use axum::extract::{Path, State};
-use axum::http::StatusCode;
+use axum::http::{HeaderMap, StatusCode};
 use axum::response::{IntoResponse, Json};
 use tracing::{error, warn};
 
 use crate::cache::policy as cache_policy;
 use crate::jsonrpc::{JsonRpcBody, JsonRpcRequest, JsonRpcResponse};
 
 use super::AppState;
+use super::auth::check_bearer_token;
 
 /// RPC handler for token-authenticated path: POST /<token>
 pub async fn token_rpc_handler(
     State(state): State<AppState>,
     Path(path_token): Path<String>,
+    headers: HeaderMap,
     body: String,
 ) -> impl IntoResponse {
-    if let Some(expected_token) = &state.token
-        && path_token != *expected_token
-    {
-        warn!("unauthorized RPC request (bad token path)");
-        return (
-            StatusCode::UNAUTHORIZED,
-            Json(
-                serde_json::to_value(JsonRpcResponse::error(
-                    serde_json::Value::Null,
-                    -32000,
-                    "Unauthorized",
-                ))
-                .unwrap(),
-            ),
-        );
+    if let Some(expected_token) = &state.token {
+        let path_valid = path_token == *expected_token;
+        let header_valid = check_bearer_token(&state, &headers);
+        if !path_valid && !header_valid {
+            warn!("unauthorized RPC request (bad token path and no valid bearer)");
+            return (
+                StatusCode::UNAUTHORIZED,
+                Json(
+                    serde_json::to_value(JsonRpcResponse::error(
+                        serde_json::Value::Null,
+                        -32000,
+                        "Unauthorized",
+                    ))
+                    .unwrap(),
+                ),
+            );
+        }
     }
     dispatch_rpc(&state, body).await
 }
 
 /// RPC handler for open access: POST /
-pub async fn open_rpc_handler(State(state): State<AppState>, body: String) -> impl IntoResponse {
-    if state.token.is_some() {
-        warn!("unauthorized RPC request (missing token path)");
+pub async fn open_rpc_handler(
+    State(state): State<AppState>,
+    headers: HeaderMap,
+    body: String,
+) -> impl IntoResponse {
+    if state.token.is_some() && !check_bearer_token(&state, &headers) {
+        warn!("unauthorized RPC request (missing or bad bearer token)");
         return (
             StatusCode::UNAUTHORIZED,
             Json(

src/main.rs

@@ -7,7 +7,7 @@ use clap::Parser;
 use tracing::info;
 
 use rpcproxy::cache::RpcCache;
-use rpcproxy::config::Config;
+use rpcproxy::config::{Config, validate_token};
 use rpcproxy::handler;
 use rpcproxy::handler::AppState;
 use rpcproxy::health;
@@ -17,6 +17,13 @@ use rpcproxy::upstream::UpstreamManager;
 async fn main() {
     let config = Config::parse();
 
+    if let Some(ref token) = config.token
+        && let Err(e) = validate_token(token)
+    {
+        eprintln!("error: invalid token: {e}");
+        std::process::exit(1);
+    }
+
     let log_level = if config.verbose {
         "debug,hyper=info,reqwest=info"
     } else {

tests/config.rs

@@ -1,5 +1,5 @@
 use clap::Parser;
-use rpcproxy::config::Config;
+use rpcproxy::config::{Config, validate_token};
 
 #[test]
 fn defaults() {
@@ -40,3 +40,30 @@ fn cli_overrides() {
     assert_eq!(config.cache_max_size, 50000);
     assert_eq!(config.token, Some("secret123".to_string()));
 }
+
+#[test]
+fn token_validation_accepts_valid_tokens() {
+    assert!(validate_token("simple").is_ok());
+    assert!(validate_token("with-dash").is_ok());
+    assert!(validate_token("with_underscore").is_ok());
+    assert!(validate_token("with.dot").is_ok());
+    assert!(validate_token("with~tilde").is_ok());
+    assert!(validate_token("ABC123xyz-_.~test").is_ok());
+    assert!(validate_token("1234567890").is_ok());
+}
+
+#[test]
+fn token_validation_rejects_empty() {
+    assert!(validate_token("").is_err());
+}
+
+#[test]
+fn token_validation_rejects_invalid_chars() {
+    assert!(validate_token("has space").is_err());
+    assert!(validate_token("has/slash").is_err());
+    assert!(validate_token("has?question").is_err());
+    assert!(validate_token("has#hash").is_err());
+    assert!(validate_token("has!bang").is_err());
+    assert!(validate_token("has@at").is_err());
+    assert!(validate_token("has%percent").is_err());
+}

tests/handler.rs

@@ -75,6 +75,107 @@ async fn auth_rejects_open_endpoint_when_token_set() {
     assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
 }
 
+/// Token-protected proxy accepts requests on open endpoint with valid Bearer header.
+#[tokio::test]
+async fn auth_accepts_bearer_header_on_open_endpoint() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response("0xabc")))
+        .mount(&server)
+        .await;
+
+    let app = setup(&server.uri(), Some("secret")).await;
+
+    let resp = app
+        .oneshot(
+            Request::builder()
+                .method("POST")
+                .uri("/")
+                .header("content-type", "application/json")
+                .header("authorization", "Bearer secret")
+                .body(Body::from(
+                    r#"{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}"#,
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: serde_json::Value = serde_json::from_slice(
+        &axum::body::to_bytes(resp.into_body(), usize::MAX)
+            .await
+            .unwrap(),
+    )
+    .unwrap();
+    assert_eq!(body["result"], "0xabc");
+}
+
+/// Token-protected proxy rejects open endpoint with wrong Bearer header.
+#[tokio::test]
+async fn auth_rejects_wrong_bearer_header_on_open_endpoint() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response("0x1")))
+        .mount(&server)
+        .await;
+
+    let app = setup(&server.uri(), Some("secret")).await;
+
+    let resp = app
+        .oneshot(
+            Request::builder()
+                .method("POST")
+                .uri("/")
+                .header("content-type", "application/json")
+                .header("authorization", "Bearer wrong")
+                .body(Body::from(
+                    r#"{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}"#,
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
+}
+
+/// Token-protected proxy accepts requests on token path with valid Bearer header (even if path token is wrong).
+#[tokio::test]
+async fn auth_accepts_bearer_header_on_token_path() {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(ok_response("0xdef")))
+        .mount(&server)
+        .await;
+
+    let app = setup(&server.uri(), Some("secret")).await;
+
+    let resp = app
+        .oneshot(
+            Request::builder()
+                .method("POST")
+                .uri("/wrong-token")
+                .header("content-type", "application/json")
+                .header("authorization", "Bearer secret")
+                .body(Body::from(
+                    r#"{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}"#,
+                ))
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+
+    assert_eq!(resp.status(), StatusCode::OK);
+    let body: serde_json::Value = serde_json::from_slice(
+        &axum::body::to_bytes(resp.into_body(), usize::MAX)
+            .await
+            .unwrap(),
+    )
+    .unwrap();
+    assert_eq!(body["result"], "0xdef");
+}
+
 /// Token-protected proxy rejects requests with wrong token path.
 #[tokio::test]
 async fn auth_rejects_wrong_token_path() {