🃏 jsapdu

The modern TypeScript library for SmartCard communication that just works.

jsapdu bridges the gap between your applications and SmartCard hardware, providing a unified, type-safe interface across multiple platforms. Whether you're building government ID solutions, payment systems, or secure authentication, jsapdu handles the complexity so you can focus on your business logic.

✨ Why jsapdu?

// Connect to any SmartCard with just a few linesimport{PcscPlatformManager}from"@aokiapp/jsapdu-pcsc";constplatform=PcscPlatformManager.getInstance().getPlatform();awaitplatform.init();constdevice=awaitplatform.acquireDevice((awaitplatform.getDeviceInfo())[0].id,);constcard=awaitdevice.startSession();// Send APDU commands with full type safetyconstresponse=awaitcard.transmit(newCommandApdu(0x00,0xa4,0x04,0x00,aid),);console.log(`Success: ${response.sw===0x9000}`);

🎯 Zero Configuration • Works out of the box with PC/SC, NFC, and more

🔒 Type Safe • Full TypeScript support with intelligent autocomplete

🌐 Cross Platform • Windows, macOS, Linux, and mobile support

📱 Modern APIs • async/await, Symbol.asyncDispose, and clean abstractions

🃏 SmartCard Ready • Built-in support for Japanese MynaCard and extensible for any card type

🧪 PC/SC FFI Included • Direct access to PC/SC functions via Foreign Function Interface (FFI)

🚀 Quick Start

Installation

npm install @aokiapp/jsapdu @aokiapp/jsapdu-pcsc

Your First SmartCard Connection

import{PcscPlatformManager}from"@aokiapp/jsapdu-pcsc";import{CommandApdu}from"@aokiapp/jsapdu-interface";asyncfunctionconnectToCard(){// Initialize platformawait using platform=PcscPlatformManager.getInstance().getPlatform();awaitplatform.init();// Find and connect to cardconstdevices=awaitplatform.getDeviceInfo();await using device=awaitplatform.acquireDevice(devices[0].id);await using card=awaitdevice.startSession();// Get card informationconstatr=awaitcard.getAtr();console.log("Card ATR:",Buffer.from(atr).toString("hex"));// Send commandsconstselectCommand=newCommandApdu(0x00,0xa4,0x04,0x00,Buffer.from("A0000000041010","hex"),);constresponse=awaitcard.transmit(selectCommand);if(response.sw===0x9000){console.log("Application selected successfully!");}}connectToCard().catch(console.error);

Japanese MynaCard Support

import{JPKI_AP,KENHOJO_AP}from"@aokiapp/mynacard";import{selectDf,verify,readEfBinaryFull}from"@aokiapp/apdu-utils";// Read MynaCard basic informationawaitcard.transmit(selectDf(KENHOJO_AP));awaitcard.transmit(verify("1234",{ef: 0x11}));// PIN verificationconstdata=awaitcard.transmit(readEfBinaryFull(0x02));// Read basic info// Parse structured TLV dataimport{SchemaParser,schemaKenhojoBasicFour}from"@aokiapp/mynacard";constparser=newSchemaParser(schemaKenhojoBasicFour);constinfo=parser.parse(data.arrayBuffer());console.log("Name:",info.name,"Address:",info.address);

📦 Packages

Package	Description	Use Case
@aokiapp/jsapdu-interface	Core abstractions and types	Platform-agnostic development
@aokiapp/jsapdu-pcsc	PC/SC platform implementation	Desktop SmartCard readers
@aokiapp/apdu-utils	APDU command builders	Common SmartCard operations
@aokiapp/mynacard	Japanese MynaCard support	Government ID integration
@aokiapp/pcsc-ffi-node	PC/SC Foreign Function Interface	Low-level PC/SC access

🌟 Features

Platform Support

• PC/SC - Windows, macOS, Linux desktop readers
• NFC - Contactless card communication
• Bluetooth LE - Wireless SmartCard readers
• WebUSB - Browser-based card access (coming soon)

SmartCard Protocols

• ISO 7816 - Contact card communication
• NFC/ISO 14443 - Contactless communication
• APDU - Application Protocol Data Units
• TLV - Tag-Length-Value data parsing

Developer Experience

• Full TypeScript support with intelligent autocomplete
• Modern async/await APIs with automatic resource cleanup
• Comprehensive error handling with structured error codes
• Extensive testing with unit, integration, and E2E tests

🎌 Japanese MynaCard Integration

jsapdu provides first-class support for Japanese government MynaCard (マイナンバーカード):

// Access different MynaCard applicationsimport{JPKI_AP,KENHOJO_AP,KENKAKU_AP}from"@aokiapp/mynacard";// Read certificate informationawaitcard.transmit(selectDf(JPKI_AP));constcert=awaitcard.transmit(readEfBinaryFull(0x01));// Signature certificate// Read personal information (券面事項入力補助)awaitcard.transmit(selectDf(KENHOJO_AP));constbasicInfo=awaitcard.transmit(readEfBinaryFull(0x02));// Parse with built-in schemasimport{schemaKenhojoBasicFour}from"@aokiapp/mynacard";constparser=newSchemaParser(schemaKenhojoBasicFour);constparsed=parser.parse(basicInfo.arrayBuffer());// { name: "田中太郎", address: "東京都...", birth: "1990-01-01", gender: "男" }

📚 Documentation

See the full documentation for detailed guides, API references, and architecture overviews.

For AI agents / machine-made readers: You must use file reading tool at Raw README at GitHub or local documentation.

🔧 Development

# Clone the repository
git clone https://github.com/AokiApp/jsapdu.git
cd jsapdu
# Install dependencies
npm install
# Build all packages
npm run build
# Run tests
npm test# Run E2E tests (requires SmartCard hardware)
npm run test:e2e

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the AokiApp Normative Application License (ANAL) - see the LICENSE file for details.

🏢 About

Created by AokiApp Inc. - Building the future of digital identity and secure communications.

---

🌟 Star this project • 📚 Read the docs • 💬 Get support