philiprehberger-jwt_kit 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b513b3bc5d568092e0a8088d423e2beade5a1b57b00486ba67f9730b9aceb6c
-  data.tar.gz: 07dcb4ce8c3ece9f4880c04e8367467ba3e5eb0da24bb753c577cc124e598a92
+  metadata.gz: 4cd6d9f8d91d59046e8427bb209a93e9220a3ff0398ef1c84758a9396fae2eb7
+  data.tar.gz: 9fc834f733af1020130928f51ee99ff24d94f468c64ab86a638d7859dbba658e
 SHA512:
-  metadata.gz: 597007459eeba4fb603b8b3322eead718e04a320594fb63ba1908e90a146e03f71f110ad5656d62b1d2a8dfaed9e74d4a03737373b1861744af723f1bed6c906
-  data.tar.gz: c93b1e5bd2d9c76bccdeff6bd1f3e797d3aa047f725d13c76b36d4ad346e06da50c3a7fe542f6bead0cf6dc93b0835ed5c9234dbe1c9a2a6be147dcf5aee7242
+  metadata.gz: 2751b52e541a834214dee62b4eaa136798d7f244900c206e063738dae3fd2ae90a2c350916ca82dcf714558028eeecb96ea4ac269a02ede7d6bb7c7c5116b7f2
+  data.tar.gz: 44de4708a12b6bf7b0317a98db9a05d3375a5083791cd126458b9f63f716942a054a4de5327a6a13c918fe1421936a72f5e19451c402f9dbb75070d234169b47

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-26
+
+### Added
+- Lifecycle callbacks on `Configuration`: `on_encode`, `on_decode`, `on_refresh`, `on_revoke` for audit logging and metrics without monkey-patching
+
+## [0.4.0] - 2026-04-15
+
+### Added
+- `JwtKit.expired?(token)` — check a token's `exp` claim without verifying the signature
+
 ## [0.3.2] - 2026-04-09
 
 ### Fixed

data/README.md

@@ -108,6 +108,15 @@ result[:header]   # => {"alg"=>"HS256", "typ"=>"JWT"}
 result[:payload]  # => {"user_id"=>42, "exp"=>..., "iat"=>..., "jti"=>...}
 ```
 
+### Expiration Check
+
+Check whether a token's `exp` claim is in the past without verifying the signature:
+
+```ruby
+Philiprehberger::JwtKit.expired?(token)  # => false
+# Use to decide whether to refresh before the authoritative decode
+```
+
 ### Audience Validation
 
 ```ruby
@@ -171,6 +180,34 @@ Replace the default in-memory store with any object that responds to `#revoke`,
 Philiprehberger::JwtKit.revocation_store = MyRedisRevocationStore.new
 ```
 
+### Lifecycle Callbacks
+
+Hook into encode, decode, refresh, and revoke without monkey-patching. Useful for audit logging, metrics, and tracing:
+
+```ruby
+Philiprehberger::JwtKit.configure do |c|
+  c.secret = 'your-secret-key'
+
+  c.on_encode do |token, payload|
+    Metrics.increment('jwt.encoded', tags: { iss: payload['iss'] })
+  end
+
+  c.on_decode do |payload|
+    Audit.log('jwt.decoded', user_id: payload['user_id'], jti: payload['jti'])
+  end
+
+  c.on_refresh do |new_token|
+    Metrics.increment('jwt.refreshed')
+  end
+
+  c.on_revoke do |jti|
+    Audit.log('jwt.revoked', jti: jti)
+  end
+end
+```
+
+Callbacks fire only after a successful operation. Exceptions raised inside a callback are swallowed so they cannot break the calling JWT operation.
+
 ## API
 
 | Method | Description |
@@ -186,8 +223,13 @@ Philiprehberger::JwtKit.revocation_store = MyRedisRevocationStore.new
 | `JwtKit.revoke(token)` | Revokes a token by its JTI |
 | `JwtKit.revoked?(token)` | Checks if a token has been revoked |
 | `JwtKit.peek(token)` | Decode header and payload without signature verification |
+| `JwtKit.expired?(token)` | Check `exp` claim without verifying the signature |
 | `JwtKit.revocation_store=` | Set a custom revocation store |
 | `MemoryStore#cleanup!(max_age:)` | Remove revocation entries older than max_age seconds |
+| `Configuration#on_encode { \|token, payload\| ... }` | Register a callback fired after a successful encode |
+| `Configuration#on_decode { \|payload\| ... }` | Register a callback fired after a successful decode |
+| `Configuration#on_refresh { \|new_token\| ... }` | Register a callback fired after a successful refresh |
+| `Configuration#on_revoke { \|jti\| ... }` | Register a callback fired after a successful revoke |
 
 ## Development
 

data/lib/philiprehberger/jwt_kit/configuration.rb

@@ -41,6 +41,92 @@ module Philiprehberger
         @expiration = 3600
         @refresh_expiration = 86_400 * 7
         @secrets = nil
+        @on_encode = nil
+        @on_decode = nil
+        @on_refresh = nil
+        @on_revoke = nil
+      end
+
+      # Registers a callback fired after a successful encode.
+      #
+      # @yieldparam token [String] the encoded JWT token
+      # @yieldparam payload [Hash] the merged payload that was encoded
+      # @return [Proc] the stored callback
+      def on_encode(&block)
+        @on_encode = block
+      end
+
+      # Registers a callback fired after a successful decode.
+      #
+      # @yieldparam payload [Hash] the decoded payload
+      # @return [Proc] the stored callback
+      def on_decode(&block)
+        @on_decode = block
+      end
+
+      # Registers a callback fired after a successful refresh.
+      #
+      # @yieldparam new_token [String] the newly issued access token
+      # @return [Proc] the stored callback
+      def on_refresh(&block)
+        @on_refresh = block
+      end
+
+      # Registers a callback fired after a successful revoke.
+      #
+      # @yieldparam jti [String, nil] the revoked token's JTI
+      # @return [Proc] the stored callback
+      def on_revoke(&block)
+        @on_revoke = block
+      end
+
+      # Invokes the on_encode callback if registered. Errors raised by the callback are swallowed.
+      #
+      # @param token [String]
+      # @param payload [Hash]
+      # @return [void]
+      def fire_on_encode(token, payload)
+        return unless @on_encode
+
+        @on_encode.call(token, payload)
+      rescue StandardError
+        nil
+      end
+
+      # Invokes the on_decode callback if registered. Errors raised by the callback are swallowed.
+      #
+      # @param payload [Hash]
+      # @return [void]
+      def fire_on_decode(payload)
+        return unless @on_decode
+
+        @on_decode.call(payload)
+      rescue StandardError
+        nil
+      end
+
+      # Invokes the on_refresh callback if registered. Errors raised by the callback are swallowed.
+      #
+      # @param new_token [String]
+      # @return [void]
+      def fire_on_refresh(new_token)
+        return unless @on_refresh
+
+        @on_refresh.call(new_token)
+      rescue StandardError
+        nil
+      end
+
+      # Invokes the on_revoke callback if registered. Errors raised by the callback are swallowed.
+      #
+      # @param jti [String, nil]
+      # @return [void]
+      def fire_on_revoke(jti)
+        return unless @on_revoke
+
+        @on_revoke.call(jti)
+      rescue StandardError
+        nil
       end
 
       # Returns the OpenSSL digest algorithm name.

data/lib/philiprehberger/jwt_kit/decoder.rb

@@ -33,6 +33,7 @@ module Philiprehberger
         validate_issuer!(payload, config)
         validate_audience!(payload, config)
 
+        config.fire_on_decode(payload)
         payload
       rescue JSON::ParserError
         raise DecodeError, 'Invalid token: malformed JSON'

data/lib/philiprehberger/jwt_kit/encoder.rb

@@ -43,7 +43,9 @@ module Philiprehberger
         signing_input = "#{header_segment}.#{payload_segment}"
         signature = sign(signing_input, config, secret: signing_secret)
 
-        "#{signing_input}.#{signature}"
+        token = "#{signing_input}.#{signature}"
+        config.fire_on_encode(token, merged)
+        token
       end
 
       # Base64url-encodes a string without padding.

data/lib/philiprehberger/jwt_kit/revocation.rb

@@ -4,6 +4,20 @@ module Philiprehberger
   module JwtKit
     # Token revocation support with an in-memory store.
     module Revocation
+      # Extracts the JTI claim from a JWT token without verifying its signature.
+      #
+      # @param token [String] JWT token
+      # @return [String, nil] the JTI, or nil if the token is malformed
+      def self.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
+
       # Thread-safe in-memory revocation store backed by a Hash.
       class MemoryStore
         def initialize
@@ -60,13 +74,7 @@ module Philiprehberger
         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
+          Revocation.extract_jti(token)
         end
       end
     end

data/lib/philiprehberger/jwt_kit/token_pair.rb

@@ -34,7 +34,9 @@ module Philiprehberger
         raise InvalidToken, 'Token is not a refresh token' unless payload['type'] == 'refresh'
 
         new_payload = payload.except('exp', 'nbf', 'iat', 'jti', 'iss', 'aud', 'type')
-        Encoder.encode(new_payload, config)
+        new_token = Encoder.encode(new_payload, config)
+        config.fire_on_refresh(new_token)
+        new_token
       end
     end
   end

data/lib/philiprehberger/jwt_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module JwtKit
-    VERSION = '0.3.2'
+    VERSION = '0.5.0'
   end
 end

data/lib/philiprehberger/jwt_kit.rb

@@ -57,6 +57,22 @@ module Philiprehberger
         { valid: false, payload: nil, error: e.message }
       end
 
+      # Checks whether a token's `exp` claim is in the past without verifying the signature.
+      # Useful for proactive refresh decisions. Returns `true` for malformed tokens or when
+      # `exp` is missing.
+      #
+      # @param token [String] JWT token
+      # @return [Boolean]
+      def expired?(token)
+        payload = peek(token)[:payload]
+        exp = payload['exp']
+        return true unless exp.is_a?(Numeric)
+
+        Time.now.to_i >= exp
+      rescue DecodeError
+        true
+      end
+
       # Encodes a payload into a signed JWT token.
       #
       # @param payload [Hash] custom claims
@@ -109,6 +125,8 @@ module Philiprehberger
       # @return [void]
       def revoke(token)
         revocation_store.revoke(token)
+        jti = Revocation.extract_jti(token)
+        configuration.fire_on_revoke(jti)
       end
 
       # Checks whether a token has been revoked.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-jwt_kit
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-09 00:00:00.000000000 Z
+date: 2026-04-27 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