authaction-ruby-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6bf466144a51660744b7de95865c88ce7963f50a0c1a1bf023e34bed2b0df45
+  data.tar.gz: 50942b4e647f7761c7f5194e06fa38fb50480022bf1795419133c4cc3b8b5a95
+SHA512:
+  metadata.gz: be653628175c59117591347d0346cd2e544fab1931712d88b97b2e5674414cf7909a747751e7bda8218dfb206df0b0f07d00e9673c962e1af8e3c86ccf20ca98
+  data.tar.gz: 6346a61e449bc82262fd70a136d805dfdb00b13e44bea35ea2828856113f06f73b4684d41b330c8425fb9f5f65104027652a543854f54248819f23e2fb179649

data/README.md

@@ -0,0 +1,188 @@
+# authaction-ruby-sdk
+
+JWT verification SDK for Ruby backends. Validates AuthAction access tokens via JWKS — handles key fetching, caching, and rotation automatically.
+
+Works with **Rails** (API mode or full-stack) and any **Rack** application.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "authaction"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install authaction
+```
+
+---
+
+## Quick Start
+
+### Verify a token directly
+
+```ruby
+require "authaction"
+
+verifier = AuthAction::JwtVerifier.new(
+  domain:   ENV["AUTHACTION_DOMAIN"],    # e.g. myapp.eu.authaction.com
+  audience: ENV["AUTHACTION_AUDIENCE"]   # e.g. https://api.myapp.com
+)
+
+# Verify a raw token — raises TokenExpiredError / TokenInvalidError on failure
+payload = verifier.verify_token(token)
+
+# Verify from Authorization header — returns nil on missing/invalid, never raises
+payload = verifier.verify_request(request.headers["Authorization"])
+
+puts payload["sub"]   # user identifier
+puts payload["email"] # any JWT claim
+```
+
+### `verify_token`
+
+Decodes and validates the JWT. Returns the claims hash on success.
+
+| Condition | Raises |
+|-----------|--------|
+| `exp` in the past | `AuthAction::TokenExpiredError` |
+| Bad signature, wrong issuer/audience, malformed JWT | `AuthAction::TokenInvalidError` |
+
+### `verify_request`
+
+Convenience wrapper for HTTP handler code. Extracts the token from a `Bearer <token>` header value.
+
+- Returns `nil` (never raises) when the header is absent, not a Bearer scheme, or the token is invalid/expired.
+- Returns the claims hash on success.
+
+---
+
+## Rails Integration
+
+### 1. Require the concern
+
+In `config/application.rb` or an initializer:
+
+```ruby
+require "authaction/rails"
+```
+
+### 2. Include in your base controller
+
+```ruby
+class ApplicationController < ActionController::API
+  include AuthAction::Rails::JwtAuthenticatable
+end
+```
+
+### 3. Protect actions with `before_action`
+
+```ruby
+class ProtectedController < ApplicationController
+  before_action :authenticate_request!
+
+  def index
+    render json: { sub: @current_payload["sub"] }
+  end
+end
+```
+
+On success, `@current_payload` (also available via the `current_payload` reader) contains the decoded JWT claims hash.
+
+On failure the concern renders a `401 Unauthorized` JSON response automatically:
+
+```json
+{ "error": "Token has expired" }
+{ "error": "Missing Bearer token" }
+```
+
+### Public endpoints
+
+Skip authentication for specific actions:
+
+```ruby
+class UsersController < ApplicationController
+  before_action :authenticate_request!, except: [:create]
+
+  def create
+    # public — no token required
+  end
+
+  def show
+    render json: { sub: current_payload["sub"] }
+  end
+end
+```
+
+---
+
+## Configuration
+
+The concern reads configuration from environment variables:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `AUTHACTION_DOMAIN` | Your AuthAction tenant domain | `myapp.eu.authaction.com` |
+| `AUTHACTION_AUDIENCE` | Expected `aud` claim in tokens | `https://api.myapp.com` |
+
+```bash
+AUTHACTION_DOMAIN=your-tenant.eu.authaction.com
+AUTHACTION_AUDIENCE=https://api.your-app.com
+```
+
+When using `JwtVerifier` directly, pass these as keyword arguments instead of relying on ENV vars.
+
+---
+
+## Exceptions
+
+```ruby
+require "authaction"
+
+begin
+  payload = verifier.verify_token(token)
+rescue AuthAction::TokenExpiredError
+  # token exp claim is in the past
+rescue AuthAction::TokenInvalidError => e
+  # bad signature, wrong issuer/audience, malformed JWT
+  puts e.message
+end
+```
+
+Both error classes inherit from `AuthAction::Error < StandardError`.
+
+---
+
+## How JWKS Caching Works
+
+`JwtVerifier` fetches public keys from `https://<domain>/.well-known/jwks.json` on first use and caches the key set in memory:
+
+- **TTL**: 5 minutes (300 seconds). The cache is invalidated automatically after expiry.
+- **Key rotation**: When a JWT arrives with an unknown `kid`, the cache is busted immediately and the JWKS endpoint is re-fetched before retrying verification.
+- **Thread safety**: A `Mutex` protects the cache so the verifier is safe to share across threads (e.g. as a class-level instance variable in Rails controllers).
+
+---
+
+## Running Tests
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+Tests use [WebMock](https://github.com/bblimke/webmock) to stub the JWKS endpoint and real RSA key pairs to provide end-to-end coverage of the JWKS parsing and JWT validation path — no network calls required.
+
+---
+
+## License
+
+MIT

data/authaction.gemspec

@@ -0,0 +1,21 @@
+require_relative "lib/authaction/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "authaction-ruby-sdk"
+  spec.version     = AuthAction::VERSION
+  spec.summary     = "AuthAction JWT verification for Ruby — Rails and Rack"
+  spec.description = "JWT verification SDK for AuthAction. Fetches and caches JWKS from the well-known endpoint, validates RS256 tokens with issuer, audience, and expiry checks. Includes a Rails concern for controller authentication."
+  spec.authors     = ["AuthAction"]
+  spec.homepage    = "https://github.com/authaction/authaction-ruby-sdk"
+  spec.license     = "MIT"
+
+  spec.required_ruby_version = ">= 3.0"
+  spec.files = Dir["lib/**/*.rb", "*.md", "*.gemspec"]
+
+  spec.add_dependency "jwt", "~> 2.9"
+
+  spec.add_development_dependency "rspec",   "~> 3.13"
+  spec.add_development_dependency "webmock", "~> 3.23"
+  spec.add_development_dependency "ostruct"
+  spec.add_development_dependency "rake"
+end

data/lib/authaction/errors.rb

@@ -0,0 +1,9 @@
+module AuthAction
+  class Error < StandardError; end
+
+  # Raised when the JWT exp claim is in the past.
+  class TokenExpiredError < Error; end
+
+  # Raised when signature, issuer, audience, or structure is invalid.
+  class TokenInvalidError < Error; end
+end

data/lib/authaction/jwt_verifier.rb

@@ -0,0 +1,96 @@
+require "jwt"
+require "net/http"
+require "json"
+require "uri"
+
+module AuthAction
+  # Core JWT verifier.
+  #
+  # Fetches the JWKS from https://<domain>/.well-known/jwks.json, caches the
+  # key set in memory (TTL: 5 minutes), and busts the cache when an unknown
+  # kid is seen (key rotation).
+  #
+  # @example
+  #   verifier = AuthAction::JwtVerifier.new(
+  #     domain:   "myapp.eu.authaction.com",
+  #     audience: "https://api.myapp.com"
+  #   )
+  #   payload = verifier.verify_token(token)
+  class JwtVerifier
+    CACHE_TTL = 300 # seconds
+
+    def initialize(domain:, audience:)
+      @issuer   = "https://#{domain}"
+      @jwks_uri = "https://#{domain}/.well-known/jwks.json"
+      @audience = audience
+      @mutex    = Mutex.new
+      @cache    = nil
+      @cached_at = nil
+    end
+
+    # Verify a raw JWT string and return the decoded payload hash.
+    #
+    # @param token [String] raw JWT
+    # @return [Hash] decoded claims
+    # @raise [TokenExpiredError] if the token is expired
+    # @raise [TokenInvalidError] if signature, issuer, audience, or structure is invalid
+    def verify_token(token)
+      payload, _header = JWT.decode(
+        token, nil, true,
+        algorithms: ["RS256"],
+        iss:        @issuer,
+        verify_iss: true,
+        aud:        @audience,
+        verify_aud: true,
+        jwks:       method(:jwks_loader)
+      )
+      payload
+    rescue JWT::ExpiredSignature
+      raise TokenExpiredError, "Token has expired"
+    rescue JWT::DecodeError => e
+      raise TokenInvalidError, e.message
+    end
+
+    # Extract and verify the Bearer token from an Authorization header value.
+    #
+    # Returns nil when the header is absent or not a Bearer scheme.
+    # Never raises — returns nil on invalid or expired tokens.
+    #
+    # @param authorization_header [String, nil]
+    # @return [Hash, nil] decoded claims or nil
+    def verify_request(authorization_header)
+      return nil unless authorization_header&.start_with?("Bearer ")
+
+      token = authorization_header[7..].strip
+      verify_token(token)
+    rescue TokenExpiredError, TokenInvalidError
+      nil
+    end
+
+    private
+
+    def jwks_loader(options)
+      @mutex.synchronize do
+        @cache = nil if options[:kid_not_found]
+        @cache = nil if cache_expired?
+        @cache ||= begin
+          @cached_at = Time.now
+          fetch_jwks
+        end
+      end
+    end
+
+    def cache_expired?
+      @cached_at.nil? || (Time.now - @cached_at) >= CACHE_TTL
+    end
+
+    def fetch_jwks
+      uri      = URI(@jwks_uri)
+      response = Net::HTTP.get_response(uri)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise TokenInvalidError, "Failed to fetch JWKS: HTTP #{response.code}"
+      end
+      JSON.parse(response.body, symbolize_names: true)
+    end
+  end
+end

data/lib/authaction/rails/jwt_authenticatable.rb

@@ -0,0 +1,58 @@
+module AuthAction
+  module Rails
+    # ActiveSupport::Concern that adds JWT authentication to a Rails controller.
+    #
+    # @example
+    #   class ApplicationController < ActionController::API
+    #     include AuthAction::Rails::JwtAuthenticatable
+    #   end
+    #
+    #   class ProtectedController < ApplicationController
+    #     before_action :authenticate_request!
+    #
+    #     def index
+    #       render json: { sub: @current_payload["sub"] }
+    #     end
+    #   end
+    #
+    # Configure via environment variables:
+    #   AUTHACTION_DOMAIN   = myapp.eu.authaction.com
+    #   AUTHACTION_AUDIENCE = https://api.myapp.com
+    module JwtAuthenticatable
+      extend ActiveSupport::Concern
+
+      included do
+        # Expose @current_payload as a helper for views (optional in API mode).
+        attr_reader :current_payload
+      end
+
+      class_methods do
+        # Class-level memoized verifier — one JWKS cache per controller class.
+        def authaction_verifier
+          @authaction_verifier ||= AuthAction::JwtVerifier.new(
+            domain:   ENV.fetch("AUTHACTION_DOMAIN"),
+            audience: ENV.fetch("AUTHACTION_AUDIENCE")
+          )
+        end
+      end
+
+      private
+
+      # Verifies the Bearer JWT from the Authorization header.
+      # Sets @current_payload on success; renders 401 on failure.
+      def authenticate_request!
+        header = request.headers["Authorization"]
+        unless header&.start_with?("Bearer ")
+          render json: { error: "Missing Bearer token" }, status: :unauthorized and return
+        end
+
+        token = header[7..].strip
+        @current_payload = self.class.authaction_verifier.verify_token(token)
+      rescue AuthAction::TokenExpiredError
+        render json: { error: "Token has expired" }, status: :unauthorized
+      rescue AuthAction::TokenInvalidError => e
+        render json: { error: e.message }, status: :unauthorized
+      end
+    end
+  end
+end

data/lib/authaction/rails.rb

@@ -0,0 +1 @@
+require "authaction/rails/jwt_authenticatable"

data/lib/authaction/version.rb

@@ -0,0 +1,3 @@
+module AuthAction
+  VERSION = "0.1.0"
+end

data/lib/authaction.rb

@@ -0,0 +1,20 @@
+require "authaction/version"
+require "authaction/errors"
+require "authaction/jwt_verifier"
+
+# AuthAction JWT verification SDK for Ruby.
+#
+# @example Basic usage
+#   verifier = AuthAction::JwtVerifier.new(
+#     domain:   "myapp.eu.authaction.com",
+#     audience: "https://api.myapp.com"
+#   )
+#   payload = verifier.verify_token(token)
+#
+# @example Rails controller (include the concern)
+#   require "authaction/rails"
+#   class ApplicationController < ActionController::API
+#     include AuthAction::Rails::JwtAuthenticatable
+#   end
+module AuthAction
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: authaction-ruby-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AuthAction
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: JWT verification SDK for AuthAction. Fetches and caches JWKS from the
+  well-known endpoint, validates RS256 tokens with issuer, audience, and expiry checks.
+  Includes a Rails concern for controller authentication.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- authaction.gemspec
+- lib/authaction.rb
+- lib/authaction/errors.rb
+- lib/authaction/jwt_verifier.rb
+- lib/authaction/rails.rb
+- lib/authaction/rails/jwt_authenticatable.rb
+- lib/authaction/version.rb
+homepage: https://github.com/authaction/authaction-ruby-sdk
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: AuthAction JWT verification for Ruby — Rails and Rack
+test_files: []