liberty 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44e1f59a2b827b9bda2ec873fca9e2592db73e23d9ad946ee673be3cca0c8d37
-  data.tar.gz: 8ed828dddae3cc7fbce9957bce6d66a11801f13499761728ca03befd954655cf
+  metadata.gz: 9450a8fadf0c6726d4249f2b6a62f4918045795f199be8ec8bec29412bbaebc1
+  data.tar.gz: 55ea606054dabaeec94add7f6b5fe63a5d38add6eca13dc9f4fc1ef2754ad5c2
 SHA512:
-  metadata.gz: 77a90f8920aef4886192435fecc60c46bdb317405ff447db995b9fd264136bd996c6b3b1123c502b7ad375addc8c2756a6dcecfeccdd3bf573b67b54e4d62703
-  data.tar.gz: 7891e701f9c931e6e43488e2b45bdd47eb0790e4b8fd098aeb7870386460db43d36357768f1010bac54e819530bdad99dc7e26147e92e351af24a0cbb7b2ad84
+  metadata.gz: 17e9cd7824c5b5038daee7fd5d3d441886865dc78562797cd502b8f96f6fd9cd48b2ed92da934265321757a2237e3682092e8653b1b4370260d73b3d9caef253
+  data.tar.gz: 7416e1f47f06cb05dd7fbaadc777f71bbac9bc828a5954f4db401c52e42abc88777ee3fd49ad1e24e22e412953e7d2b188b2a6983b153ea36f535f02a5f7d48c

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [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.4.0)
       json (~> 2.3)
       mustermann (~> 4.0)
       mustermann-contrib (~> 4.0)

data/README.md

@@ -50,6 +50,14 @@ Here's an example for an HTTP get to the `/hello` route, which returns a hello w
 class MyEndpoint < Liberty::Endpoint
   responds_to :get, '/hello'
 
+  def authenticated?
+    true
+  end
+
+  def authorized?
+    true
+  end
+
   def status
     200
   end
@@ -83,6 +91,49 @@ end
 If you configure your CORS headers before you launch your application, `Endpoints` will
 automatically respond with the right headers.
 
+### Authentication & Authorization
+
+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]`.
+
+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.
+
+Here's an example of how to use `#authenticated?` and `#authorized?`:
+
+```ruby
+class YourEndpoint < Liberty::Endpoint
+  responds_to :get, "/your_endpoint"
+
+  def authenticated?
+    !current_user.nil?
+  end
+
+  def www_authenticate_header
+    'Bearer realm="api"'
+  end
+
+  def authorized?
+    current_user.admin?
+  end
+
+  def current_user
+    @current_user ||= Sessions.find_by_token(bearer_token)
+  end
+
+  private
+
+  def bearer_token
+    request.headers[:authorization].to_s.delete_prefix("Bearer ")
+  end
+end
+```
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/lib/liberty/adapters/error_response.rb

@@ -0,0 +1,30 @@
+# 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

@@ -0,0 +1,19 @@
+# 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/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/adapters/response.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "forbidden_response"
+require_relative "unauthenticated_response"
+
 module Liberty
   module Adapters
     class Response
@@ -17,11 +20,22 @@ 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/adapters/unauthenticated_response.rb

@@ -0,0 +1,29 @@
+# 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

data/lib/liberty/endpoint.rb

@@ -22,6 +22,17 @@ 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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: liberty
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Alan Ridlehoover
@@ -116,11 +116,14 @@ 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/cors.rb
 - lib/liberty/cors/middleware.rb