@c9up/warden 0.1.3 → 0.1.5

package/src/mfa/TotpProvider.ts

@@ -0,0 +1,140 @@
+/**
+ * TotpProvider — RFC 6238 time-based one-time passwords (HOTP/RFC 4226 under
+ * the hood). Pure TypeScript on Node's `crypto.createHmac` — no native binding
+ * and no third-party dependency: a TOTP is a single HMAC, not CPU-bound work.
+ *
+ * Compatible with Google Authenticator / 1Password / Authy by default
+ * (SHA1, 6 digits, 30s period).
+ */
+
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { WardenError } from "../errors.js";
+import { base32Decode, base32Encode } from "./base32.js";
+
+export type TotpAlgorithm = "SHA1" | "SHA256" | "SHA512";
+
+export interface TotpConfig {
+	/** HMAC algorithm. Default `SHA1` (authenticator-app compatible). */
+	algorithm?: TotpAlgorithm;
+	/** Number of digits in the generated code. Default `6`. */
+	digits?: number;
+	/** Time step in seconds. Default `30`. */
+	period?: number;
+	/**
+	 * How many time steps before/after `now` are accepted on `verify`, to
+	 * tolerate clock skew. Default `1` (i.e. ±30s with the default period).
+	 */
+	window?: number;
+}
+
+export interface TotpEnrollment {
+	/** Base32 secret to persist against the user. */
+	secret: string;
+	/** `otpauth://` URI to render as a QR code during enrollment. */
+	uri: string;
+}
+
+const DEFAULTS = {
+	algorithm: "SHA1" as TotpAlgorithm,
+	digits: 6,
+	period: 30,
+	window: 1,
+};
+
+export class TotpProvider {
+	readonly kind = "totp" as const;
+	readonly #cfg: Required<TotpConfig>;
+
+	constructor(config: TotpConfig = {}) {
+		this.#cfg = { ...DEFAULTS, ...config };
+		if (this.#cfg.digits < 6 || this.#cfg.digits > 8) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				`TOTP digits must be 6-8, got ${this.#cfg.digits}`,
+			);
+		}
+	}
+
+	/**
+	 * Generate a fresh secret and the `otpauth://` provisioning URI. Persist
+	 * `secret`; render `uri` as a QR code for the user to scan.
+	 *
+	 * @param account  Identifies the account in the authenticator (usually the
+	 *                 user's email or username).
+	 * @param issuer   Your app/brand name, shown as the entry label.
+	 */
+	enroll(account: string, issuer: string): TotpEnrollment {
+		const secret = base32Encode(randomBytes(20));
+		return { secret, uri: this.uri(secret, account, issuer) };
+	}
+
+	/** Build the `otpauth://totp/...` provisioning URI for an existing secret. */
+	uri(secret: string, account: string, issuer: string): string {
+		const label = encodeURIComponent(`${issuer}:${account}`);
+		const params = new URLSearchParams({
+			secret,
+			issuer,
+			algorithm: this.#cfg.algorithm,
+			digits: String(this.#cfg.digits),
+			period: String(this.#cfg.period),
+		});
+		return `otpauth://totp/${label}?${params.toString()}`;
+	}
+
+	/** Generate the code for a given secret at a given time (ms since epoch). */
+	generate(secret: string, atMs: number = Date.now()): string {
+		const counter = Math.floor(atMs / 1000 / this.#cfg.period);
+		return this.#hotp(base32Decode(secret), counter);
+	}
+
+	/**
+	 * Verify a user-supplied code against the secret, accepting codes from the
+	 * surrounding `window` time steps to tolerate clock skew. Constant-time.
+	 */
+	verify(secret: string, code: string, atMs: number = Date.now()): boolean {
+		const normalized = code.replace(/\s/g, "");
+		if (normalized.length !== this.#cfg.digits) {
+			return false;
+		}
+		const key = base32Decode(secret);
+		const current = Math.floor(atMs / 1000 / this.#cfg.period);
+		for (let offset = -this.#cfg.window; offset <= this.#cfg.window; offset++) {
+			if (constantTimeEqual(this.#hotp(key, current + offset), normalized)) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	/** RFC 4226 HOTP: HMAC over the 8-byte counter, dynamically truncated. */
+	#hotp(key: Uint8Array, counter: number): string {
+		const buf = Buffer.alloc(8);
+		// 64-bit big-endian counter. Codes stay valid well past year 2^53,
+		// so splitting hi/lo at 2^32 is safe and avoids BigInt overhead.
+		buf.writeUInt32BE(Math.floor(counter / 2 ** 32), 0);
+		buf.writeUInt32BE(counter >>> 0, 4);
+
+		const hmac = createHmac(this.#cfg.algorithm.toLowerCase(), Buffer.from(key))
+			.update(buf)
+			.digest();
+		const off = hmac[hmac.length - 1] & 0xf;
+		const bin =
+			((hmac[off] & 0x7f) << 24) |
+			((hmac[off + 1] & 0xff) << 16) |
+			((hmac[off + 2] & 0xff) << 8) |
+			(hmac[off + 3] & 0xff);
+		return (bin % 10 ** this.#cfg.digits)
+			.toString()
+			.padStart(this.#cfg.digits, "0");
+	}
+}
+
+/** Length-safe constant-time string compare (avoids early-exit timing leaks). */
+function constantTimeEqual(a: string, b: string): boolean {
+	const ba = Buffer.from(a);
+	const bb = Buffer.from(b);
+	if (ba.length !== bb.length) {
+		return false;
+	}
+	return timingSafeEqual(ba, bb);
+}

package/src/mfa/WebauthnProvider.ts

@@ -0,0 +1,416 @@
+/**
+ * WebauthnProvider — passkeys / FIDO2 via WebAuthn, implemented in-house on
+ * `node:crypto` (see `webauthn-codec.ts`). No third-party dependency: warden
+ * keeps its zero-runtime-dependency footprint.
+ *
+ * The browser side produces the standard `PublicKeyCredential` JSON; this
+ * provider builds the ceremony options and verifies the responses server-side.
+ *
+ * Attestation statements are NOT verified — this is a deliberate
+ * trust-on-registration posture (request `attestation: "none"` on the client),
+ * which is what the vast majority of relying parties use for 2FA / passkeys.
+ * Full attestation (packed/tpm/apple/MDS cert-chain validation) can be layered
+ * on later without changing this API.
+ *
+ * Both the per-ceremony challenge and the persisted passkeys go through
+ * pluggable stores (in-memory defaults), mirroring the rest of warden.
+ */
+
+import { randomBytes } from "node:crypto";
+import { WardenError } from "../errors.js";
+import {
+	base64urlToBuffer,
+	bufferToBase64url,
+	type CborMap,
+	coseToKeyObject,
+	decodeCbor,
+	parseAuthenticatorData,
+	sha256,
+	verifyWebauthnSignature,
+} from "./webauthn-codec.js";
+
+/** Browser → server payload from `navigator.credentials.create()`. */
+export interface RegistrationResponseJSON {
+	id: string;
+	rawId: string;
+	type: "public-key";
+	response: {
+		clientDataJSON: string;
+		attestationObject: string;
+		transports?: string[];
+	};
+}
+
+/** Browser → server payload from `navigator.credentials.get()`. */
+export interface AuthenticationResponseJSON {
+	id: string;
+	rawId: string;
+	type: "public-key";
+	response: {
+		clientDataJSON: string;
+		authenticatorData: string;
+		signature: string;
+		userHandle?: string;
+	};
+}
+
+export interface RegistrationOptionsJSON {
+	challenge: string;
+	rp: { name: string; id: string };
+	user: { id: string; name: string; displayName: string };
+	pubKeyCredParams: Array<{ type: "public-key"; alg: number }>;
+	timeout: number;
+	attestation: "none";
+	excludeCredentials: Array<{
+		id: string;
+		type: "public-key";
+		transports?: string[];
+	}>;
+	authenticatorSelection: { residentKey: string; userVerification: string };
+}
+
+export interface AuthenticationOptionsJSON {
+	challenge: string;
+	timeout: number;
+	rpId: string;
+	userVerification: string;
+	allowCredentials?: Array<{
+		id: string;
+		type: "public-key";
+		transports?: string[];
+	}>;
+}
+
+/** Transient per-ceremony challenge storage. */
+export interface WebauthnChallengeStore {
+	save(state: string, challenge: string): Promise<void>;
+	/** Return the challenge for `state` and remove it (single-use). */
+	take(state: string): Promise<string | null>;
+}
+
+/** A registered passkey, persisted between ceremonies. */
+export interface StoredPasskey {
+	/** Base64URL credential id. */
+	id: string;
+	userId: string;
+	/** Base64URL of the raw COSE public-key bytes. */
+	publicKey: string;
+	/** COSE algorithm id (e.g. -7 for ES256). */
+	alg: number;
+	counter: number;
+	transports?: string[];
+}
+
+export interface WebauthnCredentialStore {
+	save(passkey: StoredPasskey): Promise<void>;
+	findById(id: string): Promise<StoredPasskey | null>;
+	findByUser(userId: string): Promise<StoredPasskey[]>;
+	updateCounter(id: string, counter: number): Promise<void>;
+}
+
+export class MemoryWebauthnChallengeStore implements WebauthnChallengeStore {
+	#store = new Map<string, string>();
+	async save(state: string, challenge: string): Promise<void> {
+		this.#store.set(state, challenge);
+	}
+	async take(state: string): Promise<string | null> {
+		const c = this.#store.get(state) ?? null;
+		this.#store.delete(state);
+		return c;
+	}
+}
+
+export class MemoryWebauthnCredentialStore implements WebauthnCredentialStore {
+	#store = new Map<string, StoredPasskey>();
+	async save(passkey: StoredPasskey): Promise<void> {
+		this.#store.set(passkey.id, passkey);
+	}
+	async findById(id: string): Promise<StoredPasskey | null> {
+		return this.#store.get(id) ?? null;
+	}
+	async findByUser(userId: string): Promise<StoredPasskey[]> {
+		return [...this.#store.values()].filter((p) => p.userId === userId);
+	}
+	async updateCounter(id: string, counter: number): Promise<void> {
+		const p = this.#store.get(id);
+		if (p) {
+			this.#store.set(id, { ...p, counter });
+		}
+	}
+}
+
+export interface WebauthnConfig {
+	/** Human-readable relying-party name (your app). */
+	rpName: string;
+	/** Relying-party ID — your registrable domain (e.g. `fluveo.ch`). */
+	rpID: string;
+	/** Expected origin(s) of the ceremony (e.g. `https://fluveo.ch`). */
+	origin: string | string[];
+	challengeStore?: WebauthnChallengeStore;
+	credentialStore?: WebauthnCredentialStore;
+	/** Ceremony timeout in ms. Default `60000`. */
+	timeout?: number;
+	/**
+	 * COSE algorithms offered to the authenticator, in preference order.
+	 * Default ES256, RS256, EdDSA.
+	 */
+	supportedAlgorithms?: number[];
+}
+
+export interface WebauthnUser {
+	id: string;
+	name: string;
+	displayName?: string;
+}
+
+const DEFAULT_ALGS = [-7, -257, -8];
+
+export class WebauthnProvider {
+	readonly kind = "webauthn" as const;
+	readonly #rpName: string;
+	readonly #rpID: string;
+	readonly #origins: string[];
+	readonly #timeout: number;
+	readonly #algorithms: number[];
+	readonly #challenges: WebauthnChallengeStore;
+	readonly #credentials: WebauthnCredentialStore;
+
+	constructor(config: WebauthnConfig) {
+		if (!config?.rpID || !config?.rpName || !config?.origin) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				"WebauthnProvider requires rpName, rpID and origin",
+			);
+		}
+		this.#rpName = config.rpName;
+		this.#rpID = config.rpID;
+		this.#origins = Array.isArray(config.origin)
+			? config.origin
+			: [config.origin];
+		this.#timeout = config.timeout ?? 60_000;
+		this.#algorithms = config.supportedAlgorithms ?? DEFAULT_ALGS;
+		this.#challenges =
+			config.challengeStore ?? new MemoryWebauthnChallengeStore();
+		this.#credentials =
+			config.credentialStore ?? new MemoryWebauthnCredentialStore();
+	}
+
+	/**
+	 * Begin passkey registration. Returns the options to hand to the browser,
+	 * plus an opaque `state` token the caller stashes in the session and passes
+	 * back to `finishRegistration()`.
+	 */
+	async startRegistration(
+		user: WebauthnUser,
+	): Promise<{ options: RegistrationOptionsJSON; state: string }> {
+		const existing = await this.#credentials.findByUser(user.id);
+		const challenge = bufferToBase64url(randomBytes(32));
+		const options: RegistrationOptionsJSON = {
+			challenge,
+			rp: { name: this.#rpName, id: this.#rpID },
+			user: {
+				id: bufferToBase64url(Buffer.from(user.id, "utf8")),
+				name: user.name,
+				displayName: user.displayName ?? user.name,
+			},
+			pubKeyCredParams: this.#algorithms.map((alg) => ({
+				type: "public-key",
+				alg,
+			})),
+			timeout: this.#timeout,
+			attestation: "none",
+			excludeCredentials: existing.map((c) => ({
+				id: c.id,
+				type: "public-key",
+				transports: c.transports,
+			})),
+			authenticatorSelection: {
+				residentKey: "preferred",
+				userVerification: "preferred",
+			},
+		};
+		const state = randomBytes(16).toString("hex");
+		await this.#challenges.save(state, challenge);
+		return { options, state };
+	}
+
+	/**
+	 * Complete registration: validate client data + authenticator data against
+	 * the stored challenge and persist the new passkey on success.
+	 */
+	async finishRegistration(
+		state: string,
+		userId: string,
+		response: RegistrationResponseJSON,
+	): Promise<{ verified: boolean }> {
+		const expectedChallenge = await this.#challenges.take(state);
+		if (!expectedChallenge) {
+			return { verified: false };
+		}
+		if (
+			!this.#validClientData(
+				response.response.clientDataJSON,
+				"webauthn.create",
+				expectedChallenge,
+			)
+		) {
+			return { verified: false };
+		}
+
+		const attestation = decodeCbor(
+			base64urlToBuffer(response.response.attestationObject),
+		).value;
+		if (!(attestation instanceof Map)) {
+			return { verified: false };
+		}
+		const authDataRaw = attestation.get("authData");
+		if (!Buffer.isBuffer(authDataRaw)) {
+			return { verified: false };
+		}
+		const authData = parseAuthenticatorData(authDataRaw);
+		if (
+			!this.#validAuthenticator(authData) ||
+			!authData.cosePublicKey ||
+			!authData.cosePublicKeyBytes ||
+			!authData.credentialId
+		) {
+			return { verified: false };
+		}
+
+		const { alg } = coseToKeyObject(authData.cosePublicKey);
+		await this.#credentials.save({
+			id: bufferToBase64url(authData.credentialId),
+			userId,
+			publicKey: bufferToBase64url(authData.cosePublicKeyBytes),
+			alg,
+			counter: authData.signCount,
+			transports: response.response.transports,
+		});
+		return { verified: true };
+	}
+
+	/**
+	 * Begin authentication. Pass `userId` to restrict to that user's passkeys
+	 * (2FA step); omit it for a usernameless / discoverable-credential sign-in.
+	 */
+	async startAuthentication(
+		userId?: string,
+	): Promise<{ options: AuthenticationOptionsJSON; state: string }> {
+		const challenge = bufferToBase64url(randomBytes(32));
+		const allow = userId ? await this.#credentials.findByUser(userId) : [];
+		const options: AuthenticationOptionsJSON = {
+			challenge,
+			timeout: this.#timeout,
+			rpId: this.#rpID,
+			userVerification: "preferred",
+			allowCredentials: userId
+				? allow.map((c) => ({
+						id: c.id,
+						type: "public-key",
+						transports: c.transports,
+					}))
+				: undefined,
+		};
+		const state = randomBytes(16).toString("hex");
+		await this.#challenges.save(state, challenge);
+		return { options, state };
+	}
+
+	/**
+	 * Complete authentication: look up the asserted credential, verify the
+	 * signature against the stored challenge, and advance the replay counter.
+	 * Returns the owning `userId` on success.
+	 */
+	async finishAuthentication(
+		state: string,
+		response: AuthenticationResponseJSON,
+	): Promise<{ verified: boolean; userId?: string }> {
+		const expectedChallenge = await this.#challenges.take(state);
+		if (!expectedChallenge) {
+			return { verified: false };
+		}
+		if (
+			!this.#validClientData(
+				response.response.clientDataJSON,
+				"webauthn.get",
+				expectedChallenge,
+			)
+		) {
+			return { verified: false };
+		}
+
+		const stored = await this.#credentials.findById(response.id);
+		if (!stored) {
+			return { verified: false };
+		}
+
+		const authDataRaw = base64urlToBuffer(response.response.authenticatorData);
+		const authData = parseAuthenticatorData(authDataRaw);
+		if (!this.#validAuthenticator(authData)) {
+			return { verified: false };
+		}
+
+		// Signed payload = authenticatorData ‖ SHA-256(clientDataJSON).
+		const clientHash = sha256(
+			base64urlToBuffer(response.response.clientDataJSON),
+		);
+		const signedData = Buffer.concat([authDataRaw, clientHash]);
+		const { key } = coseToKeyObject(
+			expectCoseMap(base64urlToBuffer(stored.publicKey)),
+		);
+		const ok = verifyWebauthnSignature(
+			stored.alg,
+			key,
+			signedData,
+			base64urlToBuffer(response.response.signature),
+		);
+		if (!ok) {
+			return { verified: false };
+		}
+
+		// Replay guard: a non-zero counter must strictly advance. Authenticators
+		// that always report 0 (e.g. many platform passkeys) are exempt.
+		if (authData.signCount !== 0 && authData.signCount <= stored.counter) {
+			return { verified: false };
+		}
+		await this.#credentials.updateCounter(stored.id, authData.signCount);
+		return { verified: true, userId: stored.userId };
+	}
+
+	/** Validate clientDataJSON: type, challenge match, and origin allow-list. */
+	#validClientData(
+		clientDataB64: string,
+		expectedType: "webauthn.create" | "webauthn.get",
+		expectedChallenge: string,
+	): boolean {
+		let parsed: { type?: string; challenge?: string; origin?: string };
+		try {
+			parsed = JSON.parse(base64urlToBuffer(clientDataB64).toString("utf8"));
+		} catch {
+			return false;
+		}
+		return (
+			parsed.type === expectedType &&
+			parsed.challenge === expectedChallenge &&
+			typeof parsed.origin === "string" &&
+			this.#origins.includes(parsed.origin)
+		);
+	}
+
+	/** Validate authenticator data: rpIdHash match and user-presence flag. */
+	#validAuthenticator(authData: {
+		rpIdHash: Buffer;
+		flags: { up: boolean };
+	}): boolean {
+		const expectedRpIdHash = sha256(Buffer.from(this.#rpID, "utf8"));
+		return authData.flags.up && expectedRpIdHash.equals(authData.rpIdHash);
+	}
+}
+
+function expectCoseMap(bytes: Buffer): CborMap {
+	const decoded = decodeCbor(bytes).value;
+	if (!(decoded instanceof Map)) {
+		throw new WardenError("INVALID_CREDENTIAL", "stored COSE key is malformed");
+	}
+	return decoded;
+}

package/src/mfa/base32.ts

@@ -0,0 +1,54 @@
+/**
+ * RFC 4648 base32 (no padding) — the encoding authenticator apps expect for
+ * TOTP secrets. Kept dependency-free and local to the MFA subsystem.
+ */
+
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+const CHAR_TO_VAL: Record<string, number> = {};
+for (let i = 0; i < ALPHABET.length; i++) {
+	CHAR_TO_VAL[ALPHABET[i]] = i;
+}
+
+/** Encode bytes to an unpadded, uppercase base32 string. */
+export function base32Encode(bytes: Uint8Array): string {
+	let bits = 0;
+	let value = 0;
+	let out = "";
+	for (const byte of bytes) {
+		value = (value << 8) | byte;
+		bits += 8;
+		while (bits >= 5) {
+			out += ALPHABET[(value >>> (bits - 5)) & 31];
+			bits -= 5;
+		}
+	}
+	if (bits > 0) {
+		out += ALPHABET[(value << (5 - bits)) & 31];
+	}
+	return out;
+}
+
+/**
+ * Decode a base32 string to bytes. Tolerant of lowercase, spaces, and `=`
+ * padding (authenticator apps and manual entry produce all three). Throws on
+ * any character outside the alphabet.
+ */
+export function base32Decode(input: string): Uint8Array {
+	const clean = input.replace(/[\s=]/g, "").toUpperCase();
+	let bits = 0;
+	let value = 0;
+	const out: number[] = [];
+	for (const ch of clean) {
+		const v = CHAR_TO_VAL[ch];
+		if (v === undefined) {
+			throw new Error(`Invalid base32 character: ${ch}`);
+		}
+		value = (value << 5) | v;
+		bits += 5;
+		if (bits >= 8) {
+			out.push((value >>> (bits - 8)) & 0xff);
+			bits -= 8;
+		}
+	}
+	return Uint8Array.from(out);
+}