auth-jwt/docs/adr/index.md

# Architecture Decision Records — `einherjar/auth-jwt`

## ADR-001: No root factory

**Status:** Accepted

**Context:** The question arose whether `auth-jwt` should expose a root factory
(e.g. `authjwt.New(secret, cfg)`) analogous to `web.New`.

**Decision:** No root factory. Callers construct `Signer`/`Verifier` directly and
wire `AuthMiddleware` themselves.

**Rationale:** HMAC vs RSA vs EC is a fundamental architectural choice that cannot
be encapsulated in a universal default. The `TokenConfig`, `publicPaths`, and
the `Blacklist` for refresh must all be supplied by the application. A root factory
would either accept all of these (producing a Config struct as complex as the raw API)
or make fixed choices that are wrong for some callers.

---

## ADR-002: Logger added to AuthMiddleware

**Status:** Accepted

**Context:** The micro-lib `httpauth-jwt` `AuthMiddleware` wrote 401 responses
silently with no log emission.

**Decision:** `AuthMiddleware` accepts `logging.Logger` and routes all 401 responses
through `httputil.Error(logger, w, r, xerrors.Unauthorized(...))`.

**Rationale:** Consistent with `auth` ADR-002. 401 responses are logged at Warn level
by `httputil.Error` — token expiry, missing headers, and invalid signatures are all
client-visible failures that benefit from operator visibility. Silent 401s are invisible
in production; the cost of one Warn log per rejected request is negligible.

---

## ADR-003: web dependency for httputil.Error

**Status:** Accepted

**Context:** `auth-jwt` error responses could be written with a local JSON helper
to avoid a dependency on `web`.

**Decision:** `auth-jwt` depends on `einherjar/web` solely for `httputil.Error`.

**Rationale:** Consistent with `auth` ADR-003. Error response shape must be identical
to all other API errors. `auth-jwt` is a transport-layer package; a `web` dependency
is expected and correct. Duplicating the error writer in `auth-jwt` would create
divergence over time.

---

## ADR-004: ErrTokenRevoked as plain sentinel

**Status:** Accepted

**Context:** `RefreshTokenPair` could return a `*xerrors.Err` with code
`ErrUnauthenticated` instead of a plain `errors.New` sentinel.

**Decision:** `ErrTokenRevoked = errors.New("token revoked")` — idiomatic Go sentinel.

**Rationale:** `errors.Is(err, authjwt.ErrTokenRevoked)` is how callers distinguish
replay attacks from infrastructure failures. A plain sentinel keeps this check simple
and allocation-free. Using `xerrors.Unauthorized(...)` returns a pointer value whose
`errors.Is` semantics require an `Is()` method implementation. The sentinel pattern
(as used for `io.EOF`, `sql.ErrNoRows`) is the established Go idiom for this case.
The HTTP 401 response is the caller's responsibility, not `RefreshTokenPair`'s.

---

## ADR-005: EC algorithm auto-detected from key curve

**Status:** Accepted

**Context:** ECDSA supports three standardized curves (P-256, P-384, P-521) mapped
to three JWT algorithms (ES256, ES384, ES512). The API could require callers to
specify the algorithm explicitly.

**Decision:** `NewECSigner` detects the algorithm from `key.Curve.Params().Name`:
P-256→ES256, P-384→ES384, P-521→ES512. Default (unknown curve) is ES256.

**Rationale:** The algorithm is determined by the key — there is no valid scenario
where a P-256 key should sign with ES384. Requiring the caller to pass it explicitly
would create a new class of misconfiguration errors. Auto-detection eliminates that
class entirely. The same logic is applied in `ecSigner.Verify` to validate the
incoming token's algorithm header.