Module: Philiprehberger::JwtKit

Defined in:
lib/philiprehberger/jwt_kit.rb,
lib/philiprehberger/jwt_kit/decoder.rb,
lib/philiprehberger/jwt_kit/encoder.rb,
lib/philiprehberger/jwt_kit/version.rb,
lib/philiprehberger/jwt_kit/revocation.rb,
lib/philiprehberger/jwt_kit/token_pair.rb,
lib/philiprehberger/jwt_kit/configuration.rb

Defined Under Namespace

Modules: Decoder, Encoder, Revocation, TokenPair Classes: Configuration, DecodeError, Error, InvalidAudience, InvalidIssuer, InvalidSignature, InvalidToken, RevokedToken, TokenExpired, TokenNotYetValid

Constant Summary collapse

VERSION = 
'0.6.0'

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.revocation_store ⇒ #revoke, ...

Returns the revocation store.

Returns:

  • (#revoke, #revoked?, #clear, #size) 


160
161
162
 
# File 'lib/philiprehberger/jwt_kit.rb', line 160

def revocation_store
  @revocation_store ||= Revocation::MemoryStore.new
end

Class Method Details

.configuration ⇒ Configuration

Returns the current configuration.

Returns:



38
39
40
 
# File 'lib/philiprehberger/jwt_kit.rb', line 38

def configuration
  @configuration ||= Configuration.new
end

.configure {|config| ... } ⇒ void

This method returns an undefined value.

Configures JwtKit using a block.

Yield Parameters:



31
32
33
 
# File 'lib/philiprehberger/jwt_kit.rb', line 31

def configure
  yield(configuration)
end

.decode(token) ⇒ Hash

Decodes a JWT token and validates its claims.

Parameters:

  • token (String) —

    JWT token

Returns:

  • (Hash) —

    decoded payload

Raises:



106
107
108
109
110
111
 
# File 'lib/philiprehberger/jwt_kit.rb', line 106

def decode(token)
  payload = Decoder.decode(token, configuration)
  raise RevokedToken, 'Token has been revoked' if revocation_store.revoked?(token)

  payload
end

.encode(payload = {}) ⇒ String

Encodes a payload into a signed JWT token.

Parameters:

  • payload (Hash) (defaults to: {}) —

    custom claims

Returns:

  • (String) —

    signed JWT token



97
98
99
 
# File 'lib/philiprehberger/jwt_kit.rb', line 97

def encode(payload = {})
  Encoder.encode(payload, configuration)
end

.expired?(token) ⇒ Boolean

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.

Parameters:

  • token (String) —

    JWT token

Returns:

  • (Boolean) 


66
67
68
69
70
71
72
73
74
 
# File 'lib/philiprehberger/jwt_kit.rb', line 66

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

.peek(token) ⇒ Hash

Decodes a JWT token WITHOUT verifying the signature. Useful for inspecting the header and payload before choosing a key.

Parameters:

  • token (String) —

    JWT token

Returns:

  • (Hash) —

    with :header and :payload keys

Raises:



119
120
121
 
# File 'lib/philiprehberger/jwt_kit.rb', line 119

def peek(token)
  Decoder.peek(token)
end

.refresh(refresh_token) ⇒ String

Generates a new access token from a refresh token.

Parameters:

  • refresh_token (String) —

    valid refresh token

Returns:

  • (String) —

    new access token



135
136
137
 
# File 'lib/philiprehberger/jwt_kit.rb', line 135

def refresh(refresh_token)
  TokenPair.refresh(refresh_token, configuration)
end

.reset_configuration! ⇒ Configuration

Resets the configuration to defaults.

Returns:



45
46
47
 
# File 'lib/philiprehberger/jwt_kit.rb', line 45

def reset_configuration!
  @configuration = Configuration.new
end

.reset_revocation_store! ⇒ Revocation::MemoryStore

Resets the revocation store to the default MemoryStore.

Returns:



173
174
175
 
# File 'lib/philiprehberger/jwt_kit.rb', line 173

def reset_revocation_store!
  @revocation_store = Revocation::MemoryStore.new
end

.revoke(token) ⇒ void

This method returns an undefined value.

Revokes a token.

Parameters:

  • token (String) —

    JWT token to revoke



143
144
145
146
147
 
# File 'lib/philiprehberger/jwt_kit.rb', line 143

def revoke(token)
  revocation_store.revoke(token)
  jti = Revocation.extract_jti(token)
  configuration.fire_on_revoke(jti)
end

.revoked?(token) ⇒ Boolean

Checks whether a token has been revoked.

Parameters:

  • token (String) —

    JWT token

Returns:

  • (Boolean) 


153
154
155
 
# File 'lib/philiprehberger/jwt_kit.rb', line 153

def revoked?(token)
  revocation_store.revoked?(token)
end

.time_to_expiry(token) ⇒ Integer?

Seconds remaining until a token’s ‘exp` claim. Does not verify the signature. Returns a negative integer for already-expired tokens and `nil` for malformed tokens or tokens without a numeric `exp` claim. Useful for scheduling a refresh before expiration rather than after.

Parameters:

  • token (String) —

    JWT token

Returns:

  • (Integer, nil) —

    seconds remaining, or nil when undeterminable



83
84
85
86
87
88
89
90
91
 
# File 'lib/philiprehberger/jwt_kit.rb', line 83

def time_to_expiry(token)
  payload = peek(token)[:payload]
  exp = payload['exp']
  return nil unless exp.is_a?(Numeric)

  exp.to_i - Time.now.to_i
rescue DecodeError
  nil
end

.token_pair(payload = {}) ⇒ Array<String>

Generates an access/refresh token pair.

Parameters:

  • payload (Hash) (defaults to: {}) —

    custom claims

Returns:

  • (Array<String>) —

    ‘[access_token, refresh_token]`



127
128
129
 
# File 'lib/philiprehberger/jwt_kit.rb', line 127

def token_pair(payload = {})
  TokenPair.generate(payload, configuration)
end

.validate(token) ⇒ Hash

Validates a token and returns a result hash instead of raising.

Parameters:

  • token (String) —

    JWT token

Returns:

  • (Hash) —

    { valid: Boolean, payload: Hash or nil, error: String or nil }



53
54
55
56
57
58
 
# File 'lib/philiprehberger/jwt_kit.rb', line 53

def validate(token)
  payload = decode(token)
  { valid: true, payload: payload, error: nil }
rescue DecodeError, RevokedToken => e
  { valid: false, payload: nil, error: e.message }
end