@revibase/ctap2-js 0.1.0

package/src/ctap2/makeCredential.ts

@@ -0,0 +1,173 @@
+import { decode } from "cbor-x";
+import {
+	parseCtaphidCborFromApduResponse,
+	unwrapCtaphidCborBody,
+} from "../apdu";
+import { CTAP_CBOR_MAKE_CRED } from "../constants";
+import { ApduError } from "../errors";
+import { bytesView, cborMapGet, encodeCtapCbor } from "./cborUtils";
+
+export interface AuthenticatorMakeCredentialRequest {
+	clientDataHash: Uint8Array;
+	rp: { id: string; name: string };
+	user: {
+		id: Uint8Array;
+		name: string;
+		displayName: string;
+		icon?: string;
+	};
+	pubKeyCredParams: Array<{ alg: number; type: string }>;
+	excludeCredentials?: Array<{ id: Uint8Array; type?: string }>;
+	extensions?: Record<string, unknown>;
+	options?: { rk?: boolean; uv?: boolean };
+}
+
+export interface AuthenticatorMakeCredentialResponse {
+	fmt: string;
+	authData: Uint8Array;
+	attStmt: Record<string, unknown>;
+	largeBlobKey?: Uint8Array;
+}
+
+function buildMakeCredentialMap(
+	req: AuthenticatorMakeCredentialRequest,
+): Map<number, unknown> {
+	const m = new Map<number, unknown>();
+	m.set(1, req.clientDataHash);
+	m.set(2, { id: req.rp.id, name: req.rp.name });
+	const u: Record<string, unknown> = {
+		id: req.user.id,
+		name: req.user.name,
+		displayName: req.user.displayName,
+	};
+	if (req.user.icon !== undefined) {
+		u.icon = req.user.icon;
+	}
+	m.set(3, u);
+	m.set(
+		4,
+		req.pubKeyCredParams.map((p) => ({
+			alg: p.alg,
+			type: p.type ?? "public-key",
+		})),
+	);
+	if (req.excludeCredentials?.length) {
+		m.set(
+			5,
+			req.excludeCredentials.map((c) => ({
+				id: c.id,
+				type: c.type ?? "public-key",
+			})),
+		);
+	}
+	if (req.extensions && Object.keys(req.extensions).length > 0) {
+		m.set(6, req.extensions);
+	}
+	if (
+		req.options &&
+		(req.options.rk !== undefined || req.options.uv !== undefined)
+	) {
+		const opt: Record<string, boolean> = {};
+		if (req.options.rk !== undefined) {
+			opt.rk = req.options.rk;
+		}
+		if (req.options.uv !== undefined) {
+			opt.uv = req.options.uv;
+		}
+		m.set(7, opt);
+	}
+	return m;
+}
+
+export function encodeAuthenticatorMakeCredentialRequest(
+	req: AuthenticatorMakeCredentialRequest,
+): Uint8Array {
+	if (req.clientDataHash.length !== 32) {
+		throw new ApduError(
+			"clientDataHash must be 32 bytes (SHA-256)",
+		);
+	}
+	if (!req.pubKeyCredParams.length) {
+		throw new ApduError("pubKeyCredParams must not be empty");
+	}
+	const enc = encodeCtapCbor(buildMakeCredentialMap(req));
+	const frame = new Uint8Array(1 + enc.length);
+	frame[0] = CTAP_CBOR_MAKE_CRED;
+	frame.set(enc, 1);
+	return frame;
+}
+
+export function parseAuthenticatorMakeCredentialResponse(
+	apduResponseIncludingSw: Uint8Array,
+): AuthenticatorMakeCredentialResponse {
+	const cborMapBytes = unwrapCtaphidCborBody(
+		parseCtaphidCborFromApduResponse(apduResponseIncludingSw),
+	);
+	const decoded = decode(cborMapBytes) as Map<number, unknown> | object;
+	const fmtRaw = cborMapGet(decoded, 1);
+	const fmt = typeof fmtRaw === "string" ? fmtRaw : undefined;
+	const authData = bytesView(cborMapGet(decoded, 2));
+	const attStmtRaw = cborMapGet(decoded, 3);
+	if (
+		attStmtRaw === null ||
+		typeof attStmtRaw !== "object" ||
+		Array.isArray(attStmtRaw)
+	) {
+		throw new ApduError("attStmt (key 3) must be a CBOR map");
+	}
+	const attStmt = attStmtRaw as Record<string, unknown>;
+	if (!fmt || !authData) {
+		throw new ApduError(
+			"missing fmt (1) or authData (2) in makeCredential response",
+		);
+	}
+	const out: AuthenticatorMakeCredentialResponse = {
+		fmt,
+		authData,
+		attStmt,
+	};
+	const lbk = bytesView(cborMapGet(decoded, 5));
+	if (lbk) {
+		out.largeBlobKey = lbk;
+	}
+	return out;
+}
+
+export function buildAttestationObjectBytes(
+	fmt: string,
+	authData: Uint8Array,
+	attStmt: Record<string, unknown>,
+): Uint8Array {
+	// WebAuthn attestation object is CBOR; use CTAP2 canonical rules (CTAP §8) for interoperability.
+	return encodeCtapCbor({
+		fmt,
+		authData,
+		attStmt,
+	});
+}
+
+export function extractCredentialIdFromAuthData(
+	authData: Uint8Array,
+): Uint8Array {
+	if (authData.length < 37) {
+		throw new ApduError("authData too short");
+	}
+	const flags = authData[32];
+	if ((flags & 0x40) === 0) {
+		throw new ApduError(
+			"authData missing AT flag (attested credential data)",
+		);
+	}
+	let off = 37 + 16;
+	if (off + 2 > authData.length) {
+		throw new ApduError(
+			"authData truncated before credential id length",
+		);
+	}
+	const credIdLen = (authData[off] << 8) | authData[off + 1];
+	off += 2;
+	if (off + credIdLen > authData.length) {
+		throw new ApduError("credential id length out of range");
+	}
+	return authData.slice(off, off + credIdLen);
+}

package/src/errors.ts

@@ -0,0 +1,11 @@
+export class ApduError extends Error {
+  declare readonly cause?: unknown;
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message);
+    this.name = "ApduError";
+    if (options?.cause !== undefined) {
+      (this as Error & { cause?: unknown }).cause = options.cause;
+    }
+  }
+}

package/src/helpers/authDataExtensions.ts

@@ -0,0 +1,214 @@
+import { decode } from "cbor-x";
+
+/** WebAuthn authenticator data flags (byte index 32). */
+const FLAG_AT = 0x40;
+const FLAG_ED = 0x80;
+
+/**
+ * Skip one definite CBOR data item (RFC 8949). Used to skip the COSE public key
+ * in attested credential data. Indefinite-length items throw (not used in WebAuthn authData).
+ */
+function skipOneCborItem(buf: Uint8Array, i: number): number {
+	const first = buf[i];
+	const mt = first >> 5;
+	const ai = first & 0x1f;
+	let p = i + 1;
+
+	if (mt === 0 || mt === 1) {
+		if (ai < 24) {
+			return p;
+		}
+		if (ai === 24) {
+			return p + 1;
+		}
+		if (ai === 25) {
+			return p + 2;
+		}
+		if (ai === 26) {
+			return p + 4;
+		}
+		if (ai === 27) {
+			return p + 8;
+		}
+		throw new Error("CBOR: invalid integer encoding");
+	}
+
+	if (mt === 2 || mt === 3) {
+		const { len, next } = readLength(ai, buf, p);
+		return next + len;
+	}
+
+	if (mt === 4) {
+		if (ai === 31) {
+			throw new Error("CBOR: indefinite array not supported in authData");
+		}
+		const { len, next } = readLength(ai, buf, p);
+		let q = next;
+		for (let k = 0; k < len; k++) {
+			q = skipOneCborItem(buf, q);
+		}
+		return q;
+	}
+
+	if (mt === 5) {
+		if (ai === 31) {
+			throw new Error("CBOR: indefinite map not supported in authData");
+		}
+		const { len, next } = readLength(ai, buf, p);
+		let q = next;
+		for (let k = 0; k < len; k++) {
+			q = skipOneCborItem(buf, q);
+			q = skipOneCborItem(buf, q);
+		}
+		return q;
+	}
+
+	if (mt === 6) {
+		const { next } = readTagNumber(ai, buf, p);
+		return skipOneCborItem(buf, next);
+	}
+
+	if (mt === 7) {
+		if (ai < 24) {
+			return p;
+		}
+		if (ai === 24) {
+			return p + 1;
+		}
+		if (ai === 25) {
+			return p + 2;
+		}
+		if (ai === 26) {
+			return p + 5;
+		}
+		if (ai === 27) {
+			return p + 9;
+		}
+		throw new Error("CBOR: invalid simple/float encoding");
+	}
+
+	throw new Error("CBOR: unknown major type");
+}
+
+function readLength(
+	ai: number,
+	buf: Uint8Array,
+	p: number,
+): { len: number; next: number } {
+	if (ai < 24) {
+		return { len: ai, next: p };
+	}
+	if (ai === 24) {
+		return { len: buf[p], next: p + 1 };
+	}
+	if (ai === 25) {
+		return { len: (buf[p] << 8) | buf[p + 1], next: p + 2 };
+	}
+	if (ai === 26) {
+		const len =
+			((buf[p] << 24) |
+				(buf[p + 1] << 16) |
+				(buf[p + 2] << 8) |
+				buf[p + 3]) >>>
+			0;
+		return { len, next: p + 4 };
+	}
+	if (ai === 27) {
+		const hi = (buf[p] << 24) | (buf[p + 1] << 16) | (buf[p + 2] << 8) | buf[p + 3];
+		const lo =
+			(buf[p + 4] << 24) |
+			(buf[p + 5] << 16) |
+			(buf[p + 6] << 8) |
+			buf[p + 7];
+		const n = (BigInt(hi >>> 0) << 32n) | BigInt(lo >>> 0);
+		if (n > BigInt(Number.MAX_SAFE_INTEGER)) {
+			throw new Error("CBOR: length too large");
+		}
+		return { len: Number(n), next: p + 8 };
+	}
+	throw new Error("CBOR: invalid length encoding");
+}
+
+function readTagNumber(
+	ai: number,
+	buf: Uint8Array,
+	p: number,
+): { next: number } {
+	if (ai < 24) {
+		return { next: p };
+	}
+	if (ai === 24) {
+		return { next: p + 1 };
+	}
+	if (ai === 25) {
+		return { next: p + 2 };
+	}
+	if (ai === 26) {
+		return { next: p + 4 };
+	}
+	if (ai === 27) {
+		return { next: p + 8 };
+	}
+	throw new Error("CBOR: invalid tag encoding");
+}
+
+/**
+ * Advance past attested credential data (starts at `start`, first byte of AAGUID).
+ */
+function skipAttestedCredentialData(authData: Uint8Array, start: number): number {
+	if (authData.length < start + 18) {
+		throw new Error("authData: truncated attested credential data header");
+	}
+	let off = start + 16;
+	const credIdLen = (authData[off] << 8) | authData[off + 1];
+	off += 2 + credIdLen;
+	if (off > authData.length) {
+		throw new Error("authData: credential id out of range");
+	}
+	return skipOneCborItem(authData, off);
+}
+
+function cborExtensionsToRecord(decoded: unknown): Record<string, unknown> {
+	if (decoded instanceof Map) {
+		const o: Record<string, unknown> = {};
+		for (const [k, v] of decoded) {
+			if (typeof k === "string") {
+				o[k] = v;
+			}
+		}
+		return o;
+	}
+	if (decoded !== null && typeof decoded === "object" && !Array.isArray(decoded)) {
+		return { ...(decoded as Record<string, unknown>) };
+	}
+	return {};
+}
+
+/**
+ * Parse the **extensions** CBOR map from WebAuthn authenticator data (ED flag).
+ * This is what browsers merge into `getClientExtensionResults()` for authenticator
+ * extension outputs; pure **client** extensions are not present here.
+ *
+ * @returns Plain object suitable for `clientExtensionResults`, or `{}` if ED is clear.
+ */
+export function parseAuthenticatorDataExtensions(
+	authData: Uint8Array,
+): Record<string, unknown> {
+	if (authData.length < 37) {
+		return {};
+	}
+	const flags = authData[32];
+	let offset = 37;
+	if (flags & FLAG_AT) {
+		offset = skipAttestedCredentialData(authData, offset);
+	}
+	if ((flags & FLAG_ED) === 0) {
+		return {};
+	}
+	if (offset >= authData.length) {
+		return {};
+	}
+	const extBytes = authData.subarray(offset);
+	const decoded = decode(extBytes);
+	return cborExtensionsToRecord(decoded);
+}

package/src/helpers/base64url.ts

@@ -0,0 +1,24 @@
+export function base64URLStringToBuffer(base64URLString: string) {
+	const base64 = base64URLString.replace(/-/g, "+").replace(/_/g, "/");
+	const padLength = (4 - (base64.length % 4)) % 4;
+	const padded = base64.padEnd(base64.length + padLength, "=");
+	const binary = atob(padded);
+	const buffer = new ArrayBuffer(binary.length);
+	const bytes = new Uint8Array(buffer);
+	for (let i = 0; i < binary.length; i++) {
+		bytes[i] = binary.charCodeAt(i);
+	}
+	return buffer;
+}
+export function bufferToBase64URLString(buffer: Uint8Array) {
+	const bytes = new Uint8Array(buffer);
+	let str = "";
+	for (const charCode of bytes) {
+		str += String.fromCharCode(charCode);
+	}
+	const base64String = btoa(str);
+	return base64String
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=/g, "");
+}

package/src/helpers/clientData.ts

@@ -0,0 +1,24 @@
+interface CollectedClientDataInput {
+  challenge: string;
+  origin: string;
+  crossOrigin: boolean;
+  topOrigin?: string;
+}
+
+export function buildCollectedClientDataJSON(
+  type: "webauthn.get" | "webauthn.create",
+  input: CollectedClientDataInput,
+): string {
+  const o: Record<string, unknown> = {
+    type,
+    challenge: input.challenge,
+    origin: input.origin,
+  };
+  if (input.crossOrigin !== undefined) {
+    o.crossOrigin = input.crossOrigin;
+  }
+  if (input.topOrigin !== undefined) {
+    o.topOrigin = input.topOrigin;
+  }
+  return JSON.stringify(o);
+}

package/src/helpers/fromWebAuthnJson.ts

@@ -0,0 +1,175 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { utf8ToBytes } from "@noble/hashes/utils.js";
+import type { UserVerificationRequirement } from "@simplewebauthn/browser";
+import { ApduError } from "../errors";
+import { type AuthenticatorGetAssertionRequest } from "../ctap2/getAssertion";
+import { type AuthenticatorMakeCredentialRequest } from "../ctap2/makeCredential";
+import {
+  PublicKeyCredentialCreationOptionsJSONWithNfc,
+  PublicKeyCredentialRequestOptionsJSONWithNfc,
+} from "../types";
+import { base64URLStringToBuffer } from "./base64url";
+import { buildCollectedClientDataJSON } from "./clientData";
+
+function userVerificationToOptionalUvBool(
+  uv: UserVerificationRequirement | undefined,
+): boolean | undefined {
+  if (uv === "required") {
+    return true;
+  }
+  if (uv === "discouraged") {
+    return false;
+  }
+  return undefined;
+}
+
+function mapAuthenticatorSelection(
+  sel: PublicKeyCredentialCreationOptionsJSONWithNfc["authenticatorSelection"],
+): { rk?: boolean; uv?: boolean } | undefined {
+  if (!sel) {
+    return undefined;
+  }
+  let rk: boolean | undefined;
+  if (sel.residentKey === "required" || sel.residentKey === "preferred") {
+    rk = true;
+  } else if (sel.residentKey === "discouraged") {
+    rk = false;
+  } else if (sel.requireResidentKey === true) {
+    rk = true;
+  }
+  const uv = userVerificationToOptionalUvBool(sel.userVerification);
+  if (rk === undefined && uv === undefined) {
+    return undefined;
+  }
+  const o: { rk?: boolean; uv?: boolean } = {};
+  if (rk !== undefined) {
+    o.rk = rk;
+  }
+  if (uv !== undefined) {
+    o.uv = uv;
+  }
+  return o;
+}
+
+function pickCtapExtensions(
+  ext: Record<string, unknown> | undefined,
+  mode: "assertion" | "registration",
+): Record<string, unknown> | undefined {
+  if (!ext) {
+    return undefined;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(ext)) {
+    if (v == null) {
+      continue;
+    }
+    if (mode === "assertion" && k === "credProps") {
+      continue;
+    }
+    out[k] = v;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+export function authenticatorGetAssertionRequestFromPublicKeyCredentialRequestOptionsJSON(
+  args: PublicKeyCredentialRequestOptionsJSONWithNfc,
+): AuthenticatorGetAssertionRequest {
+  const {
+    challenge,
+    rpId,
+    allowCredentials,
+    userVerification,
+    extensions,
+    crossOrigin = false,
+    topOrigin,
+    origin,
+  } = args;
+
+  if (!rpId) throw new ApduError("WebAuthn options: rpId is required");
+
+  const clientDataJSON = buildCollectedClientDataJSON("webauthn.get", {
+    challenge,
+    origin,
+    crossOrigin,
+    topOrigin,
+  });
+  const clientDataHash = sha256(utf8ToBytes(clientDataJSON));
+
+  const uv = userVerificationToOptionalUvBool(userVerification);
+  const uvOpts = uv === undefined ? undefined : { up: true as const, uv };
+
+  const parsedExtensions = extensions
+    ? pickCtapExtensions(
+        extensions as Record<string, unknown> | undefined,
+        "assertion",
+      )
+    : undefined;
+
+  return {
+    rpId,
+    clientDataHash,
+    allowCredentials: allowCredentials?.map((d) => ({
+      id: new Uint8Array(base64URLStringToBuffer(d.id)),
+      type: d.type ?? "public-key",
+    })),
+    extensions: parsedExtensions,
+    options: uvOpts,
+  };
+}
+
+export function authenticatorMakeCredentialRequestFromPublicKeyCredentialCreationOptionsJSON(
+  args: PublicKeyCredentialCreationOptionsJSONWithNfc,
+): AuthenticatorMakeCredentialRequest {
+  const {
+    challenge,
+    user,
+    excludeCredentials,
+    extensions,
+    authenticatorSelection,
+    crossOrigin = false,
+    topOrigin,
+    origin,
+    pubKeyCredParams,
+    rp,
+  } = args;
+
+  if (!rp.id) throw new ApduError("WebAuthn options: rp.id is required");
+
+  const clientDataJSON = buildCollectedClientDataJSON("webauthn.create", {
+    challenge,
+    origin,
+    crossOrigin,
+    topOrigin,
+  });
+  const clientDataHash = sha256(utf8ToBytes(clientDataJSON));
+
+  const userId = new Uint8Array(base64URLStringToBuffer(user.id));
+
+  const parsedExtensions = extensions
+    ? pickCtapExtensions(
+        extensions as Record<string, unknown> | undefined,
+        "registration",
+      )
+    : undefined;
+  const opt = mapAuthenticatorSelection(authenticatorSelection);
+
+  return {
+    clientDataHash,
+    rp: { id: rp.id, name: rp.name },
+    user: {
+      id: userId,
+      name: user.name,
+      displayName: user.displayName,
+    },
+    pubKeyCredParams: pubKeyCredParams.map((p) => ({
+      alg: p.alg,
+      type: p.type ?? "public-key",
+    })),
+    excludeCredentials: excludeCredentials?.map((d) => ({
+      id: new Uint8Array(base64URLStringToBuffer(d.id)),
+      type: d.type ?? "public-key",
+    })),
+    extensions: parsedExtensions,
+    options: opt,
+  };
+}