open-standards/openpay/examples/pci-zero/README.md

pci-zero — Code-form demonstration of the PCI-zero topology

A runnable counterpart to compliance/pci-zero-architecture.md. Wires the same components — vault, orchestrator, card rail — in a single Rust process so the data-flow is auditable as one program.

What this demonstrates

The binary exercises four boundary crossings:

1. Browser → vault. collection_iframe::submit constructs a CardData from a test PAN and calls Vault::tokenize. The PAN exists in the Rust process for the duration of this call and no longer; ZeroizeOnDrop wipes the bytes when submit returns.
2. Merchant → orchestrator. merchant::Merchant::checkout accepts a VaultRef and a Money amount. The merchant module deliberately does not import op-vault; it cannot construct a CardData or a RawPan. The orchestrator routes the intent to the registered card rail.
3. Driver → vault. mock_card::PciZeroCardAcquirer::authorize is the only place in the entire program (other than collection_iframe) that holds plaintext PAN. It calls Vault::detokenize, posts to the (mock) acquirer, and immediately drops the CardData.
4. Driver → acquirer. A mock acquirer response — Settled, with the masked card number for the receipt.

The merchant code path (the merchant module) holds only VaultRef, Money, and Payment<S> typestate values. There is no RawPan import in the merchant module, no CardData value, no PAN-bearing string.

What this does NOT demonstrate

• A real network boundary. "Boundary" here is Rust module visibility. In deployment the boundary is mTLS between two processes on different hosts.
• A production cryptographic backend. The example uses op_vault::InMemoryVault, the AES-256-GCM-SIV reference implementation. Production deployments use a KMS- or HSM-backed vault per compliance/hsm-kms-guidance.md.
• Card-on-file flow. The example tokenizes with TokenizationPolicy::default() (random, reusable, no TTL). Card-on-file uses TokenizationPolicy::card_on_file(); 3DS challenge flow uses TokenizationPolicy::single_use(120).

How to run

cd /path/to/open-standards/openpay
cargo run -p pci-zero

Expected output:

=== OpenPay pci-zero topology demo ===
Boundary crossings in this run:
  [B1] browser  -> vault       (tokenize, raw PAN)
  [B2] merchant -> orchestrator (VaultRef only)
  [B3] driver   -> vault       (detokenize, scoped)
  [B4] driver   -> acquirer     (raw PAN, mock)

[B1] Customer types card into vault-served iframe.
     vault returned VaultRef = tok_v7_...

[B2] Merchant runs orchestrator with VaultRef.

[B3/B4] driver detokenized + posted to mock acquirer.
       terminal status: APPROVED
       attempts: 1
       psp_payment_id: pci-zero-card_acq_ORDER-PCI-ZERO-001
         [0] rail=Card driver=pci-zero-card outcome=Settled

=== Done. Merchant code path held VaultRef only. ===

Source layout

examples/pci-zero/
├── Cargo.toml          workspace member; depends on op-core,
│                       op-vault (in-memory), op-orchestrator,
│                       op-rails-card, op-fraud
├── README.md           this file
└── src/main.rs
    ├── mod merchant          out-of-scope code path
    ├── mod collection_iframe vault-served browser stand-in
    ├── mod mock_card         CardAcquirer that detokenizes
    └── fn main               wires the three modules together

Mapping back to the deployment topology

In-process construct	Deployment counterpart
Arc<dyn Vault>	mTLS HTTP API exposed by the vault service in the CDE segment
InMemoryVault::ephemeral	KMS- or HSM-backed vault implementation (see compliance/hsm-kms-guidance.md)
mod merchant	merchant application server in the connected-to-scope segment
mod collection_iframe	TLS-isolated iframe served from the vault's own domain
mod mock_card	real PSP driver (e.g. op-rails-card Hyperswitch impl) talking to the acquirer over TLS 1.2+