@c9up/warden 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @c9up/warden
+
+Authentication & authorization for Node.js. Multi-strategy auth, RBAC, decorators.
+
+## Usage
+
+```typescript
+import { AuthManager, Guard, Permission, Role } from '@c9up/warden'
+
+const auth = new AuthManager({
+  defaultStrategy: 'jwt',
+  strategies: { jwt: myJwtStrategy },
+})
+
+const result = await auth.authenticate({ email: 'admin@c9up.com', password: 'secret' })
+auth.hasRole(result.user!, 'admin') // true
+
+class OrderController {
+  @Guard('jwt')
+  @Permission('orders.create')
+  async create() { /* protected */ }
+}
+```
+
+## Features
+
+- Multi-strategy AuthManager (JWT, session, API key, OAuth)
+- `@Guard()`, `@Permission()`, `@Role()` decorators
+- RBAC: `hasRole`, `hasPermission`, `hasAllPermissions`
+- Strategy exception safety (catch → AuthResult)
+- Runtime strategy registration
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@c9up/warden",
+  "version": "0.1.0",
+  "description": "Warden — Authentication for the Ream framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "index.*.node",
+    "scripts",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/WardenProvider.d.ts",
+      "import": "./dist/WardenProvider.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
+    },
+    "./standalone": {
+      "types": "./dist/standalone.d.ts",
+      "import": "./dist/standalone.js"
+    },
+    "./configure": {
+      "types": "./dist/configure.d.ts",
+      "import": "./dist/configure.js"
+    }
+  },
+  "peerDependencies": {
+    "@c9up/ream": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/ream": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "reflect-metadata": "^0.2.2",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/warden.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:rust": "cargo build --release -p warden-engine-napi",
+    "build:napi": "pnpm build:rust && node scripts/copy-napi.mjs",
+    "test": "vitest run",
+    "test:rust": "cargo test -p warden-engine",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/scripts/copy-napi.mjs

@@ -0,0 +1,67 @@
+import { copyFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { arch, env, platform } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+const CRATE = 'warden_engine_napi'
+const TAG = '[warden:napi]'
+
+// Rust target triple -> { suffix, os }. Set CARGO_BUILD_TARGET to cross-compile
+// (e.g. build the x86_64-apple-darwin binary on an arm64 macOS runner). When
+// unset we fall back to the host platform/arch and the default target/release.
+const tripleMap = {
+  'x86_64-unknown-linux-gnu': { suffix: 'linux-x64-gnu', os: 'linux' },
+  'aarch64-unknown-linux-gnu': { suffix: 'linux-arm64-gnu', os: 'linux' },
+  'x86_64-apple-darwin': { suffix: 'darwin-x64', os: 'darwin' },
+  'aarch64-apple-darwin': { suffix: 'darwin-arm64', os: 'darwin' },
+  'x86_64-pc-windows-msvc': { suffix: 'win32-x64-msvc', os: 'win32' },
+}
+
+const hostSuffixMap = {
+  'linux-x64': 'linux-x64-gnu',
+  'linux-arm64': 'linux-arm64-gnu',
+  'darwin-x64': 'darwin-x64',
+  'darwin-arm64': 'darwin-arm64',
+  'win32-x64': 'win32-x64-msvc',
+}
+
+const triple = env.CARGO_BUILD_TARGET ?? ''
+let suffix
+let os
+let releaseDir
+if (triple) {
+  const entry = tripleMap[triple]
+  if (!entry) {
+    throw new Error(`${TAG} unsupported CARGO_BUILD_TARGET: ${triple}`)
+  }
+  suffix = entry.suffix
+  os = entry.os
+  releaseDir = join(root, 'target', triple, 'release')
+} else {
+  suffix = hostSuffixMap[`${platform}-${arch}`]
+  os = platform
+  releaseDir = join(root, 'target', 'release')
+  if (!suffix) {
+    throw new Error(`${TAG} unsupported platform/arch: ${platform}-${arch}`)
+  }
+}
+
+const candidates =
+  os === 'win32'
+    ? [join(releaseDir, `${CRATE}.dll`), join(releaseDir, `lib${CRATE}.dll`)]
+    : os === 'darwin'
+      ? [join(releaseDir, `lib${CRATE}.dylib`)]
+      : [join(releaseDir, `lib${CRATE}.so`)]
+
+const source = candidates.find((candidate) => existsSync(candidate))
+if (!source) {
+  throw new Error(
+    `${TAG} native library not found. Looked for:\n${candidates.map((p) => `- ${p}`).join('\n')}`,
+  )
+}
+
+const target = join(root, `index.${suffix}.node`)
+copyFileSync(source, target)
+console.log(`${TAG} copied ${source} -> ${target}`)

package/src/AuthManager.ts

@@ -0,0 +1,228 @@
+/**
+ * AuthManager — manages multiple authentication strategies.
+ *
+ * @implements FR48, FR50, FR51
+ */
+
+import { WardenError } from "./errors.js";
+import { MemoryRightsStore } from "./rights/MemoryRightsStore.js";
+import { RightsResolver } from "./rights/RightsResolver.js";
+import type { EffectivePermissions, Scope } from "./rights/types.js";
+
+export interface UserPayload {
+	id: string;
+	roles?: string[];
+	permissions?: string[];
+	[key: string]: unknown;
+}
+
+export interface AuthResult {
+	authenticated: boolean;
+	user?: UserPayload;
+	error?: string;
+	/**
+	 * @internal Set when the strategy's `verify()` / `authenticate()` THREW
+	 * a generic error (vs returned a deliberate `{ authenticated: false }`
+	 * rejection). The middleware uses this to distinguish credential
+	 * failures (→ 401) from strategy crashes (→ 500). Not part of the
+	 * public consumer-facing API.
+	 */
+	strategyCrash?: true;
+}
+
+export interface AuthStrategy {
+	name: string;
+	authenticate(credentials: Record<string, unknown>): Promise<AuthResult>;
+	verify(token: string, context?: Record<string, unknown>): Promise<AuthResult>;
+}
+
+export interface AuthConfig {
+	defaultStrategy: string;
+	strategies: Record<string, AuthStrategy>;
+	/**
+	 * The rights resolver backing the coarse RBAC helpers (Epic 56). When
+	 * absent, a default `RightsResolver(new MemoryRightsStore())` is used so
+	 * `new AuthManager({ defaultStrategy, strategies })` keeps working — with
+	 * an empty store, payload roles still fold in (D2) and permissions are
+	 * empty (token `user.permissions` is not an input — D1).
+	 */
+	rights?: RightsResolver;
+}
+
+/**
+ * Manages authentication strategies and provides guard/permission checks.
+ */
+export class AuthManager {
+	private strategies: Map<string, AuthStrategy> = new Map();
+	private defaultStrategy: string;
+	private readonly rights: RightsResolver;
+
+	constructor(config: AuthConfig) {
+		this.defaultStrategy = config.defaultStrategy;
+		this.rights = config.rights ?? new RightsResolver(new MemoryRightsStore());
+		for (const [name, strategy] of Object.entries(config.strategies)) {
+			this.strategies.set(name, strategy);
+		}
+		// Fail-fast at construction: an AuthManager with zero strategies
+		// is a configuration bug. Previously, an empty `strategies: {}`
+		// passed the constructor cleanly and the first protected request
+		// crashed at runtime when `getStrategy('jwt')` threw — opaque 401
+		// or 500 instead of a boot-time INVALID_CONFIG that points the
+		// operator at the missing `config.auth.jwt` (or other strategy).
+		if (Object.keys(config.strategies).length === 0) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				`AuthManager: no authentication strategies registered. Configure at least one strategy (e.g. config.warden.auth.jwt) before booting WardenProvider.`,
+			);
+		}
+		if (!this.strategies.has(config.defaultStrategy)) {
+			throw new WardenError(
+				"INVALID_CONFIG",
+				`defaultStrategy '${config.defaultStrategy}' is not present in strategies`,
+			);
+		}
+	}
+
+	/** Authenticate with credentials using a specific or default strategy. */
+	async authenticate(
+		credentials: Record<string, unknown>,
+		strategyName?: string,
+	): Promise<AuthResult> {
+		const strategy = this.getStrategy(strategyName);
+		try {
+			const result = await strategy.authenticate(credentials);
+			if (result.user) sanitizePayload(result.user);
+			return result;
+		} catch (err) {
+			// Re-throw structured WardenError sentinels (e.g. SessionStrategy's
+			// USE_LOGIN throw) so callers see the design-boundary signal instead
+			// of a soft `{ authenticated: false }`. Generic errors stay soft.
+			if (err instanceof WardenError) throw err;
+			return {
+				authenticated: false,
+				error:
+					err instanceof Error ? err.message : "Unknown authentication error",
+			};
+		}
+	}
+
+	/** Verify a token (JWT, session, API key). */
+	async verify(
+		token: string,
+		strategyName?: string,
+		context?: Record<string, unknown>,
+	): Promise<AuthResult> {
+		const strategy = this.getStrategy(strategyName);
+		try {
+			const result = await strategy.verify(token, context);
+			if (result.user) sanitizePayload(result.user);
+			return result;
+		} catch (err) {
+			// Mirror authenticate(): rethrow structured WardenError sentinels;
+			// soft-fail generic throws but TAG them as strategy crashes so the
+			// middleware can flip 401 → 500 when every attempted strategy bombed.
+			if (err instanceof WardenError) throw err;
+			return {
+				authenticated: false,
+				error:
+					err instanceof Error ? err.message : "Unknown verification error",
+				strategyCrash: true,
+			};
+		}
+	}
+
+	/**
+	 * Resolve a user's effective permissions for a scope (Epic 56). The single
+	 * resolution entry the coarse helpers wrap — `hasRole`/`hasPermission`/
+	 * `hasAllPermissions` read this set, never the token payload directly. The
+	 * Bouncer policy path (`this.permissions`, 56.3) consults the SAME resolver,
+	 * so a coarse question and a policy question return the same answer for the
+	 * same `(user, scope)` (the single unification point — AC-E3).
+	 */
+	resolvePermissions(
+		user: UserPayload,
+		scope: Scope = "global",
+	): Promise<EffectivePermissions> {
+		return this.rights.resolve(user, scope);
+	}
+
+	/**
+	 * Check if a user has a specific role within a scope (default `"global"`).
+	 * Reflects payload roles ∪ store roles (D2) — a token-carried role still
+	 * satisfies it with no store config.
+	 */
+	async hasRole(
+		user: UserPayload,
+		role: string,
+		scope: Scope = "global",
+	): Promise<boolean> {
+		return (await this.resolvePermissions(user, scope)).roles.has(role);
+	}
+
+	/**
+	 * Check if a user has a specific permission within a scope (default
+	 * `"global"`). Derived from roles + store grants ONLY — token
+	 * `user.permissions` is NOT read (D1, cerebrum 459).
+	 */
+	async hasPermission(
+		user: UserPayload,
+		permission: string,
+		scope: Scope = "global",
+	): Promise<boolean> {
+		return (await this.resolvePermissions(user, scope)).has(permission);
+	}
+
+	/**
+	 * Check if a user has ALL required permissions within a scope (default
+	 * `"global"`). Empty list ⇒ vacuously true.
+	 */
+	async hasAllPermissions(
+		user: UserPayload,
+		permissions: string[],
+		scope: Scope = "global",
+	): Promise<boolean> {
+		return (await this.resolvePermissions(user, scope)).hasAll(permissions);
+	}
+
+	/** Get a registered strategy by name. */
+	getStrategy(name?: string): AuthStrategy {
+		const strategyName = name ?? this.defaultStrategy;
+		const strategy = this.strategies.get(strategyName);
+		if (!strategy) {
+			throw new WardenError(
+				"STRATEGY_NOT_FOUND",
+				`Auth strategy '${strategyName}' not registered`,
+				{
+					hint: "Call registerStrategy() before using this strategy name.",
+				},
+			);
+		}
+		return strategy;
+	}
+
+	/** Register a new strategy at runtime. */
+	registerStrategy(name: string, strategy: AuthStrategy): void {
+		this.strategies.set(name, strategy);
+	}
+
+	/** Get all registered strategy names. */
+	getStrategyNames(): string[] {
+		return [...this.strategies.keys()];
+	}
+}
+
+/** Strip dangerous prototype-pollution keys from user payload. */
+/**
+ * Strip prototype-pollution keys from a user payload before it's
+ * attached to the request. Exported so the middleware can apply it to
+ * the session path too — session auth goes through `verifyWithContext`
+ * directly (not `AuthManager.verify`), so without this it would skip
+ * the guard JWT / api-key users get.
+ */
+export function sanitizePayload(user: UserPayload): void {
+	for (const key of ["__proto__", "constructor", "prototype"]) {
+		if (key in user) {
+			delete (user as Record<string, unknown>)[key];
+		}
+	}
+}

package/src/AuthRateLimiter.ts

@@ -0,0 +1,105 @@
+/**
+ * AuthRateLimiter — brute force protection for login endpoints.
+ *
+ * Dual-key rate limiting: IP + email to prevent distributed attacks.
+ *
+ * @implements MISS-26
+ */
+
+export interface AuthRateLimiterConfig {
+	maxAttempts?: number; // default 5
+	windowSeconds?: number; // default 900 (15 min)
+}
+
+interface AttemptEntry {
+	count: number;
+	resetAt: number;
+}
+
+export class AuthRateLimiter {
+	private maxAttempts: number;
+	private window: number;
+	private store: Map<string, AttemptEntry> = new Map();
+	private maxStoreSize = 100_000;
+
+	constructor(config?: AuthRateLimiterConfig) {
+		this.maxAttempts = config?.maxAttempts ?? 5;
+		if (this.maxAttempts <= 0) this.maxAttempts = 1;
+		this.window = (config?.windowSeconds ?? 900) * 1000;
+		if (this.window <= 0) this.window = 900_000; // prevent bypass via 0/negative
+	}
+
+	/** Check if an attempt is allowed. Returns false if rate limited. */
+	check(ip: string, identifier: string): boolean {
+		const now = Date.now();
+		const ipNorm = normalizeIp(ip);
+		const identifierNorm = normalizeIdentifier(identifier);
+		// Dual key: limit both by IP and by identifier (email)
+		const ipKey = `ip:${ipNorm}`;
+		const idKey = `id:${identifierNorm}`;
+
+		return this.checkKey(ipKey, now) && this.checkKey(idKey, now);
+	}
+
+	/** Record a failed attempt. */
+	recordFailure(ip: string, identifier: string): void {
+		const now = Date.now();
+		const ipNorm = normalizeIp(ip);
+		const identifierNorm = normalizeIdentifier(identifier);
+		this.increment(`ip:${ipNorm}`, now);
+		this.increment(`id:${identifierNorm}`, now);
+	}
+
+	/** Reset counters on successful login. */
+	recordSuccess(ip: string, identifier: string): void {
+		const ipNorm = normalizeIp(ip);
+		const identifierNorm = normalizeIdentifier(identifier);
+		this.store.delete(`ip:${ipNorm}`);
+		this.store.delete(`id:${identifierNorm}`);
+	}
+
+	/** Get remaining attempts for an identifier. */
+	remaining(ip: string, identifier: string): number {
+		const ipNorm = normalizeIp(ip);
+		const identifierNorm = normalizeIdentifier(identifier);
+		const ipEntry = this.store.get(`ip:${ipNorm}`);
+		const idEntry = this.store.get(`id:${identifierNorm}`);
+		const ipRemaining = ipEntry
+			? Math.max(0, this.maxAttempts - ipEntry.count)
+			: this.maxAttempts;
+		const idRemaining = idEntry
+			? Math.max(0, this.maxAttempts - idEntry.count)
+			: this.maxAttempts;
+		return Math.min(ipRemaining, idRemaining);
+	}
+
+	private checkKey(key: string, now: number): boolean {
+		const entry = this.store.get(key);
+		if (!entry || entry.resetAt < now) return true;
+		return entry.count < this.maxAttempts;
+	}
+
+	private increment(key: string, now: number): void {
+		// Evict expired entries when store grows too large (prevent OOM)
+		if (this.store.size > this.maxStoreSize) {
+			for (const [k, v] of this.store) {
+				if (v.resetAt < now) this.store.delete(k);
+			}
+		}
+
+		let entry = this.store.get(key);
+		if (!entry || entry.resetAt < now) {
+			entry = { count: 0, resetAt: now + this.window };
+			this.store.set(key, entry);
+		}
+		entry.count++;
+	}
+}
+
+function normalizeIdentifier(identifier: string): string {
+	return identifier.trim().toLowerCase();
+}
+
+function normalizeIp(ip: string): string {
+	return ip.trim();
+}

package/src/Guard.ts

@@ -0,0 +1,68 @@
+/**
+ * @Guard() decorator — protects route handlers with authentication.
+ *
+ * @implements FR50, FR51
+ */
+
+// Side-effect import: registers the `Reflect.defineMetadata` / `getOwnMetadata`
+// methods used below. Pulled in here (not transitively via the framework)
+// so warden remains self-sufficient when published / consumed standalone.
+import "reflect-metadata";
+
+/** Guard decorator metadata key — Symbol.for ensures cross-module accessibility. */
+const GUARD_KEY = Symbol.for("warden:guard");
+const PERMISSION_KEY = Symbol.for("warden:permission");
+const ROLE_KEY = Symbol.for("warden:role");
+
+/**
+ * @Guard('jwt') — require authentication via the named strategy.
+ * At least one strategy name is required.
+ */
+export function Guard(first: string, ...rest: string[]): MethodDecorator {
+	const strategies = [first, ...rest];
+	return (target, propertyKey) => {
+		Reflect.defineMetadata(GUARD_KEY, strategies, target, propertyKey);
+	};
+}
+
+/**
+ * @Permission('orders.create') — require specific permissions.
+ */
+export function Permission(...permissions: string[]): MethodDecorator {
+	return (target, propertyKey) => {
+		Reflect.defineMetadata(PERMISSION_KEY, permissions, target, propertyKey);
+	};
+}
+
+/**
+ * @Role('admin') — require specific roles.
+ */
+export function Role(...roles: string[]): MethodDecorator {
+	return (target, propertyKey) => {
+		Reflect.defineMetadata(ROLE_KEY, roles, target, propertyKey);
+	};
+}
+
+/** Get guard metadata. */
+export function getGuardMetadata(
+	target: object,
+	propertyKey: string | symbol,
+): string[] {
+	return Reflect.getOwnMetadata(GUARD_KEY, target, propertyKey) ?? [];
+}
+
+/** Get permission metadata. */
+export function getPermissionMetadata(
+	target: object,
+	propertyKey: string | symbol,
+): string[] {
+	return Reflect.getOwnMetadata(PERMISSION_KEY, target, propertyKey) ?? [];
+}
+
+/** Get role metadata. */
+export function getRoleMetadata(
+	target: object,
+	propertyKey: string | symbol,
+): string[] {
+	return Reflect.getOwnMetadata(ROLE_KEY, target, propertyKey) ?? [];
+}

package/src/RefreshTokenStore.ts

@@ -0,0 +1,67 @@
+/**
+ * RefreshTokenStore — server-side opaque refresh token management.
+ *
+ * AdonisJS opaque token pattern:
+ *   { accessToken, refreshToken, expiresIn }
+ *   POST /auth/refresh → new pair, old token invalidated
+ *
+ * @implements MISS-5
+ */
+
+import { randomBytes } from "node:crypto";
+
+export interface StoredRefreshToken {
+	token: string;
+	userId: string | number;
+	expiresAt: number;
+	createdAt: number;
+}
+
+export interface RefreshTokenDriver {
+	store(token: StoredRefreshToken): Promise<void>;
+	find(token: string): Promise<StoredRefreshToken | null>;
+	revoke(token: string): Promise<void>;
+	revokeAllForUser(userId: string | number): Promise<void>;
+	cleanup(): Promise<void>;
+}
+
+/** In-memory driver for development. */
+export class MemoryRefreshTokenDriver implements RefreshTokenDriver {
+	private tokens: Map<string, StoredRefreshToken> = new Map();
+
+	async store(token: StoredRefreshToken): Promise<void> {
+		this.tokens.set(token.token, token);
+	}
+
+	async find(token: string): Promise<StoredRefreshToken | null> {
+		const stored = this.tokens.get(token);
+		if (!stored) return null;
+		if (stored.expiresAt < Date.now()) {
+			this.tokens.delete(token);
+			return null;
+		}
+		return stored;
+	}
+
+	async revoke(token: string): Promise<void> {
+		this.tokens.delete(token);
+	}
+
+	async revokeAllForUser(userId: string | number): Promise<void> {
+		for (const [key, val] of this.tokens) {
+			if (val.userId === userId) this.tokens.delete(key);
+		}
+	}
+
+	async cleanup(): Promise<void> {
+		const now = Date.now();
+		for (const [key, val] of this.tokens) {
+			if (val.expiresAt < now) this.tokens.delete(key);
+		}
+	}
+}
+
+/** Generate an opaque refresh token. */
+export function generateRefreshToken(): string {
+	return randomBytes(48).toString("base64url");
+}