@veloxts/auth 0.6.83 → 0.6.85

package/dist/adapters/utils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared utilities for auth adapters
+ *
+ * @module auth/adapters/utils
+ * @internal
+ */
+/**
+ * Extract Bearer token from Authorization header
+ *
+ * @param headerValue - Authorization header value
+ * @returns Token string or null if not a Bearer token
+ *
+ * @example
+ * ```typescript
+ * const token = extractBearerToken('Bearer eyJhbGci...');
+ * // Returns: 'eyJhbGci...'
+ *
+ * const invalid = extractBearerToken('Basic abc123');
+ * // Returns: null
+ * ```
+ */
+export declare function extractBearerToken(headerValue: string): string | null;
+/**
+ * Validates that a string value is non-empty
+ *
+ * @param value - Value to check
+ * @param fieldName - Field name for error message
+ * @returns The trimmed value if valid
+ * @throws Error if value is empty or whitespace-only
+ */
+export declare function validateNonEmptyString(value: string | undefined, fieldName: string): string;

package/dist/adapters/utils.js

@@ -0,0 +1,49 @@
+/**
+ * Shared utilities for auth adapters
+ *
+ * @module auth/adapters/utils
+ * @internal
+ */
+// ============================================================================
+// Token Extraction
+// ============================================================================
+/**
+ * Extract Bearer token from Authorization header
+ *
+ * @param headerValue - Authorization header value
+ * @returns Token string or null if not a Bearer token
+ *
+ * @example
+ * ```typescript
+ * const token = extractBearerToken('Bearer eyJhbGci...');
+ * // Returns: 'eyJhbGci...'
+ *
+ * const invalid = extractBearerToken('Basic abc123');
+ * // Returns: null
+ * ```
+ */
+export function extractBearerToken(headerValue) {
+    const parts = headerValue.split(' ');
+    if (parts.length !== 2 || parts[0].toLowerCase() !== 'bearer') {
+        return null;
+    }
+    // Trim whitespace from token to handle malformed headers
+    return parts[1].trim();
+}
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validates that a string value is non-empty
+ *
+ * @param value - Value to check
+ * @param fieldName - Field name for error message
+ * @returns The trimmed value if valid
+ * @throws Error if value is empty or whitespace-only
+ */
+export function validateNonEmptyString(value, fieldName) {
+    if (!value || value.trim() === '') {
+        throw new Error(`${fieldName} is required and cannot be empty`);
+    }
+    return value.trim();
+}

package/dist/guards.d.ts

@@ -18,13 +18,83 @@ import type { AuthContext, GuardDefinition, GuardFunction, User } from './types.
  */
 export declare function defineGuard<TContext = unknown>(definition: GuardDefinition<TContext>): GuardDefinition<TContext>;
 /**
- * Creates a simple guard from a check function
+ * Fluent guard builder for progressive configuration
  *
+ * Allows building guards step-by-step with method chaining.
+ * The builder is compatible with GuardLike, so it can be used
+ * directly with `.guard()` on procedures.
+ *
+ * **Note**: This builder uses mutable internal state. Each method
+ * modifies the builder and returns the same instance. See
+ * `createGuardBuilder` for usage patterns and caveats.
+ */
+export interface GuardBuilder<TContext> {
+    /** Guard name for error messages (read-only, set via named()) */
+    readonly name: string;
+    /** Guard check function (read-only) */
+    readonly check: GuardFunction<TContext>;
+    /** Custom error message (read-only, set via msg()) */
+    readonly message: string | undefined;
+    /** HTTP status code on failure (read-only, set via status()) */
+    readonly statusCode: number;
+    /** Set a descriptive name (used in error messages and debugging) */
+    named(name: string): GuardBuilder<TContext>;
+    /** Set custom error message shown when guard fails */
+    msg(message: string): GuardBuilder<TContext>;
+    /** Set HTTP status code returned when guard fails (default: 403) */
+    status(code: number): GuardBuilder<TContext>;
+}
+/**
+ * Resets the guard counter to zero.
+ *
+ * This is intended for testing purposes only to ensure deterministic
+ * guard naming across test runs. Should not be used in production code.
+ *
+ * @internal
  * @example
  * ```typescript
+ * import { _resetGuardCounter } from '@veloxts/auth';
+ *
+ * beforeEach(() => {
+ *   _resetGuardCounter();
+ * });
+ * ```
+ */
+export declare function _resetGuardCounter(): void;
+/**
+ * Creates a guard with simplified syntax
+ *
+ * Supports three usage patterns with progressive disclosure:
+ *
+ * @example Simple check function (returns builder for configuration)
+ * ```typescript
+ * const isVerified = guard((ctx) => ctx.user?.emailVerified === true)
+ *   .msg('Email verification required');
+ * ```
+ *
+ * @example Check with message (most common - auto-generates name)
+ * ```typescript
+ * const isVerified = guard(
+ *   (ctx) => ctx.user?.emailVerified === true,
+ *   'Email verification required'
+ * );
+ * ```
+ *
+ * @example Named guard (explicit name for debugging)
+ * ```typescript
  * const isActive = guard('isActive', (ctx) => ctx.user?.status === 'active');
  * ```
+ *
+ * @example Full fluent configuration
+ * ```typescript
+ * const isPremium = guard((ctx) => ctx.user?.subscription === 'premium')
+ *   .named('isPremium')
+ *   .msg('Premium subscription required')
+ *   .status(402);
+ * ```
  */
+export declare function guard<TContext = unknown>(check: GuardFunction<TContext>): GuardBuilder<TContext>;
+export declare function guard<TContext = unknown>(check: GuardFunction<TContext>, message: string): GuardDefinition<TContext>;
 export declare function guard<TContext = unknown>(name: string, check: GuardFunction<TContext>): GuardDefinition<TContext>;
 /**
  * Guard that requires authentication

package/dist/guards.js

@@ -24,15 +24,131 @@ export function defineGuard(definition) {
     };
 }
 /**
- * Creates a simple guard from a check function
+ * Counter for generating unique guard names when not provided
+ * @internal
+ */
+let guardCounter = 0;
+/**
+ * Resets the guard counter to zero.
+ *
+ * This is intended for testing purposes only to ensure deterministic
+ * guard naming across test runs. Should not be used in production code.
  *
+ * @internal
  * @example
  * ```typescript
- * const isActive = guard('isActive', (ctx) => ctx.user?.status === 'active');
+ * import { _resetGuardCounter } from '@veloxts/auth';
+ *
+ * beforeEach(() => {
+ *   _resetGuardCounter();
+ * });
+ * ```
+ */
+export function _resetGuardCounter() {
+    guardCounter = 0;
+}
+/**
+ * Attempts to infer a meaningful name from a guard check function
+ * @internal
+ */
+function inferGuardName(check) {
+    // Try to use function name if it exists and isn't generic
+    if (check.name && check.name !== 'check' && check.name !== 'anonymous') {
+        return check.name;
+    }
+    // Fall back to generated name
+    return `guard_${++guardCounter}`;
+}
+/**
+ * Creates a guard builder instance.
+ *
+ * The builder uses **mutable internal state** with method chaining that returns
+ * the same instance. This is intentional for performance and API simplicity:
+ *
+ * ```typescript
+ * // Each method mutates the builder and returns `this`
+ * const myGuard = guard((ctx) => ctx.user?.active)
+ *   .named('isActive')      // Mutates name, returns same builder
+ *   .msg('User inactive')   // Mutates message, returns same builder
+ *   .status(403);           // Mutates statusCode, returns same builder
+ *
+ * // The builder IS the guard definition (implements GuardLike)
+ * // No need to call .build() - use directly with .guard()
+ * ```
+ *
+ * **Important**: Because the builder mutates, avoid patterns like:
+ * ```typescript
+ * // DON'T do this - both variables reference the same mutable builder
+ * const base = guard((ctx) => ctx.user != null);
+ * const withMsg = base.msg('Auth required');
+ * const withOtherMsg = base.msg('Login needed'); // Overwrites previous msg!
+ * ```
+ *
+ * If you need variations, create separate guards:
+ * ```typescript
+ * const authRequired = guard((ctx) => ctx.user != null, 'Auth required');
+ * const loginNeeded = guard((ctx) => ctx.user != null, 'Login needed');
  * ```
+ *
+ * @internal
  */
-export function guard(name, check) {
-    return defineGuard({ name, check });
+function createGuardBuilder(check, initialName) {
+    // Mutable internal state - intentionally not exposed directly
+    let guardName = initialName;
+    let guardMessage;
+    let guardStatusCode = 403;
+    const builder = {
+        // GuardLike compatible properties (getters for current values)
+        get name() {
+            return guardName;
+        },
+        get check() {
+            return check;
+        },
+        get message() {
+            return guardMessage;
+        },
+        get statusCode() {
+            return guardStatusCode;
+        },
+        // Builder methods (return self for chaining)
+        named(name) {
+            guardName = name;
+            return builder;
+        },
+        msg(message) {
+            guardMessage = message;
+            return builder;
+        },
+        status(code) {
+            guardStatusCode = code;
+            return builder;
+        },
+    };
+    return builder;
+}
+// Implementation
+export function guard(nameOrCheck, checkOrMessage) {
+    // Overload 3: Legacy (name, check)
+    if (typeof nameOrCheck === 'string' && typeof checkOrMessage === 'function') {
+        return defineGuard({ name: nameOrCheck, check: checkOrMessage });
+    }
+    // Overloads 1 & 2: (check) or (check, message)
+    if (typeof nameOrCheck === 'function') {
+        const check = nameOrCheck;
+        const message = typeof checkOrMessage === 'string' ? checkOrMessage : undefined;
+        if (message !== undefined) {
+            // Overload 2: Simple form with message - return completed guard
+            return defineGuard({
+                name: inferGuardName(check),
+                check,
+                message,
+            });
+        }
+        // Overload 1: Return builder for fluent configuration
+        return createGuardBuilder(check, inferGuardName(check));
+    }
+    throw new Error('Invalid guard arguments: expected (check), (check, message), or (name, check)');
 }
 // ============================================================================
 // Built-in Guards

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { createEnhancedTokenStore, DEFAULT_ALLOWED_ROLES, parseUserRoles, } from
 export type { AuthenticatedContext, InferNarrowedContext, NarrowingGuard, RoleNarrowedContext, } from './guards-narrowing.js';
 export { authenticatedNarrow, hasRoleNarrow } from './guards-narrowing.js';
 export { hashPassword, PasswordHasher, passwordHasher, verifyPassword, } from './hash.js';
+export type { GuardBuilder } from './guards.js';
 export { allOf, anyOf, authenticated, defineGuard, emailVerified, executeGuard, executeGuards, guard, hasAnyPermission, hasPermission, hasRole, not, userCan, } from './guards.js';
 export { authorize, can, cannot, clearPolicies, createAdminOnlyPolicy, createOwnerOrAdminPolicy, createPolicyBuilder, createReadOnlyPolicy, definePolicy, getPolicy, registerPolicy, } from './policies.js';
 export { authMiddleware, clearRateLimitStore, rateLimitMiddleware, } from './middleware.js';

package/dist/index.js

@@ -23,9 +23,6 @@ export { authenticatedNarrow, hasRoleNarrow } from './guards-narrowing.js';
 // Password Hashing
 // ============================================================================
 export { hashPassword, PasswordHasher, passwordHasher, verifyPassword, } from './hash.js';
-// ============================================================================
-// Guards
-// ============================================================================
 export { 
 // Combinators
 allOf, anyOf, 
@@ -35,6 +32,7 @@ authenticated,
 defineGuard, emailVerified, 
 // Execution
 executeGuard, executeGuards, guard, hasAnyPermission, hasPermission, hasRole, not, userCan, } from './guards.js';
+// NOTE: _resetGuardCounter is available via '@veloxts/auth/testing' for test isolation
 // ============================================================================
 // Policies
 // ============================================================================

package/dist/rate-limit.js

@@ -70,6 +70,70 @@ export function clearAuthRateLimitStore() {
 // Start cleanup on module load
 startCleanup();
 // ============================================================================
+// Configuration Helpers
+// ============================================================================
+/** Time constants for readability */
+const FIFTEEN_MINUTES_MS = 15 * 60 * 1000;
+const ONE_HOUR_MS = 60 * 60 * 1000;
+const ONE_MINUTE_MS = 60 * 1000;
+/** IP-only key generator */
+const ipOnlyKeyGenerator = (ctx) => ctx.request.ip ?? 'unknown';
+/**
+ * Default key generator combining IP and identifier
+ */
+function defaultKeyGenerator(ctx, identifier) {
+    const ip = ctx.request.ip ?? 'unknown';
+    return identifier ? `${ip}:${identifier.toLowerCase()}` : ip;
+}
+const OPERATION_DEFAULTS = {
+    login: {
+        maxAttempts: 5,
+        windowMs: FIFTEEN_MINUTES_MS,
+        lockoutDurationMs: FIFTEEN_MINUTES_MS,
+        keyGenerator: defaultKeyGenerator,
+        message: 'Too many login attempts. Please try again later.',
+        progressiveBackoff: true,
+    },
+    register: {
+        maxAttempts: 3,
+        windowMs: ONE_HOUR_MS,
+        lockoutDurationMs: ONE_HOUR_MS,
+        keyGenerator: ipOnlyKeyGenerator,
+        message: 'Too many registration attempts. Please try again later.',
+        progressiveBackoff: false,
+    },
+    passwordReset: {
+        maxAttempts: 3,
+        windowMs: ONE_HOUR_MS,
+        lockoutDurationMs: ONE_HOUR_MS,
+        keyGenerator: ipOnlyKeyGenerator,
+        message: 'Too many password reset attempts. Please try again later.',
+        progressiveBackoff: false,
+    },
+    refresh: {
+        maxAttempts: 10,
+        windowMs: ONE_MINUTE_MS,
+        lockoutDurationMs: ONE_MINUTE_MS,
+        keyGenerator: ipOnlyKeyGenerator,
+        message: 'Too many token refresh attempts. Please try again later.',
+        progressiveBackoff: false,
+    },
+};
+/**
+ * Build a complete rate limit config by merging user config with defaults
+ */
+function buildRateLimitConfig(userConfig, operation) {
+    const defaults = OPERATION_DEFAULTS[operation];
+    return {
+        maxAttempts: userConfig?.maxAttempts ?? defaults.maxAttempts,
+        windowMs: userConfig?.windowMs ?? defaults.windowMs,
+        lockoutDurationMs: userConfig?.lockoutDurationMs ?? defaults.lockoutDurationMs,
+        keyGenerator: userConfig?.keyGenerator ?? defaults.keyGenerator,
+        message: userConfig?.message ?? defaults.message,
+        progressiveBackoff: userConfig?.progressiveBackoff ?? defaults.progressiveBackoff,
+    };
+}
+// ============================================================================
 // Auth Rate Limiter
 // ============================================================================
 /**
@@ -96,38 +160,17 @@ startCleanup();
  * ```
  */
 export function createAuthRateLimiter(config = {}) {
-    // Default configurations
-    const loginConfig = {
-        maxAttempts: config.login?.maxAttempts ?? 5,
-        windowMs: config.login?.windowMs ?? 15 * 60 * 1000, // 15 minutes
-        lockoutDurationMs: config.login?.lockoutDurationMs ?? 15 * 60 * 1000,
-        keyGenerator: config.login?.keyGenerator ?? defaultKeyGenerator,
-        message: config.login?.message ?? 'Too many login attempts. Please try again later.',
-        progressiveBackoff: config.login?.progressiveBackoff ?? true,
-    };
-    const registerConfig = {
-        maxAttempts: config.register?.maxAttempts ?? 3,
-        windowMs: config.register?.windowMs ?? 60 * 60 * 1000, // 1 hour
-        lockoutDurationMs: config.register?.lockoutDurationMs ?? 60 * 60 * 1000,
-        keyGenerator: config.register?.keyGenerator ?? ((ctx) => ctx.request.ip ?? 'unknown'),
-        message: config.register?.message ?? 'Too many registration attempts. Please try again later.',
-        progressiveBackoff: config.register?.progressiveBackoff ?? false,
-    };
-    const passwordResetConfig = {
-        maxAttempts: config.passwordReset?.maxAttempts ?? 3,
-        windowMs: config.passwordReset?.windowMs ?? 60 * 60 * 1000, // 1 hour
-        lockoutDurationMs: config.passwordReset?.lockoutDurationMs ?? 60 * 60 * 1000,
-        keyGenerator: config.passwordReset?.keyGenerator ?? ((ctx) => ctx.request.ip ?? 'unknown'),
-        message: config.passwordReset?.message ?? 'Too many password reset attempts. Please try again later.',
-        progressiveBackoff: config.passwordReset?.progressiveBackoff ?? false,
-    };
-    const refreshConfig = {
-        maxAttempts: config.refresh?.maxAttempts ?? 10,
-        windowMs: config.refresh?.windowMs ?? 60 * 1000, // 1 minute
-        lockoutDurationMs: config.refresh?.lockoutDurationMs ?? 60 * 1000,
-        keyGenerator: config.refresh?.keyGenerator ?? ((ctx) => ctx.request.ip ?? 'unknown'),
-        message: config.refresh?.message ?? 'Too many token refresh attempts. Please try again later.',
-        progressiveBackoff: config.refresh?.progressiveBackoff ?? false,
+    // Build configurations using helper
+    const loginConfig = buildRateLimitConfig(config.login, 'login');
+    const registerConfig = buildRateLimitConfig(config.register, 'register');
+    const passwordResetConfig = buildRateLimitConfig(config.passwordReset, 'passwordReset');
+    const refreshConfig = buildRateLimitConfig(config.refresh, 'refresh');
+    // Config lookup for operations
+    const configs = {
+        login: loginConfig,
+        register: registerConfig,
+        'password-reset': passwordResetConfig,
+        refresh: refreshConfig,
     };
     return {
         /**
@@ -178,18 +221,14 @@ export function createAuthRateLimiter(config = {}) {
          */
         recordFailure: (key, operation) => {
             const fullKey = `auth:${operation}:${key}`;
-            const config = operation === 'login'
-                ? loginConfig
-                : operation === 'register'
-                    ? registerConfig
-                    : passwordResetConfig;
+            const operationConfig = configs[operation];
             const now = Date.now();
             const entry = authRateLimitStore.get(fullKey);
             if (!entry || entry.windowResetAt <= now) {
                 // Start new window
                 authRateLimitStore.set(fullKey, {
                     attempts: 1,
-                    windowResetAt: now + config.windowMs,
+                    windowResetAt: now + operationConfig.windowMs,
                     lockoutUntil: null,
                     lockoutCount: entry?.lockoutCount ?? 0,
                 });
@@ -198,9 +237,11 @@ export function createAuthRateLimiter(config = {}) {
                 // Increment in current window
                 entry.attempts++;
                 // Check if lockout should trigger
-                if (entry.attempts >= config.maxAttempts) {
-                    const lockoutMultiplier = config.progressiveBackoff ? 2 ** entry.lockoutCount : 1;
-                    entry.lockoutUntil = now + config.lockoutDurationMs * lockoutMultiplier;
+                if (entry.attempts >= operationConfig.maxAttempts) {
+                    const lockoutMultiplier = operationConfig.progressiveBackoff
+                        ? 2 ** entry.lockoutCount
+                        : 1;
+                    entry.lockoutUntil = now + operationConfig.lockoutDurationMs * lockoutMultiplier;
                     entry.lockoutCount++;
                 }
             }
@@ -231,31 +272,18 @@ export function createAuthRateLimiter(config = {}) {
          */
         getRemainingAttempts: (key, operation) => {
             const fullKey = `auth:${operation}:${key}`;
-            const config = operation === 'login'
-                ? loginConfig
-                : operation === 'register'
-                    ? registerConfig
-                    : operation === 'refresh'
-                        ? refreshConfig
-                        : passwordResetConfig;
+            const operationConfig = configs[operation];
             const entry = authRateLimitStore.get(fullKey);
             if (!entry || entry.windowResetAt <= Date.now()) {
-                return config.maxAttempts;
+                return operationConfig.maxAttempts;
             }
-            return Math.max(0, config.maxAttempts - entry.attempts);
+            return Math.max(0, operationConfig.maxAttempts - entry.attempts);
         },
     };
 }
 // ============================================================================
 // Internal Helpers
 // ============================================================================
-/**
- * Default key generator combining IP and identifier
- */
-function defaultKeyGenerator(ctx, identifier) {
-    const ip = ctx.request.ip ?? 'unknown';
-    return identifier ? `${ip}:${identifier.toLowerCase()}` : ip;
-}
 /**
  * Creates the actual rate limit middleware
  */

package/dist/testing.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @veloxts/auth/testing - Internal testing utilities
+ *
+ * This module exports utilities intended for testing purposes only.
+ * These are NOT part of the public API and may change without notice.
+ *
+ * @example
+ * ```typescript
+ * import { _resetGuardCounter } from '@veloxts/auth/testing';
+ *
+ * beforeEach(() => {
+ *   _resetGuardCounter();
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ * @module @veloxts/auth/testing
+ */
+export { _resetGuardCounter } from './guards.js';
+export { clearRateLimitStore } from './middleware.js';
+export { clearPolicies } from './policies.js';
+export { clearAuthRateLimitStore, stopAuthRateLimitCleanup } from './rate-limit.js';

package/dist/testing.js

@@ -0,0 +1,25 @@
+/**
+ * @veloxts/auth/testing - Internal testing utilities
+ *
+ * This module exports utilities intended for testing purposes only.
+ * These are NOT part of the public API and may change without notice.
+ *
+ * @example
+ * ```typescript
+ * import { _resetGuardCounter } from '@veloxts/auth/testing';
+ *
+ * beforeEach(() => {
+ *   _resetGuardCounter();
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ * @module @veloxts/auth/testing
+ */
+// Guard testing utilities
+export { _resetGuardCounter } from './guards.js';
+// Rate limit store clearing (for test isolation)
+export { clearRateLimitStore } from './middleware.js';
+// Policy registry clearing (for test isolation)
+export { clearPolicies } from './policies.js';
+export { clearAuthRateLimitStore, stopAuthRateLimitCleanup } from './rate-limit.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/auth",
-  "version": "0.6.83",
+  "version": "0.6.85",
   "description": "Authentication and authorization system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +10,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
     "./adapters": {
       "types": "./dist/adapters/index.d.ts",
       "import": "./dist/adapters/index.js"
@@ -57,8 +61,8 @@
   "dependencies": {
     "@fastify/cookie": "11.0.2",
     "fastify": "5.6.2",
-    "@veloxts/core": "0.6.83",
-    "@veloxts/router": "0.6.83"
+    "@veloxts/core": "0.6.85",
+    "@veloxts/router": "0.6.85"
   },
   "peerDependencies": {
     "argon2": ">=0.30.0",
@@ -82,8 +86,8 @@
     "fastify-plugin": "5.1.0",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@veloxts/validation": "0.6.83",
-    "@veloxts/testing": "0.6.83"
+    "@veloxts/validation": "0.6.85",
+    "@veloxts/testing": "0.6.85"
   },
   "keywords": [
     "velox",