create-fluxstack 1.12.0 → 1.13.0

package/LLMD/resources/live-logging.md

@@ -0,0 +1,158 @@
+# Live Logging
+
+**Version:** 1.12.0 | **Updated:** 2025-02-12
+
+## Quick Facts
+
+- Per-component logging control — silent by default
+- Opt-in via `static logging` property on LiveComponent subclasses
+- 6 categories: `lifecycle`, `messages`, `state`, `performance`, `rooms`, `websocket`
+- Global (non-component) logs controlled by `LIVE_LOGGING` env var
+- `console.error` always visible regardless of config
+
+## Usage
+
+### Enable Logging on a Component
+
+```typescript
+// app/server/live/LiveCounter.ts
+export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
+  static componentName = 'LiveCounter'
+
+  // ✅ All categories
+  static logging = true
+
+  // ✅ Specific categories only
+  static logging = ['lifecycle', 'messages', 'state', 'rooms'] as const
+
+  // ✅ Silent (default — omit property or set false)
+  // static logging = false
+}
+```
+
+### Global Logs (Non-Component)
+
+Logs not tied to a specific component (room cleanup, key rotation, etc.) are controlled by the `LIVE_LOGGING` env var:
+
+```bash
+# .env
+LIVE_LOGGING=true                  # All global logs
+LIVE_LOGGING=lifecycle,rooms       # Specific categories only
+# (unset or 'false')              # Silent (default)
+```
+
+## Categories
+
+| Category | What It Logs |
+|----------|-------------|
+| `lifecycle` | Mount, unmount, rehydration, recovery, migration |
+| `messages` | Received/sent WebSocket messages, file uploads |
+| `state` | Signing, backup, compression, encryption, validation |
+| `performance` | Monitoring init, alerts, optimization suggestions |
+| `rooms` | Room create/join/leave, emit, broadcast |
+| `websocket` | Connection open/close, auth |
+
+## Type Definition
+
+```typescript
+type LiveLogCategory = 'lifecycle' | 'messages' | 'state' | 'performance' | 'rooms' | 'websocket'
+
+type LiveLogConfig = boolean | readonly LiveLogCategory[]
+```
+
+Use `as const` on arrays to get readonly tuple type:
+
+```typescript
+// ✅ Works with as const
+static logging = ['lifecycle', 'messages'] as const
+```
+
+## API (Framework Internal)
+
+These functions are used by the framework — app developers only need `static logging`:
+
+```typescript
+import { liveLog, liveWarn, registerComponentLogging, unregisterComponentLogging } from '@core/server/live'
+
+// Log gated by component config
+liveLog('lifecycle', componentId, '🚀 Mounted component')
+liveLog('rooms', componentId, `📡 Joined room '${roomId}'`)
+
+// Warn-level (for perf alerts, non-error warnings)
+liveWarn('performance', componentId, '⚠️ Slow render detected')
+
+// Register/unregister (called on mount/unmount by ComponentRegistry)
+registerComponentLogging(componentId, config)
+unregisterComponentLogging(componentId)
+```
+
+## How It Works
+
+1. **Mount**: `ComponentRegistry` reads `static logging` from the class and calls `registerComponentLogging(componentId, config)`
+2. **Runtime**: All `liveLog()`/`liveWarn()` calls check the registry before emitting
+3. **Unmount**: `unregisterComponentLogging(componentId)` removes the entry
+4. **Global logs**: Fall back to `LIVE_LOGGING` env var when `componentId` is `null`
+
+## Examples
+
+### Debug a Specific Component
+
+```typescript
+// Only this component will show logs
+export class LiveChat extends LiveComponent<typeof LiveChat.defaultState> {
+  static componentName = 'LiveChat'
+  static logging = true  // See everything for this component
+}
+
+// All other components remain silent
+export class LiveCounter extends LiveComponent<typeof LiveCounter.defaultState> {
+  static componentName = 'LiveCounter'
+  // No static logging → silent
+}
+```
+
+### Monitor Only Room Activity
+
+```typescript
+export class LiveChat extends LiveComponent<typeof LiveChat.defaultState> {
+  static componentName = 'LiveChat'
+  static logging = ['rooms'] as const  // Only room events
+}
+```
+
+### Production: Silent Everywhere
+
+```bash
+# .env (no LIVE_LOGGING set)
+# All components without static logging → silent
+# Components with static logging still log (remove for production)
+```
+
+## Files Reference
+
+| File | Purpose |
+|------|---------|
+| `core/server/live/LiveLogger.ts` | Logger implementation, registry, shouldLog logic |
+| `core/server/live/ComponentRegistry.ts` | Reads `static logging` on mount/unmount |
+| `core/server/live/websocket-plugin.ts` | Uses `liveLog` for WebSocket events |
+| `core/server/live/StateSignature.ts` | Uses `liveLog`/`liveWarn` for state operations |
+| `core/server/live/LiveRoomManager.ts` | Uses `liveLog` for room lifecycle |
+| `core/server/live/LiveComponentPerformanceMonitor.ts` | Uses `liveLog`/`liveWarn` for perf |
+| `core/types/types.ts` | `LiveComponent` base class with `static logging` property |
+
+## Critical Rules
+
+**ALWAYS:**
+- Use `as const` on logging arrays for type safety
+- Keep components silent by default in production
+- Use specific categories instead of `true` when possible
+
+**NEVER:**
+- Use `console.log` directly in Live Component code — use `liveLog()`
+- Forget that `console.error` is always visible (not gated)
+
+## Related
+
+- [Live Components](./live-components.md) - Base component system
+- [Live Rooms](./live-rooms.md) - Room system (logged under `rooms` category)
+- [Environment Variables](../config/environment-vars.md) - `LIVE_LOGGING` reference

package/LLMD/resources/live-upload.md

@@ -1,6 +1,6 @@
 # Live Upload (Chunked Upload via WebSocket)
 
-**Version:** 1.11.0 | **Updated:** 2026-02-08
+**Version:** 1.11.0 | **Updated:** 2025-02-08
 
 ## Overview
 

package/LLMD/resources/rest-auth.md

@@ -0,0 +1,290 @@
+# REST API Authentication
+
+**Version:** 1.14.0 | **Updated:** 2026-02-14
+
+## Quick Facts
+
+- Dois guards disponíveis: **Session** (cookie) e **Token** (Bearer)
+- Configuração via `AUTH_DEFAULT_GUARD` no `.env`
+- Rate limiting automático no login (5 tentativas / 60s)
+- Password hashing com bcrypt ou argon2id
+- Provider in-memory por padrão (extensível para database)
+- REST test files disponíveis em `rest-tests/`
+
+## Endpoints
+
+| Método | Rota | Auth | Descrição |
+|--------|------|------|-----------|
+| `POST` | `/api/auth/register` | Guest | Criar conta e auto-login |
+| `POST` | `/api/auth/login` | Guest | Autenticar com email + password |
+| `GET` | `/api/auth/me` | Required | Retorna usuário autenticado |
+| `POST` | `/api/auth/logout` | Required | Encerrar sessão/revogar token |
+
+## Guards
+
+### Session Guard (padrão)
+
+Armazena sessão no servidor e envia cookie httpOnly ao cliente.
+
+```
+Login → Servidor cria sessão → Cookie `fluxstack_session` → Browser envia automaticamente
+```
+
+**Configuração** (`.env`):
+```bash
+AUTH_DEFAULT_GUARD=session
+SESSION_COOKIE=fluxstack_session
+SESSION_LIFETIME=7200        # 2 horas
+SESSION_HTTP_ONLY=true
+SESSION_SECURE=false          # true em produção
+SESSION_SAME_SITE=lax
+```
+
+**Response do login** (sem campo token):
+```json
+{
+  "success": true,
+  "user": {
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com",
+    "createdAt": "2026-02-14T16:00:00.000Z"
+  }
+}
+```
+
+**Requests autenticados**: cookie enviado automaticamente pelo browser.
+
+### Token Guard (Bearer)
+
+Gera token aleatório de 32 bytes, armazena hash SHA256 no cache e retorna o token plain ao cliente.
+
+```
+Login → Token gerado → Response inclui token → Cliente envia Authorization: Bearer <token>
+```
+
+**Configuração** (`.env`):
+```bash
+AUTH_DEFAULT_GUARD=token
+AUTH_TOKEN_TTL=86400          # 24 horas
+```
+
+**Response do login** (com campo token):
+```json
+{
+  "success": true,
+  "user": {
+    "id": 1,
+    "name": "John Doe",
+    "email": "john@example.com",
+    "createdAt": "2026-02-14T16:00:00.000Z"
+  },
+  "token": "a1b2c3d4e5f6..."
+}
+```
+
+**Requests autenticados**:
+```
+Authorization: Bearer a1b2c3d4e5f6...
+```
+
+### Quando usar cada guard
+
+| Guard | Melhor para |
+|-------|-------------|
+| Session | SPAs web (same-origin), SSR |
+| Token | Mobile apps, CLIs, API clients, integrações |
+
+## Fluxos
+
+### Register + Auto-login
+
+```bash
+POST /api/auth/register
+Content-Type: application/json
+
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "password": "secret123"
+}
+
+# 201 Created
+# Session guard: set-cookie header
+# Token guard: token no body (via login automático)
+```
+
+### Login
+
+```bash
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "email": "john@example.com",
+  "password": "secret123"
+}
+
+# 200 OK → user + token (se token guard)
+# 401    → credenciais inválidas
+# 429    → rate limit (Retry-After header)
+```
+
+### Me (Token Guard)
+
+```bash
+GET /api/auth/me
+Authorization: Bearer <token>
+
+# 200 OK → { success: true, user: {...} }
+# 401    → não autenticado
+```
+
+### Logout (Token Guard)
+
+```bash
+POST /api/auth/logout
+Authorization: Bearer <token>
+
+# 200 OK → token revogado no cache
+```
+
+## Rate Limiting
+
+Login é protegido automaticamente contra brute force:
+
+| Config | Default | Env Var |
+|--------|---------|---------|
+| Max tentativas | 5 | `AUTH_RATE_LIMIT_MAX_ATTEMPTS` |
+| Janela (segundos) | 60 | `AUTH_RATE_LIMIT_DECAY_SECONDS` |
+
+Chave de throttle: `email|ip`. Após exceder, retorna `429 Too Many Attempts` com header `Retry-After`.
+
+## Password Hashing
+
+| Config | Default | Env Var |
+|--------|---------|---------|
+| Algoritmo | bcrypt | `AUTH_HASH_ALGORITHM` |
+| Rounds (bcrypt) | 10 | `AUTH_BCRYPT_ROUNDS` |
+
+Opções: `bcrypt` ou `argon2id`.
+
+## Middleware
+
+Três níveis de proteção disponíveis para rotas customizadas:
+
+```typescript
+import { auth, guest, authOptional } from '@server/auth'
+
+// Requer autenticação (401 se não autenticado)
+app.use(auth()).get('/protected', ({ user }) => user.toJSON())
+
+// Requer NÃO estar autenticado (409 se já logado)
+app.use(guest()).post('/login', loginHandler)
+
+// Auth opcional (não bloqueia, injeta user ou null)
+app.use(authOptional()).get('/public', ({ user }) => ({ user }))
+```
+
+## Schemas TypeBox
+
+As rotas definem schemas para validação e Swagger:
+
+```typescript
+// Body do register
+RegisterBodySchema = t.Object({
+  name: t.String({ minLength: 1 }),
+  email: t.String({ format: 'email' }),
+  password: t.String({ minLength: 6 }),
+})
+
+// Body do login
+LoginBodySchema = t.Object({
+  email: t.String({ format: 'email' }),
+  password: t.String({ minLength: 1 }),
+})
+
+// Response do login (token guard)
+LoginResponseSchema = t.Object({
+  success: t.Literal(true),
+  user: t.Object({
+    id: t.Union([t.String(), t.Number()]),
+    name: t.Optional(t.String()),
+    email: t.Optional(t.String()),
+    createdAt: t.Optional(t.String()),
+  }),
+  token: t.Optional(t.String()),
+})
+```
+
+## REST Test Files
+
+Arquivos `.http` prontos para testar com a extensão REST Client do VSCode:
+
+| Arquivo | Guard | Cobertura |
+|---------|-------|-----------|
+| `rest-tests/auth.http` | Session (cookie) | Register, Login, Me, Logout |
+| `rest-tests/auth-token.http` | Token (Bearer) | Register, Login, Me, Logout + erros |
+| `rest-tests/users-token.http` | Token (Bearer) | CRUD de usuários autenticado |
+| `rest-tests/rooms-token.http` | Token (Bearer) | Mensagens e eventos em salas |
+
+### Uso rápido
+
+1. Configure `AUTH_DEFAULT_GUARD=token` no `.env`
+2. `bun run dev`
+3. Abra `rest-tests/auth-token.http` no VSCode
+4. Execute **Register** → **Login** (captura token) → **Me** / **Logout**
+
+> O token é capturado automaticamente via `@name login` e injetado com `{{login.response.body.token}}`.
+
+## Configuração Completa
+
+| Variável | Tipo | Default | Descrição |
+|----------|------|---------|-----------|
+| `AUTH_DEFAULT_GUARD` | enum | `session` | Guard padrão: `session` ou `token` |
+| `AUTH_DEFAULT_PROVIDER` | enum | `memory` | Provider: `memory` ou `database` |
+| `AUTH_HASH_ALGORITHM` | enum | `bcrypt` | Hash: `bcrypt` ou `argon2id` |
+| `AUTH_BCRYPT_ROUNDS` | number | `10` | Rounds do bcrypt |
+| `AUTH_RATE_LIMIT_MAX_ATTEMPTS` | number | `5` | Max tentativas de login |
+| `AUTH_RATE_LIMIT_DECAY_SECONDS` | number | `60` | Janela do rate limit |
+| `AUTH_TOKEN_TTL` | number | `86400` | TTL do token (segundos) |
+| `SESSION_COOKIE` | string | `fluxstack_session` | Nome do cookie |
+| `SESSION_LIFETIME` | number | `7200` | Duração da sessão (segundos) |
+| `SESSION_HTTP_ONLY` | boolean | `true` | Cookie httpOnly |
+| `SESSION_SECURE` | boolean | `false` | Cookie secure (HTTPS) |
+| `SESSION_SAME_SITE` | enum | `lax` | SameSite policy |
+
+## Arquivos de Referência
+
+| Arquivo | Conteúdo |
+|---------|----------|
+| `app/server/routes/auth.routes.ts` | Endpoints de autenticação |
+| `app/server/auth/middleware.ts` | Middleware `auth()`, `guest()`, `authOptional()` |
+| `app/server/auth/guards/SessionGuard.ts` | Lógica do session guard |
+| `app/server/auth/guards/TokenGuard.ts` | Lógica do token guard |
+| `app/server/auth/AuthManager.ts` | Factory de guards e providers |
+| `app/server/auth/providers/InMemoryProvider.ts` | Provider in-memory |
+| `app/server/auth/RateLimiter.ts` | Rate limiting de login |
+| `config/system/auth.config.ts` | Schema de configuração auth |
+| `config/system/session.config.ts` | Schema de configuração session |
+
+## Critical Rules
+
+**ALWAYS:**
+- Usar `AUTH_DEFAULT_GUARD=token` para APIs stateless
+- Enviar `Authorization: Bearer <token>` em todos os requests autenticados
+- Tratar `401` e `429` no frontend
+- Armazenar token com segurança no cliente (httpOnly cookie ou secure storage)
+
+**NEVER:**
+- Expor token em URLs (query params)
+- Armazenar token em localStorage sem necessidade (preferir httpOnly cookie)
+- Ignorar rate limiting responses (`429`)
+- Enviar passwords sem HTTPS em produção
+
+## Related
+
+- [Live Auth](./live-auth.md) - Autenticação para Live Components (WebSocket)
+- [Routes with Eden Treaty](./routes-eden.md) - Criação de rotas type-safe
+- [Environment Variables](../config/environment-vars.md) - Referência de variáveis
+- [Troubleshooting](../reference/troubleshooting.md) - Problemas comuns