create-velox-app 0.6.31 → 0.6.52

package/src/templates/source/rsc-auth/CLAUDE.md

@@ -0,0 +1,230 @@
+# CLAUDE.md
+
+This is a VeloxTS full-stack application using React Server Components with JWT Authentication.
+
+## Project Structure
+
+```
+__PROJECT_NAME__/
+├── app/                    # Application layer (RSC)
+│   ├── pages/              # File-based routing (RSC pages)
+│   │   ├── index.tsx       # Home page (/)
+│   │   ├── users.tsx       # Users page (/users)
+│   │   ├── auth/           # Auth pages
+│   │   │   ├── login.tsx   # Login page
+│   │   │   └── register.tsx # Registration page
+│   │   └── dashboard/      # Protected pages
+│   │       └── index.tsx   # Dashboard (requires auth)
+│   ├── layouts/            # Layout components
+│   │   └── root.tsx        # Root layout
+│   └── actions/            # Server actions
+│       ├── users.ts        # User actions with validated()
+│       └── auth.ts         # Auth actions
+├── src/                    # Source layer
+│   ├── api/                # API layer (Fastify embedded in Vinxi)
+│   │   ├── handler.ts      # API handler with auth plugin
+│   │   ├── database.ts     # Prisma client
+│   │   ├── procedures/     # API procedure definitions
+│   │   │   ├── auth.ts     # Authentication procedures
+│   │   │   ├── health.ts   # Health check
+│   │   │   └── users.ts    # User CRUD
+│   │   ├── schemas/        # Zod validation schemas
+│   │   └── utils/          # Utilities
+│   │       └── auth.ts     # JWT helpers, token store
+│   ├── entry.client.tsx    # Client hydration
+│   └── entry.server.tsx    # Server rendering
+├── prisma/
+│   └── schema.prisma       # Database schema (with password field)
+├── app.config.ts           # Vinxi configuration
+└── package.json
+```
+
+## Authentication
+
+### JWT-Based Authentication with httpOnly Cookies
+- Access tokens (15 min expiry) stored in httpOnly cookies
+- Refresh tokens (7 day expiry) stored in httpOnly cookies
+- Secure password hashing (bcrypt)
+- Rate limiting on auth endpoints
+- Token revocation support
+- Tokens are NOT accessible to JavaScript (XSS protection)
+
+### Auth Architecture
+
+This template uses the **Procedure Bridge Pattern** for authentication:
+
+1. **Server Actions** (`app/actions/auth.ts`) call auth procedures directly
+2. **Tokens are stored in httpOnly cookies** by server actions (not localStorage)
+3. **API requests use cookies** via `credentials: 'include'`
+
+```typescript
+// app/actions/auth.ts - Procedure Bridge Pattern
+'use server';
+import { authAction } from '@veloxts/web/server';
+import { authProcedures } from '@/api/procedures/auth';
+import { db } from '@/api/database';
+
+// Login: executes procedure directly, stores tokens in httpOnly cookies
+export const login = authAction.fromTokenProcedure(
+  authProcedures.procedures.createSession,
+  { parseFormData: true, contextExtensions: { db }, skipGuards: true }
+);
+
+// Register: same pattern
+export const register = authAction.fromTokenProcedure(
+  authProcedures.procedures.createAccount,
+  { parseFormData: true, contextExtensions: { db }, skipGuards: true }
+);
+
+// Logout: clears auth cookies
+export const logout = authAction.fromLogoutProcedure(
+  authProcedures.procedures.deleteSession,
+  { contextExtensions: { db }, skipGuards: true }
+);
+```
+
+### Why Procedure Bridge vs HTTP Fetch?
+
+| Aspect | Procedure Bridge | HTTP Fetch |
+|--------|-----------------|------------|
+| Network | Direct in-process | HTTP round-trip |
+| Type Safety | Full inference | Lost at boundary |
+| Cookie Access | Yes (server action) | No (client-side) |
+| Guards/Middleware | Reused | Bypassed |
+| URL Hardcoding | None | Required |
+
+### Auth Endpoints (REST API)
+```
+POST /api/auth/register  - Create new account
+POST /api/auth/login     - Authenticate, get tokens
+POST /api/auth/refresh   - Refresh access token
+POST /api/auth/logout    - Revoke current token
+GET  /api/auth/me        - Get current user (protected)
+```
+
+### Client-Side Auth
+
+```typescript
+// Dashboard - uses cookies automatically
+const response = await fetch('/api/auth/me', {
+  credentials: 'include',  // Sends httpOnly cookies
+});
+
+// Logout - uses server action
+import { logout } from '@/app/actions/auth';
+await logout();  // Clears cookies server-side
+```
+
+### Password Requirements
+- Minimum 12 characters
+- At least one uppercase letter
+- At least one lowercase letter
+- At least one number
+- Not a common password
+
+## Server Actions with validated()
+
+Use the `validated()` helper for secure server actions:
+
+```typescript
+// app/actions/users.ts
+'use server';
+import { validated, validatedMutation, validatedQuery } from '@veloxts/web/server';
+import { z } from 'zod';
+
+// Public query (no auth required)
+export const searchUsers = validatedQuery(
+  z.object({ query: z.string().optional() }),
+  async (input) => {
+    return db.user.findMany({ where: { name: { contains: input.query } } });
+  }
+);
+
+// Authenticated mutation (ctx.user available)
+export const updateProfile = validatedMutation(
+  z.object({ name: z.string() }),
+  async (input, ctx) => {
+    return db.user.update({ where: { id: ctx.user.id }, data: input });
+  }
+);
+
+// Custom security options with rate limiting
+export const createUser = validated(
+  CreateUserSchema,
+  async (input) => { /* ... */ },
+  {
+    rateLimit: { maxRequests: 10, windowMs: 60_000 },
+    maxInputSize: 10 * 1024,
+  }
+);
+
+// Role-based authorization
+export const adminDeleteUser = validated(
+  DeleteUserSchema,
+  async (input) => { /* ... */ },
+  {
+    requireAuth: true,
+    requireRoles: ['admin'],
+  }
+);
+```
+
+### Security Features
+- **Input validation** - Zod schema validation
+- **Input sanitization** - Prototype pollution prevention
+- **Input size limits** - DoS protection (default 1MB)
+- **Rate limiting** - Sliding window per IP
+- **Authentication** - Optional via `requireAuth: true`
+- **Authorization** - Role-based via `requireRoles`
+
+## Commands
+
+```bash
+# Development
+__RUN_CMD__ dev         # Start dev server
+
+# Database
+__RUN_CMD__ db:generate # Generate Prisma client
+__RUN_CMD__ db:push     # Push schema to database
+__RUN_CMD__ db:migrate  # Run migrations
+__RUN_CMD__ db:studio   # Open Prisma Studio
+
+# Production
+__RUN_CMD__ build       # Build for production
+__RUN_CMD__ start       # Start production server
+```
+
+## Development
+
+1. Run `__RUN_CMD__ db:push` to set up the database
+2. Run `__RUN_CMD__ dev` to start the development server
+3. Open http://localhost:__API_PORT__ in your browser
+4. Register an account at /auth/register
+5. Access protected pages at /dashboard
+
+## Environment Variables
+
+Required for production:
+```bash
+# Generate with: openssl rand -base64 64
+JWT_SECRET="..."
+JWT_REFRESH_SECRET="..."
+```
+
+## API Endpoints
+
+### Public
+- `GET /api/health` - Health check
+- `GET /api/users` - List users
+
+### Authentication
+- `POST /api/auth/register` - Create account (rate limited)
+- `POST /api/auth/login` - Get tokens (rate limited)
+- `POST /api/auth/refresh` - Refresh token
+- `POST /api/auth/logout` - Logout (protected)
+- `GET /api/auth/me` - Current user (protected)
+
+### Protected (require Bearer token)
+- `POST /api/users` - Create user
+- `PUT /api/users/:id` - Update user
+- `DELETE /api/users/:id` - Delete user

package/src/templates/source/rsc-auth/app/actions/auth.ts

@@ -0,0 +1,112 @@
+'use server';
+
+/**
+ * Authentication Server Actions - Procedure Bridge Pattern
+ *
+ * Uses authAction helpers to execute auth procedures directly,
+ * storing tokens in httpOnly cookies for security.
+ *
+ * This is the recommended pattern for authentication in VeloxTS RSC apps:
+ * - Tokens are stored in httpOnly cookies (not accessible to JavaScript)
+ * - The procedure's validation, guards, and business logic are reused
+ * - No HTTP round-trip overhead (direct in-process execution)
+ *
+ * @example
+ * ```tsx
+ * // In a client component
+ * const result = await login({ email: 'user@example.com', password: '...' });
+ *
+ * if (result.success) {
+ *   // Tokens are stored in cookies automatically
+ *   redirect('/dashboard');
+ * } else {
+ *   setError(result.error.message);
+ * }
+ * ```
+ */
+
+import { authAction, validated } from '@veloxts/web/server';
+import { z } from 'zod';
+
+import { db } from '@/api/database';
+import { authProcedures } from '@/api/procedures/auth';
+
+// ============================================================================
+// Auth Actions (Procedure Bridge Pattern)
+// ============================================================================
+
+/**
+ * Login action - validates credentials, stores tokens in httpOnly cookies
+ *
+ * Uses the procedure bridge pattern to:
+ * 1. Execute the createSession procedure directly (no HTTP)
+ * 2. Store tokens in httpOnly cookies via onSuccess callback
+ * 3. Return a sanitized response (tokens stripped for security)
+ *
+ * Rate limited via the procedure's middleware (5 attempts per 15 minutes).
+ */
+export const login = authAction.fromTokenProcedure(authProcedures.procedures.createSession, {
+  parseFormData: true,
+  contextExtensions: { db },
+  skipGuards: true, // Login has no guards, only rate limit middleware
+});
+
+/**
+ * Register action - creates new account, stores tokens in httpOnly cookies
+ *
+ * Uses the procedure bridge pattern to:
+ * 1. Execute the createAccount procedure directly
+ * 2. Store tokens in httpOnly cookies
+ * 3. Return sanitized response
+ *
+ * Rate limited via the procedure's middleware (3 attempts per hour).
+ */
+export const register = authAction.fromTokenProcedure(authProcedures.procedures.createAccount, {
+  parseFormData: true,
+  contextExtensions: { db },
+  skipGuards: true, // Register has no guards, only rate limit middleware
+});
+
+/**
+ * Logout action - clears auth cookies
+ *
+ * For logout, we clear cookies client-side since the deleteSession procedure
+ * requires authenticated context which is complex to set up in server actions.
+ * The token will naturally expire.
+ *
+ * For production apps needing token revocation, call the API endpoint directly
+ * from the client or implement a custom logout procedure without guards.
+ */
+export const logout = authAction.fromLogoutProcedure(authProcedures.procedures.deleteSession, {
+  contextExtensions: { db },
+  skipGuards: true, // Skip auth guard - we'll clear cookies regardless
+});
+
+// ============================================================================
+// Standalone Actions (No Procedure Required)
+// ============================================================================
+
+/**
+ * Check if email is available for registration
+ *
+ * This is a simple database lookup that doesn't need procedure bridge.
+ * Rate limited to prevent email enumeration attacks.
+ */
+export const checkEmailAvailable = validated(
+  z.object({ email: z.string().email() }),
+  async (input) => {
+    const existing = await db.user.findUnique({
+      where: { email: input.email.toLowerCase().trim() },
+      select: { id: true },
+    });
+
+    // Always return the same timing to prevent enumeration
+    return { available: !existing };
+  },
+  {
+    rateLimit: {
+      maxRequests: 10,
+      windowMs: 60_000, // 10 checks per minute
+    },
+  }
+);

package/src/templates/source/rsc-auth/app/actions/users.ts

@@ -0,0 +1,289 @@
+'use server';
+
+/**
+ * User Server Actions with Authentication
+ *
+ * Type-safe server actions with built-in security using VeloxTS validated() helper.
+ * These demonstrate authenticated actions with role-based authorization.
+ *
+ * Security features included:
+ * - Input validation via Zod schemas
+ * - Input size limits (DoS protection)
+ * - Input sanitization (prototype pollution prevention)
+ * - Rate limiting (sliding window)
+ * - Authentication checks
+ * - Role-based authorization
+ *
+ * @example
+ * ```tsx
+ * // In a client component
+ * const result = await updateProfile({ name: 'John' });
+ *
+ * if (result.success) {
+ *   console.log('Updated:', result.data);
+ * } else {
+ *   if (result.error.code === 'AUTHENTICATION_REQUIRED') {
+ *     redirect('/auth/login');
+ *   }
+ *   console.log('Error:', result.error.message);
+ * }
+ * ```
+ */
+
+import { validated, validatedMutation, validatedQuery } from '@veloxts/web/server';
+import { z } from 'zod';
+
+import { db } from '@/api/database';
+
+// ============================================================================
+// Schemas
+// ============================================================================
+
+/**
+ * Schema for updating own profile (authenticated users)
+ */
+const UpdateProfileSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100, 'Name is too long').optional(),
+  email: z.string().email('Invalid email address').optional(),
+});
+
+/**
+ * Schema for admin user creation
+ */
+const AdminCreateUserSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100, 'Name is too long'),
+  email: z.string().email('Invalid email address'),
+  roles: z.array(z.string()).default(['user']),
+});
+
+/**
+ * Schema for admin user deletion
+ */
+const AdminDeleteUserSchema = z.object({
+  id: z.string().min(1, 'User ID is required'),
+});
+
+/**
+ * Schema for searching users
+ */
+const SearchUsersSchema = z.object({
+  query: z.string().max(100).optional(),
+  limit: z.number().min(1).max(100).default(10),
+});
+
+// ============================================================================
+// Public Actions (no authentication required)
+// ============================================================================
+
+/**
+ * Search users - public query action
+ *
+ * Uses validatedQuery() which allows unauthenticated access by default.
+ * Only returns public user information (no sensitive fields).
+ */
+export const searchUsers = validatedQuery(SearchUsersSchema, async (input) => {
+  const users = await db.user.findMany({
+    where: input.query
+      ? {
+          OR: [{ name: { contains: input.query } }, { email: { contains: input.query } }],
+        }
+      : undefined,
+    take: input.limit,
+    orderBy: { createdAt: 'desc' },
+    select: {
+      id: true,
+      name: true,
+      email: true,
+      createdAt: true,
+      // Exclude password, roles, etc.
+    },
+  });
+
+  return users;
+});
+
+// ============================================================================
+// Authenticated Actions (require login)
+// ============================================================================
+
+/**
+ * Get current user's profile
+ *
+ * Uses validatedMutation() which requires authentication by default.
+ * Returns the authenticated user's full profile.
+ */
+export const getProfile = validatedMutation(
+  z.object({}), // No input needed
+  async (_input, ctx) => {
+    // ctx.user is available because validatedMutation requires auth
+    const user = await db.user.findUnique({
+      where: { id: ctx.user.id },
+      select: {
+        id: true,
+        name: true,
+        email: true,
+        roles: true,
+        createdAt: true,
+        updatedAt: true,
+      },
+    });
+
+    if (!user) {
+      throw new Error('User not found');
+    }
+
+    return user;
+  }
+);
+
+/**
+ * Update current user's profile
+ *
+ * Users can only update their own profile.
+ * Includes rate limiting to prevent abuse.
+ */
+export const updateProfile = validated(
+  UpdateProfileSchema,
+  async (input, ctx) => {
+    const user = await db.user.update({
+      where: { id: ctx.user.id },
+      data: {
+        ...(input.name && { name: input.name.trim() }),
+        ...(input.email && { email: input.email.toLowerCase().trim() }),
+      },
+      select: {
+        id: true,
+        name: true,
+        email: true,
+        updatedAt: true,
+      },
+    });
+
+    return user;
+  },
+  {
+    requireAuth: true,
+    rateLimit: {
+      maxRequests: 10,
+      windowMs: 60_000, // 10 updates per minute
+    },
+  }
+);
+
+// ============================================================================
+// Admin Actions (require admin role)
+// ============================================================================
+
+/**
+ * Admin: Create a new user
+ *
+ * Only administrators can create users directly.
+ * Regular users must go through the registration flow.
+ */
+export const adminCreateUser = validated(
+  AdminCreateUserSchema,
+  async (input) => {
+    const user = await db.user.create({
+      data: {
+        name: input.name.trim(),
+        email: input.email.toLowerCase().trim(),
+        roles: JSON.stringify(input.roles),
+        // Note: No password - admin-created users need to set password via reset flow
+      },
+      select: {
+        id: true,
+        name: true,
+        email: true,
+        roles: true,
+        createdAt: true,
+      },
+    });
+
+    return user;
+  },
+  {
+    requireAuth: true,
+    requireRoles: ['admin'],
+    rateLimit: {
+      maxRequests: 20,
+      windowMs: 60_000,
+    },
+  }
+);
+
+/**
+ * Admin: Delete a user
+ *
+ * Only administrators can delete users.
+ * Cannot delete own account (safety measure).
+ */
+export const adminDeleteUser = validated(
+  AdminDeleteUserSchema,
+  async (input, ctx) => {
+    // Prevent self-deletion
+    if (input.id === ctx.user.id) {
+      throw new Error('Cannot delete your own account');
+    }
+
+    await db.user.delete({
+      where: { id: input.id },
+    });
+
+    return { deleted: true, id: input.id };
+  },
+  {
+    requireAuth: true,
+    requireRoles: ['admin'],
+    rateLimit: {
+      maxRequests: 10,
+      windowMs: 60_000,
+    },
+  }
+);
+
+/**
+ * Admin: List all users with full details
+ *
+ * Returns all user data including roles.
+ * Only accessible to administrators.
+ */
+export const adminListUsers = validated(
+  z.object({
+    page: z.number().min(1).default(1),
+    limit: z.number().min(1).max(100).default(20),
+  }),
+  async (input) => {
+    const skip = (input.page - 1) * input.limit;
+
+    const [users, total] = await Promise.all([
+      db.user.findMany({
+        skip,
+        take: input.limit,
+        orderBy: { createdAt: 'desc' },
+        select: {
+          id: true,
+          name: true,
+          email: true,
+          roles: true,
+          createdAt: true,
+          updatedAt: true,
+        },
+      }),
+      db.user.count(),
+    ]);
+
+    return {
+      users,
+      pagination: {
+        page: input.page,
+        limit: input.limit,
+        total,
+        pages: Math.ceil(total / input.limit),
+      },
+    };
+  },
+  {
+    requireAuth: true,
+    requireRoles: ['admin'],
+  }
+);