liberty 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9450a8fadf0c6726d4249f2b6a62f4918045795f199be8ec8bec29412bbaebc1
-  data.tar.gz: 55ea606054dabaeec94add7f6b5fe63a5d38add6eca13dc9f4fc1ef2754ad5c2
+  metadata.gz: fb4d162f0b2ce1791b670b9b9093a8638737aec1c142908d321ebcba16499c4f
+  data.tar.gz: 7da18983c0aa557d727059daef386d429a8a1e8abeb4cd3473b8ec2ee0e76104
 SHA512:
-  metadata.gz: 17e9cd7824c5b5038daee7fd5d3d441886865dc78562797cd502b8f96f6fd9cd48b2ed92da934265321757a2237e3682092e8653b1b4370260d73b3d9caef253
-  data.tar.gz: 7416e1f47f06cb05dd7fbaadc777f71bbac9bc828a5954f4db401c52e42abc88777ee3fd49ad1e24e22e412953e7d2b188b2a6983b153ea36f535f02a5f7d48c
+  metadata.gz: 9b657a059f19264ebab5a4cd059f50bf5d6c9057b700b4a6e4121ca35583ad1dd1f3cbe28988993a59f0e44713d8912a8d47699b0cbad66ae2e9ebcaae17e489
+  data.tar.gz: 3a6e8297c743040dc5d74f1cfbba70c13ba40a2d575e9da70859c924c0f403959b9ff13f4ec733a12e82f7b8ef1d94646d025c97fb6f749bb16202e237b56880

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    liberty (0.4.0)
+    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,15 +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'
-
-  def authenticated?
-    true
-  end
-
-  def authorized?
-    true
-  end
+  responds_to :get, '/hello', authenticated_by: Liberty::Authenticators::Public
 
   def status
     200
@@ -70,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.
@@ -91,49 +87,122 @@ end
 If you configure your CORS headers before you launch your application, `Endpoints` will
 automatically respond with the right headers.
 
-### Authentication & Authorization
+### 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.
 
-Every `Endpoint` has two hooks: `#authenticated?` and `#authorized?`. Both default to `false`,
-so an endpoint that does not implement them responds with `401 Authentication required`. Override
-them to plug in your own auth. Liberty checks `#authenticated?` first and responds with a 401 when
-it returns `false`. It then checks `#authorized?` and responds with `403 Forbidden` when that
-returns `false`. Your endpoint's status, headers, and content are only consulted when both return
-`true`. The raw `Authorization` header is available as `request.headers[:authorization]`.
+The base class raises on both until you override them, so an authenticator cannot admit anyone
+by omission either.
 
-A 401 response should tell the client how to authenticate. Override `#www_authenticate_header`
-to return the challenge, such as `Bearer realm="api"`, and Liberty adds it as the
-`WWW-Authenticate` header on 401 responses. When it returns `nil` the header is omitted.
+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.
 
-Here's an example of how to use `#authenticated?` and `#authorized?`:
+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
-class YourEndpoint < Liberty::Endpoint
-  responds_to :get, "/your_endpoint"
+module Authenticators
+  class Session < Liberty::Authenticator
+    def initialize(users: UsersRepository.new)
+      @users = users
+    end
 
-  def authenticated?
-    !current_user.nil?
-  end
+    def principal
+      @users.find(request.env["rack.session"][:user_id])
+    end
 
-  def www_authenticate_header
-    'Bearer realm="api"'
+    def challenge_endpoint_class = RedirectToLogin
   end
+end
 
-  def authorized?
-    current_user.admin?
-  end
+class RedirectToLogin < Liberty::Endpoint
+  def status = 303
+
+  def headers = {"location" => "/login"}
+end
 
-  def current_user
-    @current_user ||= Sessions.find_by_token(bearer_token)
+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
 
-  private
+  def headers = {"www-authenticate" => 'Bearer realm="api"'}
 
-  def bearer_token
-    request.headers[:authorization].to_s.delete_prefix("Bearer ")
+  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/response.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "forbidden_response"
-require_relative "unauthenticated_response"
-
 module Liberty
   module Adapters
     class Response
@@ -20,22 +17,11 @@ module Liberty
       end
 
       def to_rack_response
-        return unauthenticated_response unless endpoint.authenticated?
-        return forbidden_response unless endpoint.authorized?
-
         [status, headers, rack_body]
       end
 
       private
 
-      def unauthenticated_response
-        UnauthenticatedResponse.new(endpoint).to_rack_response
-      end
-
-      def forbidden_response
-        ForbiddenResponse.new(endpoint).to_rack_response
-      end
-
       def status
         endpoint.status
       end

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
@@ -22,17 +28,6 @@ module Liberty
       request.headers[:preferred_media_type]
     end
 
-    def authenticated?
-      false
-    end
-
-    def www_authenticate_header
-    end
-
-    def authorized?
-      false
-    end
-
     def status
       DEFAULT_STATUS
     end

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.4.0"
+  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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Alan Ridlehoover
@@ -116,18 +116,19 @@ files:
 - Rakefile
 - assets/liberty.png
 - lib/liberty.rb
-- lib/liberty/adapters/error_response.rb
-- lib/liberty/adapters/forbidden_response.rb
 - lib/liberty/adapters/parsers/factory.rb
 - lib/liberty/adapters/parsers/json.rb
 - lib/liberty/adapters/parsers/null.rb
 - lib/liberty/adapters/request.rb
 - lib/liberty/adapters/response.rb
-- lib/liberty/adapters/unauthenticated_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

data/lib/liberty/adapters/error_response.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Liberty
-  module Adapters
-    class ErrorResponse
-      attr_reader :endpoint
-
-      def initialize(endpoint)
-        @endpoint = endpoint
-      end
-
-      def to_rack_response
-        [status, headers, rack_body]
-      end
-
-      private
-
-      def headers
-        {
-          Response::CONTENT_LENGTH => body.bytesize.to_s,
-          Response::CONTENT_TYPE => Response::MIME_TYPE_TEXT
-        }
-      end
-
-      def rack_body
-        endpoint.request.head? ? [] : [body]
-      end
-    end
-  end
-end

data/lib/liberty/adapters/forbidden_response.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "error_response"
-
-module Liberty
-  module Adapters
-    class ForbiddenResponse < ErrorResponse
-      private
-
-      def status
-        403
-      end
-
-      def body
-        "Forbidden"
-      end
-    end
-  end
-end

data/lib/liberty/adapters/unauthenticated_response.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "error_response"
-
-module Liberty
-  module Adapters
-    class UnauthenticatedResponse < ErrorResponse
-      WWW_AUTHENTICATE = "www-authenticate"
-
-      private
-
-      def status
-        401
-      end
-
-      def headers
-        challenge ? super.merge(WWW_AUTHENTICATE => challenge) : super
-      end
-
-      def challenge
-        endpoint.www_authenticate_header
-      end
-
-      def body
-        "Authentication required"
-      end
-    end
-  end
-end