summercms/.planning/notes/oauth2-wristband-direct-port.md

Decision: Direct OAuth2.1-style wristband Port

Date: 2026-09-23
Status: Accepted for Phase 8
Supersedes: Phase 8 assumptions that named zitadel/oidc as the server engine

Decision

Phase 8 implements the Płytarium authorization server as an app-agnostic framework package named wristband using Go's standard library (crypto/rand, crypto/sha256, crypto/subtle, encoding/base64, encoding/json, net/http, and net/url). It does not add zitadel/oidc.

wristband owns the byte-specific RFC metadata, authorization, token, dynamic-registration, PKCE, scope, redirect, refresh-rotation, replay-revocation, and expiry-sweep behavior. fonoteka.go owns GORM persistence, users/collections, ordinary inv_ access-token issuance, consent and connected-app controllers, configuration, routes, and the operator command.

Rationale

Płytarium's unchanged clients depend on the existing PHP response bytes, metadata shape, error bodies, inv_ access-token model, ordered redirects, and app-specific consent state. zitadel/oidc is an OIDC provider with different defaults and cannot directly reproduce that token model without replacing the behavior that justified selecting it. The direct port remains small and uses standard cryptographic/HTTP primitives while preserving framework/app separation.

Header Ownership

• The Go authorization server emits exactly WWW-Authenticate: Basic realm="OAuth" for token-endpoint invalid_client.
• The existing backend personal-token 401 remains {"error":"Invalid token"} with no added challenge.
• fonoteka-mcp, as the resource server, continues to emit RFC 9728 protected-resource metadata and its rich Bearer resource_metadata challenge.

Consequences

• No external Go package is installed in Phase 8.
• Client-secret and PKCE comparisons use crypto/subtle.ConstantTimeCompare on fixed transforms.
• OAuth access tokens remain ordinary configured-prefix inv_ personal tokens verified by the existing inv_token guard.
• Historical STACK/ARCHITECTURE notes that describe the earlier ecosystem assumption remain historical; the Phase 8 context, roadmap, requirements, plans, and this note are authoritative for implementation.