[GabrielMachado11]

Contexto

Encontrado em teste da unidade naked do tim-network-adapter. Uma API key válida que não tem auth.api_key.validate recebe 403 do wave-auth-api no POST /auth/permissions/validate (Insufficient permissions.). O WaveAuthPermissionValidator tratava esse 403 como "sem veredito" e lançava PermissionValidatorUnavailableError. Com isso, o serviço que usa a framework respondia 503 ("Unable to validate the API key at this time.") para um problema que está na credencial, não numa indisponibilidade:

$ curl .../v1/naked/order?document=... -H "authorization: <key sem auth.api_key.validate>"
{"message":"Unable to validate the API key at this time."} -> 503

O que muda

• WaveAuthPermissionValidator: um 403 do /validate agora lança PermissionDeniedError ("The API key is not allowed to validate the <permission> permission"). Os handlers já mapeiam esse erro para 403.
  • A falha continua fechada: o acesso é negado, e um 403 nunca autoriza, mesmo que o corpo diga authorized: true.
  • No fluxo de múltiplas keys, PermissionDeniedError já é tratado como rejeição da key.
• Os demais status não mudam:
  • 401 continua PermissionValidatorUnauthorizedError.
  • 400, 404, 429 e 5xx continuam PermissionValidatorUnavailableError.
• Docs: o JSDoc de PermissionValidator.validate passa a descrever o caso do 403.
• Versão: bump para 0.17.1 (patch, conforme o AGENTS.md).

Como testar

• pnpm lint, pnpm test (260 testes) e pnpm build passam. A spec do validator cobre:
  • um 403 vira PermissionDeniedError, com a mensagem;
  • um 403 com authorized: true no corpo continua negando;
  • os outros 4xx continuam sem veredito.
• Teste de ponta a ponta: o naked rodou com este build contra o wave-auth-api real.
  • Key sem auth.api_key.validate → 403, antes 503.
  • Key só com read no confirm → 403.
  • Key desconhecida → 401.
  • Key válida → segue o fluxo normal.

Depois do merge

Publicar a 0.17.1 e fazer o bump nos consumidores. No tim-network-adapter, ocs e naked já estão na 0.17.x; bscsix, hperm, carrier-service e libs ainda estão na 0.16.

🤖 Generated with Claude Code