feat(shared-auth): add the shared Go JWT auth library with Spring parity [JDWLABS-480]

[jdwillmsen]

Resolves JDWLABS-480.

A shared Go library that verifies the HS256 tokens usersrole mints and decides
every authorization rule the frozen contracts name, so identity-service and
profile-service enforce identical rules from one implementation instead of two
that drift.

Surface

New module libs/backend/shared/auth (Nx project backend-shared-auth, tags
type:util scope:shared framework:go, test/lint/tidy targets with
race: true), registered in go.work. Laid out like libs/backend/shared/util
so it needs no new CI wiring — the matrix and lint jobs come from the project
graph.

Package	What it holds
auth	Verifier (HS256 only, signature, nbf/exp window, required sub/iss/aud/jti), Principal, claim-name constants, SecretKeyFromEnv reading UR_JWT_SECRET_KEY
authz	One function per contract rule, plus Authorizer.Allow dispatching by rule name
authhttp	net/http middleware, PrincipalFrom, and the refusal writers
authtest	Test-only minter reproducing JwtService.generateToken

All eight rules the contracts name are implemented, not the four the ticket
counted: the audit's four shapes plus AUTHENTICATED, PUBLIC,
ADMIN_OR_SELF_BY_EMAIL and ADMIN_OR_SELF_BY_BODY_USER_ID, which the frozen
documents also carry.

Refusals reproduce CustomAuthenticationEntryPoint and
CustomAccessDeniedHandler exactly — the Access-Denied-Reason header values,
the status, and the container error body the contracts pin, including the
doubled Access Denied prefix the JVM produces.

How parity was proven

Against the contracts, mechanically. TestAllowKnowsEveryRuleTheFrozen ContractsName reads both *.openapi.yaml files and asserts the rule set
matches in both directions. Verified by mutation: removing a rule fails with
contract rule ADMIN_OR_SELF_BY_EMAIL has no implementation, and renaming one
fails on both halves. The project declares an implicit dependency on
usersrole so a contract edit selects this project in nx affected.

Against the JVM, in both directions, with checked-in fixtures.

• A token minted by JwtService.generateToken lives in parity_test.go and is
  verified here with the clock pinned inside its real two-hour window.
• A token minted by authtest.Minter lives in the new JwtGoParityTests and is
  verified there through the production extractAllClaims path — not a
  re-implementation.

Each fixture sits in the source of the side that consumes it rather than in a
shared data file. That is deliberate: the org secrets gate flags any JWT, and
its inline gitleaks:allow directive has to sit on the token's line, which JSON
cannot carry. Putting the value in source keeps the suppression visible next to
the value a reviewer is checking, instead of a path rule that would also cover a
real leak dropped beside a fixture later. This is the judgement call in the
diff most worth a second opinion — the alternative is a value-pinned entry in
jdwlabs/.github's gitleaks.toml, which is where the parity secret itself is
already pinned, and which would need its own PR in that repo.

JwtGoParityTests also compares the JOSE header and the full claim set of a
token it mints right now against the Go fixture. That comparison caught two real
defects while it was being written:

1. jjwt writes {"alg":"HS256"} with no typ, while golang-jwt adds one. The
   minter now reproduces the JVM header byte for byte. Verified by mutation:
   putting typ back fails generateToken_shouldProduceTheSameClaimLayoutAs TheGoLibrary with "the two implementations write different JOSE headers".
2. TamperSignature was flaky. The final base64url character of a 32-byte
   signature carries only two significant bits, so editing it left the token
   valid a quarter of the time — a negative test that passed by luck. It now
   inverts a decoded byte.

Truth tables. 120 Go tests and subtests, table-driven over every rule with
allow and deny cases: admin override, self-match, non-match, manager-is-not-
special, anonymous, and a principal with no user_id claim. Token negatives
cover expired, not-yet-valid, wrong issuer, wrong audience, tampered signature,
a different key, alg of none/HS384/HS512, each missing required claim, and
seven wrong-typed claims.

Decisions worth a reviewer's attention

• The profile fallback is implemented as the contract specifies: consulted
  only when the claim is absent or null, keyed on the user_id claim and never
  on a path variable. Tests pin that a present claim does not trigger the
  lookup, that the lookup is asked for the claim's user id, and that a failed
  lookup surfaces as an error rather than a denial.
• Two divergences are pinned rather than fixed, matching
  x-authority-freshness and x-stale-profile-claim: role revocation is bounded
  by the token lifetime, and a stale non-null profile_id still authorizes.
  Both are widenings, both follow from the split, and closing either means
  reinstating the per-request read the split removes. Changing them should
  require changing a test that says so.
• NewVerifier refuses a secret outside the HS256 key-length band. jjwt
  selects the HMAC variant by key length, so a 48-byte secret makes the JVM sign
  HS384 and every Go verification fail simultaneously. A startup error beats a
  silent total outage.
• An undecidable rule answers 500, not 403. A failed profile lookup says
  nothing about the caller's rights, and reporting it as a refusal hides an
  outage behind a plausible-looking response.

Verification

go test ./... -race -count=1     all packages ok, 120 tests and subtests
go vet ./...                     clean
golangci-lint run ./...          No issues found
gofmt -l .                       no output
nx run backend-shared-auth:test  passes (go test -race ./...)
nx run backend-shared-auth:lint  passes
gradlew test (usersrole)         BUILD SUCCESSFUL, 319 tests, 0 failures
gitleaks 8.30.1, org config      no leaks found over the tracked tree

No new external dependency beyond github.com/golang-jwt/jwt/v5; the repo had
no JWT library. Nothing under usersrole/src/main is touched — the only JVM
change is the new parity test.

Open risks

• The Go fixture's lifetime is deliberately far longer than a real token, because
  JwtService reads the wall clock and offers no seam. It exercises the real
  verification path; it does not exercise a realistic expiry, which the Go-side
  tests cover instead.
• Both parity fixtures are refreshed by hand: each side's command prints a
  replacement to paste into the other, as the README documents. A claim-layout
  change that skips them fails loudly on the JVM side rather than passing
  quietly.
• implicitDependencies: ["usersrole"] means a usersrole change now also runs
  this library's tests. That is intended — the contracts are this library's
  specification — and costs about three seconds.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FvYBM6o7wARm2v9jmDp1yY

---

Review round (13 items)

11 fixed, 1 fixed differently than proposed, 1 rejected with evidence. Rebased onto origin/main after the by-user route move; the contract-derived rule test confirms the rule inventory is unchanged (same 8 rules, same counts) and no x-authorization block moved.

Finding 2 was bigger than reported, and measuring it changed the answer twice. The body-parity claim was reasoned from the handlers, which call sendError with a message. But server.error.include-message is set nowhere, so Boot's default never applies. Booting usersrole on a real port and driving unauthenticated requests shows 401/403 answering with Content-Length: 0, no Content-Type, empty body — on Accept of application/json, */* and text/html alike. Neither the composed JSON this originally emitted, nor the "message": "" the review predicted. The library now reproduces the service; the README records that the frozen contract's ContainerError body for those statuses is inaccurate and wants its own change.

That probe also caught a live break (finding 3). A CORS preflight was being refused with 401. Browsers never attach Authorization to one and Spring's CorsFilter answers it ahead of the JWT filter — measured: the deployed service returns 200. Every cross-origin call from the frontends would have failed at cutover. Preflights now pass through; a plain OPTIONS without the preflight header still authenticates, so the exemption cannot be used to reach a handler.

Also fixed: required issuer/audience with an explicit AllowAnyIssuerAndAudience opt-out (an unset field was silently disabling the check); RS256 algorithm-confusion test plus WithValidMethods as a second pin; NewMiddleware rejecting a nil verifier; OnError only for a token that was presented and failed; an enforcement test walking the service modules for imports of the test-only minter (mutation-verified); a Go-side minter layout pin so a claim-name or type change fails on both sides (mutation-verified); the contract scanner anchored on the x-authorization block with a decoy test and a count assertion; nil-principal denials for the last two rules; and the secret-length runbook.

Finding 13, fixed differently. golangci-lint is installed in neither CI nor the devcontainer, so wiring it as the lint target would fail every run. The target now runs go vet instead of the executor's default go fmt, which rewrites files and never fails — it gated nothing. Verified by mutation: a real fmt.Sprintf type error now fails the target. Installing golangci-lint and wiring all four Go projects is worth its own change.

Finding 12, rejected. Dropping ^default from the test inputs is rejected by the repo's own workspace-checks guard, whose docstring explains why: an Nx inputs array replaces the implicit ["default", "^default"], so a target declaring inputs without a dependency-aware entry hashes none of its dependencies and hits cache while reporting a pass for work it never did — which has shipped here twice. Reproduced: dropping it yields backend-shared-auth:test — inputs: [...] as an offender and fails workspace-checks:test. implicitDependencies drives affected selection; ^default drives cache hashing. They are not substitutes. Keeping the guard's rule.

Verification after the rebase: 136 Go tests/subtests (-race), go vet and golangci-lint clean, gofmt clean, nx run-many -t lint test -p backend-shared-auth usersrole green, JVM suite 330 tests / 0 failures, gitleaks clean over the tracked tree.

---

Review round 2 (1 bug, 6 risks)

5 fixed as proposed, 2 fixed differently after measuring. Details in the commit; the parts a reviewer should check:

The bug (#1) and the real bug behind #2. The README snippet no longer compiled — making the verifier field unexported and Handler a pointer method left it stale, which is what an uncompiled snippet does. It is now an Example in authhttp/example_test.go, so a rename fails the build. #2 was worse than "a risk": the bypass called the wrapped handler directly, so on a net/http mux — whose patterns carry no method by default — OPTIONS /api/users/42 with the preflight header reached a business handler with no principal. The exemption is now off by default and delegates to a Preflight http.Handler the service supplies, which never reaches the wrapped handler. Off-by-default is also the correct wiring: CORS belongs outside authentication (Spring's ordering), and a service that mounts it there needs no exemption. #3 folded in — all three CorsUtils.isPreFlightRequest conditions now, so a request without Origin cannot use it.

#4/#5/#6 — fixed differently, because both proposed remedies fail. Measured first: a service-only change selects ["servicediscovery"] alone, so the ban was unenforceable regardless of how the walk was written.

• Adding implicitDependencies on the Go services points a library at its own consumers. nx-go really does infer Go import edges (verified: servicediscovery -> backend-shared-util), so this collides with the real edge the moment the two Go services import this library — which is the library's entire purpose and what this ticket blocks.
• Moving to workspace-checks alone fixes caching but not selection: it was not selected by a service-only change either.

So the check moved to workspace-checks and that project gained implicitDependencies: ["*"] — the safe direction, since nothing depends on it, and the same argument its existing cache: false already makes: a guard that does not run withholds nothing. It now walks every Go file in the repo (mutation-verified against both a service import and this library's own verifier.go). Cost measured: exactly +1 project per PR (workspace-checks, ~8s); the affected set for a frontend change went 15 → 16.

#7. AllowAnyIssuerAndAudience honoured a populated expected value while claiming to accept any, and the test minted with the expected origin so it passed either way. The contradictory combination is now refused, and the test mints from a foreign origin — mutation-verified that it fails if the check still runs.

Verification: 145 Go tests/subtests under -race; go vet, golangci-lint, gofmt clean; nx run-many -t lint test -p backend-shared-auth usersrole workspace-checks green; JVM 330 tests / 0 failures; gitleaks clean.