@evertonferreira96/agents 0.0.0-stage → 0.1.0

package/.claude/skills/arch-api/references/endpoints.md

@@ -0,0 +1,184 @@
+# Templates por tipo de endpoint
+
+Abra ao decidir o formato de um endpoint novo (verbo, path, status, erros, autorização, persistência) ou ao conferir um endpoint antes do PR. Nomes são exemplos; o vocabulário do domínio vem do repo. Cada template assume o padrão de props/exec do `SKILL.md` e de `contract.md`.
+
+---
+
+## 1. Templates
+
+### 1.1 GET detalhe
+
+```txt
+Path         /customers/:customerId/invoices/:invoiceRef       (ref = id ou código legível, se o domínio tiver)
+operationId  getInvoiceByRef        status 200 (ok)          erros ...docs.response
+Response     { data: InvoiceDetail }                          detalhe nomeado em entities
+Service      resolve o pai (404) -> assertCanRead* -> port.find*Detail -> assert*Visible (404) -> mapper
+Adapter      leitura por id/código + tenant, relacionados agregados na mesma query
+```
+
+404 x 403 para o recurso que o leitor não pode ver: regra 9 do `SKILL.md`, detalhe em `domain.md` §3.
+
+### 1.2 GET lista
+
+```txt
+Path         /customers/:customerId/invoices
+operationId  listCustomerInvoices   status 200               erros ...docs.response
+Query        paginationQuery.extend({ ...filtros, sort: <Domain>ListSort, direction }).strict()
+Response     paginatedResponse(invoiceSummarySchema)          { data, meta }
+Service      resolve o pai -> assertCanRead* -> viewerOf -> port.list* -> mapper por item
+Adapter      build*Queries: página + contagem com o mesmo WHERE; sort por mapa; tiebreaker por id; toPaginationMeta
+```
+
+Offset para telas administrativas pequenas e médias. Feed, log e linha do tempo: cursor keyset opaco (`nextCursor`), `limit + 1` decide se há próxima página.
+
+### 1.3 POST criar
+
+```txt
+Path         /customers/:customerId/invoices
+operationId  createInvoice          status 201 (created)     erros ...docs.response + ...docs.unprocessable (+ ...docs.conflict)
+Body         CreateInvoiceBodyRequest (.strict()); opcionais com default de negócio decidido no service
+Response     { data: InvoiceDetail }                          o detalhe recém-criado, mesmo schema do GET
+Service      resolve -> assertCanActOn*(…, 'create') -> estado (422) -> referências (422 <domain>.reference_invalid) -> rules -> New* -> port.create* -> detalhe
+Adapter      uma transação: sequência/código, linha, filhos, audits; constraint -> 409/422 com code
+Idempotência obrigatória quando duplicar causa dano (Idempotency-Key, domain.md §9)
+```
+
+### 1.4 PATCH atualizar parte
+
+```txt
+Path         /customers/:customerId/invoices/:invoiceId
+operationId  updateInvoice          status 200               erros ...docs.response + ...docs.conflict (+ ...docs.unprocessable)
+Body         UpdateInvoiceBodyRequest: campos opcionais + version (lida pelo client)
+Service      resolve -> access -> monta *Write.set só com os campos enviados (undefined = não mexe; null = limpa) -> port.write*
+Adapter      updateMany com version no where; 0 linhas = 409 <domain>.stale; audit com previous/current
+Response     { data: InvoiceDetail } ou { data, meta: { version } }, conforme o vizinho
+```
+
+Não reutilize o schema de criação quando os obrigatórios diferem.
+
+### 1.5 PUT substituir
+
+```txt
+operationId  replace<Coisa> ou set<Coisa><Relação> (ex.: setInvoiceTags)    status 200
+Body         a coleção ou o recurso inteiro; o que não vier é removido
+Adapter      substituição na mesma transação (remove o que saiu, insere o que entrou)
+```
+
+Se a API não quer semântica de substituição, use PATCH.
+
+### 1.6 DELETE
+
+```txt
+operationId  delete<Coisa>        status 204 (noContent)   sem content no documento
+Service      access + estado (recurso em uso = 409/422 com code)
+Adapter      soft delete quando há auditoria, histórico ou relacionamento crítico (arch-db)
+```
+
+### 1.7 POST ação ou comando
+
+```txt
+Path         /customers/:customerId/invoices/:invoiceId/<acao>     ex.: cancel, approve, assign, move
+operationId  <acao><Coisa>        status 200, 202 ou 204 conforme a semântica
+Service      access da ação específica + transição permitida (rules) + version
+Adapter      write + audit da transição na mesma transação
+```
+
+Transição de estado com regra não é PATCH genérico. Avalie idempotência sempre.
+
+### 1.8 Upload
+
+```txt
+Fluxo        pela capacidade de storage do repo (common/storage), em rota ou fluxo próprio
+Limite       tamanho máximo explícito da rota; nunca subir o limite global
+Validação    mime type, extensão, tamanho, quantidade
+Response     { data: <Arquivo>Response }
+```
+
+### 1.9 Download
+
+```txt
+Response     content-type real (application/pdf, text/csv, application/octet-stream ...)
+Headers      Content-Type, Content-Disposition, Cache-Control quando aplicável
+Auth         access antes de gerar URL ou stream
+Grande       streaming ou URL assinada pela capacidade de storage
+```
+
+### 1.10 Público
+
+```txt
+Documento    security: [] no registerPath (regra 8 do SKILL.md, contract.md §1)
+Runtime      sem AuthUserGuard (ou OptionalAuthUserGuard se personaliza)
+Rate limit   guard dedicado obrigatório em login, cadastro, recuperação e busca
+Dados        nada sensível; cache avaliado em GET público
+```
+
+### 1.11 Protegido com tenant
+
+```txt
+Documento    security bearer; o header de contexto documentado se o client o envia
+Runtime      AuthUserGuard + @<Tenant>Ref() (nunca lança)
+Service      resolver do tenant (recusa inexistente, removido, cancelado) -> access com ator + tenant + recurso
+Adapter      toda query filtrada pelo tenant
+```
+
+### 1.12 Assíncrono
+
+```txt
+Status       202 (accepted)           Response   { data: { jobId, status } }
+Fluxo        service grava o pedido de trabalho (e outbox, se o evento não pode se perder) -> fila -> <assunto>.worker.ts
+Idempotência geralmente obrigatória    Log    jobId + traceId
+```
+
+---
+
+## 2. Checklist de endpoint novo
+
+Cada item aponta a regra (`SKILL.md`, "Regras não negociáveis") ou a seção que o explica.
+
+```txt
+Contrato
+- [ ] props e exec planos em surfaces/, nomes <acao>.<domain>.*.surface.ts           SKILL "Nomes"
+- [ ] registerOpenApi + .openapi(nome) + openapi.register em todo schema da operação contract.md §1
+- [ ] operationId camelCase único; tag existente no build                              contract.md §1
+- [ ] description lista cada code de 409/422 e a permissão                             regra 7
+- [ ] blocos de erro só os que ocorrem                                                 regra 7
+- [ ] .strict() em params, query e body; datas ISO string                               regras 4, 6
+- [ ] security = guard                                                                 regra 8
+- [ ] extensões x-* do repo preenchidas, se houver                                     contract.md §1
+
+Exec
+- [ ] @Controller() + path do decorator = Endpoint sem a barra                         regra 1
+- [ ] @HttpCode = status de sucesso do props; Zd* com instructions                     contract.md §3
+- [ ] só guards, pipes e um execute                                                    regra 2
+
+Service e domínio
+- [ ] um <Acao>Service por arquivo; type Input escrito à mão                           regra 3
+- [ ] access antes de qualquer escrita; 404 x 403 decidido                             regra 9
+- [ ] regra pura em *.rules.ts com spec                                                domain.md §2
+- [ ] resposta pelo mapper, validada contra o schema no spec                           review.md §1
+
+Persistência
+- [ ] port com tipos escritos à mão                                                    regra 10
+- [ ] adapter: transação dentro, constraints no mapa de -db-errors                     regra 14
+- [ ] SQL parametrizado em <domain>.sql.ts; sort por mapa + tiebreaker                 regra 12
+- [ ] migration e índice revisados com arch-db                                         regra 16
+
+Fiação e entrega
+- [ ] exec em controllers, service em providers, import do props no surface.module     domain.md §8
+- [ ] port novo ligado no <domain>.sgbds.module e exportado                            domain.md §8
+- [ ] doc.md atualizado (endpoint x rota x permissão, regras, escrita)                 regra 17
+- [ ] openapi:generate, check-types, lint e testes verdes                              SKILL "Comandos"
+- [ ] mudança de contrato classificada                                                 contract.md §8
+- [ ] rate limit, idempotência e timeout de provider avaliados quando críticos         security.md §3, §9
+```
+
+---
+
+## 3. Prontidão de produção
+
+```txt
+Contrato     documento gerado e versionado; client regenerado compila; breaking change avaliado
+Segurança    401 sem token e 403/404 sem acesso testados; cross-tenant testado; nada sensível no log ou no response
+Operação     logs estruturados com traceId; timeout e retry em provider externo; idempotência onde duplica
+Dados        transação nos multi-writes; constraint para cada invariante; listas com teto; audit nos writes sensíveis
+```

package/.claude/skills/arch-api/references/review.md

@@ -0,0 +1,228 @@
+# Testes, revisão e entrega
+
+Abra ao escrever testes, ao abrir um domínio novo, ao planejar a migração de um projeto existente para este padrão, ao registrar uma decisão transversal (ADR) ou ao revisar um PR de API. O que é obrigatório em todo endpoint está no `SKILL.md` ("Criando um endpoint" e "Critério de aceite").
+
+---
+
+## 1. Testes
+
+### Onde fica cada um
+
+```txt
+services/<acao>.service.spec.ts         unit do caso de uso, com port e policy falsos (o grosso da suíte)
+services/<assunto>.rules.spec.ts        unit da regra pura, sem double
+services/<domain>-access.spec.ts        matriz ação x permissão x estado
+services/<domain>.fixtures-spec.ts      ids fixos, fábricas de record, fakeRepository, fakePolicy
+adapters/<tecnologia>.<domain>.repository.adapter.spec.ts   tradução de constraint, montagem de SQL, contra banco real quando o repo tiver
+common/utils/<tipo>/<nome>.<tipo>.unit.spec.ts               helper puro
+test/e2e/<assunto>.e2e.spec.ts          app Nest inteira: guards, pipes, filter, rota, documento
+libraries/test/                         configs do runner por tipo (unit, integration, e2e)
+```
+
+O sufixo `-spec` (sem ponto) não casa com o glob usual `*.spec.ts`: a fixture é importada pelos specs e não roda como suíte. Confira o glob do runner do repo antes de criar uma.
+
+### Service spec
+
+```ts
+import { describe, expect, it } from 'vitest'; // runner do repo
+import { instructions as createContract } from '../surfaces/create-invoice.invoices.props.surface';
+import { ACTOR, CUSTOMER, ITEM, customerAccess, customerRecord, fakePolicy, fakeRepository } from './invoices.fixtures-spec';
+import { CreateInvoiceService } from './create-invoice.service';
+
+function setup(options: Parameters<typeof fakeRepository>[0] = {}, access = customerAccess(['invoices:create'])) {
+  const fake = fakeRepository(options);
+  const service = new CreateInvoiceService(fake.repository as never, fake.resolver, fakePolicy(access) as never);
+  return { ...fake, service };
+}
+
+describe('CreateInvoiceService', () => {
+  it('cria com audit e devolve o contrato', async () => {
+    const { service, repository } = setup();
+    const result = await service.execute({ actorId: ACTOR, customerId: CUSTOMER, items: [ITEM] });
+    expect(repository.createInvoice.mock.calls[0][0]).toMatchObject({ customer: CUSTOMER, createdBy: ACTOR });
+    const parsed = createContract.settings.response.body.safeParse(result);
+    expect(parsed.success, JSON.stringify(parsed.error?.issues)).toBe(true);
+  });
+
+  it('cliente bloqueado = 422 invoice.customer_blocked, sem escrita', async () => {
+    const { service, repository } = setup({ customer: customerRecord({ status: 'BLOCKED' }) });
+    await expect(service.execute({ actorId: ACTOR, customerId: CUSTOMER, items: [ITEM] }))
+      .rejects.toMatchObject({ response: { code: 'invoice.customer_blocked' } });
+    expect(repository.createInvoice).not.toHaveBeenCalled();
+  });
+});
+```
+
+- **Instancie o service com `new`** e os doubles da fixture; o teste não sobe o Nest.
+- **Valide o retorno contra `instructions.settings.response.body`** em pelo menos um caso por service: é o teste de contrato mais barato que existe.
+- **Assert por `code`** (`rejects.toMatchObject({ response: { code } })`), nunca por mensagem.
+- Callbacks passados ao port (audits) são chamados no teste com um id fictício e afirmados.
+- O double do port nasce na fixture do domínio; método novo no port entra na fixture no mesmo PR.
+
+### Mínimo por endpoint
+
+```txt
+- [ ] service: caminho feliz + retorno válido contra o schema de resposta
+- [ ] service: cada code novo, com o status certo, e sem escrita quando recusa
+- [ ] access: quem pode, quem não pode, estado que bloqueia, 404 x 403
+- [ ] rules: limites e casos de borda da regra pura
+- [ ] adapter (se mudou SQL ou tradução): filtro ausente não filtra; sort fora da whitelist não chega ao SQL; constraint vira o code
+- [ ] e2e de grupo crítico: 401 sem token, 403/404 sem acesso, 400 com campo extra (.strict()), sucesso
+- [ ] multi-tenant: recurso de outro tenant não vaza
+- [ ] sessão (se houver cache de sessão): revogação não autoriza com o cache fora
+```
+
+---
+
+## 2. Domínio novo
+
+1. **Inventário** do `SKILL.md` ("Antes de editar") mais: tabelas que o domínio lê e escreve, permissões existentes e novas, domínios de que depende e quem vai consumi-lo.
+2. **Plano mínimo**, antes do código:
+
+```txt
+1. Recursos e endpoints, com o template de cada um (endpoints.md)
+2. Contrato de cada endpoint: status, security, permissão, codes de 409/422
+3. Schemas de entities (params, filtros, sort, item, detalhe)
+4. Services, rules e access; o que vai para *-context.ts e *.resolver.ts
+5. Port e adapter; o que é leitura quente em SQL; transações e constraints
+6. Tabelas, índices e migrations com arch-db; permissões novas no catálogo e na seed
+7. Idempotência, outbox, rate limit, timeout de provider
+8. Testes por camada
+```
+
+3. **Scaffold**, se o repo tiver, com as condições do passo 1 de "Criando um endpoint" no `SKILL.md`; substitua cada stub pelo padrão dos vizinhos.
+4. **`doc.md`** nasce junto, com este esqueleto:
+
+```md
+# <Domain> Module
+
+## Overview
+O que o domínio faz e o que não é dele (com o módulo dono de cada vizinho).
+
+## Status
+| Endpoint | Rota | Permissão |
+| --- | --- | --- |
+| `listCustomerInvoices` | `GET /customers/:customerId/invoices` | ler o cliente |
+
+## Autorização (`services/<domain>-access.ts`)
+Policy usada, mapa de ações, visibilidade (o que vira 404), estados que bloqueiam escrita.
+
+## Regras (puras, testadas)
+Um item por `*.rules.ts`: o que decide e os codes que lança.
+
+## Escrita
+Transações, lock otimista, sequências, audits gravados.
+
+## Persistência
+Port -> adapter; o que é SQL (`<domain>.sql.ts`) e o que é ORM; constraints traduzidas.
+
+## Depois
+Pendências e dívidas conhecidas.
+```
+
+---
+
+## 3. Migração de projeto existente (ondas)
+
+**Onda 1, contrato e client**: `operationId` camelCase e estável; schemas nomeados com `register`; `security` = guard; datas ISO; blocos de erro só onde ocorrem; `code` em todo 409/422.
+
+**Onda 2, exec fino**: `Zd*` com `instructions`; tipos `Instruction.*`; regra, SQL e try/catch saem do controller para o service; um service por caso de uso.
+
+**Onda 3, domínio e persistência**: access por domínio; port com tipos escritos à mão no lugar do repositório genérico do scaffold; transação dentro do adapter; `-db-errors` com mapa de constraints; SQL parametrizado com sort por mapa.
+
+**Onda 4, segurança e plataforma**: TTL e revogação de sessão; backdoors removidos; CORS, limite de body, `trust proxy` e docs fail-closed; env completo no schema; exceções de domínio no lugar das do Nest.
+
+**Onda 5, governança**: `openapi:generate` + `git diff --exit-code` no CI; e2e por grupo crítico; idempotência e timeout/retry onde faltam; `doc.md` em todo domínio.
+
+Melhoria localizada, sem ADR:
+
+- **Rota pública marcada como pública no documento.** Onde o vizinho público só omite `security`, a operação herda o `security` global do build e o documento a mostra como protegida: acrescente `security: []` no `registerPath` (e corrija o template do scaffold, se ele gerar a omissão).
+
+Melhorias que mudam o padrão e pedem ADR antes:
+
+- **Centralizar o path do exec.** Hoje o path é literal repetido no decorator. Alternativa: derivar do props (`@Controller(instructions.settings.endpoint)` com subrotas declaradas no contrato) ou um decorator que aplica `instructions` ao método. Muda o scaffold e todas as surfaces; enquanto não muda, a trava é a paridade ou o e2e.
+- **Checagem de paridade rota x documento** no gate, quando o repo não tem: lista as rotas registradas no Nest e compara com as operações do `openapi.json`.
+- **Correlação antes dos guards.** Gerar o `traceId` num middleware para que 401, 403 e rate limit também saiam com ele (`security.md` §8).
+
+---
+
+## 4. ADR
+
+Crie ADR quando a decisão afeta mais de um endpoint, módulo ou time:
+
+```txt
+mudar envelope global ou formato de erro (inclusive o formato do code)
+mudar auth, JWT ou estratégia de sessão
+introduzir multi-tenancy ou mudar como o tenant é resolvido
+trocar ORM, driver ou a divisão escrita x leitura entre eles
+introduzir outbox, fila ou estratégia de eventos
+mudar paginação padrão ou versionamento
+mudar o scaffold ou a forma de props/exec
+expor a API para consumidor externo
+```
+
+Se o repo tem `docs/adr` (ou equivalente), siga o formato e a numeração de lá. Senão, template mínimo:
+
+```md
+# ADR: <título>
+
+## Contexto
+## Decisão
+## Alternativas consideradas
+## Consequências positivas
+## Consequências negativas
+## Plano de migração
+```
+
+Alternativas, cada uma com o motivo real do descarte, dão valor ao ADR meses depois. Consequências negativas são obrigatórias: ADR sem custo declarado é justificativa, não decisão.
+
+---
+
+## 5. Scorecard de PR
+
+Nota mínima recomendada 8/10. Mudança crítica (auth, permissões, migration, contrato público) busca 9+.
+
+| Critério | Peso | Pergunta |
+|---|---:|---|
+| Contrato | 2 | props e exec batem? schemas nomeados? `code` de 409/422 declarados? documento regenerado? |
+| Arquitetura | 1 | exec fino, um service por caso de uso, access no domínio, port sem tipo do ORM, transação no adapter? |
+| Segurança | 2 | guard = `security`, access antes da escrita, tenant, `.strict()`, rate limit, nada sensível no log? |
+| Performance | 1 | lista com teto e tiebreaker, sort por mapa, sem N+1, payload limitado, timeout? |
+| Observabilidade | 1 | erro com `code` estável, log estruturado, audit em write sensível? |
+| Testes | 1 | service com contrato e cada `code`, rules, access, e2e do grupo crítico? |
+| Compatibilidade | 1 | breaking change classificado, inclusive mudança de `code`? |
+| Operação | 1 | idempotência, outbox, retry e falha de provider avaliados? `doc.md` atualizado? |
+
+```txt
+0-6  não aprovar
+7    aprovar só se baixo risco e com dívida registrada
+8    bom, aprovar com pequenos ajustes
+9    padrão forte para produção
+10   referência para outros domínios
+```
+
+---
+
+## 6. Checklist final antes de entregar
+
+```txt
+- [ ] O domínio segue a estrutura e os sufixos dos vizinhos?
+- [ ] Não inventei helper, decorator, guard ou exceção que já existia em common/?
+- [ ] props e exec batem (path, verbo, status, security, schemas)?
+- [ ] Todo schema que vira tipo no client tem nome e register?
+- [ ] O access autoriza o recurso antes de qualquer escrita?
+- [ ] Tenant isolado em toda query?
+- [ ] A resposta passa pelo mapper e expõe só o necessário?
+- [ ] Lista com teto, sort por mapa, tiebreaker e meta pelo helper?
+- [ ] Multi-write em uma transação no adapter, sem chamada externa dentro?
+- [ ] Toda constraint que o write pode violar vira code?
+- [ ] Provider externo atrás de port, com timeout?
+- [ ] Testes do mínimo por endpoint criados ou atualizados?
+- [ ] openapi:generate, check-types, lint e testes verdes?
+- [ ] Breaking change classificado?
+- [ ] Migration revisada com arch-db?
+- [ ] doc.md atualizado?
+- [ ] Comandos do package.json usados, não inventados?
+```
+
+Item que não se aplica: registre como "não aplicável" com o motivo técnico.

package/.claude/skills/arch-api/references/security.md

@@ -0,0 +1,151 @@
+# Segurança, erros e operação
+
+Abra ao mexer em autenticação, sessão, guards, rate limit, tenant, configuração do bootstrap, formato de erro, logs ou integração externa, e ao revisar um endpoint contra o checklist OWASP. As regras curtas estão no `SKILL.md` (regras 7 a 9 e 15); onde cada peça mora está em `common.md`.
+
+---
+
+## 1. Configuração fail-closed
+
+- **Docs só com literal `'true'` e fora de produção**: `OPENAPI_ENABLED === 'true' && <modo> !== <produção>`. A forma `!== 'false'` faz o contrário: um deploy que esquece a flag expõe a superfície inteira. Compare o modo **normalizado** (o schema de env normaliza aliases, `common.md` §3); comparar o `process.env` cru com um alias deixa os docs ligados quando o valor vem na forma canônica.
+- **CORS por lista explícita** vinda do env (separada por vírgula), com `credentials: true`; nunca `origin: '*'` com credentials. CORS aberto numa API de autenticação transforma um XSS em qualquer domínio em roubo de sessão.
+- **`trust proxy` pelo parser do repo, default loopback.** Configure só os saltos que são seus (número de saltos ou sub-redes). `true` confia na cadeia inteira: o cliente forja `X-Forwarded-For`, escapa do rate limit e falsifica o IP do log.
+- **Limite de body explícito** no bootstrap. Upload grande vai por rota ou fluxo próprio (capacidade de storage), não aumentando o limite global.
+- **Segredo com tamanho mínimo validado no schema.** Segredo curto assina igualmente bem e é quebrável offline. Nenhum segredo em arquivo versionado; `.env.example` só com placeholder.
+- `x-powered-by` desligado; `helmet` ligado (CSP desligada só se a API não serve HTML próprio além da UI de docs).
+- Comportamento sem uma configuração opcional é decidido e escrito no `describe` da env: fail-open só onde a falha não abre acesso; o resto, fail-closed ou flag explícita.
+
+---
+
+## 2. Sessão e token
+
+- Access token com TTL curto; refresh com teto absoluto de sessão (o refresh não estende além dele). Os valores vêm do env, com `.positive()`.
+- O refresh **rotaciona** a cada uso; reapresentar um refresh já usado fora de uma janela de graça curta é tratado como roubo e revoga todas as sessões do usuário. É contrato: os clients renovam num ponto único, com dedupe de concorrentes (`arch-web`: `proxy.ts`; `arch-app`: `authedRequest`). Mudar a janela ou a regra pede ADR.
+- Quando a reação esperada do client é diferente (renovar token x fazer login de novo), o 401 distingue os dois casos de forma estável e documentada; um 401 único obriga o client a adivinhar e desloga quem só precisava renovar. Se o shape de 401 do repo não tem `code`, registre a lacuna: acrescentar `code` muda o formato de erro e pede ADR (`review.md` §4).
+- **Revogação nunca fica fail-open por indisponibilidade de cache.** Se a validade da sessão é lida de um cache na frente do banco, miss, timeout ou cache fora caem no banco; não existe caminho em que a ausência do cache autorize uma sessão revogada. Teste dedicado obrigatório.
+- Se o repo versiona sessão ou permissão no token, toda mudança de acesso invalida o token corrente; endpoint que grava permissão ou vínculo sem invalidar deixa acesso revogado valendo até o token expirar.
+- Login com provedor externo valida o `aud` contra uma lista do env; sem a lista, o login falha fechado.
+- **Proibido, sem exceção**: senha mestra, coringa ou backdoor (qualquer código no caminho de autenticação que aceite valor fixo no lugar do hash) e comparação de senha fora do provider de hash. O caminho legítimo é impersonation auditada, com permissão própria e escopo limitado.
+
+---
+
+## 3. Guards e autorização
+
+O guard autentica e limita taxa; a autorização por recurso é do access (regra 9 do `SKILL.md`, mecânica em `domain.md` §3), e o adapter só filtra a leitura pelo `viewer` que o access produziu.
+
+- Por que sem guard global de autenticação (regra 8 do `SKILL.md`): ele obriga rotas públicas a se marcarem com `@Public()`, e esquecer o decorator numa rota nova só aparece em produção.
+- `AuthUserGuard` estende o guard do passport com a estratégia JWT de `common/auth/`; `OptionalAuthUserGuard` deixa passar sem token e entrega o usuário quando há.
+- **Rate limit por guards dedicados** (na referência, um para rotas de autenticação e um para escrita). Rota de login, cadastro, recuperação de senha, busca, exportação, upload e integração recebe o guard que o vizinho equivalente usa. Se o repo tem throttling global, mantenha-o e ajuste a janela por rota sensível. Storage em memória conta por réplica (teto efetivo = N x configurado); quando precisar ser exato, troque por storage compartilhado sem tocar em controller.
+- Guard novo só quando a regra é transversal e HTTP-aware. Guard com configuração é fábrica com parâmetro obrigatório; nunca `SetMetadata` + `Reflector`, porque quem esquece a metadata anexa um guard que lê `undefined` e libera a request.
+- O 403 **não diz qual permissão faltou**: isso ensina a superfície de permissões a quem sonda. A lista requerida vai só para o log.
+- Catálogo de chaves de permissão e onde entra uma permissão nova: `domain.md` §3.
+
+---
+
+## 4. Contexto HTTP
+
+IP, user agent, id de correlação, idempotency key e referência de tenant são extraídos por decorators (`contract.md` §4) para o service receber dado, não o `Request`. Decorator de contexto opcional devolve `undefined` quando não dá para afirmar o valor (header malformado não derruba a request com 500). Se persistir IP, normalize IPv4 mapeado em IPv6 (`::ffff:10.0.0.5` -> `10.0.0.5`).
+
+---
+
+## 5. Multi-tenancy
+
+```txt
+- tenant de operação sensível nunca vem só do body
+- a referência do tenant ativo vem de fonte confiável (token, ou header lido por @<Tenant>Ref() que nunca lança)
+- o service resolve a referência por um resolver que recusa tenant inexistente, removido ou cancelado
+- o access valida ator + tenant + recurso; tenant encerrado não aceita escrita (403)
+- toda query sensível filtra pelo tenant; buscar só por id é vazamento
+- testes cobrem acesso cross-tenant
+```
+
+```ts
+// ruim: recurso só por id em sistema multi-tenant
+repository.findInvoice(invoiceId)
+// bom: id + tenant resolvido do contexto confiável
+repository.findInvoice(tenant.id, invoiceId)
+```
+
+RLS, índice com a coluna de tenant e FK composta: `arch-db`.
+
+---
+
+## 6. Checklist OWASP por endpoint
+
+- **BOLA**: o access confere o recurso específico, não só a permissão funcional.
+- **BFLA**: a ação está no mapa `<DOMAIN>_ACTIONS` com as permissões certas.
+- **Tenant isolation**: nunca confiar só no id de tenant enviado pelo cliente.
+- **Mass assignment**: regra 4 do `SKILL.md`, e o schema de input não declara campos internos (`role`, `status`, `tenant`, `createdBy`) sem regra explícita.
+- **Excessive data exposure**: resposta pelo mapper, só o necessário.
+- **Abuso**: rate limit, `Idempotency-Key` e limite de payload avaliados.
+
+```txt
+AuthN   [ ] público ou protegido explícito?  [ ] guard runtime = security do contrato?
+AuthZ   [ ] access chamado antes da escrita?  [ ] tenant e estado validados?
+        [ ] actorId vem do token, nunca do body?  [ ] mudança de acesso invalida o token corrente?
+Input   [ ] .strict() em params, query e body?  [ ] texto e arrays com .max()?  [ ] update campo a campo?
+Output  [ ] sem hash, token, causa técnica ou PII de terceiro?
+Abuso   [ ] rate limit cobre?  [ ] idempotência e replay avaliados?  [ ] 403/404 não vira oráculo de existência?
+```
+
+---
+
+## 7. Erros
+
+Shape em `common/schemas/errors.ts`:
+
+| Status | Corpo |
+|---|---|
+| 400 | `{ statusCode, message, errors?, traceId? }`; `errors` traz o detalhe da validação do pipe |
+| 401, 403, 404 | `{ statusCode, message, traceId? }` |
+| 409 | `{ statusCode, message, code?, traceId? }`; `code` quando a operação informa (ex.: `invoice.stale`) |
+| 422 | `{ statusCode, message, code, details?, traceId? }`; `code` obrigatório |
+| 500 | mensagem genérica; nada de causa |
+
+- O client decide comportamento por `code` (e por status), nunca por `message`; `message` é para humano, no idioma do produto, e pode mudar. Por isso mudar um `code` é major (`contract.md` §8).
+- `details` carrega só o que a tela precisa para reagir (campos faltando, campo e motivo); causa técnica vai para o log.
+- Lance exceções de domínio de `common/http/errors` (`common.md` §4): elas carregam o corpo no shape acima. Exceção nova (outro status ou campo) muda a exceção, o schema de erro e o bloco de `response.docs.ts` juntos, com teste do shape.
+- Erro do banco passa por `<domain>-db-errors` e `rethrowDbError` (`domain.md` §6): nunca SQL, stack, nome de tabela ou constraint, nem valor de outra pessoa no response.
+- 4xx é esperado e documentado; 5xx é genérico para o cliente e detalhado só no log.
+
+---
+
+## 8. Observabilidade
+
+O interceptor de correlação lê o header de correlação (ou gera um id), mede a duração e loga o desfecho; o filter de exceções do repo (na referência, um logger de exceções HTTP) cobre o que o interceptor não vê.
+
+```txt
+http_request_completed   traceId, method, route (template), statusCode, durationMs, actorId
+http_request_failed      os mesmos + errorName, error, statusCode, response da exceção, cause { code, message, meta }, stack (primeiras linhas)
+```
+
+- **Ordem do Nest**: middleware -> guards -> interceptors -> pipes -> handler. O interceptor envolve pipes e handler (vê o 400 de validação), mas não roda quando um guard recusa: 401/403 e rate limit dependem do filter para log e não ganham o `traceId` do interceptor. Item de revisão quando o suporte precisar correlacionar essas recusas: gerar o id num middleware (`review.md` §3).
+- Log estruturado (JSON), nunca texto solto como única fonte; `tenant` no log quando permitido.
+- **Nunca logar**: senha, token, refresh token, `Authorization`, cookie de sessão, segredo, documento sensível, cartão, payload confidencial completo, resposta integral de provider com PII.
+- Propague o id de correlação para adapters externos quando o provider aceitar.
+- Métricas e tracing, se o repo tiver: contagem e duração por operação e status, erros por `code`, latência e erro por provider externo; nenhum segredo em atributo de span.
+- Write sensível grava audit (`actorId`, ação, entidade, `previous`, `current`, `metadata`) na mesma transação (`domain.md` §1). Audit não substitui log técnico nem evento de domínio.
+
+---
+
+## 9. Resiliência de integrações externas
+
+O service não conhece HTTP client, URL, header, SDK ou payload do provider: ele injeta um port (`common/<capacidade>` ou `ports/<x>.provider.port.ts` no domínio).
+
+```ts
+export abstract class IPaymentProvider {
+  abstract createPayment(input: CreatePaymentInput): Promise<CreatePaymentOutput>;
+}
+```
+
+Todo adapter externo declara a política antes do merge:
+
+```txt
+Provider:  Operação:  Timeout:  Retry:  Backoff:  Circuit breaker:
+Idempotente?:  Erros mapeados:  Métricas/logs:  Fallback:
+```
+
+- **Timeout explícito em toda chamada externa.**
+- Retry só em erro transitório e operação idempotente; nunca retry cego em POST não idempotente. Não retentar 400/401/403/404; avaliar 408/429/5xx com backoff e teto.
+- Circuit breaker para provider instável ou crítico.
+- Chamada ao provider fora da transação (regra 14 do `SKILL.md`); quando o efeito não pode se perder, outbox (`domain.md` §9).
+- Erro de provider não vaza cru: timeout -> 504 ou erro de domínio; indisponível -> 503; validação -> 422/400; conflito -> 409; sempre com `code` quando o client precisa reagir.