create-fluxstack 1.13.0 → 1.15.0

package/LLMD/patterns/anti-patterns.md

@@ -277,6 +277,100 @@ if (import.meta.env.DEV) {
 }
 ```
 
+## Live Component Security Anti-Patterns
+
+### Never Omit publicActions
+
+```typescript
+// ❌ WRONG - No publicActions = ALL remote actions blocked (secure by default)
+export class MyComponent extends LiveComponent<State> {
+  static componentName = 'MyComponent'
+  static defaultState = { count: 0 }
+
+  async increment() { this.state.count++ }  // Client CANNOT call this!
+}
+
+// ✅ CORRECT - Explicitly whitelist callable methods
+export class MyComponent extends LiveComponent<State> {
+  static componentName = 'MyComponent'
+  static publicActions = ['increment'] as const  // Only increment is callable
+  static defaultState = { count: 0 }
+
+  async increment() { this.state.count++ }
+
+  // Internal helper - not in publicActions, so not callable from client
+  private _recalculate() { /* ... */ }
+}
+```
+
+**Why**: Components without `publicActions` deny ALL remote actions. This is secure by default - if you forget, nothing is exposed rather than everything.
+
+### Never Include setValue Without Careful Consideration
+
+```typescript
+// ❌ DANGEROUS - setValue allows client to set ANY state key
+static publicActions = ['sendMessage', 'setValue'] as const
+// Client can now do: component.setValue({ key: 'isAdmin', value: true })
+
+// ✅ CORRECT - Only expose specific, safe actions
+static publicActions = ['sendMessage', 'deleteMessage'] as const
+```
+
+**Why**: `setValue` is a generic action that allows the client to modify any state property. Only include it if all state fields are safe for clients to modify.
+
+### Never Trust MIME Types Alone for Uploads
+
+```typescript
+// ❌ WRONG - Only checking MIME type header (easily spoofed)
+if (file.type === 'image/jpeg') {
+  // Accept file - but it could be an EXE with a fake MIME header!
+}
+
+// ✅ CORRECT - Framework validates magic bytes automatically
+// FileUploadManager.validateContentMagicBytes() runs on completeUpload()
+// No manual code needed - the framework handles this
+```
+
+**Why**: MIME types come from the client and can be spoofed. The framework validates actual file content (magic bytes) against the claimed type.
+
+### Never Store Sensitive Data in State
+
+```typescript
+// ❌ WRONG - Token goes to the client via STATE_UPDATE/STATE_DELTA
+export class Chat extends LiveComponent<State> {
+  static defaultState = { messages: [], token: '' }  // token synced to client!
+  static publicActions = ['connect'] as const
+
+  async connect(payload: { token: string }) {
+    this.state.token = payload.token  // 💀 Visible in browser DevTools!
+  }
+}
+
+// ✅ CORRECT - Use $private for server-only data
+export class Chat extends LiveComponent<State> {
+  static defaultState = { messages: [] as string[] }
+  static publicActions = ['connect'] as const
+
+  async connect(payload: { token: string }) {
+    this.$private.token = payload.token  // 🔒 Never leaves the server
+    this.state.messages = await fetch(this.$private.token)
+  }
+}
+```
+
+**Why**: Everything in `state` is serialized and sent to the client via WebSocket. Use `$private` for tokens, API keys, internal IDs, or any data the client should not see.
+
+### Never Ignore Double Extensions
+
+```typescript
+// ❌ WRONG - Only checking last extension
+const ext = filename.split('.').pop()  // Returns 'jpg' for 'malware.exe.jpg'
+
+// ✅ CORRECT - Framework checks all intermediate extensions automatically
+// FileUploadManager blocks files like 'malware.exe.jpg'
+// No manual code needed - handled at framework level
+```
+
 ## Summary Table
 
 | Anti-Pattern | Impact | Solution |
@@ -288,6 +382,10 @@ if (import.meta.env.DEV) {
 | Deep relative imports | Fragile paths | Use aliases |
 | NPM plugins without whitelist | Security risk | Set PLUGINS_ALLOWED |
 | Business logic in routes | Unmaintainable | Use controllers |
+| Missing `publicActions` | All actions blocked | Always define whitelist |
+| Including `setValue` carelessly | Privilege escalation | Use specific actions |
+| Sensitive data in `state` | Data leak to client | Use `$private` instead |
+| Trusting MIME types alone | File disguise attacks | Framework validates magic bytes |
 
 ## Related
 
@@ -295,3 +393,5 @@ if (import.meta.env.DEV) {
 - [Type Safety](./type-safety.md)
 - [Plugin Security](../core/plugin-system.md)
 - [Routes with Eden Treaty](../resources/routes-eden.md)
+- [Live Components](../resources/live-components.md)
+- [Live Upload](../resources/live-upload.md)

package/LLMD/reference/routing.md

@@ -1,39 +1,39 @@
-# Routing (React Router v7)
-
-FluxStack uses **React Router v7** via the `react-router` package for web routing.
-
-## Where It Lives
-
-- Router provider: `app/client/src/main.tsx`
-- Routes and pages: `app/client/src/App.tsx`
-- Pages: `app/client/src/pages/*`
-- Shared layout: `app/client/src/components/AppLayout.tsx`
-
-## Why `react-router` (not `react-router-dom`)
-
-In v7, the React Router team recommends using the core `react-router` package
-directly for web apps. The `react-router-dom` package remains as a compatibility
-re-export for older apps, but new projects should import from `react-router`.
-
-## Example: Adding a New Route
-
-1. Create a page in `app/client/src/pages/MyPage.tsx`
-2. Add a route in `app/client/src/App.tsx`:
-
-```tsx
-import { MyPage } from './pages/MyPage'
-
-<Route path="/my-page" element={<MyPage />} />
-```
-
-3. Add a nav link in `app/client/src/components/AppLayout.tsx`
-
-## Current Demo Routes
-
-- `/` Home
-- `/counter` Live Counter
-- `/form` Live Form
-- `/upload` Live Upload
-- `/chat` Live Chat
-- `/api-test` Eden Treaty API Test
-
+# Routing (React Router v7)
+
+FluxStack uses **React Router v7** via the `react-router` package for web routing.
+
+## Where It Lives
+
+- Router provider: `app/client/src/main.tsx`
+- Routes and pages: `app/client/src/App.tsx`
+- Pages: `app/client/src/pages/*`
+- Shared layout: `app/client/src/components/AppLayout.tsx`
+
+## Why `react-router` (not `react-router-dom`)
+
+In v7, the React Router team recommends using the core `react-router` package
+directly for web apps. The `react-router-dom` package remains as a compatibility
+re-export for older apps, but new projects should import from `react-router`.
+
+## Example: Adding a New Route
+
+1. Create a page in `app/client/src/pages/MyPage.tsx`
+2. Add a route in `app/client/src/App.tsx`:
+
+```tsx
+import { MyPage } from './pages/MyPage'
+
+<Route path="/my-page" element={<MyPage />} />
+```
+
+3. Add a nav link in `app/client/src/components/AppLayout.tsx`
+
+## Current Demo Routes
+
+- `/` Home
+- `/counter` Live Counter
+- `/form` Live Form
+- `/upload` Live Upload
+- `/chat` Live Chat
+- `/api-test` Eden Treaty API Test
+

package/LLMD/resources/live-auth.md

@@ -4,6 +4,7 @@
 
 ## Quick Facts
 
+- **`publicActions` is the foundation** - Only whitelisted methods can be called remotely
 - Declarative auth configuration via `static auth` and `static actionAuth`
 - Role-based access control (RBAC) with OR logic
 - Permission-based access control with AND logic
@@ -22,6 +23,7 @@ import type { LiveComponentAuth } from '@core/server/live/auth/types'
 
 export class ProtectedChat extends LiveComponent<typeof ProtectedChat.defaultState> {
   static componentName = 'ProtectedChat'
+  static publicActions = ['sendMessage'] as const  // 🔒 REQUIRED
   static defaultState = {
     messages: [] as string[]
   }
@@ -47,6 +49,7 @@ import type { LiveComponentAuth } from '@core/server/live/auth/types'
 
 export class AdminPanel extends LiveComponent<typeof AdminPanel.defaultState> {
   static componentName = 'AdminPanel'
+  static publicActions = ['deleteUser'] as const  // 🔒 REQUIRED
   static defaultState = {
     users: [] as { id: string; name: string; role: string }[]
   }
@@ -74,6 +77,7 @@ import type { LiveComponentAuth } from '@core/server/live/auth/types'
 
 export class ContentEditor extends LiveComponent<typeof ContentEditor.defaultState> {
   static componentName = 'ContentEditor'
+  static publicActions = ['editContent', 'saveContent'] as const  // 🔒 REQUIRED
   static defaultState = {
     content: ''
   }
@@ -95,6 +99,7 @@ import type { LiveComponentAuth, LiveActionAuthMap } from '@core/server/live/aut
 
 export class ModerationPanel extends LiveComponent<typeof ModerationPanel.defaultState> {
   static componentName = 'ModerationPanel'
+  static publicActions = ['getReports', 'deleteReport', 'banUser'] as const  // 🔒 REQUIRED
   static defaultState = {
     reports: [] as any[]
   }
@@ -104,7 +109,7 @@ export class ModerationPanel extends LiveComponent<typeof ModerationPanel.defaul
     required: true
   }
 
-  // Per-action auth
+  // Per-action auth (works together with publicActions)
   static actionAuth: LiveActionAuthMap = {
     deleteReport: { permissions: ['reports.delete'] },
     banUser: { roles: ['admin', 'moderator'] }
@@ -382,7 +387,7 @@ For testing, a `DevAuthProvider` with simple tokens is available:
 │  1. WebSocket connect → store authContext on ws.data        │
 │  2. AUTH message → liveAuthManager.authenticate()           │
 │  3. COMPONENT_MOUNT → check static auth config              │
-│  4. CALL_ACTION → check static actionAuth config            │
+│  4. CALL_ACTION → check blocklist → publicActions → actionAuth │
 │  5. Component has access to this.$auth                      │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -416,9 +421,21 @@ interface LiveAuthCredentials {
 }
 ```
 
+## Security Layers (Action Execution Order)
+
+When a client calls an action, the server checks in this order:
+
+1. **Blocklist** - Internal methods (destroy, setState, emit, etc.) are always blocked
+2. **Private methods** - Methods starting with `_` or `#` are blocked
+3. **publicActions** - Action must be in the whitelist (mandatory, no fallback)
+4. **actionAuth** - Per-action role/permission check (if defined)
+5. **Method exists** - Action must exist on the component instance
+6. **Object.prototype** - Blocks toString, valueOf, hasOwnProperty
+
 ## Critical Rules
 
 **ALWAYS:**
+- Define `static publicActions` listing all client-callable methods (MANDATORY)
 - Define `static auth` for protected components
 - Define `static actionAuth` for protected actions
 - Use `$auth.hasRole()` / `$auth.hasPermission()` in action logic
@@ -426,6 +443,7 @@ interface LiveAuthCredentials {
 - Handle `AUTH_DENIED` errors in client UI
 
 **NEVER:**
+- Omit `publicActions` (component will deny ALL remote actions)
 - Store sensitive data in component state
 - Trust client-side auth checks alone (always verify server-side)
 - Expose tokens in error messages