pcsc-mini •

› NodeJS PC/SC API bindings for smart card access on Linux / MacOS / Win32

Docs ↗ | | Overview | | Prerequisites | | Installation | | Usage

import * as pcsc from "pcsc-mini";
const { CardDisposition, CardMode, ReaderStatus } = pcsc;

const client = new pcsc.Client()
  .on("reader", onReader)
  .start();

function onReader(reader: pcsc.Reader) {
  reader.on("change", async status => {
    if (!status.has(ReaderStatus.PRESENT)) return;
    if (status.hasAny(ReaderStatus.MUTE, ReaderStatus.IN_USE)) return;

    const card = await reader.connect(CardMode.SHARED);
    console.log(`${await card.state()}`);

    const resTx =  await card.transmit(
      Uint8Array.of(0xca, 0xfe, 0xf0, 0x0d)
    );
    console.log(resTx);

    const codeFeatures = pcsc.controlCode(3400);
    const features = await card.control(codeFeatures);
    console.log(features);

    await card.disconnect(CardDisposition.RESET);
    client.stop();
    process.exit(0);
  });
}
Copy

Overview

pcsc-mini provides NodeJS bindings to native PC/SC (Personal Computer/Smart Card) APIs:

• pcsc-lite on Linux and MacOS^*
• winscard on Windows.

^{* MacOS has a separate implementation built on the CryptoTokenKit API.}

Supported Platforms

Pre-built binary packages are available for the following targets.

These are installed as optional dependencies of the main pcsc-mini package (e.g. @pcsc-mini/linux-x86_64-gnu).

OS	arm64	x86	x86_64
Linux ( gnu )	✅	☑️	✅
Linux ( musl )1	✅	☑️	✅
MacOS	✅	N/A	☑️
Windows2	☑️	⬜️	✅

_{✅ Tested & verified  •  ☑️ Not tested  •  ⬜️ Not available}

_{1 During testing on Alpine, the PCSC server daemon needed to be started after a reader was connected for detection/monitoring to work and required a restart whenever a reader was disconnected and reconnected.}

_{2 Windows support is limited to a few JS runtimes at the moment (Node.js, Bun, Electron). If additional runtimes are needed, please feel free to open an issue to request it.}

JS Runtime Compatibility

Runtime	Supported Versions
NodeJS	v16.x.x, v18.x.x, v20.x.x, v22.x.x v24.x.x
OTHERS:
Bun	Tested with v1.2.12 (may work with earlier)
Deno	Tested with v2.3.1 (may work with earlier)
Electron	v15.0.0+ (Tested up to v36.2.0)

Prerequisites

Linux - Alpine

Required packages:

• ccid
• pcsc-lite
• pcsc-lite-libs

doas apk add ccid pcsc-lite pcsc-lite-libs
Copy

To run the server daemon:

doas rc-service pcscd start
Copy

Linux - Debian/Ubuntu/etc

Required packages:

• libpcsclite1
• pcscd

sudo apt install libpcsclite1 pcscd
Copy

To run the server daemon:

sudo systemctl start pcscd
Copy

MacOS/Windows

N/A :: MacOS and Windows come pre-installed with smart card support. No additional installation needed.

Installation

Bun

bun add pcsc-mini
Copy

Deno

deno add npm:pcsc-mini
Copy

npm

npm i pcsc-mini
Copy

pnpm

pnpm add pcsc-mini
Copy

Usage

import * as pcsc from "pcsc-mini";
const { CardDisposition, CardMode, ReaderStatus } = pcsc;

// The `Client` emits a "reader" event for each detected device.
const client = new pcsc.Client()
  .on("reader", onReader)
  .on("error", onError)
  .start();

function onError(err: pcsc.Err) {
  console.error("Unexpected PCSC error:", err);
  client.stop();

  // [ Log and exit / attempt `start()` retries with backoff / etc... ]
};

function onReader(reader: pcsc.Reader) {
  let card: pcsc.Card | undefined;

  console.log(`Reader detected: ${reader}`);

  // Each reader emits a "change" event on every reader state change.
  reader.on("change", async status => {
    if (status.hasAny(ReaderStatus.MUTE, ReaderStatus.IN_USE)) return;

    if (!status.has(ReaderStatus.PRESENT)) {
      void card?.disconnect(CardDisposition.RESET);
      card = undefined;
      return;
    }

    try {
      if (!card) card = await reader.connect(CardMode.SHARED);

      // Transmit Uint8Array (or NodeJS Buffer) data:
      const res = await card.transmit(
        Uint8Array.of(0xca, 0xfe, 0xf0, 0x0d)
      );

      // Use Uint8Array response directly, or via DataView/Buffer:
      const vw = new DataView(res.buffer, res.byteOffset, res.length);
      const tag = vw.getUint8(0);
      const len = vw.getUint16(2);
      const val = new Uint8Array(res.buffer, 4, len);

      // ...
    } catch (err) {
      console.error("Card error:", err);
    }
  });

  // "disconnect" is emitted when a reader is no longer detected.
  //
  // All event listeners will be removed from the now-invalid reader.
  // Any reader/card-related state should be disposed of here.
  reader.on("disconnect", async () => {
    void card?.disconnect(CardDisposition.RESET);
    card = undefined;
  });
}
Copy

Development

Prerequisites

	Minimum Version	Recommended Version
Zig	v0.15.1	See .zigversion
NodeJS	v24.0.0	See .nvmrc
pnpm	v10.0.0	See package.json
OPTIONAL:
Bun	v1.2.12
Deno	v2.3.1

Linux

See Prerequisites section above for a list of runtime prerequisites.

Other relevant development libraries (e.g. libpcsclite-dev on Debian-based distros) are included in the pcsc dependency. No additional installation needed.

MacOS

N/A :: Required MacOS Framework .tbds are included in the pcsc dependency. No additional installation needed.

Windows

N/A :: Required DLLs are shipped with the Zig compiler. No additional installation needed.

Building & Testing

Building the dev addon binary:

This will output an lib/addon.node file to enable unit testing. Runs automatically when running the unit tests.

zig build
Copy

Running Zig and NodeJS unit tests:

zig build test
Copy

Or individually:

zig build test:node -- --watch
Copy

zig build test:zig --watch
Copy

Running the E2E test application:

This enables testing basic operations against real devices (supporting up to 4 simultaneously connected readers) to verify functionality not testable via unit tests.

zig build e2e
Copy

Generating the NPM packages:

This will output the final NPM package directories to ./zig-out/npm_packages.

zig build packages
Copy

License

MIT