auth-middleware 0.3.8__tar.gz → 0.4.2__tar.gz

auth_middleware-0.4.2/.vscode/extensions.json

@@ -0,0 +1,15 @@
+{
+  "recommendations": [
+    // Python core
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "ms-python.debugpy",
+    // Linting / formatting
+    "charliermarsh.ruff",
+    "ms-python.mypy-type-checker",
+    // Security
+    "SonarSource.sonarlint-vscode",
+    // Containers
+    "ms-vscode-remote.remote-containers"
+  ]
+}

auth_middleware-0.4.2/.vscode/settings.json

@@ -0,0 +1,31 @@
+{
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "python.analysis.typeCheckingMode": "basic",
+    "python.analysis.diagnosticMode": "workspace",
+    "python.analysis.diagnosticSeverityOverrides": {
+        "reportMissingParameterType": "warning",
+        "reportMissingTypeArgument": "warning",
+        "reportUnknownParameterType": "warning",
+        "reportUnknownVariableType": "information",
+        "reportUnknownMemberType": "information"
+    },
+    "mypy-type-checker.severity": {
+        "error": "Warning",
+        "note": "Information"
+    },
+    "mypy-type-checker.args": [
+        "--config-file",
+        "${workspaceFolder}/pyproject.toml"
+    ],
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports.ruff": "explicit"
+        }
+    },
+    "sonarlint.connectedMode.project": {
+        "connectionId": "local",
+        "projectKey": "auth-middleware"
+    }
+}

auth_middleware-0.4.2/CHANGELOG.txt

@@ -0,0 +1,147 @@
+CHANGELOG
+=========
+
+Version 0.4.1 (2026-05-02)
+---------------------------
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+
+**Guard helpers and checker classes** moved to a dedicated ``guards`` package.
+The old top-level module paths have been **deleted** — they no longer exist.
+
+  OLD LOCATION (deleted)                            NEW LOCATION
+  -----------------------------------------------   -----------------------------------------------
+  auth_middleware.functions                         auth_middleware.guards.functions
+  auth_middleware.group_checker                     auth_middleware.guards.group_checker
+  auth_middleware.role_checker                      auth_middleware.guards.role_checker
+  auth_middleware.permissions_checker               auth_middleware.guards.permissions_checker
+
+**Provider implementations** reorganised into technology-scoped packages.
+All old module paths have been **deleted** — they no longer exist.
+
+  OLD LOCATION (deleted)                                           NEW LOCATION
+  --------------------------------------------------------------   ---------------------------------------------------
+  auth_middleware.providers.authn.cognito_provider                 auth_middleware.providers.aws.cognito_provider
+  auth_middleware.providers.authn.cognito_authz_provider_settings  auth_middleware.providers.aws.cognito_authz_provider_settings
+  auth_middleware.providers.authn.identity_pool_provider           auth_middleware.providers.aws.identity_pool_provider
+  auth_middleware.providers.authn.identity_pool_client             auth_middleware.providers.aws.identity_pool_client
+  auth_middleware.providers.authn.identity_pool_settings           auth_middleware.providers.aws.identity_pool_settings
+  auth_middleware.providers.authn.jwt_provider_settings            auth_middleware.providers.aws.jwt_provider_settings
+  auth_middleware.providers.authz.cognito_groups_provider          auth_middleware.providers.aws.cognito_groups_provider
+  auth_middleware.providers.authz.cognito_groups_as_roles_provider auth_middleware.providers.aws.cognito_groups_as_roles_provider
+  auth_middleware.providers.profile.cognito_profile_provider       auth_middleware.providers.aws.cognito_profile_provider
+  auth_middleware.providers.cognito (COGNITO_*_CLAIM constants)    auth_middleware.providers.aws (same constants)
+  auth_middleware.providers.cognito.utils                          auth_middleware.providers.aws.utils
+  auth_middleware.providers.exceptions.aws_exception               auth_middleware.providers.aws.aws_exception
+  auth_middleware.providers.entra_id.entra_id_provider             auth_middleware.providers.azure.entra_id_provider
+  auth_middleware.providers.entra_id.settings                      auth_middleware.providers.azure.settings
+  auth_middleware.providers.entra_id.utils                         auth_middleware.providers.azure.utils
+  auth_middleware.providers.exceptions.azure_exception             auth_middleware.providers.azure.azure_exception
+  auth_middleware.providers.authz.async_database                   auth_middleware.providers.sqlalchemy.async_database
+  auth_middleware.providers.authz.async_database_settings          auth_middleware.providers.sqlalchemy.async_database_settings
+  auth_middleware.providers.authz.sql_base_model                   auth_middleware.providers.sqlalchemy.sql_base_model
+  auth_middleware.providers.authz.sql_groups_provider              auth_middleware.providers.sqlalchemy.sql_groups_provider
+  auth_middleware.providers.authz.sql_permissions_provider         auth_middleware.providers.sqlalchemy.sql_permissions_provider
+
+Migration
+~~~~~~~~~
+
+Guards:
+
+  # Before (no longer works — ImportError)
+  from auth_middleware.functions import require_user, require_groups, require_roles
+  from auth_middleware.functions import require_permissions, has_groups, has_roles
+  from auth_middleware.functions import has_permissions, get_current_user
+  from auth_middleware.group_checker import GroupChecker
+  from auth_middleware.role_checker import RoleChecker
+  from auth_middleware.permissions_checker import PermissionsChecker
+
+  # After
+  from auth_middleware.guards import (
+      require_user,
+      require_groups,
+      require_roles,
+      require_permissions,
+      has_groups,
+      has_roles,
+      has_permissions,
+      get_current_user,
+      GroupChecker,
+      RoleChecker,
+      PermissionsChecker,
+  )
+
+Providers:
+
+  providers.authn.*                        → providers.aws.*
+  providers.authz.cognito_*                → providers.aws.cognito_*
+  providers.authz.sql_*                    → providers.sqlalchemy.sql_*
+  providers.authz.async_database*          → providers.sqlalchemy.async_database*
+  providers.profile.*                      → providers.aws.*
+  providers.cognito                        → providers.aws
+  providers.entra_id.*                     → providers.azure.*
+  providers.exceptions.aws_exception       → providers.aws.aws_exception
+  providers.exceptions.azure_exception     → providers.azure.azure_exception
+
+Deleted package directories: authn/, authz/, profile/, cognito/, entra_id/, exceptions/
+
+Other Changes
+~~~~~~~~~~~~~
+
+- New internal module ``auth_middleware.constants`` introduced with
+  ``AUTH_SCHEME_BASIC`` and ``AUTH_SCHEME_BEARER`` constants.
+  This module is not part of the public API.
+
+Version 0.4.0 (2026-05-01)
+---------------------------
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+
+Provider interfaces / ABCs moved to a dedicated ``contracts`` package.
+The old module paths have been **deleted** — they no longer exist.
+
+  OLD LOCATION (deleted)                                    NEW LOCATION
+  -------------------------------------------------------  -----------------------------------------------
+  auth_middleware.providers.authn.jwt_provider             auth_middleware.contracts.jwt_provider
+  auth_middleware.providers.authz.groups_provider          auth_middleware.contracts.groups_provider
+  auth_middleware.providers.authz.roles_provider           auth_middleware.contracts.roles_provider
+  auth_middleware.providers.authz.permissions_provider     auth_middleware.contracts.permissions_provider
+  auth_middleware.providers.profile.profile_provider       auth_middleware.contracts.profile_provider
+
+Migration
+~~~~~~~~~
+
+Update your imports to use the new canonical paths:
+
+  # Before (no longer works — ImportError)
+  from auth_middleware.providers.authn.jwt_provider import JWTProvider
+  from auth_middleware.providers.authz.groups_provider import GroupsProvider
+  from auth_middleware.providers.authz.roles_provider import RolesProvider
+  from auth_middleware.providers.authz.permissions_provider import PermissionsProvider
+  from auth_middleware.providers.profile.profile_provider import ProfileProvider
+
+  # After
+  from auth_middleware.contracts import (
+      JWTProvider,
+      GroupsProvider,
+      RolesProvider,
+      PermissionsProvider,
+      ProfileProvider,
+  )
+
+  # Or via top-level package
+  from auth_middleware import JWTProvider, GroupsProvider, RolesProvider, PermissionsProvider, ProfileProvider
+
+Other Changes
+~~~~~~~~~~~~~
+
+- Provider contracts are now exported from the top-level ``auth_middleware``
+  package, making them available via ``from auth_middleware import JWTProvider``
+  etc. without knowing the internal module structure.
+
+Version 0.3.x and earlier
+--------------------------
+
+See git history for previous changes.

{auth_middleware-0.3.8 → auth_middleware-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth-middleware
-Version: 0.3.8
+Version: 0.4.2
 Summary: Async Auth Middleware for FastAPI/Starlette
 Project-URL: Homepage, https://impalah.github.io/auth-middleware/
 Project-URL: Documentation, https://impalah.github.io/auth-middleware/

{auth_middleware-0.3.8 → auth_middleware-0.4.2}/alembic/versions/de961fac6f27_initial_migration.py

@@ -5,13 +5,14 @@ Revises:
 Create Date: 2024-11-22 10:59:30.889117
 
 """
+
 from collections.abc import Sequence
 
 import sqlalchemy as sa
 from alembic import op
 
 # revision identifiers, used by Alembic.
-revision: str = 'de961fac6f27'
+revision: str = "de961fac6f27"
 down_revision: str | None = None
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
@@ -19,23 +20,21 @@ depends_on: str | Sequence[str] | None = None
 
 def upgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
-    op.create_table('authz_permissions',
-    sa.Column('id', sa.String(length=27), nullable=False),
-    sa.Column('username', sa.String(length=500), nullable=False),
-    sa.Column('permission', sa.String(length=100), nullable=False),
-    sa.PrimaryKeyConstraint('id')
+    op.create_table(
+        "authz_permissions",
+        sa.Column("id", sa.String(length=27), nullable=False),
+        sa.Column("username", sa.String(length=500), nullable=False),
+        sa.Column("permission", sa.String(length=100), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
     )
     op.create_index(
-        op.f('ix_authz_permissions_id'),
-        'authz_permissions',
-        ['id'],
-        unique=False
+        op.f("ix_authz_permissions_id"), "authz_permissions", ["id"], unique=False
     )
     # ### end Alembic commands ###
 
 
 def downgrade() -> None:
     # ### commands auto generated by Alembic - please adjust! ###
-    op.drop_index(op.f('ix_authz_permissions_id'), table_name='authz_permissions')
-    op.drop_table('authz_permissions')
+    op.drop_index(op.f("ix_authz_permissions_id"), table_name="authz_permissions")
+    op.drop_table("authz_permissions")
     # ### end Alembic commands ###

{auth_middleware-0.3.8 → auth_middleware-0.4.2}/docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a45fb20f4e788f1218cc49e997b02191
+config: 6d8577a96de98559dfa27a9c106851f9
 tags: 645f666f9bcd5a90fca523b33c5a78b7

auth_middleware-0.4.2/docs/_modules/auth_middleware/contracts/groups_provider.html

@@ -0,0 +1,214 @@
+
+
+<!DOCTYPE html>
+<html class="writer-html5" lang="en" data-content_root="../../../">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>auth_middleware.contracts.groups_provider &mdash; Auth Middleware 0.4.2 documentation</title>
+      <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=b86133f3" />
+      <link rel="stylesheet" type="text/css" href="../../../_static/css/theme.css?v=9edc463e" />
+
+  
+    <link rel="canonical" href="/auth-middleware/_modules/auth_middleware/contracts/groups_provider.html" />
+      <script src="../../../_static/jquery.js?v=5d32c60e"></script>
+      <script src="../../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
+      <script src="../../../_static/documentation_options.js?v=ff822928"></script>
+      <script src="../../../_static/doctools.js?v=fd6eb6e6"></script>
+      <script src="../../../_static/sphinx_highlight.js?v=6ffebe34"></script>
+    <script src="../../../_static/js/theme.js"></script>
+    <link rel="index" title="Index" href="../../../genindex.html" />
+    <link rel="search" title="Search" href="../../../search.html" /> 
+</head>
+
+<body class="wy-body-for-nav"> 
+  <div class="wy-grid-for-nav">
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search"  style="background: #2980B9" >
+
+          
+          
+          <a href="../../../index.html" class="icon icon-home">
+            Auth Middleware
+          </a>
+<div role="search">
+  <form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
+    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
+    <input type="hidden" name="check_keywords" value="yes" />
+    <input type="hidden" name="area" value="default" />
+  </form>
+</div>
+        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
+              <p class="caption" role="heading"><span class="caption-text">Getting Started:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user-guide.html">User Guide</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../middleware-configuration.html">Middleware Configuration</a></li>
+</ul>
+<p class="caption" role="heading"><span class="caption-text">Infrastructure Setup:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../infrastructure.html">Infrastructure Setup</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../infrastructure.html#provider-specific-setup-guides">Provider-Specific Setup Guides</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../infrastructure.html#overview">Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../infrastructure.html#security-considerations">Security Considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../infrastructure.html#next-steps">Next Steps</a></li>
+</ul>
+<p class="caption" role="heading"><span class="caption-text">Authentication Providers:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../cognito_provider.html">AWS Cognito Provider</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../entra_id_provider.html">Azure Entra ID Authentication Provider</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwt_auth_provider.html">JWT Authentication Provider</a></li>
+</ul>
+<p class="caption" role="heading"><span class="caption-text">Advanced Topics:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html">Groups Provider</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#overview">Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#built-in-providers">Built-in Providers</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#using-groups-in-your-application">Using Groups in Your Application</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#custom-groups-provider">Custom Groups Provider</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#configuration-examples">Configuration Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#testing-groups-providers">Testing Groups Providers</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#best-practices">Best Practices</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#migration-and-deployment">Migration and Deployment</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#troubleshooting">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#api-reference">API Reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../groups-provider.html#see-also">See Also</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html">Permissions Provider</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#overview">Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#built-in-providers">Built-in Providers</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#using-permissions-in-your-application">Using Permissions in Your Application</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#permission-patterns">Permission Patterns</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#custom-permissions-provider">Custom Permissions Provider</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#advanced-features">Advanced Features</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#permission-management">Permission Management</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#testing-permissions-providers">Testing Permissions Providers</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#best-practices">Best Practices</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#troubleshooting">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#api-reference">API Reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../permissions-provider.html#see-also">See Also</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html">Extending Authorization Providers</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#overview">Overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#understanding-the-provider-interface">Understanding the Provider Interface</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#integration-patterns">Integration Patterns</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#advanced-patterns">Advanced Patterns</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#caching-and-performance">Caching and Performance</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#error-handling-and-resilience">Error Handling and Resilience</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#testing-custom-providers">Testing Custom Providers</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#deployment-considerations">Deployment Considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#best-practices-summary">Best Practices Summary</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../extending-authz-providers.html#see-also">See Also</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../user-property.html">The User Property</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../auth-authn.html">Control Authentication and Authorization</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../services.html">Services Module</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../services.html#m2m-token-detection">M2M Token Detection</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../services.html#rate-limiting">Rate Limiting</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../services.html#audit-logging">Audit Logging</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../services.html#metrics-collection">Metrics Collection</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../services.html#best-practices">Best Practices</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../services.html#see-also">See Also</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html">JWKS Cache Strategies</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html#cache-strategies">Cache Strategies</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html#background-refresh">Background Refresh</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html#configuration-examples">Configuration Examples</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html#monitoring-cache-performance">Monitoring Cache Performance</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html#best-practices">Best Practices</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html#troubleshooting">Troubleshooting</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html#performance-comparison">Performance Comparison</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwks-cache.html#see-also">See Also</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../jwt_bearer_manager.html">jwt_bearer_manager</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../exceptions.html">Exception Handling</a></li>
+</ul>
+<p class="caption" role="heading"><span class="caption-text">API Reference:</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../../api.html">API Reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../types.html">Type Definitions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../../functions.html">Authentication Functions</a></li>
+</ul>
+
+        </div>
+      </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu"  style="background: #2980B9" >
+          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+          <a href="../../../index.html">Auth Middleware</a>
+      </nav>
+
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="Page navigation">
+  <ul class="wy-breadcrumbs">
+      <li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
+          <li class="breadcrumb-item"><a href="../../index.html">Module code</a></li>
+      <li class="breadcrumb-item active">auth_middleware.contracts.groups_provider</li>
+      <li class="wy-breadcrumbs-aside">
+      </li>
+  </ul>
+  <hr/>
+</div>
+          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
+           <div itemprop="articleBody">
+             
+  <h1>Source code for auth_middleware.contracts.groups_provider</h1><div class="highlight"><pre>
+<span></span><span class="kn">from</span><span class="w"> </span><span class="nn">abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">ABCMeta</span><span class="p">,</span> <span class="n">abstractmethod</span>
+
+<span class="kn">from</span><span class="w"> </span><span class="nn">auth_middleware.types.jwt</span><span class="w"> </span><span class="kn">import</span> <span class="n">JWTAuthorizationCredentials</span>
+
+
+<div class="viewcode-block" id="GroupsProvider">
+<a class="viewcode-back" href="../../../groups-provider.html#auth_middleware.contracts.groups_provider.GroupsProvider">[docs]</a>
+<span class="k">class</span><span class="w"> </span><span class="nc">GroupsProvider</span><span class="p">(</span><span class="n">metaclass</span><span class="o">=</span><span class="n">ABCMeta</span><span class="p">):</span>
+<span class="w">    </span><span class="sd">&quot;&quot;&quot;Abstract contract for a groups provider.</span>
+
+<span class="sd">    Implementations must return the list of groups the authenticated user</span>
+<span class="sd">    belongs to, given either a raw token string or a parsed</span>
+<span class="sd">    ``JWTAuthorizationCredentials`` object.</span>
+<span class="sd">    &quot;&quot;&quot;</span>
+
+<div class="viewcode-block" id="GroupsProvider.fetch_groups">
+<a class="viewcode-back" href="../../../groups-provider.html#auth_middleware.contracts.groups_provider.GroupsProvider.fetch_groups">[docs]</a>
+    <span class="nd">@abstractmethod</span>
+    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">fetch_groups</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">token</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="n">JWTAuthorizationCredentials</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;Return the groups for the authenticated user.</span>
+
+<span class="sd">        Args:</span>
+<span class="sd">            token: The token containing the claims, either as a raw string</span>
+<span class="sd">                   or a parsed ``JWTAuthorizationCredentials`` object.</span>
+
+<span class="sd">        Returns:</span>
+<span class="sd">            List of group name strings (may be empty).</span>
+<span class="sd">        &quot;&quot;&quot;</span>
+        <span class="k">raise</span> <span class="ne">NotImplementedError</span><span class="p">(</span><span class="s2">&quot;This method should be overridden by subclasses&quot;</span><span class="p">)</span></div>
+</div>
+
+</pre></div>
+
+           </div>
+          </div>
+          <footer>
+
+  <hr/>
+
+  <div role="contentinfo">
+    <p>&#169; Copyright 2025, impalah.</p>
+  </div>
+
+  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
+    provided by <a href="https://readthedocs.org">Read the Docs</a>.
+   
+
+</footer>
+        </div>
+      </div>
+    </section>
+  </div>
+  <script>
+      jQuery(function () {
+          SphinxRtdTheme.Navigation.enable(true);
+      });
+  </script> 
+
+</body>
+</html>