88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
|
# 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.
|