Module: Securial::Auth::AuthEncoder

Extended by:
AuthEncoder
Included in:
AuthEncoder
Defined in:
lib/securial/auth/auth_encoder.rb

Overview

Handles JWT token encoding and decoding for session authentication.

This module provides methods to securely encode session information into JWT tokens and decode/validate those tokens. It uses HMAC signing with a configurable secret and includes standard JWT claims for security.

The tokens include:

  • Session ID (jti claim) for session lookup

  • Expiration time (exp claim) for automatic invalidation

  • Subject (sub claim) identifying the token type

  • Custom claims for IP address and user agent validation

See Also:

Instance Method Summary collapse

Instance Method Details

#algorithm ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the algorithm used for JWT signing.

Returns:

  • (String) —

    The configured session algorithm in uppercase



119
120
121
 
# File 'lib/securial/auth/auth_encoder.rb', line 119

def algorithm
  Securial.configuration.session_algorithm.to_s.upcase
end

#decode(token) ⇒ Hash

Decodes and validates a JWT token, returning the payload.

Verifies the token signature, expiration, and other claims before returning the decoded payload. The token must have been signed with the current secret and must not be expired.

Examples:

payload = AuthEncoder.decode("eyJhbGciOiJIUzI1NiJ9...")
session_id = payload['jti']
ip_address = payload['ip']
user_agent = payload['agent']

Parameters:

  • token (String) —

    The JWT token to decode and validate

Returns:

  • (Hash) —

    The decoded token payload containing session information

Raises:



94
95
96
97
98
99
100
101
 
# File 'lib/securial/auth/auth_encoder.rb', line 94

def decode(token)
  begin
    decoded = ::JWT.decode(token, secret, true, { algorithm: algorithm, verify_jti: true, iss: "securial" })
  rescue JWT::DecodeError
    raise Securial::Error::Auth::TokenDecodeError
  end
  decoded.first
end

#encode(session) ⇒ String?

Encodes a session object into a signed JWT token.

Creates a JWT token containing the session ID and metadata for later validation. The token is signed using the configured secret and algorithm.

Examples:

session = Securial::Session.create!(user: current_user)
token = AuthEncoder.encode(session)
# => "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxMjM0NTY3ODkw..."

Parameters:

Returns:

  • (String, nil) —

    The encoded JWT token, or nil if session is invalid

Raises:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/securial/auth/auth_encoder.rb', line 56

def encode(session)
  return nil unless session && session.class == Securial::Session

  base_payload = {
    jti: session.id,
    exp: expiry_duration.from_now.to_i,
    sub: "session-access-token",
    refresh_count: session.refresh_count,
  }

  session_payload = {
    ip: session.ip_address,
    agent: session.user_agent,
  }

  payload = base_payload.merge(session_payload)
  begin
    ::JWT.encode(payload, secret, algorithm, { kid: "hmac" })
  rescue JWT::EncodeError
    raise Securial::Error::Auth::TokenEncodeError
  end
end

#expiry_duration ⇒ ActiveSupport::Duration (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the token expiration duration.

Returns:

  • (ActiveSupport::Duration) —

    The configured session expiration duration



128
129
130
 
# File 'lib/securial/auth/auth_encoder.rb', line 128

def expiry_duration
  Securial.configuration.session_expiration_duration
end

#secret ⇒ String (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the secret key used for JWT signing and verification.

Returns:

  • (String) —

    The configured session secret



110
111
112
 
# File 'lib/securial/auth/auth_encoder.rb', line 110

def secret
  Securial.configuration.session_secret
end