@c9up/warden 0.1.4 → 0.1.6

package/src/mfa/webauthn-codec.ts

@@ -0,0 +1,264 @@
+/**
+ * WebAuthn wire-format codec — the parsing and crypto primitives behind
+ * `WebauthnProvider`, implemented from scratch on `node:crypto` so warden
+ * carries no third-party dependency.
+ *
+ * Scope: the subset of CBOR / COSE / authenticator-data that FIDO2 ceremonies
+ * actually use, with public-key algorithms Node can import via JWK:
+ *   - ES256 / ES384 / ES512 (ECDSA, COSE alg -7 / -35 / -36)
+ *   - RS256 / RS384 / RS512 (RSASSA-PKCS1-v1_5, alg -257 / -258 / -259)
+ *   - EdDSA / Ed25519 (alg -8)
+ *
+ * Attestation *statements* are intentionally not verified (see WebauthnProvider).
+ */
+
+import {
+	createHash,
+	createPublicKey,
+	verify as cryptoVerify,
+	type JsonWebKey,
+	type KeyObject,
+} from "node:crypto";
+
+export type CborValue =
+	| number
+	| string
+	| Buffer
+	| CborValue[]
+	| CborMap
+	| boolean
+	| null;
+export type CborMap = Map<number | string, CborValue>;
+
+export function base64urlToBuffer(s: string): Buffer {
+	return Buffer.from(s, "base64url");
+}
+
+export function bufferToBase64url(b: Buffer | Uint8Array): string {
+	return Buffer.from(b).toString("base64url");
+}
+
+export function sha256(data: Buffer): Buffer {
+	return createHash("sha256").update(data).digest();
+}
+
+interface Decoded {
+	value: CborValue;
+	/** Byte offset immediately after the decoded item. */
+	next: number;
+}
+
+/**
+ * Decode a single CBOR item starting at `start`. Definite-length only —
+ * indefinite-length items and floats are rejected (WebAuthn uses neither).
+ */
+export function decodeCbor(buf: Buffer, start = 0): Decoded {
+	const major = buf[start] >> 5;
+	const info = buf[start] & 0x1f;
+	let len: number;
+	let p = start + 1;
+	if (info < 24) {
+		len = info;
+	} else if (info === 24) {
+		len = buf[p];
+		p += 1;
+	} else if (info === 25) {
+		len = buf.readUInt16BE(p);
+		p += 2;
+	} else if (info === 26) {
+		len = buf.readUInt32BE(p);
+		p += 4;
+	} else if (info === 27) {
+		len = Number(buf.readBigUInt64BE(p));
+		p += 8;
+	} else {
+		throw new Error("CBOR: indefinite or reserved length is not supported");
+	}
+
+	switch (major) {
+		case 0: // unsigned int
+			return { value: len, next: p };
+		case 1: // negative int
+			return { value: -1 - len, next: p };
+		case 2: // byte string
+			return { value: buf.subarray(p, p + len), next: p + len };
+		case 3: // text string
+			return { value: buf.toString("utf8", p, p + len), next: p + len };
+		case 4: {
+			// array
+			const arr: CborValue[] = [];
+			let cur = p;
+			for (let i = 0; i < len; i++) {
+				const d = decodeCbor(buf, cur);
+				arr.push(d.value);
+				cur = d.next;
+			}
+			return { value: arr, next: cur };
+		}
+		case 5: {
+			// map
+			const map: CborMap = new Map();
+			let cur = p;
+			for (let i = 0; i < len; i++) {
+				const k = decodeCbor(buf, cur);
+				cur = k.next;
+				const v = decodeCbor(buf, cur);
+				cur = v.next;
+				if (typeof k.value !== "number" && typeof k.value !== "string") {
+					throw new Error("CBOR: only integer/text map keys are supported");
+				}
+				map.set(k.value, v.value);
+			}
+			return { value: map, next: cur };
+		}
+		case 6: {
+			// tag — decode and surface the tagged content
+			const d = decodeCbor(buf, p);
+			return { value: d.value, next: d.next };
+		}
+		case 7:
+			if (info === 20) return { value: false, next: p };
+			if (info === 21) return { value: true, next: p };
+			if (info === 22) return { value: null, next: p };
+			throw new Error("CBOR: simple/float values are not supported");
+		default:
+			throw new Error(`CBOR: unknown major type ${major}`);
+	}
+}
+
+export interface AuthenticatorData {
+	rpIdHash: Buffer;
+	flags: { up: boolean; uv: boolean; at: boolean; ed: boolean };
+	signCount: number;
+	credentialId?: Buffer;
+	cosePublicKey?: CborMap;
+	/** Raw COSE_Key bytes, ready to persist and re-decode at sign-in time. */
+	cosePublicKeyBytes?: Buffer;
+}
+
+/** Parse the raw authenticator-data structure (§6.1 of the WebAuthn spec). */
+export function parseAuthenticatorData(authData: Buffer): AuthenticatorData {
+	if (authData.length < 37) {
+		throw new Error("authenticatorData is too short");
+	}
+	const flagsByte = authData[32];
+	const flags = {
+		up: (flagsByte & 0x01) !== 0,
+		uv: (flagsByte & 0x04) !== 0,
+		at: (flagsByte & 0x40) !== 0,
+		ed: (flagsByte & 0x80) !== 0,
+	};
+	const result: AuthenticatorData = {
+		rpIdHash: authData.subarray(0, 32),
+		flags,
+		signCount: authData.readUInt32BE(33),
+	};
+	if (flags.at) {
+		if (authData.length < 55) {
+			throw new Error("attested credential data is truncated");
+		}
+		const credIdLen = authData.readUInt16BE(53);
+		result.credentialId = authData.subarray(55, 55 + credIdLen);
+		const coseStart = 55 + credIdLen;
+		const decoded = decodeCbor(authData, coseStart);
+		if (!(decoded.value instanceof Map)) {
+			throw new Error("COSE public key is not a CBOR map");
+		}
+		result.cosePublicKey = decoded.value;
+		result.cosePublicKeyBytes = authData.subarray(coseStart, decoded.next);
+	}
+	return result;
+}
+
+// COSE algorithm id → the hash Node should use ( `null` = pre-hashed / Ed25519 ).
+const ALG_HASH: Record<number, string | null> = {
+	[-7]: "sha256",
+	[-35]: "sha384",
+	[-36]: "sha512",
+	[-257]: "sha256",
+	[-258]: "sha384",
+	[-259]: "sha512",
+	[-8]: null,
+};
+
+const EC_CURVES: Record<number, string> = {
+	1: "P-256",
+	2: "P-384",
+	3: "P-521",
+};
+
+/** Convert a COSE_Key map into a Node public key plus its COSE algorithm id. */
+export function coseToKeyObject(cose: CborMap): {
+	key: KeyObject;
+	alg: number;
+} {
+	const kty = expectNumber(cose.get(1), "COSE kty");
+	const alg = expectNumber(cose.get(3), "COSE alg");
+	let jwk: JsonWebKey;
+
+	if (kty === 2) {
+		// EC2
+		const curve = EC_CURVES[expectNumber(cose.get(-1), "EC curve")];
+		if (!curve) {
+			throw new Error("unsupported COSE EC curve");
+		}
+		jwk = {
+			kty: "EC",
+			crv: curve,
+			x: bufferToBase64url(expectBytes(cose.get(-2), "EC x")),
+			y: bufferToBase64url(expectBytes(cose.get(-3), "EC y")),
+		};
+	} else if (kty === 3) {
+		// RSA
+		jwk = {
+			kty: "RSA",
+			n: bufferToBase64url(expectBytes(cose.get(-1), "RSA n")),
+			e: bufferToBase64url(expectBytes(cose.get(-2), "RSA e")),
+		};
+	} else if (kty === 1) {
+		// OKP / Ed25519
+		if (expectNumber(cose.get(-1), "OKP curve") !== 6) {
+			throw new Error("unsupported COSE OKP curve (only Ed25519)");
+		}
+		jwk = {
+			kty: "OKP",
+			crv: "Ed25519",
+			x: bufferToBase64url(expectBytes(cose.get(-2), "OKP x")),
+		};
+	} else {
+		throw new Error(`unsupported COSE key type ${kty}`);
+	}
+
+	return { key: createPublicKey({ key: jwk, format: "jwk" }), alg };
+}
+
+/**
+ * Verify a WebAuthn assertion signature over `data` (= authenticatorData ‖
+ * SHA-256(clientDataJSON)). ECDSA signatures are DER-encoded, matching what
+ * authenticators emit.
+ */
+export function verifyWebauthnSignature(
+	alg: number,
+	key: KeyObject,
+	data: Buffer,
+	signature: Buffer,
+): boolean {
+	if (!(alg in ALG_HASH)) {
+		throw new Error(`unsupported COSE algorithm ${alg}`);
+	}
+	return cryptoVerify(ALG_HASH[alg], data, key, signature);
+}
+
+function expectNumber(v: CborValue | undefined, what: string): number {
+	if (typeof v !== "number") {
+		throw new Error(`${what}: expected an integer`);
+	}
+	return v;
+}
+
+function expectBytes(v: CborValue | undefined, what: string): Buffer {
+	if (!Buffer.isBuffer(v)) {
+		throw new Error(`${what}: expected a byte string`);
+	}
+	return v;
+}

package/src/middleware.ts

@@ -22,11 +22,18 @@ import {
 	type AuthStrategy,
 	sanitizePayload,
 } from "./AuthManager.js";
+import type { BasePolicy } from "./bouncer/BasePolicy.js";
+import { Bouncer } from "./bouncer/Bouncer.js";
+import type { Ability } from "./bouncer/types.js";
+import type { ScopeRequestContext } from "./config.js";
 import {
 	getGuardMetadata,
 	getPermissionMetadata,
+	getRequireMfaMetadata,
 	getRoleMetadata,
 } from "./Guard.js";
+import { RightsResolver } from "./rights/RightsResolver.js";
+import type { Scope } from "./rights/types.js";
 import type { SessionStore } from "./strategies/SessionStrategy.js";
 
 interface StrategyWithContext extends AuthStrategy {
@@ -60,6 +67,8 @@ export interface WardenContext {
 	session?: SessionStore;
 	/** Set by the middleware after successful auth. */
 	auth?: AuthResult;
+	/** Set by `initializeBouncer` — the per-request authorization entry point. */
+	bouncer?: Bouncer;
 	/** The route handler metadata (decorators). */
 	route?: {
 		controller?: object;
@@ -163,12 +172,32 @@ export async function wardenMiddleware(ctx: WardenContext, next: WardenNext) {
 	// bypass permission checks. This is the strictest model — callers who want
 	// role-OR-permission semantics should use a custom guard instead.
 	if (controller && action) {
-		const denied = await checkAuthorization(auth, user, controller, action);
+		const scope = await resolveRequestScope(ctx);
+		const denied = await checkAuthorization(
+			auth,
+			user,
+			controller,
+			action,
+			scope,
+		);
 		if (denied) {
 			ctx.response.status(403);
 			ctx.response.json({ error: { code: "FORBIDDEN", message: denied } });
 			return;
 		}
+
+		// @RequireMfa gate: the user must carry a truthy `mfa` claim, set by the
+		// app's step-up flow once MfaManager.verify() succeeds.
+		if (getRequireMfaMetadata(controller, action) && user.mfa !== true) {
+			ctx.response.status(403);
+			ctx.response.json({
+				error: {
+					code: "MFA_REQUIRED",
+					message: "Multi-factor authentication is required for this action.",
+				},
+			});
+			return;
+		}
 	}
 
 	// Auth successful — attach to context and continue.
@@ -176,6 +205,85 @@ export async function wardenMiddleware(ctx: WardenContext, next: WardenNext) {
 	await next();
 }
 
+/**
+ * The abilities/policies/scope-resolver a per-request Bouncer is built from.
+ * Registered once by `WardenProvider` (from `config.auth`) under the container
+ * token `"bouncer:registry"`; read fresh by `initializeBouncer` per request.
+ */
+export interface BouncerRegistry {
+	abilities: Record<string, Ability<never[]>>;
+	policies: Record<string, new () => BasePolicy>;
+	resolveScope?: (ctx: ScopeRequestContext) => Scope | Promise<Scope>;
+}
+
+/**
+ * Bouncer initializer (Epic 56.6) — a GLOBAL middleware (register it for every
+ * route, after `wardenMiddleware`). It builds the per-request {@link Bouncer}
+ * from the authenticated user (`ctx.auth?.user`, or `null` for a guest), the
+ * shared `RightsResolver`, and the registered abilities/policies, then attaches
+ * it as `ctx.bouncer`. Handlers authorize via `await ctx.bouncer.authorize(...)`
+ * (throws `WARDEN_AUTHORIZATION_FAILURE` carrying `status: 403`, which the host's
+ * ExceptionHandler maps to a 403 response) or branch on `ctx.bouncer.allows(...)`.
+ *
+ * Unlike `wardenMiddleware` (a per-route GUARD that short-circuits public
+ * routes), this runs on EVERY request so `ctx.bouncer` is always available —
+ * including for guests — matching AdonisJS's `initialize_bouncer_middleware`.
+ */
+export async function initializeBouncer(ctx: WardenContext, next: WardenNext) {
+	// Both dependencies are registered by WardenProvider. Resolve defensively:
+	// a host that wired the middleware but not the provider gets an empty Bouncer
+	// (no abilities/resolver) rather than a crash on every request.
+	const resolved = tryResolve(ctx, RightsResolver);
+	const resolver = resolved instanceof RightsResolver ? resolved : undefined;
+	const candidate = tryResolve(ctx, "bouncer:registry");
+	const registry = isBouncerRegistry(candidate) ? candidate : undefined;
+
+	const user = ctx.auth?.user ?? null;
+	const scope: Scope = registry?.resolveScope
+		? await registry.resolveScope(ctx)
+		: "global";
+
+	ctx.bouncer = new Bouncer(user, registry?.abilities, registry?.policies, {
+		scope,
+		resolver,
+	});
+	await next();
+}
+
+/** Resolve a container token, returning undefined instead of throwing when absent. */
+function tryResolve(
+	ctx: WardenContext,
+	token: string | (abstract new (...args: never[]) => unknown),
+): unknown {
+	try {
+		return ctx.container.resolve(token);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Structural guard — the registry is a plain object carrying ability/policy tables. */
+function isBouncerRegistry(value: unknown): value is BouncerRegistry {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"abilities" in value &&
+		"policies" in value
+	);
+}
+
+/**
+ * Resolve the request's authorization scope from the registry's `resolveScope`
+ * hook (default `"global"`). Shared so the @Role/@Permission decorator gate and
+ * the Bouncer path evaluate in the SAME scope — without this the decorator path
+ * hardcoded "global" and tenant-scoped roles/grants never satisfied @Role/@Permission.
+ */
+async function resolveRequestScope(ctx: WardenContext): Promise<Scope> {
+	const candidate = tryResolve(ctx, "bouncer:registry");
+	const registry = isBouncerRegistry(candidate) ? candidate : undefined;
+	return registry?.resolveScope ? await registry.resolveScope(ctx) : "global";
+}
+
 /**
  * Try each declared strategy in order — session strategies via
  * `verifyWithContext()`, others via `verify(token)` with native-first credential
@@ -264,13 +372,14 @@ async function checkAuthorization(
 	user: NonNullable<AuthResult["user"]>,
 	controller: object,
 	action: string | symbol,
+	scope: Scope,
 ): Promise<string | null> {
 	const requiredPermissions = getPermissionMetadata(controller, action);
 	const requiredRoles = getRoleMetadata(controller, action);
 	if (requiredPermissions.length === 0 && requiredRoles.length === 0) {
 		return null;
 	}
-	const effective = await auth.resolvePermissions(user, "global");
+	const effective = await auth.resolvePermissions(user, scope);
 	if (requiredPermissions.length > 0) {
 		const missing = requiredPermissions.filter((p) => !effective.has(p));
 		if (missing.length > 0) return `Missing permissions: ${missing.join(", ")}`;

package/src/standalone.ts

@@ -20,10 +20,13 @@
 import {
 	AuthManager,
 	type AuthResult,
+	type AuthStrategy,
 	type UserPayload,
 } from "./AuthManager.js";
 import type { WardenConfig } from "./config.js";
+import { ApiKeyStrategy } from "./strategies/ApiKeyStrategy.js";
 import { JwtStrategy } from "./strategies/JwtStrategy.js";
+import { SessionStrategy } from "./strategies/SessionStrategy.js";
 
 export interface Warden {
 	/** Verify a bearer token. Returns auth result with user payload. */
@@ -49,11 +52,21 @@ export interface Warden {
  * Create a standalone Warden instance — no Ream container needed.
  */
 export function createWarden(config: WardenConfig): Warden {
-	const strategies: Record<string, JwtStrategy> = {};
+	// Mirror WardenProvider: build EVERY configured strategy, not just jwt —
+	// otherwise config.session / config.apiKey were silently dropped and a
+	// jwt-less config (e.g. { defaultStrategy: 'api-key', apiKey }) threw
+	// INVALID_CONFIG at boot (audit 2026-06-13). Keys match the @Guard names.
+	const strategies: Record<string, AuthStrategy> = {};
 
 	if (config.jwt) {
 		strategies.jwt = new JwtStrategy(config.jwt);
 	}
+	if (config.session) {
+		strategies.session = new SessionStrategy(config.session);
+	}
+	if (config.apiKey) {
+		strategies["api-key"] = new ApiKeyStrategy(config.apiKey);
+	}
 
 	const manager = new AuthManager({
 		defaultStrategy: config.defaultStrategy ?? "jwt",

package/src/strategies/ApiKeyStrategy.ts

@@ -45,7 +45,20 @@ export class ApiKeyStrategy implements AuthStrategy {
 
 		const user: UserPayload = { ...result.user };
 		if (result.scopes && result.scopes.length > 0) {
-			// Merge scopes into permissions without mutating source object.
+			// Expose the API key's scopes on `user.permissions` (without mutating
+			// the source object) so APP code can read them via
+			// `ctx.auth.user.permissions`.
+			//
+			// IMPORTANT — these scopes are a SEPARATE axis from the `@Permission`
+			// route gate, by design (Adonis Bouncer parity): the gate flows through
+			// RightsResolver, which resolves grants from the rights STORE and
+			// deliberately ignores payload-carried permissions (see RightsResolver
+			// D1). This mirrors AdonisJS, where token abilities are checked via
+			// `currentAccessToken.allows(scope)` and are NOT consulted by Bouncer
+			// ability/policy checks. So an API key carrying `orders.create` is NOT
+			// auto-granted by `@Permission('orders.create')` — that's intentional,
+			// not a bug. Gate API-key routes on scopes with an explicit app-level
+			// check against `ctx.auth.user.permissions`.
 			const merged = new Set([...(user.permissions ?? []), ...result.scopes]);
 			user.permissions = [...merged];
 		}