create-velox-app 0.4.14 → 0.6.23

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

@@ -0,0 +1,157 @@
+/**
+ * Auth Utilities
+ *
+ * Shared utilities for authentication that don't require database access.
+ * 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);
+
+    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'];
+  }
+}
+
+// ============================================================================
+// 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();
+
+// ============================================================================
+// JWT Configuration Helper
+// ============================================================================
+
+/**
+ * Gets required JWT secrets from environment variables.
+ * Throws a clear error in production if secrets are not configured.
+ */
+export function getJwtSecrets(): { 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 };
+}

package/src/templates/source/root/.cursorrules

@@ -0,0 +1,187 @@
+# VeloxTS Project - Cursor AI Rules
+
+This is a VeloxTS full-stack TypeScript application.
+
+## Project Type
+
+- **Framework**: VeloxTS (Laravel-inspired TypeScript framework)
+- **Backend**: Fastify + VeloxTS procedures (apps/api)
+- **Frontend**: React + Vite + TanStack Router (apps/web)
+- **Database**: Prisma with SQLite
+- **Validation**: Zod schemas
+
+## Architecture Rules
+
+### Backend (apps/api)
+
+Procedures in `src/procedures/` define API endpoints. Naming conventions determine HTTP methods:
+
+- `get*`, `find*` → GET (single resource)
+- `list*` → GET (collection)
+- `create*`, `add*` → POST
+- `update*`, `edit*` → PUT
+- `patch*` → PATCH
+- `delete*`, `remove*` → DELETE
+
+Schemas in `src/schemas/` use Zod for validation.
+
+Context available in procedures:
+- `ctx.db` - Prisma client
+- `ctx.request` - Fastify request
+- `ctx.reply` - Fastify reply
+/* @if auth */
+- `ctx.user` - Authenticated user (if logged in)
+/* @endif auth */
+
+### Frontend (apps/web)
+
+Routes in `src/routes/` use TanStack Router file-based routing.
+API calls use `@veloxts/client` hooks: `useQuery`, `useMutation`.
+Types flow from backend automatically - no codegen needed.
+
+## Code Style
+
+### TypeScript Strictness
+
+CRITICAL - Never violate these rules:
+- NEVER use `any` type
+- NEVER use `as any` assertions
+- NEVER use `@ts-ignore` or `@ts-expect-error`
+- Use `unknown` with type guards instead
+- Use proper generics and type inference
+
+### Procedure Pattern
+
+```typescript
+import { defineProcedures, procedure, z } from '@veloxts/velox';
+
+export const entityProcedures = defineProcedures('entities', {
+  getEntity: procedure()
+    .input(z.object({ id: z.string().uuid() }))
+    .output(EntitySchema)
+    .query(async ({ input, ctx }) => {
+      return ctx.db.entity.findUnique({ where: { id: input.id } });
+    }),
+
+  createEntity: procedure()
+    .input(CreateEntitySchema)
+    .output(EntitySchema)
+    .mutation(async ({ input, ctx }) => {
+      return ctx.db.entity.create({ data: input });
+    }),
+});
+```
+
+### Schema Pattern
+
+```typescript
+import { z } from '@veloxts/velox';
+
+export const EntitySchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(255),
+  createdAt: z.date(),
+});
+
+export type Entity = z.infer<typeof EntitySchema>;
+
+export const CreateEntitySchema = EntitySchema.omit({
+  id: true,
+  createdAt: true,
+});
+
+export type CreateEntity = z.infer<typeof CreateEntitySchema>;
+```
+
+/* @if auth */
+### Protected Procedures
+
+```typescript
+import { authenticated, hasRole } from '@veloxts/auth';
+
+// Require authentication
+const getProfile = procedure()
+  .guard(authenticated)
+  .query(({ ctx }) => ctx.user);
+
+// Require role
+const adminOnly = procedure()
+  .guard(hasRole('admin'))
+  .mutation(({ ctx, input }) => { /* ... */ });
+```
+/* @endif auth */
+
+## CLI Commands
+
+Common commands for development:
+
+```bash
+# Development
+__RUN_CMD__ dev                      # Start dev server with HMR
+__RUN_CMD__ velox dev --verbose      # With timing info
+
+# Code generation
+__RUN_CMD__ velox make resource Post --crud  # Full CRUD resource
+__RUN_CMD__ velox make procedure Users       # Just procedure
+__RUN_CMD__ velox make schema Post           # Just schema
+
+# Database
+__RUN_CMD__ velox migrate run        # Run migrations
+__RUN_CMD__ velox migrate status     # Check status
+__RUN_CMD__ velox db seed            # Run seeders
+__RUN_CMD__ db:push                  # Push schema (Prisma)
+__RUN_CMD__ db:studio                # Open Prisma Studio
+```
+
+## File Naming Conventions
+
+- Procedures: `src/procedures/{entity}.ts` (plural, kebab-case for multi-word)
+- Schemas: `src/schemas/{entity}.ts` (singular, kebab-case)
+- Routes: `src/routes/{path}.tsx`
+- Components: `src/components/{Name}.tsx` (PascalCase)
+
+## Import Conventions
+
+```typescript
+// VeloxTS imports (use umbrella package)
+import { defineProcedures, procedure, z } from '@veloxts/velox';
+/* @if auth */
+import { authenticated, hasRole } from '@veloxts/auth';
+/* @endif auth */
+
+// Database client from config
+import { db } from '../config/database';
+
+// Local schemas
+import { UserSchema, CreateUserSchema } from '../schemas/user';
+```
+
+## Error Handling
+
+Use structured errors with codes:
+
+```typescript
+import { VeloxError } from '@veloxts/core';
+
+// Not found
+throw VeloxError.notFound('User', userId);
+
+// Validation
+throw VeloxError.validation('Invalid email format');
+
+// Unauthorized
+throw VeloxError.unauthorized('Login required');
+
+// Forbidden
+throw VeloxError.forbidden('Cannot access this resource');
+```
+
+## JSON Output
+
+All CLI commands support `--json` for AI tooling:
+
+```bash
+velox migrate status --json
+velox make resource Post --json --dry-run
+velox procedures list --json
+```

package/src/templates/source/root/CLAUDE.auth.md

@@ -136,6 +136,85 @@ JWT_REFRESH_SECRET=<64+ chars>   # Generate: openssl rand -base64 64
 | `patchUser` | PATCH | `/users/:id` |
 | `deleteUser` | DELETE | `/users/:id` |
 
+## Guards and Policies
+
+### Using Guards
+
+Guards protect procedures from unauthorized access:
+
+```typescript
+import { authenticated, hasRole, hasPermission, allOf, anyOf } from '@veloxts/auth';
+
+// Require authentication
+const getProfile = procedure()
+  .guard(authenticated)
+  .query(({ ctx }) => ctx.user);
+
+// Require specific role
+const adminDashboard = procedure()
+  .guard(hasRole('admin'))
+  .query(({ ctx }) => { /* ... */ });
+
+// Require permission
+const deletePost = procedure()
+  .guard(hasPermission('posts.delete'))
+  .mutation(({ ctx, input }) => { /* ... */ });
+
+// Combine guards (AND logic)
+const adminWithPermission = procedure()
+  .guard(allOf([hasRole('admin'), hasPermission('users.manage')]))
+  .mutation(({ ctx, input }) => { /* ... */ });
+
+// Any of guards (OR logic)
+const moderatorOrAdmin = procedure()
+  .guard(anyOf([hasRole('admin'), hasRole('moderator')]))
+  .mutation(({ ctx, input }) => { /* ... */ });
+```
+
+### Available Guards
+
+| Guard | Description |
+|-------|-------------|
+| `authenticated` | Requires logged-in user |
+| `emailVerified` | Requires verified email |
+| `hasRole(role)` | Checks user role |
+| `hasPermission(perm)` | Checks user permission |
+| `hasAnyPermission(perms)` | Any permission matches |
+| `allOf(guards)` | All guards must pass |
+| `anyOf(guards)` | Any guard must pass |
+| `not(guard)` | Inverts guard result |
+
+### Resource Policies
+
+Define authorization rules for resources:
+
+```typescript
+import { definePolicy, registerPolicy, authorize } from '@veloxts/auth';
+
+// Define policy for Post resource
+const PostPolicy = definePolicy<User, Post>({
+  view: () => true,
+  create: (user) => user.emailVerified,
+  update: (user, post) => user.id === post.authorId,
+  delete: (user, post) => user.id === post.authorId || user.role === 'admin',
+});
+
+// Register the policy
+registerPolicy('Post', PostPolicy);
+
+// Use in procedures
+const deletePost = procedure()
+  .guard(authenticated)
+  .mutation(async ({ ctx, input }) => {
+    const post = await ctx.db.post.findUnique({ where: { id: input.id } });
+
+    // Throws 403 if unauthorized
+    await authorize(ctx.user, 'delete', 'Post', post);
+
+    return ctx.db.post.delete({ where: { id: input.id } });
+  });
+```
+
 ## Database
 
 After schema changes:
@@ -146,3 +225,188 @@ __RUN_CMD__ db:generate  # Regenerate client
 ```
 
 Access via context: `ctx.db.user.findMany()`
+
+## Code Generation
+
+### Available Generators
+
+| Generator | Alias | Description |
+|-----------|-------|-------------|
+| `procedure` | `p` | API procedure with queries/mutations |
+| `schema` | `s` | Zod validation schema |
+| `model` | `m` | Prisma model definition |
+| `migration` | `mig` | Database migration file |
+| `test` | `t` | Unit/integration test file |
+| `resource` | `r` | Complete CRUD resource (all above) |
+| `seeder` | `seed` | Database seeder |
+| `factory` | `f` | Test data factory |
+
+### Usage Examples
+
+```bash
+# Generate a complete CRUD resource
+__RUN_CMD__ velox make resource Post --crud
+
+# Generate just a procedure
+__RUN_CMD__ velox make procedure Users --crud
+
+# Generate with soft-delete support
+__RUN_CMD__ velox m r Comment --soft-delete
+
+# Preview without writing files
+__RUN_CMD__ velox make --dry-run resource Post
+
+# JSON output for scripting
+__RUN_CMD__ velox make resource Post --json
+```
+
+### Generator Options
+
+**Common Options:**
+- `--dry-run, -d` - Preview changes without writing
+- `--force, -f` - Overwrite existing files
+- `--json` - Output results as JSON
+
+**Resource/Procedure Options:**
+- `--crud, -c` - Generate full CRUD operations
+- `--paginated, -P` - Include pagination for list
+- `--soft-delete, -s` - Add soft delete support
+- `--timestamps, -t` - Include timestamps (default: true)
+
+## Migration Runner
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `velox migrate status` | Show migration status |
+| `velox migrate run` | Run pending migrations |
+| `velox migrate rollback` | Rollback last migration |
+| `velox migrate fresh` | Drop all tables and re-run |
+| `velox migrate reset` | Rollback all then re-run |
+
+### Usage
+
+```bash
+# Check status
+__RUN_CMD__ velox migrate status
+
+# Run pending migrations
+__RUN_CMD__ velox migrate run
+
+# Development mode (creates migration from schema diff)
+__RUN_CMD__ velox migrate run --dev
+
+# Rollback last migration
+__RUN_CMD__ velox migrate rollback
+
+# Fresh database
+__RUN_CMD__ velox migrate fresh
+
+# JSON output
+__RUN_CMD__ velox migrate status --json
+```
+
+## Database Seeding
+
+### Commands
+
+```bash
+# Run all seeders
+__RUN_CMD__ velox db seed
+
+# Run specific seeder
+__RUN_CMD__ velox db seed UserSeeder
+
+# Fresh seed (truncate first)
+__RUN_CMD__ velox db seed --fresh
+
+# Preview
+__RUN_CMD__ velox db seed --dry-run
+```
+
+### Seeder Example
+
+```typescript
+// apps/api/src/database/seeders/UserSeeder.ts
+import type { Seeder } from '@veloxts/cli';
+
+export const UserSeeder: Seeder = {
+  name: 'UserSeeder',
+  dependencies: [],
+
+  async run(db) {
+    await db.user.createMany({
+      data: [
+        { email: 'admin@example.com', name: 'Admin' },
+        { email: 'user@example.com', name: 'User' },
+      ],
+    });
+  },
+};
+```
+
+## Error Handling
+
+VeloxTS uses structured error codes for AI tooling:
+
+```typescript
+// Error format: VeloxError[E1001]: Message
+// E1xxx - Core errors
+// E2xxx - Generator errors
+// E3xxx - Seeding errors
+// E4xxx - Migration errors
+// E5xxx - Dev server errors
+```
+
+### Common Patterns
+
+```typescript
+import { VeloxError } from '@veloxts/core';
+
+const getUser = procedure()
+  .input(z.object({ id: z.string().uuid() }))
+  .query(async ({ ctx, input }) => {
+    const user = await ctx.db.user.findUnique({ where: { id: input.id } });
+
+    if (!user) {
+      throw VeloxError.notFound('User', input.id);
+    }
+
+    return user;
+  });
+```
+
+## Development Workflow
+
+### Hot Module Replacement (HMR)
+
+```bash
+# Default: HMR enabled
+__RUN_CMD__ velox dev
+
+# With verbose timing
+__RUN_CMD__ velox dev --verbose
+
+# Disable HMR
+__RUN_CMD__ velox dev --no-hmr
+```
+
+### CLI JSON Output
+
+All CLI commands support `--json` for scripting:
+
+```bash
+velox migrate status --json
+velox db seed --json --dry-run
+velox procedures list --json
+```
+
+### Recommended Flow
+
+1. Define Zod schemas in `apps/api/src/schemas/`
+2. Generate resource: `velox make resource Post --crud`
+3. Customize generated procedures as needed
+4. Run migrations: `velox migrate run --dev`
+5. Seed data: `velox db seed --fresh`
+6. Test endpoints with Thunder Client or curl