# Phase 3 — `op-emv` Complete

**Status**: Draft v0.3
**Date**: 2026-05-17

## What shipped

A zero-allocation BER-TLV codec for EMV payment payloads. This is what the
FFI layer (`op-ffi-swift`, `op-ffi-jni`) will hand bytes from `ProximityReader`
on iOS and `IsoDep` on Android, and what `op-fraud` will walk to extract
feature vectors.

## Modules

| Module | Responsibility |
|---|---|
| `error` | Sealed `Error` enum with byte-offset reporting on every variant. |
| `tag` | `Tag` (u32-packed 1–4 byte tag), `TagClass`, 22 named EMV tag constants. |
| `stream` | `TlvIter` + `TlvRef<'a>` — zero-alloc, `no_std`-compatible streaming decoder. |
| `tree` | `Tlv` + `TlvBody` — heap-allocated tree with `find()` and `encoded_len()`. Behind `std` feature. |

## Design choices

- **Zero alloc on the hot path.** `TlvIter` borrows from the input slice and
  never allocates. The secure-element interface and on-device fraud pre-pass
  use this layer.
- **`no_std`-compatible.** Default feature is `std`; turn it off to ship into
  bare-metal contexts.
- **`#![forbid(unsafe_code)]`.** Every index is bounds-checked. Combined with
  property tests, the parser is panic-safe on arbitrary bytes — critical
  because the secure element hands us untrusted input.
- **Padding tolerated.** EMV Book 3 §B.3 permits `0x00` bytes between TLVs;
  the iterator silently skips them.
- **Error variants carry byte offsets.** Debugging a parse failure on a 1 KB
  EMV response without knowing where in the bytes it failed is miserable;
  every error variant carries the offending offset.

## Verified ground truth

| Claim | Source / verification |
|---|---|
| BER-TLV tag is 1–4 bytes | EMV Book 3, Annex B |
| Multi-byte tag indicator = lower 5 bits of first byte = `0x1F` | EMV Book 3 §B.1 |
| Tag continuation flag = bit 8 of subsequent bytes | EMV Book 3 §B.1 |
| Constructed bit = bit 6 of first tag byte | EMV Book 3 §B.1 |
| Short-form length = 0–127 in a single byte | EMV Book 3 §B.2 |
| Long-form length: `0x8N` + N value bytes, N ≤ 4 | EMV Book 3 §B.2 |
| Indefinite length (`0x80` alone) banned in EMV | EMV Book 3 §B.2 |
| FCI Template tag `6F` is constructed Application class | Independently verified via Python computation |
| DF Name `84` is primitive Context-Specific (NOT Application) | Independently verified — caught and corrected during testing |
| FCI Proprietary `A5` is constructed Context-Specific | Independently verified |
| All 22 named tag constants' wire-length classifications | Independently verified by Python script |
| Canonical FCI test vector parses correctly | Hand-decoded the 28-byte sequence; assertions match |
| Tap-to-Pay flat byte offsets (0, 9, 18, 23, 28, 33) | Independently verified by Python walk |

## Test coverage

| File | Tests | Notes |
|---|---|---|
| `tag.rs` | 16 | Tag class, P/C bit, multi-byte parsing, round-trip write/read |
| `stream.rs` | 16 | Length forms, indefinite rejection, padding, offsets, constructed children |
| `tree.rs` | 6 | Owned tree, `find`, `encoded_len`, nested parsing |
| `conformance.rs` | 9 | Real vectors: FCI template, Tap-to-Pay flat, Tap-to-Pay nested |
| `properties.rs` | 3 | `proptest`: no panics on random bytes, stream/tree agreement |
| **Total Phase 3** | **50** | |
| **Cumulative (Phases 1+2+3)** | **112** | |

## Conformance vectors

| File | Contents | Source |
|---|---|---|
| `fci_template.hex` | `6F1A840E315041592E5359532E4444463031A5088801025F2D02656E` | Canonical Payment System Environment FCI from EMV Book 1 Annex A. Selects the `1PAY.SYS.DDF01` directory; declares English language; SFI = 2. |
| `taptopay_flat.hex` | 6 standard transaction-data tags | $1.00 USD purchase, USA, 2026-05-17. Synthetic but byte-for-byte what a terminal kernel emits. |
| `taptopay_nested.hex` | Same fields wrapped in `E1` private constructed | Tests recursion. |

## Bugs caught during construction (kept for the record)

1. **`DF_NAME` class assertion was wrong.** I initially asserted
   `Tag::DF_NAME.class() == TagClass::Application`. The Python cross-check
   showed `0x84` starts with bits `10`, making it `ContextSpecific`. Fixed
   before any phase artifact shipped.

2. **Nested-find test vector was malformed.** My first draft had
   `6F 0C A5 0A ...` — but A5's declared length (10) exceeded its actual
   inner content (8 bytes). Python overrun-detection caught it. Corrected
   to `6F 0A A5 08 ...`.

Both bugs were caught because every numerical claim in the test suite is
independently verified by Python before committing to Rust. The same Python
scripts live in our verification log; they're how we keep ourselves honest
without a Rust toolchain in the sandbox.

## What is NOT yet implemented (deferred)

- **Encoder.** We can decode any EMV BER-TLV blob. Encoding from a `Tlv` tree
  back to bytes is straightforward but waits on Phase 4 (`op-rails-card`)
  because that's where we need it: producing the response payload to send
  back through the PSP for refunds and reversals.
- **EMVCo certificate validation.** Verifying the issuer-side cryptogram
  (`9F26`) requires the public-key infrastructure: schemes' root CAs, issuer
  certificates, signed static/dynamic data. That's a substantial subsystem
  with its own crate — `op-emv-crypto` — deferred to after `op-rails-card`
  is wired up.
- **Fuzz corpus.** We have property tests; a dedicated `cargo-fuzz` corpus
  with AFL-discovered crashes goes in once the encoder lands.

## Next: Phase 4 — `op-rails-card`

The PSP adapter trait plus the first concrete driver: Hyperswitch. This is
where the verified-but-deferred ISO 20022 builder bindings get wired up and
where the EMV decoder feeds real Tap-to-Pay payloads into a sandbox HTTPS
flow.