http: classify missing token, invalid token, and insufficient scope distinctly

[davidahmann]

Problem

Authentication and authorization failures currently collapse into generic HTTP errors even though missing credentials, invalid/expired credentials, and insufficient scopes require different remediation. That weakens machine-readable diagnostics for hosts and operators.

Why now

This server sits directly on GitHub token-policy boundaries. Clients and wrappers need explicit failure classification to decide whether to prompt for auth, refresh a token, or request additional scopes.

Expected behavior

Missing token, invalid/expired token, and insufficient scope paths should each expose a distinct machine-readable error code while preserving the existing auth challenge semantics.

Claim-to-codepath map

• pkg/http/middleware/token.go
• pkg/http/middleware/pat_scope.go
• pkg/http/middleware/scope_challenge.go
• pkg/errors/error.go
• docs/error-handling.md

Evidence packet

• Commit under test: fa87e4fc9e4cd1f514cf4c236b9135987a328512
• Runtime: Go HTTP middleware tests on macOS
• Repro concept: exercise requests with no token, malformed/invalid token, and OAuth requests lacking required scopes.

Validation requirements

• Add targeted middleware/error tests for each classification.
• Preserve WWW-Authenticate challenge behavior where applicable.
• Document the new machine-readable codes.