lex-identity 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3681b4b6aab75c906d15647f1f359d19760d42994803b8c89d733480e77eacff
-  data.tar.gz: 4b49caa8730568c80e4e84a8d43f9053d83e6bef70a22730115a63492d7d5a06
+  metadata.gz: 18e33b5500f9d9b8ea10ec64025f01c80ecf3e31587c1d0933fe12f0a6b5a951
+  data.tar.gz: e3545bf086d36d22f7001ac6fbb523396b6380311d5c2a06aaabd7a22affdf90
 SHA512:
-  metadata.gz: 527ef0472ad306da82d94ebea24a2b48c0375e164248b322aff1a721897d84f7518eac789852f17af88df14117ddfc9523dd65b42047a84d27af4fb907797d03
-  data.tar.gz: d7e69edd6068f138112c1a685423fc34fd44b8c5d83482c4c4ec8a1179b628955f2043a2e0d43a2b0dc0035b71129f8f56d5d6119dfc69ca64317087a7905849
+  metadata.gz: a884c9d1092ab1560f008da1c5f45270d64f2702f31dc9316976a4c2e62cc4a8fe4c0cb127d4a13174170d192907cc7e9508401a77f00bc6676872cf3bbd13a0
+  data.tar.gz: cab921cd7605cc190b9cf5157d650c6816d4af46c0da7394b16b4b114fc556d82ed96b0135ee7eeac188df7f61dbb2ce0604fd7a868d295536ad673ae75e48f4

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## [0.3.0] - 2026-11-09
+
+### Added
+- Explicit provider-neutral browser login combining PKCE, authorization, a state-correlated loopback callback, and token exchange.
+- A single-use callback listener with bounded reads/writes, request limits, optional fixed-port binding, and cleanup on every exit.
+- Callback security and lifecycle specs for invalid state, ambiguous parameters, provider denial, stalled clients, timeout, and listener disposal.
+
+### Changed
+- Moved reusable OAuth runners to `runners/base/oauth.rb` so generic endpoint and browser operations are not automatically exposed through extension API routes. Consumers must explicitly require the new path.
+
+## [0.2.0] - 2026-11-07
+
+### Added
+- Provider integration helpers for resolver registration, lease construction, and broker credential access using one provider name.
+- Optional PKCE generation and browser helpers.
+- Provider-neutral OAuth authorization, code exchange, refresh, and deadline-bounded device-code polling.
+- Reusable provider conformance examples covering the core resolver's metadata and resolution contracts.
+- Shared OAuth runner compatible with standard extension discovery; the base extension is not itself an identity provider or remotely invocable.
+
+## [0.1.0] - 2026-11-07
+
+### Added
+- Initial gem packaging, namespace, and version.
+- Standard actors, runners, helpers, and spec directories.
+- Shared CI/release workflow, dependency updates, and RuboCop/RSpec configuration.

data/Gemfile

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 source 'https://rubygems.org'
-
 gemspec
 
-gem 'rspec', '~> 3.13'
-gem 'rubocop', '~> 1.75', require: false
+group :development, :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-legion', '~> 0.1'
+  gem 'simplecov', '~> 0.22'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LegionIO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# 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/lex-identity.gemspec

@@ -5,26 +5,29 @@ require_relative 'lib/legion/extensions/identity/version'
 Gem::Specification.new do |spec|
   spec.name          = 'lex-identity'
   spec.version       = Legion::Extensions::Identity::VERSION
-  spec.authors       = ['Esity']
-  spec.email         = ['matthewdiverson@gmail.com']
+  spec.authors       = ['LegionIO']
 
-  spec.summary       = 'LEX Identity'
-  spec.description   = 'Human partner identity modeling and behavioral entropy for brain-modeled agentic AI'
+  spec.summary       = 'Shared LegionIO identity extension base'
+  spec.description   = 'Base extension gem for shared behavior across LegionIO identity provider extensions.'
   spec.homepage      = 'https://github.com/LegionIO/lex-identity'
   spec.license       = 'MIT'
   spec.required_ruby_version = '>= 3.4'
 
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-identity'
-  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-identity'
-  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-identity'
-  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-identity/issues'
+  spec.metadata['homepage_uri']         = spec.homepage
+  spec.metadata['source_code_uri']      = spec.homepage
+  spec.metadata['documentation_uri']    = "#{spec.homepage}/blob/main/README.md"
+  spec.metadata['changelog_uri']        = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['bug_tracker_uri']      = "#{spec.homepage}/issues"
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    Dir.glob('{lib,spec}/**/*') + %w[lex-identity.gemspec Gemfile]
+    Dir.glob('{lib,spec/support}/**/*.rb') + %w[lex-identity.gemspec Gemfile LICENSE README.md CHANGELOG.md]
   end
   spec.require_paths = ['lib']
-  spec.add_development_dependency 'sequel',  '>= 5.70'
-  spec.add_development_dependency 'sqlite3', '>= 2.0'
+
+  spec.add_dependency 'faraday',         '~> 2.0'
+  spec.add_dependency 'legion-cache',    '>= 1.3.0'
+  spec.add_dependency 'legion-json',     '>= 1.2.1'
+  spec.add_dependency 'legion-logging',  '>= 1.5.3'
+  spec.add_dependency 'legion-settings', '>= 1.3.14'
 end

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

@@ -0,0 +1,44 @@
+# 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

@@ -0,0 +1,170 @@
+# 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

@@ -0,0 +1,62 @@
+# 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

@@ -0,0 +1,20 @@
+# 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