smartcard 1.0.46 → 2.0.1

package/lib/devices.js

@@ -0,0 +1,283 @@
+// @ts-check
+'use strict';
+
+const EventEmitter = require('events');
+const addon = require('../build/Release/smartcard_napi.node');
+
+/**
+ * @typedef {import('./index').Reader} Reader
+ * @typedef {import('./index').Card} Card
+ * @typedef {import('./index').MonitorEvent} MonitorEvent
+ * @typedef {import('./index').Context} ContextType
+ * @typedef {import('./index').ReaderMonitor} ReaderMonitorType
+ */
+
+const { Context, ReaderMonitor } = addon;
+const SCARD_STATE_PRESENT = addon.SCARD_STATE_PRESENT;
+const SCARD_SHARE_SHARED = addon.SCARD_SHARE_SHARED;
+const SCARD_PROTOCOL_T0 = addon.SCARD_PROTOCOL_T0;
+const SCARD_PROTOCOL_T1 = addon.SCARD_PROTOCOL_T1;
+
+/**
+ * @typedef {Object} ReaderState
+ * @property {boolean} hasCard
+ * @property {Card|null} card
+ */
+
+/**
+ * High-level event-driven API for PC/SC devices
+ *
+ * Uses native ReaderMonitor for efficient background monitoring
+ * with ThreadSafeFunction to emit events from worker thread.
+ *
+ * Events:
+ * - 'reader-attached': Emitted when a reader is attached
+ * - 'reader-detached': Emitted when a reader is detached
+ * - 'card-inserted': Emitted when a card is inserted
+ * - 'card-removed': Emitted when a card is removed
+ * - 'error': Emitted on errors
+ *
+ * @extends EventEmitter
+ */
+class Devices extends EventEmitter {
+    constructor() {
+        super();
+        /** @type {ReaderMonitorType|null} */
+        this._monitor = null;
+        /** @type {ContextType|null} */
+        this._context = null;
+        /** @type {boolean} */
+        this._running = false;
+        /** @type {Map<string, ReaderState>} */
+        this._readers = new Map();
+    }
+
+    /**
+     * Start monitoring for device changes
+     */
+    start() {
+        if (this._running) {
+            return;
+        }
+
+        try {
+            // Create context for card connections
+            this._context = new Context();
+
+            // Create native monitor
+            this._monitor = new ReaderMonitor();
+            this._running = true;
+
+            // Start native monitoring with callback
+            this._monitor.start((event) => {
+                this._handleEvent(event);
+            });
+        } catch (err) {
+            this.emit('error', err);
+        }
+    }
+
+    /**
+     * Stop monitoring
+     */
+    stop() {
+        this._running = false;
+
+        if (this._monitor) {
+            try {
+                this._monitor.stop();
+            } catch (err) {
+                // Ignore stop errors
+            }
+            this._monitor = null;
+        }
+
+        // Disconnect any connected cards
+        for (const [name, state] of this._readers) {
+            if (state.card) {
+                try {
+                    state.card.disconnect();
+                } catch (err) {
+                    // Ignore disconnect errors
+                }
+            }
+        }
+        this._readers.clear();
+
+        if (this._context) {
+            try {
+                this._context.close();
+            } catch (err) {
+                // Ignore close errors
+            }
+            this._context = null;
+        }
+    }
+
+    /**
+     * List currently known readers
+     * @returns {Reader[]} Array of readers
+     */
+    listReaders() {
+        if (!this._context || !this._context.isValid) {
+            return [];
+        }
+        try {
+            return this._context.listReaders();
+        } catch (err) {
+            return [];
+        }
+    }
+
+    /**
+     * Handle events from native monitor
+     * @param {MonitorEvent} event
+     * @returns {Promise<void>}
+     */
+    async _handleEvent(event) {
+        if (!this._running) {
+            return;
+        }
+
+        const { type, reader: readerName, state, atr } = event;
+
+        switch (type) {
+            case 'reader-attached':
+                this._handleReaderAttached(readerName, state, atr);
+                break;
+
+            case 'reader-detached':
+                this._handleReaderDetached(readerName);
+                break;
+
+            case 'card-inserted':
+                await this._handleCardInserted(readerName, state, atr);
+                break;
+
+            case 'card-removed':
+                this._handleCardRemoved(readerName);
+                break;
+
+            case 'error':
+                // readerName contains error message for error events
+                this.emit('error', new Error(readerName));
+                break;
+        }
+    }
+
+    /**
+     * Handle reader attached
+     * @param {string} readerName
+     * @param {number} state
+     * @param {Buffer|null} atr
+     */
+    _handleReaderAttached(readerName, state, atr) {
+        // Initialize reader state
+        this._readers.set(readerName, {
+            hasCard: false,
+            card: null,
+        });
+
+        // Create a reader-like object for the event
+        const reader = {
+            name: readerName,
+            state: state,
+            atr: atr,
+        };
+
+        this.emit('reader-attached', reader);
+
+        // Check if card is already present
+        if ((state & SCARD_STATE_PRESENT) !== 0) {
+            this._handleCardInserted(readerName, state, atr);
+        }
+    }
+
+    /**
+     * Handle reader detached
+     * @param {string} readerName
+     */
+    _handleReaderDetached(readerName) {
+        const state = this._readers.get(readerName);
+
+        // If card was connected, emit card-removed first
+        if (state && state.hasCard) {
+            this._handleCardRemoved(readerName);
+        }
+
+        this._readers.delete(readerName);
+
+        const reader = { name: readerName };
+        this.emit('reader-detached', reader);
+    }
+
+    /**
+     * Handle card inserted
+     * @param {string} readerName
+     * @param {number} eventState
+     * @param {Buffer|null} atr
+     * @returns {Promise<void>}
+     */
+    async _handleCardInserted(readerName, eventState, atr) {
+        let state = this._readers.get(readerName);
+        if (!state) {
+            state = { hasCard: false, card: null };
+            this._readers.set(readerName, state);
+        }
+
+        state.hasCard = true;
+
+        // Try to connect to the card
+        try {
+            const readers = this._context.listReaders();
+            const reader = readers.find(r => r.name === readerName);
+
+            if (reader) {
+                const card = await reader.connect(
+                    SCARD_SHARE_SHARED,
+                    SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1
+                );
+
+                state.card = card;
+
+                this.emit('card-inserted', {
+                    reader: { name: readerName, state: eventState, atr: atr },
+                    card: card,
+                });
+            }
+        } catch (err) {
+            // Emit error but don't fail
+            this.emit('error', err);
+        }
+    }
+
+    /**
+     * Handle card removed
+     * @param {string} readerName
+     */
+    _handleCardRemoved(readerName) {
+        const state = this._readers.get(readerName);
+        if (!state) {
+            return;
+        }
+
+        const card = state.card;
+        state.hasCard = false;
+        state.card = null;
+
+        if (card) {
+            try {
+                card.disconnect();
+            } catch (err) {
+                // Ignore - card is already removed
+            }
+        }
+
+        this.emit('card-removed', {
+            reader: { name: readerName },
+            card: card,
+        });
+    }
+}
+
+module.exports = { Devices };

package/lib/errors.js

@@ -0,0 +1,77 @@
+// @ts-check
+'use strict';
+
+/**
+ * Base error class for PC/SC errors
+ */
+class PCSCError extends Error {
+    /**
+     * @param {string} message
+     * @param {number} code
+     */
+    constructor(message, code) {
+        super(message);
+        this.name = 'PCSCError';
+        this.code = code;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+
+/**
+ * Error thrown when a card is removed during an operation
+ */
+class CardRemovedError extends PCSCError {
+    constructor(message = 'Card was removed') {
+        super(message, 0x80100069);
+        this.name = 'CardRemovedError';
+    }
+}
+
+/**
+ * Error thrown when an operation times out
+ */
+class TimeoutError extends PCSCError {
+    constructor(message = 'Operation timed out') {
+        super(message, 0x8010000A);
+        this.name = 'TimeoutError';
+    }
+}
+
+/**
+ * Error thrown when no readers are available
+ */
+class NoReadersError extends PCSCError {
+    constructor(message = 'No readers available') {
+        super(message, 0x8010002E);
+        this.name = 'NoReadersError';
+    }
+}
+
+/**
+ * Error thrown when PC/SC service is not running
+ */
+class ServiceNotRunningError extends PCSCError {
+    constructor(message = 'PC/SC service not running') {
+        super(message, 0x8010001D);
+        this.name = 'ServiceNotRunningError';
+    }
+}
+
+/**
+ * Error thrown when there's a sharing violation
+ */
+class SharingViolationError extends PCSCError {
+    constructor(message = 'Sharing violation - card is in use') {
+        super(message, 0x8010000B);
+        this.name = 'SharingViolationError';
+    }
+}
+
+module.exports = {
+    PCSCError,
+    CardRemovedError,
+    TimeoutError,
+    NoReadersError,
+    ServiceNotRunningError,
+    SharingViolationError,
+};

package/lib/index.d.ts

@@ -0,0 +1,247 @@
+/// <reference types="node" />
+
+import { EventEmitter } from 'events';
+
+/**
+ * Reader state information returned from waitForChange
+ */
+export interface ReaderState {
+    name: string;
+    state: number;
+    changed: boolean;
+    atr: Buffer | null;
+}
+
+/**
+ * Card status information
+ */
+export interface CardStatus {
+    state: number;
+    protocol: number;
+    atr: Buffer;
+}
+
+/**
+ * Represents a connected smart card
+ */
+export interface Card {
+    /** The active protocol (T0, T1, or RAW) */
+    readonly protocol: number;
+    /** Whether the card is still connected */
+    readonly connected: boolean;
+    /** The card's ATR (Answer To Reset) */
+    readonly atr: Buffer | null;
+
+    /**
+     * Transmit an APDU command to the card
+     * @param command - The command buffer or byte array
+     * @returns Promise resolving to the response buffer
+     */
+    transmit(command: Buffer | number[]): Promise<Buffer>;
+
+    /**
+     * Send a control command to the reader
+     * @param code - Control code
+     * @param data - Optional data buffer
+     * @returns Promise resolving to the response buffer
+     */
+    control(code: number, data?: Buffer | number[]): Promise<Buffer>;
+
+    /**
+     * Get the current card status
+     * @returns Card status object
+     */
+    getStatus(): CardStatus;
+
+    /**
+     * Disconnect from the card
+     * @param disposition - What to do with the card (default: SCARD_LEAVE_CARD)
+     */
+    disconnect(disposition?: number): void;
+
+    /**
+     * Reconnect to the card
+     * @param shareMode - Share mode
+     * @param protocol - Preferred protocol(s)
+     * @param initialization - Initialization action
+     * @returns The new active protocol
+     */
+    reconnect(shareMode?: number, protocol?: number, initialization?: number): number;
+}
+
+/**
+ * Represents a smart card reader
+ */
+export interface Reader {
+    /** The reader name */
+    readonly name: string;
+    /** Current reader state flags */
+    readonly state: number;
+    /** ATR of the card if present */
+    readonly atr: Buffer | null;
+
+    /**
+     * Connect to a card in the reader
+     * @param shareMode - Share mode (default: SCARD_SHARE_SHARED)
+     * @param protocol - Preferred protocol(s) (default: T0 | T1)
+     * @returns Promise resolving to a Card object
+     */
+    connect(shareMode?: number, protocol?: number): Promise<Card>;
+}
+
+/**
+ * Low-level PC/SC context
+ */
+export declare class Context {
+    constructor();
+
+    /** Whether the context is still valid */
+    readonly isValid: boolean;
+
+    /**
+     * List available readers
+     * @returns Array of Reader objects
+     */
+    listReaders(): Reader[];
+
+    /**
+     * Wait for reader/card state changes
+     * @param readers - Optional array of readers to monitor
+     * @param timeout - Timeout in milliseconds (default: infinite)
+     * @returns Promise resolving to array of reader states
+     */
+    waitForChange(readers?: Reader[] | ReaderState[], timeout?: number): Promise<ReaderState[] | null>;
+
+    /**
+     * Cancel a pending waitForChange call
+     */
+    cancel(): void;
+
+    /**
+     * Close the context and release resources
+     */
+    close(): void;
+}
+
+/**
+ * Monitor event from native ReaderMonitor
+ */
+export interface MonitorEvent {
+    type: 'reader-attached' | 'reader-detached' | 'card-inserted' | 'card-removed' | 'error';
+    reader: string;
+    state: number;
+    atr: Buffer | null;
+}
+
+/**
+ * Native PC/SC event monitor using ThreadSafeFunction
+ * Runs monitoring on a background thread for efficiency
+ */
+export declare class ReaderMonitor {
+    constructor();
+
+    /** Whether the monitor is currently running */
+    readonly isRunning: boolean;
+
+    /**
+     * Start monitoring for reader/card changes
+     * @param callback - Function called when events occur
+     */
+    start(callback: (event: MonitorEvent) => void): void;
+
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+}
+
+/**
+ * Event types for Devices class
+ */
+export interface DeviceEvents {
+    'reader-attached': (reader: Reader) => void;
+    'reader-detached': (reader: Reader) => void;
+    'card-inserted': (event: { reader: Reader; card: Card }) => void;
+    'card-removed': (event: { reader: Reader; card: Card | null }) => void;
+    'error': (error: Error) => void;
+}
+
+/**
+ * High-level event-driven API for monitoring PC/SC devices
+ */
+export declare class Devices extends EventEmitter {
+    constructor();
+
+    /**
+     * Start monitoring for device changes
+     */
+    start(): void;
+
+    /**
+     * Stop monitoring and release resources
+     */
+    stop(): void;
+
+    /**
+     * List currently known readers
+     * @returns Array of Reader objects
+     */
+    listReaders(): Reader[];
+
+    on<K extends keyof DeviceEvents>(event: K, listener: DeviceEvents[K]): this;
+    once<K extends keyof DeviceEvents>(event: K, listener: DeviceEvents[K]): this;
+    off<K extends keyof DeviceEvents>(event: K, listener: DeviceEvents[K]): this;
+    emit<K extends keyof DeviceEvents>(event: K, ...args: Parameters<DeviceEvents[K]>): boolean;
+}
+
+/**
+ * Base PC/SC error class
+ */
+export declare class PCSCError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+
+/**
+ * Error thrown when card is removed during operation
+ */
+export declare class CardRemovedError extends PCSCError {
+    constructor(message?: string);
+}
+
+/**
+ * Error thrown when operation times out
+ */
+export declare class TimeoutError extends PCSCError {
+    constructor(message?: string);
+}
+
+// Share modes
+export declare const SCARD_SHARE_EXCLUSIVE: number;
+export declare const SCARD_SHARE_SHARED: number;
+export declare const SCARD_SHARE_DIRECT: number;
+
+// Protocols
+export declare const SCARD_PROTOCOL_T0: number;
+export declare const SCARD_PROTOCOL_T1: number;
+export declare const SCARD_PROTOCOL_RAW: number;
+export declare const SCARD_PROTOCOL_UNDEFINED: number;
+
+// Disposition
+export declare const SCARD_LEAVE_CARD: number;
+export declare const SCARD_RESET_CARD: number;
+export declare const SCARD_UNPOWER_CARD: number;
+export declare const SCARD_EJECT_CARD: number;
+
+// State flags
+export declare const SCARD_STATE_UNAWARE: number;
+export declare const SCARD_STATE_IGNORE: number;
+export declare const SCARD_STATE_CHANGED: number;
+export declare const SCARD_STATE_UNKNOWN: number;
+export declare const SCARD_STATE_UNAVAILABLE: number;
+export declare const SCARD_STATE_EMPTY: number;
+export declare const SCARD_STATE_PRESENT: number;
+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;

package/lib/index.js

@@ -1,24 +1,85 @@
+// @ts-check
 'use strict';
 
-var _Iso7816Application = _interopRequireDefault(require("./Iso7816Application"));
+// Load native addon
+const addon = require('../build/Release/smartcard_napi.node');
 
-var _CommandApdu = _interopRequireDefault(require("./CommandApdu"));
+// Re-export native classes
+const { Context, Reader, Card, ReaderMonitor } = addon;
 
-var _ResponseApdu = _interopRequireDefault(require("./ResponseApdu"));
+// Re-export constants
+const SCARD_SHARE_EXCLUSIVE = addon.SCARD_SHARE_EXCLUSIVE;
+const SCARD_SHARE_SHARED = addon.SCARD_SHARE_SHARED;
+const SCARD_SHARE_DIRECT = addon.SCARD_SHARE_DIRECT;
 
-var _Devices = _interopRequireDefault(require("./Devices"));
+const SCARD_PROTOCOL_T0 = addon.SCARD_PROTOCOL_T0;
+const SCARD_PROTOCOL_T1 = addon.SCARD_PROTOCOL_T1;
+const SCARD_PROTOCOL_RAW = addon.SCARD_PROTOCOL_RAW;
+const SCARD_PROTOCOL_UNDEFINED = addon.SCARD_PROTOCOL_UNDEFINED;
 
-var _Device = _interopRequireDefault(require("./Device"));
+const SCARD_LEAVE_CARD = addon.SCARD_LEAVE_CARD;
+const SCARD_RESET_CARD = addon.SCARD_RESET_CARD;
+const SCARD_UNPOWER_CARD = addon.SCARD_UNPOWER_CARD;
+const SCARD_EJECT_CARD = addon.SCARD_EJECT_CARD;
 
-var _Card = _interopRequireDefault(require("./Card"));
+const SCARD_STATE_UNAWARE = addon.SCARD_STATE_UNAWARE;
+const SCARD_STATE_IGNORE = addon.SCARD_STATE_IGNORE;
+const SCARD_STATE_CHANGED = addon.SCARD_STATE_CHANGED;
+const SCARD_STATE_UNKNOWN = addon.SCARD_STATE_UNKNOWN;
+const SCARD_STATE_UNAVAILABLE = addon.SCARD_STATE_UNAVAILABLE;
+const SCARD_STATE_EMPTY = addon.SCARD_STATE_EMPTY;
+const SCARD_STATE_PRESENT = addon.SCARD_STATE_PRESENT;
+const SCARD_STATE_ATRMATCH = addon.SCARD_STATE_ATRMATCH;
+const SCARD_STATE_EXCLUSIVE = addon.SCARD_STATE_EXCLUSIVE;
+const SCARD_STATE_INUSE = addon.SCARD_STATE_INUSE;
+const SCARD_STATE_MUTE = addon.SCARD_STATE_MUTE;
 
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+// Import Devices class
+const { Devices } = require('./devices');
+
+// Import error classes
+const { PCSCError, CardRemovedError, TimeoutError } = require('./errors');
 
 module.exports = {
-  Iso7816Application: _Iso7816Application["default"],
-  CommandApdu: _CommandApdu["default"],
-  ResponseApdu: _ResponseApdu["default"],
-  Devices: _Devices["default"],
-  Device: _Device["default"],
-  Card: _Card["default"]
-};
+    // Classes
+    Context,
+    Reader,
+    Card,
+    Devices,
+    ReaderMonitor,
+
+    // Error classes
+    PCSCError,
+    CardRemovedError,
+    TimeoutError,
+
+    // Share modes
+    SCARD_SHARE_EXCLUSIVE,
+    SCARD_SHARE_SHARED,
+    SCARD_SHARE_DIRECT,
+
+    // Protocols
+    SCARD_PROTOCOL_T0,
+    SCARD_PROTOCOL_T1,
+    SCARD_PROTOCOL_RAW,
+    SCARD_PROTOCOL_UNDEFINED,
+
+    // Disposition
+    SCARD_LEAVE_CARD,
+    SCARD_RESET_CARD,
+    SCARD_UNPOWER_CARD,
+    SCARD_EJECT_CARD,
+
+    // State flags
+    SCARD_STATE_UNAWARE,
+    SCARD_STATE_IGNORE,
+    SCARD_STATE_CHANGED,
+    SCARD_STATE_UNKNOWN,
+    SCARD_STATE_UNAVAILABLE,
+    SCARD_STATE_EMPTY,
+    SCARD_STATE_PRESENT,
+    SCARD_STATE_ATRMATCH,
+    SCARD_STATE_EXCLUSIVE,
+    SCARD_STATE_INUSE,
+    SCARD_STATE_MUTE,
+};