authproto 0.3.0.beta1 → 0.3.0.beta2

data/lib/authproto/client.rb

@@ -5,17 +5,17 @@ require 'jose'
 require 'json'
 require 'uri'
 
-require_relative 'client_metadata'
 require_relative 'configuration'
 require_relative 'dpop/client'
 require_relative 'dpop/key_manager'
 require_relative 'errors'
+require_relative 'metadata/authorization_server'
+require_relative 'metadata/client_metadata'
+require_relative 'metadata/resource_server'
 require_relative 'par'
 require_relative 'par/client'
 require_relative 'par/client_assertion'
 require_relative 'par/request'
-require_relative 'server_metadata/authorization_server'
-require_relative 'server_metadata/resource_server'
 require_relative 'state/session_manager'
 require_relative 'state/token_set'
 require_relative 'storage/key_builder'
@@ -66,7 +66,7 @@ module AuthProto
     attr_reader :redirect_uri
 
     # Validated client metadata.
-    # @return [ClientMetadata]
+    # @return [Metadata::ClientMetadata]
     attr_reader :client_metadata
 
     # Manager for stored OAuth sessions.
@@ -85,6 +85,7 @@ module AuthProto
     # @param client_id [String] OAuth client ID URL
     # @param redirect_uri [String] callback URI listed in `redirect_uris`
     # @param metadata [Hash{String => Object}, nil] preloaded metadata, or `nil` to fetch `client_id`
+    # @param signing_key [Hash, JOSE::JWK, nil] private ES256 client-authentication key, separate from public metadata
     # @param dpop_key [Hash{String => Object}, nil] existing private DPoP JWK, or `nil` to generate one
     #
     # @raise [InvalidClientMetadata] if client metadata is invalid or unavailable
@@ -92,13 +93,15 @@ module AuthProto
     # @raise [DPoP::KeyManager::KeyError] if the DPoP key cannot be imported or generated
     # @raise [HTTPClient::HTTPError, HTTPClient::SSRFError] if fetching client metadata fails
     #
-    def initialize(client_id:, redirect_uri:, metadata: nil, dpop_key: nil)
+    def initialize(client_id:, redirect_uri:, metadata: nil, dpop_key: nil, signing_key: nil)
       @client_id = client_id
       @redirect_uri = redirect_uri
 
-      # Initialize core dependencies
+      # Client metadata is fetched from .well-known if not provided directly
       @client_metadata = load_client_metadata(metadata)
+
       validate_redirect_uri
+      @signing_key = initialize_signing_key(signing_key)
 
       @session_manager = State::SessionManager.new
       @dpop_client = initialize_dpop(dpop_key)
@@ -106,12 +109,12 @@ module AuthProto
 
     # Starts authorization, stores a pending session, and submits a PAR request.
     #
-    # Supply exactly one of `handle` or `pds_url`. Open the returned `:url` in a browser
+    # Supply exactly one of `handle` or `pds`. Open the returned `:url` in a browser
     # and pass the eventual callback parameters to {#handle_callback}.
     #
     # @param handle [String, nil] account handle (optionally prefixed with `@`) or DID
-    # @param pds_url [String, nil] PDS URL when no handle is supplied
-    # @param scope [String] space-separated scopes, including `atproto`
+    # @param pds [String, nil] PDS URL when no handle is supplied
+    # @param scope [String] space-separated scopes, which must all be declared in client metadata, including `atproto`
     #
     # @return [Hash{Symbol => String}] `:url` is the browser URL; `:session_id` identifies the pending session
     # @raise [Error] if identity arguments or scope are invalid, the handle cannot be verified, or no HTTPS PDS is found
@@ -124,33 +127,25 @@ module AuthProto
     # @raise [Storage::StorageError] if session storage or locking fails
     # @raise [Encryption::EncryptionError] if session serialization cannot encrypt secrets
     #
-    def authorize(handle: nil, pds_url: nil, scope: "atproto")
-      validate_auth_params(handle, pds_url, scope)
-
-      # Create new session
-      session = session_manager.create_session(
-        client_id: client_id,
-        scope: scope
-      )
+    def authorize(handle: nil, pds: nil, scope: 'atproto')
+      validate_auth_params(handle, pds, scope)
 
-      # Store session with storage backend
-      session_manager.update_session(session)
+      if !pds
+        did = DIDKit::DID.resolve_handle(handle)
+        raise Error, "Could not resolve or verify identity #{handle}" unless did
 
-      # Resolve identity and authorization server if handle provided
-      if handle
-        auth_info = resolve_from_handle(handle, session)
-      elsif pds_url
-        auth_info = resolve_from_pds(pds_url, session)
-      else
-        raise Error, "Either handle or pds_url must be provided"
+        pds = did.document.pds_endpoint
+        raise Error, "No HTTPS PDS location found for #{did}" unless pds && URI(pds).is_a?(URI::HTTPS)
       end
 
-      # Generate authorization URL
-      auth_url = generate_authorization_url(
-        auth_info[:server],
-        session,
-        login_hint: handle
-      )
+      authorization_server = resolve_auth_server(pds)
+
+      session = session_manager.create_session(client_id: @client_id, scope: scope)
+      session.authorization_server = authorization_server
+      session.did = did&.to_s
+      session_manager.update_session(session)
+
+      auth_url = submit_authorization_par(authorization_server, session, login_hint: handle)
 
       {
         url: auth_url,
@@ -180,46 +175,28 @@ module AuthProto
     # @raise [Encryption::EncryptionError] if tokens cannot be encrypted for storage
     #
     def handle_callback(code:, state:, iss:)
-      # Find and validate session
       session = session_manager.get_session_by_state(state)
-      raise CallbackError, "Invalid state parameter" unless session
 
-      # Verify issuer matches session
+      raise CallbackError, "Invalid state parameter" unless session
       raise CallbackError, "Issuer mismatch" unless session.auth_server && session.auth_server.issuer == iss
 
       AuthProto.storage.with_lock(Storage::KeyBuilder.lock_key("session", session.session_id), ttl: 30) do
-        # Exchange code for tokens
-        token_response = exchange_code(
-          code: code,
-          session: session
-        )
-
-        # Validate token response
-        validate_token_response(token_response, session)
+        response = exchange_code(code: code, session: session)
+        validate_token_response(response, session)
 
-        # Create token set and store in session
         token_set = State::TokenSet.new(
-          access_token: token_response["access_token"],
-          token_type: token_response["token_type"],
-          expires_in: token_response["expires_in"],
-          refresh_token: token_response["refresh_token"],
-          scope: token_response["scope"],
-          sub: token_response["sub"]
+          access_token: response['access_token'],
+          token_type: response['token_type'],
+          expires_in: response['expires_in'],
+          refresh_token: response['refresh_token'],
+          scope: response['scope'],
+          sub: response['sub']
         )
-        session.tokens = token_set
 
-        # Update stored session
+        session.tokens = token_set
         session_manager.update_session(session)
 
-        {
-          access_token: token_set.access_token,
-          token_type: token_set.token_type,
-          expires_in: (token_set.expires_at - Time.now).to_i,
-          refresh_token: token_set.refresh_token,
-          scope: token_set.scope,
-          session_id: session.session_id,
-          did: session.did
-        }
+        session.session_data
       end
     end
 
@@ -228,6 +205,7 @@ module AuthProto
     # The result contains `:access_token` (String), `:token_type` (String, `DPoP`),
     # `:expires_in` (Integer seconds remaining), `:refresh_token` (String or nil),
     # and `:scope` (String).
+    # It also contains `:session_id` (String) and `:did` (String).
     # This method does not refresh expired tokens.
     #
     # @param session_id [String] session identifier
@@ -237,13 +215,7 @@ module AuthProto
       session = session_manager.get_session(session_id)
       return nil unless session&.authorized?
 
-      {
-        access_token: session.tokens.access_token,
-        token_type: session.tokens.token_type,
-        expires_in: (session.tokens.expires_at - Time.now).to_i,
-        refresh_token: session.tokens.refresh_token,
-        scope: session.tokens.scope
-      }
+      session.session_data
     end
 
     # Refreshes a renewable session and persists the replacement tokens.
@@ -251,11 +223,11 @@ module AuthProto
     # The result contains `:access_token` (String), `:token_type` (String, `DPoP`),
     # `:expires_in` (Integer seconds remaining), `:refresh_token` (String or nil),
     # and `:scope` (String).
-    # The result also contains `:session_id` (String). An expired access token can
+    # The result also contains `:session_id` (String) and `:did` (String). An expired access token can
     # still be refreshed when the stored session has a refresh token.
     #
     # @param session_id [String] session to refresh
-    # @return [Hash{Symbol => String, Integer, nil}] replacement tokens and session ID
+    # @return [Hash{Symbol => String, Integer, nil}] replacement tokens and session identifiers
     # @raise [TokenError] if the session is missing or has no refresh token
     # @raise [Token::RefreshError] if token refresh fails or exhausts retries
     # @raise [State::SessionError] if replacement tokens have a different subject
@@ -264,6 +236,7 @@ module AuthProto
     #
     def refresh_token(session_id)
       session = session_manager.get_session(session_id)
+
       raise TokenError, "Invalid session" unless session
       raise TokenError, "Session not authorized" unless session.renewable?
 
@@ -272,23 +245,16 @@ module AuthProto
           session: session,
           dpop_client: @dpop_client,
           auth_server: session.auth_server,
-          client_metadata: client_metadata
+          client_metadata: @client_metadata,
+          signing_key: @signing_key
         )
 
-        new_tokens = refresher.perform
-        session.tokens = new_tokens
+        new_tokens = refresher.perform_refresh
 
-        # Update stored session
+        session.tokens = new_tokens
         session_manager.update_session(session)
 
-        {
-          access_token: new_tokens.access_token,
-          token_type: new_tokens.token_type,
-          expires_in: (new_tokens.expires_at - Time.now).to_i,
-          refresh_token: new_tokens.refresh_token,
-          scope: new_tokens.scope,
-          session_id: session.session_id
-        }
+        session.session_data
       end
     end
 
@@ -318,19 +284,19 @@ module AuthProto
     #
     def auth_headers(session_id:, method:, url:)
       session = session_manager.get_session(session_id)
+
       raise TokenError, "Invalid session" unless session
       raise TokenError, "Session not authorized" unless session.authorized?
 
-      # Generate DPoP proof
-      proof = dpop_client.generate_proof(
-        http_method: method,
-        http_uri: url,
+      dpop_proof = dpop_client.generate_proof(
+        method: method,
+        uri: url,
         access_token: session.tokens.access_token
       )
 
       {
         "Authorization" => "DPoP #{session.tokens.access_token}",
-        "DPoP" => proof
+        "DPoP" => dpop_proof
       }
     end
 
@@ -340,10 +306,11 @@ module AuthProto
     # @return [void]
     # @raise [Storage::StorageError] if deletion or locking fails
     #
-    def remove_session(session_id)
+    def delete_session(session_id)
       key = Storage::KeyBuilder.session_key(session_id)
+
       AuthProto.storage.delete(key)
-      session_manager.remove_session(session_id)
+      session_manager.delete_session(session_id)
     end
 
     # Invokes the session manager's expiry cleanup hook.
@@ -356,119 +323,116 @@ module AuthProto
       session_manager.cleanup_expired
     end
 
+
     private
 
     def load_client_metadata(metadata)
       if metadata
-        ClientMetadata.new(metadata)
+        Metadata::ClientMetadata.new(metadata)
       else
-        ClientMetadata.from_url(@client_id)
+        Metadata::ClientMetadata.from_url(@client_id)
       end
     end
 
     def validate_redirect_uri
-      valid = @client_metadata.redirect_uris.include?(@redirect_uri)
-      raise Error, "redirect_uri not found in client metadata" unless valid
+      unless @client_metadata.redirect_uris.include?(@redirect_uri)
+        raise Error, "redirect_uri not found in client metadata"
+      end
     end
 
-    def initialize_dpop(key)
-      key_manager = if key
-                      DPoP::KeyManager.from_jwk(key)
-                    else
-                      DPoP::KeyManager.new
-                    end
+    def initialize_signing_key(key)
+      if @client_metadata.confidential?
+        raise InvalidClientMetadata, "Confidential clients require a signing_key" if key.nil?
+      else
+        raise InvalidClientMetadata, "Public clients must not supply a signing_key" unless key.nil?
+        return nil
+      end
 
-      DPoP::Client.new(key_manager: key_manager)
-    end
+      assertion = PAR::ClientAssertion.new(client_id: @client_id, signing_key: key)
+      private_key = assertion.signing_key
 
-    def validate_auth_params(handle, pds_url, scope)
-      raise Error, "scope must include 'atproto'" unless scope.split.include?("atproto")
-      raise Error, "handle or pds_url must be provided" if handle.nil? && pds_url.nil?
-      raise Error, "cannot provide both handle and pds_url" if handle && pds_url
-    end
+      if @client_metadata.jwks
+        public_key = private_key.to_public.to_map.to_h
 
-    def resolve_from_handle(handle, session)
-      did = DIDKit::DID.resolve_handle(handle)
-      raise Error, "Could not resolve or verify identity #{handle}" unless did
+        key_in_jwks = @client_metadata.jwks['keys'].any? { |candidate|
+          metadata_key_matches_public_key?(candidate, public_key)
+        }
+
+        raise InvalidClientMetadata, "signing_key must match an active public key advertised in jwks" if !key_in_jwks
+      end
 
-      pds_url = did.document.pds_endpoint
-      raise Error, "No HTTPS PDS location found for #{did}" unless pds_url && URI(pds_url).is_a?(URI::HTTPS)
+      private_key
+    end
 
-      session.did = did.to_s
+    def metadata_key_matches_public_key?(candidate, public_key)
+      return false if candidate['revoked']
+      return false if candidate.key?('alg') && candidate['alg'] != 'ES256'
+      return false if candidate.key?('use') && candidate['use'] != 'sig'
+      return false if candidate.key?('key_ops') && !candidate['key_ops'].include?('verify')
 
-      # Get authorization server from PDS
-      server = resolve_auth_server(pds_url)
-      session.authorization_server = server
+      %w[kid kty crv x y].all? { |field| candidate[field] == public_key[field] }
+    end
 
-      # Update stored session
-      session_manager.update_session(session)
+    def initialize_dpop(key)
+      key_manager = key ? DPoP::KeyManager.from_jwk(key) : DPoP::KeyManager.new
 
-      { server: server, pds: pds_url }
+      DPoP::Client.new(key_manager: key_manager)
     end
 
-    def resolve_from_pds(pds_url, session)
-      # Get authorization server from PDS
-      server = resolve_auth_server(pds_url)
-      session.authorization_server = server
+    def validate_auth_params(handle, pds, scope)
+      unless scope.is_a?(String) && scope.valid_encoding? && Metadata::ClientMetadata::SCOPE_PATTERN.match?(scope)
+        raise Error, "scope must contain valid tokens separated by single spaces"
+      end
 
-      # Update stored session
-      session_manager.update_session(session)
+      requested_scopes = scope.split(' ')
+      raise Error, "scope must include 'atproto'" unless requested_scopes.include?('atproto')
+
+      undeclared_scopes = requested_scopes - @client_metadata.scope.split(' ')
+
+      unless undeclared_scopes.empty?
+        raise Error, "scope contains values not declared in client metadata: #{undeclared_scopes.join(' ')}"
+      end
 
-      { server: server, pds: pds_url }
+      raise Error, "handle or pds must be provided" if handle.nil? && pds.nil?
+      raise Error, "cannot provide both handle and pds" if handle && pds
     end
 
-    def resolve_auth_server(pds_url)
-      # Get resource server metadata
-      resource_server = ServerMetadata::ResourceServer.from_url(pds_url)
-      auth_server_url = resource_server.authorization_servers.first
+    def resolve_auth_server(pds)
+      resource_server = Metadata::ResourceServer.from_url(pds)
+      auth_server_url = resource_server.authorization_server
 
-      # Get and validate authorization server metadata
-      ServerMetadata::AuthorizationServer.from_issuer(auth_server_url)
+      Metadata::AuthorizationServer.from_url(auth_server_url)
     end
 
-    def generate_authorization_url(auth_server, session, login_hint: nil)
-      # Create PAR client
+    def submit_authorization_par(authorization_server, session, login_hint: nil)
       par_client = PAR::Client.new(
-        endpoint: auth_server.pushed_authorization_request_endpoint,
+        authorization_server: authorization_server,
         dpop_client: @dpop_client
       )
 
-      # Build PAR request
-      par_request = PAR::Request.build do |config|
-        config.client_id = client_id
-        config.redirect_uri = redirect_uri
-        config.state = session.state_token
-        config.scope = session.scope
-        config.login_hint = login_hint if login_hint
-
-        # Add PKCE parameters
-        config.code_challenge = session.pkce_challenge
-        config.code_challenge_method = "S256"
-
-        # Public clients use PKCE and DPoP without client authentication.
-        if client_metadata.confidential?
-          signing_key = JOSE::JWK.from_map(client_metadata.jwks.fetch("keys").first)
-          client_assertion = PAR::ClientAssertion.new(client_id: client_id, signing_key: signing_key)
-          config.client_assertion = client_assertion.generate_jwt(audience: auth_server.issuer)
-          config.client_assertion_type = PAR::CLIENT_ASSERTION_TYPE
+      par_request = PAR::Request.build do |req|
+        req.client_id = @client_id
+        req.redirect_uri = @redirect_uri
+        req.state = session.state_token
+        req.scope = session.scope
+        req.login_hint = login_hint if login_hint
+        req.code_challenge = session.pkce_challenge
+
+        if @client_metadata.confidential?
+          req.client_assertion = PAR::ClientAssertion.new(client_id: @client_id, signing_key: @signing_key)
         end
 
-        # Add DPoP proof
-        proof = @dpop_client.generate_proof(
-          http_method: "POST",
-          http_uri: auth_server.pushed_authorization_request_endpoint
+        req.dpop_proof = @dpop_client.generate_proof(
+          method: 'POST',
+          uri: authorization_server.pushed_authorization_request_endpoint
         )
-        config.dpop_proof = proof
       end
 
-      # Submit PAR request
-      response = par_client.submit(par_request)
+      par_response = par_client.submit(par_request)
 
-      # Build final authorization URL
-      par_client.authorization_url(
-        authorize_endpoint: auth_server.authorization_endpoint,
-        request_uri: response.request_uri,
-        client_id: client_id
+      par_client.build_authorization_url(
+        request_uri: par_response.request_uri,
+        client_id: @client_id
       )
     end
 
@@ -496,33 +460,28 @@ module AuthProto
     end
 
     def make_token_request(code, session)
-      # Generate proof
-      proof = dpop_client.generate_proof(
-        http_method: "POST",
-        http_uri: session.auth_server.token_endpoint
+      dpop_proof = dpop_client.generate_proof(
+        method: 'POST',
+        uri: session.auth_server.token_endpoint
       )
 
       body = {
-        grant_type: "authorization_code",
+        grant_type: 'authorization_code',
         code: code,
-        redirect_uri: redirect_uri,
-        client_id: client_id,
+        redirect_uri: @redirect_uri,
+        client_id: @client_id,
         code_verifier: session.pkce_verifier
       }
 
-      # Add client authentication
-      if client_metadata.confidential?
-        signing_key = JOSE::JWK.from_map(client_metadata.jwks["keys"].first)
-        client_assertion = PAR::ClientAssertion.new(
-          client_id: client_id,
-          signing_key: signing_key
+      if @client_metadata.confidential?
+        assertion = PAR::ClientAssertion.new(
+          client_id: @client_id,
+          signing_key: @signing_key
         )
 
         body.merge!(
           client_assertion_type: PAR::CLIENT_ASSERTION_TYPE,
-          client_assertion: client_assertion.generate_jwt(
-            audience: session.auth_server.issuer
-          )
+          client_assertion: assertion.generate_jwt(audience: session.auth_server.issuer)
         )
       end
 
@@ -531,7 +490,7 @@ module AuthProto
         body: body,
         headers: {
           "Content-Type" => "application/x-www-form-urlencoded",
-          "DPoP" => proof
+          "DPoP" => dpop_proof
         }
       )
     end
@@ -540,16 +499,14 @@ module AuthProto
       return false unless response[:status] == 400
 
       error_data = JSON.parse(response[:body])
-      error_data["error"] == "use_dpop_nonce"
+      error_data['error'] == DPoP::ERROR_USE_NONCE
     rescue JSON::ParserError
       false
     end
 
     def extract_dpop_nonce(response)
       headers = response[:headers]
-      nonce = headers["DPoP-Nonce"] ||
-              headers["dpop-nonce"] ||
-              headers["Dpop-Nonce"]
+      nonce = headers.find { |k, v| k.downcase == 'dpop-nonce' }&.last
 
       raise TokenError, "No DPoP nonce provided in error response" unless nonce
 
@@ -557,27 +514,19 @@ module AuthProto
     end
 
     def validate_token_response(response, session)
-      # Required fields
-      %w[access_token token_type expires_in scope sub].each do |field|
+      ['access_token', 'token_type', 'expires_in', 'scope', 'sub'].each do |field|
         raise TokenError, "Missing #{field} in token response" unless response[field]
       end
 
-      # Token type must be DPoP
-      raise TokenError, "Invalid token_type: #{response["token_type"]}" unless response["token_type"] == "DPoP"
-
-      # Scope must include atproto
-      raise TokenError, "Missing atproto scope in token response" unless response["scope"].split.include?("atproto")
-
-      # If we have a pre-resolved DID, verify it matches
-      raise TokenError, "Subject mismatch in token response" if session.did && session.did != response["sub"]
+      raise TokenError, "Invalid token_type: #{response['token_type']}" unless response['token_type'] == 'DPoP'
+      raise TokenError, "Missing atproto scope in token response" unless response['scope'].split.include?('atproto')
 
-      # Process DPoP-Nonce from response headers if present
-      return unless response[:headers] && response[:headers]["DPoP-Nonce"]
+      # If we have a pre-resolved DID, verify that it matches
+      raise TokenError, "Subject mismatch in token response" if session.did && session.did != response['sub']
 
-      dpop_client.process_response(
-        response[:headers],
-        session.auth_server.issuer
-      )
+      if response[:headers] && response[:headers]["DPoP-Nonce"]
+        dpop_client.process_response(response[:headers], session.auth_server.issuer)
+      end
     end
   end
 end