@veloxts/auth 0.6.68 → 0.6.69

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @veloxts/auth
 
+## 0.6.69
+
+### Patch Changes
+
+- implement user feedback improvements across packages
+
+  ## Summary
+
+  Addresses 9 user feedback items to improve DX, reduce boilerplate, and eliminate template duplications.
+
+  ### Phase 1: Validation Helpers (`@veloxts/validation`)
+
+  - Add `prismaDecimal()`, `prismaDecimalNullable()`, `prismaDecimalOptional()` for Prisma Decimal → number conversion
+  - Add `dateToIso`, `dateToIsoNullable`, `dateToIsoOptional` aliases for consistency
+
+  ### Phase 2: Template Deduplication (`@veloxts/auth`)
+
+  - Export `createEnhancedTokenStore()` with token revocation and refresh token reuse detection
+  - Export `parseUserRoles()` and `DEFAULT_ALLOWED_ROLES`
+  - Fix memory leak: track pending timeouts for proper cleanup on `destroy()`
+  - Update templates to import from `@veloxts/auth` instead of duplicating code
+  - Fix jwtManager singleton pattern in templates
+
+  ### Phase 3: Router Helpers (`@veloxts/router`)
+
+  - Add `createRouter()` returning `{ collections, router }` for DRY setup
+  - Add `toRouter()` for router-only use cases
+  - Update all router templates to use `createRouter()`
+
+  ### Phase 4: Guard Type Narrowing - Experimental (`@veloxts/auth`, `@veloxts/router`)
+
+  - Add `NarrowingGuard` interface with phantom `_narrows` type
+  - Add `authenticatedNarrow` and `hasRoleNarrow()` guards
+  - Add `guardNarrow()` method to `ProcedureBuilder` for context narrowing
+  - Enables `ctx.user` to be non-null after guard passes
+
+  ### Phase 5: Documentation (`@veloxts/router`)
+
+  - Document `.rest()` override patterns
+  - Document `createRouter()` helper usage
+  - Document `guardNarrow()` experimental API
+  - Add schema browser-safety patterns for RSC apps
+
+- Updated dependencies
+  - @veloxts/core@0.6.69
+  - @veloxts/router@0.6.69
+
 ## 0.6.68
 
 ### Patch Changes

package/dist/guards-narrowing.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Narrowing Guards (Experimental)
+ *
+ * These guards provide TypeScript type narrowing after they pass.
+ * When using `guardNarrow(authenticatedNarrow)`, the context type
+ * is narrowed to guarantee `ctx.user` is non-null.
+ *
+ * EXPERIMENTAL: This API may change. The current recommended approach
+ * is to use middleware for context type extension.
+ *
+ * @module auth/guards-narrowing
+ */
+import type { AuthContext, GuardFunction, User } from './types.js';
+/**
+ * A guard that narrows the context type after passing.
+ *
+ * The `_narrows` phantom type indicates what the guard guarantees
+ * about the context after it passes.
+ *
+ * @template TRequired - Context properties required to run the guard
+ * @template TGuaranteed - Context properties guaranteed after guard passes
+ */
+export interface NarrowingGuard<TRequired, TGuaranteed> {
+    /** Guard name for error messages */
+    name: string;
+    /** Guard check function (matches GuardFunction signature) */
+    check: GuardFunction<TRequired>;
+    /** Custom error message */
+    message?: string;
+    /** HTTP status code for guard failures */
+    statusCode?: number;
+    /**
+     * Phantom type declaring what the guard guarantees.
+     * Used by ProcedureBuilder.guardNarrow() for type narrowing.
+     * @internal
+     */
+    readonly _narrows: TGuaranteed;
+}
+/**
+ * Context type with a guaranteed authenticated user.
+ *
+ * After `authenticatedNarrow` passes, the context is narrowed to this type.
+ */
+export interface AuthenticatedContext {
+    auth: AuthContext & {
+        isAuthenticated: true;
+    };
+    user: User;
+}
+/**
+ * Context type with a guaranteed user having specific roles.
+ */
+export interface RoleNarrowedContext {
+    user: User & {
+        roles: string[];
+    };
+}
+/**
+ * Authenticated guard with type narrowing.
+ *
+ * When used with `guardNarrow()`, narrows `ctx.user` from `User | undefined`
+ * to `User`, eliminating the need for null checks in the handler.
+ *
+ * @example
+ * ```typescript
+ * import { authenticatedNarrow } from '@veloxts/auth';
+ *
+ * // With guardNarrow (experimental):
+ * procedure()
+ *   .guardNarrow(authenticatedNarrow)
+ *   .query(({ ctx }) => {
+ *     // ctx.user is typed as User (non-null)
+ *     return { email: ctx.user.email };
+ *   });
+ *
+ * // Current recommended alternative using middleware:
+ * procedure()
+ *   .guard(authenticated)
+ *   .use(async ({ ctx, next }) => {
+ *     if (!ctx.user) throw new Error('Unreachable');
+ *     return next({ ctx: { user: ctx.user } });
+ *   })
+ *   .query(({ ctx }) => {
+ *     // ctx.user is non-null via middleware
+ *   });
+ * ```
+ */
+export declare const authenticatedNarrow: NarrowingGuard<{
+    auth?: AuthContext;
+}, AuthenticatedContext>;
+/**
+ * Creates a role-checking guard with type narrowing.
+ *
+ * Narrows `ctx.user` to guarantee non-null with roles array.
+ *
+ * @param roles - Required role(s)
+ * @returns NarrowingGuard that guarantees user with roles
+ *
+ * @example
+ * ```typescript
+ * import { hasRoleNarrow } from '@veloxts/auth';
+ *
+ * procedure()
+ *   .guardNarrow(hasRoleNarrow('admin'))
+ *   .mutation(({ ctx }) => {
+ *     // ctx.user is typed as User (non-null)
+ *     // ctx.user.roles is string[]
+ *   });
+ * ```
+ */
+export declare function hasRoleNarrow(roles: string | string[]): NarrowingGuard<{
+    user?: User;
+}, RoleNarrowedContext>;
+/**
+ * Extracts the narrowed context type from a NarrowingGuard.
+ *
+ * @example
+ * ```typescript
+ * type Ctx = InferNarrowedContext<typeof authenticatedNarrow>;
+ * // Ctx = AuthenticatedContext = { auth: AuthContext & { isAuthenticated: true }; user: User }
+ * ```
+ */
+export type InferNarrowedContext<T> = T extends NarrowingGuard<unknown, infer U> ? U : never;

package/dist/guards-narrowing.js

@@ -0,0 +1,80 @@
+/**
+ * Narrowing Guards (Experimental)
+ *
+ * These guards provide TypeScript type narrowing after they pass.
+ * When using `guardNarrow(authenticatedNarrow)`, the context type
+ * is narrowed to guarantee `ctx.user` is non-null.
+ *
+ * EXPERIMENTAL: This API may change. The current recommended approach
+ * is to use middleware for context type extension.
+ *
+ * @module auth/guards-narrowing
+ */
+import { authenticated, hasRole as hasRoleBase } from './guards.js';
+// ============================================================================
+// Narrowing Guards
+// ============================================================================
+/**
+ * Authenticated guard with type narrowing.
+ *
+ * When used with `guardNarrow()`, narrows `ctx.user` from `User | undefined`
+ * to `User`, eliminating the need for null checks in the handler.
+ *
+ * @example
+ * ```typescript
+ * import { authenticatedNarrow } from '@veloxts/auth';
+ *
+ * // With guardNarrow (experimental):
+ * procedure()
+ *   .guardNarrow(authenticatedNarrow)
+ *   .query(({ ctx }) => {
+ *     // ctx.user is typed as User (non-null)
+ *     return { email: ctx.user.email };
+ *   });
+ *
+ * // Current recommended alternative using middleware:
+ * procedure()
+ *   .guard(authenticated)
+ *   .use(async ({ ctx, next }) => {
+ *     if (!ctx.user) throw new Error('Unreachable');
+ *     return next({ ctx: { user: ctx.user } });
+ *   })
+ *   .query(({ ctx }) => {
+ *     // ctx.user is non-null via middleware
+ *   });
+ * ```
+ */
+export const authenticatedNarrow = {
+    ...authenticated,
+    // Phantom type: value is never used at runtime, only carries type info.
+    // The `undefined as unknown as T` pattern is standard for phantom types.
+    _narrows: undefined,
+};
+/**
+ * Creates a role-checking guard with type narrowing.
+ *
+ * Narrows `ctx.user` to guarantee non-null with roles array.
+ *
+ * @param roles - Required role(s)
+ * @returns NarrowingGuard that guarantees user with roles
+ *
+ * @example
+ * ```typescript
+ * import { hasRoleNarrow } from '@veloxts/auth';
+ *
+ * procedure()
+ *   .guardNarrow(hasRoleNarrow('admin'))
+ *   .mutation(({ ctx }) => {
+ *     // ctx.user is typed as User (non-null)
+ *     // ctx.user.roles is string[]
+ *   });
+ * ```
+ */
+export function hasRoleNarrow(roles) {
+    const baseGuard = hasRoleBase(roles);
+    return {
+        ...baseGuard,
+        // Phantom type: carries type info for guardNarrow() context narrowing
+        _narrows: undefined,
+    };
+}

package/dist/index.d.ts

@@ -16,6 +16,10 @@ LegacySessionConfig, PolicyAction, PolicyDefinition, RateLimitConfig, TokenPair,
 export { AuthError } from './types.js';
 export type { TokenStore } from './jwt.js';
 export { createInMemoryTokenStore, generateTokenId, isValidTimespan, JwtManager, jwtManager, parseTimeToSeconds, validateTokenExpiration, } from './jwt.js';
+export type { EnhancedTokenStore, EnhancedTokenStoreOptions } from './token-store.js';
+export { createEnhancedTokenStore, DEFAULT_ALLOWED_ROLES, parseUserRoles, } from './token-store.js';
+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 { 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';

package/dist/index.js

@@ -13,6 +13,8 @@
 export { AUTH_VERSION } from './plugin.js';
 export { AuthError } from './types.js';
 export { createInMemoryTokenStore, generateTokenId, isValidTimespan, JwtManager, jwtManager, parseTimeToSeconds, validateTokenExpiration, } from './jwt.js';
+export { createEnhancedTokenStore, DEFAULT_ALLOWED_ROLES, parseUserRoles, } from './token-store.js';
+export { authenticatedNarrow, hasRoleNarrow } from './guards-narrowing.js';
 // ============================================================================
 // Password Hashing
 // ============================================================================

package/dist/token-store.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Enhanced Token Store for JWT Revocation
+ *
+ * Provides an enhanced in-memory token store with:
+ * - Token revocation with expiry
+ * - Refresh token reuse detection
+ * - Automatic cleanup of expired entries
+ *
+ * @module auth/token-store
+ */
+/**
+ * Enhanced token store interface
+ *
+ * Extends basic token revocation with refresh token reuse detection
+ * and automatic cleanup capabilities.
+ */
+export interface EnhancedTokenStore {
+    /** Revoke a token with optional expiry time */
+    revoke(jti: string, expiresInMs?: number): void;
+    /** Check if token is revoked */
+    isRevoked(jti: string): boolean;
+    /** Mark refresh token as used (for reuse detection) */
+    markRefreshTokenUsed(jti: string, userId: string): void;
+    /** Check if refresh token was already used, returns userId if reused */
+    isRefreshTokenUsed(jti: string): string | undefined;
+    /** Revoke all tokens for a user (placeholder for production implementation) */
+    revokeAllUserTokens(userId: string): void;
+    /** Clear all entries (useful for testing) */
+    clear(): void;
+    /** Stop cleanup interval and release resources */
+    destroy(): void;
+}
+/**
+ * Options for creating an enhanced token store
+ */
+export interface EnhancedTokenStoreOptions {
+    /** Interval for cleanup of expired entries (default: 5 minutes) */
+    cleanupIntervalMs?: number;
+    /** Default expiry for revoked tokens (default: 7 days) */
+    defaultExpiryMs?: number;
+}
+/**
+ * Creates an enhanced in-memory token store
+ *
+ * Provides token revocation with expiry tracking and refresh token
+ * reuse detection for security.
+ *
+ * **WARNING: NOT suitable for production!**
+ * Use Redis or database-backed store for:
+ * - Persistence across server restarts
+ * - Horizontal scaling (multiple server instances)
+ * - Proper token revocation across deployments
+ *
+ * @example
+ * ```typescript
+ * import { createEnhancedTokenStore } from '@veloxts/auth';
+ *
+ * // Create store with defaults
+ * const tokenStore = createEnhancedTokenStore();
+ *
+ * // Revoke token on logout
+ * tokenStore.revoke(accessTokenJti);
+ *
+ * // Detect refresh token reuse (security measure)
+ * const previousUser = tokenStore.isRefreshTokenUsed(refreshJti);
+ * if (previousUser) {
+ *   // Potential token theft - revoke all user tokens
+ *   tokenStore.revokeAllUserTokens(previousUser);
+ *   throw new SecurityError('Token reuse detected');
+ * }
+ * tokenStore.markRefreshTokenUsed(refreshJti, userId);
+ *
+ * // Clean up on shutdown
+ * process.on('SIGTERM', () => tokenStore.destroy());
+ * ```
+ */
+export declare function createEnhancedTokenStore(options?: EnhancedTokenStoreOptions): EnhancedTokenStore;
+/**
+ * Default allowed roles for role parsing
+ */
+export declare const DEFAULT_ALLOWED_ROLES: readonly ["user", "admin", "moderator", "editor"];
+/**
+ * Parses JSON-encoded roles string to array
+ *
+ * Safely parses a JSON array of role strings, filtering to only allowed roles.
+ * Returns default ['user'] role if parsing fails or no valid roles found.
+ *
+ * @param rolesJson - JSON string of roles (e.g., '["admin", "user"]')
+ * @param allowedRoles - Optional list of valid roles (defaults to DEFAULT_ALLOWED_ROLES)
+ * @returns Array of valid roles, defaults to ['user'] if parsing fails
+ *
+ * @example
+ * ```typescript
+ * import { parseUserRoles } from '@veloxts/auth';
+ *
+ * const roles = parseUserRoles(user.roles);
+ * // Input: '["admin", "user"]' -> Output: ['admin', 'user']
+ * // Input: null -> Output: ['user']
+ * // Input: 'invalid' -> Output: ['user']
+ *
+ * // With custom allowed roles
+ * const roles = parseUserRoles(user.roles, ['admin', 'superadmin']);
+ * ```
+ */
+export declare function parseUserRoles(rolesJson: string | null, allowedRoles?: readonly string[]): string[];

package/dist/token-store.js

@@ -0,0 +1,159 @@
+/**
+ * Enhanced Token Store for JWT Revocation
+ *
+ * Provides an enhanced in-memory token store with:
+ * - Token revocation with expiry
+ * - Refresh token reuse detection
+ * - Automatic cleanup of expired entries
+ *
+ * @module auth/token-store
+ */
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Creates an enhanced in-memory token store
+ *
+ * Provides token revocation with expiry tracking and refresh token
+ * reuse detection for security.
+ *
+ * **WARNING: NOT suitable for production!**
+ * Use Redis or database-backed store for:
+ * - Persistence across server restarts
+ * - Horizontal scaling (multiple server instances)
+ * - Proper token revocation across deployments
+ *
+ * @example
+ * ```typescript
+ * import { createEnhancedTokenStore } from '@veloxts/auth';
+ *
+ * // Create store with defaults
+ * const tokenStore = createEnhancedTokenStore();
+ *
+ * // Revoke token on logout
+ * tokenStore.revoke(accessTokenJti);
+ *
+ * // Detect refresh token reuse (security measure)
+ * const previousUser = tokenStore.isRefreshTokenUsed(refreshJti);
+ * if (previousUser) {
+ *   // Potential token theft - revoke all user tokens
+ *   tokenStore.revokeAllUserTokens(previousUser);
+ *   throw new SecurityError('Token reuse detected');
+ * }
+ * tokenStore.markRefreshTokenUsed(refreshJti, userId);
+ *
+ * // Clean up on shutdown
+ * process.on('SIGTERM', () => tokenStore.destroy());
+ * ```
+ */
+export function createEnhancedTokenStore(options) {
+    const { cleanupIntervalMs = 5 * 60 * 1000, defaultExpiryMs = 7 * 24 * 60 * 60 * 1000 } = options ?? {};
+    const revokedTokens = new Map();
+    const usedRefreshTokens = new Map();
+    // Track pending timeouts to prevent memory leaks on destroy()
+    const pendingTimeouts = new Set();
+    const cleanup = () => {
+        const now = Date.now();
+        for (const [jti, expiry] of revokedTokens.entries()) {
+            if (now > expiry) {
+                revokedTokens.delete(jti);
+            }
+        }
+    };
+    const cleanupInterval = setInterval(cleanup, cleanupIntervalMs);
+    return {
+        revoke(jti, expiresInMs = defaultExpiryMs) {
+            revokedTokens.set(jti, Date.now() + expiresInMs);
+        },
+        isRevoked(jti) {
+            const expiry = revokedTokens.get(jti);
+            if (!expiry)
+                return false;
+            if (Date.now() > expiry) {
+                revokedTokens.delete(jti);
+                return false;
+            }
+            return true;
+        },
+        markRefreshTokenUsed(jti, userId) {
+            usedRefreshTokens.set(jti, userId);
+            // Auto-expire after default expiry, track timeout for cleanup
+            const timeout = setTimeout(() => {
+                usedRefreshTokens.delete(jti);
+                pendingTimeouts.delete(timeout);
+            }, defaultExpiryMs);
+            pendingTimeouts.add(timeout);
+        },
+        isRefreshTokenUsed(jti) {
+            return usedRefreshTokens.get(jti);
+        },
+        revokeAllUserTokens(userId) {
+            // Placeholder - in production, implement proper user->token mapping
+            console.warn(`[Security] Token reuse detected for user ${userId}. ` +
+                'All tokens should be revoked. Implement proper user->token mapping for production.');
+        },
+        clear() {
+            // Clear pending timeouts since we're clearing the tokens they reference
+            for (const timeout of pendingTimeouts) {
+                clearTimeout(timeout);
+            }
+            pendingTimeouts.clear();
+            revokedTokens.clear();
+            usedRefreshTokens.clear();
+        },
+        destroy() {
+            clearInterval(cleanupInterval);
+            // Clear all pending timeouts to prevent memory leaks
+            for (const timeout of pendingTimeouts) {
+                clearTimeout(timeout);
+            }
+            pendingTimeouts.clear();
+            revokedTokens.clear();
+            usedRefreshTokens.clear();
+        },
+    };
+}
+/**
+ * Default allowed roles for role parsing
+ */
+export const DEFAULT_ALLOWED_ROLES = ['user', 'admin', 'moderator', 'editor'];
+/**
+ * Parses JSON-encoded roles string to array
+ *
+ * Safely parses a JSON array of role strings, filtering to only allowed roles.
+ * Returns default ['user'] role if parsing fails or no valid roles found.
+ *
+ * @param rolesJson - JSON string of roles (e.g., '["admin", "user"]')
+ * @param allowedRoles - Optional list of valid roles (defaults to DEFAULT_ALLOWED_ROLES)
+ * @returns Array of valid roles, defaults to ['user'] if parsing fails
+ *
+ * @example
+ * ```typescript
+ * import { parseUserRoles } from '@veloxts/auth';
+ *
+ * const roles = parseUserRoles(user.roles);
+ * // Input: '["admin", "user"]' -> Output: ['admin', 'user']
+ * // Input: null -> Output: ['user']
+ * // Input: 'invalid' -> Output: ['user']
+ *
+ * // With custom allowed roles
+ * const roles = parseUserRoles(user.roles, ['admin', 'superadmin']);
+ * ```
+ */
+export function parseUserRoles(rolesJson, allowedRoles = DEFAULT_ALLOWED_ROLES) {
+    if (!rolesJson)
+        return ['user'];
+    try {
+        const parsed = JSON.parse(rolesJson);
+        if (!Array.isArray(parsed)) {
+            return ['user'];
+        }
+        const validRoles = parsed
+            .filter((role) => typeof role === 'string')
+            .filter((role) => allowedRoles.includes(role));
+        return validRoles.length > 0 ? validRoles : ['user'];
+    }
+    catch {
+        return ['user'];
+    }
+}

package/package.json

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