gateway/README.md

@@ -579,8 +579,8 @@ ingress.
 2. Check whether `protocol_version` is supported.
 3. Resolve `device_session_id` through `SessionCache`.
 4. Reject unknown or revoked sessions.
-5. Verify that `payload_hash` matches raw `payload_bytes`.
-6. Verify the client signature using the public key from session cache.
+5. Verify the client signature using the public key from session cache.
+6. Verify that `payload_hash` matches raw `payload_bytes`.
 7. Verify that `timestamp_ms` is inside the accepted freshness window.
 8. Verify anti-replay by checking `device_session_id + request_id`.
 9. Apply authenticated rate limit and edge policy checks.

gateway/docs/flows.md

@@ -38,8 +38,8 @@ sequenceDiagram
     Gateway->>Gateway: validate envelope + protocol_version
     Gateway->>Backend: GET /api/v1/internal/sessions/{device_session_id}
     Backend-->>Gateway: session record
-    Gateway->>Gateway: verify payload_hash
     Gateway->>Gateway: verify Ed25519 signature
+    Gateway->>Gateway: verify payload_hash
     Gateway->>Gateway: verify freshness window
     Gateway->>Replay: reserve(device_session_id, request_id, ttl)
     Replay-->>Gateway: accepted

gateway/internal/grpcapi/payload_hash.go

@@ -12,8 +12,8 @@ import (
 	"google.golang.org/grpc/status"
 )
 
-// payloadHashVerifyingService applies payload-hash verification after session
-// lookup and before any later auth or routing step runs.
+// payloadHashVerifyingService applies payload-hash verification after
+// client-signature verification and before any later auth or routing step runs.
 type payloadHashVerifyingService struct {
 	edgev1.UnimplementedGatewayServer
 

gateway/internal/grpcapi/payload_hash_integration_test.go

@@ -27,6 +27,9 @@ func TestExecuteCommandRejectsPayloadHashWithInvalidLength(t *testing.T) {
 
 	req := newValidExecuteCommandRequest()
 	req.PayloadHash = []byte("short")
+	// Signature verification now precedes the payload-hash gate, so re-sign
+	// over the tampered hash to keep the signature valid and exercise the gate.
+	req.Signature = signRequest(req.GetProtocolVersion(), req.GetDeviceSessionId(), req.GetMessageType(), req.GetTimestampMs(), req.GetRequestId(), req.GetPayloadHash())
 
 	_, err := client.ExecuteCommand(context.Background(), connect.NewRequest(req))
 	require.Error(t, err)
@@ -51,6 +54,9 @@ func TestExecuteCommandRejectsPayloadHashMismatch(t *testing.T) {
 	req := newValidExecuteCommandRequest()
 	sum := sha256.Sum256([]byte("other"))
 	req.PayloadHash = sum[:]
+	// Signature verification now precedes the payload-hash gate, so re-sign
+	// over the tampered hash to keep the signature valid and exercise the gate.
+	req.Signature = signRequest(req.GetProtocolVersion(), req.GetDeviceSessionId(), req.GetMessageType(), req.GetTimestampMs(), req.GetRequestId(), req.GetPayloadHash())
 
 	_, err := client.ExecuteCommand(context.Background(), connect.NewRequest(req))
 	require.Error(t, err)
@@ -74,6 +80,9 @@ func TestSubscribeEventsRejectsPayloadHashWithInvalidLength(t *testing.T) {
 
 	req := newValidSubscribeEventsRequest()
 	req.PayloadHash = []byte("short")
+	// Signature verification now precedes the payload-hash gate, so re-sign
+	// over the tampered hash to keep the signature valid and exercise the gate.
+	req.Signature = signRequest(req.GetProtocolVersion(), req.GetDeviceSessionId(), req.GetMessageType(), req.GetTimestampMs(), req.GetRequestId(), req.GetPayloadHash())
 
 	err := subscribeEventsError(t, context.Background(), client, req)
 	require.Error(t, err)
@@ -98,6 +107,9 @@ func TestSubscribeEventsRejectsPayloadHashMismatch(t *testing.T) {
 	req := newValidSubscribeEventsRequest()
 	sum := sha256.Sum256([]byte("other"))
 	req.PayloadHash = sum[:]
+	// Signature verification now precedes the payload-hash gate, so re-sign
+	// over the tampered hash to keep the signature valid and exercise the gate.
+	req.Signature = signRequest(req.GetProtocolVersion(), req.GetDeviceSessionId(), req.GetMessageType(), req.GetTimestampMs(), req.GetRequestId(), req.GetPayloadHash())
 
 	err := subscribeEventsError(t, context.Background(), client, req)
 	require.Error(t, err)

gateway/internal/grpcapi/server.go

@@ -128,8 +128,8 @@ func NewServer(cfg config.AuthenticatedGRPCConfig, deps ServerDependencies) *Ser
 		cfg: cfg,
 		service: newEnvelopeValidatingService(
 			newSessionLookupService(
-				newPayloadHashVerifyingService(
-					newSignatureVerifyingService(
+				newSignatureVerifyingService(
+					newPayloadHashVerifyingService(
 						newFreshnessAndReplayService(
 							newAuthenticatedRateLimitService(
 								finalService,

gateway/internal/grpcapi/signature.go

@@ -12,8 +12,8 @@ import (
 	"google.golang.org/grpc/status"
 )
 
-// signatureVerifyingService applies client-signature verification after
-// payload integrity checks and before later auth or routing steps run.
+// signatureVerifyingService applies client-signature verification after session
+// lookup and before payload-hash verification and later routing steps run.
 type signatureVerifyingService struct {
 	edgev1.UnimplementedGatewayServer