[euskadi31]

Fixes the following findings of the internal security audit of 2026-10-12 (commit c5c2ac3): CORE-01, CORE-02, CORE-05, CORE-07, CORE-10, CORE-13, CORE-15 (Engine, carriers, Authorities), CORE-I1, CORE-I2, CORE-I3, CORE-I4, CORE-I5, CORE-I6, CORE-I10, CORE-I11.

This PR hardens two layers:

• the transport-agnostic core: Engine, Manager, the decision managers and the voters;
• the three transport adapters: httpsec, grpcsec and connectrpcsec.

basic, bearer and session get only the edits these changes require; PR F builds its hardening on top of them. The PR also adds security.ErrUnavailable (503 / Unavailable). The JWT PR wraps it for key-set outages, so its name and contract are stable.

Findings

CORE-01 — the voters ignored the value of the attribute they checked (Medium)

Problem. The attributes a route listed only chose which voters ran. Each voter then checked the role it was built with, whatever role the route asked for. Reproduced with real voters:

• a decision manager {HasRole("USER"), HasRole("ADMIN")} shared by two routes granted [Role("ADMIN")] to a USER;
• {Authenticated(), HasRole("ADMIN")} granted any route to any logged-in principal, because Authenticated() voted on every attribute;
• HasAnyRole("ADMIN", "MANAGER") granted a MANAGER on [Role("ADMIN")].

Fix. Voters now follow Spring Security's semantics.

• Each voter supports an attribute only when both its family and its value match: HasRole("ADMIN") abstains on Role("USER").
• HasAny* grants only for the names the route requests.
• Authenticated() and Anonymous() vote only on the new security.IsAuthenticated / security.IsAnonymous attributes.
• Decide hands each voter only the attributes it supports.
• Decide denies when an attribute is supported by no voter.
• Decide denies a decision without attributes or without voters, whatever the tie-break and WithAbstainFallback. Before, WithAbstainFallback(DecisionGrant) granted such a route to anyone, anonymous callers included.
• voter.And is strict: an inner abstention denies when the composite votes.
• An undefined Decision counts as a deny.

Breaking: yes. See MIGRATION "voter: voters compare attribute values; dedicated authentication-state attributes".

CORE-13 — Not() turned an anonymous refusal into a grant (Low)

Problem. Not(HasRole("BANNED")) admitted anonymous callers: the inner voter denies an unauthenticated principal, and Not inverted that deny into a grant.

Fix. Not grants only an authenticated principal. An undefined decision counts as a deny.

Breaking: yes. Use voter.Anonymous() with security.IsAnonymous to admit anonymous callers.

CORE-I2 — voter.FullyAuthenticated() behaved like Authenticated() (Info)

There is no remember-me or authentication-strength concept that could tell the two apart, so the stronger promise was false. FullyAuthenticated() is removed; MIGRATION says to use Authenticated().

CORE-I1 — roles and scopes shared one flat authority namespace (Info)

Problem. One bare admin authority satisfied HasRole("admin"), HasScope("admin") and HasAuthority("admin") at once. A scope a client obtained could therefore pass for a role. scope:a b was also split into two scopes.

Fix.

• HasRole matches only ROLE_<name> (security.RolePrefix).
• HasScope matches only one scope:<name> authority per scope (security.ScopePrefix). That is what jwtsec.DefaultAuthorityResolver emits.
• HasAuthority matches verbatim.
• The constructors panic on a name they could never match: none, an empty one, a role starting with ROLE_, or a scope that is not an RFC 6749 §3.3 scope-token or starts with scope:.

Breaking: yes. See MIGRATION "voter: roles and scopes live in their own authority namespaces".

CORE-02 — credentials and the session were read from the URL and from cookies (Medium)

Problem. When a header was absent, httpsec.Carrier.Get / Values fell back to a cookie or to the query parameter of the same name. As a result:

• Basic and Bearer credentials were accepted from ?Authorization=… and from an Authorization cookie, so they leaked through logs, Referer and browser history;
• a session was accepted from ?session=… or a Session header, and the header even took precedence over the victim's cookie. A link or a cross-site form could log a victim into the attacker's session.

Fix.

• The carrier reads header fields only (RFC 6750 §2.1, RFC 7617 §2).
• session.Manager reads its cookie through the explicit httpsec.Carrier.CookiesNamed accessor (the session.CookieReader interface), and finds no session on a carrier without it.

Breaking: yes. See MIGRATION "http, session: credentials from header fields only, the session from its cookie".

CORE-05 — the documented gRPC wiring served streaming RPCs unauthenticated (Medium)

Problem. The grpc-bearer example and the godoc example chained only unary interceptors. A test proved that Health.Watch was served without any token.

Fix. New helpers grpcsec.ServerOptions(engine, …) and grpcsec.AuthorizeServerOptions(adm, attrs, …) install the unary and the stream chains together, with the same options. Both examples use them, and tests check Watch on each path.

CORE-07 — personal data and error text in telemetry (Low)

Problem.

• The failing core spans recorded the whole error chain as status description and exception event. That chain could include the username typed at a Basic prompt (often a password typed into the wrong field) and wrapped store errors.
• The HTTP span recorded the raw path as http.route (reset tokens, e-mail addresses) and the raw method.

Fix.

• Spans record only error.type: the class returned by the new security.ErrorClass(err) (OpenTelemetry semantic conventions), with no exception event and nothing on success.
• basic no longer puts the username in its errors.
• http.request.method falls back to _OTHER for unknown methods.
• http.route is the ServeMux pattern's path template, or is absent.

CORE-10 — challenges and status codes (Low)

Problem.

• A Basic-only server was answered with a bare Bearer challenge, and no challenge carried a realm (RFC 7617 §2 requires one, RFC 6750 §3 an auth-param).
• The realm was rendered with Go escapes instead of an RFC 9110 §5.6.4 quoted-string.
• invalid_token was sent only for expired or unknown tokens, and insufficient_scope never.
• A wrong password joined with another authenticator's bail-out was answered 400.
• Authorize answered an anonymous caller 403 with a hard-coded challenge.
• An infrastructure failure was answered 401.
• A Connect 401 carried no WWW-Authenticate at all.

Fix. One classification, security.ErrorClass, is shared by the core spans and the three default mappers. The default answers are:

Class	HTTP	gRPC / Connect
invalid_request	400	InvalidArgument
unavailable	503	Unavailable
token_expired, token_not_found, client_secret_mismatch, invalid_credentials	401	Unauthenticated
authentication_required, unsupported_credential	401	Unauthenticated
insufficient_scope, access_denied	403	PermissionDenied
no_extractor, no sentinel (_OTHER)	500	Internal

Challenge rules:

• Every challenge carries a realm, api by default, rendered as a quoted-string; an invalid scheme or realm panics at construction.
• A Basic challenge also carries charset="UTF-8" (RFC 7617 §2.1).
• The RFC 6750 codes are sent only when the request carried a bearer token. invalid_token covers every failed check of the token (RFC 9068 §4); insufficient_scope a valid token refused by the access decision.
• An unauthenticated principal refused by Authorize gets 401 with the middleware's challenge (RFC 9110 §15.5.2, §15.5.4).
• The Connect mapper puts the same challenge in the error metadata.

Deviation from the code review (finding 5), deliberate. The review asked for a challenge on a Bearer resource's 400. This PR goes further: a Bearer resource challenges every refusal, 503 and 500 included.

• RFC 6750 §3 says the resource server "MUST include the HTTP "WWW-Authenticate" response header field" when the request "does not include authentication credentials or does not contain an access token that enables access", and "MAY include it in response to other conditions as well".
• A 5xx answered to a request without credentials falls under that MUST.
• RFC 9110 §11.6.1 allows the field in any response ("A server MAY generate a WWW-Authenticate header field in other response messages").

So challenging every refusal is the only reading that never violates the letter. The challenge on a 5xx stays bare: §3.1 defines no code for it, and an empty error="" would break the grammar, which a test now pins. A Basic resource still challenges only its 401 and 403 (RFC 7617 has no such rule). The reviewer's re-review checked this reading and found it compliant.

Breaking: yes. See the MIGRATION sections for http, grpc and connectrpc. connectrpcsec.DefaultErrorMapper() becomes DefaultErrorMapper(scheme, realm string).

CORE-15 — credentials kept or printable (Low; the parts assigned to this PR)

Problem.

• After a failed authentication, Engine.Process stored the extracted value (a cleartext password or a bearer token) in the request context and returned it.
• grpcsec.Carrier and connectrpcsec.Carrier printed their incoming metadata, bearer token included, with %v.
• Authorities() of the basic, bearer and session authentications returned their internal slice, so a caller could rewrite ROLE_USER into ROLE_ADMIN.

Fix.

• The Engine and the Manager return and store security.Anonymous() on every failure.
• The carriers print and log key counts only, whatever the fmt verb, and in slog.
• Authorities() returns a copy, and the security.Authentication contract now requires it.

CORE-I3 — contract violations panicked on the request path (Info)

Problem.

• An authenticator returning (nil, nil) panicked the request path, and so did a typed nil (var out *T; return out, nil).
• So did a nil Attribute, a nil Authentication given to Decide, and a nil or broken custom Engine.
• grpc-go recovers no panic, so on a gRPC server any of these crashed the process.

Fix.

• A typed nil counts as nil wherever the core or an adapter checks a contract.
• Success without an authenticated value is an internal error (500 / Internal).
• A nil or typed-nil attribute or authentication given to Decide is denied, or evaluated as Anonymous().
• An extractor's typed nil means "no credential".
• FromContext reads a typed nil back as Anonymous().
• At construction:
  • NewEngine, NewManager, the decision managers and the composites panic on a nil dependency;
  • the three authentication entry points panic on a nil engine;
  • the authorization constructors panic on a nil decision manager or a nil attribute, and copy their attributes.

CORE-I4 — grpcsec dropped the metadata staged on its carrier (Info)

The staged metadata is now sent as the response header, on success and on refusal. connectrpcsec merges it into the error metadata on a refusal or a handler error.

CORE-I5 — with several Authorization fields, the first one won (Info)

RFC 9110 §5.3 forbids repeating a singleton field. The new security.SingleValue(carrier, key) refuses a repeated field with ErrInvalidRequest, which is answered 400 / InvalidArgument. The Basic and Bearer extractors read through it.

CORE-I6 — status messages explained why authentication failed (Info)

The gRPC and Connect messages are now one fixed string per code (unauthenticated, permission denied, …).

• Outages wrap ErrUnavailable and are answered Unavailable.
• Errors wrapping no sentinel are answered Internal (user decision).
• The bearer.TokenVerifier, basic.UserLoader and session.PrincipalLoader contracts state these rules.

CORE-I10 — the first extractor wins (Info, documented)

This is a deliberate design, as in Spring Security's filter chain. The NewEngine godoc and the "Extractor order" section of docs/security-considerations.md explain it: put header extractors before cookie sessions, protect cookie sessions against CSRF, and use one engine per audience.

CORE-I11 — documentation drift (Info)

• AttrPrincipalSubject no longer references an option that does not exist.
• The dead route override was removed.
• LIMITATIONS lists ConnectRPC.
• README, CLAUDE.md, architecture and security-considerations now match the code.

Tests

• Red phase. Every finding starts from a failing test that reproduces it; the auditors' probes were rewritten to repository style. Examples:

  • an ADMIN route granted to a USER;
  • ?Authorization= accepted;
  • the stream served without a token;
  • the typed nil that crashed the gRPC test binary;
  • the 400 without a challenge.

• End-to-end. The basic-http, bearer-jwt, session-web, grpc-bearer and connectrpc-bearer examples gained tests for:

  • where credentials are read from;
  • repeated fields;
  • the challenge per outcome;
  • the streaming RPCs.

• Mutation testing.

  • Implementer: 231 mutants on every new guard (voters, mappers, carriers, nil checks, copies, example wiring); all are killed. The 3 initial survivors are each killed by an added test row.
  • Independent reviewer: 37 + 16 complementary mutants; every non-equivalent one is killed, the last (N6) by test(connectrpc).

• Concurrency. Every module runs with -race.

• Test doubles. The tests this PR adds build their interface doubles from the generated mockery mocks (make generate):

  • voters, extractors, authenticators and managers in the core;
  • ErrorMapper in http, grpc and connectrpc;
  • UserLoader and PasswordUser in basic, TokenVerifier in bearer, PrincipalLoader in session.

  Hand-written doubles remain only where no generated mock can stand in:

  • plain Authentication and Attribute values, which the tests compare by equality;
  • real carriers, such as the map-backed carrier and a carrier without cookie access;
  • doubles of core interfaces in the tests of other packages (the adapters, voter, the examples). The mocks are in-package _test.go files, so they are absent from every other package's test binary.

  After the migration, the mutants were re-run: all killed.

Checks

On Go 1.27.2 with golangci-lint v2.14.0:

• make generate sync build test lint check-modules: green, 0 lint issues, no sync or tidy change.
• govulncheck -test on every module: no reachable vulnerability. It ran against a local copy of the vuln.go.dev database, because the freshly built binary could not open outbound connections on this machine; CI's govulncheck workflow runs it as well.

Package	master (before)	this PR
security (core)	98.2 %	100.0 %
voter	97.2 %	100.0 %
http	92.0 %	100.0 %
grpc	100.0 %	100.0 %
connectrpc	100.0 %	100.0 %
basic	98.4 %	98.5 %
bearer	98.1 %	98.1 %
session	91.1 %	91.8 % (remaining gaps predate this PR; PR F)

Follow-ups (out of scope)

• bearer-jwt end-to-end rows for an expired token and a wrong scope: PR F, which adds the token-minting hook they need. insufficient_scope is already proven end to end through connectrpc-bearer.
• NFC normalization of Basic credentials under charset="UTF-8" (RFC 7617 §2.1): PR F. LIMITATIONS notes it meanwhile.
• Several challenges per 401, for an engine accepting several schemes, is listed in LIMITATIONS.

Notes for the maintainer

• User decisions applied:
  • realm api;
  • anonymous denial → 401 / Unauthenticated;
  • unsupported credential → 401;
  • repeated Authorization → 400 / InvalidArgument;
  • RFC 6750 codes only for bearer requests;
  • strict authority naming;
  • FullyAuthenticated() removed;
  • strict And();
  • Decide denies attributes no voter supports, and decisions without attributes or voters;
  • exported security.ErrorClass;
  • no sentinel → 500 / Internal;
  • security.ErrUnavailable → 503 / Unavailable.
• http/go.mod: go.opentelemetry.io/otel/trace becomes a direct requirement (a test helper records spans).
• No new module. Every behavior change has a MIGRATION section after "Toolchain" and a CHANGELOG entry.