test: validate adapter notification JWT auth in emulator

The adapter emulator now requires and validates the phone-ID-signed JWT (Authorization: Bearer) that the API sends with every FCM-compatible notification, mirroring the webhook JWT validation already used in integration tests.

- adapter-emulator: gateway registration now requires phone_id; notification_handler verifies the JWT (HS256, sub==phone_id, iss==api.httpsms.com) before recording/processing, rejecting invalid/missing tokens with 401.
- emulator_test.go: updated existing tests to register phone_id and send valid tokens; added negative tests for missing auth and wrong signing secret.
- helpers_test.go: setupAdapterPhone now upserts the phone before registering the gateway (so phone_id is known), and adds an assertAdapterNotificationJWT helper mirroring assertWebhookJWT.
- adapter_integration_test.go: asserts the JWT on recorded message and heartbeat notifications.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 45ed9de9-a3ad-41cf-ad32-ebec28d9771c

Author: AchoArnold

tests/adapter-emulator/control_handler.go

@@ -14,6 +14,7 @@ const maxControlBodyBytes = 1024 * 1024
 type gatewayRegistration struct {
 	PhoneNumber string `json:"phone_number"`
 	PhoneAPIKey string `json:"phone_api_key"`
+	PhoneID     string `json:"phone_id"`
 }
 
 type incomingMessageRequest struct {
@@ -39,8 +40,9 @@ func (instance *emulator) handleGatewayRegistration(writer http.ResponseWriter,
 	}
 	registration.PhoneNumber = strings.TrimSpace(registration.PhoneNumber)
 	registration.PhoneAPIKey = strings.TrimSpace(registration.PhoneAPIKey)
-	if registration.PhoneNumber == "" || registration.PhoneAPIKey == "" {
-		writeControlError(writer, http.StatusBadRequest, errors.New("phone_number and phone_api_key are required"))
+	registration.PhoneID = strings.TrimSpace(registration.PhoneID)
+	if registration.PhoneNumber == "" || registration.PhoneAPIKey == "" || registration.PhoneID == "" {
+		writeControlError(writer, http.StatusBadRequest, errors.New("phone_number, phone_api_key and phone_id are required"))
 		return
 	}
 

tests/adapter-emulator/emulator.go

@@ -9,15 +9,17 @@ import (
 type gateway struct {
 	PhoneNumber string
 	PhoneAPIKey string
+	PhoneID     string
 }
 
 type notificationRecord struct {
-	GatewayID string            `json:"gateway_id"`
-	Data      map[string]string `json:"data"`
-	MessageID string            `json:"message_id,omitempty"`
-	Kind      string            `json:"kind"`
-	Processed bool              `json:"processed"`
-	Error     string            `json:"error,omitempty"`
+	GatewayID     string            `json:"gateway_id"`
+	Data          map[string]string `json:"data"`
+	MessageID     string            `json:"message_id,omitempty"`
+	Kind          string            `json:"kind"`
+	Processed     bool              `json:"processed"`
+	Error         string            `json:"error,omitempty"`
+	Authorization string            `json:"authorization,omitempty"`
 }
 
 type emulator struct {
@@ -43,6 +45,7 @@ func (instance *emulator) registerGateway(gatewayID string, registration gateway
 	instance.gateways[gatewayID] = gateway{
 		PhoneNumber: registration.PhoneNumber,
 		PhoneAPIKey: registration.PhoneAPIKey,
+		PhoneID:     registration.PhoneID,
 	}
 }
 
@@ -59,15 +62,17 @@ func (instance *emulator) recordNotification(
 	data map[string]string,
 	kind string,
 	messageID string,
+	authorization string,
 ) *notificationRecord {
 	instance.mu.Lock()
 	defer instance.mu.Unlock()
 
 	record := &notificationRecord{
-		GatewayID: gatewayID,
-		Data:      copyStringMap(data),
-		MessageID: messageID,
-		Kind:      kind,
+		GatewayID:     gatewayID,
+		Data:          copyStringMap(data),
+		MessageID:     messageID,
+		Kind:          kind,
+		Authorization: authorization,
 	}
 	instance.records = append(instance.records, record)
 

tests/adapter-emulator/emulator_test.go

@@ -9,22 +9,29 @@ import (
 	"strings"
 	"sync"
 	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
 )
 
+const testGatewayPhoneID = "11111111-1111-1111-1111-111111111111"
+
 func TestRecordNotificationCopiesRecords(t *testing.T) {
 	t.Parallel()
 
 	instance := newEmulator("http://api.example", http.DefaultClient)
 	instance.registerGateway("gateway-1", gatewayRegistration{
 		PhoneNumber: "+18005550199",
 		PhoneAPIKey: "phone-key",
+		PhoneID:     testGatewayPhoneID,
 	})
 
 	record := instance.recordNotification(
 		"gateway-1",
 		map[string]string{"KEY_MESSAGE_ID": "message-1"},
 		"message",
 		"message-1",
+		"Bearer test-token",
 	)
 	instance.markNotificationProcessed(record)
 
@@ -90,6 +97,7 @@ func TestNotificationHandlerProcessesMessage(t *testing.T) {
 	instance.registerGateway("gateway-1", gatewayRegistration{
 		PhoneNumber: "+18005550199",
 		PhoneAPIKey: "phone-key",
+		PhoneID:     testGatewayPhoneID,
 	})
 
 	body := callbackBody(t, map[string]string{"KEY_MESSAGE_ID": "message-1"})
@@ -98,6 +106,7 @@ func TestNotificationHandlerProcessesMessage(t *testing.T) {
 		"/notifications/gateway-1",
 		bytes.NewReader(body),
 	)
+	request.Header.Set("Authorization", validNotificationToken(t, testGatewayPhoneID))
 	response := httptest.NewRecorder()
 	instance.notificationHandler().ServeHTTP(response, request)
 	if response.Code != http.StatusNoContent {
@@ -146,13 +155,15 @@ func TestNotificationHandlerStoresHeartbeat(t *testing.T) {
 	instance.registerGateway("gateway-1", gatewayRegistration{
 		PhoneNumber: "+18005550199",
 		PhoneAPIKey: "phone-key",
+		PhoneID:     testGatewayPhoneID,
 	})
 
 	request := httptest.NewRequest(
 		http.MethodPost,
 		"/notifications/gateway-1",
 		bytes.NewReader(callbackBody(t, map[string]string{"KEY_HEARTBEAT_ID": "heartbeat-1"})),
 	)
+	request.Header.Set("Authorization", validNotificationToken(t, testGatewayPhoneID))
 	response := httptest.NewRecorder()
 	instance.notificationHandler().ServeHTTP(response, request)
 	if response.Code != http.StatusNoContent {
@@ -184,13 +195,15 @@ func TestNotificationHandlerRetainsProcessingFailure(t *testing.T) {
 	instance.registerGateway("gateway-1", gatewayRegistration{
 		PhoneNumber: "+18005550199",
 		PhoneAPIKey: "phone-key",
+		PhoneID:     testGatewayPhoneID,
 	})
 
 	request := httptest.NewRequest(
 		http.MethodPost,
 		"/notifications/gateway-1",
 		bytes.NewReader(callbackBody(t, map[string]string{"KEY_MESSAGE_ID": "message-1"})),
 	)
+	request.Header.Set("Authorization", validNotificationToken(t, testGatewayPhoneID))
 	response := httptest.NewRecorder()
 	instance.notificationHandler().ServeHTTP(response, request)
 	if response.Code != http.StatusInternalServerError {
@@ -250,17 +263,20 @@ func TestNotificationHandlerProcessesRetryAfterFailure(t *testing.T) {
 	instance.registerGateway("gateway-1", gatewayRegistration{
 		PhoneNumber: "+18005550199",
 		PhoneAPIKey: "phone-key",
+		PhoneID:     testGatewayPhoneID,
 	})
 	handler := instance.notificationHandler()
 	body := callbackBody(t, map[string]string{"KEY_MESSAGE_ID": "message-1"})
 
 	firstRequest := httptest.NewRequest(http.MethodPost, "/notifications/gateway-1", bytes.NewReader(body))
+	firstRequest.Header.Set("Authorization", validNotificationToken(t, testGatewayPhoneID))
 	firstResponse := httptest.NewRecorder()
 	handler.ServeHTTP(firstResponse, firstRequest)
 	if firstResponse.Code != http.StatusInternalServerError {
 		t.Fatalf("first callback status = %d, want 500: %s", firstResponse.Code, firstResponse.Body.String())
 	}
 	secondRequest := httptest.NewRequest(http.MethodPost, "/notifications/gateway-1", bytes.NewReader(body))
+	secondRequest.Header.Set("Authorization", validNotificationToken(t, testGatewayPhoneID))
 	secondResponse := httptest.NewRecorder()
 	handler.ServeHTTP(secondResponse, secondRequest)
 	if secondResponse.Code != http.StatusNoContent {
@@ -315,6 +331,7 @@ func TestControlHandlerRegistersGatewayAndReceivesIncomingMessage(t *testing.T)
 	registration := performJSONRequest(t, handler, http.MethodPut, "/test/gateways/gateway-1", map[string]any{
 		"phone_number":  "+18005550199",
 		"phone_api_key": "phone-key",
+		"phone_id":      testGatewayPhoneID,
 	})
 	if registration.Code != http.StatusNoContent {
 		t.Fatalf("registration status = %d, want 204: %s", registration.Code, registration.Body.String())
@@ -368,18 +385,21 @@ func TestControlHandlerFiltersNotificationRecordsByMessageID(t *testing.T) {
 	instance.registerGateway("gateway-1", gatewayRegistration{
 		PhoneNumber: "+18005550199",
 		PhoneAPIKey: "phone-key",
+		PhoneID:     testGatewayPhoneID,
 	})
 	instance.recordNotification(
 		"gateway-1",
 		map[string]string{"KEY_MESSAGE_ID": "message-1"},
 		"message",
 		"message-1",
+		"Bearer test-token",
 	)
 	instance.recordNotification(
 		"gateway-1",
 		map[string]string{"KEY_MESSAGE_ID": "message-2"},
 		"message",
 		"message-2",
+		"Bearer test-token",
 	)
 
 	response := httptest.NewRecorder()
@@ -406,6 +426,76 @@ func TestControlHandlerFiltersNotificationRecordsByMessageID(t *testing.T) {
 	}
 }
 
+func TestNotificationHandlerRejectsMissingAuthorization(t *testing.T) {
+	t.Parallel()
+
+	instance := newEmulator("http://api.example", http.DefaultClient)
+	instance.registerGateway("gateway-1", gatewayRegistration{
+		PhoneNumber: "+18005550199",
+		PhoneAPIKey: "phone-key",
+		PhoneID:     testGatewayPhoneID,
+	})
+
+	request := httptest.NewRequest(
+		http.MethodPost,
+		"/notifications/gateway-1",
+		bytes.NewReader(callbackBody(t, map[string]string{"KEY_MESSAGE_ID": "message-1"})),
+	)
+	response := httptest.NewRecorder()
+	instance.notificationHandler().ServeHTTP(response, request)
+	if response.Code != http.StatusUnauthorized {
+		t.Fatalf("callback status = %d, want 401: %s", response.Code, response.Body.String())
+	}
+	if records := instance.listGatewayRecords("gateway-1"); len(records) != 0 {
+		t.Fatalf("record count = %d, want 0 for an unauthenticated request", len(records))
+	}
+}
+
+func TestNotificationHandlerRejectsTokenSignedWithWrongSecret(t *testing.T) {
+	t.Parallel()
+
+	instance := newEmulator("http://api.example", http.DefaultClient)
+	instance.registerGateway("gateway-1", gatewayRegistration{
+		PhoneNumber: "+18005550199",
+		PhoneAPIKey: "phone-key",
+		PhoneID:     testGatewayPhoneID,
+	})
+
+	request := httptest.NewRequest(
+		http.MethodPost,
+		"/notifications/gateway-1",
+		bytes.NewReader(callbackBody(t, map[string]string{"KEY_MESSAGE_ID": "message-1"})),
+	)
+	request.Header.Set("Authorization", validNotificationToken(t, "some-other-phone-id"))
+	response := httptest.NewRecorder()
+	instance.notificationHandler().ServeHTTP(response, request)
+	if response.Code != http.StatusUnauthorized {
+		t.Fatalf("callback status = %d, want 401: %s", response.Code, response.Body.String())
+	}
+	if records := instance.listGatewayRecords("gateway-1"); len(records) != 0 {
+		t.Fatalf("record count = %d, want 0 for a request signed with the wrong secret", len(records))
+	}
+}
+
+func validNotificationToken(t *testing.T, phoneID string) string {
+	t.Helper()
+
+	now := time.Now().UTC()
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.RegisteredClaims{
+		Audience:  []string{"https://adapter-emulator:9091/notifications/gateway-1"},
+		ExpiresAt: jwt.NewNumericDate(now.Add(10 * time.Minute)),
+		IssuedAt:  jwt.NewNumericDate(now),
+		Issuer:    notificationJWTIssuer,
+		NotBefore: jwt.NewNumericDate(now.Add(-10 * time.Minute)),
+		Subject:   phoneID,
+	})
+	signed, err := token.SignedString([]byte(phoneID))
+	if err != nil {
+		t.Fatalf("sign notification token: %v", err)
+	}
+	return "Bearer " + signed
+}
+
 func callbackBody(t *testing.T, data map[string]string) []byte {
 	t.Helper()
 

tests/adapter-emulator/go.mod

@@ -1,3 +1,5 @@
 module github.com/NdoleStudio/httpsms/tests/adapter-emulator
 
 go 1.25.0
+
+require github.com/golang-jwt/jwt/v5 v5.3.1

tests/adapter-emulator/go.sum

@@ -0,0 +1,2 @@
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=

tests/adapter-emulator/notification_handler.go

@@ -6,10 +6,16 @@ import (
 	"log"
 	"net/http"
 	"strings"
+
+	"github.com/golang-jwt/jwt/v5"
 )
 
 const maxCallbackBodyBytes = 1024 * 1024
 
+// notificationJWTIssuer must match the issuer the httpSMS API signs adapter notification
+// tokens with (see api/pkg/services/http_notification_sender.go).
+const notificationJWTIssuer = "api.httpsms.com"
+
 type callbackEnvelope struct {
 	Message struct {
 		Token string            `json:"token"`
@@ -31,6 +37,13 @@ func (instance *emulator) handleNotification(writer http.ResponseWriter, request
 		return
 	}
 
+	authorization := request.Header.Get("Authorization")
+	if err := verifyNotificationAuth(authorization, registeredGateway.PhoneID); err != nil {
+		log.Printf("[ADAPTER] rejected notification for gateway=%s: %v", gatewayID, err)
+		http.Error(writer, fmt.Sprintf("invalid notification token: %v", err), http.StatusUnauthorized)
+		return
+	}
+
 	request.Body = http.MaxBytesReader(writer, request.Body, maxCallbackBodyBytes)
 	var envelope callbackEnvelope
 	if err := json.NewDecoder(request.Body).Decode(&envelope); err != nil {
@@ -44,6 +57,7 @@ func (instance *emulator) handleNotification(writer http.ResponseWriter, request
 		envelope.Message.Data,
 		kind,
 		messageID,
+		authorization,
 	)
 	log.Printf(
 		"[ADAPTER] callback gateway=%s data=%v",
@@ -94,3 +108,34 @@ func notificationKind(data map[string]string) (kind string, messageID string, er
 		return "", "", fmt.Errorf("unsupported notification data")
 	}
 }
+
+// verifyNotificationAuth validates the JWT the httpSMS API signs notification requests with,
+// using the gateway's phone ID as the HMAC-SHA256 secret (see
+// api/pkg/services/http_notification_sender.go getAuthToken).
+func verifyNotificationAuth(authorization string, phoneID string) error {
+	tokenString, ok := strings.CutPrefix(authorization, "Bearer ")
+	if !ok || strings.TrimSpace(tokenString) == "" {
+		return fmt.Errorf("missing bearer token")
+	}
+
+	claims := jwt.RegisteredClaims{}
+	token, err := jwt.ParseWithClaims(tokenString, &claims, func(token *jwt.Token) (interface{}, error) {
+		if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
+			return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
+		}
+		return []byte(phoneID), nil
+	})
+	if err != nil {
+		return fmt.Errorf("parse token: %w", err)
+	}
+	if !token.Valid {
+		return fmt.Errorf("token is not valid")
+	}
+	if claims.Subject != phoneID {
+		return fmt.Errorf("subject mismatch")
+	}
+	if claims.Issuer != notificationJWTIssuer {
+		return fmt.Errorf("issuer mismatch")
+	}
+	return nil
+}

tests/adapter_integration_test.go

@@ -37,6 +37,7 @@ func TestAdapterGatewayOutgoingMessage(t *testing.T) {
 	assert.Equal(t, "message", records[0].Kind)
 	assert.True(t, records[0].Processed)
 	assert.Equal(t, messageID, records[0].Data["KEY_MESSAGE_ID"])
+	assertAdapterNotificationJWT(t, records[0], phone.PhoneID)
 }
 
 func TestAdapterGatewayIncomingMessage(t *testing.T) {
@@ -79,6 +80,7 @@ func TestAdapterGatewayHeartbeatWakeUp(t *testing.T) {
 	record := waitForAdapterHeartbeatRecord(t, phone.GatewayID, 30*time.Second)
 	assert.Equal(t, "heartbeat", record.Kind)
 	assert.NotEmpty(t, record.Data["KEY_HEARTBEAT_ID"])
+	assertAdapterNotificationJWT(t, record, phone.PhoneID)
 
 	heartbeats, response, err := newAPIClient().Heartbeats.Index(ctx, &httpsms.HeartbeatIndexParams{
 		Owner: phone.PhoneNumber,