97 lines
4.9 KiB
Markdown
97 lines
4.9 KiB
Markdown
---
|
|
title: Payment and Trezor Verification Report
|
|
tags: [operations, testing, payments, trezor]
|
|
---
|
|
|
|
# Payment and Trezor Verification Report
|
|
|
|
Date: 2026-05-24
|
|
|
|
Scope:
|
|
|
|
- Task 3 provider-neutral payment migration.
|
|
- Request Network primary pay-in, webhook, and reconciliation support.
|
|
- Internal funds ledger and release/refund ledger gates.
|
|
- Optional Trezor safekeeping support.
|
|
|
|
## Optionality Verdict
|
|
|
|
Trezor safekeeping is optional by default.
|
|
|
|
```env
|
|
TREZOR_SAFEKEEPING_REQUIRED=false
|
|
```
|
|
|
|
Only the literal value `true` enforces Trezor proof during release/refund confirmation. When unset, `false`, or any other value, release/refund confirmation continues through the existing payment adapter path.
|
|
|
|
Enforcement is centralized in `backend/src/services/trezor/trezorService.ts` and called from `backend/src/services/payment/orchestration/releaseRefundService.ts`.
|
|
|
|
## Focused Verification Command
|
|
|
|
Run this command from the backend package:
|
|
|
|
```bash
|
|
npm test -- __tests__/payment-adapter-registry.test.ts __tests__/request-network-adapter.test.ts __tests__/request-network-payin.test.ts __tests__/request-network-webhook.test.ts __tests__/payment-ledger.model.test.ts __tests__/payment-ledger.service.test.ts __tests__/payment-migration.service.test.ts __tests__/payment-release-refund-orchestration.test.ts __tests__/payment-release-refund-routes.test.ts __tests__/payment-reconciliation.service.test.ts __tests__/payment-observability-redaction.test.ts __tests__/payment-observability-events.test.ts __tests__/trezor-safekeeping.service.test.ts --runInBand
|
|
```
|
|
|
|
Expected result:
|
|
|
|
```text
|
|
Test Suites: 13 passed, 13 total
|
|
Tests: 64 passed, 64 total
|
|
```
|
|
|
|
Also run:
|
|
|
|
```bash
|
|
npm run typecheck
|
|
git diff --check
|
|
```
|
|
|
|
Expected result: both pass for backend changes.
|
|
|
|
## Suite Coverage
|
|
|
|
| Suite | Test count | Verifies |
|
|
| --- | ---: | --- |
|
|
| `payment-adapter-registry.test.ts` | 8 | Provider adapter selection, rollback defaults, enabled provider flags, Request Network alias support |
|
|
| `request-network-adapter.test.ts` | 6 | Request Network payload creation, parse/map helpers, webhook signature verification, adapter HTTP wiring |
|
|
| `request-network-payin.test.ts` | 3 | Pay-in creation, pending-intent dedupe, provider-disabled rejection |
|
|
| `request-network-webhook.test.ts` | 6 | Signature validation, test webhook allowlist, duplicate delivery handling, coordinator-blocked duplicate path |
|
|
| `payment-ledger.model.test.ts` | 3 | Ledger model entry types, required fields, unique sparse idempotency index |
|
|
| `payment-ledger.service.test.ts` | 9 | Append/idempotency behavior, balance aggregation, release/refund availability, held/disputed invariant |
|
|
| `payment-migration.service.test.ts` | 3 | SHKeeper migration dry-run counts, bounded sampling, ledger backfill candidate filtering |
|
|
| `payment-release-refund-orchestration.test.ts` | 5 | Release/refund instruction flow, ledger append, partial release, rollback compatibility, Trezor proof forwarding |
|
|
| `payment-release-refund-routes.test.ts` | 2 | Release/refund route ordering and controller dispatch |
|
|
| `payment-reconciliation.service.test.ts` | 6 | Dry-run/apply reconciliation, no-op alignment, missing refs, fallback Request Network references |
|
|
| `payment-observability-redaction.test.ts` | 3 | Recursive secret redaction and immutability |
|
|
| `payment-observability-events.test.ts` | 5 | Incident control snapshots and event construction |
|
|
| `trezor-safekeeping.service.test.ts` | 5 | Deterministic xpub derivation, xpub validation, registration proof, address allocation reuse, operation signature verification |
|
|
|
|
## Known Gaps
|
|
|
|
- No live Request Network API test is included in this CI-safe suite.
|
|
- No physical Trezor/hardware-device validation is included; Trezor tests use deterministic xpub/address/signature fixtures.
|
|
- Migration tests are read/report-oriented and do not execute destructive production backfills.
|
|
- Frontend checkout still needs a separate browser/build verification once frontend dependencies are installed.
|
|
- The existing `npm run test:payment` script points at a missing `__tests__/payment-services.test.ts`; use the focused command above instead.
|
|
|
|
## Release Gate
|
|
|
|
Before enabling Request Network for a non-test cohort:
|
|
|
|
1. Run the focused verification command.
|
|
2. Run backend typecheck.
|
|
3. Test one Request Network sandbox pay-in with webhook callback.
|
|
4. Confirm reconciliation dry-run output is empty or expected.
|
|
5. Keep the Request Network rollback/support runbook current; SHKeeper is historical context, not the current primary rollback target.
|
|
|
|
Before enabling Trezor safekeeping enforcement:
|
|
|
|
1. Register an admin Trezor account through `/api/trezor/register`.
|
|
2. Confirm `/api/trezor/account` reports `registered: true`.
|
|
3. Generate and sign one `/api/trezor/operation-message`.
|
|
4. Confirm `/api/trezor/verify-operation` succeeds.
|
|
5. Set `TREZOR_SAFEKEEPING_REQUIRED=true`.
|
|
6. Confirm release/refund without Trezor proof is rejected and release/refund with proof succeeds.
|