jwt_sessions 2.4.1 → 2.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d60c5dcae06e9f49ee1e99125baab8285156bd54eb5b36a3589001cee55acd6e
-  data.tar.gz: faa1cf67e08b8a320b525a918260dd4cf61f0aaf5f4ea1160f0e82ffff2e97b6
+  metadata.gz: 1ec082d39caff5259e52ca85c48a281d0673e7bb64c04d9033b241f99113c726
+  data.tar.gz: 6c8a90de8b2814bfe148d168706efee94f34e84b01412515d172b9807c7883cd
 SHA512:
-  metadata.gz: eb844adfe82415bc6126f5a32bceeb95234fbe8172ca427dbeaf7535bc4ae745cee3e33207b9e017c72098b8bf08b0d05cc302b952690568e5ca11fe12ad7629
-  data.tar.gz: 38b0299aa445d3a1558ed66e5a8d805850635065bf17d4de3d4f7f7b6c81a5962cac801bd79ae019209a8df96a4da64592897c6e45355e763b6220f5dfbed1af
+  metadata.gz: 433a7a5c8495505bc568641c9d733efaac8d626236ed3fa5484b3465800fcc1deac65fdb02c4d5c2261d725660fb176baf53d710952a9616296821b6852b1a7c
+  data.tar.gz: 4a5fdfbe4d0e20868544280c5245d8dfbb5a2eafa80940ff30f6572f88afcfd38383123b067e5adf5e9b1e199dd8d908b4660f4521637c789d6a1e06de2b3f1a

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+## 2.5.2 (July 06, 2020)
+
+Bugfixes:
+
+- fixed `Using the last argument as keyword parameters is deprecated;` warnings
+
+## 2.5.1 (April 20, 2020)
+
+Features:
+
+- added changelog
+
+Bugfixes:
+
+- fixed double exp key in payload
+
+Support:
+
+- moved decode error text to a constant within token class
+
+## 2.5.0 (April 12, 2020)
+
+Features:
+
+- added new error class `JWTSessions::Errors::Expired`
+
+## 2.4.3 (September 19, 2019)
+
+Bugfixes:
+
+- fixed lookup for refresh token for namespaced sessions
+
+Support:
+
+- updated sqlite to ~> 1.4 in `dummy_api`
+- added 2.6.3 Ruby to CI

data/README.md

@@ -8,50 +8,51 @@ XSS/CSRF safe JWT auth designed for SPA
 
 ## Table of Contents
 
-- [Synopsis](#synopsis)
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-  * [Creating a session](#creating-a-session)
-  * [Rails integration](#rails-integration)
-  * [Non-Rails usage](#non-rails-usage)
-- [Configuration](#configuration)
-    + [Token store](#token-store)
-    + [JWT signature](#jwt-signature)
-    + [Request headers and cookies names](#request-headers-and-cookies-names)
-    + [Expiration time](#expiration-time)
-    + [CSRF and cookies](#csrf-and-cookies)
-    + [Refresh with access token](#refresh-with-access-token)
-    + [Refresh token hijack protection](#refresh-token-hijack-protection)
-- [Flush Sessions](#flush-sessions)
-    + [Sessions Namespace](#sessions-namespace)
-    + [Logout](#logout)
-- [Examples](#examples)
-- [Contributing](#contributing)
-- [License](#license)
+  - [Synopsis](#synopsis)
+  - [Installation](#installation)
+  - [Getting Started](#getting-started)
+    - [Creating a session](#creating-a-session)
+    - [Rails integration](#rails-integration)
+    - [Non-Rails usage](#non-rails-usage)
+  - [Configuration](#configuration)
+      - [Token store](#token-store)
+      - [JWT signature](#jwt-signature)
+      - [Request headers and cookies names](#request-headers-and-cookies-names)
+      - [Expiration time](#expiration-time)
+      - [Exceptions](#exceptions)
+      - [CSRF and cookies](#csrf-and-cookies)
+        - [Refresh with access token](#refresh-with-access-token)
+      - [Refresh token hijack protection](#refresh-token-hijack-protection)
+  - [Flush Sessions](#flush-sessions)
+        - [Sessions namespace](#sessions-namespace)
+        - [Logout](#logout)
+  - [Examples](#examples)
+  - [Contributing](#contributing)
+  - [License](#license)
 
 ## Synopsis
 
-Main goal of this gem is to provide configurable, manageable, and safe stateful sessions based on JSON Web Tokens.
+The primary goal of this gem is to provide configurable, manageable, and safe stateful sessions based on JSON Web Tokens.
 
-The gem stores JWT based sessions on the backend (currently, redis and memory stores are supported), making it possible to manage sessions, reset passwords, logout users in a reliable and secure way.
+The gem stores JWT based sessions on the backend (currently, Redis and memory stores are supported), making it possible to manage sessions, reset passwords and logout users in a reliable and secure way.
 
-It's designed to be framework agnostic yet is easily integrable, and Rails integration is available out of the box.
+It is designed to be framework agnostic, yet easily integrable, and Rails integration is available out of the box.
 
-Core concept behind `jwt_sessions` is that each session is represented by a pair of tokens: access and refresh, and a session store is used to handle CSRF checks and refresh token hijacking. Both tokens have configurable expiration times, but in general refresh token is supposed to have a longer lifespan than an access token. Access token is used to retrieve secured resources and refresh token is used to renew the access token once it's expired. Default token store is based on redis.
+The core concept behind `jwt_sessions` is that each session is represented by a pair of tokens: `access` and `refresh`. The session store is used to handle CSRF checks and prevent refresh token hijacking. Both tokens have configurable expiration times but in general the refresh token is supposed to have a longer lifespan than the access token. The access token is used to retrieve secure resources and the refresh token is used to renew the access token once it has expired. The default token store uses Redis.
 
-All tokens are encoded and decoded by [ruby-jwt](https://github.com/jwt/ruby-jwt) gem, and its reserved claim names are supported as well as it's allowed to configure claim checks and cryptographic signing algorithms supported by it.
+All tokens are encoded and decoded by [ruby-jwt](https://github.com/jwt/ruby-jwt) gem. Its reserved claim names are supported and it can configure claim checks and cryptographic signing algorithms supported by it.
 `jwt_sessions` itself uses `ext` claim and `HS256` signing by default.
 
 
 ## Installation
 
-Put this line in your Gemfile
+Put this line in your Gemfile:
 
 ```ruby
 gem "jwt_sessions"
 ```
 
-Then run
+Then run:
 
 ```
 bundle install
@@ -59,18 +60,18 @@ bundle install
 
 ## Getting Started
 
-You should configure an encryption algorithm and specify the encryption key. By default the gem uses `HS256`.
+You should configure an encryption algorithm and specify the encryption key. By default the gem uses the `HS256` signing algorithm.
 
 ```ruby
 JWTSessions.encryption_key = "secret"
 ```
 
-`Authorization` mixin provides helper methods which are used to retrieve access and refresh tokens from incoming requests and verify CSRF token if needed. It assumes that a token can be found either in a cookie or in a header (cookie and header names are configurable). It tries to retrieve it from headers first, then from cookies (CSRF check included) if the headers check failed.
+`Authorization` mixin provides helper methods which are used to retrieve the access and refresh tokens from incoming requests and verify the CSRF token if needed. It assumes that a token can be found either in a cookie or in a header (cookie and header names are configurable). It tries to retrieve the token from headers first and then from cookies (CSRF check included) if the header check fails.
 
 ### Creating a session
 
 Each token contains a payload with custom session info. The payload is a regular Ruby hash. \
-Usually, it contains user ID or other data which helps to identify current user but it's not necessary, the payload can be an empty hash as well.
+Usually, it contains a user ID or other data which help identify the current user but the payload can be an empty hash as well.
 
 ```ruby
 > payload = { user_id: user.id }
@@ -84,7 +85,7 @@ Generate the session with a custom payload. By default the same payload is sewn
 => #<JWTSessions::Session:0x00007fbe2cce9ea0...>
 ```
 
-Sometimes it makes sense to keep different data within the payloads of access and refresh tokens. \
+Sometimes it makes sense to keep different data within the payloads of the access and refresh tokens. \
 The access token may contain rich data including user settings, etc., while the appropriate refresh token will include only the bare minimum which will be required to reconstruct a payload for the new access token during refresh.
 
 ```ruby
@@ -117,10 +118,10 @@ To perform the refresh do:
 Available `JWTSessions::Session.new` options:
 
 - **payload**: a hash object with session data which will be included into an access token payload. Default is an empty hash.
-- **refresh_payload**: a hash object with session data which will be included into a refresh token payload. Default is a value of the access payload.
-- **access_claims**: a hash object with [JWT claims](https://github.com/jwt/ruby-jwt#support-for-reserved-claim-names) which will be validated within the access token payload. F.e. `{ aud: ["admin"], verify_aud: true }` meaning that the token can be used only by "admin" audience. Also, the endpoint can automatically validate claims instead. See `token_claims` method.
+- **refresh_payload**: a hash object with session data which will be included into a refresh token payload. Default is the value of the access payload.
+- **access_claims**: a hash object with [JWT claims](https://github.com/jwt/ruby-jwt#support-for-reserved-claim-names) which will be validated within the access token payload. For example, `{ aud: ["admin"], verify_aud: true }` means that the token can be used only by "admin" audience. Also, the endpoint can automatically validate claims instead. See `token_claims` method.
 - **refresh_claims**: a hash object with [JWT claims](https://github.com/jwt/ruby-jwt#support-for-reserved-claim-names) which will be validated within the refresh token payload.
-- **namespace**: a string object which helps to group sessions by a custom criteria. For example, sessions can be grouped by user ID, then it'll be possible to logout the user from all devises. More info [Sessions Namespace](#sessions-namespace).
+- **namespace**: a string object which helps to group sessions by a custom criteria. For example, sessions can be grouped by user ID, making it possible to logout the user from all devices. More info [Sessions Namespace](#sessions-namespace).
 - **refresh_by_access_allowed**: a boolean value. Default is false. It links access and refresh tokens (adds refresh token ID to access payload), making it possible to perform a session refresh by the last expired access token. See [Refresh with access token](#refresh-with-access-token).
 - **access_exp**: an integer value. Contains an access token expiration time in seconds. The value overrides global settings. See [Expiration time](#expiration-time).
 - **refresh_exp**: an integer value. Contains a refresh token expiration time in seconds. The value overrides global settings. See [Expiration time](#expiration-time).
@@ -132,11 +133,11 @@ Helper methods within `Authorization` mixin:
 - **found_token**: a raw token found within the request.
 - **payload**: a decoded token's payload.
 - **claimless_payload**: a decoded token's payload without claims validation (can be used for checking data of an expired token).
-- **token_claims**: the method should be defined by a developer, and is expected to return a hash-like object with claims to be validated within a token's payload.
+- **token_claims**: the method should be defined by a developer and is expected to return a hash-like object with claims to be validated within a token's payload.
 
 ### Rails integration
 
-Include `JWTSessions::RailsAuthorization` in your controllers, add `JWTSessions::Errors::Unauthorized` exceptions handling if needed.
+Include `JWTSessions::RailsAuthorization` in your controllers and add `JWTSessions::Errors::Unauthorized` exception handling if needed.
 
 ```ruby
 class ApplicationController < ActionController::API
@@ -152,14 +153,14 @@ end
 ```
 
 Specify an encryption key for JSON Web Tokens in `config/initializers/jwt_session.rb` \
-It's adviced to store the key itself within the app secrets.
+It is advisable to store the key itself within the app secrets.
 
 ```ruby
 JWTSessions.algorithm = "HS256"
 JWTSessions.encryption_key = Rails.application.secrets.secret_jwt_encryption_key
 ```
 
-Most of the encryption algorithms require private and public keys to sign a token, yet HMAC only require a single key, so you can use a shortcat `encryption_key` to sign the token. For other algorithms you must specify a private and public keys separately.
+Most of the encryption algorithms require private and public keys to sign a token. However, HMAC requires only a single key and you can use the `encryption_key` shortcut to sign the token. For other algorithms you must specify private and public keys separately.
 
 ```ruby
 JWTSessions.algorithm   = "RS256"
@@ -167,10 +168,11 @@ JWTSessions.private_key = OpenSSL::PKey::RSA.generate(2048)
 JWTSessions.public_key  = JWTSessions.private_key.public_key
 ```
 
-You can build login controller to receive access, refresh and csrf tokens in exchange for user's login/password. \
-Refresh controller - to be able to get a new access token using refresh token after access is expired. \
-Here is example of a simple login controller, which returns set of tokens as a plain JSON response. \
-It's also possible to set tokens as cookies in the response instead.
+You can build a login controller to receive access, refresh and CSRF tokens in exchange for the user's login/password. \
+Refresh controller allows you to get a new access token using the refresh token after access is expired. \
+
+Here is an example of a simple login controller, which returns a set of tokens as a plain JSON response. \
+It is also possible to set tokens as cookies in the response instead.
 
 ```ruby
 class LoginController < ApplicationController
@@ -187,7 +189,7 @@ class LoginController < ApplicationController
 end
 ```
 
-Now you can build a refresh endpoint. To protect the endpoint use before_action `authorize_refresh_request!`. \
+Now you can build a refresh endpoint. To protect the endpoint use the before_action `authorize_refresh_request!`. \
 The endpoint itself should return a renewed access token.
 
 ```ruby
@@ -205,15 +207,16 @@ class RefreshController < ApplicationController
   end
 end
 ```
-In the example `found_token` - is a token fetched from request headers or cookies. In the context of `RefreshController` it's a refresh token. \
-The refresh request with headers must include `X-Refresh-Token` (header name is configurable) with refresh token.
+
+In the above example, `found_token` is a token fetched from request headers or cookies. In the context of `RefreshController` it is a refresh token. \
+The refresh request with headers must include `X-Refresh-Token` (header name is configurable) with the refresh token.
 
 ```
 X-Refresh-Token: eyJhbGciOiJIUzI1NiJ9...
 POST /refresh
 ```
 
-Now when there're login and refresh endpoints, you can protect the rest of your secure controllers with `before_action :authorize_access_request!`.
+When there are login and refresh endpoints, you can protect the rest of your secured controllers with `before_action :authorize_access_request!`.
 
 ```ruby
 class UsersController < ApplicationController
@@ -228,6 +231,7 @@ class UsersController < ApplicationController
   end
 end
 ```
+
 Headers must include `Authorization: Bearer` with access token.
 
 ```
@@ -244,7 +248,7 @@ end
 ```
 
 Methods `authorize_refresh_request!` and `authorize_access_request!` will always try to fetch the tokens from the headers first and then from the cookies.
-For the cases when an endpoint must support only one specific token transport the next auth methods can be used instead:
+For the cases when an endpoint must support only one specific token transport the following authorization methods can be used instead:
 
 ```ruby
 authorize_by_access_cookie!
@@ -255,7 +259,7 @@ authorize_by_refresh_header!
 
 ### Non-Rails usage
 
-You must include `JWTSessions::Authorization` module to your auth class and implement within it next methods:
+You must include `JWTSessions::Authorization` module to your auth class and within it implement the following methods:
 
 1. request_headers
 
@@ -282,7 +286,7 @@ end
 ```
 
 Example Sinatra app. \
-NOTE: Since rack updates HTTP headers by using `HTTP_` prefix, upcasing and using underscores for sake of simplicity JWTSessions tokens header names are converted to rack-style in this example.
+NOTE: Rack updates HTTP headers by using the `HTTP_` prefix, upcasing and underscores for the sake of simplicity. JWTSessions token header names are converted to the rack-style in this example.
 
 ```ruby
 require "sinatra/base"
@@ -344,9 +348,9 @@ List of configurable settings with their default values.
 
 ##### Token store
 
-In order to configure token store you should set up a store adapter in a following way: `JWTSessions.token_store = :redis, { redis_url: 'redis://127.0.0.1:6379/0' }` (options can be omitted). Currently supported stores are `:redis` and `:memory`. Please note, that if you want to use Redis as a store then you should have `redis` gem listed in your Gemfile. If you won't configure the adapter explicitly, this gem will try to load `redis` and use it, otherwise it would fallback to a `memory` adapter.
+In order to configure a token store you should set up a store adapter in a following way: `JWTSessions.token_store = :redis, { redis_url: 'redis://127.0.0.1:6379/0' }` (options can be omitted). Currently supported stores are `:redis` and `:memory`. Please note, that if you want to use Redis as a store then you should have `redis` gem listed in your Gemfile. If you do not configure the adapter explicitly, this gem will try to load `redis` and use it. Otherwise it will fall back to a `memory` adapter.
 
-Memory store accepts only `prefix` (used for redis db keys). Here is a default configuration for Redis:
+Memory store only accepts a `prefix` (used for Redis db keys). Here is a default configuration for Redis:
 
 ```ruby
 JWTSessions.token_store = :redis, {
@@ -371,7 +375,7 @@ JWTSessions.token_store = :redis, { redis_url: "redis://localhost:6397" }
 JWTSessions.algorithm = "HS256"
 ```
 
-You need to specify a secret to use for HMAC, this setting doesn"t have a default value.
+You need to specify a secret to use for HMAC as this setting does not have a default value.
 
 ```ruby
 JWTSessions.encryption_key = "secret"
@@ -384,9 +388,9 @@ JWTSessions.private_key = "abcd"
 JWTSessions.public_key  = "efjh"
 ```
 
-NOTE: ED25519 and HS512256 require rbnacl installation in order to make it work.
+NOTE: ED25519 and HS512256 require `rbnacl` installation in order to make it work.
 
-jwt_sessions only uses `exp` claim by default when it decodes tokens, you can specify which additional claims to use by
+jwt_sessions only uses `exp` claim by default when it decodes tokens and you can specify which additional claims to use by
 setting `jwt_options`. You can also specify leeway to account for clock skew.
 
 ```ruby
@@ -413,11 +417,11 @@ class UsersController < ApplicationController
 end
 ```
 
-Claims are also supported by `JWTSessions::Session`, you can pass `access_claims` and `refresh_claims` options in the initializer.
+Claims are also supported by `JWTSessions::Session` and you can pass `access_claims` and `refresh_claims` options in the initializer.
 
 ##### Request headers and cookies names
 
-Default request headers/cookies names can be re-configured
+Default request headers/cookies names can be reconfigured.
 
 ```ruby
 JWTSessions.access_header  = "Authorization"
@@ -429,19 +433,28 @@ JWTSessions.csrf_header    = "X-CSRF-Token"
 
 ##### Expiration time
 
-Access token must have a short life span, while refresh tokens can be stored for a longer time period
+Access token must have a short life span, while refresh tokens can be stored for a longer time period.
 
 ```ruby
 JWTSessions.access_exp_time = 3600 # 1 hour in seconds
 JWTSessions.refresh_exp_time = 604800 # 1 week in seconds
 ```
 
-It's defined globally, but can be overridden on a session level. See `JWTSessions::Session.new` options for more info.
+It is defined globally, but can be overridden on a session level. See `JWTSessions::Session.new` options for more info.
+
+##### Exceptions
+
+`JWTSessions::Errors::Error` - base class, all possible exceptions are inhereted from it. \
+`JWTSessions::Errors::Malconfigured` - some required gem settings are empty, or methods are not implemented. \
+`JWTSessions::Errors::InvalidPayload` - token's payload doesn't contain required keys or they are invalid. \
+`JWTSessions::Errors::Unauthorized` - token can't be decoded or JWT claims are invalid. \
+`JWTSessions::Errors::ClaimsVerification` - JWT claims are invalid (inherited from `JWTSessions::Errors::Unauthorized`). \
+`JWTSessions::Errors::Expired` - token is expired (inherited from `JWTSessions::Errors::ClaimsVerification`).
 
 #### CSRF and cookies
 
-In case when you use cookies as your tokens transport it gets vulnerable to CSRF. That's why both login and refresh methods of the `Session` class produce CSRF tokens for you. `Authorization` mixin expects that this token is sent with all requests except GET and HEAD in a header specified among this gem's settings (X-CSRF-Token by default). Verification will be done automatically and `Authorization` exception will be raised in case of mismatch between the token from the header and the one stored in session. \
-Although you don't need to mitigate BREACH attacks it's still possible to generate a new masked token with the access token.
+When you use cookies as your tokens transport it becomes vulnerable to CSRF. That is why both the login and refresh methods of the `Session` class produce CSRF tokens for you. `Authorization` mixin expects that this token is sent with all requests except GET and HEAD in a header specified among this gem's settings (`X-CSRF-Token` by default). Verification will be done automatically and the `Authorization` exception will be raised in case of a mismatch between the token from the header and the one stored in the session. \
+Although you do not need to mitigate BREACH attacks it is still possible to generate a new masked token with the access token.
 
 ```ruby
 session = JWTSessions::Session.new
@@ -450,10 +463,11 @@ session.masked_csrf(access_token)
 
 ##### Refresh with access token
 
-Sometimes it's not secure enough to store the refresh tokens in web / JS clients. \
-That's why you have a possibility to operate only by an access token, and to not pass the refresh to the client at all. \
-Session accepts `refresh_by_access_allowed: true` setting, which links the access token to the according refresh token. \
-Example Rails login controller, which passes an access token token via cookies and renders CSRF.
+Sometimes it is not secure enough to store the refresh tokens in web / JS clients. \
+This is why you have the option to only use an access token and to not pass the refresh token to the client at all. \
+Session accepts `refresh_by_access_allowed: true` setting, which links the access token to the corresponding refresh token.
+
+Example Rails login controller, which passes an access token token via cookies and renders CSRF:
 
 ```ruby
 class LoginController < ApplicationController
@@ -477,17 +491,29 @@ class LoginController < ApplicationController
 end
 ```
 
-The gem provides an ability to refresh the session by access token.
+The gem provides the ability to refresh the session by access token.
 
 ```ruby
 session = JWTSessions::Session.new(payload: payload, refresh_by_access_allowed: true)
 tokens  = session.refresh_by_access_payload
 ```
 
-In case of token forgery and successful refresh performed by an atacker - the original user will have to logout. \
-To protect the endpoint use before_action `authorize_refresh_by_access_request!`. \
-Example Rails refresh by access controller with cookies as token transport. \
-As refresh should be performed once the access token is already expired we need to use `claimless_payload` method in order to skip JWT expiration validation (and other claims) so we can proceed.
+In case of token forgery and successful refresh performed by an attacker the original user will have to logout. \
+To protect the endpoint use the before_action `authorize_refresh_by_access_request!`. \
+Refresh should be performed once the access token is already expired and we need to use the `claimless_payload` method in order to skip JWT expiration validation (and other claims) in order to proceed.
+
+Optionally `refresh_by_access_payload` accepts a block argument (the same way `refresh` method does).
+The block will be called if the refresh action is performed before the access token is expired.
+Thereby it's possible to prohibit users from making refresh calls while their access token is still active.
+
+```ruby
+tokens = session.refresh_by_access_payload do
+  # here goes malicious activity alert
+  raise JWTSessions::Errors::Unauthorized, "Refresh action is performed before the expiration of the access token."
+end
+```
+
+Example Rails refresh by access controller with cookies as token transport:
 
 ```ruby
 class RefreshController < ApplicationController
@@ -507,7 +533,7 @@ end
 
 ```
 
-For the cases when an endpoint must support only one specific token transport the next auth methods can be used instead:
+For the cases when an endpoint must support only one specific token transport the following auth methods can be used instead:
 
 ```ruby
 authorize_refresh_by_access_cookie!
@@ -516,8 +542,8 @@ authorize_refresh_by_access_header!
 
 #### Refresh token hijack protection
 
-There is a security recommendation regarding the usage of refresh tokens: only perform refresh when an access token gets expired. \
-Since sessions are always defined by a pair of tokens and there can't be multiple access tokens for a single refresh token simultaneous usage of the refresh token by multiple users can be easily noticed as refresh will be perfomed before the expiration of the access token by one of the users. Because of that `refresh` method of the `Session` class supports optional block as one of its arguments which will be executed only in case of refresh being performed before the expiration of the access token.
+There is a security recommendation regarding the usage of refresh tokens: only perform refresh when an access token expires. \
+Sessions are always defined by a pair of tokens and there cannot be multiple access tokens for a single refresh token. Simultaneous usage of the refresh token by multiple users can be easily noticed as refresh will be performed before the expiration of the access token by one of the users. As a result, `refresh` method of the `Session` class supports an optional block as one of its arguments which will be executed only in case of refresh being performed before the expiration of the access token.
 
 ```ruby
 session = JwtSessions::Session.new(payload: payload)
@@ -526,7 +552,7 @@ session.refresh(refresh_token) { |refresh_token_uid, access_token_expiration| ..
 
 ## Flush Sessions
 
-Flush a session by its refresh token. The method returns number of flushed sessions.
+Flush a session by its refresh token. The method returns number of flushed sessions:
 
 ```ruby
 session = JWTSessions::Session.new
@@ -534,7 +560,7 @@ tokens = session.login
 session.flush_by_token(tokens[:refresh]) # => 1
 ```
 
-Flush a session by its access token.
+Flush a session by its access token:
 
 ```ruby
 session = JWTSessions::Session.new(refresh_by_access_allowed: true)
@@ -545,7 +571,7 @@ session = JWTSessions::Session.new(refresh_by_access_allowed: true, payload: pay
 session.flush_by_access_payload
 ```
 
-Or by refresh token UID
+Or by refresh token UID:
 
 ```ruby
 session.flush_by_uid(uid) # => 1
@@ -553,27 +579,28 @@ session.flush_by_uid(uid) # => 1
 
 ##### Sessions namespace
 
-It's possible to group sessions by custom namespaces
+It's possible to group sessions by custom namespaces:
 
 ```ruby
 session = JWTSessions::Session.new(namespace: "account-1")
 ```
 
-and selectively flush sessions by namespace
+Selectively flush sessions by namespace:
 
 ```ruby
 session = JWTSessions::Session.new(namespace: "ie-sessions")
 session.flush_namespaced # will flush all sessions which belong to the same namespace
 ```
 
-it's posible to flush access tokens only
+Flush access tokens only:
 
 ```ruby
 session = JWTSessions::Session.new(namespace: "ie-sessions")
 session.flush_namespaced_access_tokens # will flush all access tokens which belong to the same namespace, but will keep refresh tokens
 ```
 
-To force flush of all app sessions
+Force flush of all app sessions:
+
 ```ruby
 JWTSessions::Session.flush_all
 ```
@@ -583,14 +610,14 @@ JWTSessions::Session.flush_all
 To logout you need to remove both access and refresh tokens from the store. \
 Flush sessions methods can be used to perform logout. \
 Refresh token or refresh token UID is required to flush a session. \
-To logout with an access token `refresh_by_access_allowed` setting should be set to true on an access token creation. If logout by access token is allowed it's recommended to ignore the expiration claim and to allow to logout with expired access token.
+To logout with an access token, `refresh_by_access_allowed` should be set to true on access token creation. If logout by access token is allowed it is recommended to ignore the expiration claim and to allow to logout with the expired access token.
 
 ## Examples
 
 [Rails API](test/support/dummy_api) \
 [Sinatra API](test/support/dummy_sinatra_api)
 
-You can use a mixed approach for the cases when you'd like to store an access token in localStorage and refresh token in HTTP-only secure cookies. \
+You can use a mixed approach for the cases when you would like to store an access token in localStorage and refresh token in HTTP-only secure cookies. \
 Rails controllers setup example:
 
 ```ruby

data/lib/jwt_sessions/errors.rb

@@ -5,5 +5,6 @@ module JWTSessions
     class InvalidPayload < Error; end
     class Unauthorized < Error; end
     class ClaimsVerification < Unauthorized; end
+    class Expired < ClaimsVerification; end
   end
 end

data/lib/jwt_sessions/refresh_token.rb

@@ -41,8 +41,10 @@ module JWTSessions
         end
       end
 
-      def find(uid, store, namespace = nil)
-        token_attrs = store.fetch_refresh(uid, namespace)
+      # first_match should be set to true when
+      # we need to search through the all namespaces
+      def find(uid, store, namespace = nil, first_match: false)
+        token_attrs = store.fetch_refresh(uid, namespace, first_match)
         raise Errors::Unauthorized, "Refresh token not found" if token_attrs.empty?
         build_with_token_attrs(store, uid, token_attrs, namespace)
       end

data/lib/jwt_sessions/session.rb

@@ -37,7 +37,7 @@ module JWTSessions
     end
 
     def session_exists?(token, token_type = :access)
-      send(:"#{token_type}_token_data", token)
+      send(:"#{token_type}_token_data", token, true)
       true
     rescue Errors::Unauthorized
       false
@@ -114,7 +114,7 @@ module JWTSessions
       ruid = retrieve_val_from(external_payload, :access, "ruid", "refresh uid")
       uid  = retrieve_val_from(external_payload, :access, "uid", "access uid")
 
-      refresh_token = RefreshToken.find(ruid, JWTSessions.token_store)
+      refresh_token = RefreshToken.find(ruid, JWTSessions.token_store, first_match: true)
       return false unless uid == refresh_token.access_uid
 
       CSRFToken.new(refresh_token.csrf).valid_authenticity_token?(external_csrf_token)
@@ -142,20 +142,20 @@ module JWTSessions
     end
 
     def refresh_csrf(refresh_token)
-      refresh_token_instance = refresh_token_data(refresh_token)
+      refresh_token_instance = refresh_token_data(refresh_token, true)
       CSRFToken.new(refresh_token_instance.csrf)
     end
 
-    def access_token_data(token)
+    def access_token_data(token, _first_match = false)
       uid = token_uid(token, :access, @access_claims)
       data = store.fetch_access(uid)
       raise Errors::Unauthorized, "Access token not found" if data.empty?
       data
     end
 
-    def refresh_token_data(token)
+    def refresh_token_data(token, first_match = false)
       uid = token_uid(token, :refresh, @refresh_claims)
-      retrieve_refresh_token(uid)
+      retrieve_refresh_token(uid, first_match: first_match)
     end
 
     def token_uid(token, type, claims)
@@ -177,8 +177,8 @@ module JWTSessions
       val
     end
 
-    def retrieve_refresh_token(uid)
-      @_refresh = RefreshToken.find(uid, store, namespace)
+    def retrieve_refresh_token(uid, first_match: false)
+      @_refresh = RefreshToken.find(uid, store, namespace, first_match: first_match)
     end
 
     def tokens_hash

data/lib/jwt_sessions/store_adapters.rb

@@ -9,7 +9,7 @@ module JWTSessions
     def self.build_by_name(adapter, options = nil)
       camelized_adapter = adapter.to_s.split('_').map(&:capitalize).join
       adapter_class_name = "#{camelized_adapter}StoreAdapter"
-      StoreAdapters.const_get(adapter_class_name).new(options || {})
+      StoreAdapters.const_get(adapter_class_name).new(**(options || {}))
     end
   end
 end

data/lib/jwt_sessions/store_adapters/abstract_store_adapter.rb

@@ -11,7 +11,8 @@ module JWTSessions
         raise NotImplementedError
       end
 
-      def fetch_refresh(_uid, _namespace)
+      # Set first_match to true to look up through all namespaces
+      def fetch_refresh(_uid, _namespace, _first_match)
         raise NotImplementedError
       end
 

data/lib/jwt_sessions/store_adapters/memory_store_adapter.rb

@@ -5,7 +5,7 @@ module JWTSessions
     class MemoryStoreAdapter < AbstractStoreAdapter
       attr_reader :storage
 
-      def initialize(options)
+      def initialize(**options)
         raise ArgumentError, "Memory store doesn't support any options" if options.any?
         @storage = Hash.new do |h, k|
           h[k] = Hash.new { |hh, kk| hh[kk] = {} }
@@ -22,8 +22,16 @@ module JWTSessions
         storage[""]["access"].store(uid, access_token)
       end
 
-      def fetch_refresh(uid, namespace)
-        value_if_not_expired(uid, "refresh", namespace.to_s)
+      def fetch_refresh(uid, namespace, first_match = false)
+        if first_match
+          storage.keys.each do |namespace_key|
+            val = value_if_not_expired(uid, "refresh", namespace_key)
+            return val unless val.empty?
+          end
+          {}
+        else
+          value_if_not_expired(uid, "refresh", namespace.to_s)
+        end
       end
 
       def persist_refresh(uid:, access_expiration:, access_uid:, csrf:, expiration:, namespace: "")

data/lib/jwt_sessions/store_adapters/redis_store_adapter.rb

@@ -12,7 +12,7 @@ module JWTSessions
 
         begin
           require "redis"
-          @storage = configure_redis_client(options)
+          @storage = configure_redis_client(**options)
         rescue LoadError => e
           msg = "Could not load the 'redis' gem, please add it to your gemfile or " \
                 "configure a different adapter (e.g. JWTSessions.store_adapter = :memory)"
@@ -31,8 +31,9 @@ module JWTSessions
         storage.expireat(key, expiration)
       end
 
-      def fetch_refresh(uid, namespace)
-        values = storage.hmget(refresh_key(uid, namespace), *REFRESH_KEYS).compact
+      def fetch_refresh(uid, namespace, first_match = false)
+        key    = first_match ? first_refresh_key(uid) : full_refresh_key(uid, namespace)
+        values = storage.hmget(key, *REFRESH_KEYS).compact
 
         return {} if values.length != REFRESH_KEYS.length
         REFRESH_KEYS.each_with_index.each_with_object({}) { |(key, index), acc| acc[key] = values[index] }
@@ -69,7 +70,8 @@ module JWTSessions
       end
 
       def destroy_refresh(uid, namespace)
-        storage.del(refresh_key(uid, namespace))
+        key = full_refresh_key(uid, namespace)
+        storage.del(key)
       end
 
       def destroy_access(uid)
@@ -107,16 +109,14 @@ module JWTSessions
         "#{prefix}_#{namespace}_refresh_#{uid}"
       end
 
-      def refresh_key(uid, namespace)
-        if namespace.to_s.empty?
-          wildcard_refresh_key(uid)
-        else
-          full_refresh_key(uid, namespace)
-        end
+      def first_refresh_key(uid)
+        key = full_refresh_key(uid, "*")
+        (storage.keys(key) || []).first
       end
 
-      def wildcard_refresh_key(uid)
-        (storage.keys(refresh_key(uid, "*")) || []).first
+      def refresh_key(uid, namespace)
+        namespace = "*" if namespace.to_s.empty?
+        full_refresh_key(uid, namespace)
       end
 
       def access_key(uid)

data/lib/jwt_sessions/token.rb

@@ -4,6 +4,8 @@ require "jwt"
 
 module JWTSessions
   class Token
+    DECODE_ERROR = "cannot decode the token"
+
     class << self
       def encode(payload)
         exp_payload = meta.merge(payload)
@@ -13,23 +15,25 @@ module JWTSessions
       def decode(token, claims = {})
         decode_options = { algorithm: JWTSessions.algorithm }.merge(JWTSessions.jwt_options.to_h).merge(claims)
         JWT.decode(token, JWTSessions.public_key, JWTSessions.validate?, decode_options)
-      rescue JWT::InvalidIssuerError, JWT::InvalidIatError, JWT::InvalidAudError, JWT::InvalidSubError, JWT::InvalidJtiError, JWT::ExpiredSignature => e
+      rescue JWT::ExpiredSignature => e
+        raise Errors::Expired, e.message
+      rescue JWT::InvalidIssuerError, JWT::InvalidIatError, JWT::InvalidAudError, JWT::InvalidSubError, JWT::InvalidJtiError => e
         raise Errors::ClaimsVerification, e.message
       rescue JWT::DecodeError => e
         raise Errors::Unauthorized, e.message
       rescue StandardError
-        raise Errors::Unauthorized, "could not decode a token"
+        raise Errors::Unauthorized, DECODE_ERROR
       end
 
       def decode!(token)
         decode_options = { algorithm: JWTSessions.algorithm }
         JWT.decode(token, JWTSessions.public_key, false, decode_options)
       rescue StandardError
-        raise Errors::Unauthorized, "could not decode a token"
+        raise Errors::Unauthorized, DECODE_ERROR
       end
 
       def meta
-        { exp: JWTSessions.access_expiration }
+        { "exp" => JWTSessions.access_expiration }
       end
     end
   end

data/lib/jwt_sessions/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JWTSessions
-  VERSION = "2.4.1"
+  VERSION = "2.5.2"
 end

data/test/units/jwt_sessions/test_refresh_token.rb

@@ -7,6 +7,8 @@ class TestRefreshToken < Minitest::Test
    attr_reader :csrf, :token, :access_uid
 
   def setup
+    JWTSessions::Session.flush_all
+
     JWTSessions.encryption_key = "secure encryption"
     @access_uid = SecureRandom.uuid
     @csrf = JWTSessions::CSRFToken.new
@@ -39,4 +41,18 @@ class TestRefreshToken < Minitest::Test
       JWTSessions::RefreshToken.find(token.uid, JWTSessions.token_store, nil)
     end
   end
+
+  def test_all
+    access_uid_2 = SecureRandom.uuid
+    csrf_2       = JWTSessions::CSRFToken.new
+    token_2      = JWTSessions::RefreshToken.create(
+      csrf_2.encoded,
+      access_uid_2,
+      JWTSessions.access_expiration - 5,
+      JWTSessions.token_store,
+      {},
+      nil
+    )
+    assert_equal [token.token, token_2.token].sort, JWTSessions::RefreshToken.all(nil, JWTSessions.token_store).map(&:token).sort
+  end
 end

data/test/units/jwt_sessions/test_session.rb

@@ -69,6 +69,18 @@ class TestSession < Minitest::Test
     end
   end
 
+  def test_refresh_with_namespace
+    @new_session = JWTSessions::Session.new(
+      payload: payload,
+      namespace: "custom-namespace"
+    )
+    new_tokens = @new_session.login
+    refreshed_tokens = @new_session.refresh(new_tokens[:refresh])
+    decoded_access = JWTSessions::Token.decode(refreshed_tokens[:access]).first
+    assert_equal REFRESH_KEYS, refreshed_tokens.keys.sort
+    assert_equal payload[:test], decoded_access["test"]
+  end
+
   def test_refresh_by_access_payload
     session = JWTSessions::Session.new(payload: payload, refresh_by_access_allowed: true)
     session.login
@@ -296,7 +308,7 @@ class TestSession < Minitest::Test
 
     session.flush_namespaced_access_tokens
     ruid = session.instance_variable_get(:"@_refresh").uid
-    refresh_token = JWTSessions::RefreshToken.find(ruid, JWTSessions.token_store, nil)
+    refresh_token = JWTSessions::RefreshToken.find(ruid, JWTSessions.token_store, namespace)
     assert_equal "", refresh_token.access_uid
     assert_equal "", refresh_token.access_expiration
 
@@ -306,7 +318,7 @@ class TestSession < Minitest::Test
     end
     auid = session.instance_variable_get(:"@_access").uid
     access_token = JWTSessions::AccessToken.find(auid, JWTSessions.token_store)
-    refresh_token = JWTSessions::RefreshToken.find(ruid, JWTSessions.token_store, nil)
+    refresh_token = JWTSessions::RefreshToken.find(ruid, JWTSessions.token_store, namespace)
 
     assert_equal false, access_token.uid.size.zero?
     assert_equal false, access_token.expiration.size.zero?

data/test/units/jwt_sessions/test_token.rb

@@ -110,11 +110,11 @@ class TestToken < Minitest::Test
   def test_token_leeway_decode
     JWTSessions.encryption_key = "abcdefghijklmnopqrstuvwxyzABCDEF"
     JWTSessions.jwt_options.leeway = 50
-    token   = JWTSessions::Token.encode(payload.merge(exp: Time.now.to_i - 20))
+    token   = JWTSessions::Token.encode(payload.merge("exp" => Time.now.to_i - 20))
     decoded = JWTSessions::Token.decode(token).first
     assert_equal payload["user_id"], decoded["user_id"]
     assert_equal payload["secret"], decoded["secret"]
-    token   = JWTSessions::Token.encode(payload.merge(exp: Time.now.to_i - 100))
+    token   = JWTSessions::Token.encode(payload.merge("exp" => Time.now.to_i - 100))
     assert_raises JWTSessions::Errors::Unauthorized do
       JWTSessions::Token.decode(token)
     end
@@ -141,8 +141,8 @@ class TestToken < Minitest::Test
   end
 
   def test_payload_exp_time
-    token = JWTSessions::Token.encode(payload.merge(exp: Time.now.to_i - (3600 * 24)))
-    assert_raises JWTSessions::Errors::Unauthorized do
+    token = JWTSessions::Token.encode(payload.merge("exp" => Time.now.to_i - (3600 * 24)))
+    assert_raises JWTSessions::Errors::Expired do
       JWTSessions::Token.decode(token)
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jwt_sessions
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.2
 platform: ruby
 authors:
 - Yulia Oletskaya
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-25 00:00:00.000000000 Z
+date: 2020-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -92,6 +92,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/jwt_sessions.rb
@@ -120,7 +121,11 @@ files:
 homepage: http://rubygems.org/gems/jwt_sessions
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/tuwukee/jwt_sessions
+  changelog_uri: https://github.com/tuwukee/jwt_sessions/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/tuwukee/jwt_sessions
+  bug_tracker_uri: https://github.com/tuwukee/jwt_sessions/issues
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -136,18 +141,17 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: JWT Sessions
 test_files:
 - test/units/test_jwt_sessions.rb
 - test/units/test_token_store.rb
-- test/units/jwt_sessions/store_adapters/test_memory_store_adapter.rb
-- test/units/jwt_sessions/store_adapters/test_redis_store_adapter.rb
-- test/units/jwt_sessions/test_access_token.rb
 - test/units/jwt_sessions/test_csrf_token.rb
+- test/units/jwt_sessions/test_access_token.rb
+- test/units/jwt_sessions/store_adapters/test_redis_store_adapter.rb
+- test/units/jwt_sessions/store_adapters/test_memory_store_adapter.rb
+- test/units/jwt_sessions/test_token.rb
 - test/units/jwt_sessions/test_refresh_token.rb
 - test/units/jwt_sessions/test_session.rb
-- test/units/jwt_sessions/test_token.rb