authproto 0.3.0.beta1

data/lib/authproto/state/session_manager.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require_relative '../configuration'
+require_relative '../serialization/session'
+require_relative '../storage/key_builder'
+require_relative 'session'
+
+module AuthProto
+  module State
+
+    #
+    # Manages active OAuth sessions with secure persistent storage
+    #
+
+    class SessionManager
+
+      # Creates a session manager and its encrypted session serializer.
+      # @raise [ArgumentError] if `ATPROTO_MASTER_KEY` is not valid Base64
+      #
+      def initialize
+        @serializer = Serialization::Session.new
+      end
+
+      # Creates and stores a session and its state-token lookup under a storage lock.
+      #
+      # @param client_id [String] OAuth client ID
+      # @param scope [String] requested space-separated scopes
+      # @param auth_server [ServerMetadata::AuthorizationServer, nil] pre-resolved authorization server
+      # @param did [String, nil] pre-resolved account DID
+      #
+      # @return [Session] newly created session
+      # @raise [PKCE::Error] if session PKCE generation fails
+      # @raise [Storage::StorageError] if writing or locking fails
+      # @raise [Serialization::ValidationError] if the session cannot be serialized
+      # @raise [Encryption::EncryptionError] if sensitive fields cannot be encrypted
+      #
+      def create_session(client_id:, scope:, auth_server: nil, did: nil)
+        session = Session.new(
+          client_id: client_id,
+          scope: scope,
+          auth_server: auth_server,
+          did: did
+        )
+
+        # Store both session and state mapping atomically
+        session_key = Storage::KeyBuilder.session_key(session.session_id)
+        state_key = Storage::KeyBuilder.state_key(session.state_token)
+
+        AuthProto.storage.with_lock(session_key, ttl: 30) do
+          serialized = @serializer.serialize(session)
+          AuthProto.storage.set(session_key, serialized)
+          AuthProto.storage.set(state_key, session.session_id)
+        end
+
+        session
+      end
+
+      # Persists a session and updates its state-token lookup under a storage lock.
+      #
+      # @param session [Session] session to persist
+      # @return [Session] the supplied session
+      # @raise [Storage::StorageError] if writing or locking fails
+      # @raise [Serialization::ValidationError] if the session cannot be serialized
+      # @raise [Encryption::EncryptionError] if sensitive fields cannot be encrypted
+      #
+      def update_session(session)
+        session_key = Storage::KeyBuilder.session_key(session.session_id)
+
+        AuthProto.storage.with_lock(session_key, ttl: 30) do
+          serialized = @serializer.serialize(session)
+          AuthProto.storage.set(session_key, serialized)
+
+          state_key = Storage::KeyBuilder.state_key(session.state_token)
+          AuthProto.storage.set(state_key, session.session_id)
+        end
+
+        session
+      end
+
+      # Loads and decrypts a session by ID.
+      #
+      # Returns `nil` for missing, unreadable or malformed sessions and for expired
+      # sessions that have no refresh token. Read/deserialization errors are logged.
+      #
+      # @param session_id [String] session identifier
+      # @return [Session, nil] restored session, or `nil` if unavailable
+      #
+      def get_session(session_id)
+        session_key = Storage::KeyBuilder.session_key(session_id)
+
+        begin
+          serialized = AuthProto.storage.get(session_key)
+          return nil unless serialized
+        rescue StandardError => e
+          AuthProto.configuration.logger.error("Failed to get session: #{e.message}")
+          return nil
+        end
+
+        begin
+          session = @serializer.deserialize(serialized)
+          return nil if !session.renewable? && session.tokens&.expired?
+
+          session
+        rescue StandardError => e
+          AuthProto.configuration.logger.error("Failed to deserialize session: #{e.message}")
+          nil
+        end
+      end
+
+      # Finds a stored session using its OAuth callback state token.
+      #
+      # Storage read errors are logged and treated as a missing session.
+      #
+      # @param state [String, nil] callback state token
+      # @return [Session, nil] restored session, or `nil` if unavailable
+      #
+      def get_session_by_state(state)
+        return nil unless state
+
+        state_key = Storage::KeyBuilder.state_key(state)
+
+        begin
+          session_id = AuthProto.storage.get(state_key)
+          return nil unless session_id
+        rescue StandardError => e
+          AuthProto.configuration.logger.error("Failed to get session by state: #{e.message}")
+          return nil
+        end
+
+        get_session(session_id)
+      end
+
+      # Deletes a session and its state mapping if it can be retrieved.
+      #
+      # @param session_id [String] session identifier
+      # @return [void]
+      # @raise [Storage::StorageError] if deletion or locking fails
+      #
+      def remove_session(session_id)
+        session = get_session(session_id)
+        return unless session
+
+        session_key = Storage::KeyBuilder.session_key(session_id)
+        state_key = Storage::KeyBuilder.state_key(session.state_token)
+
+        AuthProto.storage.with_lock(session_key, ttl: 30) do
+          AuthProto.storage.delete(session_key)
+          AuthProto.storage.delete(state_key)
+        end
+      end
+
+      # Provides an expiry cleanup hook; currently performs no work.
+      # Expiry is handled through backend TTLs and retrieval validation.
+      #
+      # @return [void]
+      #
+      def cleanup_expired
+        # No-op - expiry handled by storage TTL and retrieval validation
+      end
+    end
+  end
+end

data/lib/authproto/state/token_set.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module AuthProto
+  module State
+
+    #
+    # Represents a set of OAuth tokens and their associated metadata
+    #
+
+    class TokenSet
+
+      # DPoP-bound access token.
+      # @return [String]
+      attr_reader :access_token
+
+      # Refresh token, if issued.
+      # @return [String, nil]
+      attr_reader :refresh_token
+
+      # Token scheme; always `DPoP`.
+      # @return [String]
+      attr_reader :token_type
+
+      # Space-separated granted scopes.
+      # @return [String]
+      attr_reader :scope
+
+      # Access token expiry time.
+      # @return [Time]
+      attr_reader :expires_at
+
+      # DID of the authenticated account.
+      # @return [String]
+      attr_reader :sub
+
+      # Creates a token set and calculates its expiry from the current time.
+      #
+      # @param access_token [String] nonempty DPoP-bound access token
+      # @param token_type [String] must be `DPoP`
+      # @param expires_in [Integer] lifetime in seconds; negative values represent expired tokens
+      # @param scope [String] nonempty space-separated granted scopes
+      # @param sub [String] nonempty account DID
+      # @param refresh_token [String, nil] refresh token, if issued
+      # @raise [ArgumentError] if required strings are missing, the token type is wrong, or expiry is not an integer
+      #
+      def initialize(
+        access_token:,
+        token_type:,
+        expires_in:,
+        scope:,
+        sub:,
+        refresh_token: nil
+      )
+        validate_token_type(token_type)
+        validate_required("access_token", access_token)
+        validate_required("scope", scope)
+        validate_required("sub", sub)
+        validate_expires_in(expires_in)
+
+        @access_token = access_token
+        @refresh_token = refresh_token
+        @token_type = token_type
+        @scope = scope
+        @sub = sub
+        @expires_at = Time.now + expires_in
+      end
+
+      # Whether this token set includes a refresh token
+      # @return [Boolean]
+      def renewable?
+        !@refresh_token.nil? && !@refresh_token.empty?
+      end
+
+      # Checks expiry, treating tokens close to expiry as already expired.
+      #
+      # @param buffer [Numeric] seconds before actual expiry to consider the token expired
+      # @return [Boolean] whether the token has expired or is within the buffer
+      #
+      def expired?(buffer = 30)
+        Time.now >= (@expires_at - buffer)
+      end
+
+
+      private
+
+      def validate_token_type(type)
+        raise ArgumentError, "token_type must be DPoP" unless type == "DPoP"
+      end
+
+      def validate_required(name, value)
+        raise ArgumentError, "#{name} is required" if value.nil? || value.empty?
+      end
+
+      def validate_expires_in(expires_in)
+        return if expires_in.is_a?(Integer)
+
+        raise ArgumentError, "expires_in must be an integer"
+      end
+    end
+  end
+end

data/lib/authproto/state.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
+module AuthProto
+
+  #
+  # 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 = AuthProto::State::SessionManager.new
+  #
+  #   # Create a new session
+  #   session = manager.create_session(
+  #     client_id: "https://myapp.com/oauth-client-metadata.json",
+  #     scope: "atproto"
+  #   )
+  #
+  #   # Update session with tokens
+  #   tokens = AuthProto::State::TokenSet.new(
+  #     access_token: "...",
+  #     token_type: "DPoP",
+  #     expires_in: 3600,
+  #     scope: "atproto",
+  #     sub: "did:plc:abcdef123"
+  #   )
+  #   session.tokens = tokens
+  #   manager.update_session(session)
+  #
+  #   # Lookup session later
+  #   session = manager.get_session(session.session_id)
+  #   if session.authorized?
+  #     puts "Access token: #{session.tokens.access_token}"
+  #   end
+  #
+  # Session mutation is synchronized, and the session manager uses backend locks
+  # when persisting changes. TokenSet values themselves are read-only.
+  #
+
+  module State
+
+    # Error raised for session-related issues
+    class SessionError < AuthProto::Error; end
+  end
+end

data/lib/authproto/storage/interface.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module AuthProto
+
+  #
+  # Storage contracts and optional memory, Redis and SQLite adapters for OAuth state.
+  #
+
+  module Storage
+
+    autoload :Memory, File.expand_path('memory', __dir__)
+    autoload :Redis, File.expand_path('redis', __dir__)
+    autoload :SQLite, File.expand_path('sqlite', __dir__)
+
+    # Base error class for storage operations
+    class StorageError < AuthProto::Error; end
+
+    # Error for lock-related operations
+    class LockError < StorageError; end
+
+    #
+    # Base storage interface that all implementations must conform to
+    #
+
+    class Interface
+
+      # Stores a value, optionally with an expiry.
+      # Implementations must validate keys and TTLs. Accepted value types depend on the backend.
+      #
+      # @param key [String] nonempty key beginning with `atproto:`
+      # @param value [Object] backend-compatible value to store
+      # @param ttl [Integer, nil] positive lifetime in seconds, or `nil` for no expiry
+      # @return [Boolean] whether the write succeeded
+      # @raise [StorageError] if validation or storage fails
+      # @raise [NotImplementedError] unless overridden by a storage adapter
+      #
+      def set(key, value, ttl: nil)
+        raise NotImplementedError
+      end
+
+      # Reads an unexpired value.
+      #
+      # @param key [String] nonempty key beginning with `atproto:`
+      # @return [Object, nil] stored value, or `nil` if missing/expired
+      # @raise [StorageError] if validation or storage fails
+      # @raise [NotImplementedError] unless overridden by a storage adapter
+      #
+      def get(key)
+        raise NotImplementedError
+      end
+
+      # Deletes a stored value.
+      #
+      # @param key [String] nonempty key beginning with `atproto:`
+      # @return [Boolean] backend deletion status; see adapter-specific semantics
+      # @raise [StorageError] if validation or storage fails
+      # @raise [NotImplementedError] unless overridden by a storage adapter
+      #
+      def delete(key)
+        raise NotImplementedError
+      end
+
+      # Checks whether an unexpired key exists.
+      #
+      # @param key [String] nonempty key beginning with `atproto:`
+      # @return [Boolean] whether the key exists
+      # @raise [StorageError] if validation or storage fails
+      # @raise [NotImplementedError] unless overridden by a storage adapter
+      #
+      def exists?(key)
+        raise NotImplementedError
+      end
+
+      # Runs a block while holding a lock that expires after the requested TTL.
+      #
+      # A lock is not renewed automatically; choose a TTL longer than the protected work.
+      #
+      # @param key [String] nonempty lock key beginning with `atproto:`
+      # @param ttl [Integer] positive lock lifetime in seconds
+      # @yield block to run after acquiring the lock
+      # @yieldreturn [Object] result to return to the caller
+      # @return [Object] block result
+      # @raise [LockError] if the lock cannot be acquired
+      # @raise [StorageError] if validation or backend operations fail
+      # @raise [ArgumentError] if no block is supplied
+      # @raise [NotImplementedError] unless overridden by a storage adapter
+      #
+      def with_lock(key, ttl: 30)
+        raise NotImplementedError
+      end
+
+      protected
+
+      # Validates that a storage key is nonempty and begins with `atproto:`.
+      #
+      # @param key [String] value to validate
+      # @return [void]
+      # @raise [StorageError] if the value is invalid
+      #
+      def validate_key(key)
+        raise StorageError, "Key cannot be nil" if key.nil?
+        raise StorageError, "Key must be a string" unless key.is_a?(String)
+        raise StorageError, "Key cannot be empty" if key.empty?
+        raise StorageError, "Invalid key format" unless key.start_with?("atproto:")
+      end
+
+      # Validates that a TTL is `nil` or a positive integer.
+      #
+      # @param ttl [Integer, nil] value to validate
+      # @return [void]
+      # @raise [StorageError] if the value is invalid
+      #
+      def validate_ttl(ttl)
+        return if ttl.nil?
+        raise StorageError, "TTL must be a positive integer" unless ttl.is_a?(Integer) && ttl.positive?
+      end
+    end
+  end
+end

data/lib/authproto/storage/key_builder.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module AuthProto
+  module Storage
+
+    #
+    # Utility for building storage keys with correct format
+    #
+
+    class KeyBuilder
+
+      # Separator between storage key components.
+      # @return [String]
+      NAMESPACE_SEPARATOR = ":"
+
+      # Root namespace for every generated storage key.
+      # @return [String]
+      NAMESPACE_PREFIX = "atproto"
+
+      class << self
+
+        # Builds a namespaced storage key for a session.
+        #
+        # @param id [String] session ID
+        # @return [String] colon-separated key beginning with `atproto:`
+        #
+        def session_key(id)
+          build_key("session", id)
+        end
+
+        # Builds a namespaced storage key for a state-token lookup.
+        #
+        # @param token [String] OAuth state token
+        # @return [String] colon-separated key beginning with `atproto:`
+        #
+        def state_key(token)
+          build_key("state", token)
+        end
+
+        # Builds a namespaced storage key for a DPoP nonce.
+        #
+        # @param server_url [String] server origin URL
+        # @return [String] colon-separated key beginning with `atproto:`
+        #
+        def nonce_key(server_url)
+          build_key("nonce", server_url)
+        end
+
+        # Builds a namespaced storage key for a DPoP key.
+        #
+        # @param client_id [String] OAuth client ID
+        # @return [String] colon-separated key beginning with `atproto:`
+        #
+        def dpop_key(client_id)
+          build_key("dpop", client_id)
+        end
+
+        # Builds a namespaced storage key for a lock.
+        #
+        # @param namespace [String] lock namespace, such as `session`
+        # @param id [String] resource identifier
+        # @return [String] colon-separated key beginning with `atproto:`
+        #
+        def lock_key(namespace, id)
+          build_key("lock", namespace, id)
+        end
+
+        private
+
+        def build_key(*parts)
+          [NAMESPACE_PREFIX, *parts].join(NAMESPACE_SEPARATOR)
+        end
+      end
+    end
+  end
+end