Skip to content

Segurança ​

O Basalt é seguro por omissão na borda HTTP e fail-closed nos segredos. Tudo aqui é zero-dependências e ligado através do ciclo de vida dos plugins.

Os defaults seguros, num relance ​

Cada um destes vem LIGADO por omissão — tens de optar por sair, nunca por entrar. Esta tabela é o mapa; o guia de cada linha tem os detalhes e o opt-out.

DefaultO que previneOnde
O boot recusa rotas cuja meta de segurança não tem guard a aplicá-la (UnguardedRouteMetaError)rotas "protegidas" a servir abertas em silêncionesta página, abaixo
As rotas de billing/faturas exigem utilizador autenticado (meta.auth)gestão anónima de cartões/planos via tenant forjadoBilling
Guard de membership em cada pedido autenticado com tenant (tenantMembershipPlugin)um utilizador válido do tenant A a conduzir o tenant B (TEAM_NOT_A_MEMBER)nesta página, abaixo
A cache falha fechada fora do contexto de tenant em apps multi-tenant (MissingCacheScopeError)leituras cross-tenant através de um namespace "global" partilhadoCaching
meta.can rejeita formas não aplicáveis (PERMISSION_META_INVALID)uma declaração malformada a saltar a autorização em silêncioAutorização
URLs assinados de storage servem Content-Disposition: attachmentstored XSS via uploads de utilizadores numa origem CDNStorage
Corpos de mail construídos com html`…` com interpolações auto-escapadas; o log driver redige corpos em produçãoinjeção de markup no mail da app · links de reset em agregadores de logsNotificações
Páginas admin/UI transportam uma CSP route-scoped com hashinjeção de script inline — sem enfraquecer a CSP da appPáginas admin
As chaves de rate-limit ignoram X-Forwarded-For; o CORS nunca reflete origens arbitrárias com credenciais; HSTS/nosniff/frame-deny ligadoslimites forjados por header · leituras cross-origin com credenciais · clickjackingnesta página, abaixo
Os segredos falham fechados em produção (secret(), AUTH_WEAK_SECRET)arrancar com uma chave de assinatura adivinhávelnesta página, abaixo

Proteção de borda — securityPlugin ​

Um só plugin cobre rate limiting, CORS e cabeçalhos de resposta seguros. Os cabeçalhos seguros estão ligados por omissão; o rate limiting e o CORS são opt-in — ativa-os explicitamente para produção. As apps novas já trazem securityPlugin() no scaffold com um rate limit global por IP ligado (rateLimit: { limit: 120, windowMs: 60_000 }), por isso os cabeçalhos e os limites de pedidos ficam protegidos desde o primeiro deploy. Com tenancy e auth, o scaffold regista também teamsPlugin() + tenantMembershipPlugin() (vê Nunca confies num tenant vindo do cliente abaixo).

ts
import { securityPlugin } from '@basaltkit/fastify'

securityPlugin({
  rateLimit: { limit: 100, windowMs: 60_000 },      // 100 req / minuto / IP
  cors: { origin: ['https://app.example.com'], credentials: true },
  headers: true,                                     // defaults seguros
})

Rate limiting ​

Um limitador de janela fixa chaveado pelo IP do cliente (substitui com key). Pedidos bloqueados recebem 429 RATE_LIMITED com Retry-After, e cada resposta carrega X-RateLimit-Limit / -Remaining / -Reset.

ts
securityPlugin({
  rateLimit: {
    limit: 20,
    windowMs: 10_000,
    // A predefinição. Atrás de um proxy, faz o adaptador resolver request.ip a
    // partir do proxy em que confias, em vez de ler aqui um header de reencaminhamento.
    key: (req) => req.ip ?? 'unknown',
    skip: (req) => req.url.startsWith('/livez'),
  },
})

Nunca chaveies o limite global por um header de credencial

A key global corre antes da autenticação, por isso só vê o que o cliente enviou. Uma chave como req.headers['x-api-key'] ?? req.ip é um bypass: um cliente que envia um valor inventado novo em cada pedido recebe um balde novo de cada vez e nunca é limitado, e a avalanche de baldes empurra clientes legítimos para fora do store. Chaveia o limite global só pelo endereço (req.ip, ou um header que o teu próprio proxy define e remove dos pedidos dos clientes). Para um orçamento por API key, usa meta.rateLimit com key: 'apiKey' (abaixo): lê a chave que o enricher verificou, por isso uma chave inventada nunca recebe um balde próprio.

O store por omissão é em memória (MemoryRateLimitStore). A sua memória é limitada: os baldes expirados são varridos à medida que chega tráfego, e são mantidos no máximo maxEntries (por omissão 100 000) baldes — acima disso as janelas mais antigas são despejadas primeiro, para que uma avalanche de endereços de cliente distintos não faça crescer o processo sem limite (new MemoryRateLimitStore({ maxEntries }) para o dimensionar). Um balde que esgotou o seu limite nunca é despejado: uma avalanche de endereços novos não liberta mais cedo um cliente limitado — fica retido até a sua janela terminar. Para múltiplas instâncias, implementa a interface RateLimitStore sobre Redis — o mesmo padrão de driver usado por @basaltkit/cache.

Limites por rota. Uma rota pode apertar o orçamento de um endpoint sensível via meta.rateLimit — recebe o seu próprio balde (por IP + padrão de rota) nesse limite. É imposto como guard de rota, por isso vale de forma idêntica em Fastify, Express e Hono, e também quando a rota é invocada como tool MCP. Em Express e Hono (onde o hook de borda corre antes do routing) o pedido conta também para o balde global; em Fastify é contado uma só vez, no seu próprio balde:

ts
route({
  method: 'POST',
  url: '/auth/login',
  meta: { rateLimit: { limit: 5, windowMs: 60_000 } }, // 5/min além do limite global
  // …
})

Orçamentos por utilizador e por tenant. Por omissão o balde é o IP do cliente, por isso toda a gente atrás de um mesmo NAT ou proxy empresarial o partilha. meta.rateLimit.key escolhe a quem pertence o balde:

keyBaldePara quê
'ip' (predefinição)endereço do cliente (request.ip)endpoints anónimos: login, registo, reposição de palavra-passe
'user'ctx().user.idações caras por utilizador: exportações, chamadas de IA, uploads
'tenant'ctx().tenant.id (partilhado pelos utilizadores do tenant)uma quota por organização
'user+tenant'um balde por utilizador por tenantum utilizador que pertence a vários tenants
'apiKey'ctx().apiKey.id (uma chave que o apiKeysPlugin verificou)rajadas por cliente máquina
(ctx) => stringo id que devolveresqualquer outro caso
ts
route({
  method: 'POST',
  url: '/reports/export',
  meta: { auth: true, rateLimit: { limit: 10, windowMs: 60_000, key: 'user' } },
  // …
})

A chave é resolvida no guard de rota, depois de os enrichers correrem, por isso a autenticação e a tenancy já definiram ctx().user / ctx().tenant. Quando o id falta (um chamador anónimo, nenhum tenant resolvido, ou a função não devolve nada), o balde recua para o IP do cliente, e os baldes anónimos nunca se misturam com os de utilizadores autenticados. Quando o adaptador também não conseguiu resolver um IP (request.ip undefined — Hono num runtime sem getClientIp, um runRoute feito à mão, uma tool MCP chamada por stdio ou através do McpServer.callTool), um chamador autenticado fica com a chave da sua identidade (user:<id>|tenant:<id>, como faria o 'user+tenant'), e todos os pedidos anónimos sem IP partilham um só balde unknown: falha fechada, em vez de um balde por header falsificável. Configura o adaptador para resolver o IP do cliente e voltar a ter baldes por cliente. Os baldes com chave usam o mesmo store (MemoryRateLimitStore, ou Redis entre instâncias). Uma rota com chave continua a contar para o limite global por IP em todos os adaptadores, porque o hook anterior ao routing ainda não conhece o utilizador. Para dar a uma família de caminhos outro teto por IP, usa orçamentos por prefixo de caminho.

'apiKey' chaveia o balde por ctx().apiKey.id — um orçamento por API key, para que vários clientes máquina atrás de um mesmo endereço deixem de partilhar um só. Só uma chave que o apiKeysPlugin verificou se torna id de balde; sem chave verificada (um chamador com sessão, um anónimo, ou uma chave inválida que o rejectInvalid: false deixou passar) o balde recua como qualquer outro id em falta. Um orçamento por chave multiplica-se pelo número de chaves que um cliente cria, por isso usa-o para rajadas e põe as quotas em 'tenant'.

Vários orçamentos numa rota ​

meta.rateLimit aceita também um array. Todos os orçamentos são impostos, pela ordem declarada; o primeiro que recusa responde 429 e os seguintes não são cobrados — por isso põe primeiro o orçamento curto de rajada, e um pedido recusado por rajada não gasta a quota diária:

ts
import type { RouteRateLimits } from '@basaltkit/http'

route({
  method: 'GET',
  url: '/v1/orders',
  meta: {
    scopes: ['orders:read'],
    rateLimit: [
      { limit: 10, windowMs: 1_000, key: 'apiKey' },        // rajada, por chave
      { limit: 50_000, windowMs: 86_400_000, key: 'tenant' }, // diário, por cliente
    ] satisfies RouteRateLimits,
  },
  // …
})
  • Os X-RateLimit-* reportam o orçamento com menos pedidos restantes (em empate, o que reinicia mais tarde); numa recusa, eles e o Retry-After vêm do orçamento que recusou.
  • Os orçamentos são cobrados um após o outro (um hit no store cada), sem atomicidade entre eles.
  • Cada entrada do array tem o seu contador, chaveado por método, rota e posição: reordenar as entradas remapeia os contadores. Mudar um limit ou windowMs mantém a janela em curso — editar uma quota não dá a todos uma nova.
  • A forma de array (e bucket, abaixo) é sempre cobrada no guard de rota, em todos os adaptadores, além do balde de borda (global ou de prefixo). Em Fastify isto difere do objeto único, que é cobrado em vez do balde global: embrulhar { limit, windowMs } num array repõe o limite global por IP nessa rota. Se dependias dessa substituição em Fastify para levantar o teto, passa a um prefixo de caminho, que o faz em todos os adaptadores.

Baldes partilhados ​

bucket dá nome a um orçamento partilhado por todas as rotas que o declaram — uma quota diária para toda uma API pública:

ts
const daily = { limit: 50_000, windowMs: 86_400_000, key: 'tenant', bucket: 'public-api-daily' } as const

route({ method: 'GET', url: '/v1/orders', meta: { rateLimit: [{ limit: 10, windowMs: 1_000, key: 'apiKey' }, daily] }, /* … */ })
route({ method: 'POST', url: '/v1/orders', meta: { rateLimit: daily }, /* … */ })

Todas as declarações de um nome têm de levar o mesmo limit, windowMs e string de chave; a app recusa arrancar (InvalidRouteMetaError, em todos os adaptadores) quando divergem. Chaves-função não são comparadas — duas lambdas inline são objetos diferentes mesmo quando significam o mesmo. Os nomes seguem /^[A-Za-z0-9._:-]{1,64}$/. Um array ou entrada com bucket malformado (array vazio, um limite não positivo, uma string de chave desconhecida) também recusa o arranque; o objeto único mantém a sua leitura tolerante de sempre.

Orçamentos por prefixo de caminho ​

rateLimit.prefixes dá a uma família de caminhos o seu próprio orçamento de borda, cobrado antes do routing em vez do balde global — é assim que uma API pública sob /v1 recebe um teto por IP mais alto do que o resto da app, continuando a pagar um orçamento por IP antes de qualquer chave ser procurada:

ts
securityPlugin({
  rateLimit: {
    limit: 300,
    windowMs: 60_000,
    prefixes: [{ prefix: '/v1', limit: 3_000, windowMs: 60_000 }],
  },
})

Ganha o prefixo correspondente mais longo. A correspondência é em fronteiras de segmento (/v1 corresponde a /v1 e /v1/orders, nunca a /v10) depois de uma normalização mínima: a query string é cortada, sequências de / colapsam, maiúsculas/minúsculas são ignoradas e um / final é removido — não há percent-decoding nem resolução de segmentos de ponto. 404s, preflights e pedidos que um enricher rejeita também contam. Cada prefixo pode ter a sua própria key(request) (por omissão: a key global, senão o IP); tal como a chave global corre antes da autenticação, por isso nunca leias nela um header de credencial. skip também salta os orçamentos de prefixo. Um prefixo inválido (sem / inicial, com ? ou #, um limite não positivo, um duplicado) lança um TypeError quando o plugin é criado.

Os prefixos definem ou levantam o orçamento de borda de uma família de caminhos; não servem para tornar um endpoint mais restrito, porque um pedido que chega à rota por uma forma de caminho que a normalização não dobra recua para o balde global. Um orçamento que tem de valer para um endpoint específico pertence ao seu meta.rateLimit, que está ligado à rota correspondente. Em Fastify, um meta.rateLimit de objeto único chaveado por IP continua a substituir o balde de borda (prefixo ou global), como antes.

CORS ​

origin aceita true (refletir), uma string, um array de allow-list, ou um predicado. Os pedidos de preflight OPTIONS são respondidos automaticamente (204). Contam para o rate limit global como qualquer outro pedido, e os cabeçalhos Access-Control-Allow-Methods / -Allow-Headers / -Max-Age só são enviados a uma origem permitida — uma origem não permitida recebe um 204 simples, que não revela nada.

Credenciais exigem uma allow-list explícita

Refletir uma Origin arbitrária com credentials: true entregaria respostas autenticadas (com cookies) a qualquer site. Quando credentials está ligado, o Basalt recusa refletir — tens de passar uma origin explícita (string, array ou predicado). Um wildcard * só é emitido para pedidos sem credenciais.

Cabeçalhos seguros ​

headers: true define HSTS, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Referrer-Policy: no-referrer, Cross-Origin-Opener-Policy: same-origin e uma Content-Security-Policy restritiva por omissão — default-src 'none'; frame-ancestors 'none' (adequada a uma API JSON), mais Cache-Control: no-store, para que nenhuma cache do browser ou intermediária guarde uma resposta com um token de sessão, API key ou segredo MFA. Passa um objeto para personalizar (p. ex. a tua própria contentSecurityPolicy para uma superfície HTML/docs, ou cacheControl: 'private, no-cache'), contentSecurityPolicy: false / cacheControl: false para omitir só esse cabeçalho, ou headers: false para desativar tudo. Uma rota que pode ser guardada em cache define o seu próprio Cache-Control, que substitui o valor por omissão — fá-lo nas rotas meta.etag (p. ex. private, no-cache), já que no-store impede o browser de revalidar.

Cabeçalhos por rota — meta.responseHeaders ​

Algumas rotas precisam de cabeçalhos que o resto da API não precisa: um link de partilha público que os motores de busca não devem indexar, um download que nunca deve ir para cache. Declara-os na rota:

ts
route({
  method: 'POST',
  url: '/s/:token',
  meta: { responseHeaders: { 'X-Robots-Tag': 'noindex, nofollow', 'Cache-Control': 'no-store' } },
  handler: /* … */,
})

O pipeline aplica-os logo que a rota é encontrada, antes dos enrichers e dos guards, por isso estão em todas as respostas que a rota produz — o 200, o 401/403 de um guard, um 400 de validação, um 500 lançado — nos três adapters. Um cabeçalho posto com reply.header() só chegaria ao caminho de sucesso. Substituem um cabeçalho global com o mesmo nome (aqui o Cache-Control do securityPlugin), e um handler continua a poder sobrepor-se a um deles com reply.header().

Os valores são verificados no arranque em todos os adapters: strings sem CR, LF nem outros caracteres de controlo, e nunca Set-Cookie, Content-Type, Content-Length, Transfer-Encoding, cabeçalhos hop-by-hop nem X-Request-Id, que pertencem à resposta ou ao adapter. Um registo que viola uma regra recusa o arranque com HTTP_INVALID_ROUTE_META, nomeando cada rota em falta (o @basaltkit/http 2.8 só avisava e não enviava nenhum dos seus cabeçalhos). Se conduzes o runRoute() tu próprio sem assertRouteMetaValid(), essa rota lança InvalidRouteHeadersError (500, HTTP_INVALID_ROUTE_HEADERS) em cada pedido, antes de definir qualquer um dos seus cabeçalhos.

A chave é responseHeaders, não headers: a meta da rota também é tua, e nada lê nem envia meta.headers. Um pedido que nunca chega à rota — um 404, um 429 do rate limit ou um corpo malformado rejeitado pelo parser da framework — leva só os cabeçalhos globais.

Os valores são verificados no arranque (InvalidRouteMetaError): strings sem CR, LF ou outros caracteres de controlo, e nunca Set-Cookie, Content-Type, Content-Length, Transfer-Encoding, cabeçalhos hop-by-hop ou X-Request-Id, que pertencem à resposta ou ao adapter. Um pedido que nunca chega à rota — um 404, um 429 de rate limit ou um corpo malformado rejeitado pelo parser da framework — leva apenas os cabeçalhos globais.

Limites de recursos & resistência a DoS ​

Para além de headers e rate limits, conexões longas e lentas podem esgotar um servidor. O Basalt traz defaults sensatos e knobs para as arestas.

Timeouts de request (anti-slowloris) ​

Um cliente lento que envia um pedido byte a byte prende uma conexão indefinidamente. O adapter Fastify usa por omissão um requestTimeout de 30 s (o default do Fastify é desligado); sobrepõe via fastifyPlugin({ fastify: { requestTimeout } }). O Express e o Hono correm num servidor Node teu — aplica a mesma proteção nele:

ts
// Express / Hono (servidor node:http)
server.requestTimeout = 30_000   // o pedido inteiro tem de chegar em 30s
server.headersTimeout = 20_000   // headers em 20s (slowloris de headers)
server.keepAliveTimeout = 5_000

Streams SSE ​

Os Server-Sent Events são longos por natureza, por isso dá-lhes um heartbeat e um limite de vida. O send() devolve também um booleano de backpressure — para de produzir quando for false:

ts
return sse(async (stream) => {
  for await (const update of source) {
    if (!stream.send({ data: update })) break // o cliente não acompanha → abranda
  }
}, { heartbeatMs: 15_000, maxDurationMs: 30 * 60_000 }) // ping a cada 15s, limite de 30 min

Os pings de heartbeat impedem os proxies de largar um stream inativo e revelam um socket morto; o maxDurationMs é um backstop contra conexões que nunca desligam. Limita o número de streams concorrentes por utilizador/tenant no teu handler para um teto rígido.

Endpoints de cerimónia (WebAuthn, MFA) ​

Endpoints que emitem um challenge ou verificam um código são pré-auth e baratos de martelar — faz-lhes throttle. Reutiliza o bloqueio por força bruta e limites por-rota, e em produção suporta o PasskeyStore / WebAuthnChallengeStore do WebAuthn (e os stores de MFA) com uma implementação durável, não o default em memória.

Re-verificação de domínios custom ​

Um domínio custom verificado que depois expira ou repointa o DNS é um risco de takeover. Re-verifica num agendamento com @basaltkit/scheduler — o reverifyAll() re-verifica o registo TXT de cada domínio verificado e revoga os que já não o têm de forma definitiva (um timeout de DNS deixa-os verificados):

ts
schedule.call('reverify-domains', async () => {
  const { revoked } = await customDomains.reverifyAll()
  if (revoked.length) log.warn({ revoked }, 'custom domains un-verified')
}).daily().at('04:00')

O novo dono de um domínio expirado também pode tomar um claim verificado obsoleto publicando o seu registo de challenge() — vê Tenancy.

Endpoint de mail de entrada ​

O inboundMailRoutes() não está autenticado até a assinatura sobre os bytes ser verificada, por isso limita os pedidos a 10 MiB (e não ao default de 1 MiB do rawBody()), responde a endereços sem rota exatamente como aos encaminhados e só acredita em Authentication-Results de servidores que indicares. Acrescenta um meta.rateLimit — vê Mail de entrada.

Segredos fail-closed — secret() ​

O incidente de produção mais comum é enviar uma chave de assinatura placeholder. secret() torna isso impossível:

ts
import { defineEnv, secret } from '@basaltkit/env'

export const env = defineEnv({
  APP_SECRET: secret({ devDefault: 'dev-only-insecure-secret-value' }),
})
  • Desenvolvimento (NODE_ENV=development ou test, definido explicitamente): usa devDefault quando não definido — a app simplesmente corre.
  • Em qualquer outro caso — NODE_ENV=production, staging ou não definido: a variável é obrigatória, tem de cumprir um comprimento mínimo, e é rejeitada se parecer um placeholder (change-me, secret, password, …). Caso contrário a app recusa arrancar, por isso esquecer o NODE_ENV num deploy nunca recai no valor de dev público.

Bloqueio por força bruta ​

@basaltkit/auth limita logins falhados por email logo à partida — sem qualquer ligação necessária. Após demasiadas falhas dentro de uma janela deslizante, login() lança AccountLockedError (HTTP 429) mesmo com a password correta; um sucesso limpa o contador.

ts
import { authPlugin, LoginThrottle } from '@basaltkit/auth'

authPlugin({
  users,
  secret: env.APP_SECRET,
  // por omissão 5 tentativas / 15 min; personaliza ou desativa:
  loginThrottle: new LoginThrottle({ maxAttempts: 10, windowMs: 5 * 60_000 }),
  // loginThrottle: false, // para desligar
})

Um throttle por IP corre em paralelo (ligado por omissão), para apanhar também um spray de uma tentativa por muitas contas — passa o IP do cliente ao login({ ip }) (a rota incorporada já o faz).

A enumeração de contas está fechada por omissão ​

O endpoint público de registo é enumeration-safe: registar um email que já existe devolve o mesmo 202 (e faz trabalho equivalente) que um registo novo, por isso não pode ser usado para sondar que emails têm conta. A colisão é sinalizada out-of-band pelo hook auth:register_existing_email — envia ao endereço "já tens conta; entra ou repõe a password":

ts
app.hooks.on('auth:register_existing_email', ({ email }) => sendAlreadyRegisteredEmail(email))

// opt-out (409 clássico no duplicado) se mesmo precisares:
authPlugin({ users, secret: env.APP_SECRET, enumerationSafeRegister: false })

As respostas de login, reposição de password e verificação de email são também uniformes exista ou não a conta (timing equalizado, { ok: true } genérico), por isso nenhum endpoint de auth revela que emails estão registados.

Mutações idempotentes — idempotencyPlugin ​

Retries seguros para POST: um cliente que envia uma Idempotency-Key recebe a mesma resposta replicada num retry, por isso uma ligação caída nunca cobra um cartão duas vezes. Corre dentro do pipeline de rotas partilhado, por isso comporta-se da mesma forma em Fastify, Express e Hono:

ts
import { idempotencyPlugin } from '@basaltkit/http' // também reexportado por @basaltkit/fastify

// Protege POST por omissão. Cada chave fica associada ao seu pedido (params,
// query e corpo: um diferente → 422), e os replays só acontecem depois dos
// guards da rota e da validação (um caller revogado recebe 401/403, não o
// sucesso em cache).
idempotencyPlugin()
  • Repetir com a mesma chave → a resposta em cache, com Idempotent-Replayed: true. Vale para qualquer forma de handler — um que devolve o payload é repetido exactamente como um que chama reply.send().
  • Uma repetição enquanto a primeira ainda está em curso → 409 IDEMPOTENCY_CONFLICT.
  • Só é registado o resultado do próprio handler. Uma recusa levantada antes de o handler correr — o 401/403 de um guard, o 429 do rate limiter, um 400 de validação — liberta a chave, por isso um cliente que respeita o Retry-After (ou volta a autenticar-se) vê a operação executada no retry.
  • Respostas 5xx, os status de "tenta mais tarde" 408, 425 e 429 (mesmo vindos do handler), downloads stream() e streams sse() não são colocados em cache, por isso falhas genuínas continuam repetíveis. Qualquer outro erro de cliente que o handler lança (4xx) é registado e replicado byte a byte.
  • As chaves têm escopo por credenciais do caller + headers de tenant + método + padrão da rota, com hash SHA-256 antes de chegarem ao store. As credenciais são todos os headers em credentialHeaders (por omissão authorization, x-session-id, cookie, x-api-key), por isso a resposta em cache de uma credencial nunca é replicada a outra. A rota é o seu padrão (/accounts/:id/charge), por isso a mesma chave em duas rotas diferentes nunca colide. Se autenticas com outro header, adiciona-o a credentialHeaders.
  • O que o escopo não cobre. A parte do tenant é só os headers em bruto x-tenant-id e host — não um tenant resolvido a partir de um segmento do path (/t/:tenant/...) ou de um claim do token — e a rota é o seu padrão, não os params concretos do path. O fingerprint por omissão ('request', abaixo) associa esses params, a query e o corpo, por isso a mesma credencial a reutilizar uma chave em /t/acme/orders e /t/globex/orders, ou em /orders/1/pay e /orders/2/pay, é recusada com 422. Com fingerprint: 'body' ou false essa reutilização recebe a primeira resposta: faz os clientes gerarem uma chave nova por operação (e por tenant).
  • A parte da credencial são bytes em bruto. Uma repetição cujos headers de credencial diferem num só byte é outro caller para o plugin: depois de uma rotação de API key, depois de passar de x-api-key para Authorization: Bearer (ou o inverso), ou depois de o header cookie mudar, a repetição não encontra registo e corre a operação outra vez. Nunca faz replay para outro caller; pode duplicar. Repete com a credencial que a primeira tentativa usou. Vê API keys e idempotência.
  • A resposta registada é guardada tal como foi enviada, durante o ttlMs (24 h por omissão), na store configurada. Uma resposta que traz um segredo — POST /apikeys e POST /apikeys/:id/rotate devolvem a chave em texto simples — fica nessa store (memória do processo, ou Redis) quando o cliente enviou Idempotency-Key. Protege uma store partilhada como qualquer store de segredos.
  • Pedidos sem nenhum header de credencial não são colocados em cache nem replicados por omissão (senão um estranho que adivinhasse a chave receberia a resposta). Ativa com allowAnonymous: true apenas em endpoints públicos sem nada privado.
  • Chaves com mais de 255 caracteres → 400 IDEMPOTENCY_KEY_INVALID; o MemoryIdempotencyStore remove entradas expiradas e tem um limite maxEntries (por omissão 10 000). O RedisIdempotencyStore partilha os replays entre instâncias.
  • Cobre as rotas que o Basalt serve (definições route()). Um handler que registes à mão na framework por baixo — um fastify.post(...) cru — não fica coberto: declara-o com route().

A chave fica associada ao pedido — fingerprint. Um cliente que reutiliza uma chave para um pedido diferente (um bug, ou um retry depois de o utilizador editar o formulário) receberia em silêncio o resultado do primeiro pedido. O fingerprint é um SHA-256 guardado com o registo; uma repetição cujo fingerprint difere é recusada com 422 IDEMPOTENCY_KEY_REUSED, também enquanto o primeiro pedido ainda está a correr. Os modos:

  • 'request' (por omissão) — os params da rota, a query e o corpo: JSON canónico com chaves ordenadas para um corpo com parse, os bytes exatos para uma rota rawBody(). A mesma chave em /accounts/1/charge e depois em /accounts/2/charge dá 422, mesmo com um corpo idêntico. As rotas upload() associam só params e query: o stream pertence ao handler e não é lido.
  • 'body' — só o corpo (JSON canónico, ou os bytes em bruto); params e query não são associados, e as rotas upload() não levam fingerprint.
  • uma função ({ route, request }) => unknown — o teu próprio fingerprint. Um objeto ou array é canonicalizado primeiro, por isso a ordem das chaves nunca conta; uma string ou outro primitivo é hasheado tal como está. Devolve undefined para saltar um pedido.
  • false — as chaves não ficam associadas a um pedido.

Com fingerprint ligado, o RedisIdempotencyStore grava as reservas em curso como pending:<fingerprint>, que uma instância ainda no plugin só-Fastify (@basaltkit/fastify 2.5 ou anterior) lê mal durante um rolling deploy: passa primeiro toda a frota para @basaltkit/http 2.8 / @basaltkit/fastify 2.6, e só depois atualiza para 3.x.

Uma função é a forma de retirar campos voláteis que um cliente muda em cada retry:

ts
idempotencyPlugin({
  fingerprint: ({ request }) => {
    const { sentAt, ...rest } = (request.body ?? {}) as Record<string, unknown>
    return { params: request.params, body: rest } // canonicalizado: a ordem das chaves é irrelevante
  },
})

Onde corre a verificação — replayAfterGuards. Por omissão (true) a verificação corre depois dos guards da rota e da validação do pedido, mesmo antes do handler: um caller cujo token foi revogado desde o primeiro pedido recebe o 401/403 do guard em vez do sucesso em cache, os guards correm em cada replay (um tenant suspenso recebe o seu 403, não um replay), e um pedido que falha a validação nunca reserva a chave. false corre-a depois dos enrichers e antes dos guards: um caller revogado que apresente o mesmo header de credencial continua então a receber o sucesso em cache. Mesmo assim, uma rota rawBody() com fingerprint 'request' ou 'body' é verificada depois dos guards, porque os seus bytes nunca são lidos antes de eles passarem.

Para manter o comportamento do @basaltkit/http 2.x, passa idempotencyPlugin({ fingerprint: false, replayAfterGuards: false }) — vê Atualizar: idempotência estrita por omissão. Um IdempotencyStore próprio tem de persistir record.fingerprint para que um registo concluído seja recusado com 422; para responder 422 em vez de 409 a uma repetição concorrente guarda também o fingerprint passado a setPending(key, { fingerprint }) e devolve { pending: true, fingerprint } no get(), como fazem os dois stores incluídos.

Revogar access tokens ​

Os access tokens (JWTs) são stateless, por isso ficam válidos até expirarem. Liga um TokenVersionStore para os revogar mais cedo — uma reposição de password (e o explícito revokeAllTokens(userId)) invalida então todos os tokens emitidos antes do incremento:

ts
import { authPlugin, MemoryTokenVersionStore } from '@basaltkit/auth'
import { PrismaTokenVersionStore } from '@basaltkit/auth-prisma' // ou SqliteTokenVersionStore

authPlugin({ users, secret: env.APP_SECRET, tokenVersions: new PrismaTokenVersionStore(prisma) })

Desligado por omissão (a verificação passa a custar uma leitura ao store por pedido). O próprio segredo de assinatura é protegido: o Auth recusa arrancar com segredo vazio e, em produção (tudo excepto um NODE_ENV=development/test explícito, incluindo não definido), rejeita um com menos de 32 chars (uma chave HS256 curta é forjável offline) — usa secret({ minLength: 32 }).

Cifrar segredos TOTP em repouso ​

O TOTP tem proteção anti-replay de origem (o time-step de um código é registado, por isso um código intercetado é de uso único). Para sobreviver também a uma fuga da base de dados, cifra os segredos guardados com uma chave da app (pelo menos 32 bytes) — ficam como envelopes AES-256-GCM (chave derivada por HKDF com id de chave, ligados ao utilizador) e só são decifrados ao verificar um código:

ts
authPlugin({ users, secret: env.APP_SECRET, mfaEncryptionKey: env.MFA_KEY })

Um valor guardado que não seja um destes envelopes é recusado, por isso uma escrita na tabela não consegue rebaixar um segredo para um em texto simples que quem escreve conhece. A rotação de chaves e a migração de linhas em texto simples ou v1: (uma adesão legacy explícita mais auth.reencryptMfaSecret(userId)) estão em Cifrar os segredos TOTP em repouso.

Segredos em repouso ​

Todos os segredos que o Basalt guarda cifrados — segredos TOTP (o SecretBox do @basaltkit/auth, envelope bka2) e tokens OAuth de drives na nuvem (o DriveSecretBox do @basaltkit/drives, envelope bkd1) — passam por uma única primitiva auditada, createSecretBox de @basaltkit/core/secret-box:

  • AES-256-GCM, IV aleatório de 96 bits, tag completa de 128 bits (uma tag mais curta é recusada);
  • derivação de chave HKDF-SHA256 com uma etiqueta por caixa, por isso o mesmo material de chave usado por duas caixas dá chaves sem relação;
  • um anel de chaves com ids: a primeira chave sela, todas abrem, e o reseal() passa uma linha para a chave ativa — a rotação é gradual;
  • ligação AAD ao registo dono (utilizador, ou tenant + ligação + fornecedor): um blob copiado para outra linha falha a verificação da tag;
  • sem caminho em texto simples: tudo o que não seja um envelope dessa caixa é recusado.

Usa-a para um segredo teu (segredos de assinatura de webhooks, tokens de APIs de terceiros) em vez de escreveres AES à mão:

ts
import { createSecretBox } from '@basaltkit/core/secret-box'

const box = createSecretBox({
  keys: [{ id: '2026-10', key: env.INTEGRATIONS_KEY }], // ≥ 32 bytes; chaves novas primeiro
  info: 'my-app:integration-tokens:v1',                 // única por caixa
  version: 'mya1',                                      // etiqueta do envelope, [a-z0-9]{1,16}
  aadFields: 2,                                         // a que cada segredo fica ligado
})
const sealed = box.seal(token, [tenantId, integrationId])
const token2 = box.open(sealed, [tenantId, integrationId]) // caso contrário lança SecretBoxError

As falhas lançam SecretBoxError com um failure de config, malformed, unknown-key, context ou auth-failed (nunca o segredo nem a chave). O subpath não é reexportado pela entrada principal de @basaltkit/core.

HTTP de saída & SSRF ​

Sempre que a tua app vai buscar um URL que não escreveu — o "importar de URL" de um tenant, o link de um avatar, um ficheiro para o qual um fornecedor aponta — esse URL é input hostil: pode apontar para 169.254.169.254, para uma base de dados na tua rede privada, ou para um host público que redireciona para uma. Não uses o fetch simples para isso. O @basaltkit/webhooks exporta o cliente em streaming que o @basaltkit/drives usa em todas as chamadas a fornecedores:

ts
import { createGuardedFetch, GuardedFetchError } from '@basaltkit/webhooks'

const fetchUntrusted = createGuardedFetch({
  maxBytes: 20 * 1024 * 1024, // obrigatório: abandonado a meio do stream acima disto
  timeoutMs: 15_000, // inactividade do socket + espera pelos headers em cada salto
  deadlineMs: 120_000, // opcional: a troca inteira, corpo incluído
  allowedHosts: ['.example-cdn.com'], // opcional: `.sufixo` = só subdomínios
})

const response = await fetchUntrusted(url)
await files.upload(response.body, { name: 'import.pdf' }) // em streaming, com limite

O que impõe, em cada salto de redirect: só https: (alarga com allowedSchemes), a allowlist de hosts opcional, DNS resolvido uma vez com cada resposta verificada contra gamas privadas/loopback/link-local/CGNAT/ULA/ reservadas e IPv6 com IPv4 embebido, o socket fixado no IP validado (sem DNS rebinding), no máximo maxRedirects (3) saltos com authorization/cookie removidos num salto para outro host, nenhum accept-encoding (para que uma bomba de descompressão não se esconda atrás do limite), e o limite de bytes contado no fio.

As recusas lançam GuardedFetchError com kind SSRF_BLOCKED, BODY_TOO_LARGE, TIMEOUT ou TOO_MANY_REDIRECTS (código OUTBOUND_<kind>). A mensagem nomeia o host, nunca o URL — um URL pré-assinado é uma credencial — e expose é false, por isso um cliente só vê o código. O allowPrivateHosts é a única saída de emergência, para um alvo alojado na tua própria rede.

Responsabilidade partilhada — reforçar a tua integração ​

O Basalt fecha as vulnerabilidades que consegue fechar sozinho. Três coisas, porém, dependem de como a tua app liga as peças — a framework não as pode decidir por ti. Acerta nestas em cada deployment.

1. Autorização é explícita — declara um guard, não só a intenção ​

O meta.auth / meta.can / meta.teamRole / meta.scopes / meta.subscribed / meta.feature de uma rota documenta o que a rota precisa, mas o guard que o aplica tem de estar de facto registado. Uma rota declarada-mas-sem-guard estaria aberta — por isso os adapters recusam arrancá-la: no arranque verificam que cada chave de meta de segurança declarada tem um guard registado a reclamá-la (via o bucket http:guarded-meta) e falham alto, listando todas as rotas em falta.

ts
// ❌ o meta diz "admin", mas nada o aplica → UnguardedRouteMetaError no BOOT
route({ method: 'POST', url: '/admin/purge', meta: { can: 'admin' }, handler })

// ✅ regista o plugin cujo guard aplica a chave
authPlugin(…)         // aplica meta.auth
permissionsPlugin(…)  // aplica meta.can
teamsPlugin(…)        // aplica meta.teamRole
apiKeysPlugin(…)      // aplica meta.scopes
subscriptionsPlugin(…) // aplica meta.subscribed e meta.feature

O conjunto guardado completo é auth, can, teamRole, scopes, subscribed e feature (GUARDED_META_KEYS). As chaves que relaxam em vez de proteger ficam deliberadamente de fora — meta.central (salta a verificação de pertença ao tenant), meta.mcp (opta por expor a rota via MCP) e meta.rateLimit (travagem de abuso, não uma fronteira de autorização). Um meta.rateLimit sem nenhum limitador registado (sem securityPlugin({ rateLimit })) não recusa o boot, mas o adaptador avisa uma vez, nomeando as rotas, que esses orçamentos não são aplicados. Silencia-o com allowUnguardedMeta: ['rateLimit'] (ou true) quando uma edge exterior faz a travagem.

Se a proteção acontecer genuinamente numa edge/gateway exterior, opta por sair explicitamente com a opção do adapter allowUnguardedMeta: true (ou ['auth', …] para chaves específicas). Um plugin de guard próprio que aplique uma destas chaves deve reclamá-la: ensureMetadata(container).add('http:guarded-meta', 'auth').

Reclamar uma chave prova que alguém a aplica; não diz nada sobre o valor. Para isso, um plugin regista um validador de meta de rota em http:meta-validators (META_VALIDATORS_BUCKET): todos os adapters correm-nos sobre a lista completa de rotas no arranque, logo a seguir à verificação de meta guardada, e recusam arrancar com InvalidRouteMetaError (HTTP_INVALID_ROUTE_META) listando cada rota: problema. O teamsPlugin usa-o para que meta.teamRole: 'Admin' (um erro de escrita) faça falhar o arranque em vez de responder 500 no primeiro pedido. O allowUnguardedMeta nunca dispensa os validadores.

ts
const validator: RouteMetaValidator = ({ route, container }) =>
  typeof route.meta?.['shape'] === 'string' || route.meta?.['shape'] === undefined
    ? undefined
    : `meta.shape must be a string` // ou string[] para vários problemas; lançar também conta
ensureMetadata(container).add(META_VALIDATORS_BUCKET, validator)

Corres o runRoute() sem adapter? assertRoutesGuarded(routes, app.container) corre as duas verificações; assertRouteMetaValid(routes, app.container) corre só os validadores.

Um guard pode também publicar uma verificação de visibilidade pura em http:route-visibility (RouteVisibilityCheck, avaliada por isRouteVisible) — "este chamador poderia passar?" sem efeitos secundários (sem rate limit, sem auditoria, sem hooks), usada por superfícies de listagem como o tools/list do MCP. Visibilidade nunca é autorização: o guard corre sempre em cada chamada.

2. Nunca confies num tenant vindo do cliente — verifica a membership ​

Resolver o tenant ativo a partir de um header do pedido (ou subdomínio, ou path) é conveniente, mas o header é controlado pelo atacante. Ler X-Tenant-Id: acme e limitar a acme sem verificar que o utilizador autenticado pertence de facto a acme deixa qualquer utilizador com sessão ler os dados de outro tenant.

ts
// ❌ tenant vindo diretamente de um header do cliente — acesso entre tenants
const tenantId = req.headers['x-tenant-id']

// ✅ resolve, depois confirma que o utilizador é membro antes de confiar
const tenantId = req.headers['x-tenant-id']
if (!(await teams.can(tenantId, ctx().user.id, 'member'))) {
  throw new ForbiddenError()
}

Liga a seleção de tenant a uma membership user↔tenant verificada (via @basaltkit/teams, o tenantId de uma API-key, ou uma claim de sessão) — nunca apenas ao pedido em bruto.

Faz isto para todas as rotas de uma vez com tenantMembershipPlugin. Em vez de repetir a verificação, regista o guard do @basaltkit/teams: em cada pedido autenticado e com tenant resolvido, garante que o utilizador é membro do tenant e devolve 403 caso contrário. As rotas centrais que legitimamente atuam fora de um só tenant (login, criação de tenant, admin da plataforma, aceitar convite) optam por sair com meta: { central: true }.

ts
import { teamsPlugin, tenantMembershipPlugin } from '@basaltkit/teams'

createApp({
  plugins: [
    authPlugin(/* … */),
    tenancyPlugin(/* … */),
    teamsPlugin(/* … */),
    tenantMembershipPlugin(), // seguro por omissão: membership imposta em todo o lado
  ],
})

// uma rota de que o utilizador não é membro → 403; rota central sai:
route({ method: 'POST', url: '/tenants', meta: { central: true }, /* … */ })

Por omissão o guard verifica a existência de membership — qualquer registo de membership passa, por isso roles personalizados ausentes do roleRank não são rejeitados; passa role: 'member' (ou superior) para impor semântica de rank. Mais duas opções:

ts
tenantMembershipPlugin({
  // Escape baseado em QUEM chama: admins de plataforma / suporte cruzam
  // tenants legitimamente. Prefere isto a meta.central quando a exceção é
  // sobre o chamador — central desativa o guard para toda a gente nessa rota.
  exempt: ({ user }) => (user as { platformAdmin?: boolean })?.platformAdmin === true,

  // Cache de decisão opt-in: sem ela, cada pedido autenticado com tenant custa
  // um lookup indexado de membership (normalmente ok). Decisões em cache são
  // descartadas de imediato pelos hooks team:joined/role_changed/member_removed
  // no mesmo processo; ttlMs apenas limita a staleness de alterações feitas
  // NOUTRA réplica — um membro removido noutro lado pode manter acesso até ttlMs.
  cache: { ttlMs: 30_000 },
})

3. O scoping automático de tenant cobre o ORM — não SQL bruto nem escalares de chave estrangeira ​

A extensão de tenancy do Prisma limita as operações de modelo (incluindo writes de relação aninhados) e falha fechado: sem contexto de tenant, e para qualquer operação que não consegue limitar (PRISMA_UNSCOPED_OPERATION). Os dados de um update não podem mover uma linha para outro tenant (PRISMA_CROSS_TENANT_WRITE). Dois caminhos ficam fora dessa rede:

  • Queries brutas — $queryRaw, $executeRaw, $queryRawTyped, $runCommandRaw (todas as operações ao nível do client) e findRaw / aggregateRaw do MongoDB contornam o scoping de modelo. O Basalt recusa-as por omissão quando há um tenant em contexto (PRISMA_RAW_IN_TENANT), para uma query bruta não poder ler entre tenants em silêncio. Corre-as em código central (sem tenant em contexto), ou adiciona tu o predicado tenant_id = $1 e define onRawInTenant: 'allow'.
  • Escalares de chave estrangeira — connect / create aninhados são limitados, mas um valor de FK bruto (data: { projectId: body.projectId }) não é verificado, e um include segue a FK que estiver guardada. Usa chaves estrangeiras compostas (tenantId, id) (a base de dados recusa então uma ligação entre tenants) e RLS, ou verifica primeiro que o registo relacionado pertence ao tenant atual.
ts
// ❌ query bruta dentro de um contexto de tenant agora lança PRISMA_RAW_IN_TENANT
await db.$queryRaw`SELECT * FROM invoices WHERE status = ${status}`

// ✅ limita explicitamente, parametrizado, e opta por permitir
const tenantId = ctx().tenant.id
await db.$queryRaw`
  SELECT * FROM invoices WHERE status = ${status} AND tenant_id = ${tenantId}`
// com tenancyExtension({ onRawInTenant: 'allow' })

Defesa em profundidade — ativa RLS no Postgres. O scoping aplicacional é uma camada; junta uma imposta pela base de dados, para que nem um predicado esquecido vaze — incluindo o include por chave estrangeira acima, que a extensão não vê. O rlsPolicySql gera a migração, e o tenancyExtension({ rls: true }) indica o tenant ativo ao Postgres em cada operação limitada ao tenant:

ts
import { rlsPolicySql, tenancyExtension, tenantTransaction } from '@basaltkit/prisma'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL! })

// migração (uma vez): põe o SQL gerado numa migração Prisma — ativa e força
// (FORCE) o RLS e cria uma política de isolamento por tenant em cada tabela
console.log(rlsPolicySql({ tables: ['invoices', 'projects'], tenantColumn: 'tenantId' }))

// cada operação de modelo com tenant em contexto corre agora como
//   $transaction([ set_config('app.tenant_id', <tenant>, true), <operação> ])
const db = new PrismaClient({ adapter }).$extends(tenancyExtension({ rls: true }))

// transações interativas: abre-as com tenantTransaction, que define o tenant
// primeiro na própria ligação da transação — o tx continua limitado ao tenant
await tenantTransaction(db, async (tx) => {
  const invoice = await tx.invoice.create({ data })
  await tx.invoiceLine.createMany({ data: lines(invoice.id) })
})
  • Liga-te com um role a que o RLS se aplique. Superusers e roles com BYPASSRLS ignoram todas as políticas; os donos das tabelas também, a menos que a tabela tenha FORCE ROW LEVEL SECURITY (o rlsPolicySql adiciona-o por omissão). Corre a app com um role de login simples e deixa migrações/admin noutro.
  • Sem tenant não há linhas — mesmo numa ligação reutilizada. A política compara com NULLIF(current_setting('app.tenant_id', true), ''): depois de uma sessão do pool ter definido o tenant numa transação qualquer, o Postgres passa a devolver '' (não NULL), e uma comparação simples apanharia linhas cuja coluna de tenant é ''. Políticas geradas antes do @basaltkit/prisma 3.0 não têm o NULLIF — volta a correr o rlsPolicySql (idempotente) numa nova migração.
  • Custos. Cada operação limitada ao tenant passa a ser uma transação batch curta (BEGIN, set_config, a query, COMMIT) — algumas instruções extra na mesma ligação (≈ +2 ms p50 nas medições da equipa da app). A definição é local à transação (set_config(…, true)), por isso nunca vaza para uma ligação do pool.
  • Transações abertas por ti não são envolvidas (não podem ser aninhadas): um db.$transaction(async (tx) => …) interativo simples corre sem a definição do tenant e falha fechado (leituras não veem linhas, escritas falham com 42501) — usa antes tenantTransaction(db, fn). Um db.$transaction([...]) em batch tem de começar pela definição: db.$executeRawUnsafe(setTenantConfigSql(), ...tenantConfigParams(tenantId)). Essa instrução exata, para o tenant já em contexto, é a única query bruta que a guarda PRISMA_RAW_IN_TENANT deixa passar — qualquer outra continua recusada.
  • Um cliente com onMissingTenant: 'bypass' não envia a definição, por isso com RLS não vê nada: dá ao código central/admin o seu próprio role de base de dados (BYPASSRLS, ou um que as políticas não cubram).

Pesquisa full-text com RLS — o índice GIN desaparece em silêncio. Ativar RLS numa tabela que também tem uma coluna tsvector com índice GIN (o que o @basaltkit/search-postgres cria) é uma armadilha que nada assinala: o PostgreSQL só pode avaliar um qualificador antes de uma política de segurança de linha se esse qualificador for LEAKPROOF, e o operador de pesquisa de texto @@ não é. Por isso, precisamente para o role que a política protege, tsv @@ plainto_tsquery(…) nunca pode ser uma condição de índice — passa a ser um filtro aplicado depois da política, e o plano degrada-se para uma varredura sequencial sobre as linhas de todos os tenants. Medido em 30 200 documentos (PostgreSQL 16):

text
-- como owner                          -- como role da aplicação, o mesmo SQL
->  Bitmap Heap Scan                    ->  Seq Scan on basalt_search
      Recheck Cond: (tsv @@ …)                Filter: (… AND (tsv @@ …))
      ->  Bitmap Index Scan on                Rows Removed by Filter: 30197
            basalt_search_tsv_idx       Execution Time: 14.702 ms
Execution Time: 4.920 ms                                (~24x mais lento, quente)

O rlsSearchFunctionSql gera a correção: uma função de pesquisa SECURITY DEFINER que volta a aplicar ela própria o predicado do tenant, de modo que @@ volta a ser uma condição de índice enquanto as linhas que ela pode devolver continuam a ser exatamente as de um tenant.

ts
import { rlsSearchFunctionSql } from '@basaltkit/prisma'

// migração (uma vez), executada por um role que ignora o RLS da tabela
rlsSearchFunctionSql({
  name: 'basalt_search_scoped', table: 'basalt_search', vectorColumn: 'tsv',
  partitionColumn: 'idx', filterColumn: 'document',
  columns: [{ name: 'document', type: 'jsonb' }],
  role: 'app', owner: 'app_owner', maxRows: 100,
})

// runtime — o driver encaminha as queries de texto pela função
new PostgresSearchDriver({ client: pool, searchFunction: 'basalt_search_scoped' })
text
-- como role da aplicação, através da função
->  Bitmap Heap Scan on basalt_search t
      Filter: ((idx = 'notes') AND (tenant_id = NULLIF(current_setting('app.tenant_id', true), '')))
      ->  Bitmap Index Scan on basalt_search_tsv_idx
Execution Time: 1.850 ms

A função não recebe nenhum parâmetro de tenant: lê o tenant do mesmo current_setting(…) que a política lê (o que o tenancyExtension({ rls: true }) já define), por isso não há nada que um chamador possa apontar para outro lado, e uma definição por preencher lê-se como NULL — nenhuma linha, nunca todas. É endurecida como o cross-tenant scan (search_path fixado, identificadores validados, EXECUTE revogado de PUBLIC, p_limit limitado), e o driver ainda recusa qualquer linha devolvida cujo tenant não seja o que pediu.

Nunca faças ALTER FUNCTION ts_match_vq(tsvector, tsquery) LEAKPROOF. É o atalho que todos os resultados de pesquisa sugerem, e de facto traz o índice de volta — enfraquecendo a regra leakproof em toda a base de dados, para todas as tabelas e todas as políticas, de modo que um @@ bem construído passa a ser um canal lateral para sondar linhas que uma política esconde. Uma aceleração local paga com uma perda global de isolamento.

Varrer todos os tenants — o único buraco, mantido estreito. Um reconciler tem de encontrar linhas encalhadas em todos os tenants, o que com RLS o role da aplicação nunca consegue ver. O crossTenantScanSql gera a única forma segura dessa query: uma função SECURITY DEFINER que devolve apenas identificadores (id do tenant + id da linha), detida por um role que as políticas não alcançam, com o search_path fixado dentro dela e o EXECUTE revogado ao PUBLIC. O crossTenantSweep processa depois cada identificador de volta no âmbito do seu próprio tenant, onde as políticas voltam a aplicar-se:

ts
import { crossTenantScanSql, crossTenantSweep } from '@basaltkit/prisma'

// migração (uma vez): apenas identificadores — nunca uma coluna com dados do tenant
crossTenantScanSql({
  name: 'stuck_jobs', table: 'jobs', tenantColumn: 'tenantId', columns: ['id'],
  where: `t."status" = 'PROCESSING' AND t."updatedAt" < now() - interval '15 minutes'`,
  role: 'app', owner: 'app_owner', maxRows: 500,
})

// reconciler (código central, sem tenant em contexto)
await crossTenantSweep({
  client: db,
  scanFunction: 'stuck_jobs',
  run: (tenantId, fn) => tenancy.run(tenantId, fn),
  handle: (item) => RetryJob.dispatch({ jobId: item.id }),
})

A função é um bypass deliberado ao RLS, por isso trata a sua definição como crítica para a segurança: basta alargá-la a uma coluna de dados para que qualquer chamador com EXECUTE leia todos os tenants. O Basalt falha fechado à volta dela — o scan recusa correr dentro de um contexto de tenant (PRISMA_CROSS_TENANT_IN_TENANT; ao contrário do set_config interno, não tem isenção da guarda de queries brutas), recusa uma função instalada que devolva colunas que não declaraste (PRISMA_CROSS_TENANT_SCAN_SHAPE) e pagina com um cursor ordenado e limitado, para que um varrimento não puxe a tabela inteira. Sem RLS a função nem é precisa: passa uma query central normal como scan. Vê o guia do scheduler.

Na dúvida, prefere operações de modelo (limitadas automaticamente) a SQL bruto, e revê cada connect contra o tenant atual.

4. CSRF — seguro por omissão com auth por header; cookies são responsabilidade tua ​

O Basalt autentica cada pedido a partir de um header — Authorization: Bearer <jwt> ou x-session-id: <id> (ver o enricher de auth). Isto é CSRF-safe por design: um cross-site request forgery só funciona com credenciais que o browser anexa automaticamente (cookies, HTTP Basic). Um header custom nunca é enviado cross-origin num pedido forjado, por isso a página do atacante não pode aproveitar a sessão da vítima. Mantém a auth num header e não há nada a fazer.

O cookie de sessão que o authRoutes() define no login (basalt_session) está coberto pela verificação incorporada do authPlugin: um pedido só com cookie, com um método não seguro, que o browser marca cross-site/same-site, ou cujo Origin não é o teu próprio host nem uma entrada de csrf.trustedOrigins, não é autenticado (403 AUTH_CSRF_REJECTED em rotas meta.auth) — ver Sessões por cookie e CSRF.

Assumes tu o risco de CSRF no momento em que moves uma credencial para um cookie teu — p. ex. guardar o JWT num cookie para o browser o enviar automaticamente. Se o fizeres, protege-o tu:

  • Define o cookie SameSite=Lax (ou Strict), HttpOnly e Secure. Só o SameSite=Lax já trava o POST cross-site comum.
  • Acrescenta uma segunda verificação para pedidos que alteram estado: um token CSRF double-submit (um valor aleatório espelhado num cookie e num header/campo do body, comparados no servidor), ou uma allow-list de Origin/Referer.
  • Nunca contes com o CORS para isto — o CORS governa a leitura de uma resposta, não se um pedido forjado é enviado. Um POST de formulário dispara à mesma.
ts
// ✅ preferido — sem cookie, sem superfície de CSRF
fetch('/api/pay', { method: 'POST', headers: { authorization: `Bearer ${jwt}` } })

// ⚠️ se tiveres mesmo de usar sessão em cookie, junta SameSite + verificação de token CSRF
setCookie('sid', session.id, { httpOnly: true, secure: true, sameSite: 'lax' })

Revisão de segurança das rotas — basalt routes ​

basalt routes lista cada rota com as guardas que declara: auth, can, rateLimit, tenant e as outras chaves guardadas (mfa, teamRole, scopes, subscribed, feature). A coluna tenant mostra required (meta.tenant: true), exempt (meta.tenant: false), central-only (meta.tenant: 'never' — a rota rejeita qualquer pedido que resolva um tenant), ou fica vazia quando a rota herda o default da app. A coluna reflete só o meta.tenant: o meta.central: true (o bypass de membership do @basaltkit/teams) aparece na coluna de guardas como central; verifica row.tenant === 'central-only' para fixar uma rota de consola ao plano central. Duas formas de transformar isso num controlo:

bash
# CI: termina com 1 quando uma rota não declara auth e can (opt-outs explícitos passam)
pnpm basalt routes --unguarded --require=auth,can --allow='POST /webhooks/*'
pnpm basalt routes --json > routes.json   # a tabela inteira, para rever ou comparar
ts
// Um teste vitest que arranca a app (sem listen) e verifica as mesmas linhas
import { ensureMetadata } from '@basaltkit/core'
import { describeRoutes, findUnguardedRoutes } from '@basaltkit/http'

it('todas as rotas declaram auth + can', async () => {
  const app = await buildApp().boot()
  const rows = describeRoutes(ensureMetadata(app.container).get('http:routes'))
  expect(findUnguardedRoutes(rows, { require: ['auth', 'can'] })).toEqual([])
  await app.shutdown()
})

auth: false (ou public: true) é um opt-out intencional e satisfaz os dois requisitos; can: false satisfaz can. Só auth: true conta como auth — é o único valor que o authPlugin aplica. Só verifica o meta das rotas: um rate limit global, tenancy por URL (tenancyPlugin({ required: { except } })), hooks ou middleware da app, e as rotas de borda que os plugins montam sozinhos (healthPlugin, metricsPlugin, openapiPlugin) não aparecem — um resultado limpo significa "todas as rotas pedem protecção"; é a verificação no arranque descrita acima que garante que há um guard a aplicá-la.

Apanha regressões automaticamente — ai:doctor ​

O basalt ai:doctor verifica estaticamente o teu projeto contra os invariantes de segurança do framework — offline, sem chave de API. Duas verificações codificam as garantias mais importantes deste guia:

  • missing-tenant-membership (erro) — tens tenancy + auth mas nenhum tenantMembershipPlugin (com ou sem o @basaltkit/teams instalado — se não estiver, a correção é instalá-lo), por isso um tenant resolvido nunca é ligado a um membro verificado. É a classe de acesso cross-tenant da secção 2.
  • missing-security-plugin (aviso) — sem securityPlugin(), as respostas saem sem cabeçalhos seguros.
bash
basalt ai:doctor      # corre-o em CI para falhar o build numa regressão de segurança

Liga-o ao teu pipeline para que uma mudança que remova o guard de membership ou o security plugin ponha o build vermelho em vez de ir para produção.

Cadeia de fornecimento ​

O CI corre pnpm audit (severidade alta), CodeQL SAST, e o Dependabot mantém dependências e Actions atualizadas. Os releases publicam no npm com provenance (NPM_CONFIG_PROVENANCE) via changesets — sem tokens manuais ou OTP no pipeline.

Publicado sob a licença MIT.