@revibase/ctap2-js 0.1.0

package/src/apdu.ts

@@ -0,0 +1,285 @@
+import {
+  FIDO_AID,
+  NFC_TX_CHUNK_SIZE,
+  SW1_MORE_DATA,
+  SW_NO_ERROR,
+} from "./constants";
+import { ApduError } from "./errors";
+
+const CLA_CHAIN = 0x10;
+
+/** CTAP2 error codes  */
+function formatCtapErrorMessage(code: number): string {
+  const hex = `0x${code.toString(16).padStart(2, "0")}`;
+  const names: Record<number, string> = {
+    0x01: "INVALID_COMMAND",
+    0x02: "INVALID_PARAMETER",
+    0x03: "INVALID_LENGTH",
+    0x11: "CBOR_UNEXPECTED_TYPE",
+    0x12: "INVALID_CBOR",
+    0x14: "MISSING_PARAMETER",
+    0x2e: "NO_CREDENTIALS",
+    0x30: "NOT_ALLOWED",
+  };
+  const name = names[code];
+  return name ? `CTAP error ${hex} (${name})` : `CTAP error code ${hex}`;
+}
+
+interface ParsedIso7816Response {
+  data: Uint8Array;
+  sw1: number;
+  sw2: number;
+  statusWord: number;
+}
+
+interface NfcShortApduSegment {
+  bytes: Uint8Array;
+  chained: boolean;
+}
+
+export function encodeExtendedCase3e(
+  cla: number,
+  ins: number,
+  p1: number,
+  p2: number,
+  data: Uint8Array,
+): Uint8Array {
+  const n = data.length;
+  if (n > 65535) {
+    throw new ApduError("APDU data field exceeds 65535 bytes");
+  }
+  const out = new Uint8Array(7 + n + 2);
+  out[0] = cla & 0xff;
+  out[1] = ins & 0xff;
+  out[2] = p1 & 0xff;
+  out[3] = p2 & 0xff;
+  out[4] = 0x00;
+  out[5] = (n >> 8) & 0xff;
+  out[6] = n & 0xff;
+  out.set(data, 7);
+  out[7 + n] = 0x00;
+  out[7 + n + 1] = 0x00;
+  return out;
+}
+
+export function encodeShortApdu(
+  cla: number,
+  ins: number,
+  p1: number,
+  p2: number,
+  payload: Uint8Array,
+  options: { chained: boolean },
+): Uint8Array {
+  const lc = payload.length;
+  if (lc > 255) {
+    throw new ApduError("short APDU payload must be ≤ 255 bytes");
+  }
+  const withLe = !options.chained;
+  const out = new Uint8Array(5 + lc + (withLe ? 1 : 0));
+  out[0] = (cla & 0xff) | (options.chained ? CLA_CHAIN : 0);
+  out[1] = ins & 0xff;
+  out[2] = p1 & 0xff;
+  out[3] = p2 & 0xff;
+  out[4] = lc & 0xff;
+  out.set(payload, 5);
+  if (withLe) {
+    out[5 + lc] = 0x00;
+  }
+  return out;
+}
+
+/**
+ * Send CTAP CBOR command APDUs
+ * Extended APDU in memory is split into short chained frames;
+ * Intermediate responses must be SW 0x9000, the last response carries CTAP payload + SW.
+ */
+export async function transmitCborApduSegments(
+  segments: NfcShortApduSegment[],
+  transceive: (apdu: Uint8Array) => Promise<Uint8Array>,
+): Promise<Uint8Array> {
+  let last: Uint8Array | undefined;
+  for (const seg of segments) {
+    const resp = await transceive(seg.bytes);
+    if (resp.length < 2) {
+      throw new ApduError(
+        `APDU response too short for status word (${resp.length} byte(s))`,
+      );
+    }
+    const sw = (resp[resp.length - 2] << 8) | resp[resp.length - 1];
+    if (seg.chained) {
+      if (sw !== SW_NO_ERROR) {
+        throw new ApduError(
+          `ISO7816 status 0x${sw.toString(16).padStart(4, "0")}`,
+        );
+      }
+    } else {
+      last = resp;
+    }
+  }
+  if (!last) {
+    throw new ApduError("no final APDU response");
+  }
+  return last;
+}
+
+/** Max GET RESPONSE iterations (matches practical NFC response sizes). */
+const GET_RESPONSE_MAX_CHAIN = 256;
+
+/**
+ * Follow ISO 7816 "more data" responses for CBOR:
+ * while SW1 == 0x61, send GET RESPONSE (CLA 0x80, INS 0xc0, Le = SW2) and
+ * concatenate response bodies; final buffer is payload + SW1 + SW2.
+ */
+export async function collectCborApduResponse(
+  firstResponse: Uint8Array,
+  transceive: (apdu: Uint8Array) => Promise<Uint8Array>,
+): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let cur = firstResponse;
+  for (let i = 0; i < GET_RESPONSE_MAX_CHAIN; i++) {
+    if (cur.length < 2) {
+      throw new ApduError("APDU response too short");
+    }
+    const sw1 = cur[cur.length - 2];
+    const sw2 = cur[cur.length - 1];
+    chunks.push(cur.slice(0, -2));
+    if (sw1 !== SW1_MORE_DATA) {
+      const totalLen = chunks.reduce((a, c) => a + c.length, 0) + 2;
+      const out = new Uint8Array(totalLen);
+      let o = 0;
+      for (const c of chunks) {
+        out.set(c, o);
+        o += c.length;
+      }
+      out[o] = sw1;
+      out[o + 1] = sw2;
+      return out;
+    }
+    cur = await transceive(buildGetResponseApdu(sw2, true));
+  }
+  throw new ApduError("GET RESPONSE chain exceeded limit");
+}
+
+/**
+ * Full NFC CTAP2 command exchange for Java Card–style FIDO applets: send short
+ * chained command frames ({@link transmitCborApduSegments}), then resolve
+ * `61 xx` / GET RESPONSE until `90 00` (same as libfido2 `nfc_do_tx` +
+ * `rx_msg`). Use after SELECT.
+ */
+export async function transceiveNfcCtap2Command(
+  segments: NfcShortApduSegment[],
+  transceive: (apdu: Uint8Array) => Promise<Uint8Array>,
+): Promise<Uint8Array> {
+  return collectCborApduResponse(
+    await transmitCborApduSegments(segments, transceive),
+    transceive,
+  );
+}
+
+export function splitExtendedApduForNfcTransmit(
+  extended: Uint8Array,
+  chunkSize: number = NFC_TX_CHUNK_SIZE,
+): NfcShortApduSegment[] {
+  if (extended.length < 9) {
+    throw new ApduError("extended APDU too short");
+  }
+  const cla = extended[0];
+  const ins = extended[1];
+  const p1 = extended[2];
+  const p2 = extended[3];
+  const data = extended.slice(7, extended.length - 2);
+  const segments: NfcShortApduSegment[] = [];
+  let off = 0;
+  while (data.length - off > chunkSize) {
+    const chunk = data.subarray(off, off + chunkSize);
+    segments.push({
+      bytes: encodeShortApdu(cla, ins, p1, p2, chunk, { chained: true }),
+      chained: true,
+    });
+    off += chunkSize;
+  }
+  const rest = data.subarray(off);
+  segments.push({
+    bytes: encodeShortApdu(cla, ins, p1, p2, rest, { chained: false }),
+    chained: false,
+  });
+  return segments;
+}
+
+export function buildSelectFidoApdu(): Uint8Array {
+  return encodeExtendedCase3e(0x00, 0xa4, 0x04, 0x00, FIDO_AID);
+}
+
+/** Short APDU(s) for SELECT — preferred over {@link buildSelectFidoApdu} on NFC. */
+export function buildSelectFidoApduSegments(): NfcShortApduSegment[] {
+  return splitExtendedApduForNfcTransmit(buildSelectFidoApdu());
+}
+
+export function buildCborCommandApdu(cborPayload: Uint8Array): Uint8Array {
+  return encodeExtendedCase3e(0x80, 0x10, 0x00, 0x00, cborPayload);
+}
+
+export function buildGetResponseApdu(le: number, cbor: boolean): Uint8Array {
+  const apdu = new Uint8Array(5);
+  apdu[0] = cbor ? 0x80 : 0x00;
+  apdu[1] = 0xc0;
+  apdu[2] = 0x00;
+  apdu[3] = 0x00;
+  apdu[4] = le & 0xff;
+  return apdu;
+}
+
+export function parseIso7816Response(buf: Uint8Array): ParsedIso7816Response {
+  if (buf.length < 2) {
+    throw new ApduError("response must include SW1 and SW2");
+  }
+  const sw1 = buf[buf.length - 2];
+  const sw2 = buf[buf.length - 1];
+  const statusWord = (sw1 << 8) | sw2;
+  return {
+    data: buf.slice(0, -2),
+    sw1,
+    sw2,
+    statusWord,
+  };
+}
+
+function isSuccessStatus(statusWord: number): boolean {
+  return statusWord === SW_NO_ERROR;
+}
+
+type ParseCtaphidCborBodyResult =
+  | { ok: true; cborMapBytes: Uint8Array }
+  | { ok: false; layer: "iso7816"; statusWord: number }
+  | { ok: false; layer: "ctap"; errorCode: number };
+
+export function parseCtaphidCborFromApduResponse(
+  apduResponseIncludingSw: Uint8Array,
+): ParseCtaphidCborBodyResult {
+  const { data, statusWord } = parseIso7816Response(apduResponseIncludingSw);
+  if (!isSuccessStatus(statusWord)) {
+    return { ok: false, layer: "iso7816", statusWord };
+  }
+  if (data.length < 1) {
+    throw new ApduError("empty CTAP payload after ISO7816 success");
+  }
+  const status = data[0];
+  if (status !== 0) {
+    return { ok: false, layer: "ctap", errorCode: status };
+  }
+  return { ok: true, cborMapBytes: data.subarray(1) };
+}
+
+export function unwrapCtaphidCborBody(
+  parsed: ParseCtaphidCborBodyResult,
+): Uint8Array {
+  if (!parsed.ok) {
+    if (parsed.layer === "iso7816") {
+      throw new ApduError(
+        `ISO7816 status 0x${parsed.statusWord.toString(16).padStart(4, "0")}`,
+      );
+    }
+    throw new ApduError(formatCtapErrorMessage(parsed.errorCode));
+  }
+  return parsed.cborMapBytes;
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+export const NFC_TX_CHUNK_SIZE = 240;
+
+export const FIDO_AID = Uint8Array.from([
+  0xa0, 0x00, 0x00, 0x06, 0x47, 0x2f, 0x00, 0x01,
+]);
+
+export const CTAP_CMD_MSG = 0x03;
+export const CTAP_CMD_INIT = 0x06;
+export const CTAP_CMD_CBOR = 0x10;
+
+export const CTAP_CBOR_MAKE_CRED = 0x01;
+export const CTAP_CBOR_ASSERT = 0x02;
+export const CTAP_CBOR_GETINFO = 0x04;
+
+export const SW_NO_ERROR = 0x9000;
+export const SW1_MORE_DATA = 0x61;

package/src/ctap2/cborUtils.ts

@@ -0,0 +1,155 @@
+import { Encoder } from "cbor-x";
+
+/**
+ * cbor-x encodes JS `Map` with CBOR tag 259 by default. CTAP2/FIDO2 expects a
+ * plain CBOR map (no tag), or authenticators return FIDO_ERR_CBOR_UNEXPECTED_TYPE (0x11).
+ */
+const ctapCborEncoder = new Encoder({
+	useTag259ForMaps: false,
+	useRecords: false,
+	mapsAsObjects: true,
+	structuredClone: false,
+	tagUint8Array: false,
+	bundleStrings: false,
+} as ConstructorParameters<typeof Encoder>[0]);
+
+const textEncoder = new TextEncoder();
+
+/**
+ * CTAP2 canonical CBOR key order for text-string map keys (FIDO CTAP §8 Message Encoding):
+ * shorter UTF-8 length sorts first; same length → lower byte-wise lexical order.
+ */
+export function compareCtapTextMapKeys(a: string, b: string): number {
+	const ab = textEncoder.encode(a);
+	const bb = textEncoder.encode(b);
+	if (ab.length !== bb.length) {
+		return ab.length - bb.length;
+	}
+	for (let i = 0; i < ab.length; i++) {
+		if (ab[i] !== bb[i]) {
+			return ab[i] - bb[i];
+		}
+	}
+	return 0;
+}
+
+/**
+ * Recursively reorders every CBOR-serialized map to CTAP2 canonical form (sorted keys).
+ * Integer-key maps (command parameters, COSE, etc.) are sorted numerically.
+ */
+export function canonicalizeCtapValue(value: unknown): unknown {
+	if (value === null || value === undefined) {
+		return value;
+	}
+	const t = typeof value;
+	if (
+		t === "boolean" ||
+		t === "number" ||
+		t === "string" ||
+		t === "bigint"
+	) {
+		return value;
+	}
+	if (value instanceof Uint8Array) {
+		return value;
+	}
+	if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+		const view = value as ArrayBufferView;
+		return new Uint8Array(
+			view.buffer,
+			view.byteOffset,
+			view.byteLength,
+		);
+	}
+	if (Array.isArray(value)) {
+		return value.map((v) => canonicalizeCtapValue(v));
+	}
+	if (value instanceof Map) {
+		const keys = [...value.keys()];
+		if (keys.length === 0) {
+			return new Map();
+		}
+		const allNum = keys.every((k) => typeof k === "number");
+		if (allNum) {
+			const sorted = (keys as number[])
+				.slice()
+				.sort((a, b) => a - b);
+			const m = new Map<number, unknown>();
+			for (const k of sorted) {
+				m.set(k, canonicalizeCtapValue(value.get(k)));
+			}
+			return m;
+		}
+		const allStr = keys.every((k) => typeof k === "string");
+		if (allStr) {
+			const sorted = (keys as string[])
+				.slice()
+				.sort(compareCtapTextMapKeys);
+			const o: Record<string, unknown> = {};
+			for (const k of sorted) {
+				o[k] = canonicalizeCtapValue(value.get(k));
+			}
+			return o;
+		}
+		throw new Error(
+			"CTAP CBOR: map keys must be all numbers or all strings for canonical encoding",
+		);
+	}
+	if (t === "object") {
+		const o = value as Record<string, unknown>;
+		const keys = Object.keys(o).sort(compareCtapTextMapKeys);
+		const out: Record<string, unknown> = {};
+		for (const k of keys) {
+			out[k] = canonicalizeCtapValue(o[k]);
+		}
+		return out;
+	}
+	return value;
+}
+
+export function encodeCtapCbor(value: unknown): Uint8Array {
+	const encoded = ctapCborEncoder.encode(canonicalizeCtapValue(value));
+	if (encoded instanceof Uint8Array) {
+		return new Uint8Array(encoded);
+	}
+	if (ArrayBuffer.isView(encoded)) {
+		const v = encoded as ArrayBufferView;
+		return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+	}
+	return Uint8Array.from(encoded as ArrayLike<number>);
+}
+
+export function bytesView(v: unknown): Uint8Array | undefined {
+	if (v instanceof Uint8Array) {
+		return new Uint8Array(v);
+	}
+	if (ArrayBuffer.isView(v) && !(v instanceof DataView)) {
+		const view = v as ArrayBufferView;
+		return new Uint8Array(
+			view.buffer,
+			view.byteOffset,
+			view.byteLength,
+		);
+	}
+	return undefined;
+}
+
+export function cborMapGet(
+	map: Map<number, unknown> | object,
+	key: number,
+): unknown {
+	if (map instanceof Map) {
+		return map.get(key);
+	}
+	if (map !== null && typeof map === "object") {
+		const o = map as Record<number | string, unknown>;
+		if (key in o) {
+			return o[key];
+		}
+		const s = String(key);
+		if (s in o) {
+			return o[s];
+		}
+	}
+	return undefined;
+}

package/src/ctap2/getAssertion.ts

@@ -0,0 +1,154 @@
+import { decode } from "cbor-x";
+import {
+	parseCtaphidCborFromApduResponse,
+	unwrapCtaphidCborBody,
+} from "../apdu";
+import { CTAP_CBOR_ASSERT } from "../constants";
+import { ApduError } from "../errors";
+import { bytesView, cborMapGet, encodeCtapCbor } from "./cborUtils";
+
+export interface AuthenticatorGetAssertionRequest {
+	rpId: string;
+	clientDataHash: Uint8Array;
+	allowCredentials?: Array<{ id: Uint8Array; type?: string }>;
+	extensions?: Record<string, unknown>;
+	options?: { up?: boolean; uv?: boolean };
+}
+
+export interface AuthenticatorGetAssertionResponse {
+	credential?: {
+		id: Uint8Array;
+		type?: string;
+	};
+	authData: Uint8Array;
+	signature: Uint8Array;
+	user?: {
+		id: Uint8Array;
+		name?: string;
+		displayName?: string;
+		icon?: string;
+	};
+	numberOfCredentials?: number;
+	largeBlobKey?: Uint8Array;
+}
+
+function buildRequestMap(
+	req: AuthenticatorGetAssertionRequest,
+): Map<number, unknown> {
+	const m = new Map<number, unknown>();
+	m.set(1, req.rpId);
+	m.set(2, req.clientDataHash);
+	if (req.allowCredentials?.length) {
+		m.set(
+			3,
+			req.allowCredentials.map((c) => ({
+				id: c.id,
+				type: c.type ?? "public-key",
+			})),
+		);
+	}
+	if (req.extensions && Object.keys(req.extensions).length > 0) {
+		m.set(4, req.extensions);
+	}
+	if (
+		req.options &&
+		(req.options.up !== undefined || req.options.uv !== undefined)
+	) {
+		const opt: Record<string, boolean> = {};
+		if (req.options.up !== undefined) {
+			opt.up = req.options.up;
+		}
+		if (req.options.uv !== undefined) {
+			opt.uv = req.options.uv;
+		}
+		m.set(5, opt);
+	}
+	return m;
+}
+
+function decodeAssertionMap(
+	decoded: Map<number, unknown> | object,
+): AuthenticatorGetAssertionResponse {
+	const authData = bytesView(cborMapGet(decoded, 2));
+	const signature = bytesView(cborMapGet(decoded, 3));
+	if (!authData || !signature) {
+		throw new ApduError(
+			"missing authData (2) or signature (3) in response",
+		);
+	}
+	const out: AuthenticatorGetAssertionResponse = {
+		authData,
+		signature,
+	};
+
+	const credRaw = cborMapGet(decoded, 1);
+	if (credRaw !== null && typeof credRaw === "object") {
+		const o = credRaw as Record<string, unknown>;
+		const id = bytesView(o.id);
+		if (id) {
+			out.credential = {
+				id,
+				type: typeof o.type === "string" ? o.type : undefined,
+			};
+		}
+	}
+
+	const userRaw = cborMapGet(decoded, 4);
+	if (userRaw !== null && typeof userRaw === "object") {
+		const o = userRaw as Record<string, unknown>;
+		const id = bytesView(o.id);
+		if (id) {
+			out.user = {
+				id,
+				name: typeof o.name === "string" ? o.name : undefined,
+				displayName:
+					typeof o.displayName === "string"
+						? o.displayName
+						: undefined,
+				icon: typeof o.icon === "string" ? o.icon : undefined,
+			};
+		}
+	}
+
+	const nRaw = cborMapGet(decoded, 5);
+	let n: number | undefined;
+	if (typeof nRaw === "number" && Number.isFinite(nRaw)) {
+		n = Math.trunc(nRaw);
+	} else if (typeof nRaw === "bigint") {
+		n = Number(nRaw);
+	}
+	if (n !== undefined) {
+		out.numberOfCredentials = n;
+	}
+
+	const lbk = bytesView(cborMapGet(decoded, 7));
+	if (lbk) {
+		out.largeBlobKey = lbk;
+	}
+	return out;
+}
+
+export function encodeAuthenticatorGetAssertionRequest(
+	req: AuthenticatorGetAssertionRequest,
+): Uint8Array {
+	if (req.clientDataHash.length !== 32) {
+		throw new ApduError(
+			"clientDataHash must be 32 bytes (SHA-256)",
+		);
+	}
+	const enc = encodeCtapCbor(buildRequestMap(req));
+	const frame = new Uint8Array(1 + enc.length);
+	frame[0] = CTAP_CBOR_ASSERT;
+	frame.set(enc, 1);
+	return frame;
+}
+
+export function parseAuthenticatorGetAssertionResponse(
+	apduResponseIncludingSw: Uint8Array,
+): AuthenticatorGetAssertionResponse {
+	const cborMapBytes = unwrapCtaphidCborBody(
+		parseCtaphidCborFromApduResponse(apduResponseIncludingSw),
+	);
+	const decoded = decode(cborMapBytes) as Map<number, unknown> | object;
+	return decodeAssertionMap(decoded);
+}