create-velox-app 0.6.29 → 0.6.51

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

@@ -44,15 +44,69 @@ __PROJECT_NAME__/
 
 ### Server Actions
 - Defined in `app/actions/` with `'use server'` directive
-- Type-safe with Zod validation via `createAction()`
+- Type-safe with Zod validation
 - Can be called directly from client components
 
+### Validated Actions (Recommended)
+Use `validated()` for secure server actions with built-in protection:
+```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 } } });
+  }
+);
+
+// Protected mutation (requires auth by default)
+export const updateUser = validatedMutation(
+  z.object({ id: z.string(), name: z.string() }),
+  async (input, ctx) => {
+    // ctx.user is typed and available
+    return db.user.update({ where: { id: input.id }, data: input });
+  }
+);
+
+// Custom security options
+export const createUser = validated(
+  CreateUserSchema,
+  async (input) => { /* ... */ },
+  {
+    rateLimit: { maxRequests: 10, windowMs: 60_000 },
+    maxInputSize: 10 * 1024,
+  }
+);
+
+// With role-based authorization
+export const deleteUser = 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** - Custom callbacks via `authorize`
+
 ### Procedure Bridge Pattern
 Server actions can bridge to API procedures for code reuse:
 ```typescript
 // app/actions/posts.ts
 'use server';
-import { action } from '@veloxts/web';
+import { action } from '@veloxts/web/server';
 import { postProcedures } from '@/api/procedures/posts';
 
 export const createPost = action.fromProcedure(

package/src/templates/source/rsc/app/actions/posts.ts

@@ -35,7 +35,7 @@
  * ```
  */
 
-import { action } from '@veloxts/web';
+import { action } from '@veloxts/web/server';
 
 import { postProcedures } from '@/api/procedures/posts';
 

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

@@ -3,9 +3,17 @@
 /**
  * User Server Actions
  *
- * Type-safe server actions for user operations using the VeloxTS action() helper.
+ * Type-safe server actions with built-in security using VeloxTS validated() helper.
  * These can be called directly from client components with full type inference.
  *
+ * The validated() helper provides:
+ * - Input validation via Zod schemas
+ * - Input size limits (DoS protection)
+ * - Input sanitization (prototype pollution prevention)
+ * - Rate limiting (optional)
+ * - Authentication checks (optional)
+ * - Authorization via custom callbacks (optional)
+ *
  * @example
  * ```tsx
  * // In a client component
@@ -19,7 +27,7 @@
  * ```
  */
 
-import { action } from '@veloxts/web';
+import { validated, validatedMutation, validatedQuery } from '@veloxts/web/server';
 import { z } from 'zod';
 
 import { db } from '@/api/database';
@@ -36,6 +44,15 @@ const CreateUserSchema = z.object({
   email: z.string().email('Invalid email address'),
 });
 
+/**
+ * Schema for updating a user
+ */
+const UpdateUserSchema = z.object({
+  id: z.string().min(1, 'User ID is required'),
+  name: z.string().min(1).max(100).optional(),
+  email: z.string().email().optional(),
+});
+
 /**
  * Schema for deleting a user
  */
@@ -43,24 +60,90 @@ const DeleteUserSchema = 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.
+ * Includes input sanitization and validation.
+ */
+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' },
+  });
+
+  return users;
+});
+
 // ============================================================================
-// Actions
+// Mutations (with security options)
 // ============================================================================
 
 /**
  * Creates a new user.
  *
- * Input is automatically validated against CreateUserSchema.
- * Returns a discriminated union for type-safe error handling.
+ * Uses validated() with explicit options:
+ * - Rate limiting: max 10 requests per minute
+ * - Input size limit: 10KB (prevent large payload DoS)
+ * - Input sanitization: enabled by default
+ */
+export const createUser = validated(
+  CreateUserSchema,
+  async (input) => {
+    const user = await db.user.create({
+      data: {
+        name: input.name.trim(),
+        email: input.email.toLowerCase().trim(),
+      },
+    });
+
+    return user;
+  },
+  {
+    // Rate limit: 10 requests per minute per IP
+    rateLimit: {
+      maxRequests: 10,
+      windowMs: 60_000,
+    },
+    // Limit input size to 10KB
+    maxInputSize: 10 * 1024,
+  }
+);
+
+/**
+ * Updates a user.
+ *
+ * Uses validatedMutation() which requires authentication by default.
+ * When requireAuth is true, ctx.user is available and typed.
+ *
+ * Note: In a real app, add authorization to verify the user owns this record.
  */
-export const createUser = action(CreateUserSchema, async (input) => {
-  // Input is fully typed as { name: string; email: string }
-  // Validation has already been performed by the action() helper
+export const updateUser = validatedMutation(UpdateUserSchema, async (input, ctx) => {
+  // ctx.user is available because validatedMutation requires auth
+  console.log('User updating record:', ctx.user.id);
 
-  const user = await db.user.create({
+  const user = await db.user.update({
+    where: { id: input.id },
     data: {
-      name: input.name.trim(),
-      email: input.email.toLowerCase().trim(),
+      ...(input.name && { name: input.name.trim() }),
+      ...(input.email && { email: input.email.toLowerCase().trim() }),
     },
   });
 
@@ -70,14 +153,22 @@ export const createUser = action(CreateUserSchema, async (input) => {
 /**
  * Deletes a user by ID.
  *
- * Input is automatically validated to ensure a valid ID is provided.
+ * Uses validated() with role-based authorization.
+ * Only admins can delete users.
  */
-export const deleteUser = action(DeleteUserSchema, async (input) => {
-  // Input is fully typed as { id: string }
+export const deleteUser = validated(
+  DeleteUserSchema,
+  async (input) => {
+    await db.user.delete({
+      where: { id: input.id },
+    });
 
-  await db.user.delete({
-    where: { id: input.id },
-  });
-
-  return { deleted: true };
-});
+    return { deleted: true };
+  },
+  {
+    // Require authentication
+    requireAuth: true,
+    // Role-based authorization (requires 'admin' role)
+    requireRoles: ['admin'],
+  }
+);

package/src/templates/source/rsc/app/layouts/dashboard.tsx

@@ -24,12 +24,12 @@ export default function DashboardLayout({ children }: DashboardLayoutProps) {
         }
 
         .dashboard-sidebar {
-          width: 200px;
+          width: 240px;
           flex-shrink: 0;
-          background: white;
+          background: #111;
           border-radius: 8px;
-          padding: 1rem;
-          box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+          padding: 1.5rem;
+          border: 1px solid #222;
           height: fit-content;
         }
 
@@ -37,8 +37,10 @@ export default function DashboardLayout({ children }: DashboardLayoutProps) {
           font-size: 0.75rem;
           text-transform: uppercase;
           color: #888;
-          margin-bottom: 0.5rem;
-          padding: 0 0.5rem;
+          margin-bottom: 0.75rem;
+          padding: 0 0.75rem;
+          font-weight: 600;
+          letter-spacing: 0.05em;
         }
 
         .sidebar-nav {
@@ -47,39 +49,42 @@ export default function DashboardLayout({ children }: DashboardLayoutProps) {
 
         .sidebar-nav a {
           display: block;
-          padding: 0.5rem;
-          color: #1a1a2e;
+          padding: 0.75rem;
+          color: #ededed;
           text-decoration: none;
           border-radius: 4px;
           transition: background 0.2s;
         }
 
         .sidebar-nav a:hover {
-          background: #f0f0f0;
+          background: #1a1a1a;
+          color: #00d9ff;
         }
 
         .sidebar-nav a.active {
-          background: #6366f1;
-          color: white;
+          background: #00d9ff;
+          color: #000;
         }
 
         .dashboard-content {
           flex: 1;
-          background: white;
+          background: #111;
           border-radius: 8px;
           padding: 1.5rem;
-          box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+          border: 1px solid #222;
         }
 
         .dashboard-badge {
           display: inline-block;
-          background: #6366f1;
-          color: white;
+          background: #00d9ff;
+          color: #000;
           font-size: 0.625rem;
           text-transform: uppercase;
-          padding: 0.25rem 0.5rem;
+          padding: 0.5rem 0.75rem;
           border-radius: 4px;
           margin-bottom: 1rem;
+          font-weight: 600;
+          letter-spacing: 0.05em;
         }
       `}</style>
 

package/src/templates/source/rsc/app/layouts/marketing.tsx

@@ -15,6 +15,40 @@ interface MarketingLayoutProps {
 export default function MarketingLayout({ children }: MarketingLayoutProps) {
   return (
     <div className="marketing-layout">
+      <style>{`
+        .marketing-layout {
+          position: relative;
+        }
+
+        .marketing-banner {
+          background: #111;
+          border: 1px solid #222;
+          border-radius: 8px;
+          padding: 1rem 1.5rem;
+          margin-bottom: 1.5rem;
+          display: flex;
+          align-items: center;
+          gap: 1rem;
+        }
+
+        .marketing-banner .badge {
+          display: inline-block;
+          background: #00d9ff;
+          color: #000;
+          font-size: 0.625rem;
+          text-transform: uppercase;
+          padding: 0.5rem 0.75rem;
+          border-radius: 4px;
+          font-weight: 600;
+          letter-spacing: 0.05em;
+        }
+
+        .marketing-banner span:not(.badge) {
+          color: #888;
+          font-size: 0.875rem;
+        }
+      `}</style>
+
       <div className="marketing-banner">
         <span className="badge">Marketing</span>
         <span>This page uses the marketing layout</span>

package/src/templates/source/rsc/app/layouts/minimal-content.tsx

@@ -0,0 +1,21 @@
+/**
+ * Minimal Content Layout
+ *
+ * The content portion of the minimal layout, separate from the HTML document shell.
+ * This component is shared between server and client for proper hydration.
+ *
+ * Server renders: <div id="root"><MinimalContent><Page /></MinimalContent></div>
+ * Client hydrates: <MinimalContent><Page /></MinimalContent>
+ *
+ * This ensures the React tree matches on both sides, enabling proper hydration.
+ */
+
+import type { ReactNode } from 'react';
+
+interface MinimalContentProps {
+  children: ReactNode;
+}
+
+export default function MinimalContent({ children }: MinimalContentProps) {
+  return <div className="minimal-content">{children}</div>;
+}

package/src/templates/source/rsc/app/layouts/minimal.tsx

@@ -1,12 +1,23 @@
 /**
- * Minimal Layout
+ * Minimal Layout (Document Shell)
  *
  * A stripped-down layout for pages that need minimal chrome,
  * such as print-friendly pages, embedded widgets, or auth pages.
+ *
+ * This component provides the HTML document shell (server-only).
+ * The actual content wrapper is in MinimalContent (shared with client).
+ *
+ * Architecture for proper hydration:
+ * - Server renders: <MinimalLayout><Page /></MinimalLayout>
+ *   Which produces: <html>...<div id="root"><MinimalContent><Page /></></div>...</html>
+ * - Client hydrates #root with: <MinimalContent><Page /></MinimalContent>
+ *   This ensures the React tree matches exactly.
  */
 
 import type { ReactNode } from 'react';
 
+import MinimalContent from './minimal-content.tsx';
+
 interface MinimalLayoutProps {
   children: ReactNode;
   params?: Record<string, string>;
@@ -19,11 +30,81 @@ export default function MinimalLayout({ children }: MinimalLayoutProps) {
         <meta charSet="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
         <title>VeloxTS</title>
-        <link rel="stylesheet" href="/_build/styles.css" />
+        <style>{`
+          /* Global Reset & Dark Mode Base */
+          *,
+          *::before,
+          *::after {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+            font: inherit;
+          }
+
+          html {
+            font-size: 16px;
+            -webkit-font-smoothing: antialiased;
+            -moz-osx-font-smoothing: grayscale;
+          }
+
+          body {
+            background: #0a0a0a;
+            color: #ededed;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
+            line-height: 1.6;
+            min-height: 100svh;
+          }
+
+          h1, h2, h3, h4, h5, h6 {
+            text-wrap: balance;
+          }
+
+          p, li, figcaption {
+            text-wrap: pretty;
+          }
+
+          a {
+            color: #00d9ff;
+            text-decoration: none;
+            transition: opacity 0.2s;
+          }
+
+          a:hover {
+            opacity: 0.8;
+          }
+
+          code {
+            font-family: "SF Mono", "Fira Code", "Fira Mono", Menlo, Monaco, "Courier New", monospace;
+            background: #1a1a1a;
+            padding: 0.2em 0.4em;
+            border-radius: 4px;
+            font-size: 0.9em;
+          }
+
+          ::selection {
+            background: #00d9ff;
+            color: #000;
+          }
+
+          .minimal-body {
+            min-height: 100vh;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            padding: 2rem;
+          }
+
+          .minimal-content {
+            width: 100%;
+            max-width: 450px;
+          }
+        `}</style>
       </head>
-      <body className="minimal-layout">
-        {children}
-        <script src="/_build/entry.client.js" type="module" />
+      <body className="minimal-body">
+        <div id="root">
+          <MinimalContent>{children}</MinimalContent>
+        </div>
+        <script src="/_build/src/entry.client.tsx" type="module" />
       </body>
     </html>
   );