mygo/docs/server/decisions/0003-auth-contracts.md

ADR-0003: Define Authentication Contracts

Status: Accepted
Date: 2026-04-29

Context

Authentication requires distinct access and refresh behavior, stable duration parsing, and safe development defaults.

Decision

• Use AuthHandler for public authentication routes and AccountHandler for authenticated account routes.
• Add a JWT type claim that distinguishes access and refresh tokens.
• Verify token type at the boundary that consumes the token.
• Store configuration durations as time.Duration values.
• Replace known development JWT placeholders with a random runtime secret during configuration loading.

Consequences

• Access tokens authenticate protected requests.
• Refresh tokens rotate token pairs through database sessions.
• Invalid duration values fail during startup.
• Tokens signed with the generated development secret expire when the process restarts.
• Multi-instance deployments require a stable configured secret.