Verify SEP-24 callback authenticity before state updates

[Cjay-Cyber-2]

Description

Strengthen SEP-24 callback handling by verifying the callback source and authenticity requirements before changing a transaction's status. This prevents an unauthenticated or replayed callback from marking an anchor transaction as completed, failed, or otherwise advancing its state.

Context & Requirements

Mergepay supports SEP-24 anchor flows and keeps anchor I/O inside src/services/*. Anchor integrations vary: some provide signed callbacks, while others require polling or a configured callback secret. The implementation must follow the repository's configured anchor protocol and must not invent trust based solely on a client-supplied transaction ID. Validate callback input with Zod, authenticate it using the configured integration mechanism, and reject stale or conflicting state transitions.

Callback processing must be idempotent and must not move a terminal transaction back to a non-terminal state. Sensitive callback values and secrets must not appear in logs or persisted audit details.

Acceptance Criteria

• Callback requests are authenticated according to the configured SEP-24 integration method before database state changes occur.
• Invalid signatures, missing authentication data, wrong anchor identity, and malformed payloads return a safe 4xx response.
• Callback transaction identifiers are scoped to the expected user, asset, anchor, and local transaction record.
• Replayed callbacks do not create duplicate state transitions or duplicate audit events.
• Terminal transaction states cannot be overwritten by stale or contradictory callbacks.
• Successful and rejected callback outcomes are covered by tests and documented for integrators.

Implementation Guidance

Find the SEP-24 routes and anchor adapters under src/services/* and inspect the Prisma transaction model and audit behavior. Keep provider-specific verification in the adapter rather than in generic route code. Use constant-time comparison for shared secrets where applicable, and validate timestamps or nonce data if the configured callback scheme provides them.

Testing & Validation

Add tests for valid callbacks, invalid authentication, wrong transaction ownership, replayed callbacks, stale status updates, and provider errors. Assert that rejected callbacks do not modify the database or emit state-change audit records. Run npm run build, npm test, and npm run lint; manually exercise a complete testnet anchor flow when credentials are available.

Submission Guidelines

Assignment is required before starting. Open one PR that includes Closes #<issue-number>, updates the API contract or integration documentation as needed, and follows the repository's security and audit conventions.

---

Wave complexity: Medium