philiprehberger-jwt_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 061c721779c41c845521340ab97e7dfe6ce04ece1670eba7ae0d582f86db2dc8
+  data.tar.gz: 5c81cf4b22758b7a0351f32185d403b2be2b5f38bbac693ecd057a77605b5230
+SHA512:
+  metadata.gz: 8d29b733775f8a814f71dd49ebce2da9d585a0574cbd4d18627a5f70cc4f6b8305df1c6225aabd4482992c1adb2f36ec957a9571cbcedc0fa8e85e8ce48e1a06
+  data.tar.gz: c593dbec85796d146aee22d73f7b04313bb3a7cdc2f07c39075eb72b62aa5b8ed1538b6f01c0a0f1d11dcd46fc253935a84a05077b0badf0ee05a043bd52ce4f

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-21
+
+### Added
+- JWT encoding with HMAC-SHA256/384/512 signing
+- JWT decoding with signature verification
+- Automatic claim management (exp, iat, iss, jti)
+- Expiration and issuer validation
+- Access/refresh token pair generation
+- Token refresh from valid refresh tokens
+- In-memory token revocation with thread-safe store
+- Configurable secret, algorithm, issuer, and expiration
+- Zero external dependencies (uses Ruby's built-in OpenSSL)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 philiprehberger
+
+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,125 @@
+# philiprehberger-jwt_kit
+
+[![Tests](https://github.com/philiprehberger/rb-jwt-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-jwt-kit/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-jwt_kit.svg)](https://rubygems.org/gems/philiprehberger-jwt_kit)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-jwt-kit)](LICENSE)
+
+Opinionated JWT toolkit with encoding, validation, refresh tokens, and revocation
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-jwt_kit"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-jwt_kit
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/jwt_kit"
+
+Philiprehberger::JwtKit.configure do |c|
+  c.secret = "your-secret-key-at-least-32-characters"
+  c.issuer = "my-app"
+end
+
+token = Philiprehberger::JwtKit.encode(user_id: 42)
+payload = Philiprehberger::JwtKit.decode(token)
+payload["user_id"] # => 42
+```
+
+### Configuration
+
+```ruby
+Philiprehberger::JwtKit.configure do |c|
+  c.secret = "your-secret-key"          # Required — HMAC signing key
+  c.algorithm = :hs256                   # :hs256 (default), :hs384, :hs512
+  c.issuer = "my-app"                    # Optional — sets the `iss` claim
+  c.expiration = 3600                    # Access token TTL in seconds (default: 1 hour)
+  c.refresh_expiration = 86_400 * 7      # Refresh token TTL (default: 1 week)
+end
+```
+
+### Encoding
+
+```ruby
+token = Philiprehberger::JwtKit.encode(user_id: 42, role: "admin")
+# => "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHA..."
+```
+
+Claims `exp`, `iat`, `iss`, and `jti` are added automatically.
+
+### Decoding
+
+```ruby
+payload = Philiprehberger::JwtKit.decode(token)
+payload["user_id"] # => 42
+payload["exp"]     # => 1711036800
+payload["iss"]     # => "my-app"
+payload["jti"]     # => "a1b2c3d4-..."
+```
+
+Decoding validates the signature, expiration, and issuer automatically.
+
+### Token Pairs
+
+```ruby
+access_token, refresh_token = Philiprehberger::JwtKit.token_pair(user_id: 42)
+```
+
+The access token uses the standard expiration. The refresh token uses `refresh_expiration` and includes a `type: "refresh"` claim.
+
+### Refresh Tokens
+
+```ruby
+new_access_token = Philiprehberger::JwtKit.refresh(refresh_token)
+```
+
+Validates the refresh token, verifies it has `type: "refresh"`, and issues a new access token with the original payload.
+
+### Revocation
+
+```ruby
+Philiprehberger::JwtKit.revoke(token)
+Philiprehberger::JwtKit.revoked?(token)  # => true
+Philiprehberger::JwtKit.decode(token)    # => raises RevokedToken
+```
+
+Revocation uses an in-memory store keyed by JTI. The store is thread-safe.
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `JwtKit.configure { \|c\| ... }` | Configure secret, algorithm, issuer, and expiration |
+| `JwtKit.configuration` | Returns the current configuration |
+| `JwtKit.reset_configuration!` | Resets configuration to defaults |
+| `JwtKit.encode(payload)` | Encodes a payload into a signed JWT token |
+| `JwtKit.decode(token)` | Decodes and validates a JWT token |
+| `JwtKit.token_pair(payload)` | Generates an access/refresh token pair |
+| `JwtKit.refresh(refresh_token)` | Issues a new access token from a refresh token |
+| `JwtKit.revoke(token)` | Revokes a token by its JTI |
+| `JwtKit.revoked?(token)` | Checks if a token has been revoked |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/philiprehberger/jwt_kit/configuration.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module JwtKit
+    # Configuration singleton for JWT settings.
+    #
+    # @example
+    #   Philiprehberger::JwtKit.configure do |c|
+    #     c.secret = 'my-secret-key'
+    #     c.algorithm = :hs256
+    #     c.issuer = 'my-app'
+    #     c.expiration = 3600
+    #   end
+    class Configuration
+      # @return [String, nil] HMAC secret key (required for HS* algorithms)
+      attr_accessor :secret
+
+      # @return [Symbol] signing algorithm (:hs256, :hs384, :hs512)
+      attr_accessor :algorithm
+
+      # @return [String, nil] optional issuer for the `iss` claim
+      attr_accessor :issuer
+
+      # @return [Integer] default TTL in seconds for access tokens
+      attr_accessor :expiration
+
+      # @return [Integer] default TTL in seconds for refresh tokens
+      attr_accessor :refresh_expiration
+
+      def initialize
+        @secret = nil
+        @algorithm = :hs256
+        @issuer = nil
+        @expiration = 3600
+        @refresh_expiration = 86_400 * 7
+      end
+
+      # Returns the OpenSSL digest algorithm name.
+      #
+      # @return [String] digest name (e.g. 'SHA256')
+      # @raise [Error] if the algorithm is unsupported
+      def digest_algorithm
+        case @algorithm
+        when :hs256 then 'SHA256'
+        when :hs384 then 'SHA384'
+        when :hs512 then 'SHA512'
+        else raise Error, "Unsupported algorithm: #{@algorithm}"
+        end
+      end
+
+      # Returns the JWT algorithm header value.
+      #
+      # @return [String] algorithm name (e.g. 'HS256')
+      def algorithm_name
+        @algorithm.to_s.upcase
+      end
+    end
+  end
+end

data/lib/philiprehberger/jwt_kit/decoder.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module JwtKit
+    # Decodes and validates JWT tokens.
+    module Decoder
+      module_function
+
+      # Decodes a JWT token and validates its claims.
+      #
+      # @param token [String] JWT token string
+      # @param config [Configuration] JWT configuration
+      # @return [Hash] decoded payload with string keys
+      # @raise [DecodeError] if the token format is invalid
+      # @raise [InvalidSignature] if the signature does not match
+      # @raise [TokenExpired] if the token has expired
+      # @raise [InvalidIssuer] if the issuer does not match the configuration
+      def decode(token, config)
+        raise DecodeError, 'Token must be a string' unless token.is_a?(String)
+
+        parts = token.split('.')
+        raise DecodeError, 'Invalid token format: expected 3 segments' unless parts.length == 3
+
+        header_segment, payload_segment, signature_segment = parts
+
+        verify_signature!("#{header_segment}.#{payload_segment}", signature_segment, config)
+
+        payload = JSON.parse(base64url_decode(payload_segment))
+
+        validate_expiration!(payload)
+        validate_issuer!(payload, config)
+
+        payload
+      rescue JSON::ParserError
+        raise DecodeError, 'Invalid token: malformed JSON'
+      end
+
+      # Base64url-decodes a string.
+      #
+      # @param data [String] base64url-encoded string
+      # @return [String] decoded string
+      def base64url_decode(data)
+        Base64.urlsafe_decode64(data)
+      rescue ArgumentError
+        raise DecodeError, 'Invalid token: malformed base64'
+      end
+
+      # Verifies the token signature.
+      #
+      # @param signing_input [String] header.payload string
+      # @param signature [String] base64url-encoded signature
+      # @param config [Configuration] JWT configuration
+      # @raise [InvalidSignature] if the signature does not match
+      def verify_signature!(signing_input, signature, config)
+        expected = Encoder.sign(signing_input, config)
+        raise InvalidSignature, 'Token signature is invalid' unless secure_compare(expected, signature)
+      end
+
+      # Validates the expiration claim.
+      #
+      # @param payload [Hash] decoded payload
+      # @raise [TokenExpired] if the token has expired
+      def validate_expiration!(payload)
+        exp = payload['exp']
+        return unless exp
+
+        raise TokenExpired, 'Token has expired' if exp.to_i <= Time.now.to_i
+      end
+
+      # Validates the issuer claim.
+      #
+      # @param payload [Hash] decoded payload
+      # @param config [Configuration] JWT configuration
+      # @raise [InvalidIssuer] if the issuer does not match
+      def validate_issuer!(payload, config)
+        return unless config.issuer
+
+        raise InvalidIssuer, "Invalid issuer: expected #{config.issuer}" unless payload['iss'] == config.issuer
+      end
+
+      # Constant-time string comparison to prevent timing attacks.
+      #
+      # @param a [String] first string
+      # @param b [String] second string
+      # @return [Boolean] true if the strings are equal
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        left = a.unpack('C*')
+        right = b.unpack('C*')
+        result = 0
+        left.each_with_index { |byte, i| result |= byte ^ right[i] }
+        result.zero?
+      end
+    end
+  end
+end

data/lib/philiprehberger/jwt_kit/encoder.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module JwtKit
+    # Encodes payloads into signed JWT tokens.
+    module Encoder
+      module_function
+
+      # Encodes a payload into a JWT token string.
+      #
+      # @param payload [Hash] custom claims to include in the token
+      # @param config [Configuration] JWT configuration
+      # @return [String] signed JWT token
+      # @raise [Error] if no secret is configured
+      def encode(payload, config)
+        raise Error, 'Secret is required for encoding' unless config.secret
+
+        header = { 'alg' => config.algorithm_name, 'typ' => 'JWT' }
+        now = Time.now.to_i
+
+        claims = {
+          'exp' => now + config.expiration,
+          'iat' => now,
+          'jti' => SecureRandom.uuid
+        }
+        claims['iss'] = config.issuer if config.issuer
+
+        merged = claims.merge(payload.transform_keys(&:to_s))
+
+        header_segment = base64url_encode(JSON.generate(header))
+        payload_segment = base64url_encode(JSON.generate(merged))
+        signing_input = "#{header_segment}.#{payload_segment}"
+        signature = sign(signing_input, config)
+
+        "#{signing_input}.#{signature}"
+      end
+
+      # Base64url-encodes a string without padding.
+      #
+      # @param data [String] data to encode
+      # @return [String] base64url-encoded string
+      def base64url_encode(data)
+        Base64.urlsafe_encode64(data, padding: false)
+      end
+
+      # Signs data using HMAC with the configured algorithm.
+      #
+      # @param data [String] data to sign
+      # @param config [Configuration] JWT configuration
+      # @return [String] base64url-encoded signature
+      def sign(data, config)
+        digest = OpenSSL::Digest.new(config.digest_algorithm)
+        signature = OpenSSL::HMAC.digest(digest, config.secret, data)
+        base64url_encode(signature)
+      end
+    end
+  end
+end

data/lib/philiprehberger/jwt_kit/revocation.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Philiprehberger
+  module JwtKit
+    # Token revocation support with an in-memory store.
+    module Revocation
+      # Thread-safe in-memory revocation store backed by a Set.
+      class MemoryStore
+        def initialize
+          @revoked = Set.new
+          @mutex = Mutex.new
+        end
+
+        # Revokes a token by extracting and storing its JTI.
+        #
+        # @param token [String] JWT token to revoke
+        # @return [void]
+        def revoke(token)
+          jti = extract_jti(token)
+          return unless jti
+
+          @mutex.synchronize { @revoked.add(jti) }
+        end
+
+        # Checks whether a token has been revoked.
+        #
+        # @param token [String] JWT token to check
+        # @return [Boolean] true if the token has been revoked
+        def revoked?(token)
+          jti = extract_jti(token)
+          return false unless jti
+
+          @mutex.synchronize { @revoked.include?(jti) }
+        end
+
+        # Clears all revoked tokens.
+        #
+        # @return [void]
+        def clear
+          @mutex.synchronize { @revoked.clear }
+        end
+
+        # Returns the number of revoked tokens.
+        #
+        # @return [Integer]
+        def size
+          @mutex.synchronize { @revoked.size }
+        end
+
+        private
+
+        def extract_jti(token)
+          parts = token.split('.')
+          return nil unless parts.length == 3
+
+          payload = JSON.parse(Base64.urlsafe_decode64(parts[1]))
+          payload['jti']
+        rescue JSON::ParserError, ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/jwt_kit/token_pair.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module JwtKit
+    # Generates and refreshes access/refresh token pairs.
+    module TokenPair
+      module_function
+
+      # Generates an access token and refresh token pair.
+      #
+      # @param payload [Hash] custom claims to include in both tokens
+      # @param config [Configuration] JWT configuration
+      # @return [Array<String>] `[access_token, refresh_token]`
+      def generate(payload, config)
+        access_token = Encoder.encode(payload, config)
+
+        refresh_payload = payload.merge('type' => 'refresh')
+        original_expiration = config.expiration
+        config.expiration = config.refresh_expiration
+        refresh_token = Encoder.encode(refresh_payload, config)
+        config.expiration = original_expiration
+
+        [access_token, refresh_token]
+      end
+
+      # Refreshes an access token using a valid refresh token.
+      #
+      # @param refresh_token [String] a valid refresh token
+      # @param config [Configuration] JWT configuration
+      # @return [String] new access token
+      # @raise [InvalidToken] if the token is not a refresh token
+      def refresh(refresh_token, config)
+        payload = Decoder.decode(refresh_token, config)
+        raise InvalidToken, 'Token is not a refresh token' unless payload['type'] == 'refresh'
+
+        new_payload = payload.except('exp', 'iat', 'jti', 'iss', 'type')
+        Encoder.encode(new_payload, config)
+      end
+    end
+  end
+end

data/lib/philiprehberger/jwt_kit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module JwtKit
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/jwt_kit.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'json'
+require 'securerandom'
+require 'base64'
+require_relative 'jwt_kit/version'
+require_relative 'jwt_kit/configuration'
+require_relative 'jwt_kit/encoder'
+require_relative 'jwt_kit/decoder'
+require_relative 'jwt_kit/token_pair'
+require_relative 'jwt_kit/revocation'
+
+module Philiprehberger
+  module JwtKit
+    class Error < StandardError; end
+    class DecodeError < Error; end
+    class TokenExpired < DecodeError; end
+    class InvalidSignature < DecodeError; end
+    class InvalidIssuer < DecodeError; end
+    class InvalidToken < DecodeError; end
+    class RevokedToken < DecodeError; end
+
+    class << self
+      # Configures JwtKit using a block.
+      #
+      # @yieldparam config [Configuration] the configuration instance
+      # @return [void]
+      def configure
+        yield(configuration)
+      end
+
+      # Returns the current configuration.
+      #
+      # @return [Configuration]
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Resets the configuration to defaults.
+      #
+      # @return [Configuration]
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      # Encodes a payload into a signed JWT token.
+      #
+      # @param payload [Hash] custom claims
+      # @return [String] signed JWT token
+      def encode(payload = {})
+        Encoder.encode(payload, configuration)
+      end
+
+      # Decodes a JWT token and validates its claims.
+      #
+      # @param token [String] JWT token
+      # @return [Hash] decoded payload
+      # @raise [RevokedToken] if the token has been revoked
+      def decode(token)
+        payload = Decoder.decode(token, configuration)
+        raise RevokedToken, 'Token has been revoked' if revocation_store.revoked?(token)
+
+        payload
+      end
+
+      # Generates an access/refresh token pair.
+      #
+      # @param payload [Hash] custom claims
+      # @return [Array<String>] `[access_token, refresh_token]`
+      def token_pair(payload = {})
+        TokenPair.generate(payload, configuration)
+      end
+
+      # Generates a new access token from a refresh token.
+      #
+      # @param refresh_token [String] valid refresh token
+      # @return [String] new access token
+      def refresh(refresh_token)
+        TokenPair.refresh(refresh_token, configuration)
+      end
+
+      # Revokes a token.
+      #
+      # @param token [String] JWT token to revoke
+      # @return [void]
+      def revoke(token)
+        revocation_store.revoke(token)
+      end
+
+      # Checks whether a token has been revoked.
+      #
+      # @param token [String] JWT token
+      # @return [Boolean]
+      def revoked?(token)
+        revocation_store.revoked?(token)
+      end
+
+      # Returns the revocation store.
+      #
+      # @return [Revocation::MemoryStore]
+      def revocation_store
+        @revocation_store ||= Revocation::MemoryStore.new
+      end
+
+      # Resets the revocation store.
+      #
+      # @return [Revocation::MemoryStore]
+      def reset_revocation_store!
+        @revocation_store = Revocation::MemoryStore.new
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-jwt_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies: []
+description: A complete JWT toolkit for Ruby. Encode and decode tokens with automatic
+  claim management (exp, iat, iss, jti), generate access/refresh token pairs, validate
+  expiration and issuer, and revoke tokens — all without external dependencies.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/jwt_kit.rb
+- lib/philiprehberger/jwt_kit/configuration.rb
+- lib/philiprehberger/jwt_kit/decoder.rb
+- lib/philiprehberger/jwt_kit/encoder.rb
+- lib/philiprehberger/jwt_kit/revocation.rb
+- lib/philiprehberger/jwt_kit/token_pair.rb
+- lib/philiprehberger/jwt_kit/version.rb
+homepage: https://github.com/philiprehberger/rb-jwt-kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-jwt-kit
+  source_code_uri: https://github.com/philiprehberger/rb-jwt-kit
+  changelog_uri: https://github.com/philiprehberger/rb-jwt-kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-jwt-kit/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.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: Opinionated JWT toolkit with encoding, validation, refresh tokens, and revocation
+test_files: []