create-fluxstack 1.12.1 → 1.14.0

package/core/types/types.ts

@@ -2,6 +2,27 @@
 
 import { roomEvents } from '@core/server/live/RoomEventBus'
 import { liveRoomManager } from '@core/server/live/LiveRoomManager'
+import { ANONYMOUS_CONTEXT } from '@core/server/live/auth/LiveAuthContext'
+import { liveLog, liveWarn } from '@core/server/live/LiveLogger'
+
+// ===== Debug Instrumentation (injectable to avoid client-side import) =====
+// The real debugger is injected by ComponentRegistry at server startup.
+// This avoids importing server-only LiveDebugger.ts from this shared types file.
+interface LiveDebuggerInterface {
+  trackStateChange(componentId: string, delta: Record<string, unknown>, fullState: Record<string, unknown>, source?: string): void
+  trackActionCall(componentId: string, action: string, payload: unknown): void
+  trackActionResult(componentId: string, action: string, result: unknown, duration: number): void
+  trackActionError(componentId: string, action: string, error: string, duration: number): void
+  trackRoomEmit(componentId: string, roomId: string, event: string, data: unknown): void
+}
+
+let _liveDebugger: LiveDebuggerInterface | null = null
+
+/** @internal Called by ComponentRegistry to inject the debugger instance */
+export function _setLiveDebugger(dbg: LiveDebuggerInterface): void {
+  _liveDebugger = dbg
+}
+import type { LiveAuthContext, LiveComponentAuth, LiveActionAuthMap } from '@core/server/live/auth/types'
 import type { ServerWebSocket } from 'bun'
 
 // ============================================
@@ -18,6 +39,8 @@ export interface FluxStackWSData {
   subscriptions: Set<string>
   connectedAt: Date
   userId?: string
+  /** Contexto de autenticação da conexão WebSocket */
+  authContext?: LiveAuthContext
 }
 
 /**
@@ -46,9 +69,11 @@ export type FluxStackServerWebSocket = ServerWebSocket<FluxStackWSData>
 export interface LiveMessage {
   type: 'COMPONENT_MOUNT' | 'COMPONENT_UNMOUNT' |
   'COMPONENT_REHYDRATE' | 'COMPONENT_ACTION' | 'CALL_ACTION' |
-  'ACTION_RESPONSE' | 'PROPERTY_UPDATE' | 'STATE_UPDATE' | 'STATE_REHYDRATED' |
+  'ACTION_RESPONSE' | 'PROPERTY_UPDATE' | 'STATE_UPDATE' | 'STATE_DELTA' | 'STATE_REHYDRATED' |
   'ERROR' | 'BROADCAST' | 'FILE_UPLOAD_START' | 'FILE_UPLOAD_CHUNK' | 'FILE_UPLOAD_COMPLETE' |
   'COMPONENT_PING' | 'COMPONENT_PONG' |
+  // Auth system message
+  'AUTH' |
   // Room system messages
   'ROOM_JOIN' | 'ROOM_LEAVE' | 'ROOM_EMIT' | 'ROOM_STATE_SET' | 'ROOM_STATE_GET'
   componentId: string
@@ -117,7 +142,9 @@ export interface WebSocketMessage {
 }
 
 export interface WebSocketResponse {
-  type: 'MESSAGE_RESPONSE' | 'CONNECTION_ESTABLISHED' | 'ERROR' | 'BROADCAST' | 'ACTION_RESPONSE' | 'COMPONENT_MOUNTED' | 'COMPONENT_REHYDRATED' | 'STATE_UPDATE' | 'STATE_REHYDRATED' | 'FILE_UPLOAD_PROGRESS' | 'FILE_UPLOAD_COMPLETE' | 'FILE_UPLOAD_ERROR' | 'FILE_UPLOAD_START_RESPONSE' | 'COMPONENT_PONG' |
+  type: 'MESSAGE_RESPONSE' | 'CONNECTION_ESTABLISHED' | 'ERROR' | 'BROADCAST' | 'ACTION_RESPONSE' | 'COMPONENT_MOUNTED' | 'COMPONENT_REHYDRATED' | 'STATE_UPDATE' | 'STATE_DELTA' | 'STATE_REHYDRATED' | 'FILE_UPLOAD_PROGRESS' | 'FILE_UPLOAD_COMPLETE' | 'FILE_UPLOAD_ERROR' | 'FILE_UPLOAD_START_RESPONSE' | 'COMPONENT_PONG' |
+  // Auth system response
+  'AUTH_RESPONSE' |
   // Room system responses
   'ROOM_EVENT' | 'ROOM_STATE' | 'ROOM_SYSTEM' | 'ROOM_JOINED' | 'ROOM_LEFT'
   originalType?: string
@@ -208,12 +235,54 @@ export interface ServerRoomProxy<TState = any, TEvents extends Record<string, an
   setState: (updates: Partial<TState>) => void
 }
 
-export abstract class LiveComponent<TState = ComponentState> {
+export abstract class LiveComponent<TState = ComponentState, TPrivate extends Record<string, any> = Record<string, any>> {
   /** Component name for registry lookup - must be defined in subclasses */
   static componentName: string
   /** Default state - must be defined in subclasses */
   static defaultState: any
 
+  /**
+   * Per-component logging control. Silent by default.
+   *
+   * @example
+   * // Enable all log categories
+   * static logging = true
+   *
+   * // Enable specific categories only
+   * static logging = ['lifecycle', 'messages'] as const
+   *
+   * // Disabled (default — omit or set false)
+   * static logging = false
+   *
+   * Categories: 'lifecycle' | 'messages' | 'state' | 'performance' | 'rooms' | 'websocket'
+   */
+  static logging?: boolean | readonly ('lifecycle' | 'messages' | 'state' | 'performance' | 'rooms' | 'websocket')[]
+
+  /**
+   * Configuração de autenticação do componente.
+   * Define se auth é obrigatória e quais roles/permissions são necessárias.
+   *
+   * @example
+   * static auth: LiveComponentAuth = {
+   *   required: true,
+   *   roles: ['admin', 'moderator'],
+   *   permissions: ['chat.read'],
+   * }
+   */
+  static auth?: LiveComponentAuth
+
+  /**
+   * Configuração de autenticação por action.
+   * Permite controle granular de permissões por método.
+   *
+   * @example
+   * static actionAuth: LiveActionAuthMap = {
+   *   deleteMessage: { permissions: ['chat.admin'] },
+   *   sendMessage: { permissions: ['chat.write'] },
+   * }
+   */
+  static actionAuth?: LiveActionAuthMap
+
   public readonly id: string
   private _state: TState
   public state: TState // Proxy wrapper
@@ -222,6 +291,12 @@ export abstract class LiveComponent<TState = ComponentState> {
   public userId?: string
   public broadcastToRoom: (message: BroadcastMessage) => void = () => {} // Will be injected by registry
 
+  // 🔒 Server-only private state (NEVER sent to client)
+  private _privateState: TPrivate = {} as TPrivate
+
+  // Auth context (injected by registry during mount)
+  private _authContext: LiveAuthContext = ANONYMOUS_CONTEXT
+
   // Room event subscriptions (cleaned up on destroy)
   private roomEventUnsubscribers: (() => void)[] = []
   private joinedRooms: Set<string> = new Set()
@@ -250,9 +325,39 @@ export abstract class LiveComponent<TState = ComponentState> {
       this.joinedRooms.add(this.room)
       liveRoomManager.joinRoom(this.id, this.room, this.ws)
     }
+
+    // 🔥 Create direct property accessors (this.count instead of this.state.count)
+    this.createDirectStateAccessors()
+  }
+
+  // Create getters/setters for each state property directly on `this`
+  private createDirectStateAccessors() {
+    // Properties that should NOT become state accessors
+    const forbidden = new Set([
+      // Instance properties
+      ...Object.keys(this),
+      // Prototype methods
+      ...Object.getOwnPropertyNames(Object.getPrototypeOf(this)),
+      // Known internal properties
+      'state', '_state', 'ws', 'id', 'room', 'userId', 'broadcastToRoom',
+      '$private', '_privateState',
+      '$room', '$rooms', 'roomType', 'roomHandles', 'joinedRooms', 'roomEventUnsubscribers'
+    ])
+
+    // Create accessor for each state key
+    for (const key of Object.keys(this._state as object)) {
+      if (!forbidden.has(key)) {
+        Object.defineProperty(this, key, {
+          get: () => (this._state as any)[key],
+          set: (value) => { (this.state as any)[key] = value }, // Uses proxy for auto-sync
+          enumerable: true,
+          configurable: true
+        })
+      }
+    }
   }
 
-  // Create a Proxy that auto-emits STATE_UPDATE on any mutation
+  // Create a Proxy that auto-emits STATE_DELTA on any mutation
   private createStateProxy(state: TState): TState {
     const self = this
     return new Proxy(state as object, {
@@ -260,8 +365,15 @@ export abstract class LiveComponent<TState = ComponentState> {
         const oldValue = (target as any)[prop]
         if (oldValue !== value) {
           (target as any)[prop] = value
-          // Auto-sync to frontend
-          self.emit('STATE_UPDATE', { state: self._state })
+          // Delta sync - send only the changed property
+          self.emit('STATE_DELTA', { delta: { [prop]: value } })
+          // Debug: track proxy mutation
+          _liveDebugger?.trackStateChange(
+            self.id,
+            { [prop]: value } as Record<string, unknown>,
+            target as Record<string, unknown>,
+            'proxy'
+          )
         }
         return true
       },
@@ -271,6 +383,33 @@ export abstract class LiveComponent<TState = ComponentState> {
     }) as TState
   }
 
+  // ========================================
+  // 🔒 $private - Server-Only State
+  // ========================================
+
+  /**
+   * Server-only state that is NEVER synchronized with the client.
+   * Use this for sensitive data like tokens, API keys, internal IDs, etc.
+   *
+   * Unlike `this.state`, mutations to `$private` do NOT trigger
+   * STATE_DELTA or STATE_UPDATE messages.
+   *
+   * ⚠️ Private state is lost on rehydration (since it's never sent to client).
+   * Re-populate it in your action handlers as needed.
+   *
+   * @example
+   * async connect(payload: { token: string }) {
+   *   this.$private.token = payload.token
+   *   this.$private.apiKey = await getKey()
+   *
+   *   // Only UI-relevant data goes to state (synced with client)
+   *   this.state.messages = await fetchMessages(this.$private.token)
+   * }
+   */
+  public get $private(): TPrivate {
+    return this._privateState
+  }
+
   // ========================================
   // 🔥 $room - Sistema de Salas Unificado
   // ========================================
@@ -388,11 +527,55 @@ export abstract class LiveComponent<TState = ComponentState> {
     return Array.from(this.joinedRooms)
   }
 
-  // State management (batch update - single emit)
+  // ========================================
+  // 🔒 $auth - Contexto de Autenticação
+  // ========================================
+
+  /**
+   * Acessa o contexto de autenticação do usuário atual.
+   * Disponível após o mount do componente.
+   *
+   * @example
+   * async sendMessage(payload: { text: string }) {
+   *   if (!this.$auth.authenticated) {
+   *     throw new Error('Login required')
+   *   }
+   *
+   *   const userId = this.$auth.user!.id
+   *   const isAdmin = this.$auth.hasRole('admin')
+   *   const canDelete = this.$auth.hasPermission('chat.admin')
+   * }
+   */
+  public get $auth(): LiveAuthContext {
+    return this._authContext
+  }
+
+  /**
+   * Injeta o contexto de autenticação no componente.
+   * Chamado internamente pelo ComponentRegistry durante o mount.
+   * @internal
+   */
+  public setAuthContext(context: LiveAuthContext): void {
+    this._authContext = context
+    // Atualiza userId se disponível no auth context
+    if (context.authenticated && context.user?.id && !this.userId) {
+      this.userId = context.user.id
+    }
+  }
+
+  // State management (batch update - single emit with delta)
   public setState(updates: Partial<TState> | ((prev: TState) => Partial<TState>)) {
     const newUpdates = typeof updates === 'function' ? updates(this._state) : updates
     Object.assign(this._state as object, newUpdates)
-    this.emit('STATE_UPDATE', { state: this._state })
+    // Delta sync - send only the changed properties
+    this.emit('STATE_DELTA', { delta: newUpdates })
+    // Debug: track state change
+    _liveDebugger?.trackStateChange(
+      this.id,
+      newUpdates as Record<string, unknown>,
+      this._state as Record<string, unknown>,
+      'setState'
+    )
   }
 
   // Generic setValue action - set any state key with type safety
@@ -403,23 +586,86 @@ export abstract class LiveComponent<TState = ComponentState> {
     return { success: true, key, value }
   }
 
-  // Execute action safely
+  /**
+   * 🔒 REQUIRED: List of methods that are explicitly callable from the client.
+   * ONLY these methods can be called via CALL_ACTION.
+   * Components without publicActions will deny ALL remote actions (secure by default).
+   *
+   * @example
+   * static publicActions = ['sendMessage', 'deleteMessage', 'join'] as const
+   */
+  static publicActions?: readonly string[]
+
+  // Internal methods that must NEVER be callable from the client
+  private static readonly BLOCKED_ACTIONS: ReadonlySet<string> = new Set([
+    // Lifecycle & internal
+    'constructor', 'destroy', 'executeAction', 'getSerializableState',
+    // State management internals
+    'setState', 'emit', 'broadcast', 'broadcastToRoom',
+    'createStateProxy', 'createDirectStateAccessors', 'generateId',
+    // Auth internals
+    'setAuthContext', '$auth',
+    // Private state internals
+    '$private', '_privateState',
+    // Room internals
+    '$room', '$rooms', 'subscribeToRoom', 'unsubscribeFromRoom',
+    'emitRoomEvent', 'onRoomEvent', 'emitRoomEventWithState',
+  ])
+
+  // Execute action safely with security validation
   public async executeAction(action: string, payload: any): Promise<any> {
+    const actionStart = Date.now()
     try {
-      // Check if method exists
+      // 🔒 Security: Block internal/protected methods from being called remotely
+      if ((LiveComponent.BLOCKED_ACTIONS as Set<string>).has(action)) {
+        throw new Error(`Action '${action}' is not callable`)
+      }
+
+      // 🔒 Security: Block private methods (prefixed with _ or #)
+      if (action.startsWith('_') || action.startsWith('#')) {
+        throw new Error(`Action '${action}' is not callable`)
+      }
+
+      // 🔒 Security: publicActions whitelist is MANDATORY
+      // Components without publicActions deny ALL remote actions (secure by default)
+      const componentClass = this.constructor as typeof LiveComponent
+      const publicActions = componentClass.publicActions
+      if (!publicActions) {
+        console.warn(`🔒 [SECURITY] Component '${componentClass.componentName || componentClass.name}' has no publicActions defined. All remote actions are blocked. Define static publicActions to allow specific actions.`)
+        throw new Error(`Action '${action}' is not callable - component has no publicActions defined`)
+      }
+      if (!publicActions.includes(action)) {
+        throw new Error(`Action '${action}' is not callable`)
+      }
+
+      // Check if method exists on the instance
       const method = (this as any)[action]
       if (typeof method !== 'function') {
         throw new Error(`Action '${action}' not found on component`)
       }
 
+      // 🔒 Security: Block inherited Object.prototype methods
+      if (Object.prototype.hasOwnProperty.call(Object.prototype, action)) {
+        throw new Error(`Action '${action}' is not callable`)
+      }
+
+      // Debug: track action call
+      _liveDebugger?.trackActionCall(this.id, action, payload)
+
       // Execute method
       const result = await method.call(this, payload)
+
+      // Debug: track action result
+      _liveDebugger?.trackActionResult(this.id, action, result, Date.now() - actionStart)
+
       return result
     } catch (error: any) {
-      this.emit('ERROR', { 
-        action, 
-        error: error.message,
-        stack: error.stack 
+      // Debug: track action error
+      _liveDebugger?.trackActionError(this.id, action, error.message, Date.now() - actionStart)
+
+      this.emit('ERROR', {
+        action,
+        error: error.message
       })
       throw error
     }
@@ -444,7 +690,7 @@ export abstract class LiveComponent<TState = ComponentState> {
   // Broadcast to all clients in room (via WebSocket)
   protected broadcast(type: string, payload: any, excludeCurrentUser = false) {
     if (!this.room) {
-      console.warn(`⚠️ [${this.id}] Cannot broadcast '${type}' - no room set`)
+      liveWarn('rooms', this.id, `⚠️ [${this.id}] Cannot broadcast '${type}' - no room set`)
       return
     }
 
@@ -455,7 +701,7 @@ export abstract class LiveComponent<TState = ComponentState> {
       excludeUser: excludeCurrentUser ? this.userId : undefined
     }
 
-    console.log(`📤 [${this.id}] Broadcasting '${type}' to room '${this.room}'`)
+    liveLog('rooms', this.id, `📤 [${this.id}] Broadcasting '${type}' to room '${this.room}'`)
 
     // This will be handled by the registry
     this.broadcastToRoom(message)
@@ -475,14 +721,18 @@ export abstract class LiveComponent<TState = ComponentState> {
    */
   protected emitRoomEvent(event: string, data: any, notifySelf = false): number {
     if (!this.room) {
-      console.warn(`⚠️ [${this.id}] Cannot emit room event '${event}' - no room set`)
+      liveWarn('rooms', this.id, `⚠️ [${this.id}] Cannot emit room event '${event}' - no room set`)
       return 0
     }
 
     const excludeId = notifySelf ? undefined : this.id
     const notified = roomEvents.emit(this.roomType, this.room, event, data, excludeId)
 
-    console.log(`📡 [${this.id}] Room event '${event}' → ${notified} components`)
+    liveLog('rooms', this.id, `📡 [${this.id}] Room event '${event}' → ${notified} components`)
+
+    // Debug: track room emit
+    _liveDebugger?.trackRoomEmit(this.id, this.room, event, data)
+
     return notified
   }
 
@@ -495,7 +745,7 @@ export abstract class LiveComponent<TState = ComponentState> {
    */
   protected onRoomEvent<T = any>(event: string, handler: (data: T) => void): void {
     if (!this.room) {
-      console.warn(`⚠️ [${this.id}] Cannot subscribe to room event '${event}' - no room set`)
+      liveWarn('rooms', this.id, `⚠️ [${this.id}] Cannot subscribe to room event '${event}' - no room set`)
       return
     }
 
@@ -510,7 +760,7 @@ export abstract class LiveComponent<TState = ComponentState> {
     // Guardar para cleanup no destroy
     this.roomEventUnsubscribers.push(unsubscribe)
 
-    console.log(`👂 [${this.id}] Subscribed to room event '${event}'`)
+    liveLog('rooms', this.id, `👂 [${this.id}] Subscribed to room event '${event}'`)
   }
 
   /**
@@ -545,9 +795,9 @@ export abstract class LiveComponent<TState = ComponentState> {
     // Registry will handle the actual unsubscription
   }
 
-  // Generate unique ID
+  // Generate unique ID using cryptographically secure randomness
   private generateId(): string {
-    return `live-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
+    return `live-${crypto.randomUUID()}`
   }
 
   // Cleanup when component is destroyed
@@ -564,6 +814,7 @@ export abstract class LiveComponent<TState = ComponentState> {
     }
     this.joinedRooms.clear()
     this.roomHandles.clear()
+    this._privateState = {} as TPrivate
 
     this.unsubscribeFromRoom()
     // Override in subclasses for custom cleanup
@@ -638,6 +889,11 @@ export type ActionReturn<
  */
 export type InferComponentState<T extends LiveComponent<any>> = T extends LiveComponent<infer S> ? S : never
 
+/**
+ * Get the private state type from a LiveComponent class
+ */
+export type InferPrivateState<T extends LiveComponent<any, any>> = T extends LiveComponent<any, infer P> ? P : never
+
 /**
  * Type-safe call signature for a component
  * Provides autocomplete for action names and validates payload types

package/core/utils/index.ts

@@ -1,18 +1,18 @@
-/**
- * FluxStack Utilities
- * Main exports for utility functions and classes
- */
-
-// Logger utilities
-export { logger, log } from "./logger"
-export type { Logger } from "./logger/index"
-
-// Error handling
-export * from "./errors"
-
-// Monitoring
-export { MetricsCollector } from "./monitoring"
-export type * from "./monitoring"
-
-// General helpers
+/**
+ * FluxStack Utilities
+ * Main exports for utility functions and classes
+ */
+
+// Logger utilities
+export { logger, log } from "./logger"
+export type { Logger } from "./logger/index"
+
+// Error handling
+export * from "./errors"
+
+// Monitoring
+export { MetricsCollector } from "./monitoring"
+export type * from "./monitoring"
+
+// General helpers
 export * from "./helpers"

package/core/utils/logger/index.ts

@@ -127,7 +127,7 @@ export function SECTION(sectionName: string, callback: () => void): void {
 /**
  * HTTP request logging with colors and formatting
  */
-export function request(method: string, path: string, status?: number, duration?: number): void {
+export function request(method: string, path: string, status?: number, duration?: number, ip?: string): void {
   const { file: callerFile } = getCallerInfo()
   const logger = getLoggerForModule(callerFile)
 
@@ -159,12 +159,15 @@ export function request(method: string, path: string, status?: number, duration?
     durationStr = ` ${durationColor(`(${duration}ms)`)}`
   }
 
+  // Format IP address
+  const ipStr = ip ? chalk.dim(`[${ip}]`) + ' ' : ''
+
   // Build log message
   const methodStr = methodColor(method.padEnd(7))
   const pathStr = chalk.white(path.padEnd(30))
   const statusStr = status ? `→ ${statusColor(status.toString())}` : ''
 
-  const message = `${methodStr} ${pathStr} ${statusStr}${durationStr}`
+  const message = `${ipStr}${methodStr} ${pathStr} ${statusStr}${durationStr}`
 
   // Use appropriate log level based on status
   const level = status && status >= 500 ? 'error' : status && status >= 400 ? 'warn' : 'info'