liberty 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44e1f59a2b827b9bda2ec873fca9e2592db73e23d9ad946ee673be3cca0c8d37
-  data.tar.gz: 8ed828dddae3cc7fbce9957bce6d66a11801f13499761728ca03befd954655cf
+  metadata.gz: fb4d162f0b2ce1791b670b9b9093a8638737aec1c142908d321ebcba16499c4f
+  data.tar.gz: 7da18983c0aa557d727059daef386d429a8a1e8abeb4cd3473b8ec2ee0e76104
 SHA512:
-  metadata.gz: 77a90f8920aef4886192435fecc60c46bdb317405ff447db995b9fd264136bd996c6b3b1123c502b7ad375addc8c2756a6dcecfeccdd3bf573b67b54e4d62703
-  data.tar.gz: 7891e701f9c931e6e43488e2b45bdd47eb0790e4b8fd098aeb7870386460db43d36357768f1010bac54e819530bdad99dc7e26147e92e351af24a0cbb7b2ad84
+  metadata.gz: 9b657a059f19264ebab5a4cd059f50bf5d6c9057b700b4a6e4121ca35583ad1dd1f3cbe28988993a59f0e44713d8912a8d47699b0cbad66ae2e9ebcaae17e489
+  data.tar.gz: 3a6e8297c743040dc5d74f1cfbba70c13ba40a2d575e9da70859c924c0f403959b9ff13f4ec733a12e82f7b8ef1d94646d025c97fb6f749bb16202e237b56880

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+## [0.5.0] - 2026-09-17
+
+### Breaking changes
+
+- Replaces the 0.4.0 authentication hooks, which could only answer a 401. Routes now name their authenticator: `responds_to` takes a required `authenticated_by:` keyword, and a route that names none fails at load. Gone are the endpoint hooks `authenticated?`, `authorized?`, and `www_authenticate_header`, and Liberty's built-in 401 and 403 responses. Applications on 0.4.0 move their credential check into an authenticator and their 401 into a challenge endpoint. Applications on 0.3.x name `Liberty::Authenticators::Public` on every route they mean to leave open.
+
+### Added
+
+- Authenticators. A subclass of `Liberty::Authenticator` answers `principal` and `challenge_endpoint_class`. Liberty builds one per request, injects the request, and asks before the endpoint exists, then builds either the endpoint or the challenge. The challenge is an ordinary endpoint class the application writes, so a form login can answer a 303 to its login page and a token API can answer a 401 with a `WWW-Authenticate` header, each through the same response pipeline as every other endpoint.
+- `Liberty::Error`, the base for every error Liberty raises, and `Liberty::AbstractMethodError`, raised when an authenticator leaves one of its two answers unimplemented.
+- `Liberty::Authenticators::Public`, the authenticator for open routes. It finds no principal and never challenges.
+- `Endpoint#principal`, whoever the authenticator found for the request, or `nil`.
+
+### Kept
+
+- `request.headers[:authorization]`, and empty bodies with a `content-length` for `HEAD` requests, both from 0.4.0.
+
+## [0.4.0] - 2026-09-15
+
+### Breaking changes
+
+- Endpoints now offer `authenticated?` and `authorized?` hooks for plugging in your own auth handlers. Both default to `false` to prevent endpoints from being exposed accidentally, so every existing endpoint responds with a 401 until it overrides them. Applications upgrading from older versions must override these methods, either to return `true` or with code that handles auth.
+
+### Added
+
+- Responds with `401 Authentication required` when `authenticated?` returns `false`, and with `403 Forbidden` when `authorized?` returns `false`. The endpoint's status, headers, and content are only consulted when both return `true`.
+- Adds a `www_authenticate_header` hook to endpoints. When it returns a challenge, such as `Bearer realm="api"`, 401 responses include it as the `WWW-Authenticate` header. It defaults to `nil`, which omits the header.
+- Exposes the request's `Authorization` header as `request.headers[:authorization]` so endpoints can read credentials.
+- Responds to `HEAD` requests that fail auth with an empty body and a `content-length` header, as the Rack specification requires.
+
 ## [0.3.1] - 2026-09-07
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    liberty (0.3.1)
+    liberty (0.5.0)
       json (~> 2.3)
       mustermann (~> 4.0)
       mustermann-contrib (~> 4.0)

data/README.md

@@ -37,10 +37,13 @@ That said, Liberty does not use convention. It relies on classes declaratively r
 
 ## Usage
 
-Liberty consists of four top level classes:
+Liberty consists of these top level classes:
 * Endpoint
+* Authenticator
+* Authenticators::Public
 * CORS
 * Application (private)
+* EndpointBuilder (private)
 * Router (private)
 
 Inherit from the `Endpoint` class to create class that responds to a single type of request.
@@ -48,7 +51,7 @@ Here's an example for an HTTP get to the `/hello` route, which returns a hello w
 
 ```ruby
 class MyEndpoint < Liberty::Endpoint
-  responds_to :get, '/hello'
+  responds_to :get, '/hello', authenticated_by: Liberty::Authenticators::Public
 
   def status
     200
@@ -62,7 +65,8 @@ end
 
 Using `responds_to` as in the example above registers a class to receive traffic on that route
 with our incredibly fast `Router`. You shouldn't ever need to use the `Router` directly. Just
-use `responds_to` to register your route.
+use `responds_to` to register your route. Every route names its authenticator; `Public` is the
+one Liberty ships for routes open to anyone. See [Authentication](#authentication) below.
 
 The `Application` class is another private class that turns each `Endpoint` class into a
 Rack application. This is also a class you won't use directly.
@@ -83,6 +87,122 @@ end
 If you configure your CORS headers before you launch your application, `Endpoints` will
 automatically respond with the right headers.
 
+### Authentication
+
+Every route names its authenticator:
+
+```ruby
+class Journal < Liberty::Endpoint
+  responds_to :get, "/journal", authenticated_by: Authenticators::Session
+end
+```
+
+`authenticated_by:` is required. A route that does not name one fails when the class loads, so
+nothing is exposed by omission. To open a route to anyone, name `Liberty::Authenticators::Public`.
+
+An authenticator is a subclass of `Liberty::Authenticator` that answers two
+questions:
+
+- `principal`: who the request is from, or `nil`. The principal is whoever the request has been
+  authenticated as, whether a user, a service account, or an API client. It is any object your
+  application chooses.
+- `challenge_endpoint_class`: the endpoint class that answers when there is no principal, or
+  `nil` to admit the request anyway.
+
+The base class raises on both until you override them, so an authenticator cannot admit anyone
+by omission either.
+
+Liberty builds a new authenticator for every request and injects the request, available as
+`request`, the same way it builds your endpoint. Every name ending in `_class` follows one rule
+throughout Liberty: it names a class that Liberty instantiates for you. With a principal, Liberty
+builds your endpoint. Without one, it builds the challenge instead. Either way, the endpoint
+receives the request and the principal, available as `principal`, and its answers go through the
+same response pipeline, so `HEAD` requests, `content-length`, and `content-type` are handled once.
+
+Liberty ships no authenticator but `Public`, and no 401 or 403 of its own. What a request without
+a principal sees is the application's to decide: a login page for a form, a `WWW-Authenticate`
+challenge for a token.
+
+Here's a form login backed by a session. The request is injected after construction, so the
+authenticator takes its repository through its own initializer with a production default, and a
+test can hand it a fake:
+
+```ruby
+module Authenticators
+  class Session < Liberty::Authenticator
+    def initialize(users: UsersRepository.new)
+      @users = users
+    end
+
+    def principal
+      @users.find(request.env["rack.session"][:user_id])
+    end
+
+    def challenge_endpoint_class = RedirectToLogin
+  end
+end
+
+class RedirectToLogin < Liberty::Endpoint
+  def status = 303
+
+  def headers = {"location" => "/login"}
+end
+
+class Journal < Liberty::Endpoint
+  responds_to :get, "/journal", authenticated_by: Authenticators::Session
+
+  def html = "<h1>Welcome, #{principal.name}</h1>"
+end
+```
+
+Here's a bearer token. The credential arrives in the `Authorization` header, which every request
+exposes as `request.headers[:authorization]`. Despite its name, that header carries a credential
+that has not been checked yet. Checking it is the authenticator's job:
+
+```ruby
+module Authenticators
+  class Token < Liberty::Authenticator
+    def initialize(sessions: ApiSessionsRepository.new)
+      @sessions = sessions
+    end
+
+    def principal
+      @sessions.find_by_token(bearer_token)
+    end
+
+    def challenge_endpoint_class = TokenChallenge
+
+    private
+
+    def bearer_token
+      request.headers[:authorization].to_s.delete_prefix("Bearer ")
+    end
+  end
+end
+
+class TokenChallenge < Liberty::Endpoint
+  def status = 401
+
+  def headers = {"www-authenticate" => 'Bearer realm="api"'}
+
+  def text = "Authentication required"
+end
+```
+
+A page that anyone may see, but that still wants to know a signed-in user, is a session
+authenticator that never challenges:
+
+```ruby
+module Authenticators
+  class Optional < Session
+    def challenge_endpoint_class = nil
+  end
+end
+```
+
+Authorization is the endpoint's own answer. When the principal may not do what the request asks,
+the endpoint responds with the status and content it chooses, such as a 403.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/lib/liberty/adapters/request.rb

@@ -7,6 +7,7 @@ module Liberty
     class Request
       PARSED_BODY = "parsed_body"
       ROUTER_PARAMS = "router.params"
+      AUTHORIZATION = "HTTP_AUTHORIZATION"
 
       attr_reader :env
 
@@ -15,10 +16,7 @@ module Liberty
       end
 
       def headers
-        @headers ||= env ? {
-          accept_media_types: accept_media_types,
-          preferred_media_type: preferred_media_type
-        } : {}
+        @headers ||= env ? env_headers : {}
       end
 
       def params
@@ -31,6 +29,14 @@ module Liberty
 
       private
 
+      def env_headers
+        {
+          accept_media_types: accept_media_types,
+          preferred_media_type: preferred_media_type,
+          authorization: env[AUTHORIZATION]
+        }
+      end
+
       def all_params
         form_params.merge!(body_params).merge!(url_params)
       end
@@ -73,7 +79,9 @@ module Liberty
       end
 
       def symbolize_keys(hash)
-        hash.each_with_object({}) { |(key, value), obj| obj[key.to_sym] = value }
+        hash.each_with_object({}) do |(key, value), obj|
+          obj[key.to_sym] = value
+        end
       end
 
       def rack_request

data/lib/liberty/application.rb

@@ -2,13 +2,15 @@
 
 require_relative "adapters/request"
 require_relative "adapters/response"
+require_relative "endpoint_builder"
 
 module Liberty
   class Application
-    attr_reader :endpoint_class
+    attr_reader :endpoint_class, :authenticator_class
 
-    def initialize(endpoint_class:)
+    def initialize(endpoint_class:, authenticator_class:)
       @endpoint_class = endpoint_class
+      @authenticator_class = authenticator_class
     end
 
     def call(env)
@@ -18,15 +20,19 @@ module Liberty
     private
 
     def response(env)
-      Adapters::Response.new(endpoint(request(env)))
+      Adapters::Response.new(endpoint(env))
     end
 
     def request(env)
       Adapters::Request.new(env)
     end
 
-    def endpoint(request)
-      endpoint_class.new.tap { |endpoint| endpoint.inject(request: request) }
+    def endpoint(env)
+      EndpointBuilder.new(
+        request: request(env),
+        endpoint_class: endpoint_class,
+        authenticator_class: authenticator_class
+      ).endpoint
     end
   end
 end

data/lib/liberty/authenticator.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Liberty
+  # The base authenticator. Liberty builds one per request, injects the
+  # request, and asks two questions. Subclasses must answer both.
+  #
+  #   principal:
+  #     who the request is from, or nil
+  #
+  #   challenge_endpoint_class:
+  #     the endpoint class that answers when there is no principal, or nil
+  #     to admit the request anyway
+  #
+  # The request is injected after construction, so a subclass is free to
+  # define its own initializer with default dependencies.
+  class Authenticator
+    attr_reader :request
+
+    def inject(request:)
+      @request = request
+    end
+
+    def principal
+      raise AbstractMethodError, "#{self.class} must implement #principal"
+    end
+
+    def challenge_endpoint_class
+      raise AbstractMethodError, "#{self.class} must implement #challenge_endpoint_class"
+    end
+  end
+end

data/lib/liberty/authenticators/public.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../authenticator"
+
+module Liberty
+  module Authenticators
+    # The authenticator for open routes. It never finds a principal and never
+    # challenges, so every request is admitted with a nil principal.
+    class Public < Liberty::Authenticator
+      def principal
+        nil
+      end
+
+      def challenge_endpoint_class
+        nil
+      end
+    end
+  end
+end

data/lib/liberty/endpoint.rb

@@ -4,14 +4,20 @@ module Liberty
   class Endpoint
     DEFAULT_STATUS = 200
 
-    def self.responds_to(verb, path)
-      Liberty.add_endpoint(verb: verb, path: path, endpoint_class: self)
+    def self.responds_to(verb, path, authenticated_by:)
+      Liberty.add_endpoint(
+        verb: verb,
+        path: path,
+        endpoint_class: self,
+        authenticator_class: authenticated_by
+      )
     end
 
-    attr_reader :request
+    attr_reader :request, :principal
 
-    def inject(request:)
+    def inject(request:, principal: nil)
       @request = request
+      @principal = principal
     end
 
     def params

data/lib/liberty/endpoint_builder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Liberty
+  class EndpointBuilder
+    attr_reader :request, :endpoint_class, :authenticator_class
+
+    def initialize(request:, endpoint_class:, authenticator_class:)
+      @request = request
+      @endpoint_class = endpoint_class
+      @authenticator_class = authenticator_class
+    end
+
+    def endpoint
+      return build_challenge_endpoint if challenge?
+
+      build_endpoint
+    end
+
+    private
+
+    def build_challenge_endpoint
+      challenge_endpoint_class.new.tap { |endpoint| inject_dependencies(endpoint) }
+    end
+
+    def build_endpoint
+      endpoint_class.new.tap { |endpoint| inject_dependencies(endpoint) }
+    end
+
+    def principal
+      @principal ||= authenticator.principal
+    end
+
+    def challenge_endpoint_class
+      @challenge_endpoint_class ||= authenticator.challenge_endpoint_class
+    end
+
+    def challenge?
+      principal.nil? && !challenge_endpoint_class.nil?
+    end
+
+    def authenticator
+      @authenticator ||= authenticator_class.new.tap { |authenticator| authenticator.inject(request: request) }
+    end
+
+    def inject_dependencies(endpoint)
+      endpoint.inject(request: request, principal: principal)
+    end
+  end
+end

data/lib/liberty/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Liberty
+  # The base for every error Liberty raises, so an application can rescue
+  # them all with one clause.
+  class Error < StandardError
+  end
+
+  # Raised when a subclass leaves a method unimplemented that Liberty
+  # requires an answer to.
+  class AbstractMethodError < Error
+  end
+end

data/lib/liberty/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Liberty
-  VERSION = "0.3.1"
+  VERSION = "0.5.0"
 end

data/lib/liberty.rb

@@ -7,8 +7,11 @@ require "rack/accept_media_types"
 require "rack/abstract_format"
 
 require_relative "liberty/version"
+require_relative "liberty/errors"
 require_relative "liberty/endpoint"
+require_relative "liberty/authenticators/public"
 require_relative "liberty/router"
+require_relative "liberty/endpoint_builder"
 require_relative "liberty/application"
 require_relative "liberty/cors"
 
@@ -18,14 +21,15 @@ module Liberty
   end
 
   def self.middleware
-    @middleware ||= Rack::Builder.new(Liberty.router) do
-      use(Liberty::CORS::Middleware)
-      use(Rack::AbstractFormat)
-    end
+    @middleware ||=
+      Rack::Builder.new(Liberty.router) do
+        use(Liberty::CORS::Middleware)
+        use(Rack::AbstractFormat)
+      end
   end
 
-  def self.add_endpoint(verb:, path:, endpoint_class:)
-    app = Application.new(endpoint_class: endpoint_class)
+  def self.add_endpoint(verb:, path:, endpoint_class:, authenticator_class:)
+    app = Application.new(endpoint_class:, authenticator_class:)
     router.public_send(verb, path, to: app)
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: liberty
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Alan Ridlehoover
@@ -122,9 +122,13 @@ files:
 - lib/liberty/adapters/request.rb
 - lib/liberty/adapters/response.rb
 - lib/liberty/application.rb
+- lib/liberty/authenticator.rb
+- lib/liberty/authenticators/public.rb
 - lib/liberty/cors.rb
 - lib/liberty/cors/middleware.rb
 - lib/liberty/endpoint.rb
+- lib/liberty/endpoint_builder.rb
+- lib/liberty/errors.rb
 - lib/liberty/router.rb
 - lib/liberty/router/node.rb
 - lib/liberty/router/printer.rb