feat(middleware): add opt-in local JWT signature verification

[fredcamaral]

What

Adds opt-in local JWT signature verification on the general authorization path, converging on the M2M gate's existing hardened RS256 verifier instead of introducing a second (JWKS-based) mechanism.

• Extracts m2m.go's crypto core into one package-level verifyToken(pubKeys, issuer, token) — RS256-pinned (WithValidMethods, closing alg substitution), WithExpirationRequired, optional WithIssuer.
• Used by both RequireM2M (via M2MAuthenticator.verify) and the general checkAuthorization path. Hooked at checkAuthorization, so it covers Fiber + both gRPC interceptors from one audited place.
• REJECTS JWKS per the approved design: JWKS reintroduces the hot-path network coupling the M2M design deliberately avoided and that Add authz decision cache, circuit breaker, and bounded retry #108 exists to remove. Rotation is handled by a multi-cert bundle instead.

Why

The general path used ParseUnverified and trusted the token's type/owner/sub claims to build the authz subject, with the network POST /v1/authorize as the only trust anchor. This adds defense-in-depth: a forged token is rejected before its claims are ever used.

Config (opt-in; gated by presence, like the M2M cert)

• AUTH_JWT_VERIFY_CERT — newline-joined PEM bundle (PKIX pubkey or X.509 cert). Multiple certs → zero-downtime key rotation: a token verified by ANY listed key is accepted (static-keyset-with-overlap).
• AUTH_JWT_VERIFY_CERT_PATH — mounted PEM file (used only when AUTH_JWT_VERIFY_CERT is empty).
• AUTH_JWT_ISSUER — optional iss pin.

Behavior

• Unset cert → historical ParseUnverified behavior, byte-for-byte unchanged (backward compatible; all 112 pre-existing tests still pass).
• Configured → verify signature/alg/exp/iss BEFORE claim extraction; any failure denies with 401, fail closed.
• Configured-but-unparseable cert → logged loud at ERROR, verification left disabled (never silently accepted), keeping NewAuthClient's no-error signature. See "Design note" below.

Tests

30 new tests: valid signed passes; wrong-key/forged → 401; expired → 401; missing-exp → 401; HS256/none alg-confusion → 401; issuer match/mismatch; multi-cert rotation bundle accepts either key, rejects a stranger; forged/expired tokens denied before the authz backend is reached; unset-cert path unchanged; NewAuthClient env wiring (inline, bundle, path, bad-cert-disables, precedence).

Design note for reviewer

The design left the bad-cert constructor posture open (erroring constructor vs log-loud-and-disable). This PR implements log-loud-and-disable within the existing no-error NewAuthClient — non-breaking for all consumers, and "not silent" (ERROR log). Since verification is env-gated, adopting it needs no consumer code change. If you want strict fail-closed-on-bad-cert at startup, that composes naturally with #107's AUTH_REQUIRED and can be a follow-up.

One #nosec G304 G703 sits on the AUTH_JWT_VERIFY_CERT_PATH file read: the path is operator-supplied deployment config (a mounted secret), not request/user input. .golangci.yml already excludes this G304 class repo-wide; the annotation covers the standalone GoSec job too.

Verification

go build, go vet, golangci-lint run ./..., and gosec ./... all clean locally; 142 tests pass.

Closes #106

https://claude.ai/code/session_01RcQLK4qK1kbpvXWjuAR3Xh

[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: b63ad024-60a5-4210-b303-ca8d0c7ad851

📥 Commits

Reviewing files that changed from the base of the PR and between d13faf1 and 6ecb0d9.

📒 Files selected for processing (1)

• auth/middleware/verification.go

---

📝 Walkthrough

Walkthrough

JWT authorization now supports optional local RS256 verification using inline or file-based PEM keys, issuer validation, and key rotation. Authorization and M2M flows use shared verification logic, while tests cover validation, configuration, integration, and fallback behavior.

Changes

JWT Verification

Layer / File(s)	Summary
Verification and key parsing auth/middleware/verification.go, auth/middleware/verification_test.go	Adds RS256 verification with required expiry, optional issuer checks, multi-key support, and parsing tests.
Configuration and authorization wiring auth/middleware/middleware.go, auth/middleware/verification.go, auth/middleware/verification_test.go, README.md	Loads verification settings during client construction, applies them during authorization, tests fallback and failure behavior, and documents the environment variables.
M2M verifier integration auth/middleware/m2m.go	Routes M2M token validation through the shared verifier while preserving token type and subject checks.

Sequence Diagram(s)

sequenceDiagram
  participant Request
  participant checkAuthorization
  participant extractClaims
  participant verifyToken
  participant AuthBackend

  Request->>checkAuthorization: Submit bearer token
  checkAuthorization->>extractClaims: Extract authorization claims
  extractClaims->>verifyToken: Verify token with configured RSA keys
  verifyToken-->>extractClaims: Claims or HTTP 401
  alt verified
    extractClaims-->>checkAuthorization: Valid claims
    checkAuthorization->>AuthBackend: Check authorization
  else rejected
    extractClaims-->>checkAuthorization: Deny request
  end

Loading

Possibly related PRs

• LerianStudio/lib-auth#122: Both changes modify JWT subject and token-type validation in authorization.
• LerianStudio/lib-auth#125: Both changes concern offline RS256 verification in the M2M authentication flow.

✨ Finishing Touches

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch feat/local-jwt-verification-106

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@auth/middleware/verification.go`:
- Around line 140-146: Update the parse-failure log in the parseRSAPublicKeys
error branch to use source-neutral wording instead of naming
AUTH_JWT_VERIFY_CERT, so failures from either certificate configuration source
are described accurately. Preserve the existing error details and return
behavior.
- Around line 156-158: Update the inline certificate handling in the
verification middleware to trim surrounding whitespace from AUTH_JWT_VERIFY_CERT
before checking whether it is empty and returning it. Preserve precedence for a
non-empty inline certificate so whitespace-only values fall through to the
existing AUTH_JWT_VERIFY_CERT_PATH handling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 45c3cb3f-562e-456f-b191-0f4563a97ac9

📥 Commits

Reviewing files that changed from the base of the PR and between 64dd89c and d13faf1.

📒 Files selected for processing (5)

• README.md
• auth/middleware/m2m.go
• auth/middleware/middleware.go
• auth/middleware/verification.go
• auth/middleware/verification_test.go

[lerian-studio-midaz-push-bot]

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

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 📦🚀