Security Architecture: Deployed Controls vs. Target Roadmap
An accurate accounting of the security, ledger integrity, and cryptographic controls currently implemented and tested in the InstaPay IPX codebase versus the infrastructure, key-management, and third-party audit controls required prior to production launch.
Important Verification Boundary
Passing payout, ledger atomicity, crash-recovery, and Shamir secret-sharing unit tests verify application-level logic and database invariants. They do not prove that hardware enclaves (AWS Nitro), FIPS 140-2 Level 3 HSMs, KMS key-rotation pipelines, mTLS service meshes, or independent penetration tests are deployed. Those items are explicitly separated below as Not Deployed (Target Production Architecture).
Implemented Application & Database Controls
Database-Enforced Ledger Idempotency & Terminal Mutual Exclusion
tests/financialIntegrityAudit.spec.ts (38/38 passing)Every journal posting runs inside an atomic SQL transaction enforced by unique indexes uq_ledger_journals_idempotency (reference_id, type) and uq_ledger_journals_terminal_ref (preventing SETTLEMENT and REFUND from both committing for the same payout). Payload mismatches on an existing idempotency key throw LEDGER_IDEMPOTENCY_CONFLICT.
src/ledger/LedgerService.ts · migrations/066_financial_integrity_hardening.sqlPre-Broadcast Intent Persistence & Crash Recovery
tests/financialIntegrityAudit.spec.ts (Tests 2, 7, 10A, 10B)Payout intent, merchant-scoped idempotency lock (merchant_id, key), and deterministic client/tx reference are persisted in EXECUTING state before any external network call. If the process crashes after broadcast, reconciliation verifies the original transaction on-chain or via sandbox API and settles or quarantines without re-broadcasting.
app/api/v1/payouts/v2/route.ts · src/reconciliation/ReconciliationEngine.tsDiscrepancy Quarantine & Operator Resolution Workflow
tests/financialIntegrityAudit.spec.ts (Tests 6, 9C, 10A, 10B)If external settlement data disagrees with expected destination, asset, or net delivered amount (after accounting for sender-paid network fees), the payout transitions to status = 'discrepancy', emits a CRITICAL_DISCREPANCY_QUARANTINE alert, and retains the transit:payout:<id> hold until an attributed operator resolves it.
src/reconciliation/ReconciliationEngine.tsTokenized Bank Counterparty Storage (Zero Plaintext DDA Numbers)
tests/beneficiaryAndSafety.spec.tsPlaintext bank account numbers are nulled/removed in the application database. Only upstream sandbox counterparty tokens (cpty_...), ABA Mod-10 validated routing numbers, and last-4 account digits are stored.
migrations/065_purge_plaintext_account_numbers.sql · lib/beneficiaryValidation.tsIn-Process Shamir Secret Sharing Library (GF(2^8))
tests/mpcAndLiquidity.spec.ts (5/5 passing)Implements mathematical 2-of-3 Shamir Secret Sharing over GF(2^8) (polynomial 0x11b, generator 3) with AES-256-GCM share encryption (using MPC_MASTER_KEY) and explicit buffer zeroization (.fill(0)) after ephemeral signing. Note: In the current prototype, share reconstruction executes in the Node.js server process, and testnet adapters also support direct environment-variable testnet seeds.
lib/crypto/mpcVault.tsAPI Key Authentication, HMAC Signing & Chained Audit Logs
tests/unit.spec.ts · tests/retention.spec.tsEnforces SHA-256 hashed merchant API keys, constant-time HMAC-SHA256 webhook/request signature checks, SHA-256 chained audit log entries, a 7-year retention lock on financial records, and a hard prototype safety lock (TESTNET_ONLY=true, MODE=prototype) blocking mainnet endpoints and live keys.
lib/auth.ts · lib/requestSigning.ts · lib/audit.ts · src/config/safetyLock.tsPlanned Infrastructure, Hardware Custody & External Audit Controls
The following controls represent our target production security architecture. None of the items below are currently provisioned in the prototype environment, and they must not be relied upon as active operational controls until formal deployment and independent audit verification are completed:
AWS Nitro Enclaves & FIPS 140-2 Level 3 HSMs
Not Deployed (Target Production Architecture)No AWS Nitro Enclave or hardware security module (HSM) is provisioned. All cryptographic signing in the prototype executes inside the standard Node.js application process.
Client-Device FIDO2/WebAuthn Passkey Shares & Offline Cold-Storage Vaults
Not Deployed (Target Production Architecture)While lib/crypto/mpcVault.ts implements 2-of-3 secret splitting in software, worker biometric hardware share provisioning and geographically distributed offline cold storage are not deployed. Wallet ownership in the prototype is checked via standard cryptographic nonce signatures.
HashiCorp Vault / AWS KMS with Automated 90-Day Hardware Key Rotation
Not Deployed (Target Production Architecture)Secrets, database credentials, and encryption keys (such as MPC_MASTER_KEY and testnet seeds) are currently supplied via runtime environment variables rather than an external KMS/Vault rotation pipeline.
Internal Service Mesh Mutual TLS (mTLS)
Not Deployed (Target Production Architecture)The prototype runs as a unified Next.js application communicating with PostgreSQL and external sandbox/testnet endpoints over standard TLS (HTTPS / WSS), not an internal microservice mesh with mTLS.
SOC 2 Type II Attestation & Independent Third-Party Penetration Tests
Not Conducted (Pre-Launch Requirement)No independent CPA SOC 2 examination or external third-party penetration test has been performed. Verification to date consists strictly of internal automated integration, concurrency, and fault-injection test suites in this repository.
Security Review & Vulnerability Reporting
To inspect our full regulatory control status or report a security issue, contact security@instapayipx.com.