ask-auth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b1cfb133ab080dc2840a380b4039d783fa982a676c05b3b10cb597264d0da899
+  data.tar.gz: 042e1afabf24c3543eef2cab5e54c8918e97c5bbccf489c8af4f1fd1211e3739
+SHA512:
+  metadata.gz: ee48024db5d7ffaf38afa8244017202c42b917aa8233bd600f0895bc100e32ac5d1089067666eb6ee8fb159d59c88e31236daf9fdca4ef085078a2ecb0f07e9e
+  data.tar.gz: 9d6ba6e6f408b522f57da8793638812105dd3c0b691f24a98ff29ff316e31b82078d9ea84f77a1a71be48e8f360b1edb22f07b674138b29c1aa227e0b585c33d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+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,182 @@
+# ask-auth
+
+**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)` — 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.
+
+## 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)
+token = Ask::Auth.resolve(:openai_api_key, user: current_user)
+```
+
+By default, the resolution chain checks these providers in order:
+
+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)
+
+## Configuration
+
+Customize the provider chain with `Ask::Auth.configure`:
+
+```ruby
+Ask::Auth.configure do |c|
+  c.providers = [
+    Ask::Auth::Providers::Env.new,
+    Ask::Auth::Providers::File.new(path: "~/.myapp/creds.yml"),
+    Ask::Auth::Providers::Database.new(model: AccessToken)
+  ]
+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
+
+```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
+
+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
+```
+
+## Development
+
+```bash
+git clone https://github.com/ask-rb/ask-auth
+cd ask-auth
+bin/setup
+bundle exec rake test
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Ask
+  module Auth
+    module Providers
+      # ActiveRecord-backed token storage per user.
+      #
+      # Expects a model with +user_id+, +name+, +token+, +expires_at+, +refresh_token+.
+      # Handles expiry: if the token has expired and a refresh token is available,
+      # calls +refresh!+ using the stored refresh token.
+      #
+      # Only used when a model is configured or available. Safely returns nil otherwise.
+      class Database
+        # The model class used for credential storage.
+        attr_reader :model
+
+        def initialize(model: default_model)
+          @model = model
+        end
+
+        def call(name, user: nil)
+          return nil unless @model
+          return nil unless user.respond_to?(:id)
+
+          record = @model.respond_to?(:find_by) ? @model.find_by(user_id: user.id, name: name.to_s) : nil
+          return nil unless record
+
+          if record.respond_to?(:expired?) && record.expired?
+            return nil unless record.respond_to?(:refresh!)
+
+            record.refresh!
+            record.reload if record.respond_to?(:reload)
+          end
+
+          record.respond_to?(:token) ? record.token : record
+        end
+
+        private
+
+        def default_model
+          defined?(::ActiveRecord) && defined?(::Credential) ? ::Credential : nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Ask
+  module Auth
+    module Providers
+      # Resolves credentials from environment variables.
+      #
+      # Conventions tested (in order):
+      #   resolve(:github_token)  ->  ENV["GITHUB_TOKEN"], ENV["GITHUBTOKEN"], ENV["github_token"]
+      #
+      # No configuration needed — just a convention.
+      class Env
+        # Returns the credential value from ENV, or nil if not found.
+        def call(name, user: nil)
+          conventions(name).each do |key|
+            value = ENV[key.to_s]
+            return value unless value.nil?
+          end
+          nil
+        end
+
+        private
+
+        def conventions(name)
+          name = name.to_s
+          [
+            name.upcase,
+            name.upcase.delete("_"),
+            name
+          ].uniq
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module Ask
+  module Auth
+    module Providers
+      # Reads credentials from a YAML file (default: +~/.ask/credentials.yml+).
+      #
+      #   Ask::Auth::Providers::File.new(path: "~/.ask/credentials.yml")
+      #
+      # The file is automatically created (with 0600 permissions) when writing,
+      # but this provider is read-only by design.
+      class File
+        DEFAULT_PATH = "~/.ask/credentials.yml"
+
+        def initialize(path: DEFAULT_PATH)
+          @path = path
+        end
+
+        # Returns the credential value from the YAML file, or nil.
+        def call(name, user: nil)
+          data = load_file
+          return nil unless data
+
+          value = data[name.to_s] || data[name.to_sym]
+          value
+        end
+
+        # The path this provider reads from.
+        attr_reader :path
+
+        private
+
+        def load_file
+          expanded = ::File.expand_path(@path)
+          return nil unless ::File.exist?(expanded)
+
+          YAML.safe_load(::File.read(expanded), permitted_classes: [Symbol]) || {}
+        rescue Psych::SyntaxError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require "securerandom"
+
+module Ask
+  module Auth
+    module Providers
+      # PKCE OAuth flow for interactive credential authorization.
+      #
+      # 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)
+      #   url = provider.authorize_url(user: current_user)
+      #   # redirect user to url, then:
+      #   provider.authorize!(user: current_user, code: params[:code])
+      class OAuth
+        def initialize(storage: nil, client_id: nil, authorize_url: nil, token_url: nil)
+          @storage = storage
+          @client_id = client_id
+          @authorize_url = authorize_url
+          @token_url = token_url
+        end
+
+        # Returns nil (no automatic resolution) — OAuth requires interactive flow.
+        def call(name, user: nil)
+          nil
+        end
+
+        # Generate a PKCE code verifier (128-char alphanumeric string).
+        def generate_code_verifier
+          SecureRandom.alphanumeric(128)
+        end
+
+        # Generate a PKCE code challenge (SHA256 base64 digest of verifier).
+        def generate_code_challenge(verifier)
+          ::Base64.urlsafe_encode64(
+            OpenSSL::Digest.digest("SHA256", verifier),
+            padding: false
+          )
+        end
+
+        # Returns the authorization URL to redirect the user to.
+        def authorize_url(user:, verifier: nil, state: nil)
+          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
+
+          uri = URI.parse(@authorize_url || "https://example.com/oauth/authorize")
+          uri.query = URI.encode_www_form(
+            response_type: "code",
+            client_id: @client_id || "YOUR_CLIENT_ID",
+            redirect_uri: "urn:ietf:wg:oauth:2.0:oob",
+            scope: "",
+            state: state,
+            code_challenge: challenge,
+            code_challenge_method: "S256"
+          )
+          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"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Ask
+  module Auth
+    module Providers
+      # Resolves credentials from Rails encrypted credentials.
+      #
+      # Convention: +resolve(:github_token)+ looks up +Rails.application.credentials.github.token+
+      # (dot-separated path from the credential name).
+      #
+      # Safely returns nil when Rails is not loaded.
+      class RailsCredentials
+        def call(name, user: nil)
+          return nil unless defined?(::Rails) && ::Rails.application.respond_to?(:credentials)
+
+          parts = name.to_s.split("_")
+          value = parts.reduce(::Rails.application.credentials) do |obj, part|
+            break nil unless obj.respond_to?(part)
+            obj.public_send(part)
+          end
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/ask/auth/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Auth
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/auth.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "auth/version"
+require_relative "auth/providers/env"
+require_relative "auth/providers/file"
+require_relative "auth/providers/rails_credentials"
+require_relative "auth/providers/database"
+require_relative "auth/providers/oauth"
+
+module Ask
+  # Credential resolution for the ask-rb ecosystem.
+  #
+  # Resolves credentials by walking a configured chain of providers (Env → File →
+  # RailsCredentials → Database → OAuth) and returning the first match.
+  #
+  #   Ask::Auth.resolve(:github_token)
+  #   Ask::Auth.resolve(:openai_api_key, user: current_user)
+  #
+  module Auth
+    class MissingCredential < KeyError
+      def initialize(name)
+        super("No credential found for #{name.inspect}. " \
+              "Set #{name.to_s.upcase} in your environment, add it to ~/.ask/credentials.yml, " \
+              "or configure a provider.")
+      end
+    end
+
+    class InvalidCredential < RuntimeError
+      def initialize(name, reason = "invalid or expired")
+        super("Credential #{name.inspect} is #{reason}. " \
+              "Please update your token and try again.")
+      end
+    end
+
+    class << self
+      def configure
+        config = Configuration.new
+        yield config
+        @configuration = config
+        @configuration.freeze
+      end
+
+      def configuration
+        @configuration ||= default_configuration
+      end
+
+      def reset_configuration!
+        @configuration = nil
+      end
+
+      # Walk providers in order and return the first non-nil credential.
+      # +name+:: Symbol or String identifying the credential (e.g. +:github_token+)
+      # +user+:: Optional user record for per-user providers (Database, OAuth)
+      def resolve(name, user: nil)
+        name = name.to_s.strip
+        return nil if name.empty?
+
+        configuration.providers.each do |provider|
+          value = provider.call(name, user: user)
+          next if value.nil?
+
+          normalized = normalize(value)
+          return normalized unless normalized.nil?
+        end
+
+        raise MissingCredential, name
+      end
+
+      private
+
+      def default_configuration
+        Configuration.new(
+          providers: [
+            Providers::Env.new,
+            Providers::File.new,
+            Providers::RailsCredentials.new,
+            Providers::Database.new,
+            Providers::OAuth.new
+          ]
+        )
+      end
+
+      # Blank normalization: empty strings and whitespace-only normalize to nil
+      def normalize(value)
+        value = value.to_s.strip
+        value.empty? ? nil : value
+      end
+    end
+
+    # Holds configuration for the resolution chain.
+    class Configuration
+      attr_accessor :providers
+
+      def initialize(providers: [])
+        @providers = providers
+      end
+    end
+  end
+end

data/lib/ask-auth.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ask/auth"

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: ask-auth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Env, file, Rails credentials, database, and OAuth providers. Zero external
+  dependencies.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ask-auth.rb
+- lib/ask/auth.rb
+- lib/ask/auth/providers/database.rb
+- lib/ask/auth/providers/env.rb
+- lib/ask/auth/providers/file.rb
+- lib/ask/auth/providers/oauth.rb
+- lib/ask/auth/providers/rails_credentials.rb
+- lib/ask/auth/version.rb
+homepage: https://github.com/ask-rb/ask-auth
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Credential resolution for the ask-rb ecosystem
+test_files: []