authproto 0.3.0.beta1

data/lib/authproto/localhost_server.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'socket'
+require 'timeout'
+require 'uri'
+
+module AuthProto
+
+  #
+  # One-shot loopback OAuth callback listener for use from IRB.
+  #
+
+  class LocalhostServer
+
+    # Maximum total size of an incoming request header block in bytes.
+    # @return [Integer]
+    MAX_HEADER_BYTES = 16_384
+
+    # Maximum time in seconds to read one incoming request header block.
+    # @return [Integer]
+    REQUEST_TIMEOUT = 5
+
+    # Literal IP ranges accepted for callback listeners.
+    # @return [Array<IPAddr>]
+    LOOPBACK_RANGES = [IPAddr.new("127.0.0.0/8"), IPAddr.new("::1/128")].freeze
+
+    #
+    # Raised when the authorization server returns an OAuth error to the loopback listener.
+    #
+
+    class CallbackError < StandardError
+
+      # OAuth error code returned in the callback.
+      # @return [String]
+      attr_reader :error_code
+
+      # Optional human-readable error description from the authorization server.
+      # @return [String, nil]
+      attr_reader :error_description
+
+      # Creates an error for an authorization server's rejected callback.
+      #
+      # @param error_code [String] callback `error` value
+      # @param error_description [String, nil] callback `error_description` value
+      #
+      def initialize(error_code, error_description)
+        @error_code = error_code
+        @error_description = error_description
+
+        super([error_code, error_description].compact.join(": "))
+      end
+    end
+
+    #
+    # Signals an invalid callback HTTP request; the listener catches it and keeps waiting.
+    #
+
+    class InvalidRequest < StandardError
+    end
+
+    # Creates a one-shot loopback callback listener and blocks until login finishes.
+    #
+    # Open the authorization URL yourself while this call blocks. The callback block
+    # runs in the calling thread. Unrelated/malformed requests keep the listener alive.
+    # The listener closes after success, an OAuth error, a block exception, or interruption.
+    #
+    # @param metadata [Hash{String, Symbol => Object}] metadata whose first redirect URI selects host, port and path
+    # @param timeout [Numeric] positive maximum wait for incoming connections, in seconds; defaults to 300
+    # @param block [Proc] callback handler required to finish token exchange
+    #
+    # @yield [params] callback handler; any exception is propagated after socket cleanup
+    # @yieldparam params [Hash{Symbol => String}] `:code`, `:state`, and `:iss` from the query string
+    # @yieldreturn [Object] arbitrary result returned from `start`, including `nil` or `false`
+    # @return [Object] callback block result
+    #
+    # @raise [ArgumentError] if metadata/timeout is invalid or no block is supplied
+    # @raise [CallbackError] if the callback contains an OAuth `error` parameter
+    # @raise [Timeout::Error] if waiting for an incoming connection exceeds the deadline
+    # @raise [SystemCallError, IOError] if binding or accepting a connection fails
+    # @raise [Interrupt] when interrupted, for example with Ctrl-C
+    #
+    def self.start(metadata, timeout: 300, &block)
+      new(metadata).start(timeout: timeout, &block)
+    end
+
+    # Selects the first redirect URI in metadata for a loopback HTTP listener.
+    #
+    # Accepts `localhost`, IPv4 loopback, or IPv6 loopback. The URI must have a valid
+    # port and no user information or fragment. Its path is used as the callback path.
+    #
+    # @param metadata [Hash{String, Symbol => Object}] metadata containing a nonempty `redirect_uris` array of strings
+    # @raise [ArgumentError] if the first redirect URI is missing, malformed or not a supported HTTP loopback URL
+    #
+    def initialize(metadata)
+      redirects = metadata['redirect_uris'] || metadata[:redirect_uris]
+
+      unless redirects.is_a?(Array) && redirects.first.is_a?(String)
+        raise ArgumentError, "metadata must contain a non-empty redirect_uris array"
+      end
+
+      @uri = URI(redirects.first)
+
+      unless @uri.is_a?(URI::HTTP) && @uri.scheme == "http" && loopback_host?(@uri.hostname)
+        raise ArgumentError, "The first redirect URI must be an HTTP loopback URL"
+      end
+
+      raise ArgumentError, "The redirect URI should have a valid port" unless @uri.port.between?(1, 65_535)
+      raise ArgumentError, "The redirect URI should not include user info" unless !@uri.userinfo
+      raise ArgumentError, "The redirect URI should not include a URL fragment" unless !@uri.fragment
+
+      @path = (@uri.path.empty?) ? "/" : @uri.path
+    rescue URI::InvalidURIError
+      raise ArgumentError, "Invalid redirect URI"
+    end
+
+    # Listens on the configured loopback URI until a callback completes.
+    #
+    # Open the authorization URL yourself while this call blocks. The callback block
+    # runs in the calling thread. Unrelated/malformed requests keep the listener alive.
+    # The listener closes after success, an OAuth error, a block exception, or interruption.
+    #
+    # @param timeout [Numeric] positive maximum wait for incoming connections, in seconds; defaults to 300
+    # @param block [Proc] callback handler required to finish token exchange
+    #
+    # @yield [params] callback handler; any exception is propagated after socket cleanup
+    # @yieldparam params [Hash{Symbol => String}] `:code`, `:state`, and `:iss` from the query string
+    # @yieldreturn [Object] arbitrary result returned from `start`, including `nil` or `false`
+    # @return [Object] callback block result
+    #
+    # @raise [ArgumentError] if metadata/timeout is invalid or no block is supplied
+    # @raise [CallbackError] if the callback contains an OAuth `error` parameter
+    # @raise [Timeout::Error] if waiting for an incoming connection exceeds the deadline
+    # @raise [SystemCallError, IOError] if binding or accepting a connection fails
+    # @raise [Interrupt] when interrupted, for example with Ctrl-C
+    #
+    def start(timeout: 300, &block)
+      raise ArgumentError, "A callback block is required" unless block_given?
+      raise ArgumentError, "timeout must be positive" unless timeout.is_a?(Numeric) && timeout.positive?
+
+      server = TCPServer.new(@uri.hostname, @uri.port)
+
+      begin
+        puts "Waiting for OAuth callback at #{@uri} (Ctrl-C to cancel)"
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          unless remaining.positive? && IO.select([server], nil, nil, remaining)
+            raise Timeout::Error, "Timed out waiting for the OAuth callback"
+          end
+
+          socket = server.accept
+          success, result = handle_connection(socket, &block)
+
+          return result if success
+        end
+      ensure
+        server.close
+      end
+    end
+
+
+    private
+
+    def loopback_host?(host)
+      if host&.downcase == "localhost"
+        true
+      elsif host
+        ip = IPAddr.new(host)
+        LOOPBACK_RANGES.any? { |range| range.include?(ip) }
+      else
+        false
+      end
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+
+    def handle_connection(socket, &block)
+      params = handle_request(socket)
+      return [false, nil] unless params
+
+      begin
+        if params['error']
+          raise CallbackError.new(params['error'], params['error_description'])
+        end
+
+        callback_params = params.slice('code', 'state', 'iss').transform_keys(&:to_sym)
+        result = yield callback_params
+      rescue StandardError => e
+        respond(socket, 400, "Bad Request", "Authentication failed: #{e.inspect}")
+        raise
+      end
+
+      respond(socket, 200, "OK", "Authentication complete - you can close this tab.")
+      [true, result]
+    ensure
+      socket.close
+    end
+
+    def handle_request(socket)
+      method, target = read_request(socket)
+
+      if method != 'GET'
+        respond(socket, 405, "Method Not Allowed", "Use GET for the OAuth callback.")
+        return
+      end
+
+      request_uri = URI(target)
+
+      unless target.start_with?('/') && !request_uri.host && !request_uri.fragment && request_uri.path == @path
+        respond(socket, 404, "Not Found", "Waiting for the OAuth callback.")
+        return
+      end
+
+      extract_callback_params(request_uri)
+    rescue InvalidRequest, URI::InvalidURIError, ArgumentError
+      respond(socket, 400, "Bad Request", "Invalid callback request.")
+      nil
+    rescue Timeout::Error
+      respond(socket, 408, "Request Timeout", "Request timed out.")
+      nil
+    rescue IOError, SystemCallError
+      nil
+    end
+
+    def read_request(socket)
+      Timeout.timeout(REQUEST_TIMEOUT) do
+        bytes = 0
+        lines = []
+
+        loop do
+          line = socket.gets("\n", MAX_HEADER_BYTES + 1)
+          raise InvalidRequest unless line
+
+          bytes += line.bytesize
+          raise InvalidRequest if bytes > MAX_HEADER_BYTES
+          break if line == "\r\n" || line == "\n"
+
+          lines << line
+        end
+
+        match = /\A([A-Z]+) (\S+) HTTP\/1\.[01]\r?\n\z/.match(lines.first.to_s)
+        raise InvalidRequest unless match
+
+        [match[1], match[2]]
+      end
+    end
+
+    def extract_callback_params(uri)
+      pairs = URI.decode_www_form(uri.query.to_s)
+      raise InvalidRequest unless pairs.map(&:first).uniq.length == pairs.length
+
+      params = pairs.to_h
+
+      unless params['error'] || %w[code state iss].all? { |key| params[key] && !params[key].empty? }
+        raise InvalidRequest
+      end
+
+      params
+    end
+
+    def respond(socket, status, reason, body)
+      socket.write("HTTP/1.1 #{status} #{reason}\r\n" +
+                   "Content-Type: text/plain; charset=utf-8\r\n" +
+                   "Content-Length: #{body.bytesize}\r\n" +
+                   "Cache-Control: no-store\r\n" +
+                   "Connection: close\r\n\r\n#{body}\n")
+    rescue IOError, SystemCallError
+      # A closed browser tab must not discard successful tokens or mask an error.
+    end
+  end
+end

data/lib/authproto/minisky.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'minisky'
+require 'net/http'
+require 'uri'
+
+require_relative 'client'
+
+#
+# Experimental Minisky client backed by an AuthProto session.
+# Requiring authproto alone does not load Minisky or this integration.
+#
+
+class Minisky::OAuthClient
+  include Minisky::Requests
+
+  # Maximum authenticated XRPC retries after nonce challenges.
+  # @return [Integer]
+  MAX_NONCE_RETRIES = 2
+
+  # PDS host or base URL used by Minisky.
+  # @return [String]
+  attr_reader :host
+
+  # OAuth client that owns the session, tokens and DPoP key.
+  # @return [AuthProto::Client]
+  attr_reader :oauth_client
+
+  # Most recent authorization/callback session ID; `nil` before authorization.
+  # @return [String, nil]
+  attr_reader :session_id
+
+  # Creates an experimental Minisky client backed by an OAuth session.
+  #
+  # Disables Minisky's app-password token management and enables authenticated
+  # requests by default. Configure AuthProto's global storage/transport separately.
+  #
+  # @param host [String] PDS host or base URL used for XRPC requests
+  # @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 dpop_key [Hash{String => Object}, nil] existing private DPoP JWK, or `nil` to generate one
+  #
+  # @raise [AuthProto::InvalidClientMetadata] if metadata is invalid or unavailable
+  # @raise [AuthProto::Error] if OAuth client or DPoP initialization fails
+  # @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)
+    @host = host
+    @session_id = session_id
+
+    @send_auth_headers = true
+    @auto_manage_tokens = false
+
+    @oauth_client = AuthProto::Client.new(
+      client_id: client_id,
+      redirect_uri: redirect_uri,
+      metadata: metadata,
+      dpop_key: dpop_key
+    )
+  end
+
+  # Returns no app-password credential configuration; OAuth owns this client's tokens.
+  # @return [nil]
+  def config
+    nil
+  end
+
+  # Starts OAuth authorization and remembers the pending session ID.
+  #
+  # @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
+  #
+  # @return [Hash{Symbol => String}] `:url` to open and pending `:session_id`
+  # @raise [AuthProto::Error] if authorization, discovery, PAR or persistence fails
+  # @see AuthProto::Client#authorize
+  #
+  def authorize(**options)
+    oauth_client.authorize(**options).tap { |result| @session_id = result.fetch(:session_id) }
+  end
+
+  # Completes OAuth authorization and remembers the authenticated session ID.
+  #
+  # @param options [Hash{Symbol => String}] callback parameters forwarded to {AuthProto::Client#handle_callback}
+  # @option options [String] :code authorization code
+  # @option options [String] :state callback state token
+  # @option options [String] :iss authorization server issuer
+  #
+  # @return [Hash{Symbol => String, Integer, nil}] token and session details from the OAuth client
+  # @raise [AuthProto::Client::CallbackError] if state or issuer validation fails
+  # @raise [AuthProto::Client::TokenError] if token exchange or validation fails
+  # @raise [AuthProto::Error] if proofs, storage or serialization fail
+  # @see AuthProto::Client#handle_callback
+  #
+  def handle_callback(**options)
+    oauth_client.handle_callback(**options).tap { |result| @session_id = result.fetch(:session_id) }
+  end
+
+  # Sends an XRPC GET through Minisky, adding OAuth handling when authenticated.
+  #
+  # Authenticated requests check token expiry, generate a fresh DPoP proof for each
+  # attempt, retry at most {MAX_NONCE_RETRIES} nonce challenges, and refresh once on
+  # an `invalid_token` response. `auth: false` delegates to Minisky without OAuth.
+  #
+  # @param method [String, URI::HTTP] XRPC NSID or URL accepted by Minisky
+  # @param params [Hash, nil] query parameters encoded using `URI.encode_www_form`
+  # @param auth [Boolean] whether to authenticate; defaults to Minisky's auth mode
+  # @param headers [Hash{String => String}, nil] custom headers; OAuth authorization/proof headers are replaced
+  #
+  # @return [Hash, Array, String, Numeric, Boolean, nil] parsed JSON or raw response body returned by Minisky
+  # @raise [ArgumentError] if the method is invalid or `auth` is a truthy non-Boolean value
+  # @raise [Minisky::AuthError] if no completed OAuth login or refresh capability is available
+  # @raise [Minisky::BadResponse] if the final response has an error or redirect status
+  # @raise [AuthProto::DPoP::Client::Error] if proof handling fails or a nonce challenge lacks its nonce
+  # @raise [AuthProto::Error] if OAuth refresh or token persistence fails
+  # @raise [JSON::ParserError] if a JSON response cannot be parsed
+  # @raise [Net::OpenTimeout, Net::ReadTimeout, IOError, SystemCallError] if HTTP transport fails
+  #
+  def get_request(method, params = nil, auth: default_auth_mode, headers: nil)
+    return super unless auth
+
+    raise ArgumentError, "OAuth requests accept auth: true or false, not a bearer token" unless auth == true
+
+    url = build_request_uri(method).dup
+    url.query = URI.encode_www_form(params) if params && !params.empty?
+
+    response = oauth_request(Net::HTTP::Get, url, headers || {})
+    handle_response(response)
+  end
+
+  # Sends an XRPC POST through Minisky, adding OAuth handling when authenticated.
+  #
+  # Authenticated requests check token expiry, generate a fresh DPoP proof for each
+  # attempt, retry at most {MAX_NONCE_RETRIES} nonce challenges, and refresh once on
+  # an `invalid_token` response. `auth: false` delegates to Minisky without OAuth.
+  # Non-string data is JSON-encoded, adding `Content-Type: application/json` unless
+  # a content type was supplied. Strings are transmitted unchanged.
+  #
+  # @param method [String, URI::HTTP] XRPC NSID or URL accepted by Minisky
+  # @param data [String, #to_json, nil] raw body bytes, JSON-encodable data, or no body
+  # @param params [Hash, nil] query parameters encoded using `URI.encode_www_form`
+  # @param auth [Boolean] whether to authenticate; defaults to Minisky's auth mode
+  # @param headers [Hash{String => String}, nil] custom headers; OAuth authorization/proof headers are replaced
+  #
+  # @return [Hash, Array, String, Numeric, Boolean, nil] parsed JSON or raw response body returned by Minisky
+  # @raise [ArgumentError] if the method is invalid or `auth` is a truthy non-Boolean value
+  # @raise [Minisky::AuthError] if no completed OAuth login or refresh capability is available
+  # @raise [Minisky::BadResponse] if the final response has an error or redirect status
+  # @raise [AuthProto::DPoP::Client::Error] if proof handling fails or a nonce challenge lacks its nonce
+  # @raise [AuthProto::Error] if OAuth refresh or token persistence fails
+  # @raise [JSON::ParserError] if a JSON response cannot be parsed
+  # @raise [Net::OpenTimeout, Net::ReadTimeout, IOError, SystemCallError] if HTTP transport fails
+  #
+  def post_request(method, data = nil, auth: default_auth_mode, headers: nil, params: nil)
+    return super unless auth
+
+    raise ArgumentError, "OAuth requests accept auth: true or false, not a bearer token" unless auth == true
+
+    url = build_request_uri(method).dup
+    url.query = URI.encode_www_form(params) if params && !params.empty?
+    headers = (headers || {}).dup
+
+    body = if data.is_a?(String) || data.nil?
+             data.to_s
+           else
+             unless headers.keys.any? { |key| key.to_s.downcase == "content-type" }
+               headers["Content-Type"] = "application/json"
+             end
+             data.to_json
+           end
+
+    response = oauth_request(Net::HTTP::Post, url, headers, body: body)
+    handle_response(response)
+  end
+
+  # Rejects Minisky's app-password login entry point.
+  #
+  # Accepts and ignores any arguments. Use {#authorize} and {#handle_callback} for OAuth login.
+  #
+  # @return [void]
+  # @raise [NotImplementedError] always
+  #
+  def log_in(*)
+    raise NotImplementedError, "Use authorize and handle_callback for OAuth login"
+  end
+
+  # Refreshes and persists tokens for the current session via the OAuth client.
+  #
+  # @return [Hash{Symbol => String, Integer, nil}] replacement tokens and session ID
+  # @raise [AuthProto::Client::TokenError] if the session cannot be refreshed
+  # @raise [AuthProto::Token::RefreshError] if refresh fails
+  # @raise [AuthProto::Storage::StorageError] if token persistence fails
+  #
+  def perform_token_refresh
+    oauth_client.refresh_token(session_id)
+  end
+
+  # Checks the OAuth login and refreshes an expired access token if possible.
+  #
+  # @return [Symbol] `:ok` for a usable token, or `:refreshed` after successful refresh
+  # @raise [Minisky::AuthError] if login is incomplete or expired tokens cannot be refreshed
+  # @raise [AuthProto::Error] if token refresh, serialization or persistence fails
+  #
+  def check_access
+    session = oauth_client.session_manager.get_session(session_id) if session_id
+    raise Minisky::AuthError, "Complete OAuth login before making authenticated requests" unless session&.tokens
+
+    return :ok unless session.tokens.expired?
+
+    raise Minisky::AuthError, "OAuth session cannot be refreshed; log in again" unless session.renewable?
+
+    perform_token_refresh
+    :refreshed
+  end
+
+
+  private
+
+  def oauth_request(request_class, url, headers, body: nil)
+    check_access
+
+    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
+                             ))
+
+      request = request_class.new(url, request_headers)
+      request.body = body unless body.nil?
+      response = make_request(request)
+
+      nonce = response["DPoP-Nonce"]
+      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"
+        unless nonce && !nonce.empty?
+          raise AuthProto::DPoP::Client::Error, "DPoP nonce challenge (HTTP 401) is missing DPoP-Nonce"
+        end
+        return response if nonce_retries >= MAX_NONCE_RETRIES
+
+        nonce_retries += 1
+      elsif response.code.to_i == 401 && error == "invalid_token" && !refreshed
+        perform_token_refresh
+        refreshed = true
+      else
+        return response
+      end
+    end
+  end
+
+  def authentication_error(response)
+    # Only interpret a single DPoP challenge. Leave other auth schemes and
+    # ambiguous multi-challenge headers to Minisky's normal error handling.
+    challenge = response["WWW-Authenticate"].to_s
+    return unless challenge.match?(/\ADPoP\s/i)
+    return if challenge.match?(/,\s*(?:Bearer|Basic|DPoP)\b/i)
+
+    challenge[/\berror\s*=\s*"(use_dpop_nonce|invalid_token)"/i, 1]
+  end
+end