feat(middleware): add M2M authentication gate

[qnen]

O quê

Adiciona M2MAuthenticator — um middleware Fiber v3 (RequireM2M) que autentica chamadores machine-to-machine verificando um token de aplicação (M2M) emitido pelo Casdoor.

É a fundação do gate do endpoint de declarações (PUT /v1/declarations/{slug}) da inversão do access-manager: cada plugin passa a declarar suas próprias permissions via manifest, e esse endpoint precisa de uma trava que prove que quem chama é uma aplicação M2M legítima. O comportamento fica centralizado no lib-auth de propósito, pra qualquer serviço reusar.

Como

• Verificação RS256 offline contra uma chave pública injetada (o certificado do issuer, ex.: token_jwt_key.pem do Casdoor). Sem round-trip de rede, sem dependência do SDK do Casdoor — cada consumidor injeta o cert do seu próprio issuer.
• NewM2MAuthenticator(certificatePEM, enabled, logger): quando enabled=false é pass-through (dev/local); quando enabled=true exige um PEM parseável na construção (misconfig falha no boot, não em runtime).
• RequireM2M() expõe a identidade autenticada (sub, azp) via M2MSubjectFromContext / M2MClientIDFromContext pros handlers downstream.

Postura de segurança (Opção B — decidida)

Autentica, não autoriza. RS256 é pinado (fecha alg-substitution none/HS256), exp é obrigatório, e o type tem que ser application. Não faz RBAC e não amarra o chamador ao {slug} — essa checagem de posse é intencionalmente fora de escopo: a application M2M é provisionada manualmente por um operador confiável, e possuir um token M2M válido é a fronteira de confiança aceita. Hardening de posse (app↔slug) fica anotado como evolução futura.

Base empírica: um token M2M real de dev carrega type=application, sub="admin/<uuid>", name="<uuid>", azp=<clientId> — não carrega o slug legível em claim nenhum, o que inviabiliza um match direto claim==slug e motivou a Opção B.

Falhas (todas fail-closed)

Situação	Resposta
Token ausente	401
Inparseável / assinatura inválida / expirado / sem exp	401
Token autêntico mas type != application (ex.: normal-user)	403
Application token sem sub	401

Testes & qualidade

• Verificação RS256 real (par de chaves gerado no teste), cobrindo os vetores: chave errada, alg-confusion HS256, alg none, expirado, sem exp, tipo errado, sub ausente, malformado, nil-key, pass-through desabilitado, e o caminho completo via app.Test do Fiber. go build/vet/test/golangci-lint verdes.
• Review adversarial (security + logic): PASS, zero Critical/High/Medium.

Próximo passo (outro repo)

Ao mergear, o semantic-release corta uma nova v3.x beta. O plugin-access-manager (componente identity) então faz o bump e pluga RequireM2M() como 1º handler da rota PUT /v1/declarations/:slug, passando o cert Casdoor embedado.

---

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 53d31e9e-4ee5-4b7d-b02b-eaa354e72425

📥 Commits

Reviewing files that changed from the base of the PR and between 2034198 and 5afd305.

📒 Files selected for processing (2)

• auth/middleware/m2m.go
• auth/middleware/m2m_test.go

---

📝 Walkthrough

Walkthrough

Adds configurable Fiber middleware for offline Casdoor RS256 M2M token authentication. It validates JWT claims, returns 401 or 403, stores sub and azp in Fiber locals, adds tracing attributes, and tests configuration, verification, enforcement, and identity propagation.

Changes

M2M authentication

Layer / File(s)	Summary
Authenticator setup and test fixtures auth/middleware/m2m.go, auth/middleware/m2m_test.go	Defines authenticator state, parses RSA certificate PEM data when enabled, supports disabled pass-through configuration, and provides RSA/JWT test helpers.
JWT verification rules auth/middleware/m2m.go, auth/middleware/m2m_test.go	Accepts valid RS256 application tokens with required exp and sub claims, optionally pins iss, and rejects invalid signatures, algorithm confusion, expired or malformed tokens, missing claims, wrong token types, and nil keys.
Middleware enforcement and identity propagation auth/middleware/m2m.go, auth/middleware/m2m_test.go	Adds bearer-token enforcement, disabled-mode pass-through, Fiber-local identity storage and accessors, tracing attributes, and middleware response tests.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant RequireM2M
  participant verify
  participant DownstreamHandler
  Client->>RequireM2M: Send request with bearer token
  RequireM2M->>verify: Validate JWT
  verify-->>RequireM2M: Return verified sub and azp
  RequireM2M->>DownstreamHandler: Set Fiber locals and continue
  DownstreamHandler-->>Client: Return response with M2M identity

Loading

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/item-17-m2m-auth-middleware

---

_{Comment @coderabbitai help to get the list of available commands.}

[lerian-studio-midaz-push-bot]

🎉 This PR is included in version 3.0.0-beta.4 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[lerian-studio-midaz-push-bot]

🎉 This PR is included in version 3.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀