dev.arkaitz.auth-base — dev.arkaitz/auth-base 0.1.0

Public entry point of auth-base: the ceremony by which someone becomes a subject, and nothing else (SPEC §1).

It is a library you call. It never calls the host back except through the functions the host hands it, it knows nothing about web-base or any other framework, and its only dependency is ring/ring-core — a handler, a request map, a session map and a store protocol, which every Clojure web application in the world already speaks.

A host wires it in one place:

(def ceremony
  (auth/ceremony {:store    (auth/in-memory-store {:subjects {"[e-mail]" :ada}})
                  :deliver! (fn [identifier link] (send-mail! identifier link))
                  :link     {:base-url "https://example.test" :redeem-path "/entrar"}}))

(def auth-routes
  (auth/routes ceremony {:view       views/login
                         :login-path "/entrar"}))

and under web-base, that is the whole of the integration:

(wb/handler {:routes     (into auth-routes my-routes)
             :subject-fn (auth/subject-fn ceremony)
             :login-path "/entrar"
             :session    {:key (env "SESSION_KEY")}})

A host that has never heard of web-base mounts (auth/handlers ceremony opts) under its own router instead, and reads the subject with the same subject-fn.

What is here and what is not. It authenticates; it never authorises — whether a subject may do a thing arrives as the host's own predicate and is obeyed (SPEC §2). It owns the credential as a unit of its own and has no idea what a person is, which is what lets an administrator exist before any data does. It composes what must be delivered and hands it over; it does not send mail. It receives a store; it does not open a database.

To implement the store port against a real database, require dev.arkaitz.auth-base.store and extend its Store protocol. Read its docstring first: take-challenge! must be atomic, and that is the whole security of a secret that travels by email.

ceremony clj

Validates the host's configuration and returns the value the three acts take. See dev.arkaitz.auth-base.ceremony/ceremony.

end clj

(end response) → the response with the session deleted.

establish clj

(establish ceremony response subject) → the response carrying that subject's session, marked for rotation in the same act.

fixed-window clj

(fixed-window {:limit n :window-ms n}) → the rate limiter that ships with the library, for a host that wants it somewhere other than on :issue.

handlers clj

(handlers ceremony opts) → {:paths … :form … :issue … :redeem … :logout …}.

in-memory-store clj

(in-memory-store) or (in-memory-store {:subjects {…}}) → the store implementation that ships with the library.

issue! clj

(issue! ceremony identifier) → nil, always, whatever the identifier is.

redeem! clj

(redeem! ceremony token) → the subject, or nil. At most once, ever.

revoke! clj

(revoke! ceremony subject) → nil, and every session of that subject dies at its next request.

routes clj

(routes ceremony opts) → the same handlers as reitit route data.

subject-fn clj

(subject-fn ceremony) → the request → subject-or-nil function the host hands to whatever paints the identity and guards the private pages. This is also where revocation takes effect.

subject-of clj

(subject-of ceremony identifier) → the subject behind an identifier: the store's record, or a bootstrap identity when there is none (SPEC §12).

unauthorized clj

(unauthorized ceremony) → the 401 with WWW-Authenticate that web-base declines to emit, for a host mounting this module for an API.

wrap-revoked clj

(wrap-revoked handler ceremony) → optional middleware that also throws away a cookie whose session has been revoked. Handler first, so it threads like every other Ring middleware.