smartcard 2.0.3 → 3.1.0

package/README.md

@@ -289,11 +289,11 @@ interface Card {
     readonly protocol: number;
     readonly connected: boolean;
     readonly atr: Buffer | null;
-    transmit(command: Buffer | number[]): Promise<Buffer>;
+    transmit(command: Buffer | number[], options?: { maxRecvLength?: number }): Promise<Buffer>;
     control(code: number, data?: Buffer): Promise<Buffer>;
     getStatus(): { state: number; protocol: number; atr: Buffer };
     disconnect(disposition?: number): void;
-    reconnect(shareMode?: number, protocol?: number, init?: number): number;
+    reconnect(shareMode?: number, protocol?: number, init?: number): Promise<number>;
 }
 ```
 

package/lib/control-codes.js

@@ -0,0 +1,107 @@
+// @ts-check
+'use strict';
+
+/**
+ * Control codes and feature constants for PC/SC smart card operations
+ */
+
+/**
+ * Generate a control code (platform-specific)
+ * @param {number} code - The control code number
+ * @returns {number} The platform-specific control code
+ */
+function SCARD_CTL_CODE(code) {
+    if (process.platform === 'win32') {
+        // Windows: (FILE_DEVICE_SMARTCARD << 16) + (code << 2)
+        // FILE_DEVICE_SMARTCARD = 0x31
+        return (0x31 << 16) + (code << 2);
+    } else {
+        // macOS/Linux: 0x42000000 + code
+        return 0x42000000 + code;
+    }
+}
+
+// Common control codes
+const CM_IOCTL_GET_FEATURE_REQUEST = SCARD_CTL_CODE(3400);
+
+// CCID Feature tags (from CCID spec)
+const FEATURE_VERIFY_PIN_START = 0x01;
+const FEATURE_VERIFY_PIN_FINISH = 0x02;
+const FEATURE_MODIFY_PIN_START = 0x03;
+const FEATURE_MODIFY_PIN_FINISH = 0x04;
+const FEATURE_GET_KEY_PRESSED = 0x05;
+const FEATURE_VERIFY_PIN_DIRECT = 0x06;
+const FEATURE_MODIFY_PIN_DIRECT = 0x07;
+const FEATURE_MCT_READER_DIRECT = 0x08;
+const FEATURE_MCT_UNIVERSAL = 0x09;
+const FEATURE_IFD_PIN_PROPERTIES = 0x0A;
+const FEATURE_ABORT = 0x0B;
+const FEATURE_SET_SPE_MESSAGE = 0x0C;
+const FEATURE_VERIFY_PIN_DIRECT_APP_ID = 0x0D;
+const FEATURE_MODIFY_PIN_DIRECT_APP_ID = 0x0E;
+const FEATURE_WRITE_DISPLAY = 0x0F;
+const FEATURE_GET_KEY = 0x10;
+const FEATURE_IFD_DISPLAY_PROPERTIES = 0x11;
+const FEATURE_GET_TLV_PROPERTIES = 0x12;
+const FEATURE_CCID_ESC_COMMAND = 0x13;
+
+/**
+ * Parse feature TLV response from CM_IOCTL_GET_FEATURE_REQUEST
+ * @param {Buffer} response - The TLV response buffer
+ * @returns {Map<number, number>} Map of feature tag to control code
+ */
+function parseFeatures(response) {
+    const features = new Map();
+    let offset = 0;
+
+    while (offset + 4 <= response.length) {
+        const tag = response[offset];
+        const length = response[offset + 1];
+
+        if (length === 4 && offset + 2 + length <= response.length) {
+            // Big-endian control code
+            const controlCode =
+                (response[offset + 2] << 24) |
+                (response[offset + 3] << 16) |
+                (response[offset + 4] << 8) |
+                response[offset + 5];
+            features.set(tag, controlCode);
+        }
+
+        offset += 2 + length;
+    }
+
+    return features;
+}
+
+module.exports = {
+    // Control code generator
+    SCARD_CTL_CODE,
+
+    // Common control codes
+    CM_IOCTL_GET_FEATURE_REQUEST,
+
+    // CCID Feature tags
+    FEATURE_VERIFY_PIN_START,
+    FEATURE_VERIFY_PIN_FINISH,
+    FEATURE_MODIFY_PIN_START,
+    FEATURE_MODIFY_PIN_FINISH,
+    FEATURE_GET_KEY_PRESSED,
+    FEATURE_VERIFY_PIN_DIRECT,
+    FEATURE_MODIFY_PIN_DIRECT,
+    FEATURE_MCT_READER_DIRECT,
+    FEATURE_MCT_UNIVERSAL,
+    FEATURE_IFD_PIN_PROPERTIES,
+    FEATURE_ABORT,
+    FEATURE_SET_SPE_MESSAGE,
+    FEATURE_VERIFY_PIN_DIRECT_APP_ID,
+    FEATURE_MODIFY_PIN_DIRECT_APP_ID,
+    FEATURE_WRITE_DISPLAY,
+    FEATURE_GET_KEY,
+    FEATURE_IFD_DISPLAY_PROPERTIES,
+    FEATURE_GET_TLV_PROPERTIES,
+    FEATURE_CCID_ESC_COMMAND,
+
+    // Helper functions
+    parseFeatures,
+};

package/lib/errors.js

@@ -67,6 +67,32 @@ class SharingViolationError extends PCSCError {
     }
 }
 
+/**
+ * PC/SC error codes mapped to specific error classes
+ * @type {Map<number, typeof PCSCError>}
+ */
+const ERROR_CODE_MAP = new Map([
+    [0x80100069, CardRemovedError],      // SCARD_W_REMOVED_CARD
+    [0x8010000A, TimeoutError],           // SCARD_E_TIMEOUT
+    [0x8010002E, NoReadersError],         // SCARD_E_NO_READERS_AVAILABLE
+    [0x8010001D, ServiceNotRunningError], // SCARD_E_NO_SERVICE
+    [0x8010000B, SharingViolationError],  // SCARD_E_SHARING_VIOLATION
+]);
+
+/**
+ * Factory function to create the appropriate error class based on PC/SC error code
+ * @param {string} message - Error message
+ * @param {number} code - PC/SC error code
+ * @returns {PCSCError} The appropriate error instance
+ */
+function createPCSCError(message, code) {
+    const ErrorClass = ERROR_CODE_MAP.get(code);
+    if (ErrorClass) {
+        return new ErrorClass(message);
+    }
+    return new PCSCError(message, code);
+}
+
 module.exports = {
     PCSCError,
     CardRemovedError,
@@ -74,4 +100,5 @@ module.exports = {
     NoReadersError,
     ServiceNotRunningError,
     SharingViolationError,
+    createPCSCError,
 };

package/lib/index.d.ts

@@ -21,6 +21,18 @@ export interface CardStatus {
     atr: Buffer;
 }
 
+/**
+ * Options for card.transmit()
+ */
+export interface TransmitOptions {
+    /**
+     * Maximum receive buffer size in bytes.
+     * Default: 258 (standard APDU: 256 data + 2 status bytes)
+     * Maximum: 262144 (256KB for extended APDUs)
+     */
+    maxRecvLength?: number;
+}
+
 /**
  * Represents a connected smart card
  */
@@ -35,9 +47,10 @@ export interface Card {
     /**
      * Transmit an APDU command to the card
      * @param command - The command buffer or byte array
+     * @param options - Optional transmit options
      * @returns Promise resolving to the response buffer
      */
-    transmit(command: Buffer | number[]): Promise<Buffer>;
+    transmit(command: Buffer | number[], options?: TransmitOptions): Promise<Buffer>;
 
     /**
      * Send a control command to the reader
@@ -60,13 +73,13 @@ export interface Card {
     disconnect(disposition?: number): void;
 
     /**
-     * Reconnect to the card
+     * Reconnect to the card (async)
      * @param shareMode - Share mode
      * @param protocol - Preferred protocol(s)
      * @param initialization - Initialization action
-     * @returns The new active protocol
+     * @returns Promise resolving to the new active protocol
      */
-    reconnect(shareMode?: number, protocol?: number, initialization?: number): number;
+    reconnect(shareMode?: number, protocol?: number, initialization?: number): Promise<number>;
 }
 
 /**
@@ -216,6 +229,32 @@ export declare class TimeoutError extends PCSCError {
     constructor(message?: string);
 }
 
+/**
+ * Error thrown when no readers are available
+ */
+export declare class NoReadersError extends PCSCError {
+    constructor(message?: string);
+}
+
+/**
+ * Error thrown when PC/SC service is not running
+ */
+export declare class ServiceNotRunningError extends PCSCError {
+    constructor(message?: string);
+}
+
+/**
+ * Error thrown when there's a sharing violation
+ */
+export declare class SharingViolationError extends PCSCError {
+    constructor(message?: string);
+}
+
+/**
+ * Factory function to create the appropriate error class based on PC/SC error code
+ */
+export declare function createPCSCError(message: string, code: number): PCSCError;
+
 // Share modes
 export declare const SCARD_SHARE_EXCLUSIVE: number;
 export declare const SCARD_SHARE_SHARED: number;
@@ -245,3 +284,42 @@ export declare const SCARD_STATE_ATRMATCH: number;
 export declare const SCARD_STATE_EXCLUSIVE: number;
 export declare const SCARD_STATE_INUSE: number;
 export declare const SCARD_STATE_MUTE: number;
+
+// Control code generator
+/**
+ * Generate a platform-specific control code
+ * @param code - The control code number
+ * @returns The platform-specific control code
+ */
+export declare function SCARD_CTL_CODE(code: number): number;
+
+// Common control codes
+export declare const CM_IOCTL_GET_FEATURE_REQUEST: number;
+
+// CCID Feature tags
+export declare const FEATURE_VERIFY_PIN_START: number;
+export declare const FEATURE_VERIFY_PIN_FINISH: number;
+export declare const FEATURE_MODIFY_PIN_START: number;
+export declare const FEATURE_MODIFY_PIN_FINISH: number;
+export declare const FEATURE_GET_KEY_PRESSED: number;
+export declare const FEATURE_VERIFY_PIN_DIRECT: number;
+export declare const FEATURE_MODIFY_PIN_DIRECT: number;
+export declare const FEATURE_MCT_READER_DIRECT: number;
+export declare const FEATURE_MCT_UNIVERSAL: number;
+export declare const FEATURE_IFD_PIN_PROPERTIES: number;
+export declare const FEATURE_ABORT: number;
+export declare const FEATURE_SET_SPE_MESSAGE: number;
+export declare const FEATURE_VERIFY_PIN_DIRECT_APP_ID: number;
+export declare const FEATURE_MODIFY_PIN_DIRECT_APP_ID: number;
+export declare const FEATURE_WRITE_DISPLAY: number;
+export declare const FEATURE_GET_KEY: number;
+export declare const FEATURE_IFD_DISPLAY_PROPERTIES: number;
+export declare const FEATURE_GET_TLV_PROPERTIES: number;
+export declare const FEATURE_CCID_ESC_COMMAND: number;
+
+/**
+ * Parse feature TLV response from CM_IOCTL_GET_FEATURE_REQUEST
+ * @param response - The TLV response buffer
+ * @returns Map of feature tag to control code
+ */
+export declare function parseFeatures(response: Buffer): Map<number, number>;

package/lib/index.js

@@ -38,7 +38,41 @@ const SCARD_STATE_MUTE = addon.SCARD_STATE_MUTE;
 const { Devices } = require('./devices');
 
 // Import error classes
-const { PCSCError, CardRemovedError, TimeoutError } = require('./errors');
+const {
+    PCSCError,
+    CardRemovedError,
+    TimeoutError,
+    NoReadersError,
+    ServiceNotRunningError,
+    SharingViolationError,
+    createPCSCError,
+} = require('./errors');
+
+// Import control codes
+const {
+    SCARD_CTL_CODE,
+    CM_IOCTL_GET_FEATURE_REQUEST,
+    FEATURE_VERIFY_PIN_START,
+    FEATURE_VERIFY_PIN_FINISH,
+    FEATURE_MODIFY_PIN_START,
+    FEATURE_MODIFY_PIN_FINISH,
+    FEATURE_GET_KEY_PRESSED,
+    FEATURE_VERIFY_PIN_DIRECT,
+    FEATURE_MODIFY_PIN_DIRECT,
+    FEATURE_MCT_READER_DIRECT,
+    FEATURE_MCT_UNIVERSAL,
+    FEATURE_IFD_PIN_PROPERTIES,
+    FEATURE_ABORT,
+    FEATURE_SET_SPE_MESSAGE,
+    FEATURE_VERIFY_PIN_DIRECT_APP_ID,
+    FEATURE_MODIFY_PIN_DIRECT_APP_ID,
+    FEATURE_WRITE_DISPLAY,
+    FEATURE_GET_KEY,
+    FEATURE_IFD_DISPLAY_PROPERTIES,
+    FEATURE_GET_TLV_PROPERTIES,
+    FEATURE_CCID_ESC_COMMAND,
+    parseFeatures,
+} = require('./control-codes');
 
 module.exports = {
     // Classes
@@ -52,6 +86,10 @@ module.exports = {
     PCSCError,
     CardRemovedError,
     TimeoutError,
+    NoReadersError,
+    ServiceNotRunningError,
+    SharingViolationError,
+    createPCSCError,
 
     // Share modes
     SCARD_SHARE_EXCLUSIVE,
@@ -82,4 +120,32 @@ module.exports = {
     SCARD_STATE_EXCLUSIVE,
     SCARD_STATE_INUSE,
     SCARD_STATE_MUTE,
+
+    // Control codes
+    SCARD_CTL_CODE,
+    CM_IOCTL_GET_FEATURE_REQUEST,
+
+    // CCID Feature tags
+    FEATURE_VERIFY_PIN_START,
+    FEATURE_VERIFY_PIN_FINISH,
+    FEATURE_MODIFY_PIN_START,
+    FEATURE_MODIFY_PIN_FINISH,
+    FEATURE_GET_KEY_PRESSED,
+    FEATURE_VERIFY_PIN_DIRECT,
+    FEATURE_MODIFY_PIN_DIRECT,
+    FEATURE_MCT_READER_DIRECT,
+    FEATURE_MCT_UNIVERSAL,
+    FEATURE_IFD_PIN_PROPERTIES,
+    FEATURE_ABORT,
+    FEATURE_SET_SPE_MESSAGE,
+    FEATURE_VERIFY_PIN_DIRECT_APP_ID,
+    FEATURE_MODIFY_PIN_DIRECT_APP_ID,
+    FEATURE_WRITE_DISPLAY,
+    FEATURE_GET_KEY,
+    FEATURE_IFD_DISPLAY_PROPERTIES,
+    FEATURE_GET_TLV_PROPERTIES,
+    FEATURE_CCID_ESC_COMMAND,
+
+    // Helper functions
+    parseFeatures,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "smartcard",
-    "version": "2.0.3",
+    "version": "3.1.0",
     "description": "PC/SC bindings for Node.js using N-API - ABI stable across Node.js versions",
     "author": "Tom KP",
     "license": "MIT",
@@ -19,7 +19,9 @@
         "install": "node-gyp rebuild",
         "build": "node-gyp rebuild",
         "rebuild": "node-gyp rebuild",
-        "test": "node test/test.js"
+        "test": "node test/test.js && node test/unit.js",
+        "test:unit": "node test/unit.js",
+        "test:integration": "node test/test.js"
     },
     "files": [
         "lib/",

package/src/async_workers.cpp

@@ -84,6 +84,7 @@ TransmitWorker::TransmitWorker(
     SCARDHANDLE card,
     DWORD protocol,
     std::vector<uint8_t> sendBuffer,
+    size_t maxRecvLength,
     Napi::Promise::Deferred deferred)
     : Napi::AsyncWorker(env),
       card_(card),
@@ -92,8 +93,16 @@ TransmitWorker::TransmitWorker(
       recvLength_(0),
       result_(SCARD_S_SUCCESS),
       deferred_(deferred) {
-    // Pre-allocate receive buffer (max APDU response size)
-    recvBuffer_.resize(258);
+    // Pre-allocate receive buffer with configurable size
+    // Default is 258 (standard APDU: 256 data + 2 status bytes)
+    // Max is 262144 (256KB) for extended APDUs
+    size_t bufferSize = maxRecvLength;
+    if (bufferSize == 0) {
+        bufferSize = 258;  // Default
+    } else if (bufferSize > 262144) {
+        bufferSize = 262144;  // Cap at 256KB
+    }
+    recvBuffer_.resize(bufferSize);
 }
 
 void TransmitWorker::Execute() {
@@ -232,3 +241,48 @@ void ConnectWorker::OnOK() {
 void ConnectWorker::OnError(const Napi::Error& error) {
     deferred_.Reject(error.Value());
 }
+
+// ============================================================================
+// ReconnectWorker
+// ============================================================================
+
+ReconnectWorker::ReconnectWorker(
+    Napi::Env env,
+    SCARDHANDLE card,
+    DWORD shareMode,
+    DWORD preferredProtocols,
+    DWORD initialization,
+    Napi::Promise::Deferred deferred)
+    : Napi::AsyncWorker(env),
+      card_(card),
+      shareMode_(shareMode),
+      preferredProtocols_(preferredProtocols),
+      initialization_(initialization),
+      activeProtocol_(0),
+      result_(SCARD_S_SUCCESS),
+      deferred_(deferred) {
+}
+
+void ReconnectWorker::Execute() {
+    result_ = SCardReconnect(
+        card_,
+        shareMode_,
+        preferredProtocols_,
+        initialization_,
+        &activeProtocol_
+    );
+}
+
+void ReconnectWorker::OnOK() {
+    Napi::Env env = Env();
+
+    if (result_ == SCARD_S_SUCCESS) {
+        deferred_.Resolve(Napi::Number::New(env, activeProtocol_));
+    } else {
+        deferred_.Reject(Napi::Error::New(env, GetPCSCErrorString(result_)).Value());
+    }
+}
+
+void ReconnectWorker::OnError(const Napi::Error& error) {
+    deferred_.Reject(error.Value());
+}

package/src/async_workers.h

@@ -35,6 +35,7 @@ public:
                    SCARDHANDLE card,
                    DWORD protocol,
                    std::vector<uint8_t> sendBuffer,
+                   size_t maxRecvLength,
                    Napi::Promise::Deferred deferred);
 
     void Execute() override;
@@ -98,3 +99,29 @@ private:
     LONG result_;
     Napi::Promise::Deferred deferred_;
 };
+
+// Async worker for SCardReconnect
+class ReconnectWorker : public Napi::AsyncWorker {
+public:
+    ReconnectWorker(Napi::Env env,
+                    SCARDHANDLE card,
+                    DWORD shareMode,
+                    DWORD preferredProtocols,
+                    DWORD initialization,
+                    Napi::Promise::Deferred deferred);
+
+    void Execute() override;
+    void OnOK() override;
+    void OnError(const Napi::Error& error) override;
+
+    DWORD GetActiveProtocol() const { return activeProtocol_; }
+
+private:
+    SCARDHANDLE card_;
+    DWORD shareMode_;
+    DWORD preferredProtocols_;
+    DWORD initialization_;
+    DWORD activeProtocol_;
+    LONG result_;
+    Napi::Promise::Deferred deferred_;
+};

package/src/pcsc_card.cpp

@@ -111,11 +111,20 @@ Napi::Value PCSCCard::Transmit(const Napi::CallbackInfo& info) {
         return env.Null();
     }
 
+    // Parse options (optional second argument)
+    size_t maxRecvLength = 0;  // 0 means use default
+    if (info.Length() > 1 && info[1].IsObject()) {
+        Napi::Object options = info[1].As<Napi::Object>();
+        if (options.Has("maxRecvLength") && options.Get("maxRecvLength").IsNumber()) {
+            maxRecvLength = options.Get("maxRecvLength").As<Napi::Number>().Uint32Value();
+        }
+    }
+
     // Create promise for async transmit
     Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(env);
 
     TransmitWorker* worker = new TransmitWorker(
-        env, card_, protocol_, sendBuffer, deferred);
+        env, card_, protocol_, sendBuffer, maxRecvLength, deferred);
     worker->Queue();
 
     return deferred.Promise();
@@ -235,14 +244,12 @@ Napi::Value PCSCCard::Reconnect(const Napi::CallbackInfo& info) {
         initialization = info[2].As<Napi::Number>().Uint32Value();
     }
 
-    DWORD activeProtocol = 0;
-    LONG result = SCardReconnect(card_, shareMode, preferredProtocols, initialization, &activeProtocol);
+    // Create promise for async reconnect
+    Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(env);
 
-    if (result != SCARD_S_SUCCESS) {
-        Napi::Error::New(env, GetPCSCErrorString(result)).ThrowAsJavaScriptException();
-        return env.Null();
-    }
+    ReconnectWorker* worker = new ReconnectWorker(
+        env, card_, shareMode, preferredProtocols, initialization, deferred);
+    worker->Queue();
 
-    protocol_ = activeProtocol;
-    return Napi::Number::New(env, activeProtocol);
+    return deferred.Promise();
 }