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

先從 pkg/http/middleware/token.go、pat_scope.go 和 scope_challenge.go 中的 middleware 路徑開始，接著檢查 pkg/errors/error.go 中的錯誤定義，以及 docs/error-handling.md 中現有的指南。使用憑證缺少、無效或已過期，以及 scope 不足的請求，執行 Go HTTP middleware 和錯誤測試。完成的標準是每條路徑都有不同的機器可讀取代碼，適用的 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.