xtr-security 3.0.0__py3-none-any.whl

xtr_security/.agents/skills/xtr-security/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: xtr-security
+description: Authentication and authorization for an xtr application — firewalls, bearer access tokens, users and providers, roles, voters, the current user, and password hashing — configured by one SecurityConfig. Use when adding a login or sign-in flow, protecting routes or a whole router, reading the current user in an endpoint or a service, checking a role or a permission, writing a voter or an owner-only rule, declaring a user provider, setting a role hierarchy, hashing or verifying a password, choosing a decision strategy, answering 401 or 403, requiring OAuth2 scopes, verifying a third-party OIDC issuer's tokens, or activating SecurityBundle in an application on xtr-dependency-injection.
+---
+
+# xtr-security
+
+Two questions, kept apart. *Who is calling?* settles on a **token** — a user and the roles fixed
+on them for this request, settled by a **firewall** over a slice of the request space. *May
+they?* asks a set of **voters** and folds the answers into one decision, through access control,
+`IsGranted` or the `Security` facade.
+
+This is the bundle of the family: depend on it and the core (users, tokens, roles, voters), the
+HTTP edge (firewalls, authenticators, the route surface) and the password hasher come with it.
+Write one `SecurityConfig`; the container owns the rest.
+
+## Quick reference
+
+| Want | Write |
+| --- | --- |
+| Protect every route | `app = FastAPI(dependencies=[Firewall()])` |
+| Protect one router by name | `router = Firewall("api")(APIRouter())` |
+| Require a role on a route | `@IsGranted("ROLE_ADMIN")` under the route decorator |
+| Require it over a subject | `dependencies=[IsGranted("BOOK_EDIT", subject=load_book)]` |
+| The current user in an endpoint | `user: Annotated[UserInterface, CurrentUser()]` |
+| The current user, or a decision, in a service | inject `Security` |
+| Refuse in a service | `await security.deny_access_unless_granted("EDIT", book)` |
+| A rule of your own | a class extending `Voter`, registered `@as_service` |
+| Hash a password | inject `UserPasswordHasherInterface` |
+| Require scopes | `api.scoped("books:read")` in a route's `dependencies` |
+
+Import from these surfaces, nothing deeper: `xtr_security` (`Security`), `xtr_security.bundle`
+(every `*Config` and `SecurityBundle`), `xtr_security_core` (users, tokens, voters, errors),
+`xtr_security_http` (`Firewall`, `IsGranted`, `CurrentUser`, badges) and `xtr_password_hasher`.
+
+Self-issued JSON Web Tokens are an add-on package, `xtr-security-jwt`, with a skill of its own
+(`xtr-security-jwt`); it plugs its authenticator into this bundle.
+
+## Configure the firewalls
+
+One `@configure` function in `<app>/config/security.py`. Every field has a default, so start
+small and add.
+
+```python
+from xtr_dependency_injection import configure
+from xtr_security.bundle import (
+    AccessControlConfig,
+    AccessTokenConfig,
+    AutoHasherConfig,
+    FirewallConfig,
+    InMemoryUserProviderConfig,
+    SecurityConfig,
+    ServiceTokenHandlerConfig,
+)
+from xtr_security_core import InMemoryUser
+
+from app.security_handler import MyTokenHandler  # your AccessTokenHandlerInterface service
+
+_ADA = {"password": _ADA_HASH, "roles": ("ROLE_USER",)}
+
+
+@configure
+def security() -> SecurityConfig:
+    return SecurityConfig(
+        providers={  # one entry per name a firewall's `provider` refers to
+            "users": InMemoryUserProviderConfig(users={"ada@example.com": _ADA}),
+        },
+        password_hashers={InMemoryUser: AutoHasherConfig()},
+        role_hierarchy={"ROLE_ADMIN": ("ROLE_USER",)},
+        firewalls={
+            "api": FirewallConfig(
+                pattern=r"^/api",
+                provider="users",
+                authenticators=(
+                    AccessTokenConfig(
+                        token_handler=ServiceTokenHandlerConfig(service=MyTokenHandler),
+                        realm="api",
+                    ),
+                ),
+            ),
+        },
+        access_control=(
+            AccessControlConfig(path=r"^/api/admin", attribute="ROLE_ADMIN"),
+            AccessControlConfig(path=r"^/api", attribute="IS_AUTHENTICATED"),
+        ),
+    )
+```
+
+- Firewalls are matched in order; the first whose `pattern`, `host`, `methods` or
+  `request_matcher` claims the request wins. A firewall with none of them claims everything, so
+  it goes last.
+- `access_control` rules are tried in order too, so the narrow `^/api/admin` rule comes before
+  the broad `^/api`. One attribute per rule: a role, `"IS_AUTHENTICATED"`, `"PUBLIC_ACCESS"`, or
+  an `oauth2_scope(...)` string.
+- `role_hierarchy` expands the token's roles, so `ROLE_ADMIN` need not list `ROLE_USER`.
+- Every string in a bundle config is parameter-resolved: write a literal `%` as `%%`, and read
+  secrets with `env("...")`.
+
+Field tables, the token handler you write, the other provider kinds and the authenticator seam:
+[references/firewalls-and-authenticators.md](references/firewalls-and-authenticators.md).
+
+## Protect a route, and read the user
+
+```python
+from typing import Annotated
+
+from fastapi import APIRouter, FastAPI
+from xtr_security_core import UserInterface
+from xtr_security_http import CurrentUser, Firewall, IsGranted
+
+api = Firewall("api")
+app = FastAPI(dependencies=[Firewall()])
+router = api(APIRouter(prefix="/api"))
+
+
+@router.get("/me")
+async def me(user: Annotated[UserInterface, CurrentUser()]) -> dict[str, object]:
+    return {"identifier": user.get_user_identifier(), "roles": list(user.get_roles())}
+
+
+@router.delete("/books/{isbn}")
+@IsGranted("ROLE_ADMIN")
+async def delete_book(isbn: str) -> None: ...
+```
+
+- `Firewall()` runs the firewall the configuration matches; `Firewall("api")` runs that one and
+  shows its exact scheme in the generated schema. Authentication runs once per request however
+  many firewall dependencies a route carries.
+- `CurrentUser()` raises on an anonymous request, answered `401`. `optional=True` yields `None`
+  instead, for a parameter typed `UserInterface | None`; `CurrentUser(MyUser)` requires a class.
+- `IsGranted` takes a `subject` in `dependencies=[...]`: a path-parameter name, or a callable
+  shared with the endpoint through `Depends`. A denial is `403` for a fully authenticated caller
+  and `401` for an anonymous one, or `status_code=` answered directly.
+
+## Decide in a service
+
+```python
+from xtr_security import Security
+
+
+class PublishBook:
+    def __init__(self, security: Security) -> None:
+        self._security = security
+
+    async def publish(self, book: Book) -> None:
+        await self._security.deny_access_unless_granted("BOOK_PUBLISH", book)
+```
+
+`Security` answers `get_token()`, `get_user()`, `is_granted(attribute, subject=None)`,
+`is_granted_for_user(user, attribute, subject=None)` and `deny_access_unless_granted(...)`, and is
+scoped to the request — a singleton cannot depend on it, so take it as a method argument or make
+the service scoped too.
+
+## Write a voter
+
+A class implementing `VoterInterface` is gathered into the decision manager by the bundle's
+`security.voter` tag. Extend `Voter`, register it as a service, and that is the whole wiring.
+
+```python
+from typing_extensions import override
+from xtr_dependency_injection import as_service
+from xtr_security_core import TokenInterface, Vote, Voter
+
+
+@as_service
+class OrderViewVoter(Voter):
+    @override
+    def supports(self, attribute: object, subject: object) -> bool:
+        return attribute == "ORDER_VIEW" and isinstance(subject, Order)
+
+    @override
+    async def vote_on_attribute(
+        self, attribute: object, subject: object, token: TokenInterface, vote: Vote | None
+    ) -> bool:
+        owner = subject.email == token.get_user_identifier()
+        if vote is not None and not owner:
+            vote.add_reason("the order belongs to another customer")
+        return owner
+```
+
+Keep `supports` narrow: a voter that speaks about everything drowns out the others under the
+affirmative strategy. A one-off rule needs no class — an `IsGranted` attribute may be a callable
+`(IsGrantedContext, subject) -> bool`, run by the built-in closure voter.
+
+Strategies, the built-in voters, scopes and the hierarchy's wildcards:
+[references/authorization.md](references/authorization.md).
+
+## Hash and verify a password
+
+Inject `UserPasswordHasherInterface`; it reads the stored hash off the user itself.
+
+```python
+# in an async service, hashing is CPU-bound: never run it on the event loop
+user.password = await anyio.to_thread.run_sync(hasher.hash_password, user, plain_password)
+ok = await anyio.to_thread.run_sync(hasher.is_password_valid, user, attempt)
+stale = hasher.needs_rehash(user)  # re-store right after a successful check
+```
+
+`password_hashers` maps each user class to its hasher; `AutoHasherConfig()` is argon2id with
+bcrypt and PBKDF2 verifying behind it, so a hash from an older algorithm still verifies and
+`needs_rehash` says when to replace it. Costs, migrations and the command:
+[references/password-hashing.md](references/password-hashing.md).
+
+## Testing
+
+Voters, hashers and the decision are plain objects — test them with no kernel.
+
+```python
+import pytest
+from xtr_security_core import Access, InMemoryUser, UsernamePasswordToken
+
+pytestmark = pytest.mark.anyio
+
+
+async def test_a_voter_refuses_another_customers_order() -> None:
+    ada = InMemoryUser("ada@example.com", roles=["ROLE_USER"])
+    token = UsernamePasswordToken(ada, "api", roles=ada.get_roles())
+    order = Order("lin@example.com")
+
+    assert await OrderViewVoter().vote(token, order, ["ORDER_VIEW"]) is Access.DENIED
+```
+
+A whole decision needs no kernel either: an `AccessDecisionManager(voters=[...],
+strategy=AffirmativeStrategy())` over a `TokenStorage`, asked through
+`AuthorizationChecker(storage, manager)`. The wired services — the token storage, the authorization checker, `Security`, the firewall map —
+are **scoped**, so reach them inside a unit of work:
+
+```python
+from xtr_dependency_injection import unit_of_work
+from xtr_dependency_injection.testing import boot_for_test
+
+async with await boot_for_test(kernel) as booted, unit_of_work(booted.container) as unit:
+    security = await unit.get(Security)
+```
+
+End to end, sign a request the way a client does — call your own token route, send the credential
+back — rather than writing a token into storage by hand.
+
+## Use in an application
+
+`uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
+`SecurityBundle`, which brings the event dispatcher and http-kernel bundles with it. That is the
+steps below a recipe can do; the `concurrent_scoped_access`, `setup(app, kernel)` and
+`config/security.py` steps it prints for you to make.
+
+1. **Install** — `uv add xtr-security`; `[console]` adds `debug:firewall` and
+   `security:hash-password`, `"xtr-security-http[oidc]"` adds OIDC token verification.
+2. **Activate** — `SecurityBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported
+   from `xtr_security.bundle`. Call `setup(app, kernel)` where the application is built, and
+   build the kernel with `concurrent_scoped_access=True` so concurrent requests keep their own
+   token storage.
+3. **Brings along** — the event-dispatcher and http-kernel bundles always; the logging and
+   console bundles whenever those packages are installed.
+4. **Configure** — optional: unconfigured there are no firewalls and the affirmative strategy.
+   `<app>/config/security.py`, a `@configure` function returning a `SecurityConfig`, changes it.
+5. **Environment** — nothing of its own; read your secrets with `env(...)` in the configuration.
+6. **Ignore** — nothing.
+7. **Check** — `debug:bundles` shows `security` as `listed` and `active`, `event_dispatcher` and
+   `http_kernel` as `required`; `debug:firewall [name]` lists or describes the firewalls.
+8. **Remove** — drop the `BUNDLES` entry, delete `<app>/config/security.py`, then
+   `uv remove xtr-security`.
+
+## Errors
+
+Everything the family raises derives from `SecurityError` (`xtr_security_core.exception`).
+
+| Error | Raised when |
+| --- | --- |
+| `InvalidConfigurationError` | A configuration the bundle cannot turn into services — an unknown provider, a non-stateless firewall, an authenticator with no factory. Also a `ValueError` |
+| `AuthenticationError` | Authentication failed, answered `401`. The base of `BadCredentialsError` (rejected), `AuthenticationCredentialsNotFoundError` (none presented — what `CurrentUser()` raises when anonymous), `InvalidAccessTokenError` (a bearer token present but untrusted), `UserNotFoundError`, and the account-state errors `DisabledError`, `LockedError`, `AccountExpiredError` |
+| `AccessDeniedError` | Authorization refused; carries `attributes`, `subject` and `access_decision` |
+| `UnknownFirewallError` | A firewall was asked for by a name none is registered under |
+| `InvalidPasswordError` | A password encodes to more than `MAX_PASSWORD_LENGTH` (4096) UTF-8 bytes |
+
+Catch them where you answer them; the firewall's exception listener already turns an uncaught one
+into the right status and challenge.
+
+## Do not
+
+- Do not read the `Authorization` header, or parse a credential, in an endpoint. That is the
+  firewall's job: write a token handler or an authenticator instead.
+- Do not build `TokenStorage`, `AuthorizationChecker`, `AccessDecisionManager` or
+  `PasswordHasherFactory` by hand — the bundle registers each; inject it.
+- Do not call a hasher on the event loop; wrap it in `anyio.to_thread.run_sync`.
+- Do not store a plaintext password, and do not use `PlaintextHasherConfig()` outside a test.
+- Do not depend on a scoped security service from a singleton; take it as an argument.
+- Do not write a voter whose `supports` is broadly `True`: under the affirmative strategy one
+  careless grant decides everything.
+- Do not set `security=False` on a firewall to make a `401` go away: that opens every request it
+  claims. Give the open routes a `PUBLIC_ACCESS` access-control rule instead.
+- Do not trust a claim from client input when minting a user; read the roles from your own store.

xtr_security/.agents/skills/xtr-security/references/authorization.md

@@ -0,0 +1,149 @@
+# Authorization: voters, strategies, roles and scopes
+
+An attribute is asked over an optional subject. Every voter grants, denies or abstains; a strategy
+folds the answers into one decision. `Security` (or `AuthorizationChecker`) is the one call the
+rest of the application makes.
+
+## The decision, with no container
+
+```python
+from xtr_security_core import (
+    AccessDecisionManager,
+    AffirmativeStrategy,
+    AuthenticatedVoter,
+    AuthenticationTrustResolver,
+    AuthorizationChecker,
+    InMemoryUser,
+    RoleHierarchy,
+    RoleHierarchyVoter,
+    TokenStorage,
+    UsernamePasswordToken,
+)
+
+hierarchy = RoleHierarchy({"ROLE_ADMIN": ("ROLE_USER",)})
+manager = AccessDecisionManager(
+    voters=[
+        RoleHierarchyVoter(hierarchy),
+        AuthenticatedVoter(AuthenticationTrustResolver()),
+        OrderViewVoter(),
+    ],
+    strategy=AffirmativeStrategy(),
+)
+
+ada = InMemoryUser("ada@example.com", roles=["ROLE_USER"])
+storage = TokenStorage()
+storage.set_token(UsernamePasswordToken(ada, "api", roles=ada.get_roles()))
+checker = AuthorizationChecker(storage, manager)
+
+await checker.is_granted("ROLE_USER")  # True
+await checker.is_granted("ORDER_VIEW", Order("lin@example.com"))  # False
+await checker.is_granted("IS_AUTHENTICATED")  # True
+```
+
+In an application the bundle builds exactly this from the configuration, and gathers every voter
+you registered. Build it by hand only in a test.
+
+## Strategies
+
+`AccessDecisionManagerConfig(strategy=…, allow_if_all_abstain=False, allow_if_equal_granted_denied=True)`.
+
+| `strategy` | Grants when |
+| --- | --- |
+| `"affirmative"` (default) | any voter grants |
+| `"consensus"` | grants outnumber denials; a tie follows `allow_if_equal_granted_denied` |
+| `"unanimous"` | no voter denies |
+| `"priority"` | the first voter that does not abstain grants |
+
+A decision every voter abstained on is refused unless `allow_if_all_abstain=True`. Under the
+affirmative default, one voter that grants too eagerly decides everything — which is why a
+voter's `supports` must be narrow.
+
+## The built-in voters
+
+| Voter | Grants on |
+| --- | --- |
+| `RoleHierarchyVoter(hierarchy)` | a role the token's roles *reach* through the hierarchy |
+| `RoleVoter()` | a role the token holds outright |
+| `AuthenticatedVoter(trust_resolver)` | `IS_AUTHENTICATED`, `IS_AUTHENTICATED_FULLY`, `PUBLIC_ACCESS` |
+| `OAuth2ScopeVoter()` | an `OAUTH2_SCOPE(...)` attribute every scope of which the token holds |
+| `ClosureVoter()` | a callable attribute `(IsGrantedContext, subject) -> bool` returning `True` |
+
+The bundle registers all five and adds yours. `PUBLIC_ACCESS` is how an access-control rule says
+"open": it grants whether or not anybody is authenticated.
+
+## Your voter
+
+Extend `Voter` and answer two methods; `@as_service` is all the wiring.
+
+```python
+def supports(self, attribute: object, subject: object) -> bool: ...
+async def vote_on_attribute(
+    self, attribute: object, subject: object, token: TokenInterface, vote: Vote | None
+) -> bool: ...
+```
+
+- `supports` is asked per attribute and subject. Return `False` for anything you do not own; the
+  voter then abstains and the others decide.
+- `vote` is the record of this voter's answer; `vote.add_reason("...")` explains a refusal and
+  shows up in the `AccessDecision` a handler can read.
+- A voter is a service like any other: inject a repository, a clock, a logger.
+- `CacheableVoterInterface` additionally declares `supports_attribute` / `supports_type` so the
+  manager can skip a voter that could never speak.
+
+A one-off rule needs no class at all:
+
+```python
+from xtr_security_core import IsGrantedContext
+
+
+async def can_publish(context: IsGrantedContext, subject: object) -> bool:
+    return await context.is_granted("ROLE_ADMIN")
+
+
+@router.post("/books/{isbn}/publish")
+@IsGranted(can_publish)
+async def publish(isbn: str) -> None: ...
+```
+
+`IsGrantedContext` carries the `token`, its `user`, and `is_granted(...)` for a nested question.
+
+## The role hierarchy
+
+`role_hierarchy={"ROLE_ADMIN": ("ROLE_USER",)}` makes an admin reach the user role, so a token
+needs only the role it really has. Expansion is transitive and safe against cycles. A `*` in a key
+captures a segment and substitutes it into the values, so
+`{"ROLE_TENANT_*_ADMIN": ("ROLE_TENANT_*_USER",)}` makes `ROLE_TENANT_42_ADMIN` reach
+`ROLE_TENANT_42_USER`.
+
+Standalone, `RoleHierarchy(mapping).get_reachable_role_names(roles)` is the same expansion and
+`get_parent_role_names(role)` is one level of it.
+
+## OAuth2 scopes
+
+A scope requirement is an attribute like any other. `oauth2_scope("books:read", "books:write")`
+builds `"OAUTH2_SCOPE(books:read books:write)"`, which goes in an `AccessControlConfig` or an
+`IsGranted`; `parse_oauth2_scope(attribute)` — from `xtr_security_http.authorization` — reads the
+scopes back, or `None` for anything not shaped like one.
+
+On a route, prefer the firewall's own variant, which also adds the scopes to the generated schema:
+
+```python
+api = Firewall("api")
+
+
+@router.get("/books", dependencies=[api.scoped("books:read")])
+async def books() -> list[str]: ...
+```
+
+`api.scoped(...)` shares the one scheme with `api`, so the two are a single security scheme in the
+schema. An access-token authenticator copies the badge's granted `scope` onto the token, and
+`OAuth2ScopeVoter` reads it; a refused scope is answered `403` with an RFC 6750
+`insufficient_scope` challenge.
+
+## Reading a decision
+
+`is_granted(attribute, subject=None, access_decision=None)` fills an `AccessDecision` when given
+one: every `Vote` cast, each with its `voter`, `result` and `reasons`, the deciding strategy's
+name and a `message`. `deny_access_unless_granted(...)` attaches one to the `AccessDeniedError` it
+raises, which is how a handler can tell a caller *why*. With `trace_votes` on (the default in
+debug) each vote is also announced as a `VoteEvent` a listener can log.

xtr_security/.agents/skills/xtr-security/references/firewalls-and-authenticators.md

@@ -0,0 +1,165 @@
+# Firewalls, providers and authenticators
+
+Every field an application writes, and the pieces it writes itself. Import the configurations
+from `xtr_security.bundle`.
+
+## `SecurityConfig`
+
+| Field | Default | What it is |
+| --- | --- | --- |
+| `firewalls` | `{}` | The firewalls, keyed by name, matched in order — first match wins |
+| `providers` | `{}` | The user providers, keyed by the name a firewall's `provider` refers to |
+| `password_hashers` | `{}` | The hasher each user class, `"module:Class"` string or declared name is hashed by |
+| `role_hierarchy` | `{}` | The roles each role reaches, expanding a token's roles |
+| `access_control` | `()` | The access-control rules, tried in order |
+| `access_decision_manager` | affirmative | `AccessDecisionManagerConfig` — how the votes become one decision |
+| `expose_security_errors` | `ExposeSecurityLevel.NONE` | How much of an authentication failure reaches the client |
+| `trace_votes` | `None` | Announce every vote as an event; `None` follows the kernel's debug flag |
+| `authenticator_factories` | built-ins | The factories that build firewalls' authenticators |
+| `token_handler_factories` | built-ins | The factories that build access-token handlers |
+| `user_provider_factories` | built-ins | The factories that build user providers |
+
+A firewall naming a `provider` that is not declared fails the build with
+`InvalidConfigurationError`, as the configuration is written.
+
+## `FirewallConfig`
+
+| Field | Default | What it is |
+| --- | --- | --- |
+| `pattern` | `None` | A regular expression matched against the request path |
+| `host` | `None` | A regular expression matched against the request host |
+| `methods` | `()` | The HTTP methods claimed; every method when empty |
+| `request_matcher` | `None` | A callable `(Request) -> bool`, tried last |
+| `security` | `True` | `False` lets every request the firewall claims through untouched |
+| `stateless` | `True` | Only `True` is accepted; `False` raises `InvalidConfigurationError` |
+| `provider` | `None` | The name of the user provider the firewall loads users from |
+| `user_checker` | `None` | A user-checker service type, or the default in-memory checker |
+| `entry_point` | `None` | The authenticator whose challenge answers an unauthenticated request |
+| `access_denied_handler` | `None` | A handler service type for a denied, fully-authenticated caller |
+| `authenticators` | `()` | The authenticator configurations the firewall runs |
+| `required_badges` | `()` | Badge types every passport must carry |
+
+A secured firewall with no authenticators is refused. A firewall with no `pattern`, `host`,
+`methods` or `request_matcher` claims every request, so register it last.
+
+## `AccessControlConfig`
+
+`AccessControlConfig(path, attribute, host=None, methods=(), ips=(), firewall=None)`. `path` and
+`host` are regular expressions, searched against the request. One attribute per rule, by design:
+a rule needing two conditions is two rules, or one closure attribute.
+
+## User providers
+
+| Configuration | Loads a user from |
+| --- | --- |
+| `InMemoryUserProviderConfig(users={identifier: {"password": …, "roles": (…), "enabled": True}})` | the table written inline |
+| `ChainUserProviderConfig(providers=("db", "ldap"))` | each named provider in turn; needs at least one |
+| `ServiceUserProviderConfig(service=MyUserProvider, qualifier=None)` | a provider the container provides |
+
+Write your own by implementing `UserProviderInterface` from `xtr_security_core`:
+`load_user_by_identifier(identifier)` (raising `UserNotFoundError`) and
+`supports_class(user_class)`. Register it `@as_service` and name it with
+`ServiceUserProviderConfig`. Implement `PasswordUpgraderInterface` as well and the password
+migrating listener re-stores a rehashed password for you after a successful sign-in.
+
+A configured provider is also injectable by name:
+
+```python
+from typing import Annotated
+
+from xtr_dependency_injection import Target
+from xtr_security_core import InMemoryUserProvider
+
+users: Annotated[InMemoryUserProvider, Target("users")]
+```
+
+## Access-token authenticators
+
+`AccessTokenConfig(token_handler, token_extractors=("header",), realm=None)`. Extractors are
+`"header"`, `"query"` and `"body"`, tried in order; the first one's scheme documents the firewall
+in the generated schema. `realm` is named in the `WWW-Authenticate` challenge.
+
+| Token handler | Verifies |
+| --- | --- |
+| `ServiceTokenHandlerConfig(service=MyTokenHandler, qualifier=None)` | with a handler you registered as a service |
+| `OidcTokenHandlerConfig(issuers=(…), audience="…", keyset=… \| discovery_uri=… \| jwks_uri=…)` | a third-party OIDC issuer's tokens; needs the `oidc` extra |
+
+`OidcTokenHandlerConfig` takes **exactly one** key source, and at least one issuer and an
+audience; `algorithms` default to `("RS256",)`, `claim` to `"sub"`, plus `leeway`,
+`enforce_at_jwt_type` and `allow_insecure_http`. `exp` is required on a token: one that never
+expires is refused.
+
+## The token handler you write
+
+A handler turns a token string into a `UserBadge` — the identifier, and how to load the user.
+Raise `InvalidAccessTokenError` for anything it cannot trust; that becomes an `invalid_token`
+challenge.
+
+```python
+from xtr_dependency_injection import as_service
+from xtr_security_core import InMemoryUser
+from xtr_security_http import AccessTokenHandlerInterface, InvalidAccessTokenError, UserBadge
+
+
+@as_service
+class MyTokenHandler(AccessTokenHandlerInterface):
+    async def get_user_badge_from(self, access_token: str) -> UserBadge:
+        if access_token != "s3cret":
+            raise InvalidAccessTokenError("Unknown token.")
+        return UserBadge("ada", user_loader=lambda i: InMemoryUser(i, roles=["ROLE_USER"]))
+```
+
+Leave the `user_loader` out and the firewall's own `provider` loads the user, so the token carries
+identity and your store carries the roles — usually what you want.
+
+## What runs on a request
+
+1. The firewall map matches the request, or the named firewall is taken.
+2. The first authenticator whose `supports()` is not `False` reads the request into a `Passport`
+   of badges and credentials.
+3. Listeners resolve the badges: the user provider gives a `UserBadge` its loader, credentials are
+   verified, the account's pre- and post-authentication checks run.
+4. Every badge must be resolved and every `required_badges` type present, or
+   `BadCredentialsError`.
+5. A token is created and stored; the access map's rule for the request is decided against it.
+
+An unknown user in a password passport is still verified against a dummy hash, so a bad
+identifier and a bad password take the same time.
+
+`expose_security_errors` controls what a client learns: `ExposeSecurityLevel.NONE` reports
+everything as bad credentials, `ACCOUNT_STATUS` reveals disabled, locked and expired accounts,
+`ALL` reveals the failure. Leave it at `NONE` in production.
+
+## Listening to a firewall's events
+
+Each firewall dispatches `CheckPassportEvent`, `AuthenticationTokenCreatedEvent`,
+`AuthenticationSuccessEvent`, `LoginSuccessEvent` and `LoginFailureEvent` on a dispatcher of its
+own. A listener of them on the main dispatcher hears every firewall; to hear one alone, name its
+dispatcher:
+
+```python
+from xtr_event_dispatcher import as_event_listener
+from xtr_security.bundle import firewall_dispatcher_name
+
+
+@as_event_listener(dispatcher=firewall_dispatcher_name("api"))
+def count_api_login(event: LoginSuccessEvent) -> None: ...
+```
+
+In debug mode `debug:event-dispatcher --dispatcher security.event_dispatcher.api` lists that
+firewall's listeners.
+
+## Challenges
+
+The exception listener answers for you: an `AuthenticationError` becomes the firewall's
+entry-point challenge, or a bare `401` with `WWW-Authenticate: Bearer`; an `AccessDeniedError`
+becomes `403`, or the entry-point challenge when the caller is not fully authenticated, or an
+`insufficient_scope` challenge when a scope was the denied attribute.
+
+## Adding a kind of authenticator
+
+Only a library shipping its own bundle needs this. Implement `AuthenticatorFactoryInterface`
+(a `key`, a `priority`, a `config_type` and `create_authenticator(...)`) and prepend it onto the
+security configuration from the bundle's `prepend_extension` hook with `add_authenticator_factory`.
+`add_token_handler_factory` and `add_user_provider_factory` are the same seam for the other two
+registries. An application configures what those factories accept; it does not write factories.