@cryptag/sdk 2.0.2

package/LICENSE

@@ -0,0 +1,140 @@
+Required Notice: Copyright 2026 Serdar Tepekule
+https://github.com/serdartpkl/cryptag
+
+CrypTag is free for noncommercial use under the PolyForm Noncommercial
+License 1.0.0, reproduced in full below. Commercial use requires a separate
+commercial license — to arrange one, open an issue at the repository above.
+
+================================================================================
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -0,0 +1,262 @@
+<p align="center">
+  <img src="cryptag-logo.png" alt="CrypTag" width="320">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@cryptag/sdk"><img src="https://img.shields.io/npm/v/@cryptag/sdk.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@cryptag/sdk"><img src="https://img.shields.io/node/v/@cryptag/sdk.svg" alt="node version"></a>
+  <a href="https://github.com/serdartpkl/cryptag/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue.svg" alt="PolyForm Noncommercial license"></a>
+</p>
+
+---
+
+**CrypTag** is a complete NTAG424 DNA toolkit: one half **programs** tags over a contactless
+reader, the other **verifies** the tap output they produce — sharing the same cryptographic
+core and a single, structured error model.
+
+- **Encoder** (`@cryptag/encoder`) — talk to a tag over a PC/SC reader: discover, authenticate
+  (EV2 & LRP), read/write files, configure SDM profiles, and manage keys (AN10922 diversification).
+- **Decoder** (`@cryptag/decoder`) — verify the SDM URL/token a tag produces (plain, encrypted and
+  full). No hardware required.
+
+`@cryptag/sdk` is the umbrella package that re-exports both. `@cryptag/crypto` (primitives) and
+`@cryptag/common` (error model and validation) are shared internals.
+
+```js
+import { CrypTagEncoder, CrypTagDecoder } from '@cryptag/sdk';
+```
+
+> 📖 You can find detailed documentation on [cryptag.io](https://cryptag.io).
+
+## Packages
+
+| Package | Role |
+|---|---|
+| `@cryptag/sdk` | Umbrella — re-exports `CrypTagEncoder` + `CrypTagDecoder` |
+| `@cryptag/encoder` | Tag programming over PC/SC |
+| `@cryptag/decoder` | SDM URL/token verification |
+| `@cryptag/crypto` | Shared AES/LRP/CMAC/diversification primitives |
+| `@cryptag/common` | Shared error model and argument validation |
+
+## Install
+
+```bash
+npm install @cryptag/sdk
+# …or just one half:
+npm install @cryptag/encoder
+npm install @cryptag/decoder
+```
+
+> The encoder needs a **PC/SC contactless reader**. Its native binding (`nfc-pcsc` →
+> `@pokusew/pcsclite`) is compiled on install. If you switch Node versions, rebuild it with
+> `npm run rebuild`. For **Electron**, build it for the Electron ABI with `npm run rebuild:electron`
+> (defaults to Electron 26; pass a version with `npm run rebuild:electron -- 28.2.0`).
+
+## Quick Start
+
+A tag carries its SDM data in one of two NDEF records: a **URL** (the chip emits a
+browser-openable link with the `picc_data`/`enc`/`cmac` query params) or a **text**
+record (a JSON blob your own app reads). The cryptography is identical — only the container
+differs, and `readNDEF` parses both into the same `sdmParams.params` (including the
+`cmacSeparator` the tag needs), so the decode call is the same for both.
+
+### URL Record
+
+Program a tag, read back the URL it emits, then verify that tap on your backend:
+
+```js
+import { CrypTagEncoder, CrypTagDecoder } from '@cryptag/sdk';
+
+const encoder = new CrypTagEncoder();
+await encoder.connect();
+
+// 'full' = encrypted PICC data + encrypted file data + CMAC. encodeTag discovers
+// the tag and authenticates with key 0 internally.
+await encoder.encodeTag('full', {
+  ndefType: 'url',               // 'url' or 'text'
+  url: 'https://cryptag.app/verify',
+  fileData: 'HELLO-FROM-CRYPTAG',// plain string encrypted into every tap
+  encSize: 128,                  // enc field length in hex chars (32/64/128)
+  counterLimit: 3000,            // SDM tap counter stops after 3000 taps
+  resetCounter: true,            // reset the counter to zero before encoding
+  enableTTStatus: false,         // TagTamper status mirroring (TagTamper variant only)
+  compressed: false,             // shorter URLs without parameter names
+  sdmSettings: null,             // advanced SDM access-right override
+});
+
+// encodeTag already re-discovered the new SDM config, so readNDEF sees it: the
+// chip fills the placeholders live and readNDEF parses them into separate fields.
+const ndef = await encoder.readNDEF();
+await encoder.disconnect();
+
+const sdm = ndef.data.sdmParams.params;   // { picc_data, enc, cmac, cmacSeparator } — ready for decodeFull
+
+// Verify and decode on your backend (no hardware).
+const decoder = new CrypTagDecoder({
+  keyList: {                               // keys must match the tag (factory = all-zero)
+    '2': { masterKey: '00000000000000000000000000000000', diversify: false },
+    '3': { masterKey: '00000000000000000000000000000000', diversify: false },
+  },
+  sdmSettings: { sdmMetaRead: 2, sdmFileRead: 3 },
+});
+
+const out = decoder.decodeFull(sdm);       // sdm.cmacSeparator wires the MAC input automatically
+if (out.success && out.data.cmacValid) {
+  console.log('authentic tap →', { uid: out.data.uid, counter: out.data.counter, file: out.data.fileData });
+}
+```
+
+`readNDEF` also hands you the full link at `ndef.data.url`.
+
+### Text Record
+
+Same `full` profile, but written as a JSON text record instead of a URL — drop `url`, set
+`ndefType: 'text'`. SDM builds the JSON itself, and the decode side is identical:
+
+```js
+import { CrypTagEncoder, CrypTagDecoder } from '@cryptag/sdk';
+
+const encoder = new CrypTagEncoder();
+await encoder.connect();
+
+// 'full' = encrypted PICC data + encrypted file data + CMAC. encodeTag discovers
+// the tag and authenticates with key 0 internally.
+await encoder.encodeTag('full', {
+  ndefType: 'text',              // JSON text record instead of a URL
+  fileData: 'HELLO-FROM-CRYPTAG',// plain string encrypted into every tap
+  encSize: 128,                  // enc field length in hex chars (32/64/128)
+  counterLimit: 3000,            // SDM tap counter stops after 3000 taps
+  resetCounter: true,            // reset the counter to zero before encoding
+  enableTTStatus: false,         // TagTamper status mirroring (TagTamper variant only)
+  compressed: false,             // shorter token instead of named fields
+  sdmSettings: null,             // advanced SDM access-right override
+});
+
+// encodeTag already re-discovered the new SDM config, so readNDEF sees it: the
+// chip fills the placeholders live and readNDEF parses them into separate fields.
+const ndef = await encoder.readNDEF();
+await encoder.disconnect();
+
+const sdm = ndef.data.sdmParams.params;   // same shape (incl. cmacSeparator) as the URL case
+
+// Verify and decode on your backend (no hardware).
+const decoder = new CrypTagDecoder({
+  keyList: {                               // keys must match the tag (factory = all-zero)
+    '2': { masterKey: '00000000000000000000000000000000', diversify: false },
+    '3': { masterKey: '00000000000000000000000000000000', diversify: false },
+  },
+  sdmSettings: { sdmMetaRead: 2, sdmFileRead: 3 },
+});
+
+const out = decoder.decodeFull(sdm);       // identical to the URL example
+if (out.success && out.data.cmacValid) {
+  console.log('authentic tap →', { uid: out.data.uid, counter: out.data.counter, file: out.data.fileData });
+}
+```
+
+`readNDEF` hands you the raw record at `ndef.data.text` (e.g. `{"picc_data":"…","enc":"…","cmac":"…"}`).
+
+## Commands
+
+NTAG424 DNA commands implemented, by communication mode. The full per-method API (encoder +
+decoder), with examples, lives in the **[documentation](https://cryptag.io)**.
+
+**Authentication (4 Commands)**
+- EV2First
+- LRPFirst
+- EV2NonFirst
+- LRPNonFirst
+
+**Plain Mode (10 Commands)**
+- GetFileSettings
+- ChangeFileSettings
+- GetFileCounters
+- GetVersion
+- ISOReadBinary
+- ISOSelectFile
+- ISOUpdateBinary
+- ReadData
+- WriteData
+- ReadSig
+
+**MAC Mode (7 Commands)**
+- GetFileSettings
+- ChangeFileSettings
+- GetFileCounters
+- GetKeyVersion
+- GetVersion
+- ReadData
+- WriteData
+
+**Full Mode (11 Commands)**
+- ChangeKey
+- ChangeKey0
+- ChangeFileSettings
+- GetCardUID
+- GetFileCounters
+- ReadData
+- WriteData
+- ReadSig
+- SetConfiguration (FailedCtr)
+- SetConfiguration (RandomID)
+- SetConfiguration (LRP)
+
+**Total: 37 commands** (some appear in multiple communication modes with distinct implementations).
+
+## Results and Errors
+
+**Both halves** return the same result shape (`duration` in ms is added on encoder tag operations):
+
+```js
+{ success: true,  data: { /* method-specific */ }, duration: 12 }
+{ success: false, error: { code, message, details? } }
+```
+
+For the **decoder**, `data` holds `{ cmacValid, uid, counter, … }`. `success: true` means the decode
+ran — **authenticity is `data.cmacValid`**, so always check it (a tap can decode cleanly yet still fail
+CMAC verification). A hard failure (bad input or a decode error) returns `{ success: false, error }`.
+
+`error.code` is shared across both halves:
+
+| Code | Category | When it happens |
+|---|---|---|
+| `E100` | Connection | Reader, card, or transport problem (no reader, no card, discovery failed) |
+| `E200` | Authentication | Wrong key, MAC mismatch, permission denied, or auth temporarily blocked |
+| `E300` | Command | A tag command did not complete (select, read/write, change key/settings) |
+| `E400` | Validation | Bad argument or configuration (encoder + decoder) |
+| `E500` | Unknown | Unmapped/unexpected error |
+| `E600` | Decoding | A decode could not be completed (decoder: malformed data or a key/config problem) |
+
+When a failure originates at the tag, its ISO/NTAG424 status word (e.g. `911E`, `919D`, `91AE`) is
+translated into one of the categories above with a descriptive `message`. A result's `error` is always
+a **plain object** `{ code, message, details? }` — no stack, no class — so it logs and `JSON.stringify`s
+identically. (Internally the SDK throws a `CrypTagError`, but that never leaks into a result.)
+
+## How They Fit Together
+
+`encodeTag()` configures a tag so that, on each tap, it emits a URL containing SDM placeholders
+(`picc_data`, `enc`, `cmac`, …). Your backend parses those query parameters and passes them to the
+matching decoder method (`decodePlain`/`decodeEncrypted`/`decodeFull`), which verifies the CMAC
+and returns the UID, the tap counter, and — for the full profile — the decrypted file data.
+
+## Requirements
+
+- Node.js ≥ 14 (ES modules).
+- Encoder only: a PC/SC contactless reader (e.g. ACR122U) and an NTAG424 DNA tag.
+
+## Development
+
+This is an npm-workspaces monorepo. From the repo root:
+
+```bash
+npm install            # install + link all workspaces
+npm run types          # type-check/emit .d.ts for all packages
+npm run rebuild        # rebuild the encoder's native binding for Node
+npm run rebuild:electron   # …or for the Electron ABI
+```
+
+## License
+
+[PolyForm Noncommercial License 1.0.0](LICENSE) © Serdar Tepekule.
+
+Free for noncommercial use. **Commercial use requires a separate license** — open an issue on [GitHub](https://github.com/serdartpkl/cryptag) to arrange one.

package/cryptag.js

@@ -0,0 +1,16 @@
+/**
+ * @cryptag/sdk — umbrella package re-exporting the encoder and decoder.
+ *
+ *   import { CrypTagEncoder, CrypTagDecoder } from '@cryptag/sdk';
+ *
+ * @cryptag/crypto is an internal dependency of the two and is intentionally
+ * NOT re-exported here.
+ */
+
+import { CrypTagEncoder } from '@cryptag/encoder';
+import { CrypTagDecoder } from '@cryptag/decoder';
+
+export { CrypTagEncoder, CrypTagDecoder };
+
+/** @hidden */
+export default { CrypTagEncoder, CrypTagDecoder };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@cryptag/sdk",
+  "version": "2.0.2",
+  "description": "CrypTag — NTAG424 DNA Toolkit",
+  "type": "module",
+  "main": "cryptag.js",
+  "types": "types/cryptag.d.ts",
+  "exports": {
+    ".": "./cryptag.js"
+  },
+  "scripts": {
+    "rebuild": "node scripts/rebuild.mjs",
+    "rebuild:electron": "node scripts/rebuild.mjs -e",
+    "types": "tsc -p packages/common/tsconfig.json && tsc -p packages/crypto/tsconfig.json && tsc -p packages/decoder/tsconfig.json && tsc -p packages/encoder/tsconfig.json && tsc -p tsconfig.json",
+    "docs": "npm run build --prefix docs",
+    "prepack": "node -e \"require('fs').rmSync('types',{recursive:true,force:true})\" && tsc -p tsconfig.json"
+  },
+  "workspaces": [
+    "packages/common",
+    "packages/crypto",
+    "packages/encoder",
+    "packages/decoder"
+  ],
+  "keywords": [
+    "nfc",
+    "ntag424",
+    "sdm",
+    "lrp",
+    "ev2"
+  ],
+  "author": "Serdar Tepekule",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/serdartpkl/cryptag.git"
+  },
+  "homepage": "https://cryptag.io",
+  "bugs": "https://github.com/serdartpkl/cryptag/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "cryptag.js",
+    "types/"
+  ],
+  "dependencies": {
+    "@cryptag/decoder": "2.0.2",
+    "@cryptag/encoder": "2.0.2"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/types/cryptag.d.ts

@@ -0,0 +1,8 @@
+declare namespace _default {
+    export { CrypTagEncoder };
+    export { CrypTagDecoder };
+}
+export default _default;
+import { CrypTagEncoder } from '@cryptag/encoder';
+import { CrypTagDecoder } from '@cryptag/decoder';
+export { CrypTagEncoder, CrypTagDecoder };