backend: SEP-12 KYC — signature verification, query optimization, error recovery, audit

[davidmaronio]

Summary

These four issues target the SEP-12 KYC Integration, which did not yet exist in the backend (only SEP-10 auth and SEP-0001 were present). This PR adds the SEP-12 KYC module and implements all four enhancements on it.

• SEP-12 module: PUT / GET / DELETE /sep12/customer routes (src/routes/sep12.js, mounted in app.js) backed by src/lib/sep12-kyc.js and a sep12_kyc_customers table (knex migration).
• [Backend] Add cryptographic signature verification to SEP-12 KYC Integration #590 — cryptographic signature verification: every KYC write must carry an Ed25519 signature from the account's own Stellar key over a canonical payload (account|memo|timestamp|sha256(fields)), verified with Keypair.verify, with a 5-minute replay window.
• [Backend] Optimize SQL queries in SEP-12 KYC Integration #591 — SQL query optimization: a single-round-trip parameterised upsert (INSERT ... ON CONFLICT (stellar_account, memo)), a unique composite index for the hot upsert/lookup path, a status index for dashboards, and column-scoped selects.
• [Backend] Enhance error recovery for SEP-12 KYC Integration #592 — error recovery: a withRecovery wrapper over the existing queryWithRetry, surfacing exhausted transient failures as a retryable 503 and everything else as a non-leaky 500 with structured KycError codes.
• [Backend] Conduct security audit on SEP-12 KYC Integration #593 — security audit: backend/SEP12_KYC_SECURITY_AUDIT.md documents the threat model (auth, replay, SQLi, mass-assignment, PII-in-logs) and residual risks; the code enforces strict zod validation (.strict() rejects unknown keys) and never logs field values.

Test plan

• npx vitest run src/lib/sep12-kyc.test.js — 15 tests pass (valid/forged/stale/wrong-key/missing signatures, parameterised upsert shape, field validation, invalid account, status derivation, get/delete hit & miss, retryable-503 vs non-leaky-500 recovery)
• node --check on all new/modified files

Notes

• The SEP-12 routes are mounted publicly but are signature-gated per request; the audit doc recommends placing them behind the existing API rate-limit middleware in production.

Closes #590
Closes #591
Closes #592
Closes #593

[vercel]

@davidmaronio is attempting to deploy a commit to the Emmanuel's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@davidmaronio Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits