# `Macaw.Auth.Conformance`
[🔗](https://github.com/dcoai/macaw_auth/blob/v0.4.1/lib/macaw/auth/conformance.ex#L1)

The conformance kit: what every `Macaw.Auth.Backend` must do, as tests a
backend's author runs.

    defmodule MyBackend.ConformanceTest do
      use Macaw.Auth.Conformance, backend: MyBackend, fixtures: MyBackend.Fixtures
    end

The fixtures module implements `Macaw.Auth.Conformance.Fixtures`: it resets
the backend's store, makes users, disables and deletes them, says how
long a session may idle, and lists every value the backend stores for
sessions, so the kit can prove no token is stored as it is.

A backend still being built may name a capability it doesn't have yet
with `pending: [second_factor: "why"]`: the kit's tests that need it
are then skipped, and say so in every test run's summary, rather than
removed or passed by a fixture that pretends. The only capability so
far is `:second_factor` (enrolling, verifying and requiring one).

The kit checks:
- valid credentials sign in; a wrong password and an unknown user are the
  same refusal (no enumeration); a disabled user is refused;
- a session round-trips by token and by id; a garbage token is invalid;
- a user deleted since signing in gets no session (`{:error, :invalid}`);
- **no session token is ever stored as it is**;
- revoking one session, or all but one, ends them, and **tells a
  subscribed process** (an open page) which ids ended;
- an idle session expires, and a re-check (`touch: false`) never extends
  one; the backend's `session_idle_seconds/1` is the fixture's
  `idle_seconds/0` (the remember cookie's lifetime); a disabled user's
  live session is refused;
- a user's sessions list newest first;
- completing a step of a revoked session is `{:error, :invalid}`;
- a user with a second factor owes it, and completing the step clears it;
  a user enrolled through the fixture is reported `:enrolled`; a valid
  code passes the step (`Macaw.Auth.verify_second_factor/3`), a wrong
  one doesn't, and **a code is accepted once**; a user whom policy
  requires to have one owes enrollment;
- the backend exports `check_config!/0`, the check the application
  makes at start, and it is `:ok` for the configuration the kit's tests
  run under.

---

*Consult [api-reference.md](api-reference.md) for complete listing*