@c9up/warden 0.1.13 → 0.1.14

package/src/errors.ts

@@ -18,8 +18,50 @@ export class WardenError extends Error {
 	) {
 		super(message);
 		this.name = "WardenError";
-		this.code = `WARDEN_${code}`;
+		// Warden's own codes carry the `WARDEN_` namespace. The AdonisJS auth
+		// identifiers (`E_UNAUTHORIZED_ACCESS`, `E_INVALID_CREDENTIALS`) are
+		// PRESERVED verbatim so the exposed `.code` matches Adonis exactly — a
+		// consumer branching on `error.code === 'E_UNAUTHORIZED_ACCESS'` (or a
+		// framework mapping the Adonis id) sees the same string it would under
+		// `@adonisjs/auth`. Documented deviation from the blanket prefix.
+		this.code = code.startsWith("E_") ? code : `WARDEN_${code}`;
 		this.hint = options?.hint;
 		this.status = options?.status;
 	}
 }
+
+/**
+ * `E_UNAUTHORIZED_ACCESS` — raised when an incoming request cannot be
+ * authenticated (AdonisJS `@adonisjs/auth` parity). Carries `guardDriverName`
+ * (the guard that rejected) and, for session-guard flows, an optional
+ * `redirectTo` (the login route an HTML client is redirected to). Status 401.
+ *
+ * Content negotiation (redirect for `Accept: text/html` + session guard, else
+ * 401 JSON) is performed by Warden itself — see `renderAuthError` in
+ * `middleware.ts` — so the package stays agnostic of the host's exception
+ * handler.
+ */
+export class E_UNAUTHORIZED_ACCESS extends WardenError {
+	readonly redirectTo?: string;
+	readonly guardDriverName: string;
+
+	constructor(
+		message: string,
+		options: { guardDriverName: string; redirectTo?: string },
+	) {
+		super("E_UNAUTHORIZED_ACCESS", message, { status: 401 });
+		this.guardDriverName = options.guardDriverName;
+		this.redirectTo = options.redirectTo;
+	}
+}
+
+/**
+ * `E_INVALID_CREDENTIALS` — raised when a credential check (email/password)
+ * fails (AdonisJS parity). Status 400. Distinct from `E_UNAUTHORIZED_ACCESS`
+ * (a missing/invalid session or token on a protected route → 401).
+ */
+export class E_INVALID_CREDENTIALS extends WardenError {
+	constructor(message = "Invalid user credentials") {
+		super("E_INVALID_CREDENTIALS", message, { status: 400 });
+	}
+}

package/src/index.ts

@@ -4,6 +4,13 @@
  * @implements FR48, FR49, FR50, FR51, FR52, FR53
  */
 
+export type { AuthAttempt, ExtractedCredentials } from "./Authenticator.js";
+export {
+	API_KEY_GUARD_NAMES,
+	Authenticator,
+	extractCredentials,
+	GuardAccessor,
+} from "./Authenticator.js";
 export type {
 	AuthConfig,
 	AuthResult,
@@ -13,6 +20,7 @@ export type {
 export { AuthManager } from "./AuthManager.js";
 export type { AuthRateLimiterConfig } from "./AuthRateLimiter.js";
 export { AuthRateLimiter } from "./AuthRateLimiter.js";
+export { AbilitiesBuilder } from "./bouncer/AbilitiesBuilder.js";
 export { AuthorizationResponse } from "./bouncer/AuthorizationResponse.js";
 export { BasePolicy } from "./bouncer/BasePolicy.js";
 export { Bouncer } from "./bouncer/Bouncer.js";
@@ -27,10 +35,22 @@ export type {
 	AbilityOptions,
 	AuthorizerResponse,
 	BouncerContext,
+	BouncerEmitter,
+	PolicyContainerResolver,
 } from "./bouncer/types.js";
-export { defineConfig } from "./config.js";
+export type { GuardFactory, WardenConfig } from "./config.js";
+export {
+	apiKeyGuard,
+	defineConfig,
+	jwtGuard,
+	sessionGuard,
+} from "./config.js";
 export { configure } from "./configure.js";
-export { WardenError } from "./errors.js";
+export {
+	E_INVALID_CREDENTIALS,
+	E_UNAUTHORIZED_ACCESS,
+	WardenError,
+} from "./errors.js";
 export { GitHubDriver } from "./firstcontact/drivers/GitHubDriver.js";
 export { GoogleDriver } from "./firstcontact/drivers/GoogleDriver.js";
 export { FirstContactManager } from "./firstcontact/FirstContactManager.js";

package/src/mfa/OtpProvider.ts

@@ -96,9 +96,37 @@ export class OtpProvider {
 		}
 		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;
+
+		// Validate the numeric config up-front (mirrors TotpProvider's digit
+		// guard) so a misconfig fails loudly at construction instead of minting
+		// unusable codes: `digits` bounds the code length (also keeps `10**digits`
+		// within `randomInt`'s safe range); a non-positive `ttlSeconds` would make
+		// every code born-expired; a non-positive `maxAttempts` would burn the
+		// challenge on the first guess.
+		const digits = config.digits ?? 6;
+		if (!Number.isInteger(digits) || digits < 4 || digits > 10) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				`OTP digits must be an integer 4-10, got ${digits}`,
+			);
+		}
+		const ttlSeconds = config.ttlSeconds ?? 300;
+		if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				`OTP ttlSeconds must be a positive integer, got ${ttlSeconds}`,
+			);
+		}
+		const maxAttempts = config.maxAttempts ?? 5;
+		if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				`OTP maxAttempts must be a positive integer, got ${maxAttempts}`,
+			);
+		}
+		this.#digits = digits;
+		this.#ttlMs = ttlSeconds * 1000;
+		this.#maxAttempts = maxAttempts;
 	}
 
 	/** Mint a code, persist the challenge, and deliver it to `recipient`. */

package/src/mfa/WebauthnProvider.ts

@@ -81,10 +81,21 @@ export interface AuthenticationOptionsJSON {
 	}>;
 }
 
-/** Transient per-ceremony challenge storage. */
+/**
+ * Transient per-ceremony challenge storage.
+ *
+ * Implementations MUST be **time-bound**: a challenge that is never consumed has
+ * to expire server-side (single-use alone is not enough — an unconsumed
+ * challenge left live indefinitely widens the replay/relay window). A DB/Redis
+ * store should use a TTL column / `EXPIRE`; the in-memory default stamps an
+ * `expiresAt` and refuses an expired challenge in `take`.
+ */
 export interface WebauthnChallengeStore {
 	save(state: string, challenge: string): Promise<void>;
-	/** Return the challenge for `state` and remove it (single-use). */
+	/**
+	 * Return the challenge for `state` and remove it (single-use). MUST return
+	 * `null` if the stored challenge has passed its TTL.
+	 */
 	take(state: string): Promise<string | null>;
 }
 
@@ -109,14 +120,24 @@ export interface WebauthnCredentialStore {
 }
 
 export class MemoryWebauthnChallengeStore implements WebauthnChallengeStore {
-	#store = new Map<string, string>();
+	#store = new Map<string, { challenge: string; expiresAt: number }>();
+	readonly #ttlMs: number;
+
+	/** @param ttlMs Server-side challenge lifetime. Default 5 min. */
+	constructor(ttlMs = 300_000) {
+		this.#ttlMs = ttlMs;
+	}
+
 	async save(state: string, challenge: string): Promise<void> {
-		this.#store.set(state, challenge);
+		this.#store.set(state, { challenge, expiresAt: Date.now() + this.#ttlMs });
 	}
 	async take(state: string): Promise<string | null> {
-		const c = this.#store.get(state) ?? null;
-		this.#store.delete(state);
-		return c;
+		const entry = this.#store.get(state);
+		this.#store.delete(state); // single-use regardless of freshness
+		if (!entry || entry.expiresAt < Date.now()) {
+			return null;
+		}
+		return entry.challenge;
 	}
 }
 
@@ -139,6 +160,12 @@ export class MemoryWebauthnCredentialStore implements WebauthnCredentialStore {
 	}
 }
 
+/** WebAuthn user-verification requirement (PIN / biometric). */
+export type UserVerificationRequirement =
+	| "required"
+	| "preferred"
+	| "discouraged";
+
 export interface WebauthnConfig {
 	/** Human-readable relying-party name (your app). */
 	rpName: string;
@@ -155,6 +182,13 @@ export interface WebauthnConfig {
 	 * Default ES256, RS256, EdDSA.
 	 */
 	supportedAlgorithms?: number[];
+	/**
+	 * User-verification requirement. Default `"preferred"`. Set `"required"`
+	 * for strong MFA / sensitive passkeys — the ceremony then requests UV AND
+	 * the server rejects an assertion whose authenticator-data UV flag is unset
+	 * (a mere user-presence touch no longer satisfies the check).
+	 */
+	userVerification?: UserVerificationRequirement;
 }
 
 export interface WebauthnUser {
@@ -172,6 +206,7 @@ export class WebauthnProvider {
 	readonly #origins: string[];
 	readonly #timeout: number;
 	readonly #algorithms: number[];
+	readonly #userVerification: UserVerificationRequirement;
 	readonly #challenges: WebauthnChallengeStore;
 	readonly #credentials: WebauthnCredentialStore;
 
@@ -189,6 +224,7 @@ export class WebauthnProvider {
 			: [config.origin];
 		this.#timeout = config.timeout ?? 60_000;
 		this.#algorithms = config.supportedAlgorithms ?? DEFAULT_ALGS;
+		this.#userVerification = config.userVerification ?? "preferred";
 		this.#challenges =
 			config.challengeStore ?? new MemoryWebauthnChallengeStore();
 		this.#credentials =
@@ -226,7 +262,7 @@ export class WebauthnProvider {
 			})),
 			authenticatorSelection: {
 				residentKey: "preferred",
-				userVerification: "preferred",
+				userVerification: this.#userVerification,
 			},
 		};
 		const state = randomBytes(16).toString("hex");
@@ -302,7 +338,7 @@ export class WebauthnProvider {
 			challenge,
 			timeout: this.#timeout,
 			rpId: this.#rpID,
-			userVerification: "preferred",
+			userVerification: this.#userVerification,
 			allowCredentials: userId
 				? allow.map((c) => ({
 						id: c.id,
@@ -397,13 +433,23 @@ export class WebauthnProvider {
 		);
 	}
 
-	/** Validate authenticator data: rpIdHash match and user-presence flag. */
+	/**
+	 * Validate authenticator data: rpIdHash match, mandatory user-presence, and
+	 * — when `userVerification: "required"` is configured — the user-verification
+	 * flag (PIN / biometric actually performed, not just a presence touch).
+	 */
 	#validAuthenticator(authData: {
 		rpIdHash: Buffer;
-		flags: { up: boolean };
+		flags: { up: boolean; uv: boolean };
 	}): boolean {
 		const expectedRpIdHash = sha256(Buffer.from(this.#rpID, "utf8"));
-		return authData.flags.up && expectedRpIdHash.equals(authData.rpIdHash);
+		if (!authData.flags.up || !expectedRpIdHash.equals(authData.rpIdHash)) {
+			return false;
+		}
+		if (this.#userVerification === "required" && !authData.flags.uv) {
+			return false;
+		}
+		return true;
 	}
 }