@taxi/nfc-card-utils (0.1.1)

2025-09-12T15:36:27Z

Setup this registry in your project .npmrc file:

@taxi:registry=

To install the package using npm, run the following command:

npm install @taxi/nfc-card-utils@0.1.1

or add it to the package.json file:

"@taxi/nfc-card-utils": "0.1.1"

For more information on the npm registry, see the documentation.

@taxi/nfc-card-utils

Simple NFC card utilities for Node.js using nfc-pcsc, with helpers to encrypt/decrypt data and read/write from Mifare Classic cards.

Install

From the monorepo root, install deps in this package:

cd packages\nfc-card-utils
npm i

Build

npm run build

Outputs to dist/ with CJS and ESM builds and type declarations.

API

class NFCReader(options?: { logger?: boolean; defaultKey?: string; defaultKeyType?: 'A' | 'B' })
- Wraps nfc-pcsc with event emitter. Exposes reader when connected.
- Methods: authenticate(blockNumber, keyType?, key?), read(blockNumber, length, blockSize), write(blockNumber, buffer, blockSize)
generateKey(): string – returns a 32-byte key as hex (64 chars)
encryptValue(value: any, key: string): string – AES-256-CTR encrypt to hex
decryptValue(encryptedHex: string, key: string): any – decrypt from hex to object
embedKeyAndValue(encryptedHex: string, key: string): string – random64 + key + random64 + payload
extractKeyAndValue(str: string): { key: string; encryptedValue: string }
readFromCard(reader: any): Promise<any> – reads sequential data, extracts key + payload, decrypts
writeToNfc(reader: any, value: any, key?: string, keyType?: 'A' | 'B'): Promise<boolean> – encrypts, embeds key and writes across blocks
clearCard(reader: any, key?: string, keyType?: 'A' | 'B'): Promise<boolean> – zero-fills blocks

Notes

Requires a supported NFC reader and compatible cards (e.g., Mifare Classic 1K). On Windows, install vendor drivers.
Default auth key is ffffffffffff with key type A. Adjust if your cards differ.
The write/read routines skip trailer blocks (block index 3 of each sector).

Example

import { NFCReader, generateKey, encryptValue, decryptValue } from '@taxi/nfc-card-utils';

const reader = new NFCReader({ logger: true });
reader.on('reader', r => console.log('connected', r.name));
reader.on('card', async card => {
  if (!reader.reader) return;
  const ok = await reader.authenticate(4, 'A', 'ffffffffffff');
  if (!ok) return;
  const payload = await readFromCard(reader.reader);
  console.log('Card payload', payload);
});

Dependencies

ID	Version
nfc-pcsc	^0.8.1

Development Dependencies

ID	Version
@types/node	^20.19.13
rimraf	^6.0.1
tsup	^8.3.5
typescript	^5.6.3

Details

npm

2025-09-12 15:36:27 +00:00

8

MIT

latest

8.5 KiB

Assets (1)

nfc-card-utils-0.1.1.tgz 8.5 KiB

Versions (2) View all

0.1.1

2025-09-12

0.1.0