create-fluxstack 1.12.0 → 1.13.0

package/app/server/auth/contracts.ts

@@ -0,0 +1,192 @@
+/**
+ * FluxStack Auth System - Contracts
+ *
+ * Inspirado no Laravel: Guard + Provider + Authenticatable.
+ * - Guard: COMO autenticar (session, token, JWT...)
+ * - UserProvider: ONDE buscar os usuários (memória, banco, API...)
+ * - Authenticatable: O QUE é um usuário autenticável
+ *
+ * Adaptado para API-only (sem HTML, sem redirects, sem CSRF).
+ */
+
+// ===== Authenticatable =====
+
+/**
+ * Interface que define o que é um "usuário autenticável".
+ * Qualquer model/entidade que implemente isso pode ser usada com o auth system.
+ *
+ * Para usar com seu ORM:
+ * ```ts
+ * class User implements Authenticatable {
+ *   getAuthId() { return this.id }
+ *   getAuthPassword() { return this.passwordHash }
+ *   // ...
+ * }
+ * ```
+ */
+export interface Authenticatable {
+  /** Retorna o identificador único (ex: id, uuid) */
+  getAuthId(): string | number
+
+  /** Retorna o nome do campo identificador (ex: 'id') */
+  getAuthIdField(): string
+
+  /** Retorna o hash da password armazenada */
+  getAuthPassword(): string
+
+  /** Retorna o token de "remember me" (ou null) */
+  getRememberToken(): string | null
+
+  /** Define o token de "remember me" */
+  setRememberToken(token: string | null): void
+
+  /** Retorna dados serializáveis do usuário (para response da API) */
+  toJSON(): Record<string, unknown>
+}
+
+// ===== UserProvider =====
+
+/**
+ * Interface para buscar e validar usuários.
+ * O provider NÃO sabe como autenticar - apenas onde os dados estão.
+ *
+ * Para implementar com banco de dados:
+ * ```ts
+ * class DrizzleUserProvider implements UserProvider {
+ *   async retrieveById(id) { return db.select().from(users).where(eq(users.id, id)) }
+ *   async retrieveByCredentials({ email }) { return db.select().from(users).where(eq(users.email, email)) }
+ *   async validateCredentials(user, { password }) { return Hash.check(password, user.getAuthPassword()) }
+ * }
+ * ```
+ */
+export interface UserProvider {
+  /** Busca usuário pelo ID */
+  retrieveById(id: string | number): Promise<Authenticatable | null>
+
+  /**
+   * Busca usuário pelas credenciais (SEM a password).
+   * Ex: { email: "user@example.com" } → busca por email.
+   * A password é validada separadamente em validateCredentials().
+   */
+  retrieveByCredentials(credentials: Record<string, unknown>): Promise<Authenticatable | null>
+
+  /**
+   * Valida a password contra o hash do usuário.
+   * Recebe o user já encontrado + as credenciais originais (com password).
+   */
+  validateCredentials(user: Authenticatable, credentials: Record<string, unknown>): Promise<boolean>
+
+  /** Busca usuário pelo remember token */
+  retrieveByToken(id: string | number, token: string): Promise<Authenticatable | null>
+
+  /** Atualiza o remember token do usuário */
+  updateRememberToken(user: Authenticatable, token: string | null): Promise<void>
+
+  /** Cria um novo usuário (para registro) */
+  createUser(data: Record<string, unknown>): Promise<Authenticatable>
+}
+
+// ===== Guard =====
+
+/**
+ * Interface do guard de autenticação.
+ * O guard sabe COMO autenticar (session cookie, bearer token, etc).
+ *
+ * Para criar um guard customizado:
+ * ```ts
+ * class JWTGuard implements Guard {
+ *   async user() { /* decode JWT from header *\/ }
+ *   async attempt(creds) { /* validate + generate JWT *\/ }
+ * }
+ * authManager.extend('jwt', (config) => new JWTGuard(config))
+ * ```
+ */
+export interface Guard {
+  /** Nome do guard */
+  readonly name: string
+
+  /** Retorna o usuário autenticado ou null */
+  user(): Promise<Authenticatable | null>
+
+  /** Retorna o ID do usuário autenticado ou null */
+  id(): Promise<string | number | null>
+
+  /** Verifica se há um usuário autenticado */
+  check(): Promise<boolean>
+
+  /** Verifica se NÃO há usuário autenticado */
+  guest(): Promise<boolean>
+
+  /**
+   * Tenta autenticar com credenciais.
+   * Retorna o usuário se sucesso, null se falha.
+   */
+  attempt(credentials: Record<string, unknown>, remember?: boolean): Promise<Authenticatable | null>
+
+  /** Autentica um usuário diretamente (sem validar credenciais) */
+  login(user: Authenticatable, remember?: boolean): Promise<void>
+
+  /** Desloga o usuário atual */
+  logout(): Promise<void>
+
+  /**
+   * Valida credenciais SEM efetuar login.
+   * Útil para confirmar password antes de ações sensíveis.
+   */
+  validate(credentials: Record<string, unknown>): Promise<boolean>
+
+  /**
+   * Inicializa o guard com o contexto da request atual.
+   * Chamado pelo middleware antes de qualquer operação.
+   */
+  setRequest(context: RequestContext): void
+}
+
+// ===== Request Context =====
+
+/**
+ * Contexto da request disponível para os guards.
+ * Abstrai o acesso a headers, cookies, etc.
+ */
+export interface RequestContext {
+  /** Headers da request */
+  headers: Record<string, string | undefined>
+
+  /** Cookies da request */
+  cookie: Record<string, { value: string; set: (opts: CookieOptions) => void } | undefined>
+
+  /** Setter para cookies na response */
+  setCookie: (name: string, value: string, options?: CookieOptions) => void
+
+  /** Remove um cookie */
+  removeCookie: (name: string) => void
+
+  /** IP da request (para rate limiting) */
+  ip: string
+}
+
+/** Opções para cookies */
+export interface CookieOptions {
+  maxAge?: number
+  httpOnly?: boolean
+  secure?: boolean
+  sameSite?: 'strict' | 'lax' | 'none'
+  path?: string
+  domain?: string
+}
+
+// ===== Guard Factory =====
+
+/** Config de um guard individual */
+export interface GuardConfig {
+  driver: string
+  provider: string
+  [key: string]: unknown
+}
+
+/** Factory function para criar guards customizados */
+export type GuardFactory = (
+  name: string,
+  config: GuardConfig,
+  provider: UserProvider
+) => Guard

package/app/server/auth/guards/SessionGuard.ts

@@ -0,0 +1,167 @@
+/**
+ * FluxStack Auth - Session Guard
+ *
+ * Guard baseado em session cookie. Padrão para SPAs que se comunicam
+ * com a API via fetch/axios (mesma origem ou CORS com credentials).
+ *
+ * Fluxo:
+ * 1. POST /login → attempt() → valida credenciais → cria sessão → seta cookie
+ * 2. Requests seguintes → cookie enviado automaticamente → user() resolve da sessão
+ * 3. POST /logout → logout() → destroi sessão → remove cookie
+ */
+
+import type {
+  Guard,
+  Authenticatable,
+  UserProvider,
+  RequestContext,
+} from '../contracts'
+import type { SessionManager } from '../sessions/SessionManager'
+
+export class SessionGuard implements Guard {
+  readonly name: string
+  private provider: UserProvider
+  private sessions: SessionManager
+  private request: RequestContext | null = null
+
+  /** Cache do usuário para a request atual (evita múltiplas queries) */
+  private resolvedUser: Authenticatable | null | undefined = undefined
+
+  constructor(name: string, provider: UserProvider, sessions: SessionManager) {
+    this.name = name
+    this.provider = provider
+    this.sessions = sessions
+  }
+
+  setRequest(context: RequestContext): void {
+    this.request = context
+    // Reset cache para nova request
+    this.resolvedUser = undefined
+  }
+
+  async user(): Promise<Authenticatable | null> {
+    // Cache per-request
+    if (this.resolvedUser !== undefined) {
+      return this.resolvedUser
+    }
+
+    this.resolvedUser = null
+
+    if (!this.request) return null
+
+    // 1. Ler session ID do cookie
+    const sessionId = this.getSessionId()
+    if (!sessionId) return null
+
+    // 2. Buscar dados da sessão
+    const sessionData = await this.sessions.read(sessionId)
+    if (!sessionData?.userId) return null
+
+    // 3. Buscar usuário pelo ID
+    const user = await this.provider.retrieveById(sessionData.userId as string | number)
+    if (user) {
+      this.resolvedUser = user
+    }
+
+    return this.resolvedUser
+  }
+
+  async id(): Promise<string | number | null> {
+    const user = await this.user()
+    return user?.getAuthId() ?? null
+  }
+
+  async check(): Promise<boolean> {
+    return (await this.user()) !== null
+  }
+
+  async guest(): Promise<boolean> {
+    return (await this.user()) === null
+  }
+
+  async attempt(
+    credentials: Record<string, unknown>,
+    _remember?: boolean
+  ): Promise<Authenticatable | null> {
+    // 1. Buscar usuário pelas credenciais (SEM password)
+    const user = await this.provider.retrieveByCredentials(credentials)
+    if (!user) return null
+
+    // 2. Validar password
+    const valid = await this.provider.validateCredentials(user, credentials)
+    if (!valid) return null
+
+    // 3. Login
+    await this.login(user)
+
+    return user
+  }
+
+  async login(user: Authenticatable, _remember?: boolean): Promise<void> {
+    if (!this.request) {
+      throw new Error('SessionGuard: request context not set. Call setRequest() first.')
+    }
+
+    const config = this.sessions.getConfig()
+
+    // 1. Regenerar sessão (ou criar nova) para prevenir session fixation
+    const existingSessionId = this.getSessionId()
+    let sessionId: string
+
+    if (existingSessionId) {
+      sessionId = await this.sessions.regenerate(existingSessionId)
+    } else {
+      sessionId = await this.sessions.create({})
+    }
+
+    // 2. Salvar userId na sessão
+    await this.sessions.put(sessionId, 'userId', user.getAuthId())
+    await this.sessions.put(sessionId, '_loginAt', Date.now())
+
+    // 3. Setar cookie
+    this.request.setCookie(config.cookieName, sessionId, {
+      maxAge: config.lifetime,
+      httpOnly: config.httpOnly,
+      secure: config.secure,
+      sameSite: config.sameSite,
+      path: config.path,
+      domain: config.domain,
+    })
+
+    // 4. Cache do usuário para esta request
+    this.resolvedUser = user
+  }
+
+  async logout(): Promise<void> {
+    if (!this.request) return
+
+    const config = this.sessions.getConfig()
+    const sessionId = this.getSessionId()
+
+    // 1. Destroir sessão
+    if (sessionId) {
+      await this.sessions.destroy(sessionId)
+    }
+
+    // 2. Remover cookie
+    this.request.removeCookie(config.cookieName)
+
+    // 3. Limpar cache
+    this.resolvedUser = null
+  }
+
+  async validate(credentials: Record<string, unknown>): Promise<boolean> {
+    const user = await this.provider.retrieveByCredentials(credentials)
+    if (!user) return false
+    return this.provider.validateCredentials(user, credentials)
+  }
+
+  /** Lê o session ID do cookie */
+  private getSessionId(): string | null {
+    if (!this.request) return null
+
+    const config = this.sessions.getConfig()
+    const cookie = this.request.cookie[config.cookieName]
+    return cookie?.value || null
+  }
+}

package/app/server/auth/guards/TokenGuard.ts

@@ -0,0 +1,202 @@
+/**
+ * FluxStack Auth - Token Guard
+ *
+ * Guard baseado em Bearer token (header Authorization).
+ * Para APIs consumidas por mobile apps, CLIs, integrações.
+ *
+ * Fluxo:
+ * 1. Client envia: Authorization: Bearer <token>
+ * 2. Guard busca user pelo token no provider
+ * 3. Se válido, user está autenticado
+ *
+ * Tokens são armazenados no cache com referência ao userId.
+ */
+
+import type {
+  Guard,
+  Authenticatable,
+  UserProvider,
+  RequestContext,
+} from '../contracts'
+import type { CacheDriver } from '@server/cache/contracts'
+
+interface StoredToken {
+  userId: string | number
+  createdAt: number
+  expiresAt: number | null
+}
+
+export class TokenGuard implements Guard {
+  readonly name: string
+  private provider: UserProvider
+  private cache: CacheDriver
+  private request: RequestContext | null = null
+  private tokenTtl: number
+
+  /** Cache do usuário para a request atual */
+  private resolvedUser: Authenticatable | null | undefined = undefined
+
+  constructor(
+    name: string,
+    provider: UserProvider,
+    cache: CacheDriver,
+    tokenTtlSeconds: number = 86400 // 24h default
+  ) {
+    this.name = name
+    this.provider = provider
+    this.cache = cache
+    this.tokenTtl = tokenTtlSeconds
+  }
+
+  setRequest(context: RequestContext): void {
+    this.request = context
+    this.resolvedUser = undefined
+  }
+
+  async user(): Promise<Authenticatable | null> {
+    if (this.resolvedUser !== undefined) {
+      return this.resolvedUser
+    }
+
+    this.resolvedUser = null
+
+    if (!this.request) return null
+
+    // 1. Extrair token do header Authorization
+    const token = this.getBearerToken()
+    if (!token) return null
+
+    // 2. Buscar token no cache
+    const tokenData = await this.cache.get<StoredToken>(`auth_token:${this.hashToken(token)}`)
+    if (!tokenData) return null
+
+    // 3. Verificar expiração
+    if (tokenData.expiresAt && Date.now() > tokenData.expiresAt) {
+      await this.cache.delete(`auth_token:${this.hashToken(token)}`)
+      return null
+    }
+
+    // 4. Buscar usuário
+    const user = await this.provider.retrieveById(tokenData.userId)
+    if (user) {
+      this.resolvedUser = user
+    }
+
+    return this.resolvedUser
+  }
+
+  async id(): Promise<string | number | null> {
+    const user = await this.user()
+    return user?.getAuthId() ?? null
+  }
+
+  async check(): Promise<boolean> {
+    return (await this.user()) !== null
+  }
+
+  async guest(): Promise<boolean> {
+    return (await this.user()) === null
+  }
+
+  async attempt(credentials: Record<string, unknown>): Promise<Authenticatable | null> {
+    // 1. Buscar user
+    const user = await this.provider.retrieveByCredentials(credentials)
+    if (!user) return null
+
+    // 2. Validar password
+    const valid = await this.provider.validateCredentials(user, credentials)
+    if (!valid) return null
+
+    // 3. Gerar e armazenar token
+    await this.login(user)
+
+    return user
+  }
+
+  async login(user: Authenticatable): Promise<void> {
+    // Gerar token
+    const token = this.generateToken()
+    const hashedToken = this.hashToken(token)
+
+    // Armazenar no cache
+    const tokenData: StoredToken = {
+      userId: user.getAuthId(),
+      createdAt: Date.now(),
+      expiresAt: this.tokenTtl > 0 ? Date.now() + (this.tokenTtl * 1000) : null,
+    }
+    await this.cache.set(`auth_token:${hashedToken}`, tokenData, this.tokenTtl || undefined)
+
+    // Armazenar lista de tokens do user (para revogação em massa)
+    const userTokensKey = `user_tokens:${user.getAuthId()}`
+    const existingTokens = await this.cache.get<string[]>(userTokensKey) ?? []
+    existingTokens.push(hashedToken)
+    await this.cache.set(userTokensKey, existingTokens)
+
+    // Cache do user
+    this.resolvedUser = user
+
+    // Salvar token plain-text temporariamente para a response poder retorná-lo
+    ;(this as any)._lastGeneratedToken = token
+  }
+
+  async logout(): Promise<void> {
+    if (!this.request) return
+
+    const token = this.getBearerToken()
+    if (token) {
+      await this.cache.delete(`auth_token:${this.hashToken(token)}`)
+    }
+
+    this.resolvedUser = null
+  }
+
+  async validate(credentials: Record<string, unknown>): Promise<boolean> {
+    const user = await this.provider.retrieveByCredentials(credentials)
+    if (!user) return false
+    return this.provider.validateCredentials(user, credentials)
+  }
+
+  /**
+   * Revoga todos os tokens de um usuário.
+   */
+  async revokeAllTokens(userId: string | number): Promise<void> {
+    const userTokensKey = `user_tokens:${userId}`
+    const tokens = await this.cache.get<string[]>(userTokensKey) ?? []
+
+    for (const hashedToken of tokens) {
+      await this.cache.delete(`auth_token:${hashedToken}`)
+    }
+    await this.cache.delete(userTokensKey)
+  }
+
+  /** Retorna o último token gerado (para a response após login) */
+  getLastGeneratedToken(): string | null {
+    return (this as any)._lastGeneratedToken ?? null
+  }
+
+  /** Extrai Bearer token do header Authorization */
+  private getBearerToken(): string | null {
+    if (!this.request) return null
+
+    const authHeader = this.request.headers['authorization'] ?? this.request.headers['Authorization']
+    if (!authHeader?.startsWith('Bearer ')) return null
+
+    return authHeader.slice(7)
+  }
+
+  /** Gera um token criptograficamente seguro */
+  private generateToken(): string {
+    const bytes = new Uint8Array(32)
+    crypto.getRandomValues(bytes)
+    return Array.from(bytes)
+      .map(b => b.toString(16).padStart(2, '0'))
+      .join('')
+  }
+
+  /** Hash do token para armazenamento (nunca guardar plain-text) */
+  private hashToken(token: string): string {
+    const hasher = new Bun.CryptoHasher('sha256')
+    hasher.update(token)
+    return hasher.digest('hex')
+  }
+}