Reject billing deductions that reuse a requestId with a different user, amount or endpoint instead of replaying them #1501

Summary

BillingService treats requestId as an idempotency key, but it only checks that the key exists. It never checks that the stored row matches the new request. A second deduction with the same requestId and a different user, amount, API or endpoint is answered with the first row's usageEventId and stellarTxHash, reported as alreadyProcessed: true. The caller learns another tenant's event and transaction ids and believes a charge was made that was not. This issue stores a request fingerprint and returns a typed conflict on mismatch.

Background and evidence

In src/services/billing.ts:

• Existence-only precheck. deductInternal calls this.getByRequestId(request.requestId) (about lines 547-553) and returns { ...existing, alreadyProcessed: true } for any match.
• Unscoped lookup. getByRequestId (about lines 922-947) selects id, stellar_tx_hash FROM usage_events WHERE request_id = $1, with no user, amount or endpoint predicate.
• Same pattern after the lock. runPhase1 (about lines 293-311) and the 23505 recovery path (about lines 600-622) return the existing row without comparing fields.
• Bulk does the same. deductBulkInternal and runPhase1Bulk (about lines 728-852) return existing rows for any matching request id.
• Any user can collide. src/routes/billing/deduct.ts accepts any caller-chosen requestId string, so collisions across users are trivially possible.

Scope

In scope

1. Fingerprint.
   • Add request_fingerprint CHAR(64) (migration) holding the SHA-256 of a canonical userId|apiId|endpointId|apiKeyId|amountInContractUnits. Write it in runPhase1 and runPhase1Bulk.
   • On every existing-row path, compare the fingerprint.
   • On mismatch, return a new result { success: false, conflict: true, error: 'requestId already used for a different deduction' } without exposing the existing row's ids.
2. Route mapping. src/routes/billing/deduct.ts and src/routes/billing/deduct/bulk.ts map conflict to 409 BILLING_REQUEST_ID_CONFLICT in the standard envelope. Add the code to docs/error-codes.yaml and run npm run error-codes:generate.
3. Legacy rows. Rows with a NULL fingerprint are compared on user_id (the only field reliably present) and treated as a conflict on mismatch.
4. Docs. Update docs/sdk/billing-deduct.md and the OpenAPI 409 example for /api/billing/deduct.

Out of scope

• Scoping GET /api/billing/request/:requestId (tracked separately).
• Global uniqueness on the partitioned table (a separate issue).

Design constraints

• No disclosure. A conflict response must not include the other row's usageEventId or stellarTxHash.
• Exact amounts. The canonical fingerprint uses integer contract units, so "1.0" and "1.0000000" match.
• No extra round trip. The fingerprint is selected alongside the existing columns.

Test plan

Extend src/services/billing.test.ts, src/services/billing.bulk.test.ts and src/routes/billing/deduct.test.ts.

Regression proof. Row 2 returns the other user's usageEventId on current main.

Acceptance criteria

• No existing-row return path skips the fingerprint comparison.
• Every test-plan row passes.
• npm run db:check-migrations and npm run error-codes:check pass.
• npm run lint, npm run typecheck, npm run build and npm test pass, and CI is green.
• At least 90% line coverage on the touched paths in billing.ts.

Getting started

git checkout -b fix/billing-requestid-conflict
npm ci && npx prisma generate
npm run test:unit -- src/services/billing src/routes/billing/deduct

Read first: deductInternal, runPhase1, getByRequestId and deductBulkInternal in src/services/billing.ts, and src/routes/billing/deduct.ts.

PR requirements

• Link this issue (Closes #<n>).
• Explain the canonical fingerprint format.
• Paste test output and coverage.
• Example commit: fix(billing): reject requestId reuse with a different deduction.

Priority rationale

Medium. This is a contained change in one service, but it closes a cross-tenant information leak and false-success reporting on the deduction path.