@softize/opus 8.6.6

package/src/audit/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @softize/opus/audit — shared helpers/types for audit drivers.
+ *
+ * Drivers (console, pg) são thin wrappers que implementam AuditSink.
+ * Código compartilhado entre drivers mora aqui — hoje, o redator
+ * recursivo (`redactDeep`) e a aplicação dele num record (`redactRecord`).
+ */
+
+import type { AuditRecord } from '../core/index.ts'
+
+/** Chaves sensíveis por convenção — o default do `redactDeep`. */
+export const SENSITIVE_KEY_PATTERN = /password|passwd|secret|token|authorization|api[-_]?key|credential/i
+
+/**
+ * Redator RECURSIVO por nome de chave: em qualquer profundidade (objetos e
+ * arrays), valor cuja CHAVE casa o padrão vira '[REDACTED]'. É o complemento do
+ * `AuditConfig.redact` por action (dot-paths estáticos): aqui a cobertura é
+ * global — `user.create`/`setPassword` não grava senha em claro por esquecimento.
+ * Não muta o original; objetos não-planos (Date, Map, class) passam intactos.
+ */
+export function redactDeep(value: unknown, keyPattern: RegExp = SENSITIVE_KEY_PATTERN): unknown {
+  const seen = new WeakSet<object>()
+  const matches = (key: string): boolean => {
+    keyPattern.lastIndex = 0 // padrão /g do chamador não pode ficar stateful
+    return keyPattern.test(key)
+  }
+  const walk = (v: unknown): unknown => {
+    if (v === null || typeof v !== 'object') return v
+    if (seen.has(v)) return '[CIRCULAR]'
+    seen.add(v)
+    if (Array.isArray(v)) return v.map(walk)
+    const proto: unknown = Object.getPrototypeOf(v)
+    if (proto !== Object.prototype && proto !== null) return v
+    const out: Record<string, unknown> = {}
+    for (const [k, val] of Object.entries(v)) {
+      out[k] = matches(k) ? '[REDACTED]' : walk(val)
+    }
+    return out
+  }
+  return walk(value)
+}
+
+/** Aplica um redator a input/output de um record (o que os drivers persistem). */
+export function redactRecord(
+  record: AuditRecord,
+  redact: (value: unknown) => unknown,
+): AuditRecord {
+  const next: AuditRecord = { ...record, input: redact(record.input) }
+  if (record.output !== undefined) next.output = redact(record.output)
+  return next
+}

package/src/auth/drivers/better-auth.ts

@@ -0,0 +1,103 @@
+/**
+ * @softize/opus/auth/better-auth — driver de sessão do better-auth (lado consumidor)
+ *
+ * Valida a sessão de um IdP (better-auth) encaminhando o cookie da request pro
+ * `${baseURL}/api/auth/get-session`. O IdP é a fonte da verdade — este adapter não
+ * guarda segredo: os apps confiam no IdP.
+ *
+ * Uso:
+ *   import { betterAuthSession } from '@softize/opus/auth/better-auth'
+ *
+ *   const auth = betterAuthSession({
+ *     baseURL: process.env.AUTH_IDP_URL!,            // https://auth.example.com
+ *     can: (user) => (perm) => user.staff === true,  // staff-only
+ *   })
+ */
+
+import type { AuthAdapter, CanFn, User } from '../../core/index.ts'
+
+export interface BetterAuthSession {
+  user:
+    | ({ id: string; email: string; name: string; staff?: boolean } & Record<string, unknown>)
+    | null
+  session?: unknown
+}
+
+export interface BetterAuthDriverOptions {
+  /** Base URL do IdP, ex: `https://auth.example.com`. */
+  baseURL: string
+  /** Mapeia a sessão do IdP → `User` do core. Default espalha `session.user`. */
+  mapUser?: (session: BetterAuthSession) => User
+  /** Mapeia a sessão → tenantId. Default null. */
+  mapTenant?: (session: BetterAuthSession) => string | null
+  /** Constrói o `CanFn`. Default nega tudo (consumer deve plugar). */
+  can?: (user: User, session: BetterAuthSession) => CanFn
+  /** Timeout do fetch ao IdP (ms). Default 5000. */
+  timeoutMs?: number
+  /** Nome do adapter (default 'better-auth'). */
+  name?: string
+}
+
+const denyAll: CanFn = () => false
+
+export function betterAuthSession(options: BetterAuthDriverOptions): AuthAdapter {
+  const { baseURL, mapUser, mapTenant, can, timeoutMs = 5000, name = 'better-auth' } = options
+  const base = baseURL.replace(/\/+$/, '')
+
+  return {
+    name,
+    kind: 'auth',
+    async resolveContext(req) {
+      const headers = forwardHeaders(req)
+      if (headers === null) return { user: null, can: denyAll }
+
+      let session: BetterAuthSession
+      try {
+        const res = await fetch(`${base}/api/auth/get-session`, {
+          headers,
+          signal: AbortSignal.timeout(timeoutMs),
+        })
+        if (!res.ok) return { user: null, can: denyAll }
+        session = (await res.json()) as BetterAuthSession
+      } catch {
+        // IdP fora do ar / timeout → fail-closed (sem user).
+        return { user: null, can: denyAll }
+      }
+
+      if (session === null || session.user === null || session.user === undefined) {
+        return { user: null, can: denyAll }
+      }
+
+      const user = mapUser ? mapUser(session) : ({ ...session.user } as User)
+      const tenantId = mapTenant?.(session) ?? null
+      return { user, tenantId, can: can ? can(user, session) : denyAll }
+    },
+  }
+}
+
+/** Encaminha `cookie` + `authorization` pro IdP — sem eles o get-session não autentica. */
+function forwardHeaders(req: unknown): Record<string, string> | null {
+  if (typeof req !== 'object' || req === null) return null
+  const headers = (req as { headers?: Record<string, string | string[] | undefined> }).headers
+  if (headers === undefined) return null
+  const out: Record<string, string> = {}
+  const cookie = pickHeader(headers, 'cookie')
+  const authorization = pickHeader(headers, 'authorization')
+  if (cookie !== null) out.cookie = cookie
+  if (authorization !== null) out.authorization = authorization
+  return Object.keys(out).length === 0 ? null : out
+}
+
+function pickHeader(
+  headers: Record<string, string | string[] | undefined>,
+  name: string,
+): string | null {
+  const target = name.toLowerCase()
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() !== target) continue
+    const value = headers[key]
+    if (value === undefined) return null
+    return Array.isArray(value) ? (value[0] ?? null) : value
+  }
+  return null
+}

package/src/auth/drivers/jwt.ts

@@ -0,0 +1,188 @@
+/**
+ * @softize/opus/auth/jwt — JWT auth driver
+ *
+ * Implementa `AuthAdapter` extraindo + validando JWT da request. Padrão
+ * comum em backends Node (matchando o que Conversya faz manualmente
+ * em `services/*\/middleware/auth.ts`):
+ *
+ *   1. Extrai token do header `Authorization: Bearer <token>` ou cookie.
+ *   2. Valida assinatura + expiração via `jsonwebtoken`.
+ *   3. Mapeia payload → `User` + `tenantId` via funções fornecidas.
+ *   4. Delega `can()` a um permission engine plugável.
+ *
+ * Não persiste sessão, não revoga token, não emite — esses são concerns
+ * de session store (DB/Redis) que o consumer pluga via `validatePayload`.
+ *
+ * Uso:
+ *   import { jwtAuth } from '@softize/opus/auth/jwt'
+ *
+ *   const auth = jwtAuth({
+ *     secret: process.env.JWT_SECRET!,
+ *     mapUser: (payload) => ({ id: payload.userId, role: payload.role }),
+ *     mapTenant: (payload) => payload.tenantId ?? null,
+ *     can: (user, payload) => (perm) =>
+ *       hasPermission(user.id, perm, payload),
+ *   })
+ */
+
+import jwt, { type JwtPayload, type Algorithm } from 'jsonwebtoken'
+const { verify } = jwt
+import type { AuthAdapter, CanFn, User } from '../../core/index.ts'
+
+// =============================================================================
+// Options
+// =============================================================================
+
+export interface JwtAuthOptions<P extends JwtPayload = JwtPayload> {
+  /** Secret HMAC ou public key. Pode ser string sync ou async resolver. */
+  secret: string | Buffer | ((kid?: string) => Promise<string | Buffer> | string | Buffer)
+
+  /** Algorithms aceitos (default ['HS256']). */
+  algorithms?: Algorithm[]
+
+  /**
+   * Extração customizada de token. Se ausente, busca em:
+   *   1. Header `Authorization: Bearer <token>`
+   *   2. Cookie `cookieName` (default 'auth_token')
+   * Retorna `null` se não encontrar.
+   */
+  tokenExtractor?: (req: unknown) => string | null
+
+  /** Nome do cookie pra extração default. Default 'auth_token'. */
+  cookieName?: string
+
+  /**
+   * Validação custom **após** verify do JWT. Útil pra checar sessão
+   * em DB (Redis cache, blacklist, etc). Retornar false rejeita.
+   */
+  validatePayload?: (payload: P) => boolean | Promise<boolean>
+
+  /** Mapeia JWT payload pro shape `User` do core. */
+  mapUser: (payload: P) => User
+
+  /**
+   * Mapeia JWT payload pra tenantId. Default tenta `payload.tenantId`.
+   */
+  mapTenant?: (payload: P) => string | null
+
+  /**
+   * Constrói o `CanFn` baseado em user + payload. Default retorna
+   * função que sempre nega (consumer **deve** plugar engine de permissões).
+   */
+  can?: (user: User, payload: P) => CanFn
+
+  /** Nome do adapter (default 'jwt'). */
+  name?: string
+}
+
+// =============================================================================
+// Adapter factory
+// =============================================================================
+
+export function jwtAuth<P extends JwtPayload = JwtPayload>(
+  options: JwtAuthOptions<P>,
+): AuthAdapter {
+  const {
+    secret,
+    algorithms = ['HS256'],
+    tokenExtractor,
+    cookieName = 'auth_token',
+    validatePayload,
+    mapUser,
+    mapTenant,
+    can,
+    name = 'jwt',
+  } = options
+
+  return {
+    name,
+    kind: 'auth',
+
+    async resolveContext(req) {
+      const token =
+        tokenExtractor !== undefined
+          ? tokenExtractor(req)
+          : defaultExtract(req, cookieName)
+
+      if (token === null) {
+        return { user: null, can: denyAll }
+      }
+
+      const resolvedSecret =
+        typeof secret === 'function' ? await secret() : secret
+
+      let payload: P
+      try {
+        payload = verify(token, resolvedSecret, { algorithms }) as P
+      } catch {
+        return { user: null, can: denyAll }
+      }
+
+      if (validatePayload !== undefined) {
+        const valid = await validatePayload(payload)
+        if (!valid) return { user: null, can: denyAll }
+      }
+
+      const user = mapUser(payload)
+      const tenantId = mapTenant?.(payload) ?? null
+      const userCan = can?.(user, payload) ?? denyAll
+
+      return { user, tenantId, can: userCan }
+    },
+  }
+}
+
+// =============================================================================
+// Default token extractor
+// =============================================================================
+
+function defaultExtract(req: unknown, cookieName: string): string | null {
+  if (typeof req !== 'object' || req === null) return null
+
+  const headers = (req as { headers?: Record<string, string | string[] | undefined> })
+    .headers
+
+  // Bearer header
+  const authHeader = pickHeader(headers, 'authorization')
+  if (authHeader !== null && authHeader.toLowerCase().startsWith('bearer ')) {
+    return authHeader.slice('Bearer '.length).trim() || null
+  }
+
+  // Cookie
+  const cookieHeader = pickHeader(headers, 'cookie')
+  if (cookieHeader !== null) {
+    const fromCookie = parseCookie(cookieHeader, cookieName)
+    if (fromCookie !== null) return fromCookie
+  }
+
+  return null
+}
+
+function pickHeader(
+  headers: Record<string, string | string[] | undefined> | undefined,
+  name: string,
+): string | null {
+  if (headers === undefined) return null
+  const target = name.toLowerCase()
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() !== target) continue
+    const value = headers[key]
+    if (value === undefined) return null
+    if (Array.isArray(value)) return value[0] ?? null
+    return value
+  }
+  return null
+}
+
+function parseCookie(header: string, name: string): string | null {
+  const parts = header.split(';')
+  for (const part of parts) {
+    const eq = part.indexOf('=')
+    if (eq < 0) continue
+    const k = part.slice(0, eq).trim()
+    if (k === name) return decodeURIComponent(part.slice(eq + 1).trim())
+  }
+  return null
+}
+
+const denyAll: CanFn = () => false

package/src/auth/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @softize/opus/auth — shared helpers/types for auth drivers.
+ *
+ * Drivers (jwt, futuro: better-auth/clerk/etc) implementam AuthAdapter
+ * do core. Espaço reservado pra helpers comuns (token extractors,
+ * permission engines, etc).
+ */
+
+export {}

package/src/client/drivers/fetch.ts

@@ -0,0 +1,202 @@
+/**
+ * @softize/opus/client/fetch — fetch-based client driver.
+ *
+ * Implementa `ClientAdapter` usando o `fetch` global. Constrói URLs
+ * seguindo a mesma convenção do server adapter (path = name → segments,
+ * method = POST simple/form, GET search/view).
+ *
+ * Uso:
+ *   import { fetchClient } from '@softize/opus/client/fetch'
+ *
+ *   const client = fetchClient({
+ *     baseUrl: 'http://localhost:3001',
+ *     headers: { 'x-user-id': 'u_alice' },
+ *   })
+ *
+ *   const result = await client.run(archiveDeal, { dealId: 'd1' })
+ */
+
+import type {
+  ActionDef,
+  ActionResult,
+  ClientAdapter,
+  ResultMeta,
+} from '../../core/index.ts'
+import { error } from '../../core/index.ts'
+import { inputSourceFor, methodFor, pathFor } from '../index.ts'
+
+// =============================================================================
+// Options
+// =============================================================================
+
+export interface FetchClientOptions {
+  /** URL base do server. Ex: 'http://localhost:3001'. */
+  baseUrl: string
+
+  /** Prefixo do path (espelha apiPrefix do server adapter). Default '/api'. */
+  apiPrefix?: string
+
+  /** Headers fixos enviados em toda request (ex: auth). */
+  headers?: Record<string, string>
+
+  /** Hook pra injetar headers dinâmicos (ex: token rotativo) por request. */
+  beforeRequest?: (init: RequestInit, action: ActionDef) => RequestInit | Promise<RequestInit>
+
+  /** Override do `fetch` global. Útil pra testes ou edge runtimes. */
+  fetch?: typeof globalThis.fetch
+}
+
+// =============================================================================
+// Adapter factory
+// =============================================================================
+
+export function fetchClient(options: FetchClientOptions): ClientAdapter {
+  const {
+    baseUrl,
+    apiPrefix = '/api',
+    headers: baseHeaders = {},
+    beforeRequest,
+    fetch: fetchImpl = globalThis.fetch,
+  } = options
+
+  return {
+    name: 'fetch',
+    kind: 'client',
+
+    async run<T>(action: ActionDef, input: unknown): Promise<ActionResult<T>> {
+      const method = methodFor(action)
+      const source = inputSourceFor(action)
+      const path = pathFor(action, apiPrefix)
+      const url = buildUrl(baseUrl, path, source === 'query' ? input : undefined)
+
+      let init: RequestInit = {
+        method,
+        headers: {
+          'content-type': 'application/json',
+          accept: 'application/json',
+          ...baseHeaders,
+        },
+      }
+      if (source === 'body') init.body = JSON.stringify(input ?? {})
+
+      if (beforeRequest !== undefined) {
+        init = await beforeRequest(init, action)
+      }
+
+      let response: Response
+      try {
+        response = await fetchImpl(url, init)
+      } catch (cause) {
+        return errorResult<T>(
+          action.name,
+          error({
+            code: 'client.network',
+            category: 'dependency',
+            message: 'Network request failed',
+            cause: String(cause),
+          }),
+        )
+      }
+
+      const text = await response.text()
+      const parsed = parseJson(text)
+
+      // Server falou opus? passthrough — inclusive em status != 200
+      // (not_found=404, validation=422, conflict=409 etc chegam como envelope).
+      if (isActionResultEnvelope(parsed)) {
+        return parsed as ActionResult<T>
+      }
+
+      // Daqui pra baixo a resposta NÃO é um envelope opus. Classificamos por
+      // status — NUNCA como `internal.unhandled`. `internal.unhandled` é erro de
+      // HANDLER do server, e esse só chega via envelope acima. Falha de
+      // transporte/gateway é `dependency`, pra UI distinguir "servidor
+      // indisponível" (retriable) de "erro interno do app".
+      if (!response.ok) {
+        const isServerSide = response.status >= 500
+        return errorResult<T>(
+          action.name,
+          error({
+            code: isServerSide ? 'client.unreachable' : 'client.http_error',
+            category: 'dependency',
+            message: isServerSide
+              ? `Servidor indisponível (HTTP ${response.status}) em ${action.name}`
+              : `HTTP ${response.status} em ${action.name} (resposta não-opus)`,
+            retriable: isServerSide,
+            meta: { httpStatus: response.status },
+          }),
+          response.status,
+        )
+      }
+
+      // Status 2xx mas corpo não é envelope opus (JSON alheio, HTML, vazio) —
+      // contrato quebrado entre client e server, não erro interno do server.
+      return errorResult<T>(
+        action.name,
+        error({
+          code: 'client.invalid_response',
+          category: 'dependency',
+          message: `Resposta de ${action.name} não é um ActionResult opus válido (status ${response.status})`,
+        }),
+        response.status,
+      )
+    },
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function buildUrl(
+  baseUrl: string,
+  path: string,
+  query?: unknown,
+): string {
+  const trimmed = baseUrl.replace(/\/$/, '')
+  const url = `${trimmed}${path}`
+  if (query === undefined || query === null) return url
+  if (typeof query !== 'object') return url
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue
+    params.set(key, String(value))
+  }
+  const qs = params.toString()
+  return qs.length > 0 ? `${url}?${qs}` : url
+}
+
+/** Resposta é um `ActionResult` serializado (envelope opus)? */
+function isActionResultEnvelope(value: unknown): boolean {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'ok' in value &&
+    'meta' in value
+  )
+}
+
+function parseJson(text: string): unknown {
+  if (text.length === 0) return null
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+function errorResult<T>(
+  actionName: string,
+  err: ReturnType<typeof error>,
+  httpStatus?: number,
+): ActionResult<T> {
+  const meta: ResultMeta = {
+    actionId: 'client',
+    action: actionName,
+    durationMs: 0,
+  }
+  if (httpStatus !== undefined) {
+    meta.actionId = `client:${httpStatus}`
+  }
+  return { ok: false, error: err, meta }
+}

package/src/client/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @softize/opus/client — shared helpers for client drivers.
+ *
+ * Drivers (fetch, tanstack) usam pra:
+ *   - construir URL de uma action (mesma convenção do server adapter)
+ *   - decidir HTTP method + input source (body vs query)
+ *   - desserializar response → ActionResult
+ *
+ * Lógica específica de driver (HTTP fetch, cache adapter, etc) vive em
+ * `src/drivers/<driver>.ts`.
+ *
+ * Importa de `@softize/opus/server` pra manter convenção alinhada (mesmo path,
+ * mesmo método). Isso garante que client + server sempre falam o mesmo
+ * dialeto sem duplicação de regra.
+ */
+
+export {
+  inputSourceFor,
+  methodFor,
+  pathFor,
+  type HttpMethod,
+} from '../server/index.ts'

package/src/core/actions.ts

@@ -0,0 +1,110 @@
+/**
+ * tbdlib — `defineAction` factory + type guards
+ *
+ * `defineAction` é identity function tipada que aceita qualquer variante
+ * de `ActionDef` e preserva o subtipo exato pra type narrowing posterior.
+ *
+ * Validação estrutural acontece no `Runtime.register()`, não aqui. Esta função
+ * é puramente sobre **declaração**.
+ *
+ * Ver §2 do protocolo.
+ */
+
+import type {
+  ActionDef,
+  FormAction,
+  ListAction,
+  SimpleAction,
+  ViewAction,
+} from './types.ts'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+// =============================================================================
+// defineAction (overloads per kind para inferência precisa)
+// =============================================================================
+
+/**
+ * Constrói uma `SimpleAction`. `In` é o lado do fio do schema de input;
+ * `ParsedIn` (inferido do output do schema) é o que o handler recebe —
+ * ver `ActionBase` em `types.ts`.
+ */
+export function defineAction<In, Out, ParsedIn = In>(
+  spec: SimpleAction<In, Out, ParsedIn>,
+): SimpleAction<In, Out, ParsedIn>
+
+/**
+ * Constrói uma `FormAction`. `In` deve ser um objeto cujas chaves casam com
+ * a estrutura de `fields`.
+ */
+export function defineAction<In extends Record<string, unknown>, Out, ParsedIn = In>(
+  spec: FormAction<In, Out, ParsedIn>,
+): FormAction<In, Out, ParsedIn>
+
+/**
+ * Constrói uma `ListAction`. Output é envelopado em `Paginated<Out>`.
+ */
+export function defineAction<In, Out, ParsedIn = In>(
+  spec: ListAction<In, Out, ParsedIn>,
+): ListAction<In, Out, ParsedIn>
+
+/**
+ * Constrói uma `ViewAction`.
+ */
+export function defineAction<In, Out, ParsedIn = In>(
+  spec: ViewAction<In, Out, ParsedIn>,
+): ViewAction<In, Out, ParsedIn>
+
+export function defineAction(spec: any): any {
+  return spec
+}
+
+// =============================================================================
+// Type guards
+// =============================================================================
+
+/**
+ * `true` se a action é do kind `simple`.
+ */
+export function isSimpleAction(
+  action: ActionDef,
+): action is SimpleAction<any, any> {
+  return action.kind === 'simple'
+}
+
+/**
+ * `true` se a action é do kind `form`.
+ */
+export function isFormAction(
+  action: ActionDef,
+): action is FormAction<any, any> {
+  return action.kind === 'form'
+}
+
+/**
+ * `true` se a action é do kind `search`.
+ */
+export function isListAction(
+  action: ActionDef,
+): action is ListAction<any, any> {
+  return action.kind === 'list'
+}
+
+/**
+ * `true` se a action é do kind `view`.
+ */
+export function isViewAction(
+  action: ActionDef,
+): action is ViewAction<any, any> {
+  return action.kind === 'view'
+}
+
+/**
+ * `true` se a action declarou execução em background (apenas `simple` e `form`).
+ */
+export function isBackgroundAction(action: ActionDef): boolean {
+  return (
+    (action.kind === 'simple' || action.kind === 'form') &&
+    action.background?.enabled === true
+  )
+}