docs: add token family feature documentation

- Included token_family app in conf.py
- Added family_app.rst for token family details
- Documented related family settings in settings.rst
- Linked family_app in index.rst toctree

Author: juanbailon

docs/conf.py

@@ -34,6 +34,7 @@ def django_configure():
             "rest_framework",
             "rest_framework_simplejwt",
             "rest_framework_simplejwt.token_blacklist",
+            "rest_framework_simplejwt.token_family",
         ),
     )
 

docs/family_app.rst

@@ -0,0 +1,116 @@
+.. _family_app:
+
+Family app
+===========
+
+The **Token Family** system provides a way to group refresh and access tokens into logical families,
+allowing developers to track, manage, and invalidate related tokens as a unit.
+
+This feature is especially useful in enhancing security and traceability in authentication flows.
+Each token family is identified by a unique ``family_id``, which is included in the token payload.
+This enables the system to:
+
+- Detect and respond to refresh token reuse by invalidating the entire token family.
+- Revoke all related tokens at once.
+- Enforce expiration policies at the family level via a ``family_exp`` claim.
+
+A new token family is automatically created every time a user successfully obtains a pair of tokens
+from the ``TokenObtainPairView`` (i.e., when starting a new session). From that point onward, as long as the user
+continues to refresh their tokens, the newly issued access and refresh tokens will retain the same
+``family_id`` and ``family_exp`` values. This means all tokens issued as part of a session are 
+considered to belong to the same token family.
+
+This session-based grouping allows administrators or systems to treat the token family as the unit of trust.
+If suspicious activity is detected, the entire session can be invalidated at once by blacklisting the
+associated token family.
+
+The Token Family system is optional and customizable. It works best when paired with the
+:doc:`/blacklist_app`.
+
+By organizing tokens into families, you gain finer control over user sessions and potential compromises.
+For example, when the settings ``BLACKLIST_AFTER_ROTATION`` and ``TOKEN_FAMILY_BLACKLIST_ON_REUSE`` are
+set to ``True``, if a refresh token is stolen and used by both the valid user and the attacker,
+the system will detect the reuse of the token and automatically blacklist the associated family. 
+This invalidates every token that shares the same ``family_id`` as the reused refresh token, effectively
+cutting off access without waiting for individual token expiration.
+
+-------
+
+Simple JWT includes an app that provides token family functionality.  To use
+this app, include it in your list of installed apps in ``settings.py``:
+
+.. code-block:: python
+
+  # Django project settings.py
+
+  ...
+
+  INSTALLED_APPS = (
+      ...
+      'rest_framework_simplejwt.token_family',
+      ...
+  )
+
+Also, make sure to run ``python manage.py migrate`` to run the app's
+migrations.
+
+If the token family app is detected in ``INSTALLED_APPS`` and the setting
+``TOKEN_FAMILY_ENABLED`` is set to ``True``, Simple JWT will add a new family
+to the family list and will also add two new claims, "family_id" and 
+"family_exp", to the refresh tokens. It will also check that the
+family indicated in the token's payload does not appear in a blacklist of
+families before it considers it as valid, and it will also check that the
+family expiration date ("family_exp") has not passed; if the family is expired,
+then the token will be considered as invalid.
+
+The Simple JWT family app implements its family and blacklisted family
+lists using two models: ``TokenFamily`` and ``BlacklistedTokenFamily``.  Model
+admins are defined for both of these models.  To add a family to the blacklist,
+find its corresponding ``TokenFamily`` record in the admin and use the
+admin again to create a ``BlacklistedTokenFamily`` record that points to the
+``TokenFamily`` record.
+
+Alternatively, you can blacklist a family by creating a ``FamilyMixin``
+subclass instance and calling the instance's ``blacklist_family`` method:
+
+.. code-block:: python
+
+  from rest_framework_simplejwt.tokens import RefreshToken
+
+  token = RefreshToken(base64_encoded_token_string)
+  token.blacklist_family()
+
+Keep in mind that the ``base64_encoded_token_string`` should already
+contain a family ID claim in its payload.
+
+This will create a unique family and blacklist records for the token's
+"family_id" claim or whichever claim is specified by the ``TOKEN_FAMILY_CLAIM`` setting.
+
+
+In a ``urls.py`` file, you can also include a route for ``TokenFamilyBlacklistView``:
+
+.. code-block:: python
+
+  from rest_framework_simplejwt.views import TokenFamilyBlacklistView
+
+  urlpatterns = [
+    ...
+    path('api/token/family/blacklist/', TokenFamilyBlacklistView.as_view(), name='token_family_blacklist'),
+    ...
+  ]
+
+It allows API users to blacklist token families sending them to ``/api/token/family/blacklist/``, for example using curl:
+
+.. code-block:: bash
+
+  curl \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -d '{"refresh":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTc0NzI0OTU1MywiaWF0IjoxNzQ3MjQ0MTUzLCJqdGkiOiI1YmMzMjlmMjVkODE0OGFhOTY1ODI1YjgwNDQ1ZDQ5OCIsInVzZXJfaWQiOjIsImZhbWlseV9pZCI6ImMyZGYyM2M1YjU1NjRmYjNhNTA3MjFhYzVkMTljNThmIiwiZmFtaWx5X2V4cCI6MTc0NzI0OTE1M30.4oDOmtkgot_W2mXByKuCyJLi6_xeMZtDQJmHIBXZx98"}' \
+    http://localhost:8000/api/token/family/blacklist/
+
+The family app also provides a management command, ``flushexpiredfamilies``,
+which will delete any families from the token family list and family blacklist that have
+expired. The command will not affect families that have ``None`` as their expiration.
+You should set up a cron job on your server or hosting platform which
+runs this command daily.

docs/index.rst

@@ -51,6 +51,7 @@ Contents
     creating_tokens_manually
     token_types
     blacklist_app
+    family_app
     stateless_user_authentication
     development_and_contributing
     drf_yasg_integration

docs/settings.rst

@@ -20,6 +20,11 @@ Some of Simple JWT's behavior can be customized through settings variables in
       "BLACKLIST_AFTER_ROTATION": False,
       "UPDATE_LAST_LOGIN": False,
 
+      "TOKEN_FAMILY_ENABLED": False,
+      "TOKEN_FAMILY_LIFETIME": timedelta(days=30),
+      "TOKEN_FAMILY_CHECK_ON_ACCESS": False,
+      "TOKEN_FAMILY_BLACKLIST_ON_REUSE": False,
+
       "ALGORITHM": "HS256",
       "SIGNING_KEY": settings.SECRET_KEY,
       "VERIFYING_KEY": "",
@@ -43,6 +48,9 @@ Some of Simple JWT's behavior can be customized through settings variables in
 
       "JTI_CLAIM": "jti", 
 
+      "TOKEN_FAMILY_CLAIM": "family_id",
+      "TOKEN_FAMILY_EXPIRATION_CLAIM": "family_exp",
+
       "SLIDING_TOKEN_REFRESH_EXP_CLAIM": "refresh_exp",
       "SLIDING_TOKEN_LIFETIME": timedelta(minutes=5),
       "SLIDING_TOKEN_REFRESH_LIFETIME": timedelta(days=1),
@@ -53,6 +61,7 @@ Some of Simple JWT's behavior can be customized through settings variables in
       "TOKEN_BLACKLIST_SERIALIZER": "rest_framework_simplejwt.serializers.TokenBlacklistSerializer",
       "SLIDING_TOKEN_OBTAIN_SERIALIZER": "rest_framework_simplejwt.serializers.TokenObtainSlidingSerializer",
       "SLIDING_TOKEN_REFRESH_SERIALIZER": "rest_framework_simplejwt.serializers.TokenRefreshSlidingSerializer",
+      "TOKEN_FAMILY_BLACKLIST_SERIALIZER": "rest_framework_simplejwt.serializers.TokenFamilyBlacklistSerializer",
   }
 
 Above, the default values for these settings are shown.
@@ -105,6 +114,46 @@ login (TokenObtainPairView).
     a security vulnerability. If you really want this, throttle the endpoint with
     DRF at the very least.
 
+``TOKEN_FAMILY_ENABLED``
+----------------------------
+
+When set to ``True``, enables the Token Family tracking system. This allows
+refresh tokens to be grouped into families using a shared identifier. By default,
+this identifier is only included in refresh tokens, but it can also be added to
+access tokens if ``TOKEN_FAMILY_CHECK_ON_ACCESS`` is set to ``True``.
+Families can be invalidated as a whole, meaning all tokens associated with the
+same family will then be considered invalid.
+You need to add ``'rest_framework_simplejwt.token_family',`` to your 
+``INSTALLED_APPS`` in the settings file to use this setting.
+
+This feature is most effective when used in conjunction with the :doc:`/blacklist_app`
+
+Learn more about :doc:`/family_app`.
+
+``TOKEN_FAMILY_LIFETIME``
+----------------------------
+
+A ``datetime.timedelta`` object that specifies how long a token family is considered valid.
+This ``timedelta`` value is added to the current UTC time during token generation
+to obtain the token's default "family_exp" claim value.
+This setting can also be set to ``None``, in which case the "family_exp" claim
+will not be included in the token payload and the token family will never expire automatically.
+In that case, the only way to invalidate the family is by blacklisting it.
+
+``TOKEN_FAMILY_CHECK_ON_ACCESS``
+-------------------------------------
+
+When set to ``True``, the token family claims ("family_id" and "family_exp") will be included
+in the access token payload. Requests authenticated with access tokens will then verify
+that the token's family is valid, meaning it has not expired and has not been blacklisted.
+
+``TOKEN_FAMILY_BLACKLIST_ON_REUSE``
+-------------------------------------
+
+When set to ``True``, any detected reuse of a refresh token will trigger blacklisting of
+the entire token family. This invalidates all tokens that share the same family identifier.
+This feature can be enhanced when used together with ``BLACKLIST_AFTER_ROTATION`` set to ``True``.
+
 ``ALGORITHM``
 -------------
 
@@ -259,6 +308,18 @@ identifier is used to identify revoked tokens in the blacklist app.  It may be
 necessary in some cases to use another claim besides the default "jti" claim to
 store such a value.
 
+``TOKEN_FAMILY_CLAIM``
+---------------------------
+
+The claim name used to store the token family's unique identifier in the token
+payload. Defaults to "family_id".
+
+``TOKEN_FAMILY_EXPIRATION_CLAIM``
+-------------------------------------
+
+The claim name used to store the token family's expiration date in the token
+payload. Defaults to "family_exp".
+
 ``TOKEN_USER_CLASS``
 --------------------