nick-doc/08 - Operations/Payment and Trezor Verification Report.md

title, tags

title	tags
Payment and Trezor Verification Report	operations testing payments trezor

Payment and Trezor Verification Report

Date: 2026-05-24

Scope:

• Task 3 provider-neutral payment migration.
• Request Network optional 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.

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:

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:

Test Suites: 13 passed, 13 total
Tests:       64 passed, 64 total

Also run:

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 PAYMENT_ROLLBACK_PROVIDER=shkeeper.

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.