feat(api): sign HTTP adapter notifications with phone-ID JWT

[AchoArnold]

Summary

Follow-up to #989 (already merged): sign every HTTP adapter notification request with a JWT,
the same claim shape and Authorization: Bearer <token> header used for webhook requests, but
signed with the receiving phone's ID (a UUID) instead of a per-webhook signing key.

Details

• FCMClient.Send now takes the sending phone's ID; the Firebase/emulator clients ignore it,
  HTTPNotificationSender uses it to sign the request.
• Claims: sub = phone ID, aud = the adapter endpoint URL (userinfo stripped), iss =
  api.httpsms.com, 10 minute validity window, secret = phone ID string (HS256).
• Sent as Authorization: Bearer <token>, identical to webhook requests.
• Adapter endpoint URLs must not rely on HTTP basic auth credentials embedded in the URL
  (https://user:pass@host/path) since Authorization is always used for the JWT now.
• Adapters that want to verify authenticity should validate this JWT using the phone ID as the
  HMAC-SHA256 secret.

Validation

• cd api && go test ./... -count=1
• go vet ./...

[greptile-apps]

Confidence Score: 3/5

This PR is not safe to merge until HTTP notification JWTs use a secret that cannot be recovered from the token itself.

Findings

1.   JWT signing key is exposed ▶

Summary

• Generates a ten-minute HS256 JWT containing issuer, audience, subject, and time claims.
• Adds the JWT as an Authorization: Bearer header on every HTTP delivery attempt.
• Updates Firebase, emulator, service, mock, and test call sites for the expanded client interface.
• The proposed signing key is recoverable directly from the token, undermining the intended request authentication.

Diagram

sequenceDiagram
    participant PNS as PhoneNotificationService
    participant HTTP as HTTPNotificationSender
    participant Adapter as HTTP Adapter
    PNS->>HTTP: Send(message, phone.ID)
    HTTP->>HTTP: "Build JWT (sub=phone.ID, key=phone.ID)"
    HTTP->>Adapter: POST notification + Bearer JWT
    Adapter->>Adapter: Verify HS256 using phone.ID
    Note over HTTP,Adapter: The readable subject reveals the signing key

Loading

[greptile-apps]

JWT signing key is exposed

The token uses phoneID.String() as both its readable sub claim and its HS256 signing key. Anyone who obtains a notification token can read the phone ID without verifying the token, then use it to create tokens with arbitrary claims or expiration times. An adapter therefore cannot reliably distinguish genuine httpsms notifications from forged requests. Use a separate, non-public signing secret, as the webhook signer does.

How this was verified: The phone ID is embedded in the readable subject at line 118 and the identical value is used as the HMAC key at line 120.

[AchoArnold]

Fixed in def44f1 / 7896ab5: removed the \sub\ claim entirely instead of just picking a different secret. The adapter already knows which phone ID to verify against from its own gateway registration (not from a token claim), so there's no need to embed the phone ID anywhere in the token — it's now used only as the HMAC signing secret and never appears in a readable claim.

[codacy-production]

Not up to standards ⛔

🔴 Issues 1 critical

Alerts:
⚠ 1 issue (≤ 0 issues of at least minor severity)

Results:
1 new issue

Category	Results
Security	1 critical

View in Codacy

🟢 Metrics 22 complexity · 30 duplication

Metric	Results
Complexity	22
Duplication	30

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[AchoArnold]

Updated the /tests\ integration suite to validate the new adapter-notification JWT auth:

• \ ests/adapter-emulator: gateway registration now requires \phone_id; the notification handler verifies the JWT (HS256, \sub==phone ID, \iss==\�pi.httpsms.com) before recording/processing a notification, rejecting invalid/missing tokens with 401. Added unit tests for missing auth and wrong signing secret.
• \ ests/helpers_test.go: \setupAdapterPhone\ now upserts the phone before registering the gateway (so the phone ID is known up front), and adds an \�ssertAdapterNotificationJWT\ helper mirroring the existing \�ssertWebhookJWT.
• \ ests/adapter_integration_test.go: asserts the JWT claims on recorded message and heartbeat notifications.

Note: \go build/\go vet/unit tests pass in both the \ ests\ and \ ests/adapter-emulator\ modules, but the full docker-compose E2E integration suite wasn't run in this environment — CI should rebuild the adapter-emulator image (it now depends on \golang-jwt/jwt/v5) and run the full suite to confirm.

[Copilot]

🔵 Needs a closer look

It changes security-sensitive request signing/authentication behavior for adapter notifications and should be validated by a human reviewer for correctness and compatibility.

Pull request overview

This PR updates the API’s HTTP adapter notification transport to sign every adapter notification request with a phone-ID–keyed JWT (mirroring the webhook Authorization: Bearer <token> approach), and updates the adapter emulator + integration tests to validate/consume that JWT.

Changes:

• Extend FCMClient.Send to accept a phoneID so HTTP adapter transports can sign outgoing notifications.
• Add JWT creation for HTTP adapter notification requests (issuer/subject/audience/time-window) and ensure userinfo in the endpoint URL is excluded from the JWT audience.
• Update the adapter emulator and integration tests to require and assert an Authorization bearer token on notifications.

File summaries

File	Description
tests/helpers_test.go	Adds recording/assertion support for adapter notification Authorization header JWTs; reorders adapter phone setup so phone ID is available pre-registration.
tests/adapter-emulator/notification_handler.go	Enforces JWT verification on incoming notification callbacks and records the Authorization header.
tests/adapter-emulator/go.mod	Adds github.com/golang-jwt/jwt/v5 dependency for JWT verification in the emulator.
tests/adapter-emulator/go.sum	Locks checksum entries for the new JWT dependency.
tests/adapter-emulator/emulator.go	Persists PhoneID for registered gateways and stores Authorization header in notification records.
tests/adapter-emulator/emulator_test.go	Updates tests for new gateway PhoneID and adds auth rejection test cases + token helper.
tests/adapter-emulator/control_handler.go	Extends gateway registration payload validation to require phone_id.
tests/adapter_integration_test.go	Asserts adapter notifications include a valid phone-ID–signed JWT.
api/pkg/services/phone_notification_service.go	Passes phone.ID into the transport client when sending notifications.
api/pkg/services/phone_notification_service_test.go	Verifies the mapped notification client receives the correct phoneID.
api/pkg/services/http_notification_sender.go	Generates and attaches JWT bearer token to adapter notification HTTP requests (audience strips URL userinfo).
api/pkg/services/http_notification_sender_test.go	Adds assertions around JWT presence/claims and verifies userinfo isn’t relied upon for auth.
api/pkg/services/fcm_client.go	Updates FCMClient interface signature and adjusts Firebase client implementation accordingly.
api/pkg/services/emulator_fcm_client.go	Updates emulator FCM client to accept (and ignore) the new phoneID parameter.

Review details

• Files reviewed: 13/14 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[AchoArnold]

Fixed in 7896ab5: verifyNotificationAuth now checks token.Method != jwt.SigningMethodHS256 instead of just asserting *jwt.SigningMethodHMAC, so HS384/HS512 (and any non-HMAC alg) are rejected. Added TestNotificationHandlerRejectsNonHS256SigningMethod to cover it.

[AchoArnold]

Fixed in 7896ab5: updated the doc comment - phoneID identifies the receiving/target phone (the one being notified), not the sending phone.