lex-identity 0.3.0 → 0.4.0

data/README.md

@@ -1,230 +0,0 @@
-# lex-identity
-
-Shared base extension for LegionIO identity providers. Ruby 3.4+.
-
-Providers opt into small helper mixins and common OAuth runners. No provider
-inheritance hierarchy, authentication policy, storage backend, or name-normalization
-rule is imposed. Existing identity extensions are not migrated by this gem.
-
-## Layout and runtime ownership
-
-- `lib/legion/extensions/identity/helpers/` — provider integration, PKCE, browser, OAuth, loopback callback listener
-- `lib/legion/extensions/identity/runners/base/oauth.rb` — reusable OAuth operations, outside automatic runner discovery
-- `lib/legion/extensions/identity/actors/` — reserved for shared actors; no timers are started
-- `spec/support/provider_contract.rb` — reusable conformance examples, included in the gem
-
-The base extension reports `identity_provider?`, `remote_invocable?`,
-`transport_required?`, and `crypt_required?` as false. It does not register itself
-as an identity provider. Shared runner code lives under `runners/base/` and is
-explicitly required; only direct `runners/*.rb` files are discovered by LegionIO.
-This prevents generic endpoint arguments and browser control from becoming API
-routes. `remote_invocable?` alone does not disable route registration.
-
-`Legion::Identity::Resolver`, `Broker`, `Lease`, and `LeaseRenewer` remain owned by
-LegionIO core. This gem does not duplicate their registries or renewal scheduler,
-and can be loaded without booting LegionIO.
-
-## Provider integration
-
-```ruby
-require 'legion/extensions/identity'
-
-# MyProvider is your existing identity provider module or object.
-MyProvider.extend(Legion::Extensions::Identity::Helpers::Provider)
-MyProvider.identity_register
-
-lease = MyProvider.identity_build_lease(
-  credential: access_token,
-  expires_at: expires_at,
-  renewable: true,
-  metadata: { scopes: granted_scopes }
-)
-MyProvider.identity_register_credential(lease: lease, qualifier: :work, default: true)
-MyProvider.identity_credentials_available
-MyProvider.identity_token_for(qualifier: :work, purpose: :api_request)
-```
-
-All registration, lease provenance, credential discovery, and token lookup use
-`MyProvider.provider_name`. There is no second provider-name argument to keep in sync.
-
-| Method | Behavior |
-|---|---|
-| `identity_register` | Registers with the loaded Resolver, or appends to core's existing pending registrations; returns `:registered`, `:pending`, or `:unavailable` when core is absent. Standalone loading does not raise or create a second registry. |
-| `identity_build_lease(credential:, **attributes)` | Builds the core Lease when loaded, otherwise a plain attribute Hash for standalone use. The provider name cannot be overridden through attributes. |
-| `identity_register_credential(lease:, qualifier: :default, default: false)` | Registers with core Broker; raises if Broker is unavailable. Pass a real core Lease when using Broker. |
-| `identity_credentials_available` | Returns this provider's broker qualifiers, or `[]` before Broker loads. |
-| `identity_token_for(qualifier: nil, **options)` | Uses Broker lookup, including context/purpose options; returns `nil` before Broker loads. |
-
-Providers retain their metadata: `provider_name`, `provider_type`, `priority`,
-`trust_weight`, `trust_level`, and `capabilities`. They also retain subject
-verification, profile mapping, normalization, and credential acquisition.
-
-## Optional browser and PKCE helpers
-
-```ruby
-require 'legion/extensions/identity/helpers/pkce'
-require 'legion/extensions/identity/helpers/browser'
-
-helper = Object.new
-helper.extend(Legion::Extensions::Identity::Helpers::Pkce)
-helper.extend(Legion::Extensions::Identity::Helpers::Browser)
-
-proof = helper.pkce_generate
-# { code_verifier:, code_challenge:, code_challenge_method: 'S256' }
-helper.browser_open(url: authorization_url) if helper.browser_gui_available?
-```
-
-These low-level browser/PKCE helpers do not start login sessions. The optional
-`browser_login` runner below supplies the common callback lifecycle.
-
-## Optional OAuth operations
-
-```ruby
-require 'legion/extensions/identity/runners/base/oauth'
-
-oauth = Legion::Extensions::Identity::Runners::Oauth
-url = oauth.oauth_authorize_url(
-  authorization_endpoint: authorization_endpoint,
-  client_id: client_id,
-  redirect_uri: redirect_uri,
-  scope: 'openid profile',
-  state: state,
-  code_challenge: proof[:code_challenge]
-)
-
-result = oauth.exchange_code(
-  token_endpoint: token_endpoint,
-  client_id: client_id,
-  code: code,
-  redirect_uri: redirect_uri,
-  code_verifier: proof[:code_verifier]
-)
-```
-
-The authorization URL helper returns a String, preserving unrelated endpoint query
-parameters while replacing conflicting OAuth parameters. Scope values are
-space-separated strings.
-
-The public runners return `{ result: provider_response }` on success or
-`{ error:, description: }` on failure:
-
-- `browser_login(authorization_endpoint:, token_endpoint:, client_id:, scope:, callback_port: 0, callback_timeout: 120)`
-
-- `request_device_code(device_authorization_endpoint:, client_id:, scope:)`
-- `exchange_code(token_endpoint:, client_id:, code:, redirect_uri:, code_verifier:, scope: nil)`
-- `refresh_token(token_endpoint:, client_id:, refresh_token:, scope: nil)`
-- `poll_device_code(token_endpoint:, client_id:, device_code:, interval: 5, timeout: 300)`
-
-Device responses require a nonempty device code; token responses require a
-nonempty access token. Provider errors are preserved rather than wrapped as success.
-Polling uses monotonic time, increases the wait by five seconds on `slow_down`,
-and caps waits and request timeouts by the remaining budget. A zero timeout does
-not send a request; nonpositive intervals and negative timeouts raise `ArgumentError`.
-
-For provider-specific runners, extend the helpers you use and the common runner:
-
-```ruby
-MyRunner.extend(Legion::Extensions::Identity::Helpers::Oauth)
-MyRunner.extend(Legion::Extensions::Identity::Helpers::Pkce)    # browser_login
-MyRunner.extend(Legion::Extensions::Identity::Helpers::Browser) # browser_login
-MyRunner.extend(Legion::Extensions::Identity::Runners::Oauth)
-```
-
-`Helpers::Oauth#oauth_post(endpoint:, form:, open_timeout: 5, request_timeout: 15)`
-provides form encoding and symbol-keyed JSON parsing for additional provider grants.
-It propagates transport exceptions; the public runners log and return an explicit
-failure. No token persistence, refresh-token rotation policy, or scheduled refresh
-is implemented here.
-
-Concrete provider runners can expose provider-specific operations using configured
-endpoints. Do not expose these generic endpoint arguments through a public runner.
-The old `legion/extensions/identity/runners/oauth` require path has been removed;
-use the explicit `runners/base/oauth` path.
-
-## Explicit browser login
-
-```ruby
-require 'legion/extensions/identity/runners/base/oauth'
-
-result = Legion::Extensions::Identity::Runners::Oauth.browser_login(
-  authorization_endpoint: authorization_endpoint,
-  token_endpoint: token_endpoint,
-  client_id: client_id,
-  scope: 'openid profile',
-  callback_port: 0,
-  callback_timeout: 120
-)
-```
-
-Each call creates its own state, PKCE verifier, and listener. The runner opens the
-browser, waits for a correlated authorization response, exchanges the code using
-the exact redirect URI and verifier, then returns the existing token-result Hash.
-Providers still own token persistence and authenticated-subject verification.
-
-The redirect URI is `http://127.0.0.1:<port>/callback`. Port `0` requests an available
-ephemeral port. If your provider requires an exact registered redirect URI, supply
-its registered fixed port; the listener never binds a non-loopback interface.
-
-The listener accepts only a complete GET callback with matching state and exactly
-one nonempty code or error. Missing/mismatched state, duplicate parameters,
-ambiguous code/error responses, and malformed requests are rejected without
-consuming the pending login. Unrelated paths do not terminate the wait. State is
-checked before accepting provider errors as well as authorization codes.
-
-Callback waiting uses a monotonic deadline, with an 8 KiB header limit and a
-two-second per-client I/O budget bounded by the remaining wait. The listener and
-accepted sockets close on success, provider denial, timeout, and exceptions.
-Browser-launch failure also closes the listener. The static browser response
-contains no callback parameters and only confirms receipt—not token-exchange
-success.
-
-`callback_timeout` must be positive and finite. It bounds callback waiting, not
-browser process startup or the subsequent token endpoint's separate HTTP timeouts.
-A missing graphical session returns `browser_unavailable`; launcher failure returns
-`browser_launch_failed`; an unanswered callback returns `timeout`.
-
-This is explicit user-initiated login only. There is no automatic sign-in, persistent
-session store, background actor, API-hook registration, or implicit device-code
-fallback. Headless callers can use `request_device_code` and `poll_device_code`.
-
-## Shared provider conformance
-
-```ruby
-require File.join(
-  Gem.loaded_specs.fetch('lex-identity').full_gem_path,
-  'spec/support/provider_contract'
-)
-
-RSpec.describe MyProvider do
-  let(:identity_provider) { described_class }
-  let(:canonical_name) { 'example-user' }
-
-  # Configure your provider's upstream responses in the surrounding spec.
-  it_behaves_like 'identity provider contract'
-end
-```
-
-These examples exercise the current core resolver contract:
-
-- Auth and fallback providers receive `resolve` without arguments.
-- Profile providers receive `resolve_all(canonical_name:)` when present, otherwise
-  `resolve(canonical_name:)`. The selected method must return a profile Hash or
-  `nil`, not an account Array.
-- Auth/fallback results require a valid canonical name, kind, and source.
-- Profile providers cannot choose the canonical name.
-- Metadata types and trust levels are checked without forcing common values.
-
-Account enumeration is separate from the profile result consumed by core. The
-shared examples do not add or change a provider's `resolve_all` implementation.
-
-## Development
-
-```bash
-bundle install
-bundle exec rspec --format json --out tmp/rspec_results.json --format progress --out tmp/rspec_progress.txt
-bundle exec rubocop -A
-```
-
-## License
-
-MIT.

data/lib/legion/extensions/identity/helpers/browser.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-require 'rbconfig'
-require 'legion/logging/helper'
-
-module Legion
-  module Extensions
-    module Identity
-      module Helpers
-        module Browser
-          include Legion::Logging::Helper
-
-          def browser_gui_available?(**)
-            return true if /darwin|mswin|mingw/.match?(browser_host_os)
-
-            !ENV['DISPLAY'].nil? || !ENV['WAYLAND_DISPLAY'].nil?
-          end
-
-          def browser_open(url:, **)
-            command = case browser_host_os
-                      when /darwin/ then 'open'
-                      when /linux/ then 'xdg-open'
-                      when /mswin|mingw/ then 'start'
-                      end
-            unless command
-              log.warn('No browser command is available for this operating system')
-              return false
-            end
-
-            opened = system(command, url) == true
-            log.warn('Browser launch failed') unless opened
-            opened
-          end
-
-          private
-
-          def browser_host_os
-            RbConfig::CONFIG['host_os']
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/identity/helpers/callback_server.rb

@@ -1,170 +0,0 @@
-# frozen_string_literal: true
-
-require 'socket'
-require 'uri'
-require 'legion/logging/helper'
-
-module Legion
-  module Extensions
-    module Identity
-      module Helpers
-        class CallbackServer
-          include Legion::Logging::Helper
-
-          HEADER_LIMIT = 8192
-          CLIENT_TIMEOUT = 2
-          RESPONSE_BODY = "Callback received. Return to the application.\n"
-
-          attr_reader :redirect_uri
-
-          def initialize(port: 0, **)
-            raise ArgumentError, 'port must be an integer between 0 and 65535' unless port.is_a?(Integer) && (0..65_535).cover?(port)
-
-            @listener = TCPServer.new('127.0.0.1', port)
-            @redirect_uri = "http://127.0.0.1:#{@listener.addr[1]}/callback"
-          end
-
-          def wait_for_callback(state:, timeout: 120, **)
-            raise ArgumentError, 'timeout must be finite and nonnegative' unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout >= 0
-            raise ArgumentError, 'state must be a nonempty string' unless state.is_a?(String) && !state.empty?
-            raise IOError, 'callback server is closed' if @listener.closed?
-
-            deadline = callback_now + timeout
-            while callback_wait(io: @listener, deadline: deadline)
-              @client = @listener.accept_nonblock(exception: false)
-              next if @client == :wait_readable
-
-              result = callback_receive(client: @client, state: state, deadline: [deadline, callback_now + CLIENT_TIMEOUT].min)
-              return result if result
-            end
-            { error: 'timeout', description: 'Timed out waiting for OAuth callback' }
-          rescue IOError, SystemCallError => e
-            handle_exception(e, level: :warn, operation: 'identity.callback.wait')
-            { error: 'callback_failed', description: 'OAuth callback listener failed' }
-          ensure
-            shutdown
-          end
-
-          def shutdown(**)
-            callback_close(socket: @client) if @client.is_a?(IO)
-            callback_close(socket: @listener)
-            nil
-          end
-
-          private
-
-          def callback_now
-            ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
-          end
-
-          def callback_wait(io:, deadline:, writable: false)
-            remaining = deadline - callback_now
-            return false unless remaining.positive?
-
-            readers, writers = writable ? [nil, [io]] : [[io], nil]
-            !IO.select(readers, writers, nil, remaining).nil?
-          end
-
-          def callback_receive(client:, state:, deadline:)
-            header = callback_read_header(client: client, deadline: deadline)
-            status, result = header ? callback_parse(header: header, state: state) : [400, nil]
-            callback_respond(client: client, status: status, deadline: deadline)
-            result
-          rescue IOError, SystemCallError => e
-            handle_exception(e, level: :warn, operation: 'identity.callback.receive')
-            nil
-          ensure
-            callback_close(socket: client)
-          end
-
-          def callback_read_header(client:, deadline:)
-            header = +''.b
-            while header.bytesize < HEADER_LIMIT && callback_wait(io: client, deadline: deadline)
-              chunk = client.read_nonblock(HEADER_LIMIT - header.bytesize, exception: false)
-              next if chunk == :wait_readable
-              return if chunk.nil?
-
-              header << chunk
-              return header if header.include?("\r\n\r\n")
-            end
-            nil
-          end
-
-          def callback_parse(header:, state:)
-            return [400, nil] unless header.end_with?("\r\n\r\n")
-
-            request, *headers = header.delete_suffix("\r\n\r\n").split("\r\n")
-            match = %r{\AGET (/[^\s]*) HTTP/1\.[01]\z}.match(request.to_s)
-            return [400, nil] unless match && callback_headers_valid?(headers: headers)
-
-            target = match[1]
-            return [400, nil] if target.start_with?('//') || /[^\x21-\x7e]|%(?![0-9a-fA-F]{2})/.match?(target)
-
-            uri = URI.parse(target)
-            return [400, nil] if uri.host || uri.fragment
-            return [404, nil] unless uri.path == '/callback'
-
-            callback_result(query: uri.query.to_s, state: state)
-          rescue URI::InvalidURIError, ArgumentError => e
-            sanitized = ArgumentError.new('Rejected malformed OAuth callback request')
-            sanitized.set_backtrace(e.backtrace)
-            handle_exception(sanitized, level: :warn, operation: 'identity.callback.parse')
-            [400, nil]
-          end
-
-          def callback_headers_valid?(headers:)
-            headers.all? do |header|
-              match = /\A([!#$%&'*+.^_`|~0-9A-Za-z-]+):[\t\x20-\x7e]*\z/.match(header)
-              next false unless match
-
-              name = match[1].downcase
-              next false if name == 'transfer-encoding'
-              next false if name == 'content-length' && header.split(':', 2).last.strip != '0'
-
-              true
-            end
-          end
-
-          def callback_result(query:, state:)
-            pairs = URI.decode_www_form(query, Encoding::UTF_8)
-            params = pairs.to_h
-            return [400, nil] if pairs.length != params.length || params['state'] != state
-            return [400, nil] if params.key?('code') == params.key?('error')
-
-            if params.key?('code')
-              return [400, nil] if params['code'].empty? || params.key?('error_description') || params.key?('error_uri')
-
-              [200, { code: params['code'] }]
-            else
-              return [400, nil] if params['error'].empty?
-
-              [200, { error: params['error'], description: params.fetch('error_description', '') }]
-            end
-          end
-
-          def callback_respond(client:, status:, deadline:)
-            reason = { 200 => 'OK', 400 => 'Bad Request', 404 => 'Not Found' }.fetch(status)
-            body = status == 200 ? RESPONSE_BODY : "Callback request not accepted.\n"
-            response = "HTTP/1.1 #{status} #{reason}\r\nContent-Type: text/plain; charset=utf-8\r\n" \
-                       "Cache-Control: no-store\r\nConnection: close\r\nContent-Length: #{body.bytesize}\r\n\r\n#{body}"
-            offset = 0
-            while offset < response.bytesize && callback_wait(io: client, deadline: deadline, writable: true)
-              written = client.write_nonblock(response.byteslice(offset..), exception: false)
-              next if written == :wait_writable
-
-              offset += written
-            end
-          rescue IOError, SystemCallError => e
-            handle_exception(e, level: :warn, operation: 'identity.callback.respond')
-          end
-
-          def callback_close(socket:)
-            socket.close unless socket.closed?
-          rescue IOError, SystemCallError => e
-            handle_exception(e, level: :warn, operation: 'identity.callback.close')
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/identity/helpers/oauth.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-require 'uri'
-require 'faraday'
-require 'legion/json'
-require 'legion/json/helper'
-require 'legion/logging'
-
-module Legion
-  module Extensions
-    module Identity
-      module Helpers
-        module Oauth
-          include Legion::Logging::Helper
-          include Legion::JSON::Helper
-
-          def oauth_authorize_url(authorization_endpoint:, client_id:, redirect_uri:, scope:, state:, code_challenge:,
-                                  code_challenge_method: 'S256', **)
-            uri = URI.parse(authorization_endpoint)
-            params = {
-              'client_id' => client_id, 'response_type' => 'code', 'redirect_uri' => redirect_uri,
-              'scope' => scope, 'state' => state, 'code_challenge' => code_challenge,
-              'code_challenge_method' => code_challenge_method
-            }
-            query = URI.decode_www_form(uri.query.to_s).reject { |key, _value| params.key?(key) }
-            uri.query = URI.encode_www_form(query + params.to_a)
-            uri.to_s
-          end
-
-          def oauth_post(endpoint:, form:, open_timeout: 5, request_timeout: 15, **)
-            connection = Faraday.new do |http|
-              http.headers['Accept'] = 'application/json'
-              http.headers['Content-Type'] = 'application/x-www-form-urlencoded'
-              http.options.open_timeout = open_timeout
-              http.options.timeout = request_timeout
-            end
-            response = connection.post(endpoint, URI.encode_www_form(form))
-            oauth_parse_response(response: response)
-          end
-
-          private
-
-          def oauth_parse_response(response:)
-            body = response.body.to_s.empty? ? {} : json_load(response.body)
-            return body if body.is_a?(Hash) && body[:error]
-            return { error: "http_#{response.status}", error_description: response.reason_phrase.to_s } unless response.success?
-            return body if body.is_a?(Hash)
-
-            { error: 'invalid_response', error_description: 'OAuth response must be a JSON object' }
-          rescue Legion::JSON::ParseError => e
-            sanitized = StandardError.new("OAuth response parsing failed (#{e.class})")
-            sanitized.set_backtrace(e.backtrace)
-            handle_exception(sanitized, level: :error, operation: 'identity.oauth_parse_response')
-            return { error: "http_#{response.status}", error_description: response.reason_phrase.to_s } unless response.success?
-
-            { error: 'invalid_response', error_description: 'OAuth response is not valid JSON' }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/identity/helpers/pkce.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-require 'digest'
-require 'securerandom'
-
-module Legion
-  module Extensions
-    module Identity
-      module Helpers
-        module Pkce
-          def pkce_generate(**)
-            verifier = SecureRandom.hex(32)
-            challenge = [Digest::SHA256.digest(verifier)].pack('m0').tr('+/', '-_').delete('=')
-            { code_verifier: verifier, code_challenge: challenge, code_challenge_method: 'S256' }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/identity/helpers/provider.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Identity
-      module Helpers
-        module Provider
-          def identity_register(**)
-            if defined?(Legion::Identity::Resolver) && Legion::Identity::Resolver.respond_to?(:register)
-              Legion::Identity::Resolver.register(self)
-              :registered
-            elsif defined?(Legion::Identity) &&
-                  Legion::Identity.respond_to?(:pending_registrations) &&
-                  Legion::Identity.pending_registrations.respond_to?(:<<)
-              Legion::Identity.pending_registrations << self
-              :pending
-            else
-              :unavailable
-            end
-          end
-
-          def identity_build_lease(credential:, **attributes)
-            attributes = attributes.merge(provider: provider_name, credential: credential)
-            return attributes unless defined?(Legion::Identity::Lease)
-
-            Legion::Identity::Lease.new(**attributes)
-          end
-
-          def identity_register_credential(lease:, qualifier: :default, default: false, **)
-            unless defined?(Legion::Identity::Broker) && Legion::Identity::Broker.respond_to?(:register_provider)
-              raise 'Credential registration requires Legion::Identity::Broker'
-            end
-
-            Legion::Identity::Broker.register_provider(provider_name, provider: self, lease: lease, qualifier: qualifier, default: default)
-          end
-
-          def identity_credentials_available(**)
-            return [] unless defined?(Legion::Identity::Broker)
-
-            Legion::Identity::Broker.credentials_available(provider_name)
-          end
-
-          def identity_token_for(qualifier: nil, **)
-            return nil unless defined?(Legion::Identity::Broker)
-
-            Legion::Identity::Broker.token_for(provider_name, qualifier: qualifier, **)
-          end
-        end
-      end
-    end
-  end
-end