ab-auth-client 0.1.11__tar.gz

ab_auth_client-0.1.11/.gitignore

@@ -0,0 +1,195 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

ab_auth_client-0.1.11/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Coulter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ab_auth_client-0.1.11/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: ab-auth-client
+Version: 0.1.11
+Author-email: Matthew Coulter <53892067+mattcoulter7@users.noreply.github.com>
+License-File: LICENSE
+Requires-Python: <4,>=3.12
+Requires-Dist: ab-cache<0.2.0,>=0.1.3
+Requires-Dist: ab-pkce<0.2.0,>=0.1.3
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic<3,>=2.11.7
+Requires-Dist: requests<3,>=2.32.4
+Requires-Dist: yarl<2,>=1.20.1
+Description-Content-Type: text/markdown
+
+# Open Banking, Opened | Auth
+
+Auth Package for Open Banking, Opened API.

ab_auth_client-0.1.11/README.md

@@ -0,0 +1,3 @@
+# Open Banking, Opened | Auth
+
+Auth Package for Open Banking, Opened API.

ab_auth_client-0.1.11/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[dependency-groups]
+dev = [
+  "debugpy>=1.8.14,<2",
+  "isort>=6.0.1,<7",
+  "ab-test-fixtures>=0.1.5,<0.2.0",
+  "pre-commit>=4.2.0,<5",
+  "pytest-asyncio>=1.0.0,<2",
+  "pytest-cov>=6.2.1,<7",
+  "pytest>=8.4.1,<9",
+  "ruff>=0.12.3,<0.13",
+  "tox>=4.27.0,<5"
+]
+
+[project]
+authors = [{email = "53892067+mattcoulter7@users.noreply.github.com", name = "Matthew Coulter"}]
+dependencies = [
+  "ab-cache>=0.1.3,<0.2.0",
+  "ab-pkce>=0.1.3,<0.2.0",
+  "httpx>=0.28.1",
+  "pydantic>=2.11.7,<3",
+  "requests>=2.32.4,<3",
+  "yarl>=1.20.1,<2",
+]
+description = ""
+name = "ab-auth-client"
+readme = "README.md"
+requires-python = ">=3.12, <4"
+version = "0.1.11"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/ab_core"]
+
+[tool.hatch.build.targets.wheel]
+include = ["src/ab_core"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src/ab_core" = "ab_core"
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "session"
+asyncio_mode = "auto"
+markers = [
+  "integration: Assigns the test to the integration test suite.",
+  "regression: Assigns the test to the regression test suite"
+]
+
+[tool.ruff]
+line-length = 120
+src = ["src"]
+target-version = "py312"
+
+[tool.ruff.lint]
+exclude = [".git", ".venv", "__pycache__", "proto"]
+fixable = ["ALL"]
+ignore = [
+  "D104" # missing docstring in public package
+]
+select = [
+  "ARG001", # unused arguments
+  "B", # flake8-bugbear
+  "C4", # flake8-comprehensions
+  "D", # pydocstyle (docstring checks)
+  "E", # pycodestyle errors
+  "F", # pyflakes
+  "I", # isort
+  "UP", # pyupgrade
+  "W" # pycodestyle warnings
+]

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/client/__init__.py

@@ -0,0 +1,11 @@
+from typing import Annotated, Union
+
+from pydantic import Discriminator
+
+from .pkce import PKCEOAuth2Client
+from .standard import StandardOAuth2Client
+
+OAuth2Client = Annotated[
+    StandardOAuth2Client | PKCEOAuth2Client,
+    Discriminator("type"),
+]

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/client/base.py

@@ -0,0 +1,114 @@
+from abc import ABC, abstractmethod
+from typing import (
+    Generic,
+    TypeVar,
+)
+from urllib.parse import parse_qs, urlparse
+
+from pydantic import BaseModel, Field
+
+from ab_core.auth_client.oauth2.schema.authorize import (
+    OAuth2AuthorizeResponse,
+    OAuth2BuildAuthorizeRequest,
+)
+from ab_core.auth_client.oauth2.schema.exchange import (
+    OAuth2ExchangeCodeRequest,
+    OAuth2ExchangeFromRedirectUrlRequest,
+)
+from ab_core.auth_client.oauth2.schema.oidc import OIDCConfig
+from ab_core.auth_client.oauth2.schema.refresh import RefreshTokenRequest
+from ab_core.auth_client.oauth2.schema.token import OAuth2Token
+from ab_core.cache.caches.base import CacheAsyncSession, CacheSession
+
+BuildReqT = TypeVar("BuildReqT", bound=OAuth2BuildAuthorizeRequest)
+BuildResT = TypeVar("BuildResT", bound=OAuth2AuthorizeResponse)
+ExReqT = TypeVar("ExReqT", bound=OAuth2ExchangeCodeRequest)
+ExUrlReqT = TypeVar("ExUrlReqT", bound=OAuth2ExchangeFromRedirectUrlRequest)
+
+
+class OAuth2ClientBase(BaseModel, ABC, Generic[BuildReqT, BuildResT, ExReqT, ExUrlReqT]):
+    config: OIDCConfig = Field(..., description="OIDC client configuration")
+
+    # ---------- Authorize URL ----------
+    @abstractmethod
+    def build_authorize_request(
+        self,
+        request: BuildReqT,
+        *,
+        cache_session: CacheSession | None = None,  # separate param
+    ) -> BuildResT: ...
+
+    @abstractmethod
+    async def build_authorize_request_async(
+        self,
+        request: BuildReqT,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> BuildResT: ...
+
+    # ---------- Exchanges ----------
+    @abstractmethod
+    def exchange_code(
+        self,
+        request: ExReqT,
+        *,
+        cache_session: CacheSession | None = None,
+    ) -> OAuth2Token: ...
+
+    @abstractmethod
+    async def exchange_code_async(
+        self,
+        request: ExReqT,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token: ...
+
+    @abstractmethod
+    def exchange_from_redirect_url(
+        self,
+        request: ExUrlReqT,
+        *,
+        cache_session: CacheSession | None = None,
+    ) -> OAuth2Token: ...
+
+    @abstractmethod
+    async def exchange_from_redirect_url_async(
+        self,
+        request: ExUrlReqT,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token: ...
+
+    @abstractmethod
+    def refresh(
+        self,
+        request: RefreshTokenRequest,
+        *,
+        cache_session: CacheSession | None = None,
+    ) -> OAuth2Token: ...
+
+    @abstractmethod
+    async def refresh_async(
+        self,
+        request: RefreshTokenRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token: ...
+
+    # ---------- Helpers ----------
+    def _parse_code_and_state_from_redirect(self, redirect_url: str) -> tuple[str, str | None]:
+        p = urlparse(redirect_url)
+        qs = parse_qs(p.query)
+        code_list = qs.get("code")
+        if not code_list or not code_list[0]:
+            raise ValueError("No `code` found in redirect URL")
+        state = (qs.get("state") or [None])[0]
+        return code_list[0], state
+
+    def _validate_redirect_uri_match(self, redirect_url: str) -> None:
+        rp = urlparse(redirect_url)
+        cp = urlparse(str(self.config.redirect_uri))
+        if (rp.scheme, rp.netloc, rp.path) != (cp.scheme, cp.netloc, cp.path):
+            raise ValueError(
+                f"Redirect URL `{redirect_url}` does not match configured redirect_uri `{self.config.redirect_uri}`"
+            )

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/client/pkce.py

@@ -0,0 +1,353 @@
+import base64
+import secrets
+from typing import Literal, override
+
+import httpx
+import requests
+from yarl import URL
+
+from ab_core.auth_client.oauth2.schema.authorize import (
+    PKCEAuthorizeResponse,
+    PKCEBuildAuthorizeRequest,
+)
+from ab_core.auth_client.oauth2.schema.client_type import OAuth2ClientType
+from ab_core.auth_client.oauth2.schema.exchange import (
+    PKCEExchangeCodeRequest,
+    PKCEExchangeFromRedirectUrlRequest,
+)
+from ab_core.auth_client.oauth2.schema.refresh import RefreshTokenRequest
+from ab_core.auth_client.oauth2.schema.token import OAuth2Token
+from ab_core.cache.caches.base import CacheAsyncSession, CacheSession
+
+from .base import OAuth2ClientBase
+
+
+class PKCEOAuth2Client(
+    OAuth2ClientBase[
+        PKCEBuildAuthorizeRequest,
+        PKCEAuthorizeResponse,
+        PKCEExchangeCodeRequest,
+        PKCEExchangeFromRedirectUrlRequest,
+    ]
+):
+    type: Literal[OAuth2ClientType.PKCE] = OAuth2ClientType.PKCE
+
+    @override
+    def build_authorize_request(
+        self,
+        request: PKCEBuildAuthorizeRequest,
+        *,
+        cache_session: CacheSession | None = None,  # separate param (not in request)
+    ) -> PKCEAuthorizeResponse:
+        # Base builds URL + state
+        state = request.state or base64.urlsafe_b64encode(secrets.token_bytes(16)).decode().rstrip("=")
+
+        q: dict[str, str] = {
+            "response_type": request.response_type,
+            "client_id": self.config.client_id,
+            "redirect_uri": str(self.config.redirect_uri),
+            "scope": request.scope,
+            "state": state,
+            "code_challenge": request.pkce.challenge,
+            "code_challenge_method": request.pkce.method.value,
+        }
+        if request.extra_params:
+            q.update({k: str(v) for k, v in request.extra_params.items()})
+
+        url = str(URL(str(self.config.authorize_url)).with_query(q))
+
+        res = PKCEAuthorizeResponse(
+            url=url,
+            state=state,
+            code_verifier=request.pkce.verifier,
+            code_challenge=request.pkce.challenge,
+            code_challenge_method=request.pkce.method.value,
+        )
+
+        # Persist verifier keyed by state if cache available
+        if cache_session is not None:
+            cache_session.set(
+                key=f"pkce:{res.state}",
+                value={"verifier": res.code_verifier},
+                expiry=request.state_ttl or 600,
+            )
+
+        return res
+
+    async def build_authorize_request_async(
+        self,
+        request: PKCEBuildAuthorizeRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> PKCEAuthorizeResponse:
+        state = request.state or base64.urlsafe_b64encode(secrets.token_bytes(16)).decode().rstrip("=")
+
+        q: dict[str, str] = {
+            "response_type": request.response_type,
+            "client_id": self.config.client_id,
+            "redirect_uri": str(self.config.redirect_uri),
+            "scope": request.scope,
+            "state": state,
+            "code_challenge": request.pkce.challenge,
+            "code_challenge_method": request.pkce.method.value,
+        }
+        if request.extra_params:
+            q.update({k: str(v) for k, v in request.extra_params.items()})
+
+        url = str(URL(str(self.config.authorize_url)).with_query(q))
+
+        res = PKCEAuthorizeResponse(
+            url=url,
+            state=state,
+            code_verifier=request.pkce.verifier,
+            code_challenge=request.pkce.challenge,
+            code_challenge_method=request.pkce.method.value,
+        )
+
+        if cache_session is not None:
+            await cache_session.set(  # assume async cache has awaitable set
+                key=f"pkce:{res.state}",
+                value={"verifier": res.code_verifier},
+                expiry=request.state_ttl or 600,
+            )
+
+        return res
+
+    # ---- exchanges ----
+    @override
+    def exchange_code(
+        self,
+        request: PKCEExchangeCodeRequest,
+        *,
+        cache_session: CacheSession | None = None,
+    ) -> OAuth2Token:
+        # in pkce code verifier is needed during exchange
+        code_verifier = request.code_verifier
+        if code_verifier is None:
+            if not request.state:
+                raise ValueError("code_verifier missing; provide it or supply state for cache lookup")
+            code_verifier = self._lookup_verifier(
+                state=request.state,
+                delete_after=request.delete_after,
+                cache_session=cache_session,
+            )
+
+        payload = {
+            "grant_type": "authorization_code",
+            "client_id": self.config.client_id,
+            "redirect_uri": str(self.config.redirect_uri),
+            "code": request.code,
+            "code_verifier": code_verifier,
+        }
+        resp = requests.post(
+            self.config.token_url,
+            data=payload,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        resp.raise_for_status()
+        return OAuth2Token.model_validate(resp.json())
+
+    async def exchange_code_async(
+        self,
+        request: PKCEExchangeCodeRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token:
+        code_verifier = request.code_verifier
+        if code_verifier is None:
+            if not request.state:
+                raise ValueError("code_verifier missing; provide it or supply state for cache lookup")
+            code_verifier = await self._lookup_verifier_async(
+                state=request.state,
+                delete_after=request.delete_after,
+                cache_session=cache_session,
+            )
+
+        payload = {
+            "grant_type": "authorization_code",
+            "client_id": self.config.client_id,
+            "redirect_uri": str(self.config.redirect_uri),
+            "code": request.code,
+            "code_verifier": code_verifier,
+        }
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                str(self.config.token_url),
+                data=payload,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=10,
+            )
+        resp.raise_for_status()
+        return OAuth2Token.model_validate(resp.json())
+
+    @override
+    def exchange_from_redirect_url(
+        self,
+        request: PKCEExchangeFromRedirectUrlRequest,
+        *,
+        cache_session: CacheSession | None = None,
+    ) -> OAuth2Token:
+        redirect_url = str(request.redirect_url)
+        if request.enforce_redirect_uri_match:
+            self._validate_redirect_uri_match(redirect_url)
+
+        code, state = self._parse_code_and_state_from_redirect(redirect_url)
+        if request.expected_state is not None and state != request.expected_state:
+            raise ValueError("state mismatch")
+        if not state and request.code_verifier is None:
+            raise ValueError("no state in redirect URL and no code_verifier supplied")
+
+        code_verifier = request.code_verifier
+        if code_verifier is None:
+            code_verifier = self._lookup_verifier(
+                state=state,
+                delete_after=request.delete_after,
+                cache_session=cache_session,
+            )
+
+        payload = {
+            "grant_type": "authorization_code",
+            "client_id": self.config.client_id,
+            "redirect_uri": str(self.config.redirect_uri),
+            "code": code,
+            "code_verifier": code_verifier,
+        }
+        resp = requests.post(
+            self.config.token_url,
+            data=payload,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        resp.raise_for_status()
+        return OAuth2Token.model_validate(resp.json())
+
+    async def exchange_from_redirect_url_async(
+        self,
+        request: PKCEExchangeFromRedirectUrlRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token:
+        redirect_url = str(request.redirect_url)
+        if request.enforce_redirect_uri_match:
+            self._validate_redirect_uri_match(redirect_url)
+
+        code, state = self._parse_code_and_state_from_redirect(redirect_url)
+        if request.expected_state is not None and state != request.expected_state:
+            raise ValueError("state mismatch")
+        if not state and request.code_verifier is None:
+            raise ValueError("no state in redirect URL and no code_verifier supplied")
+
+        code_verifier = request.code_verifier
+        if code_verifier is None:
+            code_verifier = await self._lookup_verifier_async(
+                state=state,  # type: ignore[arg-type]
+                delete_after=request.delete_after,
+                cache_session=cache_session,
+            )
+
+        payload = {
+            "grant_type": "authorization_code",
+            "client_id": self.config.client_id,
+            "redirect_uri": str(self.config.redirect_uri),
+            "code": code,
+            "code_verifier": code_verifier,
+        }
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                str(self.config.token_url),
+                data=payload,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=10,
+            )
+        resp.raise_for_status()
+        return OAuth2Token.model_validate(resp.json())
+
+    @override
+    def refresh(
+        self,
+        request: RefreshTokenRequest,
+        *,
+        cache_session: CacheSession | None = None,  # kept for symmetry
+    ) -> OAuth2Token:
+        payload = {
+            "grant_type": "refresh_token",
+            "client_id": self.config.client_id,
+            "refresh_token": request.refresh_token,
+        }
+        if request.scope:
+            payload["scope"] = request.scope
+
+        resp = requests.post(
+            self.config.token_url,
+            data=payload,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        # Some IdPs (e.g. Cognito) rotate refresh tokens; keep the new one if present.
+        if "refresh_token" not in data:
+            data["refresh_token"] = request.refresh_token
+
+        return OAuth2Token.model_validate(data)
+
+    async def refresh_async(
+        self,
+        request: RefreshTokenRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token:
+        payload = {
+            "grant_type": "refresh_token",
+            "client_id": self.config.client_id,
+            "refresh_token": request.refresh_token,
+        }
+        if request.scope:
+            payload["scope"] = request.scope
+
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                str(self.config.token_url),
+                data=payload,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=10,
+            )
+        resp.raise_for_status()
+        data = resp.json()
+
+        if "refresh_token" not in data:
+            data["refresh_token"] = request.refresh_token
+
+        return OAuth2Token.model_validate(data)
+
+    # ---- internals ----
+    def _lookup_verifier(
+        self,
+        *,
+        state: str,
+        delete_after: bool,
+        cache_session: CacheSession | None = None,
+    ) -> str:
+        if cache_session is None:
+            raise ValueError("code_verifier not provided and no cache_session configured on client")
+        rec = cache_session.get(f"pkce:{state}")
+        if rec is None or "verifier" not in rec:
+            raise ValueError("code_verifier not found in cache for given state")
+        if delete_after:
+            cache_session.delete(f"pkce:{state}")
+        return rec["verifier"]
+
+    async def _lookup_verifier_async(
+        self,
+        *,
+        state: str,
+        delete_after: bool,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> str:
+        if cache_session is None:
+            raise ValueError("code_verifier not provided and no cache_session configured on client")
+        rec = await cache_session.get(f"pkce:{state}")
+        if rec is None or "verifier" not in rec:
+            raise ValueError("code_verifier not found in cache for given state")
+        if delete_after:
+            await cache_session.delete(f"pkce:{state}")
+        return rec["verifier"]

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/client/standard.py

@@ -0,0 +1,219 @@
+import base64
+import secrets
+from typing import Literal, override
+
+import httpx
+import requests
+from yarl import URL
+
+from ab_core.auth_client.oauth2.schema.authorize import (
+    OAuth2AuthorizeResponse,
+    OAuth2BuildAuthorizeRequest,
+)
+from ab_core.auth_client.oauth2.schema.client_type import OAuth2ClientType
+from ab_core.auth_client.oauth2.schema.exchange import (
+    OAuth2ExchangeCodeRequest,
+    OAuth2ExchangeFromRedirectUrlRequest,
+)
+from ab_core.auth_client.oauth2.schema.refresh import RefreshTokenRequest
+from ab_core.auth_client.oauth2.schema.token import OAuth2Token
+from ab_core.cache.caches.base import CacheAsyncSession, CacheSession
+
+from .base import OAuth2ClientBase
+
+
+class StandardOAuth2Client(
+    OAuth2ClientBase[
+        OAuth2BuildAuthorizeRequest,
+        OAuth2AuthorizeResponse,
+        OAuth2ExchangeCodeRequest,
+        OAuth2ExchangeFromRedirectUrlRequest,
+    ]
+):
+    type: Literal[OAuth2ClientType.STANDARD] = OAuth2ClientType.STANDARD
+
+    # ---------- Authorize URL ----------
+    @override
+    def build_authorize_request(
+        self,
+        request: OAuth2BuildAuthorizeRequest,
+        *,
+        cache_session: CacheSession | None = None,
+    ) -> OAuth2AuthorizeResponse:
+        state = request.state or base64.urlsafe_b64encode(secrets.token_bytes(16)).decode().rstrip("=")
+
+        q: dict[str, str] = {
+            "response_type": request.response_type,
+            "client_id": self.config.client_id,
+            "redirect_uri": str(self.config.redirect_uri),
+            "scope": request.scope,
+            "state": state,
+        }
+        if request.extra_params:
+            q.update({k: str(v) for k, v in request.extra_params.items()})
+
+        url = str(URL(str(self.config.authorize_url)).with_query(q))
+        # Base returns the base response; subclasses can upcast to their own response type
+        return OAuth2AuthorizeResponse(url=url, state=state)
+
+    async def build_authorize_request_async(
+        self,
+        request: OAuth2BuildAuthorizeRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2AuthorizeResponse:
+        state = request.state or base64.urlsafe_b64encode(secrets.token_bytes(16)).decode().rstrip("=")
+
+        q: dict[str, str] = {
+            "response_type": request.response_type,
+            "client_id": self.config.client_id,
+            "redirect_uri": str(self.config.redirect_uri),
+            "scope": request.scope,
+            "state": state,
+        }
+        if request.extra_params:
+            q.update({k: str(v) for k, v in request.extra_params.items()})
+
+        url = str(URL(str(self.config.authorize_url)).with_query(q))
+        # Base returns the base response; subclasses can upcast to their own response type
+        return OAuth2AuthorizeResponse(url=url, state=state)
+
+    @override
+    def exchange_code(
+        self,
+        request: OAuth2ExchangeCodeRequest,
+        *,
+        cache_session: CacheSession | None = None,
+    ) -> OAuth2Token:
+        if not self.config.client_secret:
+            raise ValueError("client_secret required for standard flow")
+        payload = {
+            "grant_type": "authorization_code",
+            "client_id": self.config.client_id,
+            "client_secret": self.config.client_secret,
+            "redirect_uri": str(self.config.redirect_uri),
+            "code": request.code,
+        }
+        resp = requests.post(
+            self.config.token_url,
+            data=payload,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        resp.raise_for_status()
+        return OAuth2Token.model_validate(resp.json())
+
+    async def exchange_code_async(
+        self,
+        request: OAuth2ExchangeCodeRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token:
+        if not self.config.client_secret:
+            raise ValueError("client_secret required for standard flow")
+
+        payload = {
+            "grant_type": "authorization_code",
+            "client_id": self.config.client_id,
+            "client_secret": self.config.client_secret,
+            "redirect_uri": str(self.config.redirect_uri),
+            "code": request.code,
+        }
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                str(self.config.token_url),
+                data=payload,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=10,
+            )
+        resp.raise_for_status()
+        return OAuth2Token.model_validate(resp.json())
+
+    @override
+    def exchange_from_redirect_url(
+        self,
+        request: OAuth2ExchangeFromRedirectUrlRequest,
+        *,
+        cache_session: CacheSession | None = None,
+    ) -> OAuth2Token:
+        if request.enforce_redirect_uri_match:
+            self._validate_redirect_uri_match(str(request.redirect_url))
+        code, state = self._parse_code_and_state_from_redirect(str(request.redirect_url))
+        if request.expected_state is not None and state != request.expected_state:
+            raise ValueError("state mismatch")
+        return self.exchange_code(OAuth2ExchangeCodeRequest(code=code))
+
+    async def exchange_from_redirect_url_async(
+        self,
+        request: OAuth2ExchangeFromRedirectUrlRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token:
+        if request.enforce_redirect_uri_match:
+            self._validate_redirect_uri_match(str(request.redirect_url))
+        code, state = self._parse_code_and_state_from_redirect(str(request.redirect_url))
+        if request.expected_state is not None and state != request.expected_state:
+            raise ValueError("state mismatch")
+        return await self.exchange_code_async(OAuth2ExchangeCodeRequest(code=code))
+
+    @override
+    def refresh(
+        self,
+        request: RefreshTokenRequest,
+        *,
+        cache_session: CacheSession | None = None,  # kept for symmetry
+    ) -> OAuth2Token:
+        if not self.config.client_secret:
+            raise ValueError("client_secret required for standard client refresh")
+
+        payload: dict[str, str] = {
+            "grant_type": "refresh_token",
+            "client_id": self.config.client_id,
+            "client_secret": self.config.client_secret,
+            "refresh_token": request.refresh_token,
+        }
+        if request.scope:
+            payload["scope"] = request.scope  # optional; most IdPs ignore unless narrowing
+
+        resp = requests.post(
+            self.config.token_url,
+            data=payload,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        # Keep original refresh token if server doesn’t rotate it.
+        data.setdefault("refresh_token", request.refresh_token)
+
+        return OAuth2Token.model_validate(data)
+
+    async def refresh_async(
+        self,
+        request: RefreshTokenRequest,
+        *,
+        cache_session: CacheAsyncSession | None = None,
+    ) -> OAuth2Token:
+        if not self.config.client_secret:
+            raise ValueError("client_secret required for standard client refresh")
+
+        payload: dict[str, str] = {
+            "grant_type": "refresh_token",
+            "client_id": self.config.client_id,
+            "client_secret": self.config.client_secret,
+            "refresh_token": request.refresh_token,
+        }
+        if request.scope:
+            payload["scope"] = request.scope
+
+        async with httpx.AsyncClient() as client:
+            resp = await client.post(
+                str(self.config.token_url),
+                data=payload,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=10,
+            )
+        resp.raise_for_status()
+        data = resp.json()
+        data.setdefault("refresh_token", request.refresh_token)
+
+        return OAuth2Token.model_validate(data)

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/schema/authorize.py

@@ -0,0 +1,54 @@
+# ab_core/auth/oauth2/schema/authorize.py
+
+from pydantic import AnyHttpUrl, BaseModel, Field, Literal
+
+from ab_core.pkce.methods import PKCE, S256PKCE
+
+from .client_type import OAuth2ClientType
+
+# ---------- Requests ----------
+
+
+class OAuth2BuildAuthorizeRequest(BaseModel):
+    type: Literal[OAuth2ClientType.STANDARD] = OAuth2ClientType.STANDARD
+    scope: str = "openid profile email"
+    response_type: str = "code"
+    state: str | None = None
+    state_ttl: int | None = None
+    extra_params: dict[str, str] | None = None
+
+
+class PKCEBuildAuthorizeRequest(OAuth2BuildAuthorizeRequest):
+    type: Literal[OAuth2ClientType.PKCE] = OAuth2ClientType.PKCE
+    # If None, the PKCE client will default to S256
+    pkce: PKCE | None = Field(
+        default_factory=S256PKCE,
+    )
+
+
+AuthorizeRequest = Annotated[
+    OAuth2BuildAuthorizeRequest | PKCEBuildAuthorizeRequest,
+    Field(discriminator="type"),
+]
+
+
+# ---------- Responses ----------
+
+
+class OAuth2AuthorizeResponse(BaseModel):
+    type: Literal[OAuth2ClientType.STANDARD] = OAuth2ClientType.STANDARD
+    url: AnyHttpUrl
+    state: str
+
+
+class PKCEAuthorizeResponse(OAuth2AuthorizeResponse):
+    type: Literal[OAuth2ClientType.PKCE] = OAuth2ClientType.PKCE
+    code_verifier: str
+    code_challenge: str
+    code_challenge_method: str
+
+
+AuthorizeResponse = Annotated[
+    OAuth2AuthorizeResponse | PKCEAuthorizeResponse,
+    Field(discriminator="type"),
+]

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/schema/client_type.py

@@ -0,0 +1,6 @@
+from enum import StrEnum
+
+
+class OAuth2ClientType(StrEnum):
+    STANDARD = "STANDARD"
+    PKCE = "PKCE"

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/schema/exchange.py

@@ -0,0 +1,23 @@
+# ab_core/auth/oauth2/schema/exchange.py
+from pydantic import AnyHttpUrl, BaseModel
+
+
+class OAuth2ExchangeCodeRequest(BaseModel):
+    code: str
+
+
+class OAuth2ExchangeFromRedirectUrlRequest(BaseModel):
+    redirect_url: AnyHttpUrl
+    expected_state: str | None = None
+    enforce_redirect_uri_match: bool = True
+
+
+class PKCEExchangeCodeRequest(OAuth2ExchangeCodeRequest):
+    code_verifier: str | None = None
+    state: str | None = None
+    delete_after: bool = True
+
+
+class PKCEExchangeFromRedirectUrlRequest(OAuth2ExchangeFromRedirectUrlRequest):
+    code_verifier: str | None = None
+    delete_after: bool = True

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/schema/oidc.py

@@ -0,0 +1,9 @@
+from pydantic import AnyHttpUrl, BaseModel
+
+
+class OIDCConfig(BaseModel):
+    client_id: str
+    client_secret: str | None = None  # for standard flow
+    redirect_uri: AnyHttpUrl
+    authorize_url: AnyHttpUrl
+    token_url: AnyHttpUrl

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/schema/refresh.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel, SecretStr
+
+
+class RefreshTokenRequest(BaseModel):
+    refresh_token: SecretStr
+    scope: str | None = None  # optional; most providers ignore if omitted

ab_auth_client-0.1.11/src/ab_core/auth_client/oauth2/schema/token.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel, SecretStr
+
+
+class OAuth2Token(BaseModel):
+    """An OAuth2 token model with secrets stored as SecretStr."""
+
+    access_token: SecretStr
+    id_token: SecretStr | None = None
+    refresh_token: SecretStr | None = None
+    expires_in: int
+    scope: str | None = None
+    token_type: str
+
+
+class OAuth2TokenExposed(BaseModel):
+    """An OAuth2 token model with secrets exposed as plain strings."""
+
+    access_token: str
+    id_token: str | None = None
+    refresh_token: str | None = None