Add payload hash to signer JWT claims (#356)

Co-authored-by: eltitanb <[email protected]>
Co-authored-by: ltitanb <[email protected]>
Co-authored-by: Manuel Iñaki Bilbao <[email protected]>

Author: 3 people

api/signer-api.yml

@@ -10,6 +10,12 @@ paths:
   /signer/v1/get_pubkeys:
     get:
       summary: Get a list of public keys for which signatures may be requested
+      description: >
+        This endpoint requires a valid JWT Bearer token.
+        
+        The token **must include** the following claims:
+        - `exp` (integer): Expiration timestamp
+        - `module` (string): The ID of the module making the request, which must match a module ID in the Commit-Boost configuration file.
       tags:
         - Signer
       security:
@@ -61,6 +67,13 @@ paths:
   /signer/v1/request_signature/bls:
     post:
       summary: Request a signature for a 32-byte blob of data (typically a hash), signed by the BLS private key for the requested public key.
+      description: >
+        This endpoint requires a valid JWT Bearer token.
+        
+        The token **must include** the following claims:
+        - `exp` (integer): Expiration timestamp
+        - `module` (string): The ID of the module making the request, which must match a module ID in the Commit-Boost configuration file.
+        - `payload_hash` (string): The Keccak-256 hash of the JSON-encoded request body, with optional `0x` prefix. This is required to prevent JWT replay attacks.
       tags:
         - Signer
       security:
@@ -201,6 +214,13 @@ paths:
   /signer/v1/request_signature/proxy-bls:
     post:
       summary: Request a signature for a 32-byte blob of data (typically a hash), signed by the BLS private key for the requested proxy public key.
+      description: >
+        This endpoint requires a valid JWT Bearer token.
+        
+        The token **must include** the following claims:
+        - `exp` (integer): Expiration timestamp
+        - `module` (string): The ID of the module making the request, which must match a module ID in the Commit-Boost configuration file.
+        - `payload_hash` (string): The Keccak-256 hash of the JSON-encoded request body, with optional `0x` prefix. This is required to prevent JWT replay attacks.
       tags:
         - Signer
       security:
@@ -341,6 +361,13 @@ paths:
   /signer/v1/request_signature/proxy-ecdsa:
     post:
       summary: Request a signature for a 32-byte blob of data (typically a hash), signed by the ECDSA private key for the requested proxy Ethereum address.
+      description: >
+        This endpoint requires a valid JWT Bearer token.
+        
+        The token **must include** the following claims:
+        - `exp` (integer): Expiration timestamp
+        - `module` (string): The ID of the module making the request, which must match a module ID in the Commit-Boost configuration file.
+        - `payload_hash` (string): The Keccak-256 hash of the JSON-encoded request body, with optional `0x` prefix. This is required to prevent JWT replay attacks.
       tags:
         - Signer
       security:
@@ -481,6 +508,13 @@ paths:
   /signer/v1/generate_proxy_key:
     post:
       summary: Request a proxy key be generated for a specific consensus pubkey
+      description: >
+        This endpoint requires a valid JWT Bearer token.
+        
+        The token **must include** the following claims:
+        - `exp` (integer): Expiration timestamp
+        - `module` (string): The ID of the module making the request, which must match a module ID in the Commit-Boost configuration file.
+        - `payload_hash` (string): The Keccak-256 hash of the JSON-encoded request body, with optional `0x` prefix. This is required to prevent JWT replay attacks.
       tags:
         - Signer
       security:
@@ -580,20 +614,6 @@ paths:
                     type: string
                     example: "Internal error"
 
-  /status:
-    get:
-      summary: Get the status of the Signer API module
-      tags:
-        - Management
-      responses:
-        "200":
-          description: Success
-          content:
-            text/plain:
-              schema:
-                type: string
-                example: "OK"
-
 components:
   securitySchemes:
     BearerAuth:

crates/common/src/commit/client.rs

@@ -42,7 +42,7 @@ pub struct SignerClient {
 impl SignerClient {
     /// Create a new SignerClient
     pub fn new(signer_server_url: Url, jwt_secret: Jwt, module_id: ModuleId) -> eyre::Result<Self> {
-        let jwt = create_jwt(&module_id, &jwt_secret)?;
+        let jwt = create_jwt(&module_id, &jwt_secret, None)?;
 
         let mut auth_value =
             HeaderValue::from_str(&format!("Bearer {}", jwt)).wrap_err("invalid jwt")?;
@@ -67,7 +67,7 @@ impl SignerClient {
 
     fn refresh_jwt(&mut self) -> Result<(), SignerClientError> {
         if self.last_jwt_refresh.elapsed() > Duration::from_secs(SIGNER_JWT_EXPIRATION) {
-            let jwt = create_jwt(&self.module_id, &self.jwt_secret)?;
+            let jwt = create_jwt(&self.module_id, &self.jwt_secret, None)?;
 
             let mut auth_value =
                 HeaderValue::from_str(&format!("Bearer {}", jwt)).wrap_err("invalid jwt")?;
@@ -85,6 +85,16 @@ impl SignerClient {
         Ok(())
     }
 
+    fn create_jwt_for_payload<T: Serialize>(
+        &mut self,
+        payload: &T,
+    ) -> Result<Jwt, SignerClientError> {
+        let payload_vec = serde_json::to_vec(payload)?;
+        create_jwt(&self.module_id, &self.jwt_secret, Some(&payload_vec))
+            .wrap_err("failed to create JWT for payload")
+            .map_err(SignerClientError::JWTError)
+    }
+
     /// Request a list of validator pubkeys for which signatures can be
     /// requested.
     // TODO: add more docs on how proxy keys work
@@ -114,10 +124,10 @@ impl SignerClient {
         Q: Serialize,
         T: for<'de> Deserialize<'de>,
     {
-        self.refresh_jwt()?;
+        let jwt = self.create_jwt_for_payload(request)?;
 
         let url = self.url.join(route)?;
-        let res = self.client.post(url).json(&request).send().await?;
+        let res = self.client.post(url).json(&request).bearer_auth(jwt).send().await?;
 
         let status = res.status();
         let response_bytes = res.bytes().await?;
@@ -162,10 +172,10 @@ impl SignerClient {
     where
         T: ProxyId + for<'de> Deserialize<'de>,
     {
-        self.refresh_jwt()?;
+        let jwt = self.create_jwt_for_payload(request)?;
 
         let url = self.url.join(GENERATE_PROXY_KEY_PATH)?;
-        let res = self.client.post(url).json(&request).send().await?;
+        let res = self.client.post(url).json(&request).bearer_auth(jwt).send().await?;
 
         let status = res.status();
         let response_bytes = res.bytes().await?;

crates/common/src/types.rs

@@ -25,13 +25,15 @@ pub struct Jwt(pub String);
 #[derive(Debug, Serialize, Deserialize)]
 pub struct JwtClaims {
     pub exp: u64,
-    pub module: String,
+    pub module: ModuleId,
+    pub payload_hash: Option<B256>,
 }
 
 #[derive(Debug, Serialize, Deserialize)]
-pub struct JwtAdmin {
+pub struct JwtAdminClaims {
     pub exp: u64,
     pub admin: bool,
+    pub payload_hash: Option<B256>,
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]