token.rb in jwt_keeper-3.1.0

- old
+ new

@@ -1,11 +1,15 @@
 module JWTKeeper
+  # This class acts as the main interface to wrap the concerns of JWTs. Handling everything from
+  # encoding to invalidation.
   class Token
     attr_accessor :claims, :cookie_secret
 
     # Initalizes a new web token
     # @param private_claims [Hash] the custom claims to encode
+    # @param cookie_secret [String] the cookie secret to use during encoding
+    # @return [void]
     def initialize(private_claims = {}, cookie_secret = nil)
       @cookie_secret = cookie_secret
       @claims = {
         nbf: DateTime.now.to_i, # not before
         iat: DateTime.now.to_i, # issued at
@@ -23,10 +27,11 @@
       new(private_claims, cookie_secret)
     end
 
     # Decodes and validates an existing token
     # @param raw_token [String] the raw token
+    # @param cookie_secret [String] the cookie secret
     # @return [Token] token object
     def self.find(raw_token, cookie_secret = nil)
       claims = decode(raw_token, cookie_secret)
       return nil if claims.nil?
 
@@ -37,16 +42,18 @@
 
     # Sets a token to the pending rotation state. The expire is set to the maxium possible time but
     # is inherently ignored by the token's exp check and then rewritten with the revokation on
     # rotate.
     # @param token_jti [String] the token unique id
+    # @return [void]
     def self.rotate(token_jti)
       Datastore.rotate(token_jti, JWTKeeper.configuration.expiry.from_now.to_i)
     end
 
     # Revokes a web token
     # @param token_jti [String] the token unique id
+    # @return [void]
     def self.revoke(token_jti)
       Datastore.revoke(token_jti, JWTKeeper.configuration.expiry.from_now.to_i)
     end
 
     # Easy interface for using the token's id
@@ -55,11 +62,11 @@
       claims[:jti]
     end
 
     # Revokes and creates a new web token
     # @param new_claims [Hash] Used to override and update claims during rotation
-    # @return [String] new token
+    # @return [Token]
     def rotate(new_claims = nil)
       revoke
 
       new_claims ||= claims.except(:iss, :aud, :exp, :nbf, :iat, :jti)
       new_token = self.class.create(new_claims)
@@ -68,10 +75,11 @@
       @cookie_secret = new_token.cookie_secret
       self
     end
 
     # Revokes a web token
+    # @return [void]
     def revoke
       return if invalid?
       Datastore.revoke(id, claims[:exp] - DateTime.now.to_i)
     end
 
@@ -104,17 +112,17 @@
     def invalid?
       self.class.decode(encode, cookie_secret).nil? || revoked?
     end
 
     # Encodes the jwt
-    # @return [String]
+    # @return [String] the encoded jwt
     def to_jwt
       encode
     end
     alias to_s to_jwt
 
     # Encodes the cookie
-    # @return [Hash]
+    # @return [Hash] the cookie options
     def to_cookie
       {
         value: cookie_secret,
         expires: Time.at(claims[:exp])
       }.merge(JWTKeeper.configuration.cookie_options)