create-fluxstack 1.13.0 → 1.14.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

package/LLMD/resources/live-components.md

@@ -6,7 +6,8 @@
 
 - Server-side state management with WebSocket sync
 - **Direct state access** - `this.count++` auto-syncs (v1.13.0)
-- Automatic state persistence and re-hydration
+- **Mandatory `publicActions`** - Only whitelisted methods are callable from client (secure by default)
+- Automatic state persistence and re-hydration (with anti-replay nonces)
 - Room-based event system for multi-user sync
 - Type-safe client-server communication (FluxStackWebSocket)
 - Built-in connection management and recovery
@@ -25,7 +26,8 @@ import type { CounterDemo as _Client } from '@client/src/live/CounterDemo'
 
 export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
   static componentName = 'LiveCounter'
-  static logging = ['lifecycle', 'messages'] as const  // Per-component logging (optional)
+  static publicActions = ['increment', 'decrement', 'reset'] as const  // 🔒 REQUIRED
+  // static logging = ['lifecycle', 'messages'] as const  // Console logging (optional, prefer DEBUG_LIVE)
   static defaultState = {
     count: 0
   }
@@ -56,6 +58,7 @@ export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState>
 1. **Direct state access** - `this.count++` instead of `this.state.count++`
 2. **declare keyword** - TypeScript hint for dynamic properties
 3. **Cleaner code** - No need to prefix with `this.state.`
+4. **Mandatory `publicActions`** - Components without it deny ALL remote actions (secure by default)
 
 ### Key Changes in v1.12.0
 
@@ -72,6 +75,7 @@ import { LiveComponent, type FluxStackWebSocket } from '@core/types/types'
 
 export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
   static componentName = 'LiveCounter'
+  static publicActions = ['increment'] as const  // 🔒 REQUIRED
   static defaultState = {
     count: 0,
     lastUpdatedBy: null as string | null,
@@ -186,16 +190,86 @@ this.setState(prev => ({
 
 ### setValue (Generic Action)
 
-Built-in action to set any state key from the client:
+Built-in action to set any state key from the client. **Must be explicitly included in `publicActions` to be callable:**
 
 ```typescript
-// Client can call this without defining a custom action
+// Server: opt-in to setValue
+static publicActions = ['increment', 'setValue'] as const  // Must include 'setValue'
+
+// Client can then call:
 await component.setValue({ key: 'count', value: 42 })
 ```
 
+> **Security note:** `setValue` is powerful - it allows the client to set any state key. Only add it to `publicActions` if you trust the client to modify any state field.
+
+### $private — Server-Only State
+
+`$private` is a key-value store that lives **exclusively on the server**. It is NEVER synchronized with the client — no `STATE_UPDATE`, no `STATE_DELTA`, not included in `getSerializableState()`.
+
+Use it for sensitive data like tokens, API keys, internal IDs, or any server-side bookkeeping:
+
+```typescript
+export class Chat extends LiveComponent<typeof Chat.defaultState> {
+  static componentName = 'Chat'
+  static publicActions = ['connect', 'sendMessage'] as const
+  static defaultState = { messages: [] as string[] }
+
+  async connect(payload: { token: string }) {
+    // 🔒 Stays on server — never sent to client
+    this.$private.token = payload.token
+    this.$private.apiKey = await getApiKey()
+
+    // ✅ Only UI data goes to state (synced with client)
+    this.state.messages = await fetchMessages(this.$private.token)
+    return { success: true }
+  }
+
+  async sendMessage(payload: { text: string }) {
+    // Use $private data for server-side logic
+    await postToAPI(this.$private.apiKey, payload.text)
+    this.state.messages = [...this.state.messages, payload.text]
+    return { success: true }
+  }
+}
+```
+
+#### Typed $private (optional)
+
+Pass a second generic to get full autocomplete and type checking:
+
+```typescript
+interface ChatPrivate {
+  token: string
+  apiKey: string
+  retryCount: number
+}
+
+export class Chat extends LiveComponent<typeof Chat.defaultState, ChatPrivate> {
+  static componentName = 'Chat'
+  static publicActions = ['connect'] as const
+  static defaultState = { messages: [] as string[] }
+
+  async connect(payload: { token: string }) {
+    this.$private.token = payload.token     // ✅ autocomplete
+    this.$private.retryCount = 0            // ✅ must be number
+    this.$private.tokkken = 'x'             // ❌ TypeScript error (typo)
+  }
+}
+```
+
+The second generic defaults to `Record<string, any>`, so existing components work without changes.
+
+**Key facts:**
+- Starts as an empty `{}` — no static default needed
+- Mutations do NOT trigger any WebSocket messages
+- Cleared automatically on `destroy()`
+- Lost on rehydration (re-populate in your action handlers)
+- Blocked from remote access (`$private` and `_privateState` are in BLOCKED_ACTIONS)
+- Optional `TPrivate` generic for full type safety
+
 ### getSerializableState
 
-Get current state for serialization:
+Get current state for serialization (does NOT include `$private`):
 
 ```typescript
 const currentState = this.getSerializableState()
@@ -260,11 +334,13 @@ const counter = Live.use(LiveCounter, {
 
 ## Actions
 
-Actions are methods called from the client:
+Actions are methods callable from the client. **Only methods listed in `publicActions` can be called remotely.** Components without `publicActions` deny ALL remote actions.
 
 ```typescript
 // Server-side
 export class LiveForm extends LiveComponent<FormState> {
+  static publicActions = ['submit', 'validate'] as const  // 🔒 REQUIRED
+
   async submit() {
     const { name, email } = this.state
     
@@ -429,10 +505,11 @@ On reconnect, components restore previous state:
 
 1. Client stores signed state in localStorage
 2. On reconnect, sends signed state to server
-3. Server validates signature
+3. Server validates signature (HMAC-SHA256) and **anti-replay nonce**
 4. Component re-hydrated with previous state
+5. State expires after 24 hours (configurable)
 
-No manual code needed - automatic.
+No manual code needed - automatic. Each signed state includes a cryptographic nonce that is consumed on validation, preventing replay attacks.
 
 ## Multi-User Synchronization
 
@@ -530,8 +607,9 @@ app/client/src/live/
 
 Each server file contains:
 - `static componentName` - Component identifier
+- `static publicActions` - **REQUIRED** whitelist of client-callable methods
 - `static defaultState` - Initial state object
-- `static logging` - Per-component log control (optional, see [Live Logging](./live-logging.md))
+- `static logging` - Per-component console log control (optional, prefer `DEBUG_LIVE=true` for debug panel — see [Live Logging](./live-logging.md))
 - Component class extending `LiveComponent`
 - Client link via `import type { Demo as _Client }`
 
@@ -583,6 +661,7 @@ export class MyComponent extends LiveComponent<State> {
 
 **ALWAYS:**
 - Define `static componentName` matching class name
+- Define `static publicActions` listing ALL client-callable methods (MANDATORY)
 - Define `static defaultState` inside the class
 - Use `typeof ClassName.defaultState` for type parameter
 - Use `declare` for each state property (TypeScript type hint)
@@ -592,12 +671,15 @@ export class MyComponent extends LiveComponent<State> {
 - Add client link: `import type { Demo as _Client } from '@client/...'`
 
 **NEVER:**
+- Omit `static publicActions` (component will deny ALL remote actions)
 - Export separate `defaultState` constant (use static)
 - Create constructor just to call super() (not needed)
 - Forget `static componentName` (breaks minification)
 - Emit room events without subscribing first
 - Store non-serializable data in state
-- Use reserved names for state properties (id, state, ws, room, userId, $room, $rooms, broadcastToRoom, roomType)
+- Use reserved names for state properties (id, state, ws, room, userId, $room, $rooms, $private, broadcastToRoom, roomType)
+- Include `setValue` in `publicActions` unless you trust clients to modify any state key
+- Store sensitive data (tokens, API keys, secrets) in `state` — use `$private` instead
 
 **STATE UPDATES (v1.13.0) — all auto-sync via Proxy:**
 ```typescript
@@ -636,6 +718,8 @@ import { liveUploadDefaultState, type LiveUploadState } from '@app/shared'
 export const defaultState: LiveUploadState = liveUploadDefaultState
 
 export class LiveUpload extends LiveComponent<LiveUploadState> {
+  static componentName = 'LiveUpload'
+  static publicActions = ['startUpload', 'updateProgress', 'completeUpload', 'failUpload', 'reset'] as const
   static defaultState = defaultState
 
   constructor(initialState: Partial<typeof defaultState>, ws: any, options?: { room?: string; userId?: string }) {