atproto_auth 0.0.1

data/lib/atproto_auth/state.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  # Manages OAuth state for AT Protocol authorization flows. This module provides thread-safe
+  # storage and management of authorization session data, including tokens, PKCE values,
+  # and identity information.
+  #
+  # The module consists of three main components:
+  #
+  # 1. {TokenSet} - Represents OAuth tokens (access and refresh) with their metadata,
+  #    including expiration times, scope, and the authenticated user's DID.
+  #
+  # 2. {Session} - Tracks the complete state of an authorization flow, including:
+  #    - PKCE verifier/challenge pairs
+  #    - State tokens for request verification
+  #    - Authorization server information
+  #    - Current tokens and user identity (DID)
+  #
+  # 3. {SessionManager} - Provides thread-safe storage and retrieval of active sessions,
+  #    with support for lookup by session ID or state token.
+  #
+  # @example Creating and managing a session
+  #   manager = AtprotoAuth::State::SessionManager.new
+  #
+  #   # Create a new session
+  #   session = manager.create_session(
+  #     client_id: "https://myapp.com/client-metadata.json",
+  #     scope: "atproto"
+  #   )
+  #
+  #   # Update session with tokens
+  #   tokens = TokenSet.new(
+  #     access_token: "...",
+  #     token_type: "DPoP",
+  #     expires_in: 3600,
+  #     scope: "atproto",
+  #     sub: "did:plc:abcdef123"
+  #   )
+  #   session.tokens = tokens
+  #
+  #   # Lookup session later
+  #   session = manager.get_session(session_id)
+  #   if session.authorized?
+  #     puts "Access token: #{session.tokens.access_token}"
+  #   end
+  #
+  # All classes in this module are thread-safe and can be used in concurrent environments.
+  # The module handles secure generation and validation of state tokens, and ensures
+  # consistency of session data through synchronized access.
+  module State
+    # Error raised for session-related issues
+    class SessionError < AtprotoAuth::Error; end
+  end
+end

data/lib/atproto_auth/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AtprotoAuth
+  VERSION = "0.0.1"
+end

data/lib/atproto_auth.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "jose"
+require "jwt"
+
+require "atproto_auth/version"
+
+require "atproto_auth/configuration"
+require "atproto_auth/errors"
+require "atproto_auth/client_metadata"
+require "atproto_auth/http_client"
+require "atproto_auth/pkce"
+
+require "atproto_auth/server_metadata"
+require "atproto_auth/server_metadata/origin_url"
+require "atproto_auth/server_metadata/authorization_server"
+require "atproto_auth/server_metadata/resource_server"
+
+require "atproto_auth/dpop/key_manager"
+require "atproto_auth/dpop/proof_generator"
+require "atproto_auth/dpop/nonce_manager"
+require "atproto_auth/dpop/client"
+
+require "atproto_auth/state"
+require "atproto_auth/state/token_set"
+require "atproto_auth/state/session"
+require "atproto_auth/state/session_manager"
+
+require "atproto_auth/identity"
+require "atproto_auth/identity/document"
+require "atproto_auth/identity/resolver"
+
+require "atproto_auth/par"
+require "atproto_auth/par/client_assertion"
+require "atproto_auth/par/request"
+require "atproto_auth/par/response"
+require "atproto_auth/par/client"
+
+require "atproto_auth/client"
+
+# AtprotoAuth is a Ruby library implementing the AT Protocol OAuth specification.
+# It provides functionality for both client and server-side implementations of
+# the AT Protocol OAuth flow, including support for DPoP, PAR, and dynamic client registration.
+module AtprotoAuth
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/sig/atproto_auth/client_metadata.rbs

@@ -0,0 +1,95 @@
+module AtprotoAuth
+  # Handles and validates AT Protocol OAuth client metadata.
+  class ClientMetadata
+    @client_id: String
+
+    @grant_types: Array[String]
+
+    @response_types: Array[String]
+
+    @redirect_uris: Array[String]
+
+    @scope: String
+
+    @client_name: String?
+
+    @application_type: String
+
+    @client_uri: String?
+
+    @logo_uri: String?
+
+    @tos_uri: String?
+
+    @policy_uri: String?
+
+    @token_endpoint_auth_method: String?
+
+    @jwks: Hash[String, untyped]?
+
+    @jwks_uri: String?
+
+    attr_reader client_id: String
+    attr_reader grant_types: Array[String]
+    attr_reader response_types: Array[String]
+    attr_reader redirect_uris: Array[String]
+    attr_reader scope: String
+    attr_reader client_name: String?
+    attr_reader client_uri: String?
+    attr_reader logo_uri: String?
+    attr_reader tos_uri: String?
+    attr_reader policy_uri: String?
+    attr_reader token_endpoint_auth_method: String?
+    attr_reader jwks: Hash[String, untyped]?
+    attr_reader jwks_uri: String?
+    attr_reader application_type: String
+
+    def initialize: (Hash[String, untyped] metadata) -> void
+
+    def self.from_url: (String url) -> ClientMetadata
+
+    def confidential?: () -> bool
+
+    private
+
+    def validate_and_set_metadata!: (Hash[String, untyped] metadata) -> void
+
+    def validate_client_id!: (String client_id) -> String
+
+    def validate_grant_types!: (Array[String] grant_types) -> Array[String]
+
+    def validate_response_types!: (Array[String] response_types) -> Array[String]
+
+    def validate_redirect_uris!: (Array[String] uris) -> Array[String]
+
+    def validate_redirect_uri!: (URI uri) -> void
+
+    def validate_redirect_uri_origin!: (URI uri) -> void
+
+    def validate_native_redirect_uri!: (URI uri) -> void
+
+    def validate_custom_scheme!: (URI uri) -> void
+
+    def validate_scope!: (String scope) -> String
+
+    def validate_offline_access_scope!: (Array[String] scope_values) -> void
+
+    def validate_application_type: (String? type) -> String
+
+    def validate_client_uri: (String? uri) -> String?
+
+    def validate_https_uri: (String? uri) -> String?
+
+    def validate_auth_methods!: (Hash[String, untyped] metadata) -> void
+
+    def validate_dpop!: (Hash[String, untyped] metadata) -> void
+
+    def self.validate_url!: (String url) -> void
+
+    def self.fetch_metadata: (String url) -> Hash[Symbol, untyped]
+
+    def self.parse_metadata: (String body) -> Hash[String, untyped]
+
+    def self.validate_client_id!: (String metadata_client_id, String url) -> void
+  end
+end

data/sig/atproto_auth/dpop/client.rbs

@@ -0,0 +1,38 @@
+module AtprotoAuth
+  module DPoP
+    class Client
+      @key_manager: untyped
+
+      @nonce_manager: untyped
+
+      @proof_generator: untyped
+
+      class Error < AtprotoAuth::Error
+      end
+
+      attr_reader key_manager: untyped
+
+      attr_reader proof_generator: untyped
+
+      attr_reader nonce_manager: untyped
+
+      def initialize: (?key_manager: untyped?, ?nonce_ttl: untyped?) -> void
+
+      def generate_proof: (http_method: untyped, http_uri: untyped, ?access_token: untyped?) -> untyped
+
+      def process_response: (untyped response_headers, untyped server_url) -> untyped
+
+      def request_headers: (untyped proof) -> { "DPoP" => untyped }
+
+      def public_key: () -> untyped
+
+      def export_key: (?include_private: bool) -> untyped
+
+      private
+
+      def extract_nonce: (untyped headers) -> untyped
+
+      def origin_for_uri: (untyped uri) -> untyped
+    end
+  end
+end

data/sig/atproto_auth/dpop/key_manager.rbs

@@ -0,0 +1,33 @@
+module AtprotoAuth
+  module DPoP
+    class KeyManager
+      @keypair: JOSE::JWK
+
+      class KeyError < AtprotoAuth::Error
+      end
+
+      CURVE: String
+      ALGORITHM: String
+
+      attr_reader keypair: JOSE::JWK
+
+      def initialize: (?JOSE::JWK keypair) -> void
+
+      def generate_keypair: () -> JOSE::JWK
+
+      def public_jwk: () -> Hash[String, untyped]
+
+      def sign: (String data) -> String
+
+      def verify: (String signature, String data) -> bool
+
+      def to_jwk: (?include_private: bool) -> Hash[String, untyped]
+
+      def self.from_jwk: (Hash[String, untyped] jwk) -> AtprotoAuth::DPoP::KeyManager
+
+      private
+
+      def validate_keypair!: () -> void
+    end
+  end
+end

data/sig/atproto_auth/dpop/nonce_manager.rbs

@@ -0,0 +1,48 @@
+module AtprotoAuth
+  module DPoP
+    class NonceManager
+      @ttl: Integer
+      @nonces: Hash[String, AtprotoAuth::DPoP::NonceManager::StoredNonce]
+      @monitor: Monitor
+
+      class NonceError < AtprotoAuth::Error
+      end
+
+      class StoredNonce
+        @value: String
+        @server_url: String
+        @timestamp: Integer
+
+        attr_reader value: String
+        attr_reader timestamp: Integer
+        attr_reader server_url: String
+
+        def initialize: (String value, String server_url) -> void
+
+        def expired?: (?Integer ttl) -> bool
+      end
+
+      DEFAULT_TTL: Integer
+
+      def initialize: (?ttl: Integer) -> void
+
+      def update: (nonce: String, server_url: String) -> void
+
+      def get: (String server_url) -> (nil | String)
+
+      def clear: (String server_url) -> void
+
+      def clear_all: () -> void
+
+      def server_urls: () -> Array[String]
+
+      def valid_nonce?: (String server_url) -> bool
+
+      private
+
+      def validate_inputs!: (String nonce, String server_url) -> void
+
+      def validate_server_url!: (String server_url) -> void
+    end
+  end
+end

data/sig/atproto_auth/dpop/proof_generator.rbs

@@ -0,0 +1,42 @@
+module AtprotoAuth
+  module DPoP
+    class ProofGenerator
+      @key_manager: AtprotoAuth::DPoP::KeyManager
+
+      class ProofError < AtprotoAuth::Error
+      end
+
+      attr_reader key_manager: AtprotoAuth::DPoP::KeyManager
+
+      def initialize: (AtprotoAuth::DPoP::KeyManager key_manager) -> void
+
+      def generate: (
+          http_method: String,
+          http_uri: String,
+          ?nonce: String?,
+          ?access_token: String?,
+          ?ath: bool?
+        ) -> String
+
+      private
+
+      def validate_inputs!: (String http_method, String http_uri) -> void
+
+      def build_header: () -> { typ: "dpop+jwt", alg: "ES256", jwk: Hash[String, untyped] }
+
+      def build_payload: (
+          http_method: String,
+          http_uri: String,
+          nonce: String?,
+          access_token: String?,
+          include_ath: bool
+        ) -> Hash[Symbol, untyped]
+
+      def normalize_uri: (String uri) -> String
+
+      def generate_access_token_hash: (String access_token) -> String
+
+      def encode_jwt_segments: (Hash[Symbol, untyped] header, Hash[Symbol, untyped] payload) -> String
+    end
+  end
+end

data/sig/atproto_auth/http_client.rbs

@@ -0,0 +1,58 @@
+module AtprotoAuth
+  class HttpClient
+    @timeout: Integer
+
+    @verify_ssl: bool
+
+    FORBIDDEN_IP_RANGES: ::Array[IPAddr]
+
+    ALLOWED_SCHEMES: ::Array[String]
+
+    DEFAULT_TIMEOUT: Integer
+
+    MAX_REDIRECTS: Integer
+
+    MAX_RESPONSE_SIZE: Integer
+
+    class SSRFError < Error
+    end
+
+    class HttpError < Error
+      @response: ::Net::HTTPResponse?
+
+      attr_reader response: ::Net::HTTPResponse?
+
+      def initialize: (String message, ::Net::HTTPResponse? response) -> void
+    end
+
+    def initialize: (?timeout: Integer, ?verify_ssl: bool) -> void
+
+    def get: (String url, ?::Hash[String, String] headers) -> { status: Integer, headers: ::Hash[String, String], body: String }
+
+    private
+
+    def validate_uri!: (String url) -> URI
+
+    def validate_ip!: (URI uri) -> nil
+
+    def resolve_ip: (String hostname) -> IPAddr
+
+    def forbidden_ip?: (IPAddr ip) -> bool
+
+    def make_request: (URI uri, ?::Hash[String, String] headers) -> ::Net::HTTPResponse
+
+    def configure_http_client!: (::Net::HTTP http) -> void
+
+    def add_security_headers!: (::Net::HTTP::Get request, ::Hash[String, String] headers) -> void
+
+    def handle_redirect: (URI original_uri, ::Net::HTTPResponse response, ::Hash[String, String] headers, ?::Integer redirect_count) -> ::Net::HTTPResponse
+
+    def validate_response!: (::Net::HTTPResponse response) -> void
+
+    def check_success_status!: (::Net::HTTPResponse response) -> nil
+
+    def check_content_length!: (::Net::HTTPResponse response) -> nil
+
+    def check_content_type!: (::Net::HTTPResponse response) -> nil
+  end
+end

data/sig/atproto_auth/identity/document.rbs

@@ -0,0 +1,31 @@
+module AtprotoAuth
+  module Identity
+    class Document
+      @did: String
+      @rotation_keys: Array[String]
+      @also_known_as: Array[String]
+      @services: Array[Hash[String, untyped]]
+      @pds: String
+
+      attr_reader did: String
+      attr_reader rotation_keys: Array[String]
+      attr_reader also_known_as: Array[String]
+      attr_reader services: Array[Hash[String, untyped]]
+      attr_reader pds: String
+
+      def initialize: (Hash[String, untyped] data) -> void
+
+      def has_handle?: (String handle) -> bool
+
+      private
+
+      def validate_document!: (Hash[String, untyped] data) -> void
+
+      def validate_did!: (String did) -> void
+
+      def validate_services!: (Array[Hash[String, untyped]]? services) -> void
+
+      def extract_pds!: (Hash[String, untyped] data) -> String
+    end
+  end
+end

data/sig/atproto_auth/identity/resolver.rbs

@@ -0,0 +1,41 @@
+module AtprotoAuth
+  module Identity
+    class Resolver
+      @plc_directory: String
+
+      PLC_DIRECTORY_URL: String
+      DID_PLC_PREFIX: String
+      HANDLE_REGEX: ::Regexp
+
+      def initialize: (?plc_directory: String?) -> void
+
+      def resolve_handle: (String handle) -> Hash[Symbol, untyped]
+
+      def get_did_info: (String did) -> Hash[Symbol, untyped]
+
+      def verify_pds_binding: (String did, String pds_url) -> bool
+
+      def verify_issuer_binding: (String did, String issuer) -> bool
+
+      def verify_handle_binding: (String handle, String did) -> bool
+
+      private
+
+      def validate_handle!: (String handle) -> void
+
+      def validate_did!: (String did) -> void
+
+      def normalize_handle: (String handle) -> String
+
+      def resolve_handle_dns: (String _handle) -> nil
+
+      def resolve_handle_http: (String handle) -> Hash[Symbol, untyped]
+
+      def fetch_did_document: (String did) -> Hash[String, untyped]
+
+      def validate_pds_url!: (String url) -> void
+
+      def normalize_url: (String url) -> String
+    end
+  end
+end

data/sig/atproto_auth/par/client.rbs

@@ -0,0 +1,31 @@
+module AtprotoAuth
+  module PAR
+    class Client
+      @endpoint: String
+
+      attr_reader endpoint: String
+
+      def initialize: (endpoint: String) -> void
+
+      def submit: (Request request) -> Response
+
+      def authorization_url: (
+          authorize_endpoint: String,
+          request_uri: String,
+          client_id: String
+        ) -> String
+
+      private
+
+      def validate_endpoint!: () -> void
+
+      def build_headers: (Request request) -> Hash[String, String]
+
+      def make_request: (Request request, Hash[String, String] headers) -> Hash[Symbol, untyped]
+
+      def process_response: (Hash[Symbol, untyped] response) -> Response
+
+      def encode_params: (Hash[String, String]) -> String
+    end
+  end
+end

data/sig/atproto_auth/par/request.rbs

@@ -0,0 +1,73 @@
+module AtprotoAuth
+  module PAR
+    class Request
+      @response_type: String
+      @client_id: String
+      @redirect_uri: String
+      @code_challenge: String
+      @code_challenge_method: String
+      @state: String
+      @scope: String
+      @login_hint: String?
+      @nonce: String?
+      @dpop_proof: String?
+      @client_assertion_type: String?
+      @client_assertion: String?
+
+      class Configuration
+        attr_accessor client_id: String
+        attr_accessor redirect_uri: String
+        attr_accessor code_challenge: String
+        attr_accessor code_challenge_method: String
+        attr_accessor state: String
+        attr_accessor scope: String
+        attr_accessor login_hint: String?
+        attr_accessor nonce: String?
+        attr_accessor dpop_proof: String?
+        attr_accessor client_assertion_type: String?
+        attr_accessor client_assertion: String?
+      end
+
+      attr_reader response_type: String
+      attr_reader client_id: String
+      attr_reader code_challenge: String
+      attr_reader code_challenge_method: String
+      attr_reader state: String
+      attr_reader redirect_uri: String
+      attr_reader scope: String
+      attr_reader login_hint: String?
+      attr_reader nonce: String?
+      attr_reader dpop_proof: String?
+      attr_reader client_assertion_type: String?
+      attr_reader client_assertion: String?
+
+      def self.build: () { (Configuration) -> void } -> Request
+
+      def initialize: (Configuration config) -> void
+
+      def to_form: () -> String
+
+      private
+
+      def build_params: () -> Hash[String, String]
+
+      def add_optional_params: (Hash[String, String] params) -> void
+
+      def add_client_auth_params: (Hash[String, String] params) -> void
+
+      def validate!: () -> void
+
+      def validate_required_params!: () -> void
+
+      def validate_response_type!: () -> void
+
+      def validate_code_challenge_method!: () -> void
+
+      def validate_scope!: () -> void
+
+      def validate_client_auth!: () -> void
+
+      def encode_params: (Hash[String, String]) -> String
+    end
+  end
+end

data/sig/atproto_auth/par/response.rbs

@@ -0,0 +1,17 @@
+module AtprotoAuth
+  module PAR
+    class Response
+      @request_uri: String
+      @expires_in: Integer
+
+      attr_reader request_uri: String
+      attr_reader expires_in: Integer
+
+      def initialize: (request_uri: String, expires_in: Integer) -> void
+
+      private
+
+      def validate!: () -> void
+    end
+  end
+end

data/sig/atproto_auth/pkce.rbs

@@ -0,0 +1,24 @@
+module AtprotoAuth
+  module PKCE
+    class Error < AtprotoAuth::Error
+    end
+
+    MIN_VERIFIER_LENGTH: Integer
+    MAX_VERIFIER_LENGTH: Integer
+    ALLOWED_VERIFIER_CHARS: ::Regexp
+
+    def self.generate_verifier: (?Integer length) -> String
+
+    def self.generate_challenge: (String verifier) -> String
+
+    def self.verify: (String challenge, String verifier) -> bool
+
+    private
+
+    def self.validate_verifier_length!: (Integer length) -> void
+
+    def self.validate_verifier!: (String verifier) -> void
+
+    def self.secure_compare: (String str1, String str2) -> bool
+  end
+end