EMV KernelX Contactless

A VS Code toolkit for TLV/APDU parsing, colored hover previews, tag dictionaries and debugging across all contactless EMV kernels.

Features

🎯 TLV Parser

Parse EMV hex data into TLV tree structure
Preview single-line or multi-line TLV parse results in editor hover without opening the side panel
Review bitfield tags in aligned hover tables with set/unset bit states
Support for single-byte and multi-byte Tags
BERTLV length encoding (short/long form)
Recursive parsing for constructed Tags (70, 77, etc.)
DOL (CDOL1, CDOL2, PDOL) parsing

TLV Hover Preview

TLV Tree View

🔍 Kernel-Specific Tag Dictionary

Supports all contactless EMV kernels with isolated tag definitions:

Kernel	Name
`paypass`	Mastercard PayPass (Kernel 2)
`paywave`	Visa payWave (Kernel 3)
`expresspay`	American Express ExpressPay (Kernel 4)
`unionpay`	China UnionPay QuickPass (Kernel 5)
`dpas`	Discover DPAS (Kernel 6)
`jspeedy`	JCB J/Speedy (Kernel 7)
`kernel8`	Kernel 8
`pure`	Pure

📊 APDU Transaction Timeline

Send APDU commands with template shortcuts
View transaction history with SW status highlighting
Mock card reader for testing

🔢 TVR/TSI Bitmask Viewer

Visual bit-by-bit analysis of TVR, TSI, AIP, CVM Results
Kernel-specific bit definitions

✅ Linter & Static Analysis

State transition validation
Tag length/type constraint checking
DOL format validation
SW compliance checking

Usage

Parse Selected Hex

Select hex text in editor (e.g., 9F0206010203040506)
Press Ctrl+Shift+E (Mac: Cmd+Shift+E) or right-click -> "EMV KernelX Contactless: Parse Selected Hex"

Parse Clipboard

Ctrl+Shift+P -> "EMV KernelX Contactless: Parse Clipboard"

Switch Kernel

Ctrl+Shift+P -> "EMV KernelX Contactless: Switch Kernel Type"

APDU Templates

Quick send common EMV commands:

PPSE: 00A4040008A0000000031010
AID: 00A4040007A0000000031010
GPO: 80A8000083
Read Record: 00B2011400

Configuration

{
  "benpay.emv.defaultKernel": "paypass",
  "benpay.emv.apduTimeout": 30000,
  "benpay.emv.cardReaderType": "mock",
  "benpay.emv.logHighlightEnabled": true
}

Installation

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

License

MIT

🧪 Testing

Running Tests

# Validate test cases
bash tests/validate-tests.sh

# Run test suite
npx ts-node tests/run-tests.ts

Test Case Format (.emvtest)

name: "Test Name"
kernel: kernel2
category: offline_approval
description: "Test description"

steps:
  - step: 1
    name: "SELECT"
    command: "00A4040007A0000000041010"
    expectedSw: "9000"

expectedResults:
  cid: "40"

verification:
  - rule: "CID valid"
    tag: "9F27"
    condition: "exists"

Test Categories

Category	Description
`offline_approval`	Offline transaction approval
`online_auth`	Online authorization
`cvm_required`	CVM required transaction
`cvm_signature`	Signature CVM
`cvm_pin`	PIN CVM
`tlv_parse`	TLV parsing
`bitfield`	Bitfield parsing

📦 Kernel Profiles

Profiles are stored in emv-profiles/ directory.

Available Kernels

Kernel	Brand	AID
kernel2_paypass	PayPass/MasterCard	A0000000041010
kernel3_paywave	payWave/Visa	A0000000031010
kernel4_expresspay	ExpressPay/Amex	A00000002501
kernel5_unionpay	UnionPay	A0000000651010
kernel6_dpas	DPAS	A0000003241010
kernel7_jspeedy	J/Speedy	A0000001523010
kernel8_emvco	EMVCo L2	A000000000
pure	Pure	A000000451

Profile Structure

version: "1.0.0"
kernel: kernel2
brand: PayPass
aid: "A0000000041010"

tags:
  - tag: "9F26"
    name: "ApplicationCryptogram"
    type: "b"
    required: true

rules:
  - id: "K2-001"
    severity: "error"
    description: "Validation rule"

config:
  contactlessLimit: 5000
  floorLimit: 10000