authgate-client 0.1.0__tar.gz

authgate_client-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+.idea/
+.vscode/

authgate_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 — 2026-09-27
+
+First release.
+
+**Added**
+
+- `AuthGate(issuer, audience).verify(token)` — verifies an AuthGate access token and returns the
+  caller as a typed `Identity`. RS256 pinned; `iss`, `aud`, `exp` and `iat` checked; `sub` and
+  `jti` required; `nbf` honoured; `leeway=` clock skew, 60 s by default and at most 300. Keys come
+  from the issuer's discovery document and JWKS, are cached for five minutes, and are refetched on
+  an unknown `kid` at most once every 30 seconds.
+- `Identity` — `account_id`, `tenant_id`, `email`, `superuser`, `permissions`, the verified
+  `claims`, and `may(resource, action)` with the server's superuser rule.
+- FastAPI integration behind the `fastapi` extra: `Depends(auth.identity)` and
+  `Depends(auth.require(resource, action))`, with 401 / 403 / 503 responses.
+- `InvalidTokenError`, `IssuerUnavailableError` and `ConfigurationError`, all derived from
+  `AuthGateError`.

authgate_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bosko Djokic
+
+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.

authgate_client-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: authgate-client
+Version: 0.1.0
+Summary: Verify AuthGate access tokens in Python, with an optional FastAPI integration.
+Project-URL: Homepage, https://github.com/boskodjokic/authgate-python
+Project-URL: Issues, https://github.com/boskodjokic/authgate-python/issues
+Project-URL: Changelog, https://github.com/boskodjokic/authgate-python/blob/main/CHANGELOG.md
+Project-URL: Server, https://github.com/boskodjokic/authgate
+Author: Bosko Djokic
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,authgate,fastapi,jwks,jwt,oidc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyjwt[crypto]>=2.13
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx2>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# authgate-client
+
+[![CI](https://github.com/boskodjokic/authgate-python/actions/workflows/ci.yml/badge.svg)](https://github.com/boskodjokic/authgate-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/authgate-client)](https://pypi.org/project/authgate-client/)
+[![Python](https://img.shields.io/pypi/pyversions/authgate-client)](https://pypi.org/project/authgate-client/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/boskodjokic/authgate-python/blob/main/LICENSE)
+
+Verify [AuthGate](https://github.com/boskodjokic/authgate) access tokens in Python. Framework-free,
+with one dependency — PyJWT and its `crypto` extra — and an optional FastAPI integration. Installed
+as `authgate-client`, imported as `authgate`.
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+
+from authgate import AuthGate, Identity
+
+auth = AuthGate(issuer="https://auth.example.com", audience="https://api.example.com")
+app = FastAPI()
+
+
+@app.get("/materials")
+def list_materials(caller: Annotated[Identity, Depends(auth.identity)]):
+    return materials.for_tenant(caller.tenant_id)
+
+
+@app.delete("/materials/{material_id}")
+def delete_material(material_id: str, caller: Annotated[Identity, Depends(auth.require("material", "delete"))]):
+    materials.delete(material_id, by=caller.account_id)
+```
+
+```bash
+pip install authgate-client              # the verifier
+pip install "authgate-client[fastapi]"   # plus the FastAPI dependencies
+```
+
+## You may not need this
+
+AuthGate publishes a standard `/.well-known/openid-configuration` and JWKS, so any JWT library that
+can fetch a JWKS already verifies its tokens. This package is a convenience, the Python counterpart
+of the server's Spring starter. What it adds is what a hand-written verifier usually gets wrong:
+
+- **The audience is required.** A verifier that skips `aud` accepts every token the issuer ever
+  minted, including tokens meant for a different service. There is no default for "any".
+- **A typed caller.** The `perms` claim arrives as `Identity.permissions`, and
+  `caller.may("material", "update")` applies the server's own rule, superuser included.
+- **Key refresh that cannot be turned against the issuer.** Tokens naming an unknown `kid` trigger
+  at most one JWKS fetch every 30 seconds, however many arrive.
+- **An outage is not a bad token.** If the issuer cannot be reached, the answer is 503, not 401 —
+  a 401 tells well-behaved clients to throw their token away and sign the user out.
+
+## Without FastAPI
+
+`verify` is plain synchronous code, so it works in Flask, Django, a worker or a script:
+
+```python
+from authgate import AuthGate, InvalidTokenError, IssuerUnavailableError
+
+auth = AuthGate(issuer="https://auth.example.com", audience="https://api.example.com")
+
+try:
+    caller = auth.verify(token)
+except InvalidTokenError:
+    ...  # 401
+except IssuerUnavailableError:
+    ...  # 503
+
+if not caller.may("material", "update"):
+    ...  # 403
+```
+
+It is also why the FastAPI dependencies are plain `def`s: FastAPI runs them in its threadpool, so
+the occasional key fetch never blocks the event loop. With the keys cached, verifying a token is
+normally a signature check and nothing else.
+
+## Testing an app that uses it
+
+Override `auth.identity` to stand in a caller. Every `require()` builds on it, so the permission
+checks still run against the identity you supply:
+
+```python
+app.dependency_overrides[auth.identity] = lambda: Identity("acct-1", permissions={"material": frozenset({"read"})})
+```
+
+The dependencies are for HTTP routes, since they read the `Authorization` header. Use them with
+`Depends`, not `Security(..., scopes=...)`: scopes make FastAPI treat each use as a separate
+dependency, and the token would be verified once per use instead of once per request.
+
+## What is checked
+
+| Check | Rule |
+|---|---|
+| Signature | RS256 only. The algorithm is pinned, never read from the token header, which closes `alg: none` and the RSA-key-as-HMAC-secret confusion. It is checked before any key lookup, so such a token is refused as invalid even while the issuer is down |
+| Key | the `kid` header must name an RS256 signing key the issuer publishes. If the issuer cannot be reached to look one up, the answer is 503, not 401 |
+| Issuer | `iss` must equal the discovery document's `issuer` exactly, and that document must name the issuer you configured |
+| Audience | `aud` must contain the audience you configured |
+| Lifetime | `exp` and `iat` required, `nbf` honoured if present, with 60 seconds of clock skew allowed (`leeway=`, up to 300). An `iat` further in the future than that is rejected — stricter than Spring, which checks only `exp` and `nbf` |
+| Required claims | `exp`, `iat`, `iss`, `aud`, `sub`, `jti` |
+| Transport | the issuer must be `https://host[:port][/path]`; plain `http://` is accepted only for `localhost`, `127.0.0.1` and `::1` |
+
+Keys are fetched on first use — constructing an `AuthGate` does no I/O — and cached for five
+minutes. A failed refresh keeps serving the cached keys rather than failing every request — until
+a refresh succeeds, however long that takes, so a key the issuer withdraws during an outage is
+trusted until the verifier can see that it is gone.
+
+## The caller
+
+| `Identity` field | Claim | |
+|---|---|---|
+| `account_id` | `sub` | AuthGate's account id, not the external provider's subject |
+| `tenant_id` | `tenant` | |
+| `email` | `email` | for display and audit |
+| `superuser` | `superuser` | `True` only for a literal JSON `true` |
+| `permissions` | `perms` | `{resource: frozenset(actions)}` |
+| `claims` | all of them | the verified payload; not part of equality, so two tokens for one caller compare equal |
+
+## Errors
+
+| Raised | Meaning | FastAPI response |
+|---|---|---|
+| — | no `Authorization: Bearer` header at all | 401, `WWW-Authenticate: Bearer` |
+| `InvalidTokenError` | the token is not acceptable here | 401, `WWW-Authenticate: Bearer error="invalid_token"` |
+| `IssuerUnavailableError` | the issuer's keys cannot be fetched | 503, with a fixed message; the detail is logged |
+| `ConfigurationError` | the verifier is set up wrong, or the issuer's discovery document contradicts it | raised at construction; 500 if discovered later |
+| — | a missing permission in `require()` | 403, `WWW-Authenticate: Bearer error="insufficient_scope"` |
+
+All three exceptions derive from `AuthGateError`.
+
+The public API is what `authgate` exports — `AuthGate`, `Identity` and the errors above. The
+submodules are implementation, and may change between releases.
+
+## Revocation
+
+AuthGate revokes an access token by adding its `jti` to a denylist on the server. A verifier
+working from the published keys cannot see that list, so a token that was already issued stays
+valid here until it expires. The server's short access-token lifetime — 15 minutes by default — is
+what bounds that window, and revocation is enforced where a new token would be issued. Every
+JWT-issuing provider behaves this way.
+
+## Development
+
+```bash
+pip install -e ".[dev]" "ruff==0.16.9"   # the ruff CI pins
+pytest
+ruff check . && ruff format --check .
+```
+
+The tests run against an in-process fake issuer: a real RSA key, a real JWKS served over real HTTP
+on `127.0.0.1`, and tokens carrying exactly the claims the server issues. That is what makes each
+attack — `alg: none`, HMAC confusion, a foreign key reusing a known `kid`, a tampered payload — a
+short test with no external network.
+
+## License
+
+MIT — see [LICENSE](https://github.com/boskodjokic/authgate-python/blob/main/LICENSE).

authgate_client-0.1.0/README.md

@@ -0,0 +1,156 @@
+# authgate-client
+
+[![CI](https://github.com/boskodjokic/authgate-python/actions/workflows/ci.yml/badge.svg)](https://github.com/boskodjokic/authgate-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/authgate-client)](https://pypi.org/project/authgate-client/)
+[![Python](https://img.shields.io/pypi/pyversions/authgate-client)](https://pypi.org/project/authgate-client/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/boskodjokic/authgate-python/blob/main/LICENSE)
+
+Verify [AuthGate](https://github.com/boskodjokic/authgate) access tokens in Python. Framework-free,
+with one dependency — PyJWT and its `crypto` extra — and an optional FastAPI integration. Installed
+as `authgate-client`, imported as `authgate`.
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+
+from authgate import AuthGate, Identity
+
+auth = AuthGate(issuer="https://auth.example.com", audience="https://api.example.com")
+app = FastAPI()
+
+
+@app.get("/materials")
+def list_materials(caller: Annotated[Identity, Depends(auth.identity)]):
+    return materials.for_tenant(caller.tenant_id)
+
+
+@app.delete("/materials/{material_id}")
+def delete_material(material_id: str, caller: Annotated[Identity, Depends(auth.require("material", "delete"))]):
+    materials.delete(material_id, by=caller.account_id)
+```
+
+```bash
+pip install authgate-client              # the verifier
+pip install "authgate-client[fastapi]"   # plus the FastAPI dependencies
+```
+
+## You may not need this
+
+AuthGate publishes a standard `/.well-known/openid-configuration` and JWKS, so any JWT library that
+can fetch a JWKS already verifies its tokens. This package is a convenience, the Python counterpart
+of the server's Spring starter. What it adds is what a hand-written verifier usually gets wrong:
+
+- **The audience is required.** A verifier that skips `aud` accepts every token the issuer ever
+  minted, including tokens meant for a different service. There is no default for "any".
+- **A typed caller.** The `perms` claim arrives as `Identity.permissions`, and
+  `caller.may("material", "update")` applies the server's own rule, superuser included.
+- **Key refresh that cannot be turned against the issuer.** Tokens naming an unknown `kid` trigger
+  at most one JWKS fetch every 30 seconds, however many arrive.
+- **An outage is not a bad token.** If the issuer cannot be reached, the answer is 503, not 401 —
+  a 401 tells well-behaved clients to throw their token away and sign the user out.
+
+## Without FastAPI
+
+`verify` is plain synchronous code, so it works in Flask, Django, a worker or a script:
+
+```python
+from authgate import AuthGate, InvalidTokenError, IssuerUnavailableError
+
+auth = AuthGate(issuer="https://auth.example.com", audience="https://api.example.com")
+
+try:
+    caller = auth.verify(token)
+except InvalidTokenError:
+    ...  # 401
+except IssuerUnavailableError:
+    ...  # 503
+
+if not caller.may("material", "update"):
+    ...  # 403
+```
+
+It is also why the FastAPI dependencies are plain `def`s: FastAPI runs them in its threadpool, so
+the occasional key fetch never blocks the event loop. With the keys cached, verifying a token is
+normally a signature check and nothing else.
+
+## Testing an app that uses it
+
+Override `auth.identity` to stand in a caller. Every `require()` builds on it, so the permission
+checks still run against the identity you supply:
+
+```python
+app.dependency_overrides[auth.identity] = lambda: Identity("acct-1", permissions={"material": frozenset({"read"})})
+```
+
+The dependencies are for HTTP routes, since they read the `Authorization` header. Use them with
+`Depends`, not `Security(..., scopes=...)`: scopes make FastAPI treat each use as a separate
+dependency, and the token would be verified once per use instead of once per request.
+
+## What is checked
+
+| Check | Rule |
+|---|---|
+| Signature | RS256 only. The algorithm is pinned, never read from the token header, which closes `alg: none` and the RSA-key-as-HMAC-secret confusion. It is checked before any key lookup, so such a token is refused as invalid even while the issuer is down |
+| Key | the `kid` header must name an RS256 signing key the issuer publishes. If the issuer cannot be reached to look one up, the answer is 503, not 401 |
+| Issuer | `iss` must equal the discovery document's `issuer` exactly, and that document must name the issuer you configured |
+| Audience | `aud` must contain the audience you configured |
+| Lifetime | `exp` and `iat` required, `nbf` honoured if present, with 60 seconds of clock skew allowed (`leeway=`, up to 300). An `iat` further in the future than that is rejected — stricter than Spring, which checks only `exp` and `nbf` |
+| Required claims | `exp`, `iat`, `iss`, `aud`, `sub`, `jti` |
+| Transport | the issuer must be `https://host[:port][/path]`; plain `http://` is accepted only for `localhost`, `127.0.0.1` and `::1` |
+
+Keys are fetched on first use — constructing an `AuthGate` does no I/O — and cached for five
+minutes. A failed refresh keeps serving the cached keys rather than failing every request — until
+a refresh succeeds, however long that takes, so a key the issuer withdraws during an outage is
+trusted until the verifier can see that it is gone.
+
+## The caller
+
+| `Identity` field | Claim | |
+|---|---|---|
+| `account_id` | `sub` | AuthGate's account id, not the external provider's subject |
+| `tenant_id` | `tenant` | |
+| `email` | `email` | for display and audit |
+| `superuser` | `superuser` | `True` only for a literal JSON `true` |
+| `permissions` | `perms` | `{resource: frozenset(actions)}` |
+| `claims` | all of them | the verified payload; not part of equality, so two tokens for one caller compare equal |
+
+## Errors
+
+| Raised | Meaning | FastAPI response |
+|---|---|---|
+| — | no `Authorization: Bearer` header at all | 401, `WWW-Authenticate: Bearer` |
+| `InvalidTokenError` | the token is not acceptable here | 401, `WWW-Authenticate: Bearer error="invalid_token"` |
+| `IssuerUnavailableError` | the issuer's keys cannot be fetched | 503, with a fixed message; the detail is logged |
+| `ConfigurationError` | the verifier is set up wrong, or the issuer's discovery document contradicts it | raised at construction; 500 if discovered later |
+| — | a missing permission in `require()` | 403, `WWW-Authenticate: Bearer error="insufficient_scope"` |
+
+All three exceptions derive from `AuthGateError`.
+
+The public API is what `authgate` exports — `AuthGate`, `Identity` and the errors above. The
+submodules are implementation, and may change between releases.
+
+## Revocation
+
+AuthGate revokes an access token by adding its `jti` to a denylist on the server. A verifier
+working from the published keys cannot see that list, so a token that was already issued stays
+valid here until it expires. The server's short access-token lifetime — 15 minutes by default — is
+what bounds that window, and revocation is enforced where a new token would be issued. Every
+JWT-issuing provider behaves this way.
+
+## Development
+
+```bash
+pip install -e ".[dev]" "ruff==0.16.9"   # the ruff CI pins
+pytest
+ruff check . && ruff format --check .
+```
+
+The tests run against an in-process fake issuer: a real RSA key, a real JWKS served over real HTTP
+on `127.0.0.1`, and tokens carrying exactly the claims the server issues. That is what makes each
+attack — `alg: none`, HMAC confusion, a foreign key reusing a known `kid`, a tampered payload — a
+short test with no external network.
+
+## License
+
+MIT — see [LICENSE](https://github.com/boskodjokic/authgate-python/blob/main/LICENSE).

authgate_client-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "authgate-client"
+dynamic = ["version"]
+description = "Verify AuthGate access tokens in Python, with an optional FastAPI integration."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Bosko Djokic" }]
+keywords = ["authgate", "jwt", "oidc", "jwks", "authentication", "fastapi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+# Every release before 2.13 carries a published advisory (CVE-2026-32597, CVE-2026-48522..48526 among
+# them), and 2.10.0 compared `iss` with a substring match (CVE-2024-53861).
+dependencies = ["pyjwt[crypto]>=2.13"]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+dev = ["pytest>=8", "ruff>=0.6", "fastapi>=0.100", "httpx2>=2.0"]
+
+[project.urls]
+Homepage = "https://github.com/boskodjokic/authgate-python"
+Issues = "https://github.com/boskodjokic/authgate-python/issues"
+Changelog = "https://github.com/boskodjokic/authgate-python/blob/main/CHANGELOG.md"
+Server = "https://github.com/boskodjokic/authgate"
+
+[tool.hatch.version]
+path = "src/authgate/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/authgate"]
+
+# An explicit list: hatch honours .gitignore but not .git/info/exclude, where the local-only
+# planning docs are kept out of git, so without it they would ship in the sdist. Anchored with a
+# leading slash — an unanchored pattern matches at any depth, so "tests" or "README.md" nested
+# under docs/ would still be swept in.
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/CHANGELOG.md", "/LICENSE", "/README.md", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

authgate_client-0.1.0/src/authgate/__init__.py

@@ -0,0 +1,24 @@
+"""authgate — verify AuthGate access tokens.
+
+from authgate import AuthGate
+
+auth = AuthGate(issuer="https://auth.example.com", audience="https://api.example.com")
+caller = auth.verify(token)
+caller.may("material", "update")
+"""
+
+from .errors import AuthGateError, ConfigurationError, InvalidTokenError, IssuerUnavailableError
+from .identity import Identity
+from .verifier import AuthGate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthGate",
+    "AuthGateError",
+    "ConfigurationError",
+    "Identity",
+    "InvalidTokenError",
+    "IssuerUnavailableError",
+    "__version__",
+]

authgate_client-0.1.0/src/authgate/errors.py

@@ -0,0 +1,24 @@
+"""The errors this package defines.
+
+The verifier is framework-free: it raises these, and `authgate.fastapi` maps them to status codes.
+"""
+
+
+class AuthGateError(Exception):
+    """Base for every error this package raises."""
+
+
+class ConfigurationError(AuthGateError):
+    """The verifier is set up wrong, or the issuer's discovery document contradicts the setup."""
+
+
+class InvalidTokenError(AuthGateError):
+    """The caller's token is not acceptable here. Maps to 401."""
+
+
+class IssuerUnavailableError(AuthGateError):
+    """The issuer's signing keys could not be fetched. Maps to 503.
+
+    Kept apart from InvalidTokenError on purpose. Reporting an outage as a 401 tells the client its
+    token is bad, and a well-behaved client responds by discarding it and signing the user out.
+    """

authgate_client-0.1.0/src/authgate/fastapi.py

@@ -0,0 +1,68 @@
+"""FastAPI integration — the only module in the package that imports a web framework.
+
+Reached through `AuthGate.identity` and `AuthGate.require`; there is nothing here to import directly.
+
+No `from __future__ import annotations` in this module: FastAPI reads the dependency signatures
+below at runtime, and `require`'s annotation refers to a closure variable that string annotations
+could not resolve.
+"""
+
+import logging
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Annotated
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+from .errors import InvalidTokenError, IssuerUnavailableError
+from .identity import Identity
+
+if TYPE_CHECKING:
+    from .verifier import AuthGate
+
+log = logging.getLogger("authgate")
+
+# auto_error=False so a missing token gets the same 401 and WWW-Authenticate header as a bad one,
+# rather than FastAPI's own response. The scheme still shows up in the OpenAPI document.
+_bearer = HTTPBearer(auto_error=False)
+
+
+def identity_dependency(auth: "AuthGate") -> Callable[..., Identity]:
+    # A plain `def`, not `async def`: FastAPI runs it in its threadpool, so the rare key fetch
+    # never blocks the event loop.
+    def identity(credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_bearer)]) -> Identity:
+        if credentials is None:
+            raise HTTPException(
+                status.HTTP_401_UNAUTHORIZED, "missing bearer token", headers={"WWW-Authenticate": "Bearer"}
+            )
+        try:
+            # Stripped because FastAPI versions disagree on whether they do it: RFC 6750 allows more
+            # than one space after "Bearer", and only newer releases trim it off.
+            return auth.verify(credentials.credentials.strip())
+        except InvalidTokenError as exc:
+            raise HTTPException(
+                status.HTTP_401_UNAUTHORIZED, str(exc), headers={"WWW-Authenticate": 'Bearer error="invalid_token"'}
+            ) from exc
+        except IssuerUnavailableError as exc:
+            # The detail — internal host names, network errors, the caller's kid — is for the log, not
+            # for an unauthenticated caller. Truncated, because part of it is caller-supplied.
+            log.warning("Answering 503, the token issuer is unavailable: %.500s", exc)
+            raise HTTPException(status.HTTP_503_SERVICE_UNAVAILABLE, "the token issuer is unavailable") from exc
+
+    return identity
+
+
+def require_dependency(auth: "AuthGate", resource: str, action: str) -> Callable[..., Identity]:
+    identity = auth.identity
+
+    def require(caller: Annotated[Identity, Depends(identity)]) -> Identity:
+        if not caller.may(resource, action):
+            raise HTTPException(
+                status.HTTP_403_FORBIDDEN,
+                f"missing permission: {action} on {resource}",
+                # RFC 6750 §3.1, and what Spring's resource server answers the same denial with.
+                headers={"WWW-Authenticate": 'Bearer error="insufficient_scope"'},
+            )
+        return caller
+
+    return require

authgate_client-0.1.0/src/authgate/identity.py

@@ -0,0 +1,55 @@
+"""The caller, as an AuthGate access token describes them."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import KW_ONLY, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Identity:
+    """A typed view over a verified token, so handlers are not digging through a claim dict.
+
+    Mirrors `Identity` in the Java starter, so a permission check reads the same in both languages.
+
+    `account_id` is AuthGate's account id (the `sub` claim), not the external provider's subject:
+    a service never needs to know which identity provider someone signed in through.
+
+    `claims` takes no part in equality or hashing: two tokens for the same caller differ in `jti`,
+    `iat` and `exp`, and still describe the same caller.
+    """
+
+    account_id: str
+    # Everything after the account id is keyword-only, so a field added later cannot silently shift
+    # a positional call in someone's code.
+    _: KW_ONLY
+    tenant_id: str | None = None
+    email: str | None = None
+    superuser: bool = False
+    permissions: Mapping[str, frozenset[str]] = field(default_factory=dict, hash=False)
+    claims: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_claims(cls, claims: Mapping[str, Any]) -> Identity:
+        """Build an identity from a payload that has already been verified. `sub` must be present."""
+        permissions: dict[str, frozenset[str]] = {}
+        perms = claims.get("perms")
+        if isinstance(perms, Mapping):
+            for resource, actions in perms.items():
+                # A malformed entry grants nothing rather than failing the whole request — the Java
+                # starter treats one the same way.
+                permissions[resource] = frozenset(map(str, actions)) if isinstance(actions, list) else frozenset()
+        return cls(
+            account_id=str(claims["sub"]),
+            tenant_id=claims.get("tenant"),
+            email=claims.get("email"),
+            # Only a literal JSON true. A string "true" is a malformed token, not a superuser.
+            superuser=claims.get("superuser") is True,
+            permissions=permissions,
+            claims=dict(claims),
+        )
+
+    def may(self, resource: str, action: str) -> bool:
+        """Whether this caller may take `action` on `resource`. Superusers pass everything."""
+        return self.superuser or action in self.permissions.get(resource, frozenset())