Applet Tooling

A CLI tool for generating EMV card personalization data. It converts a YAML specification into a series of DGI (Data Grouping Identifier) hex-encoded records suitable for loading onto a payment applet.

Prerequisites

• Node.js v24+
• npm 10+

Setup

npm install

Alternatively, install the published CLIs directly:

npm install -g @interledger/applet-personalization

This exposes ca-tools and applet-personalization on your PATH; substitute them for the npm run ca-tools --/npm run applet-personalization -- invocations used throughout this README.

You can also run the CLI without installing it, via npx. Bare npx @interledger/applet-personalization resolves to applet-personalization, the primary workflow described below:

npx @interledger/applet-personalization personalize [options]

ca-tools isn't the npx default, so invoke it explicitly with -p:

npx -p @interledger/applet-personalization ca-tools generate-keys

Usage

The applet-personalization personalize command converts a personalization YAML spec into DGI hex-encoded records.

npm run applet-personalization -- personalize [options]

Options:

| Flag | Default | Description | | ---------------------- | -------------------------------------- | ----------------------------------------------- | | --in <path> | ./personalization.yaml | Path to the personalization YAML file | | --out <path> | - (stdout) | Path where the output will be written | | --format <format> | txt | Output format: props, txt, json, or csv | | --private-key <path> | from YAML metadata.issuer.privateKey | Path to the issuer private key PEM file | | --public-cert <path> | from YAML metadata.issuer.publicCert | Path to the issuer public cert JSON file | | --debug | off | Enable debug logging to stderr |

A ready-to-use sample spec is checked in at personalization.yaml. Its metadata.issuer key/cert paths are illustrative only, so pass --private-key/--public-cert explicitly, e.g. pointing at keys generated via EMV CA & Issuer Key Generation below.

Example:

npm run applet-personalization -- personalize \
  --in ./personalization.yaml \
  --out ./tmp/personalization.properties \
  --format props \
  --private-key ./keys/issuer/private-key.pem \
  --public-cert ./keys/issuer/public-cert.json

With --format props, the output is written as a property personalization.args, containing all the DGIs as gp parameters (--store-data={data}), ready for applet personalization:

personalization.args=--store-data 0101837081805A0854133300890106405F2010494E5445524C45444745522F544553545F24032912315F25032501015F280205285F3401019F07023D009F080200019F0D05FC788400009F0E0500000000009F0F05B4788480009F420209789F4401028C159F02065F2A025F36019A039F21039F3704DFF104208E0A00000000000000000200 --store-data 01020E700C8D0A8A0295059F37049F4C04 --store-data 0201127010DFF1010C24696C702E6465762F303037 --store-data ... --store-data 7FFF00

The other formats (txt, json, csv) emit the same DGI values without the --store-data/property wrapping, one value per line, as a JSON array, or semicolon-separated, respectively.

EMV CA & Issuer Key Generation

Generates the RSA CA and issuer key pairs and EMV certificate fields used for Offline Data Authentication.

# Generate the 1984-bit CA key pair
npm run ca-tools -- generate-keys

# Generate the 1976-bit issuer key pair
npm run applet-personalization -- generate-keys

# Generate the EMV Certificate for the Issuer PK, signed by CA Private Key
# (requires the CA key pair to exist first)
npm run ca-tools -- sign-issuer-key --capk-index 01 --public-key ./keys/issuer/public-key.pem --issuer-identifier 227200FF

Output is written to keys/ (gitignored) — keys/ca/ for CA key pairs and the shared CAPK file, keys/issuer/ for issuer key pairs and certs.

Each subcommand supports additional options:

• ca-tools generate-keys: --rid, --index, --expiry-date, --keys-dir (default ./keys/ca), --public-keys-file
• ca-tools sign-issuer-key: --keys-dir (default ./keys/ca), --public-keys-file, --rid, --expiry-date, --serial-number, --output, in addition to the required --capk-index, --public-key, --issuer-identifier
• applet-personalization generate-keys: --keys-dir (default ./keys/issuer)

Development

# Run tests
npm run test

# Run tests with coverage
npm run test:cov

# Lint and format checks
npm run checks

# Auto-format
npm run format

Releasing

Versioning and publishing are handled by Changesets. When a PR changes package behavior, add a changeset describing it:

npx changeset

Merging to main triggers the release workflow, which opens (or updates) a "Version Packages" PR. Merging that PR publishes the new version to npm.