fix(auth): revoke access tokens with refresh sessions

Author: shepilov-vladislav

CHANGELOG.md

@@ -1,3 +1,14 @@
+## Unreleased
+
+### Security
+
+- **DB session revocation now invalidates access tokens immediately.** Database access-token rows carry the
+  nullable public refresh-session id that issued them. Revoking one session, revoking other sessions,
+  detecting refresh-token replay, or expiring a refresh session now deletes every linked access token as
+  well as the refresh chain. Previously, an already-issued access token remained usable until its access
+  TTL elapsed. **Breaking schema change:** bundled and custom access-token tables need a nullable indexed
+  `session_id` column before rollout; see Migration.
+
 ## 5.2.0 (2026-07-13)
 
 ### Security

docs/api/models.md

@@ -31,6 +31,13 @@ columns or relationship wiring from the reference classes.
 [Configuration](../configuration/user_and_manager.md#custom-sqlalchemy-user-and-token-models) covers the full
 support matrix and migration notes.
 
+## `access_token` session ownership
+
+`AccessTokenMixin.session_id` is a nullable, indexed copy of the public refresh-session id. Access-only
+flows leave it `null`; login, TOTP verification, and refresh rotation link newly issued DB access tokens
+to the corresponding refresh session. The DB strategy uses that index to invalidate only the access
+tokens owned by a revoked, expired, or replay-compromised session.
+
 ## `refresh_token` session metadata
 
 The bundled `RefreshTokenMixin` stores refresh tokens as keyed digests only. It also adds the DB-backed

docs/api/strategies.md

@@ -36,6 +36,8 @@ queries. `DatabaseTokenStrategy` implements that protocol and can:
 - revoke one current-user session by public `session_id`;
 - revoke all other current-user sessions, preserving the current session when the current refresh
   credential can be identified;
+- bind newly issued access tokens to their refresh session and delete those access tokens when that
+  session is revoked, expires, or is invalidated after refresh-token replay;
 - identify a public `session_id` from a raw refresh token by hashing the supplied value and comparing
   it with stored digests;
 - record consumed refresh-token digests during rotation and revoke the whole refresh-session chain when

docs/configuration/user_and_manager.md

@@ -226,6 +226,9 @@ backend = AuthenticationBackend(
 )
 ```
 
+Custom access-token classes must expose a nullable mapped `session_id`; `AccessTokenMixin` provides
+the indexed column used for immediate session-scoped revocation.
+
 Custom refresh-token classes have a session-management and reuse-detection contract in addition to
 the shared token contract. They must expose mapped `session_id`, `last_used_at`, and `client_metadata`
 attributes, while consumed digest lookup lives in the separate `refresh_token_consumed_digest` table.

docs/deployment.md

@@ -160,6 +160,12 @@ metadata columns:
 - `last_used_at` — nullable timestamp updated on successful refresh rotation;
 - `client_metadata` — nullable bounded JSON for safe hints such as normalized User-Agent.
 
+The access-token table also requires a nullable indexed `session_id VARCHAR(36)` column. New login,
+TOTP verification, and refresh flows copy the refresh session's public id into that column so session
+revocation can delete linked access tokens immediately. Existing access-token rows cannot be mapped
+reliably to historical refresh sessions: leave them null to let the normal access TTL expire, or delete
+them during the migration to force immediate re-authentication.
+
 For bundled models, these fields come from `RefreshTokenMixin`. Existing installations must run an
 application-owned migration before rollout: add missing columns, backfill each existing row with a
 unique UUID-style `session_id`, leave `last_used_at` null for historical sessions, and only store

docs/http_api.md

@@ -25,8 +25,8 @@ mount protected controllers manually, pass `security=` to the relevant controlle
 | POST | `{auth}/refresh` | `RefreshTokenRequest` (`refresh_token`) | `enable_refresh=True` | New access token from refresh token / cookie. |
 | GET | `{auth}/sessions` | None | `include_session_devices=True` | Authenticated; list the current user's active DB-backed refresh sessions. CookieTransport clients can be marked current from the refresh cookie. |
 | POST | `{auth}/sessions` | `RefreshTokenRequest` (`refresh_token`) | `include_session_devices=True` | Authenticated; list active refresh sessions while identifying the current bearer refresh session. |
-| DELETE | `{auth}/sessions/{session_id}` | None | `include_session_devices=True` | Authenticated; revoke one of the current user's refresh sessions by public session id. |
-| POST | `{auth}/sessions/revoke-others` | Optional `RefreshTokenRequest` (`refresh_token`) for bearer clients | `include_session_devices=True` | Authenticated; revoke the current user's other refresh sessions. |
+| DELETE | `{auth}/sessions/{session_id}` | None | `include_session_devices=True` | Authenticated; revoke one of the current user's DB sessions and its linked access tokens by public session id. |
+| POST | `{auth}/sessions/revoke-others` | Optional `RefreshTokenRequest` (`refresh_token`) for bearer clients | `include_session_devices=True` | Authenticated; revoke the current user's other DB sessions and their linked access tokens. |
 | POST | `{auth}/switch-organization` | `SwitchOrganizationRequest` (`organization_slug`) | `organization_config.enabled=True`, `organization_config.include_switch_organization=True`, and a JWT-capable non-API-key backend | Authenticated; verifies target organization membership and returns an organization-bound JWT through the configured transport. |
 | POST | `{auth}/organization-invitations/accept` | `OrganizationInvitationTokenRequest` (`token`) | `organization_config.enabled=True`, `organization_config.include_organization_invitations=True` | Authenticated; validates a single-use invitation token, requires the authenticated user's normalized email to match the invitation, creates membership roles from the invitation, and consumes the invitation. |
 | POST | `{auth}/organization-invitations/decline` | `OrganizationInvitationTokenRequest` (`token`) | `organization_config.enabled=True`, `organization_config.include_organization_invitations=True` | Authenticated; validates the token and authenticated email, then revokes the pending invitation without creating membership. |
@@ -76,6 +76,11 @@ The first controller slice supports strategies implementing the refresh-session
 including the built-in DB token strategy. JWT and Redis token strategies do not provide a session
 dashboard in this slice.
 
+The built-in DB strategy links each newly issued access token to the refresh session that issued it.
+Deleting a session, revoking other sessions, detecting refresh-token replay, or expiring a refresh
+session therefore invalidates its access tokens immediately rather than waiting for their access TTL.
+Custom strategies control their own revocation semantics.
+
 | Status | Error code | Applies to | Meaning |
 | ------ | ---------- | ---------- | ------- |
 | 400 | `SESSION_MANAGEMENT_UNSUPPORTED` | All session/device routes | The configured strategy does not implement refresh-session management. |

docs/migration.md

@@ -1,5 +1,27 @@
 # Migration Guide
 
+## DB access-token session ownership
+
+DB session revocation now invalidates access tokens immediately instead of revoking only the refresh
+chain. Before deploying the new code, add a nullable indexed `session_id` column to the bundled or
+custom access-token table:
+
+```python
+import sqlalchemy as sa
+from alembic import op
+
+
+def upgrade() -> None:
+    op.add_column("access_token", sa.Column("session_id", sa.String(length=36), nullable=True))
+    op.create_index("ix_access_token_session_id", "access_token", ["session_id"])
+```
+
+Historical access tokens cannot be matched safely to historical refresh sessions. Leaving
+`session_id` null preserves them until their configured access TTL expires. For a strict rollout with
+immediate revocation semantics, delete existing access-token rows in the migration window and require
+users to authenticate again. Custom access-token models supplied through `DatabaseTokenModels` must
+expose the nullable mapped `session_id` attribute.
+
 ## Litestar 2.24: explicit dependency annotations
 
 litestar-auth now requires Litestar `>=2.24.0`. Litestar 2.24 deprecates *inferred*

litestar_auth/_auth_model_mixins.py

@@ -734,6 +734,12 @@ class AccessTokenMixin(_TokenModelMixin):
 
     auth_user_back_populates: ClassVar[str] = "access_tokens"
 
+    session_id: Mapped[str | None] = mapped_column(
+        String(length=_SESSION_ID_LENGTH),
+        index=True,
+        nullable=True,
+    )
+
 
 class RefreshTokenMixin(_TokenModelMixin):
     """Shared mapped attributes for refresh-token models."""

litestar_auth/authentication/backend.py

@@ -7,7 +7,12 @@
 from litestar.exceptions import ClientException, NotAuthorizedException
 from litestar.response import Response
 
-from litestar_auth.authentication.strategy.base import ContextualStrategy, SessionBindable, TokenInvalidationCapable
+from litestar_auth.authentication.strategy.base import (
+    ContextualStrategy,
+    RefreshSessionAccessTokenStrategy,
+    SessionBindable,
+    TokenInvalidationCapable,
+)
 from litestar_auth.authentication.transport.base import LogoutTokenReadable
 from litestar_auth.authentication.transport.cookie import CookieTransport
 from litestar_auth.exceptions import TokenError
@@ -44,13 +49,23 @@ def with_session[S](self, session: S) -> AuthenticationBackend[UP, ID]:
 
         return type(self)(name=self.name, transport=self.transport, strategy=bound_strategy)
 
-    async def login(self, user: UP) -> Response[Any]:
+    async def login(self, user: UP, *, session_id: str | None = None) -> Response[Any]:
         """Issue a token through the configured strategy and transport.
 
         Returns:
             Response mutated by the configured transport for login.
+
+        Raises:
+            TypeError: If session binding is requested for an unsupported strategy.
         """
-        token = await self.strategy.write_token(user)
+        if session_id is None:
+            token = await self.strategy.write_token(user)
+        elif isinstance(self.strategy, RefreshSessionAccessTokenStrategy):
+            session_strategy = cast("RefreshSessionAccessTokenStrategy[UP]", self.strategy)
+            token = await session_strategy.write_token_for_session(user, session_id)
+        else:
+            msg = "The configured authentication strategy cannot bind access tokens to refresh sessions."
+            raise TypeError(msg)
         return self.transport.set_login_token(Response(content=None), token)
 
     async def logout(self, user: UP, token: str) -> Response[Any]:

litestar_auth/authentication/strategy/_db_refresh.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from datetime import UTC, datetime, timedelta
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any, Protocol, cast
 
 from sqlalchemy import delete, select
 
@@ -25,6 +25,13 @@
     from litestar_auth.authentication.strategy.db_models import RefreshTokenConsumedDigest
 
 
+class _SessionBoundAccessTokenRow(Protocol):
+    """Access-token fields needed to resolve its refresh session."""
+
+    user_id: object
+    session_id: str | None
+
+
 class _DatabaseRefreshSessionMixin[UP: UserProtocol[Any], ID](
     _DatabaseRefreshTokenRotationMixin[UP, ID],
 ):
@@ -36,6 +43,7 @@ class _DatabaseRefreshSessionMixin[UP: UserProtocol[Any], ID](
     token_bytes: int
     _token_hash_secret: bytes
     _refresh_token_repository_type: TokenRepositoryType
+    _access_token_repository_type: TokenRepositoryType
     consumed_refresh_token_digest_model: type[RefreshTokenConsumedDigest]
 
     def _repository(self, repository_type: TokenRepositoryType) -> SQLAlchemyAsyncRepository[Any]:
@@ -101,19 +109,23 @@ async def revoke_refresh_session(self, user: UP, session_id: str) -> bool:
             ``True`` when a matching active session was deleted, otherwise ``False``.
         """
         expired_count = await self._delete_expired_refresh_sessions_for_user(user)
+        session_ids = select(self.refresh_token_model.session_id).where(
+            self.refresh_token_model.user_id == user.id,
+            self.refresh_token_model.session_id == session_id,
+        )
+        deleted_access_count = await self._execute_delete(
+            delete(self.access_token_model).where(self.access_token_model.session_id.in_(session_ids)),
+        )
         deleted_marker_count = await self._delete_refresh_session_consumed_digests(
-            select(self.refresh_token_model.session_id).where(
-                self.refresh_token_model.user_id == user.id,
-                self.refresh_token_model.session_id == session_id,
-            ),
+            session_ids,
         )
         deleted_count = await self._execute_delete(
             delete(self.refresh_token_model).where(
                 self.refresh_token_model.user_id == user.id,
                 self.refresh_token_model.session_id == session_id,
             ),
         )
-        if expired_count or deleted_marker_count or deleted_count:
+        if expired_count or deleted_access_count or deleted_marker_count or deleted_count:
             await self.session.commit()
         return deleted_count > 0
 
@@ -127,11 +139,15 @@ async def revoke_other_refresh_sessions(self, user: UP, current_session_id: str
         conditions = [self.refresh_token_model.user_id == user.id]
         if current_session_id is not None:
             conditions.append(self.refresh_token_model.session_id != current_session_id)
+        session_ids = select(self.refresh_token_model.session_id).where(*conditions)
+        deleted_access_count = await self._execute_delete(
+            delete(self.access_token_model).where(self.access_token_model.session_id.in_(session_ids)),
+        )
         deleted_marker_count = await self._delete_refresh_session_consumed_digests(
-            select(self.refresh_token_model.session_id).where(*conditions),
+            session_ids,
         )
         deleted_count = await self._execute_delete(delete(self.refresh_token_model).where(*conditions))
-        if expired_count or deleted_marker_count or deleted_count:
+        if expired_count or deleted_access_count or deleted_marker_count or deleted_count:
             await self.session.commit()
         return deleted_count
 
@@ -157,7 +173,7 @@ async def identify_refresh_session(self, user: UP, refresh_token: str) -> str |
                 await self.session.commit()
             return None
         if self._is_token_expired(persisted_token.created_at, self.refresh_max_age):
-            await self._delete_refresh_token_row(persisted_token)
+            await self._revoke_refresh_session_chain(persisted_token.session_id)
             await self.session.commit()
             return None
         return persisted_token.session_id
@@ -172,9 +188,30 @@ async def _load_refresh_session_row(self, user: UP, session_id: str) -> _Refresh
         )
         return cast("_RefreshTokenRow | None", result.scalars().first())
 
+    async def _load_totp_stepup_refresh_session_row(self, user: UP, session_id: str) -> _RefreshTokenRow | None:
+        """Resolve a refresh session from either its public id or a linked access token.
+
+        Returns:
+            Matching refresh-session row, otherwise ``None``.
+        """
+        row = await self._load_refresh_session_row(user, session_id)
+        if row is not None:
+            return row
+        access_token = cast(
+            "_SessionBoundAccessTokenRow | None",
+            await self._resolve_token(
+                self._repository(self._access_token_repository_type),
+                session_id,
+                load=[],
+            ),
+        )
+        if access_token is None or access_token.user_id != user.id or access_token.session_id is None:
+            return None
+        return await self._load_refresh_session_row(user, access_token.session_id)
+
     async def issue_totp_stepup(self, user: UP, session_id: str, *, ttl_seconds: int) -> None:
         """Store a short-lived TOTP step-up marker on a DB-backed refresh session."""
-        row = await self._load_refresh_session_row(user, session_id)
+        row = await self._load_totp_stepup_refresh_session_row(user, session_id)
         if row is None:
             return
         metadata = dict(row.client_metadata or {})
@@ -188,7 +225,7 @@ async def issue_totp_stepup(self, user: UP, session_id: str, *, ttl_seconds: int
 
     async def has_recent_totp_verification(self, user: UP, session_id: str) -> bool:
         """Return whether a DB-backed refresh session has a live TOTP step-up marker."""
-        row = await self._load_refresh_session_row(user, session_id)
+        row = await self._load_totp_stepup_refresh_session_row(user, session_id)
         if row is None:
             return False
         metadata = row.client_metadata or {}
@@ -211,11 +248,15 @@ async def _delete_expired_refresh_sessions_for_user(self, user: UP) -> int:
             Number of deleted rows.
         """
         cutoff = datetime.now(tz=UTC) - self.refresh_max_age
+        expired_session_ids = select(self.refresh_token_model.session_id).where(
+            self.refresh_token_model.user_id == user.id,
+            self.refresh_token_model.created_at <= cutoff,
+        )
+        await self._execute_delete(
+            delete(self.access_token_model).where(self.access_token_model.session_id.in_(expired_session_ids)),
+        )
         await self._delete_refresh_session_consumed_digests(
-            select(self.refresh_token_model.session_id).where(
-                self.refresh_token_model.user_id == user.id,
-                self.refresh_token_model.created_at <= cutoff,
-            ),
+            expired_session_ids,
         )
         return await self._execute_delete(
             delete(self.refresh_token_model).where(