create-velox-app 0.6.68 → 0.6.70

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # create-velox-app
 
+## 0.6.70
+
+### Patch Changes
+
+- ### feat(auth): Unified Adapter-Only Architecture
+
+  **New Features:**
+
+  - Add `JwtAdapter` implementing the `AuthAdapter` interface for unified JWT authentication
+  - Add `jwtAuth()` convenience function for direct adapter usage with optional built-in routes (`/api/auth/refresh`, `/api/auth/logout`)
+  - Add `AuthContext` discriminated union (`NativeAuthContext | AdapterAuthContext`) for type-safe auth mode handling
+  - Add double-registration protection to prevent conflicting auth system setups
+  - Add shared decoration utilities (`decorateAuth`, `setRequestAuth`, `checkDoubleRegistration`)
+
+  **Architecture Changes:**
+
+  - `authPlugin` now uses `JwtAdapter` internally - all authentication flows through the adapter pattern
+  - Single code path for authentication (no more dual native/adapter modes)
+  - `authContext.authMode` is now always `'adapter'` with `providerId='jwt'` when using `authPlugin`
+
+  **Breaking Changes:**
+
+  - Remove deprecated `LegacySessionConfig` interface (use `sessionMiddleware` instead)
+  - Remove deprecated `session` field from `AuthConfig`
+  - `User` interface no longer has index signature (extend via declaration merging)
+
+  **Type Safety Improvements:**
+
+  - `AuthContext` discriminated union enables exhaustive type narrowing based on `authMode`
+  - Export `NativeAuthContext` and `AdapterAuthContext` types for explicit typing
+
+  **Migration:**
+
+  - Existing `authPlugin` usage remains backward-compatible
+  - If checking `authContext.token`, use `authContext.session` instead (token stored in session for adapter mode)
+
+## 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
+
 ## 0.6.68
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-velox-app",
-  "version": "0.6.68",
+  "version": "0.6.70",
   "description": "Project scaffolder for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",

package/src/templates/source/api/config/auth.ts

@@ -9,159 +9,9 @@
 
 import type { AuthPluginOptions } from '@veloxts/velox';
 
+import { getJwtSecrets, parseUserRoles, tokenStore } from '../utils/auth.js';
 import { db } from './database.js';
 
-// ============================================================================
-// Environment Variable Validation
-// ============================================================================
-
-/**
- * Gets required JWT secrets from environment variables.
- * Throws a clear error in production if secrets are not configured.
- */
-function getRequiredSecrets(): { jwtSecret: string; refreshSecret: string } {
-  const jwtSecret = process.env.JWT_SECRET;
-  const refreshSecret = process.env.JWT_REFRESH_SECRET;
-
-  const isDevelopment = process.env.NODE_ENV !== 'production';
-
-  if (!jwtSecret || !refreshSecret) {
-    if (isDevelopment) {
-      console.warn(
-        '\n' +
-          '='.repeat(70) +
-          '\n' +
-          '  WARNING: JWT secrets not configured!\n' +
-          '  Using temporary development secrets. DO NOT USE IN PRODUCTION!\n' +
-          '\n' +
-          '  To configure secrets, add to .env:\n' +
-          '    JWT_SECRET=<generate with: openssl rand -base64 64>\n' +
-          '    JWT_REFRESH_SECRET=<generate with: openssl rand -base64 64>\n' +
-          '='.repeat(70) +
-          '\n'
-      );
-      return {
-        jwtSecret:
-          jwtSecret || `dev-only-jwt-secret-${Math.random().toString(36).substring(2).repeat(4)}`,
-        refreshSecret:
-          refreshSecret ||
-          `dev-only-refresh-secret-${Math.random().toString(36).substring(2).repeat(4)}`,
-      };
-    }
-
-    throw new Error(
-      '\n' +
-        'CRITICAL: JWT secrets are required but not configured.\n' +
-        '\n' +
-        'Required environment variables:\n' +
-        '  - JWT_SECRET: Secret for signing access tokens (64+ characters)\n' +
-        '  - JWT_REFRESH_SECRET: Secret for signing refresh tokens (64+ characters)\n' +
-        '\n' +
-        'Generate secure secrets with:\n' +
-        '  openssl rand -base64 64\n' +
-        '\n' +
-        'Add them to your environment or .env file before starting the server.\n'
-    );
-  }
-
-  return { jwtSecret, refreshSecret };
-}
-
-// ============================================================================
-// Token Revocation Store
-// ============================================================================
-
-/**
- * In-memory token revocation store.
- *
- * PRODUCTION NOTE: Replace with Redis or database-backed store for:
- * - Persistence across server restarts
- * - Horizontal scaling (multiple server instances)
- */
-class InMemoryTokenStore {
-  private revokedTokens: Map<string, number> = new Map();
-  private usedRefreshTokens: Map<string, string> = new Map();
-  private cleanupInterval: NodeJS.Timeout | null = null;
-
-  constructor() {
-    this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
-  }
-
-  revoke(jti: string, expiresInMs: number = 7 * 24 * 60 * 60 * 1000): void {
-    this.revokedTokens.set(jti, Date.now() + expiresInMs);
-  }
-
-  isRevoked(jti: string): boolean {
-    const expiry = this.revokedTokens.get(jti);
-    if (!expiry) return false;
-    if (Date.now() > expiry) {
-      this.revokedTokens.delete(jti);
-      return false;
-    }
-    return true;
-  }
-
-  markRefreshTokenUsed(jti: string, userId: string): void {
-    this.usedRefreshTokens.set(jti, userId);
-    setTimeout(() => this.usedRefreshTokens.delete(jti), 7 * 24 * 60 * 60 * 1000);
-  }
-
-  isRefreshTokenUsed(jti: string): string | undefined {
-    return this.usedRefreshTokens.get(jti);
-  }
-
-  revokeAllUserTokens(userId: string): void {
-    console.warn(
-      `[Security] Token reuse detected for user ${userId}. ` +
-        'All tokens should be revoked. Implement proper user->token mapping for production.'
-    );
-  }
-
-  private cleanup(): void {
-    const now = Date.now();
-    for (const [jti, expiry] of this.revokedTokens.entries()) {
-      if (now > expiry) {
-        this.revokedTokens.delete(jti);
-      }
-    }
-  }
-
-  destroy(): void {
-    if (this.cleanupInterval) {
-      clearInterval(this.cleanupInterval);
-      this.cleanupInterval = null;
-    }
-  }
-}
-
-export const tokenStore = new InMemoryTokenStore();
-
-// ============================================================================
-// Role Parsing
-// ============================================================================
-
-const ALLOWED_ROLES = ['user', 'admin', 'moderator', 'editor'] as const;
-
-export function parseUserRoles(rolesJson: string | null): string[] {
-  if (!rolesJson) return ['user'];
-
-  try {
-    const parsed: unknown = JSON.parse(rolesJson);
-
-    if (!Array.isArray(parsed)) {
-      return ['user'];
-    }
-
-    const validRoles = parsed
-      .filter((role): role is string => typeof role === 'string')
-      .filter((role) => ALLOWED_ROLES.includes(role as (typeof ALLOWED_ROLES)[number]));
-
-    return validRoles.length > 0 ? validRoles : ['user'];
-  } catch {
-    return ['user'];
-  }
-}
-
 // ============================================================================
 // User Loader
 // ============================================================================
@@ -186,7 +36,7 @@ async function userLoader(userId: string) {
 // ============================================================================
 
 export function createAuthConfig(): AuthPluginOptions {
-  const { jwtSecret, refreshSecret } = getRequiredSecrets();
+  const { jwtSecret, refreshSecret } = getJwtSecrets();
 
   return {
     jwt: {
@@ -207,3 +57,6 @@ export function createAuthConfig(): AuthPluginOptions {
 }
 
 export const authConfig = createAuthConfig();
+
+// Re-export for convenience
+export { parseUserRoles, tokenStore } from '../utils/auth.js';

package/src/templates/source/api/procedures/auth.ts

@@ -16,7 +16,6 @@ import {
   authenticated,
   createAuthRateLimiter,
   hashPassword,
-  jwtManager,
   procedure,
   procedures,
   verifyPassword,
@@ -30,7 +29,7 @@ import {
   TokenResponse,
   UserResponse,
 } from '../schemas/auth.js';
-import { getJwtSecrets, parseUserRoles, tokenStore } from '../utils/auth.js';
+import { jwt, parseUserRoles, tokenStore } from '../utils/auth.js';
 
 // ============================================================================
 // Rate Limiter
@@ -82,21 +81,6 @@ const EnhancedRegisterInput = RegisterInput.extend({
     ),
 });
 
-// ============================================================================
-// JWT Manager
-// ============================================================================
-
-const { jwtSecret, refreshSecret } = getJwtSecrets();
-
-const jwt = jwtManager({
-  secret: jwtSecret,
-  refreshSecret: refreshSecret,
-  accessTokenExpiry: '15m',
-  refreshTokenExpiry: '7d',
-  issuer: 'velox-app',
-  audience: 'velox-app-client',
-});
-
 // Dummy hash for timing attack prevention
 const DUMMY_HASH = '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/X4.uy7dPSSXB5G6Uy';
 

package/src/templates/source/api/router.auth.ts

@@ -9,21 +9,18 @@
  * The server entry point (index.ts) handles environment setup.
  */
 
-import { extractRoutes } from '@veloxts/velox';
+import { createRouter, extractRoutes } from '@veloxts/velox';
 
 import { authProcedures } from './procedures/auth.js';
 import { healthProcedures } from './procedures/health.js';
 import { userProcedures } from './procedures/users.js';
 
-// Procedure collections for routing
-export const collections = [healthProcedures, authProcedures, userProcedures];
-
-// Router definition for frontend type safety
-export const router = {
-  auth: authProcedures,
-  health: healthProcedures,
-  users: userProcedures,
-};
+// Create router and collections from procedure definitions
+export const { collections, router } = createRouter(
+  healthProcedures,
+  authProcedures,
+  userProcedures
+);
 
 export type AppRouter = typeof router;
 

package/src/templates/source/api/router.default.ts

@@ -9,19 +9,13 @@
  * The server entry point (index.ts) handles environment setup.
  */
 
-import { extractRoutes } from '@veloxts/velox';
+import { createRouter, extractRoutes } from '@veloxts/velox';
 
 import { healthProcedures } from './procedures/health.js';
 import { userProcedures } from './procedures/users.js';
 
-// Procedure collections for routing
-export const collections = [healthProcedures, userProcedures];
-
-// Router definition for frontend type safety
-export const router = {
-  health: healthProcedures,
-  users: userProcedures,
-};
+// Create router and collections from procedure definitions
+export const { collections, router } = createRouter(healthProcedures, userProcedures);
 
 export type AppRouter = typeof router;
 

package/src/templates/source/api/router.trpc.ts

@@ -9,11 +9,13 @@
  * The server entry point (index.ts) handles environment setup.
  */
 
+import { createRouter } from '@veloxts/velox';
+
 import { healthProcedures } from './procedures/health.js';
 import { userProcedures } from './procedures/users.js';
 
-// Procedure collections for routing
-export const collections = [healthProcedures, userProcedures];
+// Create router and collections from procedure definitions
+export const { collections, router } = createRouter(healthProcedures, userProcedures);
 
 /**
  * AppRouter type for frontend type safety
@@ -29,9 +31,4 @@ export const collections = [healthProcedures, userProcedures];
  * export const api = createVeloxHooks<AppRouter>();
  * ```
  */
-export const router = {
-  health: healthProcedures,
-  users: userProcedures,
-};
-
 export type AppRouter = typeof router;

package/src/templates/source/api/utils/auth.ts

@@ -5,34 +5,13 @@
  * These are safe to import from procedures without pulling in server-only code.
  */
 
-// ============================================================================
-// Role Parsing
-// ============================================================================
-
-const ALLOWED_ROLES = ['user', 'admin', 'moderator', 'editor'] as const;
-
-export function parseUserRoles(rolesJson: string | null): string[] {
-  if (!rolesJson) return ['user'];
-
-  try {
-    const parsed: unknown = JSON.parse(rolesJson);
+import { createEnhancedTokenStore, jwtManager } from '@veloxts/auth';
 
-    if (!Array.isArray(parsed)) {
-      return ['user'];
-    }
-
-    const validRoles = parsed
-      .filter((role): role is string => typeof role === 'string')
-      .filter((role) => ALLOWED_ROLES.includes(role as (typeof ALLOWED_ROLES)[number]));
-
-    return validRoles.length > 0 ? validRoles : ['user'];
-  } catch {
-    return ['user'];
-  }
-}
+// Re-export from @veloxts/auth for convenience
+export { createEnhancedTokenStore, parseUserRoles } from '@veloxts/auth';
 
 // ============================================================================
-// Token Revocation Store
+// Token Store
 // ============================================================================
 
 /**
@@ -42,63 +21,7 @@ export function parseUserRoles(rolesJson: string | null): string[] {
  * - Persistence across server restarts
  * - Horizontal scaling (multiple server instances)
  */
-class InMemoryTokenStore {
-  private revokedTokens: Map<string, number> = new Map();
-  private usedRefreshTokens: Map<string, string> = new Map();
-  private cleanupInterval: NodeJS.Timeout | null = null;
-
-  constructor() {
-    this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
-  }
-
-  revoke(jti: string, expiresInMs: number = 7 * 24 * 60 * 60 * 1000): void {
-    this.revokedTokens.set(jti, Date.now() + expiresInMs);
-  }
-
-  isRevoked(jti: string): boolean {
-    const expiry = this.revokedTokens.get(jti);
-    if (!expiry) return false;
-    if (Date.now() > expiry) {
-      this.revokedTokens.delete(jti);
-      return false;
-    }
-    return true;
-  }
-
-  markRefreshTokenUsed(jti: string, userId: string): void {
-    this.usedRefreshTokens.set(jti, userId);
-    setTimeout(() => this.usedRefreshTokens.delete(jti), 7 * 24 * 60 * 60 * 1000);
-  }
-
-  isRefreshTokenUsed(jti: string): string | undefined {
-    return this.usedRefreshTokens.get(jti);
-  }
-
-  revokeAllUserTokens(userId: string): void {
-    console.warn(
-      `[Security] Token reuse detected for user ${userId}. ` +
-        'All tokens should be revoked. Implement proper user->token mapping for production.'
-    );
-  }
-
-  private cleanup(): void {
-    const now = Date.now();
-    for (const [jti, expiry] of this.revokedTokens.entries()) {
-      if (now > expiry) {
-        this.revokedTokens.delete(jti);
-      }
-    }
-  }
-
-  destroy(): void {
-    if (this.cleanupInterval) {
-      clearInterval(this.cleanupInterval);
-      this.cleanupInterval = null;
-    }
-  }
-}
-
-export const tokenStore = new InMemoryTokenStore();
+export const tokenStore = createEnhancedTokenStore();
 
 // ============================================================================
 // JWT Configuration Helper
@@ -155,3 +78,24 @@ export function getJwtSecrets(): { jwtSecret: string; refreshSecret: string } {
 
   return { jwtSecret, refreshSecret };
 }
+
+// ============================================================================
+// JWT Manager Singleton
+// ============================================================================
+
+const { jwtSecret, refreshSecret } = getJwtSecrets();
+
+/**
+ * Shared JWT manager instance for the application.
+ *
+ * Use this singleton instead of creating new jwtManager instances.
+ * Configured with environment variables via getJwtSecrets().
+ */
+export const jwt = jwtManager({
+  secret: jwtSecret,
+  refreshSecret: refreshSecret,
+  accessTokenExpiry: '15m',
+  refreshTokenExpiry: '7d',
+  issuer: 'velox-app',
+  audience: 'velox-app-client',
+});

package/src/templates/source/rsc-auth/src/api/procedures/auth.ts

@@ -16,7 +16,6 @@ import {
   authenticated,
   createAuthRateLimiter,
   hashPassword,
-  jwtManager,
   verifyPassword,
 } from '@veloxts/auth';
 import { procedure, procedures } from '@veloxts/router';
@@ -29,7 +28,7 @@ import {
   TokenResponse,
   UserResponse,
 } from '../schemas/auth.js';
-import { getJwtSecrets, parseUserRoles, tokenStore } from '../utils/auth.js';
+import { jwt, parseUserRoles, tokenStore } from '../utils/auth.js';
 
 // ============================================================================
 // Rate Limiter
@@ -81,21 +80,6 @@ const EnhancedRegisterInput = RegisterInput.extend({
     ),
 });
 
-// ============================================================================
-// JWT Manager
-// ============================================================================
-
-const { jwtSecret, refreshSecret } = getJwtSecrets();
-
-const jwt = jwtManager({
-  secret: jwtSecret,
-  refreshSecret: refreshSecret,
-  accessTokenExpiry: '15m',
-  refreshTokenExpiry: '7d',
-  issuer: 'velox-app',
-  audience: 'velox-app-client',
-});
-
 // Dummy hash for timing attack prevention
 const DUMMY_HASH = '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/X4.uy7dPSSXB5G6Uy';
 

package/src/templates/source/rsc-auth/src/api/utils/auth.ts

@@ -5,34 +5,13 @@
  * These are safe to import from procedures without pulling in server-only code.
  */
 
-// ============================================================================
-// Role Parsing
-// ============================================================================
-
-const ALLOWED_ROLES = ['user', 'admin', 'moderator', 'editor'] as const;
-
-export function parseUserRoles(rolesJson: string | null): string[] {
-  if (!rolesJson) return ['user'];
-
-  try {
-    const parsed: unknown = JSON.parse(rolesJson);
+import { createEnhancedTokenStore, jwtManager } from '@veloxts/auth';
 
-    if (!Array.isArray(parsed)) {
-      return ['user'];
-    }
-
-    const validRoles = parsed
-      .filter((role): role is string => typeof role === 'string')
-      .filter((role) => ALLOWED_ROLES.includes(role as (typeof ALLOWED_ROLES)[number]));
-
-    return validRoles.length > 0 ? validRoles : ['user'];
-  } catch {
-    return ['user'];
-  }
-}
+// Re-export from @veloxts/auth for convenience
+export { createEnhancedTokenStore, parseUserRoles } from '@veloxts/auth';
 
 // ============================================================================
-// Token Revocation Store
+// Token Store
 // ============================================================================
 
 /**
@@ -42,63 +21,7 @@ export function parseUserRoles(rolesJson: string | null): string[] {
  * - Persistence across server restarts
  * - Horizontal scaling (multiple server instances)
  */
-class InMemoryTokenStore {
-  private revokedTokens: Map<string, number> = new Map();
-  private usedRefreshTokens: Map<string, string> = new Map();
-  private cleanupInterval: NodeJS.Timeout | null = null;
-
-  constructor() {
-    this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
-  }
-
-  revoke(jti: string, expiresInMs: number = 7 * 24 * 60 * 60 * 1000): void {
-    this.revokedTokens.set(jti, Date.now() + expiresInMs);
-  }
-
-  isRevoked(jti: string): boolean {
-    const expiry = this.revokedTokens.get(jti);
-    if (!expiry) return false;
-    if (Date.now() > expiry) {
-      this.revokedTokens.delete(jti);
-      return false;
-    }
-    return true;
-  }
-
-  markRefreshTokenUsed(jti: string, userId: string): void {
-    this.usedRefreshTokens.set(jti, userId);
-    setTimeout(() => this.usedRefreshTokens.delete(jti), 7 * 24 * 60 * 60 * 1000);
-  }
-
-  isRefreshTokenUsed(jti: string): string | undefined {
-    return this.usedRefreshTokens.get(jti);
-  }
-
-  revokeAllUserTokens(userId: string): void {
-    console.warn(
-      `[Security] Token reuse detected for user ${userId}. ` +
-        'All tokens should be revoked. Implement proper user->token mapping for production.'
-    );
-  }
-
-  private cleanup(): void {
-    const now = Date.now();
-    for (const [jti, expiry] of this.revokedTokens.entries()) {
-      if (now > expiry) {
-        this.revokedTokens.delete(jti);
-      }
-    }
-  }
-
-  destroy(): void {
-    if (this.cleanupInterval) {
-      clearInterval(this.cleanupInterval);
-      this.cleanupInterval = null;
-    }
-  }
-}
-
-export const tokenStore = new InMemoryTokenStore();
+export const tokenStore = createEnhancedTokenStore();
 
 // ============================================================================
 // JWT Configuration Helper
@@ -155,3 +78,24 @@ export function getJwtSecrets(): { jwtSecret: string; refreshSecret: string } {
 
   return { jwtSecret, refreshSecret };
 }
+
+// ============================================================================
+// JWT Manager Singleton
+// ============================================================================
+
+const { jwtSecret, refreshSecret } = getJwtSecrets();
+
+/**
+ * Shared JWT manager instance for the application.
+ *
+ * Use this singleton instead of creating new jwtManager instances.
+ * Configured with environment variables via getJwtSecrets().
+ */
+export const jwt = jwtManager({
+  secret: jwtSecret,
+  refreshSecret: refreshSecret,
+  accessTokenExpiry: '15m',
+  refreshTokenExpiry: '7d',
+  issuer: 'velox-app',
+  audience: 'velox-app-client',
+});