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

まず pkg/http/middleware/token.go、pat_scope.go、scope_challenge.go のミドルウェアパスから始め、次に pkg/errors/error.go のエラー定義と docs/error-handling.md の既存のガイダンスを確認します。資格情報がない場合、無効または期限切れの場合、および scope が不十分な場合のリクエストを使って、Go の HTTP ミドルウェアテストとエラーテストを実行します。各パスにそれぞれ異なる機械可読コードがあり、該当する WWW-Authenticate の動作が維持され、対象テストが通過し、コードが文書化されていれば完了です。

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.