@huitl/sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,179 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  aesCmac: () => aesCmac,
+  decryptPiccData: () => decryptPiccData,
+  deriveSessionKey: () => deriveSessionKey,
+  parseSunMessage: () => parseSunMessage,
+  verifySun: () => verifySun
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/crypto/aes-cmac.ts
+var import_crypto2 = __toESM(require("crypto"), 1);
+
+// src/constants.ts
+var ZERO = Buffer.alloc(16, 0);
+var RB = Buffer.from("00000000000000000000000000000087", "hex");
+
+// src/crypto/primitives.ts
+var import_crypto = __toESM(require("crypto"), 1);
+function xor(a, b) {
+  const r = Buffer.alloc(a.length);
+  for (let i = 0; i < a.length; i++) r[i] = a[i] ^ b[i];
+  return r;
+}
+function leftShift(buf) {
+  const r = Buffer.alloc(buf.length);
+  let carry = 0;
+  for (let i = buf.length - 1; i >= 0; i--) {
+    r[i] = (buf[i] << 1 | carry) & 255;
+    carry = buf[i] >> 7 & 1;
+  }
+  return r;
+}
+function subKeys(key) {
+  const c = import_crypto.default.createCipheriv("aes-128-ecb", key, null);
+  c.setAutoPadding(false);
+  const l = Buffer.concat([c.update(Buffer.alloc(16, 0)), c.final()]);
+  let k1 = leftShift(l);
+  if (l[0] & 128) k1 = xor(k1, RB);
+  let k2 = leftShift(k1);
+  if (k1[0] & 128) k2 = xor(k2, RB);
+  return { k1, k2 };
+}
+
+// src/crypto/aes-cmac.ts
+function aesCmac(key, msg) {
+  const { k1, k2 } = subKeys(key);
+  const n = msg.length === 0 ? 1 : Math.ceil(msg.length / 16);
+  const complete = msg.length > 0 && msg.length % 16 === 0;
+  const padded = Buffer.alloc(n * 16, 0);
+  msg.copy(padded);
+  if (!complete) padded[msg.length] = 128;
+  const last = (n - 1) * 16;
+  xor(padded.subarray(last, last + 16), complete ? k1 : k2).copy(padded, last);
+  const c = import_crypto2.default.createCipheriv("aes-128-cbc", key, ZERO);
+  c.setAutoPadding(false);
+  const enc = Buffer.concat([c.update(padded), c.final()]);
+  return enc.subarray(enc.length - 16);
+}
+
+// src/crypto/decrypt.ts
+var import_crypto3 = __toESM(require("crypto"), 1);
+function decryptPiccData(key, enc) {
+  const d = import_crypto3.default.createDecipheriv("aes-128-cbc", key, ZERO);
+  d.setAutoPadding(false);
+  const dec = Buffer.concat([d.update(enc), d.final()]);
+  return {
+    uid: dec.subarray(1, 8).toString("hex").toUpperCase(),
+    readCounter: dec.readUIntLE(8, 3)
+  };
+}
+
+// src/crypto/session-key.ts
+function deriveSessionKey(sdmKey, uid, counter, isMac) {
+  const ctrLE = Buffer.alloc(3);
+  ctrLE.writeUIntLE(counter, 0, 3);
+  const label = isMac ? Buffer.from([60, 195, 0, 1, 0, 128]) : Buffer.from([195, 60, 0, 1, 0, 128]);
+  return aesCmac(sdmKey, Buffer.concat([label, uid, ctrLE]));
+}
+
+// src/crypto/verify.ts
+var import_crypto4 = __toESM(require("crypto"), 1);
+
+// src/crypto/truncate.ts
+function truncate(cmac) {
+  const t = Buffer.alloc(8);
+  for (let i = 0; i < 8; i++) t[i] = cmac[i * 2 + 1];
+  return t;
+}
+
+// src/crypto/verify.ts
+function verifySun(sdmKey, encPiccData, cmac, macInput) {
+  const picc = decryptPiccData(sdmKey, encPiccData);
+  const uid = Buffer.from(picc.uid, "hex");
+  const sk = deriveSessionKey(sdmKey, uid, picc.readCounter, true);
+  const expected = truncate(aesCmac(sk, macInput));
+  const valid = import_crypto4.default.timingSafeEqual(expected, cmac);
+  return { valid, uid: picc.uid, readCounter: picc.readCounter };
+}
+
+// src/url/parse.ts
+function parseSunMessage(fullUrl) {
+  let url;
+  try {
+    url = new URL(fullUrl);
+  } catch {
+    throw new Error("Invalid URL format");
+  }
+  const piccHex = url.searchParams.get("picc_data");
+  const cmacHex = url.searchParams.get("cmac");
+  if (!piccHex) {
+    throw new Error("Missing required parameter: picc_data");
+  }
+  if (!cmacHex) {
+    throw new Error("Missing required parameter: cmac");
+  }
+  if (piccHex.length !== 32) {
+    throw new Error(
+      `Invalid picc_data length: expected 32 hex characters, got ${piccHex.length}`
+    );
+  }
+  if (cmacHex.length !== 16) {
+    throw new Error(
+      `Invalid cmac length: expected 16 hex characters, got ${cmacHex.length}`
+    );
+  }
+  if (!/^[0-9a-fA-F]+$/.test(piccHex)) {
+    throw new Error("Invalid picc_data: not valid hexadecimal");
+  }
+  if (!/^[0-9a-fA-F]+$/.test(cmacHex)) {
+    throw new Error("Invalid cmac: not valid hexadecimal");
+  }
+  const piccDataPos = fullUrl.indexOf(piccHex);
+  const cmacPos = fullUrl.indexOf(cmacHex);
+  return {
+    encPiccData: Buffer.from(piccHex, "hex"),
+    cmac: Buffer.from(cmacHex, "hex"),
+    macInput: Buffer.from(fullUrl.substring(piccDataPos, cmacPos), "ascii")
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  aesCmac,
+  decryptPiccData,
+  deriveSessionKey,
+  parseSunMessage,
+  verifySun
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/crypto/aes-cmac.ts","../src/constants.ts","../src/crypto/primitives.ts","../src/crypto/decrypt.ts","../src/crypto/session-key.ts","../src/crypto/verify.ts","../src/crypto/truncate.ts","../src/url/parse.ts"],"sourcesContent":["export { aesCmac, decryptPiccData, deriveSessionKey, verifySun } from \"./crypto/index.js\";\nexport { parseSunMessage } from \"./url/index.js\";\nexport type { PiccData, VerifyResult, SunMessage } from \"./types.js\";\n","import crypto from \"crypto\";\nimport { ZERO } from \"../constants.js\";\nimport { xor, subKeys } from \"./primitives.js\";\n\n/** Compute AES-CMAC per RFC 4493 */\nexport function aesCmac(key: Buffer, msg: Buffer): Buffer {\n  const { k1, k2 } = subKeys(key);\n  const n = msg.length === 0 ? 1 : Math.ceil(msg.length / 16);\n  const complete = msg.length > 0 && msg.length % 16 === 0;\n  const padded = Buffer.alloc(n * 16, 0);\n  msg.copy(padded);\n  if (!complete) padded[msg.length] = 0x80;\n  const last = (n - 1) * 16;\n  xor(padded.subarray(last, last + 16), complete ? k1 : k2).copy(padded, last);\n  const c = crypto.createCipheriv(\"aes-128-cbc\", key, ZERO);\n  c.setAutoPadding(false);\n  const enc = Buffer.concat([c.update(padded), c.final()]);\n  return enc.subarray(enc.length - 16);\n}\n","/** 16-byte zero buffer used as IV for AES-CBC operations */\nexport const ZERO = Buffer.alloc(16, 0);\n\n/** AES-CMAC polynomial constant Rb for 128-bit block size (RFC 4493) */\nexport const RB = Buffer.from(\"00000000000000000000000000000087\", \"hex\");\n","import crypto from \"crypto\";\nimport { RB } from \"../constants.js\";\n\nexport function xor(a: Buffer, b: Buffer): Buffer {\n  const r = Buffer.alloc(a.length);\n  for (let i = 0; i < a.length; i++) r[i] = a[i] ^ b[i];\n  return r;\n}\n\nexport function leftShift(buf: Buffer): Buffer {\n  const r = Buffer.alloc(buf.length);\n  let carry = 0;\n  for (let i = buf.length - 1; i >= 0; i--) {\n    r[i] = ((buf[i] << 1) | carry) & 0xff;\n    carry = (buf[i] >> 7) & 1;\n  }\n  return r;\n}\n\nexport function subKeys(key: Buffer): { k1: Buffer; k2: Buffer } {\n  const c = crypto.createCipheriv(\"aes-128-ecb\", key, null);\n  c.setAutoPadding(false);\n  const l = Buffer.concat([c.update(Buffer.alloc(16, 0)), c.final()]);\n  let k1 = leftShift(l);\n  if (l[0] & 0x80) k1 = xor(k1, RB);\n  let k2 = leftShift(k1);\n  if (k1[0] & 0x80) k2 = xor(k2, RB);\n  return { k1, k2 };\n}\n","import crypto from \"crypto\";\nimport { ZERO } from \"../constants.js\";\nimport type { PiccData } from \"../types.js\";\n\n/** Decrypt encrypted PICC data from an NTAG 424 DNA chip (AES-128-CBC, zero IV) */\nexport function decryptPiccData(key: Buffer, enc: Buffer): PiccData {\n  const d = crypto.createDecipheriv(\"aes-128-cbc\", key, ZERO);\n  d.setAutoPadding(false);\n  const dec = Buffer.concat([d.update(enc), d.final()]);\n  // PICCData format: [0xC7 tag byte] [7-byte UID] [3-byte ReadCtr LE] [padding]\n  return {\n    uid: dec.subarray(1, 8).toString(\"hex\").toUpperCase(),\n    readCounter: dec.readUIntLE(8, 3),\n  };\n}\n","import { aesCmac } from \"./aes-cmac.js\";\n\n/**\n * Derive a session key for SDM MAC or ENC operations.\n * Uses the SV (Session Vector) construction per NXP AN12196.\n */\nexport function deriveSessionKey(\n  sdmKey: Buffer,\n  uid: Buffer,\n  counter: number,\n  isMac: boolean\n): Buffer {\n  const ctrLE = Buffer.alloc(3);\n  ctrLE.writeUIntLE(counter, 0, 3);\n  const label = isMac\n    ? Buffer.from([0x3c, 0xc3, 0x00, 0x01, 0x00, 0x80])\n    : Buffer.from([0xc3, 0x3c, 0x00, 0x01, 0x00, 0x80]);\n  return aesCmac(sdmKey, Buffer.concat([label, uid, ctrLE]));\n}\n","import crypto from \"crypto\";\nimport type { VerifyResult } from \"../types.js\";\nimport { decryptPiccData } from \"./decrypt.js\";\nimport { deriveSessionKey } from \"./session-key.js\";\nimport { aesCmac } from \"./aes-cmac.js\";\nimport { truncate } from \"./truncate.js\";\n\n/**\n * Verify a SUN (Secure Unique NFC) message from an NTAG 424 DNA chip.\n *\n * @param sdmKey - The SDM meta-read key (AES-128, 16 bytes)\n * @param encPiccData - Encrypted PICC data from the URL (16 bytes)\n * @param cmac - Truncated CMAC from the URL (8 bytes)\n * @param macInput - The portion of the URL used as MAC input\n */\nexport function verifySun(\n  sdmKey: Buffer,\n  encPiccData: Buffer,\n  cmac: Buffer,\n  macInput: Buffer\n): VerifyResult {\n  const picc = decryptPiccData(sdmKey, encPiccData);\n  const uid = Buffer.from(picc.uid, \"hex\");\n  const sk = deriveSessionKey(sdmKey, uid, picc.readCounter, true);\n  const expected = truncate(aesCmac(sk, macInput));\n  const valid = crypto.timingSafeEqual(expected, cmac);\n  return { valid, uid: picc.uid, readCounter: picc.readCounter };\n}\n","/** Truncate a 16-byte CMAC to 8 bytes per NTAG 424 DNA spec (odd-indexed bytes) */\nexport function truncate(cmac: Buffer): Buffer {\n  const t = Buffer.alloc(8);\n  for (let i = 0; i < 8; i++) t[i] = cmac[i * 2 + 1];\n  return t;\n}\n","import type { SunMessage } from \"../types.js\";\n\n/**\n * Parse a SUN message URL from an NTAG 424 DNA chip.\n * Extracts the encrypted PICC data, CMAC, and MAC input from the URL.\n *\n * @param fullUrl - The complete URL produced by the NFC chip tap\n * @returns Parsed SUN message components\n * @throws {Error} If the URL is missing required parameters or has invalid format\n */\nexport function parseSunMessage(fullUrl: string): SunMessage {\n  let url: URL;\n  try {\n    url = new URL(fullUrl);\n  } catch {\n    throw new Error(\"Invalid URL format\");\n  }\n\n  const piccHex = url.searchParams.get(\"picc_data\");\n  const cmacHex = url.searchParams.get(\"cmac\");\n\n  if (!piccHex) {\n    throw new Error(\"Missing required parameter: picc_data\");\n  }\n  if (!cmacHex) {\n    throw new Error(\"Missing required parameter: cmac\");\n  }\n  if (piccHex.length !== 32) {\n    throw new Error(\n      `Invalid picc_data length: expected 32 hex characters, got ${piccHex.length}`\n    );\n  }\n  if (cmacHex.length !== 16) {\n    throw new Error(\n      `Invalid cmac length: expected 16 hex characters, got ${cmacHex.length}`\n    );\n  }\n  if (!/^[0-9a-fA-F]+$/.test(piccHex)) {\n    throw new Error(\"Invalid picc_data: not valid hexadecimal\");\n  }\n  if (!/^[0-9a-fA-F]+$/.test(cmacHex)) {\n    throw new Error(\"Invalid cmac: not valid hexadecimal\");\n  }\n\n  const piccDataPos = fullUrl.indexOf(piccHex);\n  const cmacPos = fullUrl.indexOf(cmacHex);\n\n  return {\n    encPiccData: Buffer.from(piccHex, \"hex\"),\n    cmac: Buffer.from(cmacHex, \"hex\"),\n    macInput: Buffer.from(fullUrl.substring(piccDataPos, cmacPos), \"ascii\"),\n  };\n}\n"],"mappings":"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","names":["import_crypto","crypto","crypto","import_crypto","crypto","import_crypto","crypto"]}

package/dist/index.d.cts

@@ -0,0 +1,59 @@
+/** Compute AES-CMAC per RFC 4493 */
+declare function aesCmac(key: Buffer, msg: Buffer): Buffer;
+
+/** Decrypted PICC data from an NTAG 424 DNA chip */
+interface PiccData {
+    /** 7-byte UID as uppercase hex (14 characters) */
+    uid: string;
+    /** SDM read counter value */
+    readCounter: number;
+}
+/** Result of SUN message verification */
+interface VerifyResult {
+    /** Whether the CMAC signature is valid */
+    valid: boolean;
+    /** Chip UID as uppercase hex */
+    uid: string;
+    /** SDM read counter value */
+    readCounter: number;
+}
+/** Parsed SUN (Secure Unique NFC) message components */
+interface SunMessage {
+    /** Encrypted PICC data (16 bytes) */
+    encPiccData: Buffer;
+    /** Truncated CMAC signature (8 bytes) */
+    cmac: Buffer;
+    /** The portion of the URL used as MAC input */
+    macInput: Buffer;
+}
+
+/** Decrypt encrypted PICC data from an NTAG 424 DNA chip (AES-128-CBC, zero IV) */
+declare function decryptPiccData(key: Buffer, enc: Buffer): PiccData;
+
+/**
+ * Derive a session key for SDM MAC or ENC operations.
+ * Uses the SV (Session Vector) construction per NXP AN12196.
+ */
+declare function deriveSessionKey(sdmKey: Buffer, uid: Buffer, counter: number, isMac: boolean): Buffer;
+
+/**
+ * Verify a SUN (Secure Unique NFC) message from an NTAG 424 DNA chip.
+ *
+ * @param sdmKey - The SDM meta-read key (AES-128, 16 bytes)
+ * @param encPiccData - Encrypted PICC data from the URL (16 bytes)
+ * @param cmac - Truncated CMAC from the URL (8 bytes)
+ * @param macInput - The portion of the URL used as MAC input
+ */
+declare function verifySun(sdmKey: Buffer, encPiccData: Buffer, cmac: Buffer, macInput: Buffer): VerifyResult;
+
+/**
+ * Parse a SUN message URL from an NTAG 424 DNA chip.
+ * Extracts the encrypted PICC data, CMAC, and MAC input from the URL.
+ *
+ * @param fullUrl - The complete URL produced by the NFC chip tap
+ * @returns Parsed SUN message components
+ * @throws {Error} If the URL is missing required parameters or has invalid format
+ */
+declare function parseSunMessage(fullUrl: string): SunMessage;
+
+export { type PiccData, type SunMessage, type VerifyResult, aesCmac, decryptPiccData, deriveSessionKey, parseSunMessage, verifySun };

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/** Compute AES-CMAC per RFC 4493 */
+declare function aesCmac(key: Buffer, msg: Buffer): Buffer;
+
+/** Decrypted PICC data from an NTAG 424 DNA chip */
+interface PiccData {
+    /** 7-byte UID as uppercase hex (14 characters) */
+    uid: string;
+    /** SDM read counter value */
+    readCounter: number;
+}
+/** Result of SUN message verification */
+interface VerifyResult {
+    /** Whether the CMAC signature is valid */
+    valid: boolean;
+    /** Chip UID as uppercase hex */
+    uid: string;
+    /** SDM read counter value */
+    readCounter: number;
+}
+/** Parsed SUN (Secure Unique NFC) message components */
+interface SunMessage {
+    /** Encrypted PICC data (16 bytes) */
+    encPiccData: Buffer;
+    /** Truncated CMAC signature (8 bytes) */
+    cmac: Buffer;
+    /** The portion of the URL used as MAC input */
+    macInput: Buffer;
+}
+
+/** Decrypt encrypted PICC data from an NTAG 424 DNA chip (AES-128-CBC, zero IV) */
+declare function decryptPiccData(key: Buffer, enc: Buffer): PiccData;
+
+/**
+ * Derive a session key for SDM MAC or ENC operations.
+ * Uses the SV (Session Vector) construction per NXP AN12196.
+ */
+declare function deriveSessionKey(sdmKey: Buffer, uid: Buffer, counter: number, isMac: boolean): Buffer;
+
+/**
+ * Verify a SUN (Secure Unique NFC) message from an NTAG 424 DNA chip.
+ *
+ * @param sdmKey - The SDM meta-read key (AES-128, 16 bytes)
+ * @param encPiccData - Encrypted PICC data from the URL (16 bytes)
+ * @param cmac - Truncated CMAC from the URL (8 bytes)
+ * @param macInput - The portion of the URL used as MAC input
+ */
+declare function verifySun(sdmKey: Buffer, encPiccData: Buffer, cmac: Buffer, macInput: Buffer): VerifyResult;
+
+/**
+ * Parse a SUN message URL from an NTAG 424 DNA chip.
+ * Extracts the encrypted PICC data, CMAC, and MAC input from the URL.
+ *
+ * @param fullUrl - The complete URL produced by the NFC chip tap
+ * @returns Parsed SUN message components
+ * @throws {Error} If the URL is missing required parameters or has invalid format
+ */
+declare function parseSunMessage(fullUrl: string): SunMessage;
+
+export { type PiccData, type SunMessage, type VerifyResult, aesCmac, decryptPiccData, deriveSessionKey, parseSunMessage, verifySun };

package/dist/index.js

@@ -0,0 +1,138 @@
+// src/crypto/aes-cmac.ts
+import crypto2 from "crypto";
+
+// src/constants.ts
+var ZERO = Buffer.alloc(16, 0);
+var RB = Buffer.from("00000000000000000000000000000087", "hex");
+
+// src/crypto/primitives.ts
+import crypto from "crypto";
+function xor(a, b) {
+  const r = Buffer.alloc(a.length);
+  for (let i = 0; i < a.length; i++) r[i] = a[i] ^ b[i];
+  return r;
+}
+function leftShift(buf) {
+  const r = Buffer.alloc(buf.length);
+  let carry = 0;
+  for (let i = buf.length - 1; i >= 0; i--) {
+    r[i] = (buf[i] << 1 | carry) & 255;
+    carry = buf[i] >> 7 & 1;
+  }
+  return r;
+}
+function subKeys(key) {
+  const c = crypto.createCipheriv("aes-128-ecb", key, null);
+  c.setAutoPadding(false);
+  const l = Buffer.concat([c.update(Buffer.alloc(16, 0)), c.final()]);
+  let k1 = leftShift(l);
+  if (l[0] & 128) k1 = xor(k1, RB);
+  let k2 = leftShift(k1);
+  if (k1[0] & 128) k2 = xor(k2, RB);
+  return { k1, k2 };
+}
+
+// src/crypto/aes-cmac.ts
+function aesCmac(key, msg) {
+  const { k1, k2 } = subKeys(key);
+  const n = msg.length === 0 ? 1 : Math.ceil(msg.length / 16);
+  const complete = msg.length > 0 && msg.length % 16 === 0;
+  const padded = Buffer.alloc(n * 16, 0);
+  msg.copy(padded);
+  if (!complete) padded[msg.length] = 128;
+  const last = (n - 1) * 16;
+  xor(padded.subarray(last, last + 16), complete ? k1 : k2).copy(padded, last);
+  const c = crypto2.createCipheriv("aes-128-cbc", key, ZERO);
+  c.setAutoPadding(false);
+  const enc = Buffer.concat([c.update(padded), c.final()]);
+  return enc.subarray(enc.length - 16);
+}
+
+// src/crypto/decrypt.ts
+import crypto3 from "crypto";
+function decryptPiccData(key, enc) {
+  const d = crypto3.createDecipheriv("aes-128-cbc", key, ZERO);
+  d.setAutoPadding(false);
+  const dec = Buffer.concat([d.update(enc), d.final()]);
+  return {
+    uid: dec.subarray(1, 8).toString("hex").toUpperCase(),
+    readCounter: dec.readUIntLE(8, 3)
+  };
+}
+
+// src/crypto/session-key.ts
+function deriveSessionKey(sdmKey, uid, counter, isMac) {
+  const ctrLE = Buffer.alloc(3);
+  ctrLE.writeUIntLE(counter, 0, 3);
+  const label = isMac ? Buffer.from([60, 195, 0, 1, 0, 128]) : Buffer.from([195, 60, 0, 1, 0, 128]);
+  return aesCmac(sdmKey, Buffer.concat([label, uid, ctrLE]));
+}
+
+// src/crypto/verify.ts
+import crypto4 from "crypto";
+
+// src/crypto/truncate.ts
+function truncate(cmac) {
+  const t = Buffer.alloc(8);
+  for (let i = 0; i < 8; i++) t[i] = cmac[i * 2 + 1];
+  return t;
+}
+
+// src/crypto/verify.ts
+function verifySun(sdmKey, encPiccData, cmac, macInput) {
+  const picc = decryptPiccData(sdmKey, encPiccData);
+  const uid = Buffer.from(picc.uid, "hex");
+  const sk = deriveSessionKey(sdmKey, uid, picc.readCounter, true);
+  const expected = truncate(aesCmac(sk, macInput));
+  const valid = crypto4.timingSafeEqual(expected, cmac);
+  return { valid, uid: picc.uid, readCounter: picc.readCounter };
+}
+
+// src/url/parse.ts
+function parseSunMessage(fullUrl) {
+  let url;
+  try {
+    url = new URL(fullUrl);
+  } catch {
+    throw new Error("Invalid URL format");
+  }
+  const piccHex = url.searchParams.get("picc_data");
+  const cmacHex = url.searchParams.get("cmac");
+  if (!piccHex) {
+    throw new Error("Missing required parameter: picc_data");
+  }
+  if (!cmacHex) {
+    throw new Error("Missing required parameter: cmac");
+  }
+  if (piccHex.length !== 32) {
+    throw new Error(
+      `Invalid picc_data length: expected 32 hex characters, got ${piccHex.length}`
+    );
+  }
+  if (cmacHex.length !== 16) {
+    throw new Error(
+      `Invalid cmac length: expected 16 hex characters, got ${cmacHex.length}`
+    );
+  }
+  if (!/^[0-9a-fA-F]+$/.test(piccHex)) {
+    throw new Error("Invalid picc_data: not valid hexadecimal");
+  }
+  if (!/^[0-9a-fA-F]+$/.test(cmacHex)) {
+    throw new Error("Invalid cmac: not valid hexadecimal");
+  }
+  const piccDataPos = fullUrl.indexOf(piccHex);
+  const cmacPos = fullUrl.indexOf(cmacHex);
+  return {
+    encPiccData: Buffer.from(piccHex, "hex"),
+    cmac: Buffer.from(cmacHex, "hex"),
+    macInput: Buffer.from(fullUrl.substring(piccDataPos, cmacPos), "ascii")
+  };
+}
+export {
+  aesCmac,
+  decryptPiccData,
+  deriveSessionKey,
+  parseSunMessage,
+  verifySun
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/crypto/aes-cmac.ts","../src/constants.ts","../src/crypto/primitives.ts","../src/crypto/decrypt.ts","../src/crypto/session-key.ts","../src/crypto/verify.ts","../src/crypto/truncate.ts","../src/url/parse.ts"],"sourcesContent":["import crypto from \"crypto\";\nimport { ZERO } from \"../constants.js\";\nimport { xor, subKeys } from \"./primitives.js\";\n\n/** Compute AES-CMAC per RFC 4493 */\nexport function aesCmac(key: Buffer, msg: Buffer): Buffer {\n  const { k1, k2 } = subKeys(key);\n  const n = msg.length === 0 ? 1 : Math.ceil(msg.length / 16);\n  const complete = msg.length > 0 && msg.length % 16 === 0;\n  const padded = Buffer.alloc(n * 16, 0);\n  msg.copy(padded);\n  if (!complete) padded[msg.length] = 0x80;\n  const last = (n - 1) * 16;\n  xor(padded.subarray(last, last + 16), complete ? k1 : k2).copy(padded, last);\n  const c = crypto.createCipheriv(\"aes-128-cbc\", key, ZERO);\n  c.setAutoPadding(false);\n  const enc = Buffer.concat([c.update(padded), c.final()]);\n  return enc.subarray(enc.length - 16);\n}\n","/** 16-byte zero buffer used as IV for AES-CBC operations */\nexport const ZERO = Buffer.alloc(16, 0);\n\n/** AES-CMAC polynomial constant Rb for 128-bit block size (RFC 4493) */\nexport const RB = Buffer.from(\"00000000000000000000000000000087\", \"hex\");\n","import crypto from \"crypto\";\nimport { RB } from \"../constants.js\";\n\nexport function xor(a: Buffer, b: Buffer): Buffer {\n  const r = Buffer.alloc(a.length);\n  for (let i = 0; i < a.length; i++) r[i] = a[i] ^ b[i];\n  return r;\n}\n\nexport function leftShift(buf: Buffer): Buffer {\n  const r = Buffer.alloc(buf.length);\n  let carry = 0;\n  for (let i = buf.length - 1; i >= 0; i--) {\n    r[i] = ((buf[i] << 1) | carry) & 0xff;\n    carry = (buf[i] >> 7) & 1;\n  }\n  return r;\n}\n\nexport function subKeys(key: Buffer): { k1: Buffer; k2: Buffer } {\n  const c = crypto.createCipheriv(\"aes-128-ecb\", key, null);\n  c.setAutoPadding(false);\n  const l = Buffer.concat([c.update(Buffer.alloc(16, 0)), c.final()]);\n  let k1 = leftShift(l);\n  if (l[0] & 0x80) k1 = xor(k1, RB);\n  let k2 = leftShift(k1);\n  if (k1[0] & 0x80) k2 = xor(k2, RB);\n  return { k1, k2 };\n}\n","import crypto from \"crypto\";\nimport { ZERO } from \"../constants.js\";\nimport type { PiccData } from \"../types.js\";\n\n/** Decrypt encrypted PICC data from an NTAG 424 DNA chip (AES-128-CBC, zero IV) */\nexport function decryptPiccData(key: Buffer, enc: Buffer): PiccData {\n  const d = crypto.createDecipheriv(\"aes-128-cbc\", key, ZERO);\n  d.setAutoPadding(false);\n  const dec = Buffer.concat([d.update(enc), d.final()]);\n  // PICCData format: [0xC7 tag byte] [7-byte UID] [3-byte ReadCtr LE] [padding]\n  return {\n    uid: dec.subarray(1, 8).toString(\"hex\").toUpperCase(),\n    readCounter: dec.readUIntLE(8, 3),\n  };\n}\n","import { aesCmac } from \"./aes-cmac.js\";\n\n/**\n * Derive a session key for SDM MAC or ENC operations.\n * Uses the SV (Session Vector) construction per NXP AN12196.\n */\nexport function deriveSessionKey(\n  sdmKey: Buffer,\n  uid: Buffer,\n  counter: number,\n  isMac: boolean\n): Buffer {\n  const ctrLE = Buffer.alloc(3);\n  ctrLE.writeUIntLE(counter, 0, 3);\n  const label = isMac\n    ? Buffer.from([0x3c, 0xc3, 0x00, 0x01, 0x00, 0x80])\n    : Buffer.from([0xc3, 0x3c, 0x00, 0x01, 0x00, 0x80]);\n  return aesCmac(sdmKey, Buffer.concat([label, uid, ctrLE]));\n}\n","import crypto from \"crypto\";\nimport type { VerifyResult } from \"../types.js\";\nimport { decryptPiccData } from \"./decrypt.js\";\nimport { deriveSessionKey } from \"./session-key.js\";\nimport { aesCmac } from \"./aes-cmac.js\";\nimport { truncate } from \"./truncate.js\";\n\n/**\n * Verify a SUN (Secure Unique NFC) message from an NTAG 424 DNA chip.\n *\n * @param sdmKey - The SDM meta-read key (AES-128, 16 bytes)\n * @param encPiccData - Encrypted PICC data from the URL (16 bytes)\n * @param cmac - Truncated CMAC from the URL (8 bytes)\n * @param macInput - The portion of the URL used as MAC input\n */\nexport function verifySun(\n  sdmKey: Buffer,\n  encPiccData: Buffer,\n  cmac: Buffer,\n  macInput: Buffer\n): VerifyResult {\n  const picc = decryptPiccData(sdmKey, encPiccData);\n  const uid = Buffer.from(picc.uid, \"hex\");\n  const sk = deriveSessionKey(sdmKey, uid, picc.readCounter, true);\n  const expected = truncate(aesCmac(sk, macInput));\n  const valid = crypto.timingSafeEqual(expected, cmac);\n  return { valid, uid: picc.uid, readCounter: picc.readCounter };\n}\n","/** Truncate a 16-byte CMAC to 8 bytes per NTAG 424 DNA spec (odd-indexed bytes) */\nexport function truncate(cmac: Buffer): Buffer {\n  const t = Buffer.alloc(8);\n  for (let i = 0; i < 8; i++) t[i] = cmac[i * 2 + 1];\n  return t;\n}\n","import type { SunMessage } from \"../types.js\";\n\n/**\n * Parse a SUN message URL from an NTAG 424 DNA chip.\n * Extracts the encrypted PICC data, CMAC, and MAC input from the URL.\n *\n * @param fullUrl - The complete URL produced by the NFC chip tap\n * @returns Parsed SUN message components\n * @throws {Error} If the URL is missing required parameters or has invalid format\n */\nexport function parseSunMessage(fullUrl: string): SunMessage {\n  let url: URL;\n  try {\n    url = new URL(fullUrl);\n  } catch {\n    throw new Error(\"Invalid URL format\");\n  }\n\n  const piccHex = url.searchParams.get(\"picc_data\");\n  const cmacHex = url.searchParams.get(\"cmac\");\n\n  if (!piccHex) {\n    throw new Error(\"Missing required parameter: picc_data\");\n  }\n  if (!cmacHex) {\n    throw new Error(\"Missing required parameter: cmac\");\n  }\n  if (piccHex.length !== 32) {\n    throw new Error(\n      `Invalid picc_data length: expected 32 hex characters, got ${piccHex.length}`\n    );\n  }\n  if (cmacHex.length !== 16) {\n    throw new Error(\n      `Invalid cmac length: expected 16 hex characters, got ${cmacHex.length}`\n    );\n  }\n  if (!/^[0-9a-fA-F]+$/.test(piccHex)) {\n    throw new Error(\"Invalid picc_data: not valid hexadecimal\");\n  }\n  if (!/^[0-9a-fA-F]+$/.test(cmacHex)) {\n    throw new Error(\"Invalid cmac: not valid hexadecimal\");\n  }\n\n  const piccDataPos = fullUrl.indexOf(piccHex);\n  const cmacPos = fullUrl.indexOf(cmacHex);\n\n  return {\n    encPiccData: Buffer.from(piccHex, \"hex\"),\n    cmac: Buffer.from(cmacHex, \"hex\"),\n    macInput: Buffer.from(fullUrl.substring(piccDataPos, cmacPos), \"ascii\"),\n  };\n}\n"],"mappings":"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","names":["crypto","crypto","crypto","crypto","crypto","crypto"]}

package/llms.txt

@@ -0,0 +1,59 @@
+# @huitl/sdk
+
+> NTAG 424 DNA cryptographic verification SDK for Node.js and TypeScript.
+
+## What it does
+
+This is the open-source SDK for the HUITL Protocol. It packages the cryptographic math needed to verify NFC taps from NTAG 424 DNA chips — the world's most deployed secure NFC chip (by NXP).
+
+When someone taps an NTAG 424 DNA chip with their phone, the chip generates a unique, one-time cryptographic message (called a SUN message) that includes an encrypted chip identity and a CMAC signature. This SDK parses, decrypts, and verifies that message.
+
+## Core functions
+
+- `parseSunMessage(url)` — Extract encrypted PICC data and CMAC from a tap URL
+- `verifySun(sdmKey, encPiccData, cmac, macInput)` — Full SUN verification (decrypt + CMAC check)
+- `decryptPiccData(key, enc)` — Decrypt encrypted PICC data to get UID and read counter
+- `deriveSessionKey(sdmKey, uid, counter, isMac)` — Derive session keys per NXP AN12196
+- `aesCmac(key, msg)` — AES-CMAC per RFC 4493
+
+## Installation
+
+```bash
+npm install @huitl/sdk
+```
+
+## Quick example
+
+```typescript
+import { parseSunMessage, verifySun } from "@huitl/sdk";
+
+const sdmKey = Buffer.from("your-32-char-hex-key", "hex");
+const parsed = parseSunMessage(tapUrl);
+const result = verifySun(sdmKey, parsed.encPiccData, parsed.cmac, parsed.macInput);
+// result: { valid: boolean, uid: string, readCounter: number }
+```
+
+## CLI tools
+
+- `huitl verify <url> --key <hex>` — Verify a SUN message URL
+- `huitl keygen [--count N]` — Generate test AES key + UID pairs
+- `huitl dev --local` — Start a local dev server with SQLite for testing
+- `huitl init` — Scaffold a new HUITL project
+
+## Key concepts
+
+- **SUN (Secure Unique NFC)**: NXP's protocol where each tap produces a unique encrypted+signed message
+- **PICC data**: Encrypted payload containing the chip's 7-byte UID and a rolling read counter
+- **SDM key**: The AES-128 key shared between the chip and the verification server
+- **Anti-replay**: The read counter increments on each tap and must always increase
+
+## Architecture
+
+Zero runtime dependencies for core crypto — uses only Node.js built-in `crypto` module.
+Optional dependencies (better-sqlite3, hono) are only needed for the `huitl dev` command.
+
+## Links
+
+- npm: https://www.npmjs.com/package/@huitl/sdk
+- GitHub: https://github.com/huitl/sdk
+- Protocol: https://huitl.com

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@huitl/sdk",
+  "version": "0.1.0",
+  "description": "NTAG 424 DNA cryptographic verification SDK — parse, decrypt, and verify NFC SUN messages",
+  "license": "MIT",
+  "author": "Fabio Seva <seva@huitlprotocol.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/huitl/sdk.git"
+  },
+  "keywords": [
+    "nfc",
+    "ntag424",
+    "ntag-424-dna",
+    "sun",
+    "aes-cmac",
+    "authentication",
+    "verification",
+    "nxp",
+    "picc",
+    "digital-product-passport",
+    "anti-counterfeiting",
+    "iot"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "huitl": "./dist/cli.cjs"
+  },
+  "files": [
+    "dist",
+    "llms.txt",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/node": "^22.0.0",
+    "better-sqlite3": "^11.0.0",
+    "commander": "^13.0.0",
+    "hono": "^4.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.0.0"
+  },
+  "peerDependencies": {
+    "better-sqlite3": ">=9.0.0",
+    "hono": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}