ask-auth 0.2.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 268475822d2ec9d8bc5ab6d195f4ea3825e0aff7791ff47a74ea8f659171a75b
-  data.tar.gz: f6b5c88522979f20a4abab042318c563cea020be1d158e5e44f8a8185e54a682
+  metadata.gz: d8434cd70339a093050b7c19364a628d9b8e56048f41c1bb492f6268ed672b39
+  data.tar.gz: d5c377bb5480fb7e19d1dca9a0ca46bc1a29d09ef4dc7d3fc3f216fa38342552
 SHA512:
-  metadata.gz: 4668da8f0e6cd3785047da39491b9dfea164c498520b0865e5c31cf5d7e3150c0dfab75fb3db24fd09f091550b830bd10d20ccd83c746f2921b68104b65c1658
-  data.tar.gz: 1ba6532f00081411fdedfd54ca8926f4bacdafd8ae7b5952aafc5c84232c4fd8e7f883d3b89e50ef5a7d4df7251055ef3b8489c1a216f8728f033470c9e1cc28
+  metadata.gz: 7676f10e858addff8c2ab69db3223aea179e11016ce8faa44422432dfcc2e567ff772c9d04e037b8370d4a32b894c0094a5e3a23debfdd43d02bb877283c775f
+  data.tar.gz: cacdcf31dbe213784f73c9ca0a70b8b17e280cd13697fb07e4cbcf5ac99261c340ed24f0591b637584dcc6d32be10bf83eac713b89751511a82ff2e2e6ecdfd1

data/CHANGELOG.md

@@ -1,3 +1,57 @@
+## [0.3.1] — 2026-08-07
+
+### Added
+
+- **Device authorization grant (RFC 8628) OAuth providers.** `Ask::Auth::Providers::DeviceOAuth` base — `start_device_flow` (device + user code from the provider), `complete_device_flow` (long-poll the token endpoint; `PendingAuthorization` until the user authorizes) — plus two providers:
+  - `Ask::Auth::Providers::Xai` — xAI/Grok device OAuth (public Grok-CLI client, `auth.x.ai/oauth2`), mirroring opencode's xai.ts.
+  - `Ask::Auth::Providers::GithubCopilot` — GitHub Copilot device OAuth (`github.com/login/device/code`), mirroring opencode's copilot.ts. Note: Copilot's device flow is a gray area of GitHub's terms.
+
+## [0.3.0] — 2026-08-07
+
+### Added
+
+- **OpenAI Codex OAuth provider — bring your ChatGPT subscription.** `Ask::Auth::Providers::OpenaiCodex` completes the PKCE flow against `auth.openai.com` (public Codex client id, `openid profile email offline_access` scope): `authorize_url` (with `id_token_add_organizations`), `authorize!` (code exchange → `{token, refresh_token, expires_at, account_id, raw}`), and `refresh(refresh_token:)`. Includes `.allowed_model?` tier filtering (gpt-5.4+ general + codex family; pro-reasoning and gpt-5.6 excluded) and account-id extraction from the id_token — mirroring opencode's codex.ts.
+- **Completed OAuth base provider.** `Ask::Auth::Providers::OAuth` now implements the token exchange (`authorize!`) and refresh grants via an injectable stdlib HTTP layer, with optional verifier/state persistence through a `store`/`fetch`-responding storage object. `Ask::Auth::OAuthError` raised on transport/provider failures.
+- `Ask::Auth::OAuth::HTTP` — dependency-free form-encoded POST for token endpoints (swappable in tests).
+
+## [0.2.3] — 2026-07-18
+
+### Fixed
+
+- **`Providers::File#call` and `Providers::Env#call` safely return nil for Array names** — When `resolve` passes Array path segments (e.g., `[:opencode, :api_key]`), providers that don't support nested lookups now return nil instead of crashing on `.to_sym`.
+
+## [0.2.2] — 2026-07-18
+
+### Fixed
+
+- **`Providers::RailsCredentials` checks value, not just `respond_to?`** — `ActiveSupport::OrderedOptions#respond_to?` returns `true` for any method name. The provider now checks the actual returned value before returning it.
+
+## [0.2.1] — 2026-07-18
+
+### Added
+
+- **`resolve(*names)` supports Array path segments for nested lookups** — Callers can pass Symbol/String for flat lookup or an Array for path segments:
+  ```ruby
+  Ask::Auth.resolve(:opencode_api_key)
+  Ask::Auth.resolve(:opencode_go_api_key, [:opencode, :api_key])
+  ```
+
+## [0.2.0] — 2026-07-18
+
+### Added
+
+- **`resolve(*names)` now accepts multiple credential names** — Tries each name in order through the provider chain, returns the first match. Backward-compatible with single-name calls.
+
+### Fixed
+
+- **`MissingCredential` shows all tried names** — Error message lists all credential names attempted.
+
+## [0.1.4] — 2026-07-18
+
+### Added
+
+- **`Providers::RailsCredentials` progressive split strategy** — Tries progressively shorter left splits for credential names like `nvidia_nim_api_key`.
+
 ## [0.1.1] - 2026-06-25
 
 ### Changed

data/README.md

@@ -1,49 +1,38 @@
 # ask-auth
 
-**Credential resolution for the ask-rb ecosystem.**
+[![Gem Version](https://badge.fury.io/rb/ask-auth.svg)](https://badge.fury.io/rb/ask-auth)
 
-A single API for resolving credentials across all ask-rb gems. Service gems call `Ask::Auth.resolve(:github_token)` — they never touch env vars, files, or OAuth flows directly. The resolution chain walks configured providers in order and returns the first match.
-
-Zero external dependencies for the core. Optional ActiveRecord integration for database-backed token storage.
+Credential resolution for the ask-rb ecosystem. A single API for resolving credentials across all ask-rb gems: service gems call `Ask::Auth.resolve(:github_token)` and never touch env vars, files, or OAuth flows directly. Zero external dependencies.
 
 ## Installation
 
-Add this line to your Gemfile:
-
 ```ruby
 gem "ask-auth"
 ```
 
-Or install it directly:
-
-```bash
-gem install ask-auth
-```
-
 ## Quick Start
 
 ```ruby
 require "ask-auth"
 
-# Simple — works everywhere, no config needed
 token = Ask::Auth.resolve(:github_token)
 # => "ghp_abc123..."
 
-# With a user context (for per-user providers like Database)
+# Per-user credentials (Database, OAuth providers)
 token = Ask::Auth.resolve(:openai_api_key, user: current_user)
 ```
 
-By default, the resolution chain checks these providers in order:
+`resolve` walks the provider chain in order and returns the first match, or raises `Ask::Auth::MissingCredential`. Multiple names can be given for fallbacks, and arrays of symbols resolve nested paths (e.g. `resolve([:opencode, :api_key])`).
 
-1. **Env** — environment variables
-2. **File** — `~/.ask/credentials.yml`
-3. **RailsCredentials** — `Rails.application.credentials` (if Rails is loaded)
-4. **Database** — ActiveRecord-backed token storage (if ActiveRecord is loaded)
-5. **OAuth** — interactive PKCE flow (returns nil by default — requires explicit authorization)
+## Resolution chain
 
-## Configuration
+1. **Env**: environment variables (`ENV["GITHUB_TOKEN"]`)
+2. **File**: `~/.ask/credentials.yml`
+3. **RailsCredentials**: `Rails.application.credentials` (when Rails is loaded)
+4. **Database**: ActiveRecord-backed per-user token storage (when ActiveRecord is loaded)
+5. **OAuth**: interactive PKCE flow (returns nil by default, requires explicit authorization)
 
-Customize the provider chain with `Ask::Auth.configure`:
+## Configuration
 
 ```ruby
 Ask::Auth.configure do |c|
@@ -55,125 +44,16 @@ Ask::Auth.configure do |c|
 end
 ```
 
-Once configured, the resolution chain is frozen and thread-safe.
-
-## Providers
-
-### Env (`Ask::Auth::Providers::Env`)
-
-Resolves credentials from environment variables by convention. Tries multiple naming styles:
-
-```ruby
-Ask::Auth.resolve(:github_token)
-# Checks (in order): ENV["GITHUB_TOKEN"], ENV["GITHUBTOKEN"], ENV["github_token"]
-```
-
-No configuration needed.
-
-### File (`Ask::Auth::Providers::File`)
-
-Reads credentials from a YAML file:
-
-```yaml
-# ~/.ask/credentials.yml
-github_token: ghp_abc123...
-openai_api_key: sk-...
-```
-
-```ruby
-Ask::Auth::Providers::File.new
-Ask::Auth::Providers::File.new(path: "~/.custom/credentials.yml")
-```
-
-The file is created with `0600` permissions when written (the provider is read-only; use your editor or a setup script).
-
-### RailsCredentials (`Ask::Auth::Providers::RailsCredentials`)
-
-Wraps `Rails.application.credentials`. Converts `snake_case` names to dot-separated paths:
-
-```ruby
-Ask::Auth.resolve(:github_token)
-# Looks up: Rails.application.credentials.github.token
-```
-
-Safely returns nil when Rails is not loaded.
-
-### Database (`Ask::Auth::Providers::Database`)
-
-ActiveRecord-backed token storage per user. Expects a model with `user_id`, `name`, `token`, `expires_at`, and `refresh_token` columns.
-
-```ruby
-# app/models/credential.rb
-class Credential < ApplicationRecord
-  belongs_to :user
-end
-```
-
-```ruby
-Ask::Auth::Providers::Database.new
-Ask::Auth::Providers::Database.new(model: AccessToken)
-```
-
-Handles token expiry automatically: calls `refresh!` when a token has expired and a `refresh_token` is available.
-
-### OAuth (`Ask::Auth::Providers::OAuth`)
-
-PKCE OAuth flow for interactive credential authorization. This provider does not resolve automatically — it provides the authorization interface:
-
-```ruby
-provider = Ask::Auth::Providers::OAuth.new(
-  client_id: "your-client-id",
-  authorize_url: "https://provider.com/oauth/authorize",
-  token_url: "https://provider.com/oauth/token"
-)
-
-# Step 1: Generate the authorization URL
-url = provider.authorize_url(user: current_user)
-
-# Step 2: Exchange the code for tokens
-provider.authorize!(user: current_user, code: params[:code])
-```
-
-The full token exchange flow requires configuration. The PKCE utility methods (`generate_code_verifier`, `generate_code_challenge`) are ready for use.
-
-## Custom Providers
-
-Any object that responds to `call(name, user:)` can be a provider:
-
-```ruby
-Ask::Auth.configure do |c|
-  c.providers = [
-    Ask::Auth::Providers::Env.new,
-    ->(name, user: nil) { user&.api_key_for(name) }
-  ]
-end
-```
-
-## Error Handling
+Any object responding to `call(name, user:)` can act as a provider. Once configured, the resolution chain is frozen and thread-safe.
 
-```ruby
-begin
-  token = Ask::Auth.resolve(:missing_key)
-rescue Ask::Auth::MissingCredential => e
-  puts e.message
-  # "No credential found for :missing_key. Set MISSING_KEY in your environment..."
-end
+## Full documentation
 
-begin
-  # At usage time
-  raise Ask::Auth::InvalidCredential.new(:github_token, "rate limited")
-rescue Ask::Auth::InvalidCredential => e
-  puts e.message
-  # "Credential :github_token is rate limited..."
-end
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [ask-auth in depth](https://ask-rb.github.io/ask-docs/core/auth) covers each provider, the OAuth flow, and error handling. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
-git clone https://github.com/ask-rb/ask-auth
-cd ask-auth
-bin/setup
+```
+bundle install
 bundle exec rake test
 ```
 

data/lib/ask/auth/oauth/http.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Ask
+  module Auth
+    module OAuth
+      # Minimal form-encoded POST for token endpoints — stdlib only, so
+      # ask-auth stays dependency-free. Swappable in tests.
+      module HTTP
+        OPEN_TIMEOUT = 10
+        READ_TIMEOUT = 30
+
+        def self.post_form(url, params, headers: {})
+          uri = URI(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.open_timeout = OPEN_TIMEOUT
+          http.read_timeout = READ_TIMEOUT
+          http.use_ssl = uri.scheme == "https"
+          req = Net::HTTP::Post.new(uri)
+          req.set_form_data(params)
+          headers.each { |k, v| req[k] = v }
+          res = http.request(req)
+          [res.code.to_i, res.body.to_s]
+        end
+      end
+    end
+  end
+end

data/lib/ask/auth/providers/device_oauth.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "oauth"
+
+module Ask
+  module Auth
+    module Providers
+      # RFC 8628 device authorization grant (OAuth 2.0 device flow) — the
+      # headless-friendly alternative to authorization-code PKCE: no
+      # redirect_uri, no callback route. The user opens a URL on any
+      # device, types a short code, and we long-poll the token endpoint.
+      #
+      #   provider = Ask::Auth::Providers::Xai.new
+      #   device = provider.start_device_flow(user: current_user)
+      #   # render device[:verification_uri] + device[:user_code]
+      #   tokens = provider.complete_device_flow(user:, device_code: device[:device_code])
+      #   # raises PendingAuthorization until the user authorizes
+      #
+      # Subclasses set client_id, token_url, device_code_url, and scope.
+      class DeviceOAuth < OAuth
+        DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"
+
+        # The user hasn't authorized yet — the caller should wait and retry.
+        class PendingAuthorization < StandardError; end
+
+        def initialize(storage: nil, client_id: nil, token_url: nil, device_code_url: nil,
+          scope: nil, http: Ask::Auth::OAuth::HTTP)
+          super(storage: storage, client_id: client_id, authorize_url: nil, token_url: token_url,
+            redirect_uri: nil, scope: scope, http: http)
+          @device_code_url = device_code_url
+        end
+
+        # Step 1: ask the provider for a device + user code.
+        # Returns { device_code:, user_code:, verification_uri:, interval:, expires_at: }.
+        def start_device_flow(user: nil)
+          raise OAuthError, "device_code_url not configured" if @device_code_url.to_s.empty?
+
+          status, body = @http.post_form(@device_code_url, {client_id: @client_id, scope: @scope.to_s})
+          raise OAuthError, "device authorization request failed (#{status}): #{body.to_s[0, 200]}" unless status == 200
+
+          data = JSON.parse(body)
+          {
+            device_code: data["device_code"],
+            user_code: data["user_code"],
+            verification_uri: data["verification_uri"] || data["verification_url"],
+            interval: data["interval"].to_i,
+            expires_at: data["expires_in"].to_i > 0 ? Time.now + data["expires_in"].to_i : nil
+          }
+        rescue JSON::ParserError => e
+          raise OAuthError, "bad device authorization response: #{e.message}"
+        end
+
+        # Step 2: poll the token endpoint. Returns the token hash on
+        # success (same shape as #authorize!), or raises PendingAuthorization
+        # when the user hasn't authorized yet.
+        def complete_device_flow(user: nil, device_code:)
+          status, body = @http.post_form(token_url_for, {
+            grant_type: DEVICE_CODE_GRANT_TYPE,
+            device_code: device_code,
+            client_id: @client_id
+          })
+          data = parse_json(body)
+
+          case status
+          when 200
+            parse_token_response(body)
+          when 400
+            case data["error"]
+            when "authorization_pending", "slow_down"
+              raise PendingAuthorization
+            when "access_denied", "expired_token"
+              raise OAuthError, "device authorization #{data["error"]}"
+            else
+              raise OAuthError, "device authorization failed (#{status}): #{data["error_description"] || data["error"]}"
+            end
+          else
+            raise OAuthError, "device authorization failed (#{status}): #{body.to_s[0, 200]}"
+          end
+        end
+
+        private
+
+        def token_url_for
+          @token_url || raise(OAuthError, "token_url not configured")
+        end
+
+        def parse_json(body)
+          JSON.parse(body)
+        rescue JSON::ParserError
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/ask/auth/providers/github_copilot.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "device_oauth"
+
+module Ask
+  module Auth
+    module Providers
+      # GitHub Copilot device OAuth — "bring your Copilot subscription".
+      # RFC 8628 device grant against github.com/login/device/code (the
+      # public Copilot CLI client id). Constants mirror opencode's
+      # github-copilot/copilot.ts.
+      #
+      # Note: Copilot's device flow is a gray area of GitHub's terms — it
+      # works, but treat it as a user-beware integration.
+      class GithubCopilot < DeviceOAuth
+        CLIENT_ID = "Ov23li8tweQw6odWQebz"
+        DEVICE_CODE_URL = "https://github.com/login/device/code"
+        ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token"
+        SCOPE = "read:user"
+
+        def initialize(storage: nil, client_id: CLIENT_ID, http: Ask::Auth::OAuth::HTTP)
+          super(storage: storage, client_id: client_id, token_url: ACCESS_TOKEN_URL,
+            device_code_url: DEVICE_CODE_URL, scope: SCOPE, http: http)
+        end
+      end
+    end
+  end
+end

data/lib/ask/auth/providers/oauth.rb

@@ -1,28 +1,45 @@
 # frozen_string_literal: true
 
 require "base64"
+require "json"
 require "openssl"
 require "securerandom"
+require_relative "../oauth/http"
 
 module Ask
   module Auth
     module Providers
-      # PKCE OAuth flow for interactive credential authorization.
+      # Authorization-code PKCE OAuth flow for interactive credential
+      # authorization (e.g. bring-your-own-subscription).
       #
-      # This provider implements the OAuth interface. The full interactive flow
-      # can be deferred — the interface is wired for integration and the PKCE
-      # utility methods are ready.
-      #
-      #   provider = Ask::Auth::Providers::OAuth.new(storage: database_provider)
+      #   provider = Ask::Auth::Providers::OAuth.new(
+      #     client_id: "...", authorize_url: "...", token_url: "...",
+      #     redirect_uri: "https://app.example/oauth/callback", scope: "..."
+      #   )
       #   url = provider.authorize_url(user: current_user)
-      #   # redirect user to url, then:
-      #   provider.authorize!(user: current_user, code: params[:code])
+      #   # redirect user to url; the callback receives ?code=...&state=...
+      #   tokens = provider.authorize!(user: current_user, code: params[:code])
+      #   # { token:, refresh_token:, expires_at:, raw: {...} }
+      #
+      # The code verifier is generated during #authorize_url. Persist it via
+      # a storage object that responds to #store(name, user:, value:) /
+      # #fetch(name, user:) — the app implements it (e.g. on its OAuth state
+      # table) — or pass code_verifier: back into #authorize! yourself.
+      #
+      # Subclasses override #parse_token_response to add provider-specific
+      # fields (e.g. an account id from the id_token).
       class OAuth
-        def initialize(storage: nil, client_id: nil, authorize_url: nil, token_url: nil)
+        attr_reader :client_id, :redirect_uri
+
+        def initialize(storage: nil, client_id: nil, authorize_url: nil, token_url: nil,
+          redirect_uri: nil, scope: nil, http: Ask::Auth::OAuth::HTTP)
           @storage = storage
           @client_id = client_id
           @authorize_url = authorize_url
           @token_url = token_url
+          @redirect_uri = redirect_uri
+          @scope = scope
+          @http = http
         end
 
         # Returns nil (no automatic resolution) — OAuth requires interactive flow.
@@ -43,35 +60,100 @@ module Ask
           )
         end
 
-        # Returns the authorization URL to redirect the user to.
-        def authorize_url(user:, verifier: nil, state: nil)
+        # Returns the authorization URL to redirect the user to. The code
+        # verifier (and state) are persisted via the storage object when one
+        # is configured, so the callback can recover them.
+        def authorize_url(user:, verifier: nil, state: nil, extra_params: {})
           verifier ||= generate_code_verifier
           state ||= SecureRandom.hex(16)
           challenge = generate_code_challenge(verifier)
 
-          # Store state and verifier for this user (requires a storage provider)
-          if @storage && user
-            @storage.call(:oauth_state, user: user)
-          end
+          persist_oauth_state(user, verifier, state)
 
-          uri = URI.parse(@authorize_url || "https://example.com/oauth/authorize")
-          uri.query = URI.encode_www_form(
+          params = {
             response_type: "code",
-            client_id: @client_id || "YOUR_CLIENT_ID",
-            redirect_uri: "urn:ietf:wg:oauth:2.0:oob",
-            scope: "",
+            client_id: @client_id,
+            redirect_uri: redirect_uri_value,
+            scope: @scope.to_s,
             state: state,
             code_challenge: challenge,
             code_challenge_method: "S256"
-          )
+          }.merge(extra_params)
+
+          uri = URI.parse(@authorize_url || "https://example.com/oauth/authorize")
+          uri.query = URI.encode_www_form(params)
           uri.to_s
         end
 
         # Exchange an authorization code for tokens.
-        # +user+:: The user to associate the credential with
-        # +code+:: The authorization code from the redirect
-        def authorize!(user:, code:)
-          raise NotImplementedError, "Token exchange requires a configured token_url and client_id"
+        #
+        # Returns { token:, refresh_token:, expires_at:, raw: {...} } (plus
+        # any subclass-added keys). Raises OAuthError on transport or
+        # provider errors.
+        def authorize!(user:, code:, code_verifier: nil, redirect_uri: nil)
+          verifier = code_verifier || fetch_oauth_state(user, :verifier)
+          if verifier.to_s.empty?
+            raise OAuthError, "missing code verifier — pass code_verifier or persist it via a storage object"
+          end
+
+          body = token_exchange(
+            grant_type: "authorization_code",
+            code: code,
+            redirect_uri: redirect_uri || redirect_uri_value,
+            client_id: @client_id,
+            code_verifier: verifier
+          )
+          parse_token_response(body)
+        end
+
+        # Refresh an access token using a refresh token grant.
+        def refresh(refresh_token:)
+          body = token_exchange(
+            grant_type: "refresh_token",
+            refresh_token: refresh_token,
+            client_id: @client_id
+          )
+          parse_token_response(body)
+        end
+
+        private
+
+        def token_exchange(**params)
+          raise OAuthError, "token_url not configured" if @token_url.to_s.empty?
+
+          status, body = @http.post_form(@token_url, params)
+          raise OAuthError, "token exchange failed (#{status}): #{body.to_s[0, 200]}" unless status == 200
+
+          body
+        end
+
+        def parse_token_response(body)
+          data = JSON.parse(body)
+          {
+            token: data["access_token"],
+            refresh_token: data["refresh_token"],
+            expires_at: data["expires_in"] ? Time.now + data["expires_in"].to_i : nil,
+            raw: data
+          }
+        rescue JSON::ParserError => e
+          raise OAuthError, "bad token response: #{e.message}"
+        end
+
+        def redirect_uri_value
+          @redirect_uri || "urn:ietf:wg:oauth:2.0:oob"
+        end
+
+        def persist_oauth_state(user, verifier, state)
+          return unless @storage.respond_to?(:store) && user
+
+          @storage.store(:oauth_state, user: user, value: {verifier: verifier, state: state})
+        end
+
+        def fetch_oauth_state(user, key)
+          return nil unless @storage.respond_to?(:fetch) && user
+
+          value = @storage.fetch(:oauth_state, user: user)
+          value.is_a?(Hash) ? value[key] : nil
         end
       end
     end

data/lib/ask/auth/providers/openai_codex.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+require "base64"
+require_relative "oauth"
+
+module Ask
+  module Auth
+    module Providers
+      # OpenAI Codex OAuth — "bring your ChatGPT subscription" (Plus/Pro).
+      #
+      # Users authenticate with their OpenAI account (PKCE against
+      # auth.openai.com, the public Codex client id) and get tokens that
+      # route requests through their subscription quota instead of the
+      # pay-per-token API — flat-rate, like Cline/Hermes/opencode.
+      #
+      #   provider = Ask::Auth::Providers::OpenaiCodex.new(redirect_uri: "...")
+      #   url = provider.authorize_url(user: current_user)
+      #   tokens = provider.authorize!(user: current_user, code: params[:code])
+      #   provider.refresh(refresh_token: tokens[:refresh_token])
+      #
+      # #authorize! returns { token:, refresh_token:, expires_at:, account_id:, raw: }.
+      # Models are tier-filtered with .allowed_model? (mirrors opencode's
+      # codex.ts: the OAuth path excludes pro-reasoning and gpt-5.6, and only
+      # gpt-5.4+ general models are allowed).
+      class OpenaiCodex < OAuth
+        CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
+        ISSUER = "https://auth.openai.com"
+        AUTHORIZE_URL = "#{ISSUER}/oauth/authorize"
+        TOKEN_URL = "#{ISSUER}/oauth/token"
+        SCOPE = "openid profile email offline_access"
+
+        ALLOWED_MODELS = %w[gpt-5.5 gpt-5.3-codex-spark gpt-5.4 gpt-5.4-mini].freeze
+        DISALLOWED_MODELS = %w[gpt-5.5-pro].freeze
+
+        def initialize(storage: nil, client_id: CLIENT_ID, redirect_uri: nil, http: Ask::Auth::OAuth::HTTP)
+          super(
+            storage: storage,
+            client_id: client_id,
+            authorize_url: AUTHORIZE_URL,
+            token_url: TOKEN_URL,
+            redirect_uri: redirect_uri,
+            scope: SCOPE,
+            http: http
+          )
+        end
+
+        def authorize_url(user:, verifier: nil, state: nil)
+          super(user: user, verifier: verifier, state: state, extra_params: {id_token_add_organizations: "true"})
+        end
+
+        def parse_token_response(body)
+          data = JSON.parse(body)
+          {
+            token: data["access_token"],
+            refresh_token: data["refresh_token"],
+            expires_at: data["expires_in"] ? Time.now + data["expires_in"].to_i : nil,
+            account_id: self.class.account_id_from(data["id_token"]),
+            raw: data
+          }
+        rescue JSON::ParserError => e
+          raise OAuthError, "bad token response: #{e.message}"
+        end
+
+        # Whether a model id is usable through a ChatGPT subscription's OAuth
+        # path. General gpt-5.4+ models and the codex family are allowed;
+        # pro-reasoning models (gpt-5.5-pro) and gpt-5.6 are not.
+        def self.allowed_model?(model_id)
+          return true if ALLOWED_MODELS.include?(model_id)
+          return false if DISALLOWED_MODELS.include?(model_id) || model_id == "gpt-5.6"
+
+          match = model_id.match(/\Agpt-(\d+\.\d+)/)
+          match ? match[1].to_f > 5.4 : false
+        end
+
+        # The ChatGPT account id, from the id_token's JWT claims — sent as
+        # the ChatGPT-Account-Id header on API calls.
+        def self.account_id_from(id_token)
+          claims = decode_jwt_claims(id_token)
+          claims["chatgpt_account_id"] ||
+            claims.dig("https://api.openai.com/auth", "chatgpt_account_id") ||
+            claims.dig("organizations", 0, "id")
+        end
+
+        def self.decode_jwt_claims(token)
+          payload = token.to_s.split(".")[1]
+          return {} if payload.to_s.empty?
+
+          decoded = Base64.urlsafe_decode64(payload)
+          JSON.parse(decoded)
+        rescue ArgumentError, JSON::ParserError
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/ask/auth/providers/xai.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "device_oauth"
+
+module Ask
+  module Auth
+    module Providers
+      # xAI (Grok) device OAuth — "bring your xAI account": the public
+      # Grok-CLI OAuth client (RFC 8628 device grant against
+      # auth.x.ai/oauth2). Constants mirror opencode's xai.ts. The access
+      # token works as the bearer key for the standard xAI OpenAI-compatible
+      # API (api.x.ai/v1).
+      class Xai < DeviceOAuth
+        CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828"
+        TOKEN_URL = "https://auth.x.ai/oauth2/token"
+        DEVICE_AUTHORIZATION_URL = "https://auth.x.ai/oauth2/device/code"
+        SCOPE = "openid profile email offline_access grok-cli:access api:access"
+
+        def initialize(storage: nil, client_id: CLIENT_ID, http: Ask::Auth::OAuth::HTTP)
+          super(storage: storage, client_id: client_id, token_url: TOKEN_URL,
+            device_code_url: DEVICE_AUTHORIZATION_URL, scope: SCOPE, http: http)
+        end
+      end
+    end
+  end
+end

data/lib/ask/auth/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Auth
-    VERSION = "0.2.3"
+    VERSION = "0.3.1"
   end
 end

data/lib/ask/auth.rb

@@ -6,6 +6,10 @@ require_relative "auth/providers/file"
 require_relative "auth/providers/rails_credentials"
 require_relative "auth/providers/database"
 require_relative "auth/providers/oauth"
+require_relative "auth/providers/openai_codex"
+require_relative "auth/providers/device_oauth"
+require_relative "auth/providers/xai"
+require_relative "auth/providers/github_copilot"
 
 module Ask
   # Credential resolution for the ask-rb ecosystem.
@@ -27,6 +31,12 @@ module Ask
       end
     end
 
+    class OAuthError < StandardError
+      def initialize(message)
+        super("OAuth flow failed: #{message}")
+      end
+    end
+
     class InvalidCredential < RuntimeError
       def initialize(name, reason = "invalid or expired")
         super("Credential #{name.inspect} is #{reason}. " \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-auth
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.3.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -78,11 +78,16 @@ files:
 - README.md
 - lib/ask-auth.rb
 - lib/ask/auth.rb
+- lib/ask/auth/oauth/http.rb
 - lib/ask/auth/providers/database.rb
+- lib/ask/auth/providers/device_oauth.rb
 - lib/ask/auth/providers/env.rb
 - lib/ask/auth/providers/file.rb
+- lib/ask/auth/providers/github_copilot.rb
 - lib/ask/auth/providers/oauth.rb
+- lib/ask/auth/providers/openai_codex.rb
 - lib/ask/auth/providers/rails_credentials.rb
+- lib/ask/auth/providers/xai.rb
 - lib/ask/auth/version.rb
 homepage: https://github.com/ask-rb/ask-auth
 licenses: