a437feb8ab
openpay/
compliance/ PCI-DSS readiness package (scope-map,
pci-zero-architecture, hsm-kms-guidance,
qsa-checklist), citing PCI-DSS v4.0.1
requirements. (#1)
examples/pci-zero/ Runnable example demonstrating a deployment
where merchant code never touches a PAN. (#1)
crates/op-core/ Tokenized<Card> typestate + NetworkToken
+ CardNetwork + Cryptogram. (#2)
crates/op-rails-card/network_token/
NetworkTokenProvider trait + VTS adapter
+ MDES adapter, with deterministic stubs
behind a 'live' feature flag. (#2)
crates/op-driver-sdk/conformance/network_token.rs
Conformance harness for third-party
NetworkTokenProvider implementations. (#2)
crates/op-cli/src/ledger/ 'openpay ledger as-of' subcommand for
bi-temporal queries. (#3)
crates/op-orchestrator/src/telemetry.rs
OpenTelemetry span emission per
Payment<S> transition with semantic-
conventions tags. (#3)
docs/observability/ Grafana dashboard JSON + wiring guide
for the bi-temporal ledger lens. (#3)
smart-byte/
smart-byte-rs/ Rust reference implementation: envelope
encode/decode (canonical CBOR + BLAKE3
content addressing), Ed25519 sign +
verify, lockstep BFT commit MVP, Iroh
transport scaffold, CLI. (#4)
spec/identity_and_key_rotation.md
Adopts KERI SAIDs + key-event log
format; explicitly does not adopt ACDC
chaining wholesale. (#5)
conformance/v1/ 21 test vectors covering canonicalisation,
SAID computation, signature verification,
lockstep commit, gossip propagation.
CI gate enforces spec/vector coupling. (#6)
eoc/
eoc-rs/ Rust + WASM reference implementation:
4-stage cascade (cache -> kv -> graph ->
neural), joule counters via RAPL / NVML /
powermetrics, CLI, wasm-bindgen surface.
18 tests pass. (#7)
eoc-bench/ Benchmark harness, MT-Bench and Router
case sets, 'joules per MT-Bench point'
metric, 'eoc-bench run | compare' CLI. (#8)
standards/sci-for-ai-submission.md
Submission proposal mapping EOC's
receipt schema to GSF SCI-for-AI. (#9)
cookbook/ HuggingFace-style cookbook (markdown +
runnable Python) demonstrating EOC's
cascade with HF AI Energy Score. (#9)
docs/bench-v0.md Reproducibility doc for eoc-bench.
Workspace state:
- openpay clippy -- -D warnings: clean across all touched crates
- smart-byte-rs cargo test --workspace + clippy: clean
- eoc-rs cargo test --workspace + clippy: clean (18 tests)
- eoc-bench cargo check --workspace + clippy + 15 tests: clean
Rust 1.95.0 edition 2024 pinned at the open-standards root via
rust-toolchain.toml; every workspace inherits.
Closes #1 #2 #3 #4 #5 #6 #7 #8 #9.
76 lines
4 KiB
Markdown
76 lines
4 KiB
Markdown
# `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 `drop`s 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
|
|
|
|
```bash
|
|
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+ |
|