EMV KernelX Contactless

Professional TLV/APDU toolkit for EMV contactless kernel development and testing — browse, execute, and analyze EMV contactless transaction tests across 8 payment kernels (Kernel 2-8, PURE) with a unified test proxy server.

Features

TLV / APDU Toolkit

• TLV Parser — Parse EMV hex data into TLV tree; single-line and multi-line hover previews; bitfield tags rendered as aligned set/unset bit tables; single- and multi-byte tags; BERTLV short/long form; recursive parsing for constructed tags (70, 77, …); DOL (CDOL1, CDOL2, PDOL) parsing.
• Kernel-Specific Tag Dictionary — Isolated tag definitions for all 8 contactless kernels.
• APDU Transaction Timeline — Send APDU commands with template shortcuts (PPSE / AID / GPO / Read Record); transaction history with SW status highlighting; mock card reader.
• TVR / TSI / AIP / CVM Bitmask Viewer — Visual bit-by-bit analysis with kernel-specific definitions.
• Linter & Static Analysis — State transition validation, tag length/type constraint checks, DOL format validation, SW compliance.
• AI Analysis (EMV L2 Agent) — EMV: Analyze with EMV L2 Agent runs the local L2 agent runtime for deeper diagnostic suggestions.
• In-Editor Decoders — Decode TVR / AFL in place; ATR Parser, AID Lookup, CAPK Lookup tools.

EMV L2 Kernel Testing (0.2.5)

A dedicated test workbench that talks to a local test-proxy-server:

• 6 EMV Kernels fully covered + 2 in development — Kernel 2 (Mastercard PayPass), Kernel 3 (Visa payWave), Kernel 4 (Amex ExpressPay), Kernel 5 (JCB J/Speedy), Kernel 6 (Discover DPAS), PURE. Kernel 7 (CUP/UnionPay) and Kernel 8 (EMVCo Common) have backend routes registered but their IBS adapters, test scripts, and rule packs are still under development — see docs/KERNEL_REGISTRY.md for current status.
• Three-level test tree — Kernel → Category → Test in the Kernel Tests sidebar view.
• Real-time progress — WebSocket-based execution progress streaming with per-step updates and cancellation.
• Detailed webview results — APDU exchange list, TLV decoding, and test logs in one panel.
• Test history — Last 100 executions preserved in the Test History view with full state and re-run.
• Multi-protocol backend — HTTP, Unix Domain Socket, and mDNS auto-discovery for test-proxy-server.
• Security — HMAC-SHA256 request authentication, scrypt + AES-256-GCM encrypted secret storage, environment binding.

Quick Start

1. Install the extension (see Installation).
2. Start the test proxy server:

   cd submodules/test-proxy-server
   npm install
   npm start   # listens on http://127.0.0.1:3101 by default
   

3. In VS Code, run EMV Test: Connect Test Proxy from the Command Palette. The status bar shows $(plug) EMV: Connected on success.
4. Open the Kernel Tests view in the activity bar, expand a kernel, and click the play icon next to a test case.

A 5-minute walkthrough is in docs/QUICKSTART.md.

Installation

From VSIX (recommended for development)

The latest build is checked into the repository root:

code --install-extension benpay-emv-l2-toolkit-0.2.5.vsix

From source

git clone https://github.com/nextransit/emv_vsix.git
cd emv_vsix
npm install
npm run package   # produces benpay-emv-l2-toolkit-<version>.vsix
code --install-extension benpay-emv-l2-toolkit-*.vsix

From VS Code Marketplace

Search for "EMV KernelX Contactless" in the Extensions view and install.

Configuration

All settings live under emv.kernelTest.* in VS Code Settings (Ctrl+, / Cmd+,).

Example settings.json:

{
  "emv.kernelTest.backendUrl": "http://127.0.0.1:3101",
  "emv.kernelTest.autoConnect": true,
  "emv.kernelTest.useUnixSocket": false
}

Commands

Two command palettes are registered.

EMV (TLV / APDU workbench)

• EMV: Open EMV Workbench
• EMV: Parse Selected Text as TLV
• EMV: Parse Clipboard
• EMV: Analyze APDU Log
• EMV: Analyze with EMV L2 Agent
• EMV: Show Transaction Flow
• EMV: Decode TVR In Place / Decode AFL In Place
• EMV: Open ATR Parser / Open AID Lookup / Open CAPK Lookup
• EMV: Switch Kernel
• EMV: Export Analysis Report

EMV Test (L2 kernel testing)

• EMV Test: Open Kernel Tests
• EMV Test: Connect Test Proxy
• EMV Test: Run Test / Run Category / Cancel All Tests
• EMV Test: Run Test and Show Result
• EMV Test: Show Test History / Clear Test History
• EMV Test: Refresh Tests
• EMV Test: Setup HMAC Secret
• EMV Test: Export TestSchema Script Pack
• EMV Test: Open Test Settings

Architecture

EMV KernelX is a VS Code extension wrapping a layered platform. Core analysis runs in an independent Node/TypeScript layer; the VS Code extension is the UI shell.

+-------------------------------------------------------+
|                VSCode EMV Workbench                   |
|   Commands / Editor / TreeView / Hover / Webview      |
+---------------------------+---------------------------+
                            |
+---------------------------v---------------------------+
|                Extension Adapter Layer                |
+---------------------------+---------------------------+
                            |
+---------------------------v---------------------------+
|                  L0 Core Platform                     |
|  ExecutionEngine / KernelResolver / PluginHost        |
|  ContextBuilder / LogImporter / ApduParser / TlvParser|
+------+--------------------+-------------------+-------+
       |                    |                   |
+------v------+    +--------v-------+   +-------v-------+
| Plugin Host |    | Data Pack      |   | test-proxy-   |
| (kernel-rt) |    | Runtime        |   | server (HTTP/ |
|             |    | (rule/profile) |   |  UDS / mDNS)  |
+-------------+    +----------------+   +---------------+

See docs/ARCHITECTURE.md for the full layered model, plugin isolation rules, and data/code separation guarantees.

Documentation

• User Guide — installation, configuration, daily usage.
• Quick Start — 5-minute onboarding.
• Architecture — system architecture and plugin model.
• L2 Testing — Level 2 certification integration guide.
• API — extension API reference.
• Security & Asset Rules — EMV test asset protection policy.
• Beta Testing Plan — pre-release checklist.

Reference

• .emvtest ↔ Proxy .js Bridge — explains the two-track model between VSCode .emvtest DSL and test-proxy-server .js scripts.

Development

Requires Node.js and npm (pnpm optional for the workspace packages).

npm install              # install root + workspace deps
npm run compile          # type-check + build (out/)
npm run watch            # incremental build
npm run lint             # eslint over src/
npm run test             # workspace unit tests + root tests
npm run test:e2e         # integration test suite
npm test:agent           # EMV L2 agent runtime smoke test
npm run package          # produce .vsix via vsce
npm run publish          # publish to VS Code Marketplace

TestSchema pack management (for kernel script packs):

npm run sync:testschema-packs            # pull latest packs from submodules
npm run sync:testschema-proxy-pack       # mirror proxy pack layout
npm run verify:testschema-packs          # CI-style verify bundled packs

Security

This project handles EMV payment core assets (test proxy server, kernel script packs, TestSchema data). All assets are managed as git submodules under submodules/ and must remain on private repositories — they are not part of the public extension package.

Before contributing, read docs/SECURITY_ASSET_RULES.md for submodule policy, secret handling (HMAC + scrypt/AES-256-GCM), and environment-binding requirements.

License

MIT

Privacy Policy · Terms of Service

Kernel Profiles

Kernel profiles live in emv-profiles/. Each profile declares its AID, brand, tag dictionary, validation rules, and config.