[takashi-matsuyama]

Why

In MCP OAuth resource-server mode, a refused token left no record on the server. A client such as Claude Code shows only "needs authentication", the 401 body deliberately never names the check that failed, and kozou printed nothing. So an operator could not tell an issuer mismatch from an expired token, a missing role claim, or a role outside allowedRoles. The 403 for a token without a role claim also pointed at a remedy this surface does not have ("no default role is configured": MCP OAuth has no defaultRole).

What changes

• One stderr line per refusal, naming the check. Every 401/403 on the MCP endpoint (and on POST /admin/refresh when enabled) writes
  <prefix> auth <status> <code>: <explanation>, for example
  [kozou mcp] auth 403 role_missing: the token carries no "role" claim. This endpoint has no default role: the role must come from the token, so assign it in the authorization server.
  Codes: no_token, malformed_header, malformed_token, algorithm_not_allowed, unknown_key, ambiguous_key, jwks_unavailable, bad_signature, expired, not_yet_valid, issuer_mismatch, issuer_missing, audience_mismatch, audience_missing, claims_invalid, other_token_error, role_missing, role_unreadable, role_not_allowed, insufficient_scope.
  A line holds fixed text, configuration names (the role claim's name, a configured scope's name) and the code; a setting is named as it appears in the MCP auth settings (server.mcp.http.auth for the kozou CLI), never as the REST block's key. It never holds the token, a claim value, a header, an address or the request path. no_token says that a lone tokenless request is how a client normally starts, before it signs in.
• Capped per reason. At most 5 lines per reason per 60 s, measured on a monotonic clock. Further refusals are counted and reported in one line when the window closes (or when the server closes), so a flood of bad tokens cannot bury another reason's line or grow the log without bound.
• @kozou/core/auth: KozouAuthError carries a reason (new exported type AuthFailureReason), classified from the jose error class. The message returned to the caller is unchanged, and the REST surface does not read the reason. reason is not enumerable, like message, so JSON.stringify(err) or { ...err } does not hand it to a client. The type's doc states its stability: reasons may be added in a minor release; within a major none is renamed, removed or given a different meaning.
• MCP 403 for a missing role: now Token does not specify a role (no "role" claim). (the configured claim name). REST keeps Token does not specify a role and no default role is configured.

Both kozou mcp --http and kozou dev serve MCP through startHttpServer, so both get the lines.

Unchanged

• 401 bodies and WWW-Authenticate challenges.
• Every other 403 body.
• REST behaviour and messages.
• A JWKS that cannot be connected to at all (refused, DNS, TLS) still answers 500 and logs the existing request failed: line, as before; it is not a refusal and gets no reason.

Verification

• pnpm -r run build, pnpm -r typecheck, pnpm run lint, pnpm -r --if-present test (with testcontainers): all green locally.
• @kozou/core: each jose failure maps to its reason, and every message is unchanged.
• @kozou/mcp (test/refusalLog.test.ts): for each reason, the response status and exactly one line with that status and code; no planted claim value, token, token segment or header on stderr; the scope a tools/call lacked; the three key-set reasons against a loopback JWKS; the cap (with an injected clock), a wall-clock step, the unref-ed timer and the flush on close. An inventory typed Record<RefusalCode, …> places every code in a test.
• kozou (test/mcp-refusal-log.test.ts): kozou mcp --http run as a process, with an HS256 config and with a JWKS config: one line per reason, in order, and no value on the process's stderr.
• Negative controls, each restored (and rebuilt) before the next: removing the log call; writing the refusal message to stderr; putting the Authorization header into a line; swapping two reason mappings in core; putting the role name into the reason; raising the cap; never scheduling the window-end count; restoring the shared 403 text; wording no_token as a failure; a line status that disagrees with the response; making reason enumerable; folding ambiguous_key back into unknown_key; measuring windows on Date.now; dropping unref(); removing a case from the shared request table; restoring the REST-style auth.jwt.audience wording. Each one turned at least one of the new tests red. Adding a new code to the union without a status, an explanation and a place in the test inventory does not compile.
• The real-Keycloak suite (keycloak.e2e.test.ts) now prints no_token, role_missing (a user with no role attribute), role_not_allowed and audience_missing lines for tokens a real Keycloak 26 minted.

Not covered

• A JWKS fetch timeout (jwks_unavailable through JWKSTimeout) is not exercised: jose's timeout is 5 s and not configurable from kozou. The other jwks_unavailable causes (a non-200 response, a body that is not JSON, a malformed key set) are.
• kozou mcp --http does not close the server on SIGTERM/SIGINT, so a count still held back when the process stops is not written (the lines already written stay). kozou dev closes it and writes the count.
• The REST surface still logs nothing on a refusal.