@c9up/warden 0.1.4 → 0.1.6

package/src/mfa/OtpProvider.ts

@@ -0,0 +1,177 @@
+/**
+ * OtpProvider — delivered one-time passcodes (email / SMS). Unlike TOTP this is
+ * a challenge/response flow: `start()` mints a code, persists it (hashed, with
+ * an expiry and an attempt budget) and hands it to a delivery channel; the user
+ * later submits it to `verify()`.
+ *
+ * Delivery is pluggable — the app supplies an email or SMS channel. The store
+ * is pluggable too, with an in-memory default mirroring the rest of warden.
+ */
+
+import {
+	createHash,
+	randomBytes,
+	randomInt,
+	timingSafeEqual,
+} from "node:crypto";
+import { WardenError } from "../errors.js";
+
+/** Sends the code to the user. Implemented by the consuming app (email/SMS). */
+export interface OtpDeliveryChannel {
+	send(recipient: string, code: string): Promise<void>;
+}
+
+/** A persisted, pending OTP challenge. */
+export interface OtpChallenge {
+	id: string;
+	recipient: string;
+	/** Salted hash of the code — never the plaintext. */
+	hash: string;
+	expiresAt: number;
+	attempts: number;
+}
+
+/** Storage for pending challenges. */
+export interface OtpChallengeStore {
+	save(challenge: OtpChallenge): Promise<void>;
+	find(id: string): Promise<OtpChallenge | null>;
+	delete(id: string): Promise<void>;
+}
+
+export class MemoryOtpChallengeStore implements OtpChallengeStore {
+	#store = new Map<string, OtpChallenge>();
+	async save(c: OtpChallenge): Promise<void> {
+		this.#store.set(c.id, c);
+	}
+	async find(id: string): Promise<OtpChallenge | null> {
+		return this.#store.get(id) ?? null;
+	}
+	async delete(id: string): Promise<void> {
+		this.#store.delete(id);
+	}
+}
+
+export interface OtpConfig {
+	channel: OtpDeliveryChannel;
+	/** Where pending challenges live. Default in-memory. */
+	store?: OtpChallengeStore;
+	/** Number of digits in the code. Default `6`. */
+	digits?: number;
+	/** How long a code stays valid, in seconds. Default `300` (5 min). */
+	ttlSeconds?: number;
+	/** Max verification attempts before the challenge is burned. Default `5`. */
+	maxAttempts?: number;
+}
+
+export interface OtpStartResult {
+	challengeId: string;
+	expiresAt: number;
+}
+
+export type OtpFailureReason =
+	| "not_found"
+	| "expired"
+	| "too_many_attempts"
+	| "mismatch";
+
+export interface OtpVerification {
+	ok: boolean;
+	reason?: OtpFailureReason;
+}
+
+export class OtpProvider {
+	readonly kind = "otp" as const;
+	readonly #channel: OtpDeliveryChannel;
+	readonly #store: OtpChallengeStore;
+	readonly #digits: number;
+	readonly #ttlMs: number;
+	readonly #maxAttempts: number;
+
+	constructor(config: OtpConfig) {
+		if (!config?.channel) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				"OtpProvider requires a delivery channel (email/SMS)",
+			);
+		}
+		this.#channel = config.channel;
+		this.#store = config.store ?? new MemoryOtpChallengeStore();
+		this.#digits = config.digits ?? 6;
+		this.#ttlMs = (config.ttlSeconds ?? 300) * 1000;
+		this.#maxAttempts = config.maxAttempts ?? 5;
+	}
+
+	/** Mint a code, persist the challenge, and deliver it to `recipient`. */
+	async start(
+		recipient: string,
+		nowMs: number = Date.now(),
+	): Promise<OtpStartResult> {
+		const code = this.#randomCode();
+		const id = randomBytes(16).toString("hex");
+		const expiresAt = nowMs + this.#ttlMs;
+		await this.#store.save({
+			id,
+			recipient,
+			hash: saltedHash(code),
+			expiresAt,
+			attempts: 0,
+		});
+		await this.#channel.send(recipient, code);
+		return { challengeId: id, expiresAt };
+	}
+
+	/**
+	 * Verify a submitted code. Wrong codes consume an attempt; the challenge is
+	 * deleted on success, on expiry, or once the attempt budget is exhausted.
+	 */
+	async verify(
+		challengeId: string,
+		code: string,
+		nowMs: number = Date.now(),
+	): Promise<OtpVerification> {
+		const challenge = await this.#store.find(challengeId);
+		if (!challenge) {
+			return { ok: false, reason: "not_found" };
+		}
+		if (nowMs > challenge.expiresAt) {
+			await this.#store.delete(challengeId);
+			return { ok: false, reason: "expired" };
+		}
+		if (matchesStored(challenge.hash, code.replace(/\s/g, ""))) {
+			await this.#store.delete(challengeId);
+			return { ok: true };
+		}
+		const attempts = challenge.attempts + 1;
+		if (attempts >= this.#maxAttempts) {
+			await this.#store.delete(challengeId);
+			return { ok: false, reason: "too_many_attempts" };
+		}
+		await this.#store.save({ ...challenge, attempts });
+		return { ok: false, reason: "mismatch" };
+	}
+
+	#randomCode(): string {
+		const max = 10 ** this.#digits;
+		return randomInt(0, max).toString().padStart(this.#digits, "0");
+	}
+}
+
+function saltedHash(code: string): string {
+	const salt = randomBytes(8);
+	const digest = createHash("sha256").update(salt).update(code).digest();
+	return `${salt.toString("hex")}$${digest.toString("hex")}`;
+}
+
+function matchesStored(stored: string, candidate: string): boolean {
+	const sep = stored.indexOf("$");
+	if (sep === -1) {
+		return false;
+	}
+	const salt = Buffer.from(stored.slice(0, sep), "hex");
+	const expected = Buffer.from(stored.slice(sep + 1), "hex");
+	const actual = createHash("sha256").update(salt).update(candidate).digest();
+	if (actual.length !== expected.length) {
+		return false;
+	}
+	return timingSafeEqual(actual, expected);
+}

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);
+}