create-fluxstack 1.12.0 → 1.13.0

package/LLMD/config/environment-vars.md

@@ -90,6 +90,36 @@
 | `BUILD_REMOVE_UNUSED_CSS` | boolean | `false` | Remove unused CSS | build.config.ts |
 | `BUILD_OPTIMIZE_IMAGES` | boolean | `false` | Optimize images | build.config.ts |
 
+## Live Component Logging
+
+| Variable | Type | Default | Description | Config File |
+|----------|------|---------|-------------|-------------|
+| `LIVE_LOGGING` | string | `undefined` | Global live component logs: `true`, `false`, or comma-separated categories (`lifecycle,rooms,messages`) | env only |
+
+> Per-component logging is controlled via `static logging` on the class. See [Live Logging](../resources/live-logging.md).
+
+## Authentication
+
+| Variable | Type | Default | Description | Config File |
+|----------|------|---------|-------------|-------------|
+| `AUTH_DEFAULT_GUARD` | enum | `'session'` | Auth guard: `session`, `token` | auth.config.ts |
+| `AUTH_DEFAULT_PROVIDER` | enum | `'memory'` | User provider: `memory`, `database` | auth.config.ts |
+| `AUTH_HASH_ALGORITHM` | enum | `'bcrypt'` | Hash algorithm: `bcrypt`, `argon2id` | auth.config.ts |
+| `AUTH_BCRYPT_ROUNDS` | number | `10` | Bcrypt cost rounds | auth.config.ts |
+| `AUTH_RATE_LIMIT_MAX_ATTEMPTS` | number | `5` | Max login attempts before lockout | auth.config.ts |
+| `AUTH_RATE_LIMIT_DECAY_SECONDS` | number | `60` | Rate limit window (seconds) | auth.config.ts |
+| `AUTH_TOKEN_TTL` | number | `86400` | Bearer token TTL (seconds, token guard only) | auth.config.ts |
+
+## Session
+
+| Variable | Type | Default | Description | Config File |
+|----------|------|---------|-------------|-------------|
+| `SESSION_COOKIE` | string | `'fluxstack_session'` | Session cookie name | session.config.ts |
+| `SESSION_LIFETIME` | number | `7200` | Session duration (seconds) | session.config.ts |
+| `SESSION_HTTP_ONLY` | boolean | `true` | HttpOnly cookie flag | session.config.ts |
+| `SESSION_SECURE` | boolean | `false` | Secure cookie flag (HTTPS only) | session.config.ts |
+| `SESSION_SAME_SITE` | enum | `'lax'` | SameSite policy: `lax`, `strict`, `none` | session.config.ts |
+
 ## Logging
 
 | Variable | Type | Default | Description | Config File |

package/LLMD/resources/live-auth.md

@@ -0,0 +1,447 @@
+# Live Components Authentication
+
+**Version:** 1.14.0 | **Updated:** 2025-02-12
+
+## Quick Facts
+
+- Declarative auth configuration via `static auth` and `static actionAuth`
+- Role-based access control (RBAC) with OR logic
+- Permission-based access control with AND logic
+- Auto re-mount when authentication changes
+- Pluggable auth providers (JWT, Crypto, Custom)
+- `$auth` helper available in component actions
+
+## Server-Side: Protected Components
+
+### Basic Protection (Auth Required)
+
+```typescript
+// app/server/live/ProtectedChat.ts
+import { LiveComponent } from '@core/types/types'
+import type { LiveComponentAuth } from '@core/server/live/auth/types'
+
+export class ProtectedChat extends LiveComponent<typeof ProtectedChat.defaultState> {
+  static componentName = 'ProtectedChat'
+  static defaultState = {
+    messages: [] as string[]
+  }
+
+  // Auth required to mount this component
+  static auth: LiveComponentAuth = {
+    required: true
+  }
+
+  async sendMessage(payload: { text: string }) {
+    // Only authenticated users can call this
+    return { success: true }
+  }
+}
+```
+
+### Role-Based Protection
+
+```typescript
+// app/server/live/AdminPanel.ts
+import { LiveComponent } from '@core/types/types'
+import type { LiveComponentAuth } from '@core/server/live/auth/types'
+
+export class AdminPanel extends LiveComponent<typeof AdminPanel.defaultState> {
+  static componentName = 'AdminPanel'
+  static defaultState = {
+    users: [] as { id: string; name: string; role: string }[]
+  }
+
+  // Requires auth + admin OR moderator role (OR logic)
+  static auth: LiveComponentAuth = {
+    required: true,
+    roles: ['admin', 'moderator']
+  }
+
+  async deleteUser(payload: { userId: string }) {
+    // User info available via $auth
+    console.log(`User ${this.$auth.user?.id} deleting ${payload.userId}`)
+    return { success: true }
+  }
+}
+```
+
+### Permission-Based Protection
+
+```typescript
+// app/server/live/ContentEditor.ts
+import { LiveComponent } from '@core/types/types'
+import type { LiveComponentAuth } from '@core/server/live/auth/types'
+
+export class ContentEditor extends LiveComponent<typeof ContentEditor.defaultState> {
+  static componentName = 'ContentEditor'
+  static defaultState = {
+    content: ''
+  }
+
+  // Requires ALL permissions (AND logic)
+  static auth: LiveComponentAuth = {
+    required: true,
+    permissions: ['content.read', 'content.write']
+  }
+}
+```
+
+### Per-Action Protection
+
+```typescript
+// app/server/live/ModerationPanel.ts
+import { LiveComponent } from '@core/types/types'
+import type { LiveComponentAuth, LiveActionAuthMap } from '@core/server/live/auth/types'
+
+export class ModerationPanel extends LiveComponent<typeof ModerationPanel.defaultState> {
+  static componentName = 'ModerationPanel'
+  static defaultState = {
+    reports: [] as any[]
+  }
+
+  // Component-level: any authenticated user
+  static auth: LiveComponentAuth = {
+    required: true
+  }
+
+  // Per-action auth
+  static actionAuth: LiveActionAuthMap = {
+    deleteReport: { permissions: ['reports.delete'] },
+    banUser: { roles: ['admin', 'moderator'] }
+  }
+
+  // Anyone authenticated can view
+  async getReports() {
+    return { reports: this.state.reports }
+  }
+
+  // Requires reports.delete permission
+  async deleteReport(payload: { reportId: string }) {
+    return { success: true }
+  }
+
+  // Requires admin OR moderator role
+  async banUser(payload: { userId: string }) {
+    return { success: true }
+  }
+}
+```
+
+## Using $auth in Actions
+
+The `$auth` helper provides access to the authenticated user context:
+
+```typescript
+export class MyComponent extends LiveComponent<State> {
+  async myAction() {
+    // Check if authenticated
+    if (!this.$auth.authenticated) {
+      throw new Error('Not authenticated')
+    }
+
+    // Get user info
+    const userId = this.$auth.user?.id
+    const userName = this.$auth.user?.name
+
+    // Check roles
+    if (this.$auth.hasRole('admin')) {
+      // Admin-only logic
+    }
+
+    if (this.$auth.hasAnyRole(['admin', 'moderator'])) {
+      // Admin OR moderator logic
+    }
+
+    // Check permissions
+    if (this.$auth.hasPermission('users.delete')) {
+      // Has specific permission
+    }
+
+    if (this.$auth.hasAllPermissions(['users.read', 'users.write'])) {
+      // Has ALL permissions
+    }
+
+    return { userId }
+  }
+}
+```
+
+### $auth API
+
+```typescript
+interface LiveAuthContext {
+  readonly authenticated: boolean
+  readonly user?: {
+    id: string
+    roles?: string[]
+    permissions?: string[]
+    [key: string]: unknown  // Custom fields
+  }
+  readonly token?: string
+  readonly authenticatedAt?: number
+
+  hasRole(role: string): boolean
+  hasAnyRole(roles: string[]): boolean
+  hasAllRoles(roles: string[]): boolean
+  hasPermission(permission: string): boolean
+  hasAnyPermission(permissions: string[]): boolean
+  hasAllPermissions(permissions: string[]): boolean
+}
+```
+
+## Client-Side: Authentication
+
+### Authenticate on Connection
+
+Pass auth credentials when the WebSocket connects:
+
+```typescript
+// app/client/src/App.tsx
+import { LiveComponentsProvider } from '@/core/client'
+
+function App() {
+  const token = localStorage.getItem('auth_token')
+
+  return (
+    <LiveComponentsProvider
+      auth={{ token }}  // Sent as query param on connect
+      autoConnect={true}
+    >
+      <AppContent />
+    </LiveComponentsProvider>
+  )
+}
+```
+
+### Dynamic Authentication
+
+Authenticate after connection via `useLiveComponents`:
+
+```typescript
+import { useLiveComponents } from '@/core/client'
+
+function LoginForm() {
+  const { authenticated, authenticate } = useLiveComponents()
+  const [token, setToken] = useState('')
+
+  const handleLogin = async () => {
+    const success = await authenticate({ token })
+    if (success) {
+      // Components with auth errors will auto re-mount
+      console.log('Authenticated!')
+    }
+  }
+
+  return (
+    <div>
+      <p>Status: {authenticated ? 'Logged in' : 'Not logged in'}</p>
+      <input value={token} onChange={e => setToken(e.target.value)} />
+      <button onClick={handleLogin}>Login</button>
+    </div>
+  )
+}
+```
+
+### Checking Auth Status in Components
+
+```typescript
+import { Live } from '@/core/client'
+import { AdminPanel } from '@server/live/AdminPanel'
+
+function AdminSection() {
+  const panel = Live.use(AdminPanel)
+
+  // Check if authenticated on WebSocket level
+  if (!panel.$authenticated) {
+    return <p>Please log in</p>
+  }
+
+  // Check for auth errors
+  if (panel.$error?.includes('AUTH_DENIED')) {
+    return <p>Access denied: {panel.$error}</p>
+  }
+
+  return <div>{/* Admin content */}</div>
+}
+```
+
+### Auto Re-mount on Auth Change
+
+When authentication changes from `false` to `true`, components that failed with `AUTH_DENIED` automatically retry mounting:
+
+```typescript
+// No manual code needed!
+// 1. User tries to mount AdminPanel → AUTH_DENIED
+// 2. User calls authenticate({ token: 'admin-token' })
+// 3. AdminPanel automatically re-mounts with auth context
+```
+
+## Auth Providers
+
+### Creating a Custom Provider
+
+```typescript
+// app/server/auth/MyAuthProvider.ts
+import type {
+  LiveAuthProvider,
+  LiveAuthCredentials,
+  LiveAuthContext
+} from '@core/server/live/auth/types'
+import { AuthenticatedContext } from '@core/server/live/auth/LiveAuthContext'
+
+export class MyAuthProvider implements LiveAuthProvider {
+  readonly name = 'my-auth'
+
+  async authenticate(credentials: LiveAuthCredentials): Promise<LiveAuthContext | null> {
+    const token = credentials.token as string
+    if (!token) return null
+
+    // Validate token (JWT decode, database lookup, etc.)
+    const user = await validateToken(token)
+    if (!user) return null
+
+    return new AuthenticatedContext(
+      {
+        id: user.id,
+        name: user.name,
+        roles: user.roles,
+        permissions: user.permissions
+      },
+      token
+    )
+  }
+
+  // Optional: Custom action authorization
+  async authorizeAction(
+    context: LiveAuthContext,
+    componentName: string,
+    action: string
+  ): Promise<boolean> {
+    // Custom logic (rate limiting, business rules, etc.)
+    return true
+  }
+
+  // Optional: Custom room authorization
+  async authorizeRoom(
+    context: LiveAuthContext,
+    roomId: string
+  ): Promise<boolean> {
+    // Example: VIP rooms require premium role
+    if (roomId.startsWith('vip-') && !context.hasRole('premium')) {
+      return false
+    }
+    return true
+  }
+}
+```
+
+### Registering Providers
+
+```typescript
+// app/server/index.ts
+import { liveAuthManager } from '@core/server/live/auth'
+import { MyAuthProvider } from './auth/MyAuthProvider'
+
+// Register provider
+liveAuthManager.register(new MyAuthProvider())
+
+// Optional: Set as default (first registered is default)
+liveAuthManager.setDefault('my-auth')
+```
+
+### Built-in DevAuthProvider (Development)
+
+For testing, a `DevAuthProvider` with simple tokens is available:
+
+```typescript
+// Tokens available in development:
+// - 'admin-token' → role: admin, all permissions
+// - 'user-token'  → role: user, basic permissions
+// - 'mod-token'   → role: moderator
+
+// Already registered in dev mode automatically
+```
+
+## Auth Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     CLIENT                                  │
+├─────────────────────────────────────────────────────────────┤
+│  1. Connect WebSocket (optional: ?token=xxx)                │
+│  2. authenticate({ token }) → AUTH message                  │
+│  3. Live.use(ProtectedComponent) → COMPONENT_MOUNT          │
+│  4. If AUTH_DENIED, wait for auth change                    │
+│  5. Auth changes → auto re-mount                            │
+└─────────────────────────────────────────────────────────────┘
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     SERVER                                  │
+├─────────────────────────────────────────────────────────────┤
+│  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            │
+│  5. Component has access to this.$auth                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Configuration Types
+
+```typescript
+// Component-level auth
+interface LiveComponentAuth {
+  required?: boolean      // Must be authenticated to mount
+  roles?: string[]        // Required roles (OR logic - any role)
+  permissions?: string[]  // Required permissions (AND logic - all)
+}
+
+// Action-level auth
+interface LiveActionAuth {
+  roles?: string[]        // Required roles (OR logic)
+  permissions?: string[]  // Required permissions (AND logic)
+}
+
+type LiveActionAuthMap = Record<string, LiveActionAuth>
+
+// Credentials from client
+interface LiveAuthCredentials {
+  token?: string
+  publicKey?: string      // For crypto auth
+  signature?: string      // For crypto auth
+  timestamp?: number
+  nonce?: string
+  [key: string]: unknown  // Custom fields
+}
+```
+
+## Critical Rules
+
+**ALWAYS:**
+- Define `static auth` for protected components
+- Define `static actionAuth` for protected actions
+- Use `$auth.hasRole()` / `$auth.hasPermission()` in action logic
+- Register auth providers before server starts
+- Handle `AUTH_DENIED` errors in client UI
+
+**NEVER:**
+- Store sensitive data in component state
+- Trust client-side auth checks alone (always verify server-side)
+- Expose tokens in error messages
+- Skip auth on actions that modify data
+
+**AUTH LOGIC:**
+```typescript
+// Roles: OR logic (any role grants access)
+roles: ['admin', 'moderator']  // admin OR moderator
+
+// Permissions: AND logic (all permissions required)
+permissions: ['users.read', 'users.write']  // BOTH required
+```
+
+## Related
+
+- [Live Components](./live-components.md) - Base component documentation
+- [Live Rooms](./live-rooms.md) - Room-based communication
+- [Plugin System](../core/plugin-system.md) - Auth as plugin

package/LLMD/resources/live-components.md

@@ -1,18 +1,18 @@
 # Live Components
 
-**Version:** 1.12.0 | **Updated:** 2025-02-09
+**Version:** 1.13.0 | **Updated:** 2025-02-09
 
 ## Quick Facts
 
 - Server-side state management with WebSocket sync
-- **Reactive state Proxy** - `this.state.count++` auto-syncs
+- **Direct state access** - `this.count++` auto-syncs (v1.13.0)
 - Automatic state persistence and re-hydration
 - Room-based event system for multi-user sync
 - Type-safe client-server communication (FluxStackWebSocket)
 - Built-in connection management and recovery
 - **Client component links** - Ctrl+Click navigation
 
-## LiveComponent Class Structure (v1.12.0)
+## LiveComponent Class Structure (v1.13.0)
 
 Server-side component extends `LiveComponent` with **static defaultState**:
 
@@ -25,28 +25,38 @@ 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 defaultState = {
     count: 0
   }
 
-  // ✅ Reactive state - auto-syncs with frontend
+  // Declarar propriedades do estado (TypeScript)
+  declare count: number
+
+  // ✅ Direct state access - auto-syncs with frontend
   async increment() {
-    this.state.count++
-    return { success: true, count: this.state.count }
+    this.count++
+    return { success: true, count: this.count }
   }
 
   async decrement() {
-    this.state.count--
-    return { success: true, count: this.state.count }
+    this.count--
+    return { success: true, count: this.count }
   }
 
   async reset() {
-    this.state.count = 0
+    this.count = 0
     return { success: true }
   }
 }
 ```
 
+### Key Changes in v1.13.0
+
+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.`
+
 ### Key Changes in v1.12.0
 
 1. **Static defaultState inside class** - No external export needed
@@ -120,29 +130,67 @@ export class MyComponent extends LiveComponent<typeof MyComponent.defaultState>
 
 ## State Management
 
-### Reactive State (v1.12.0) ✨
+### Reactive State Proxy (How It Works)
+
+State mutations auto-sync with the frontend via two layers:
+
+**Layer 1 — Proxy** (`this.state`): A `Proxy` wraps the internal state object. Any `set` on `this.state` compares old vs new value and, if changed, emits `STATE_DELTA` to the client automatically.
+
+**Layer 2 — Direct Accessors** (`this.count`): On construction, `createDirectStateAccessors()` defines a getter/setter via `Object.defineProperty` for each key in `defaultState`. The setter delegates to the proxy, so it also triggers `STATE_DELTA`.
+
+```
+this.count++              → accessor setter → proxy set → STATE_DELTA
+this.state.count++        → proxy set → STATE_DELTA
+this.setState({count: 1}) → Object.assign + single STATE_DELTA (batch)
+```
+
+### Direct State Access (v1.13.0) ✨
 
-State mutations auto-sync with frontend via Proxy:
+State properties are accessible directly on `this`:
 
 ```typescript
-// ✅ Direct mutation - auto-syncs!
-this.state.count++
-this.state.message = 'Hello'
+// Declare properties for TypeScript
+declare count: number
+declare message: string
+
+// ✅ Direct access - auto-syncs via proxy!
+this.count++
+this.message = 'Hello'
 
-// No need for setState() on single property updates
+// ✅ Also works (v1.12.0 style) - same proxy underneath
+this.state.count++
 ```
 
+> **Performance note:** Each direct assignment emits one `STATE_DELTA`. For multiple properties at once, use `setState` (single emit).
+
 ### setState (Batch Updates)
 
 Use `setState` for multiple properties at once (single emit):
 
 ```typescript
-// ✅ Batch update - one sync event
+// ✅ Batch update - one STATE_DELTA event
 this.setState({
   count: newCount,
   lastUpdatedBy: userId,
   updatedAt: new Date().toISOString()
 })
+
+// ✅ Function updater (access previous state)
+this.setState(prev => ({
+  count: prev.count + 1,
+  lastUpdatedBy: userId
+}))
+```
+
+> `setState` writes directly to `_state` (bypasses proxy) and emits a single `STATE_DELTA` with all changed keys. More efficient than N individual assignments.
+
+### setValue (Generic Action)
+
+Built-in action to set any state key from the client:
+
+```typescript
+// Client can call this without defining a custom action
+await component.setValue({ key: 'count', value: 42 })
 ```
 
 ### getSerializableState
@@ -483,6 +531,7 @@ app/client/src/live/
 Each server file contains:
 - `static componentName` - Component identifier
 - `static defaultState` - Initial state object
+- `static logging` - Per-component log control (optional, see [Live Logging](./live-logging.md))
 - Component class extending `LiveComponent`
 - Client link via `import type { Demo as _Client }`
 
@@ -536,6 +585,7 @@ export class MyComponent extends LiveComponent<State> {
 - Define `static componentName` matching class name
 - Define `static defaultState` inside the class
 - Use `typeof ClassName.defaultState` for type parameter
+- Use `declare` for each state property (TypeScript type hint)
 - Call `super.destroy()` in destroy method if overriding
 - Use `emitRoomEventWithState` for state changes in rooms
 - Handle errors in actions (throw Error)
@@ -547,17 +597,22 @@ export class MyComponent extends LiveComponent<State> {
 - 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)
 
-**STATE UPDATES (v1.12.0):**
+**STATE UPDATES (v1.13.0) — all auto-sync via Proxy:**
 ```typescript
-// ✅ Single property - use direct mutation
+// ✅ Direct access (1 prop → 1 STATE_DELTA)
+declare count: number
+this.count++
+
+// ✅ Also works (same proxy underneath)
 this.state.count++
 
-// ✅ Multiple properties - use setState (one sync)
+// ✅ Multiple properties → use setState (1 STATE_DELTA for all)
 this.setState({ a: 1, b: 2, c: 3 })
 
 // ❌ Don't use setState for single property (unnecessary)
-this.setState({ count: this.state.count + 1 })
+this.setState({ count: this.count + 1 })
 ```
 
 ---
@@ -697,7 +752,10 @@ export function UploadDemo() {
 
 ## Related
 
+- [Live Auth](./live-auth.md) - Authentication for Live Components
+- [Live Logging](./live-logging.md) - Per-component logging control
+- [Live Rooms](./live-rooms.md) - Multi-room real-time communication
+- [Live Upload](./live-upload.md) - Chunked file upload
 - [Project Structure](../patterns/project-structure.md)
 - [Type Safety Patterns](../patterns/type-safety.md)
 - [WebSocket Plugin](../core/plugin-system.md)
-- [Live Upload](./live-upload.md)