authproto 0.3.0.beta1 → 0.3.0.beta2

data/lib/authproto/metadata/resource_server.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+require_relative '../configuration'
+require_relative '../errors'
+require_relative '../http_client'
+require_relative '../metadata'
+require_relative '../validated_uri'
+
+module AuthProto
+  module Metadata
+
+    #
+    # This class represents a Resource Server (PDS) and is responsible for
+    # validating and managing its metadata. It ensures that the authorization
+    # server URLs provided are valid and compliant with expected standards.
+    # The class also includes functionality to fetch and parse metadata from a
+    # remote URL, raising specific errors for invalid or malformed metadata.
+    #
+
+    class ResourceServer
+
+      # The single authorization server origin advertised by the resource server.
+      # @return [String]
+      attr_reader :authorization_server
+
+      # Validates resource server metadata and its single authorization server origin.
+      #
+      # @param metadata [Hash{String => Object}] discovery document containing `authorization_servers`
+      # @raise [InvalidAuthorizationServer] if the list is missing or does not contain one valid origin
+      # @raise [URI::InvalidURIError] if the authorization server URI cannot be parsed
+      #
+      def initialize(metadata)
+        @authorization_server = validate_authorization_servers(metadata["authorization_servers"])
+      end
+
+      # Fetches `/.well-known/oauth-protected-resource` using the configured transport.
+      # Requires HTTP 200 without redirects, a JSON object served as application/json,
+      # and a resource identifier that exactly matches the requested URL.
+      # URL scheme restrictions are enforced by the configured transport.
+      # The PDS URL must have no userinfo, path prefix, query or fragment.
+      #
+      # @param url [String] resource server/PDS base URL
+      # @return [ResourceServer] validated resource server metadata
+      # @raise [InvalidAuthorizationServer] if HTTP transport, JSON parsing or metadata validation fails
+      # @raise [HTTPClient::SSRFError] if the transport rejects the initial destination
+      # @raise [URI::InvalidURIError] if the PDS or authorization server URL cannot be parsed
+      #
+      def self.from_url(url)
+        validate_source_url(url)
+
+        response = fetch_metadata(url)
+        validate_response(response)
+
+        metadata = parse_metadata(response[:body])
+        validate_resource(metadata["resource"], url)
+
+        new(metadata)
+      end
+
+
+      private
+
+      def validate_authorization_servers(servers)
+        raise InvalidAuthorizationServer, "authorization_servers missing" if servers.nil?
+        raise InvalidAuthorizationServer, "authorization_servers is not an array" unless servers.is_a?(Array)
+        raise InvalidAuthorizationServer, "must have exactly one authorization server" unless servers.length == 1
+
+        uri = ValidatedURI.new(servers.first)
+
+        valid = (
+          uri.scheme == 'https' && (!uri.specified_port || uri.effective_port != 443) &&
+          uri.path.empty? && !uri.query && !uri.fragment && !uri.userinfo
+        )
+
+        raise InvalidAuthorizationServer, "invalid authorization server URL format for #{servers.first}" unless valid
+
+        servers.first
+      end
+
+      class << self
+        private
+
+        def validate_source_url(url)
+          uri = ValidatedURI.new(url)
+
+          unless uri.path.empty? && !uri.userinfo && !uri.query && !uri.fragment
+            raise InvalidAuthorizationServer,
+              "Resource server URL must be an HTTP(S) origin without userinfo, a path prefix, query or fragment"
+          end
+        rescue URI::InvalidURIError => e
+          raise InvalidAuthorizationServer, "Invalid resource server URL: #{e.message}"
+        end
+
+        def fetch_metadata(url)
+          metadata_url = URI.join(url, "/.well-known/oauth-protected-resource")
+
+          AuthProto.configuration.http_client.get(metadata_url.to_s)
+        rescue HTTPClient::HTTPError => e
+          raise InvalidAuthorizationServer, "Failed to fetch resource server metadata: #{e.message}"
+        end
+
+        def validate_response(response)
+          unless response[:status] == 200
+            raise InvalidAuthorizationServer, "Resource server metadata must return HTTP 200"
+          end
+
+          content_type = response[:headers]["content-type"].to_s.split(";", 2).first.to_s.strip
+
+          unless content_type.casecmp?("application/json")
+            raise InvalidAuthorizationServer, "Resource server metadata must use application/json"
+          end
+        end
+
+        def parse_metadata(body)
+          metadata = JSON.parse(body.to_s)
+
+          unless metadata.is_a?(Hash)
+            raise InvalidAuthorizationServer, "Resource server metadata must be a JSON object"
+          end
+
+          metadata
+        rescue JSON::ParserError => e
+          raise InvalidAuthorizationServer, "Invalid JSON in resource server metadata: #{e.message}"
+        end
+
+        def validate_resource(resource, url)
+          unless resource.is_a?(String) && resource == url
+            raise InvalidAuthorizationServer, "Resource server metadata resource must match the requested resource URL"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/authproto/{server_metadata.rb → metadata.rb}

@@ -3,8 +3,8 @@
 module AuthProto
 
   #
-  # Provides functionality for fetching and validating AT Protocol OAuth server metadata
-  # from both Resource Servers (PDS instances) and Authorization Servers (PDS/entryway).
+  # Provides functionality for fetching and validating AT Protocol OAuth metadata
+  # for clients, Resource Servers (PDS instances), and Authorization Servers (PDS/entryway).
   #
   # The flow for resolving an account's authorization server is:
   # 1. Start with PDS URL
@@ -13,16 +13,16 @@ module AuthProto
   # 4. Fetch Authorization Server metadata from /.well-known/oauth-authorization-server
   #
   # @example Resolving authorization server from PDS URL
-  #   resource_server = AuthProto::ServerMetadata::ResourceServer.from_url("https://pds.example.com")
-  #   auth_server_url = resource_server.authorization_servers.first
-  #   auth_server = AuthProto::ServerMetadata::AuthorizationServer.from_issuer(auth_server_url)
+  #   resource_server = AuthProto::Metadata::ResourceServer.from_url("https://pds.example.com")
+  #   auth_server_url = resource_server.authorization_server
+  #   auth_server = AuthProto::Metadata::AuthorizationServer.from_url(auth_server_url)
   #
   # The module includes three main classes:
   # - {ResourceServer} - Handles PDS metadata validation and authorization server discovery
   # - {AuthorizationServer} - Handles authorization server metadata validation
-  # - {OriginURL} - Validates URLs conform to AT Protocol's "simple origin URL" requirements
+  # - {ClientMetadata} - Handles client metadata and registration requirements
   #
 
-  module ServerMetadata
+  module Metadata
   end
 end

data/lib/authproto/minisky.rb

@@ -40,6 +40,7 @@ class Minisky::OAuthClient
   # @param client_id [String] OAuth client metadata URL or localhost client ID
   # @param redirect_uri [String] registered callback URI
   # @param metadata [Hash{String => Object}, nil] preloaded metadata, or `nil` to fetch it
+  # @param signing_key [Hash, JOSE::JWK, nil] private ES256 key for confidential-client authentication
   # @param dpop_key [Hash{String => Object}, nil] existing private DPoP JWK, or `nil` to generate one
   #
   # @raise [AuthProto::InvalidClientMetadata] if metadata is invalid or unavailable
@@ -47,7 +48,7 @@ class Minisky::OAuthClient
   # @raise [AuthProto::HTTPClient::HTTPError, AuthProto::HTTPClient::SSRFError] if fetching metadata fails
   # @see AuthProto::Client#initialize
   #
-  def initialize(host, client_id:, redirect_uri:, metadata: nil, dpop_key: nil, session_id: nil)
+  def initialize(host, client_id:, redirect_uri:, metadata: nil, dpop_key: nil, signing_key: nil, session_id: nil)
     @host = host
     @session_id = session_id
 
@@ -58,7 +59,8 @@ class Minisky::OAuthClient
       client_id: client_id,
       redirect_uri: redirect_uri,
       metadata: metadata,
-      dpop_key: dpop_key
+      dpop_key: dpop_key,
+      signing_key: signing_key
     )
   end
 
@@ -72,8 +74,8 @@ class Minisky::OAuthClient
   #
   # @param options [Hash{Symbol => Object}] options forwarded to {AuthProto::Client#authorize}
   # @option options [String] :handle account handle, optionally prefixed with `@`
-  # @option options [String] :pds_url PDS URL, as an alternative to `handle`
-  # @option options [String] :scope ("atproto") requested scopes
+  # @option options [String] :pds PDS URL, as an alternative to `handle`
+  # @option options [String] :scope ('atproto') requested scopes
   #
   # @return [Hash{Symbol => String}] `:url` to open and pending `:session_id`
   # @raise [AuthProto::Error] if authorization, discovery, PAR or persistence fails
@@ -226,15 +228,11 @@ class Minisky::OAuthClient
     nonce_retries = 0
     refreshed = false
 
-    proof_url = url.dup
-    proof_url.query = nil
-    proof_url.fragment = nil
-
     loop do
       # Fresh proof for every attempt; callers cannot override OAuth auth headers.
       request_headers = headers.reject { |k, v| %w[authorization dpop].include?(k.to_s.downcase) }
       request_headers.merge!(oauth_client.auth_headers(
-                               session_id: session_id, method: request_class::METHOD, url: proof_url.to_s
+                               session_id: session_id, method: request_class::METHOD, url: url.to_s
                              ))
 
       request = request_class.new(url, request_headers)
@@ -245,7 +243,7 @@ class Minisky::OAuthClient
       oauth_client.dpop_client.process_response(response.each_header.to_h, url.to_s) if nonce && !nonce.empty?
       error = authentication_error(response)
 
-      if response.code.to_i == 401 && error == "use_dpop_nonce"
+      if response.code.to_i == 401 && error == AuthProto::DPoP::ERROR_USE_NONCE
         unless nonce && !nonce.empty?
           raise AuthProto::DPoP::Client::Error, "DPoP nonce challenge (HTTP 401) is missing DPoP-Nonce"
         end

data/lib/authproto/par/client.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'cgi'
 require 'json'
 require 'uri'
 
@@ -25,7 +24,7 @@ module AuthProto
     #
     # @example Basic PAR flow
     #   client = AuthProto::PAR::Client.new(
-    #     endpoint: "https://auth.example.com/par",
+    #     authorization_server: authorization_server,
     #     dpop_client: AuthProto::DPoP::Client.new
     #   )
     #
@@ -34,16 +33,14 @@ module AuthProto
     #     config.client_id = "https://app.example.com/oauth-client-metadata.json"
     #     config.redirect_uri = "https://app.example.com/callback"
     #     config.code_challenge = "abc123..."
-    #     config.code_challenge_method = "S256"
     #     config.state = "xyz789..."
-    #     config.scope = "atproto"
+    #     config.scope = 'atproto'
     #   end
     #
     #   response = client.submit(request)
     #
     #   # Build authorization URL using response
-    #   auth_url = client.authorization_url(
-    #     authorize_endpoint: "https://auth.example.com/authorize",
+    #   auth_url = client.build_authorization_url(
     #     request_uri: response.request_uri,
     #     client_id: request.client_id
     #   )
@@ -51,8 +48,7 @@ module AuthProto
     # @example With client authentication (confidential clients)
     #   request = AuthProto::PAR::Request.build do |config|
     #     # ... basic parameters ...
-    #     config.client_assertion_type = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
-    #     config.client_assertion = jwt_token
+    #     config.client_assertion = AuthProto::PAR::ClientAssertion.new(client_id: client_id, signing_key: signing_key)
     #   end
     #
     # All requests use HTTPS and include a fresh DPoP proof from the supplied
@@ -62,29 +58,28 @@ module AuthProto
 
     class Client
 
+      # Authorization server supplying endpoints and the client assertion audience.
+      # @return [Metadata::AuthorizationServer]
+      attr_reader :authorization_server
+
       # HTTPS pushed authorization request endpoint.
       # @return [String]
-      attr_reader :endpoint
+      attr_reader :par_endpoint
 
       # DPoP client used to sign requests.
       # @return [DPoP::Client]
       attr_reader :dpop_client
 
-      # Nonce manager belonging to the DPoP client.
-      # @return [DPoP::NonceManager]
-      attr_reader :nonce_manager
-
       # Creates a PAR transport using the global HTTP client and supplied DPoP client.
       #
-      # @param endpoint [String] HTTPS PAR endpoint
+      # @param authorization_server [Metadata::AuthorizationServer] discovered authorization server metadata
       # @param dpop_client [DPoP::Client] proof generator and nonce tracker
-      # @raise [Error] if the endpoint is malformed or does not use HTTPS
       #
-      def initialize(endpoint:, dpop_client:)
-        @endpoint = endpoint
+      def initialize(authorization_server:, dpop_client:)
+        @authorization_server = authorization_server
+        @par_endpoint = authorization_server.pushed_authorization_request_endpoint
         @dpop_client = dpop_client
         @nonce_manager = dpop_client.nonce_manager
-        validate_endpoint
       end
 
       # Submits a PAR request, handling DPoP nonce requirements
@@ -94,6 +89,8 @@ module AuthProto
       # @raise [Error] if request fails
       #
       def submit(request)
+        raise Error, "Expected a PAR::Request" unless request.is_a?(PAR::Request)
+
         # Try the initial request
         response = make_request(request)
 
@@ -105,7 +102,7 @@ module AuthProto
           store_nonce(nonce)
 
           # Get stored nonce to verify
-          nonce_manager.get(server_origin)
+          @nonce_manager.get(server_origin)
 
           # Generate new proof with nonce and retry
           response = make_request(request)
@@ -124,12 +121,7 @@ module AuthProto
       # @raise [Error] if no supported nonce header is present
       #
       def extract_nonce(response)
-        # Try all possible header key formats
-        headers = response[:headers]
-        nonce = headers["DPoP-Nonce"] ||
-                headers["dpop-nonce"] ||
-                headers["Dpop-Nonce"]
-
+        nonce = response[:headers].find { |k, v| k.downcase == 'dpop-nonce' }&.last
         raise Error, "No DPoP nonce provided in response" unless nonce
 
         nonce
@@ -137,38 +129,38 @@ module AuthProto
 
       # Builds the browser URL using the client ID and returned PAR request URI.
       #
-      # The endpoint's existing query is replaced by these two parameters.
+      # Retains existing query parameters.
       #
-      # @param authorize_endpoint [String] authorization endpoint URL
       # @param request_uri [String] request URI from {Response#request_uri}
       # @param client_id [String] OAuth client ID
       # @return [String] browser authorization URL
       # @raise [URI::InvalidURIError] if the authorization endpoint cannot be parsed
       #
-      def authorization_url(authorize_endpoint:, request_uri:, client_id:)
-        uri = URI(authorize_endpoint)
-        uri.query = encode_params(
-          "request_uri" => request_uri,
-          "client_id" => client_id
-        )
+      def build_authorization_url(request_uri:, client_id:)
+        uri = URI(@authorization_server.authorization_endpoint)
+
+        params = {
+          request_uri: request_uri,
+          client_id: client_id
+        }
+
+        existing_query = uri.query || ''
+        params_query = URI.encode_www_form(params).gsub('*', '%2A')   # unescaped '*' may break links in the terminal
+
+        uri.query = existing_query + (existing_query.empty? ? '' : '&') + params_query
+
         uri.to_s
       end
 
-      private
 
-      def validate_endpoint
-        uri = URI(@endpoint)
-        raise Error, "endpoint must be HTTPS" unless uri.scheme == "https"
-      rescue URI::InvalidURIError => e
-        raise Error, "invalid endpoint URL: #{e.message}"
-      end
+      private
 
       def make_request(request)
         # Generate DPoP proof for this request
         proof = dpop_client.generate_proof(
-          http_method: "POST",
-          http_uri: endpoint,
-          nonce: nonce_manager.get(server_origin)
+          method: 'POST',
+          uri: @par_endpoint,
+          nonce: @nonce_manager.get(server_origin)
         )
 
         # Build headers including DPoP proof
@@ -176,8 +168,8 @@ module AuthProto
 
         # Make the request
         AuthProto.configuration.http_client.post(
-          endpoint,
-          body: request.to_form,
+          @par_endpoint,
+          body: request.to_form(audience: @authorization_server.issuer),
           headers: headers
         )
       end
@@ -191,24 +183,24 @@ module AuthProto
 
       def requires_nonce?(response)
         body = JSON.parse(response[:body])
-        body["error"] == "use_dpop_nonce"
+        body['error'] == DPoP::ERROR_USE_NONCE
       rescue JSON::ParserError
         false
       end
 
       def store_nonce(nonce)
-        nonce_manager.update(nonce: nonce, server_url: server_origin)
+        @nonce_manager.update(nonce: nonce, server_url: server_origin)
       end
 
       def server_origin
-        uri = URI(@endpoint)
+        uri = URI(@par_endpoint)
         "#{uri.scheme}://#{uri.host}#{":#{uri.port}" if uri.port != uri.default_port}"
       end
 
       def handle_error_response(response)
         begin
           error_data = JSON.parse(response[:body])
-          error_message = error_data["error_description"] || error_data["error"] || "Unknown error"
+          error_message = error_data['error_description'] || error_data['error'] || "Unknown error"
         rescue JSON::ParserError
           error_message = "Invalid response from server"
         end
@@ -219,11 +211,19 @@ module AuthProto
       def process_response(response)
         raise Error, "unexpected response status: #{response[:status]}" unless response[:status] == 201
 
+        content_type = (response[:headers] || {}).find { |key, _| key.downcase == 'content-type' }&.last
+
+        unless content_type.to_s.split(';', 2).first.to_s.strip.casecmp?('application/json')
+          raise Error, "PAR response must use application/json"
+        end
+
         begin
           data = JSON.parse(response[:body])
+          raise Error, "PAR response must be a JSON object" unless data.is_a?(Hash)
+
           Response.new(
-            request_uri: data["request_uri"],
-            expires_in: data["expires_in"]
+            request_uri: data['request_uri'],
+            expires_in: data['expires_in']
           )
         rescue JSON::ParserError => e
           raise Error, "invalid JSON response: #{e.message}"
@@ -231,10 +231,6 @@ module AuthProto
           raise Error, "failed to process response: #{e.message}"
         end
       end
-
-      def encode_params(params)
-        params.map { |k, v| "#{CGI.escape(k)}=#{CGI.escape(v.to_s)}" }.join("&")
-      end
     end
   end
 end

data/lib/authproto/par/client_assertion.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'jwt'
+require 'jose'
 require 'securerandom'
 
 require_relative '../errors'
@@ -19,14 +20,21 @@ module AuthProto
       # Raised when client assertion key import or JWT signing fails.
       class Error < AuthProto::Error; end
 
+      attr_reader :signing_key
+
       # Creates an ES256 client assertion signer.
       #
       # @param client_id [String] client ID used in `iss` and `sub`
-      # @param signing_key [JOSE::JWK] private EC P-256 signing key, including its `kid`
+      # @param signing_key [Hash, JOSE::JWK] private EC P-256 signing key, including its `kid`
+      # @raise [Error] if the key cannot sign with ES256 or its usage is incompatible
       #
       def initialize(client_id:, signing_key:)
         @client_id = client_id
-        @signing_key = signing_key
+        @signing_key = validate_signing_key(signing_key)
+      rescue ClientAssertion::Error
+        raise
+      rescue StandardError => e
+        raise Error, "Invalid signing_key: #{e.message}"
       end
 
       # Signs a short-lived client authentication JWT with ES256.
@@ -42,28 +50,63 @@ module AuthProto
         now = Time.now.to_i
 
         payload = {
-          # Required claims
-          iss: @client_id, # Issuer is client_id
-          sub: @client_id, # Subject is client_id
-          aud: audience, # Audience is the authorization server issuer
-          jti: SecureRandom.uuid, # Unique identifier
-          exp: now + lifetime, # Expiration time
-          iat: now # Issued at time
+          iss: @client_id,        # issuer
+          sub: @client_id,        # subject
+          aud: audience,          # audience is the authorization server issuer
+          jti: SecureRandom.uuid, # token identifier
+          exp: now + lifetime,    # expiration time
+          iat: now                # issued at time
         }
 
-        # Header specifying ES256 algorithm for signing
         header = {
-          alg: "ES256",
-          typ: "JWT",
-          kid: @signing_key.fields["kid"]
+          alg: 'ES256',
+          typ: 'JWT',
+          kid: @signing_key.fields['kid']
         }
 
-        # Sign and return the JWT
         key = JWT::JWK.import(@signing_key.to_map.to_h)
-        JWT.encode(payload, key, "ES256", header)
+        JWT.encode(payload, key, 'ES256', header)
       rescue JWT::Error, ArgumentError => e
         raise Error, "Failed to generate client assertion: #{e.message}"
       end
+
+
+      private
+
+      def validate_signing_key(signing_key)
+        data = signing_key.is_a?(JOSE::JWK) ? signing_key.to_map.to_h : signing_key
+
+        raise Error, "signing_key must be a hash or a JOSE::JWK" unless data.is_a?(Hash)
+        raise Error, "signing_key must be active" if data['revoked']
+
+        unless data['kty'] == 'EC' && data['crv'] == 'P-256'
+          raise Error, "signing_key must be a EC P-256 JWK"
+        end
+
+        unless data['d'].is_a?(String) && !data['d'].empty?
+          raise Error, "signing_key must be a private key ('d' field must not be empty)"
+        end
+
+        %w[kid x y].each do |field|
+          unless data[field].is_a?(String) && !data[field].empty?
+            raise Error, "signing_key '#{field}' field must not be empty"
+          end
+        end
+
+        if (data.key?('alg') && data['alg'] != 'ES256') ||
+           (data.key?('use') && data['use'] != 'sig') ||
+           (data.key?('key_ops') && (!data['key_ops'].is_a?(Array) || !data['key_ops'].include?('sign')))
+          raise Error, "signing_key must be active and permit ES256 signing"
+        end
+
+        signing_key = JOSE::JWK.from_map(data)
+
+        imported = JWT::JWK.import(data)
+        proof = JWT.encode({}, imported, 'ES256')
+        JWT.decode(proof, imported.public_key, true, algorithms: ['ES256'])
+
+        signing_key
+      end
     end
   end
 end