docs(auth): define bearer token contract

[onutc]

Summary

• add a focused bearer-token contract doc for external UI and service clients
• state the decision that Spritz should define the preferred bearer-token contract
• document JWKS as the normal validation path and introspection as a legacy bridge
• link the existing native-browser/external-UI auth doc to the contract note

Validation

• npx -y @simpledoc/simpledoc check
• git diff --check

[gitrank-connector]

👍 GitRank PR Analysis

Score: 5 points

Metric	Value
Component	Other (1× multiplier)
Severity	P3 - Low (5 base pts)
Final Score	5 × 1 = 5

Eligibility Checks

Check	Status
Issue/Bug Fix	❌
Fix Implementation	✅
PR Documented	✅
Tests	✅ (not required)
Lines Within Limit	✅

Impact Summary

This PR establishes a clear bearer token contract specification for Spritz authentication, defining the preferred JWT-based model and providing transition guidance from legacy token formats. It adds 140 lines of architectural documentation across two files and links existing auth documentation to the new contract specification. The contribution improves system clarity and provides guidance for future client implementations without modifying any production code.

Analysis Details

Component Classification: This PR adds documentation for bearer token contract definitions and authentication guidance. Documentation changes that don't affect code functionality fall under the OTHER category as they are not tied to a specific feature component.

Severity Justification: This is a P3 (Low) severity contribution. It is purely documentation/guidance with no impact on service availability, security vulnerabilities, or functional bugs. It provides architectural clarity and transition guidance but does not fix a broken feature or address a critical issue.

Eligibility Notes: Tests are not required for this change type. This is pure documentation (markdown files in docs/ directory) with no business logic, API changes, or code implementation. The PR includes proper validation (simpledoc check, git diff check) and has a clear description. No issue reference is needed as this is architectural documentation rather than a bug fix. The fix_implementation check passes because the documentation accurately reflects the stated decision and guidance.

---

Analyzed by GitRank 🤖