xtr-security-openid-connect-server 6.3.0__py3-none-any.whl

xtr_security_openid_connect_server/.agents/skills/xtr-security-openid-connect-server/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: xtr-security-openid-connect-server
+description: How to turn an xtr-security-oauth2-server deployment into an OpenID Connect provider for the authorization code flow with xtr-security-openid-connect-server - ID tokens with nonce, auth_time and at_hash, a /userinfo endpoint, the /.well-known/openid-configuration document, and prompt and max_age handling. Use when an application must offer "sign in with" to its OAuth clients, issue or debug an id_token, answer claims for a signed-in end user, write an IdentityProviderInterface, add the claims a scope reveals, decide prompt=none, prompt=login, prompt=consent or max_age, send an end user back through the login page and return to the authorization request, publish or read the OpenID configuration document, raise consent_required from a consent listener, or fix an InvalidConfigurationError naming identity_provider, login_firewall or a claim set.
+---
+
+# xtr-security-openid-connect-server
+
+An add-on bundle on [xtr-security-oauth2-server](https://github.com/xterr/python-xtr/tree/main/packages/xtr-security-oauth2-server):
+it makes that deployment's authorization server an OpenID Connect provider for the authorization
+code flow. A client asking for the `openid` scope is answered an `id_token` naming the end-user,
+reads that end-user's claims from `/userinfo`, and discovers both from
+`/.well-known/openid-configuration`.
+
+The authorization server knows nothing of this package: the flows, clients, endpoints, consent
+event and `oauth2` firewall key are the `xtr-security-oauth2-server` skill's; firewalls, voters and
+user providers are the `xtr-security` skill's. This skill covers only the identity layer on top.
+
+No logout, no implicit or hybrid flow, no pairwise subjects, no `claims` parameter, no request
+objects, no dynamic client registration, no `id_token` on a refresh.
+
+## Quick reference
+
+- List `OpenIdConnectServerBundle` beside `OAuth2ServerBundle`; it requires that bundle, so listing
+  it alone brings it along. It puts `enable_auth_code_grant=False` and
+  `response_type_class=IdTokenResponse` in place, and appends `openid` to `scopes.available` when
+  that tuple names anything.
+- Write a class implementing `IdentityProviderInterface` (async
+  `get_user_entity_by_identifier(identifier, client)`) and name it in `identity_provider`. The
+  bundle registers it; never register it again.
+- List `PROMPT_LISTENER` (`"openid_connect_server#prompt_listener"`, from
+  `xtr_security_openid_connect_server.bundle`) in the `listeners` of the firewall that signs
+  end-users in, and leave that firewall stateful.
+- Put a firewall carrying `OAuth2AuthenticatorConfig()` in front of `/userinfo`. The endpoint reads
+  no credential of its own, so without one every request is refused.
+- Two route resources: `openid_connect_server` (`/userinfo`, `GET` and `POST`) moves under a
+  prefix; `openid_connect_server_well_known` (`/.well-known/openid-configuration`) stays at the
+  root.
+- The ID token claims `iss`, `sub`, `aud`, `exp`, `iat`, `auth_time`, `nonce` and `at_hash` — no
+  scope claims. `profile`, `email`, `address` and `phone` are answered by `/userinfo` only.
+- The ID token is signed with the authorization server's key, `kid` and
+  `authorization_server.signature_algorithm`, so the published key set verifies it.
+- A consent listener runs below `AUTH_TIME_LISTENER_PRIORITY` (`2048`) and raises
+  `consent_required(event)` when `prompt=none` needs a consent not yet given.
+- Every error derives from `OpenIdConnectServerError`, itself an `OAuth2Error`.
+
+## Configure the provider
+
+```python
+# app/config/packages/openid_connect_server.py
+from xtr_dependency_injection import configure
+from xtr_security_openid_connect_server.bundle import OpenIdConnectServerConfig
+
+from app.identity_provider import PeopleIdentityProvider
+
+__all__ = ["openid_connect_server"]
+
+
+@configure
+def openid_connect_server() -> OpenIdConnectServerConfig:
+    return OpenIdConnectServerConfig(
+        identity_provider=PeopleIdentityProvider,
+        claim_sets={"company": ("company_id",)},
+        login_path="/login",
+        login_firewall="main",
+    )
+```
+
+- Every field has a default, so the bundle builds and boots with nothing written. `/userinfo` is
+  what reports an unset `identity_provider`, by name and with this file.
+- `claim_sets` adds the claims a scope of the application's own reveals. The four scopes OpenID
+  Connect Core defines come held and are refused here.
+- Add the claim scopes the deployment answers for to `scopes.available` in
+  `app/config/packages/oauth2_server.py`, or `/authorize` refuses a client asking for them.
+
+Every field, default and refusal:
+[references/configuration.md](references/configuration.md).
+
+## Say where the end-users are
+
+```python
+# app/identity_provider.py
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_security_core.exception import UserNotFoundError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from xtr_security_oauth2_server_core.entities.client_entity_interface import (
+        ClientEntityInterface,
+    )
+
+    from xtr_security_openid_connect_server.entities import UserClaimsEntityInterface
+
+
+@final
+class Person:
+    def __init__(self, identifier: str, claims: Mapping[str, object]) -> None:
+        self._identifier = identifier
+        self._claims = claims
+
+    def get_identifier(self) -> str:
+        return self._identifier
+
+    async def get_claims(self) -> Mapping[str, object]:
+        return self._claims
+
+
+@final
+class PeopleIdentityProvider:
+    async def get_user_entity_by_identifier(
+        self,
+        identifier: str,
+        client: ClientEntityInterface,
+    ) -> UserClaimsEntityInterface:
+        del client  # Describe a person differently per client here, if a deployment must.
+        if identifier != "alice":
+            raise UserNotFoundError(identifier)
+        return Person("alice", {"name": "Alice", "email": "alice@example.com"})
+```
+
+- The identifier comes from a token this server issued, so a missing user raises
+  `UserNotFoundError` rather than answering `None` — the error the security family's user providers
+  already raise, so an implementation built on one lets it through unchanged.
+- Claims the granted scopes do not reveal are dropped by `ClaimExtractor`, so returning everything
+  a person holds is safe.
+- The container builds the class from its constructor: declare what it needs as typed parameters.
+
+## Serve and guard the endpoints
+
+```python
+# app/config/routes/openid_connect_server.py
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from xtr_http_kernel.routing.decorator import as_routes
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from fastapi import APIRouter, FastAPI
+
+__all__ = ["openid_connect_server"]
+
+
+@as_routes
+def openid_connect_server(app: FastAPI, resources: Mapping[str, APIRouter]) -> None:
+    app.include_router(resources["openid_connect_server"])
+    app.include_router(resources["openid_connect_server_well_known"])
+```
+
+```python
+# app/config/packages/security.py — the two firewalls this package needs
+from xtr_security.bundle import FirewallConfig
+from xtr_security_oauth2_server.bundle import OAuth2AuthenticatorConfig
+from xtr_security_openid_connect_server.bundle import PROMPT_LISTENER
+
+main = FirewallConfig(
+    pattern=r"^/(authorize|login)",
+    stateless=False,
+    provider="people",
+    authenticators=(...,),  # whatever signs an end-user in
+    listeners=(PROMPT_LISTENER,),
+)
+userinfo = FirewallConfig(
+    pattern=r"^/userinfo",
+    provider="people",
+    authenticators=(OAuth2AuthenticatorConfig(),),
+)
+```
+
+- The prompt step must sit on the firewall that signs end-users in, the one `login_firewall` names:
+  only that firewall covers both the authorization endpoint and the login page, and the
+  authorization request waits in its session during a re-login. A stateless one is refused by name
+  the first time a re-login is asked of it.
+- Moving the userinfo endpoint under a prefix moves the `userinfo_endpoint` the document publishes;
+  move the firewall pattern with it.
+
+## Decide prompt, max_age and consent
+
+```python
+from xtr_event_dispatcher import as_event_listener
+from xtr_security_oauth2_server.event.authorization_request_resolve_event import (
+    AuthorizationRequestResolveEvent,
+)
+from xtr_security_oauth2_server.oauth2_events import OAuth2Events
+from xtr_security_openid_connect_server.prompt import consent_required
+from xtr_security_openid_connect_server.request_types.open_id_authorization_request import (
+    OpenIdAuthorizationRequest,
+)
+
+
+@as_event_listener(OAuth2Events.AUTHORIZATION_REQUEST_RESOLVE)  # priority 0, below 2048
+async def ask_for_consent(event: AuthorizationRequestResolveEvent) -> None:
+    request = event.get_authorization_request()
+    asked = request.get_prompt() if isinstance(request, OpenIdAuthorizationRequest) else frozenset()
+    if "none" in asked and not consent_already_given(event):
+        raise consent_required(event)
+    if "consent" in asked or not consent_already_given(event):
+        _ = event.set_response(await consent_page(event))
+        return
+    _ = event.resolve_authorization(AuthorizationRequestResolveEvent.APPROVED)
+```
+
+- `prompt=none` with nobody signed in, or a sign-in older than `max_age`, is answered
+  `login_required` at the validated redirect URI with the `state` echoed — decided by the prompt
+  step, before the endpoint refuses an anonymous request.
+- `prompt=login`, or an exceeded `max_age`, parks the request in the session and redirects to
+  `login_path`; the return trip carries the same request with `login` taken out of `prompt`.
+- A remembered sign-in proves no credential, so the sign-in time is unknown: the ID token states no
+  `auth_time`, and any `max_age` treats it as stale.
+- `prompt=select_account` and an unknown value are `invalid_request`, never ignored.
+
+What each parameter does to a round trip, and what the ID token then carries:
+[references/flows.md](references/flows.md).
+
+## Testing
+
+Serve the application over ASGI inside its own lifespan, both bundles listed, with
+`InMemoryPersistenceConfig()` so each kernel starts empty. Nothing is mocked.
+
+```python
+import httpx
+import pytest
+from xtr_dependency_injection.testing import assert_zero_config
+from xtr_security_openid_connect_server.bundle import OpenIdConnectServerBundle
+
+pytestmark = pytest.mark.anyio
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+async def test_the_bundle_boots_unconfigured() -> None:
+    await assert_zero_config(OpenIdConnectServerBundle)
+
+
+async def test_a_sign_in_is_answered_an_id_token(app) -> None:  # app calls setup(app, kernel)
+    async with app.router.lifespan_context(app):
+        transport = httpx.ASGITransport(app=app)
+        async with httpx.AsyncClient(transport=transport, base_url="https://test") as http:
+            answered = await http.post(
+                "/token",
+                data={
+                    "grant_type": "authorization_code",
+                    "code": "…",
+                    "redirect_uri": "https://dashboard.example.com/callback",
+                    "code_verifier": "…",
+                },
+                auth=("dashboard", "s3cret"),
+            )
+
+    assert "id_token" in answered.json()
+```
+
+- Check the `id_token` with a client implementation, not by re-signing it: the provider's own suite
+  reads it with `xtr-security-http`'s OpenID Connect client, which shares no code with it.
+- `ClaimExtractor`, `ClaimSetEntity`, `token_hash`, `parse_prompt`, `consent_required`,
+  `IdTokenResponse` and `OpenIdAuthCodeGrant` are plain objects: test them with no kernel.
+- Freeze time with `MockClock` from [xtr-clock](https://github.com/xterr/python-xtr/tree/main/packages/xtr-clock)
+  wherever `auth_time`, `max_age` or an expiry is asserted.
+
+## Use in an application
+
+1. **Install** — `uv add xtr-security-openid-connect-server`, beside an application already hosting
+   `xtr-security-oauth2-server`.
+2. **Recipe** — `uv run xtr-recipes recipes:sync` lists `OpenIdConnectServerBundle`, writes a
+   starting `config/packages/openid_connect_server.py` and a
+   `config/routes/openid_connect_server.py` serving the userinfo endpoint at its default path and
+   the document at the root. It prints the rest: the identity provider, the prompt step, the
+   userinfo firewall, the scopes, the issuer, the consent listener.
+3. **Activate** — `OpenIdConnectServerBundle: {"all": True}` in `BUNDLES` in
+   `<app>/config/bundles.py`. The authorization server's `setup(app, kernel)` and
+   `concurrent_scoped_access=True` already apply.
+4. **Brings along** — the OAuth 2.0 authorization server, and the security, clock, event-dispatcher
+   and HTTP-kernel bundles, all required.
+5. **Configure** — `identity_provider`, `login_path` and `login_firewall` in
+   `config/packages/openid_connect_server.py`; `openid_connect_server#prompt_listener` in that
+   firewall's `listeners`, a firewall over `/userinfo`, in
+   `config/packages/security.py`; the issuer and the claim scopes in
+   `config/packages/oauth2_server.py`; a consent listener below `AUTH_TIME_LISTENER_PRIORITY`.
+6. **Environment** — nothing of its own: the ID token is signed with the authorization server's
+   key, so that server's variables are all there are.
+7. **Ignore** — nothing: this package writes no file into the project.
+8. **Remove** — `uv run xtr-recipes recipes:remove xtr-security-openid-connect-server`, then undo
+   the printed steps. The authorization server goes back to its shipped code flow and bearer answer
+   by itself.
+9. **Check** — `debug:bundles` shows `openid_connect_server` active with `oauth2_server` required;
+   `debug:config openid_connect_server`; `GET /.well-known/openid-configuration` names the issuer
+   and the userinfo endpoint.
+
+## Errors
+
+All derive from `OpenIdConnectServerError`, itself an `OAuth2Error`.
+
+| Error | Raised when |
+| --- | --- |
+| `InvalidConfigurationError` | A setting the provider cannot run with, or one missing where a service needs it — `identity_provider` unset, a stateless `login_firewall`, an authorization server whose flow or answer was changed back — named, with the file to write it in |
+| `InvalidArgumentError` | One of this package's objects used wrongly: a claim set naming no scope or one the protocol defines, a negative `max_age`, an unsigned ID token back from the signature provider |
+| `UnsupportedAlgorithmError` | A signature algorithm whose digest its name does not say, or an `EdDSA` key on neither Ed25519 nor Ed448, so no `at_hash` can be taken for it |
+
+A refusal a client is owed is the authorization server's `OAuthServerError`, which the endpoints
+deliver: `invalid_request` from `parse_prompt` and a malformed `max_age` or missing `redirect_uri`,
+`login_required` and `consent_required` for the two refusals a sign-in can end in, and
+`server_error` when the token answer cannot carry an ID token.
+
+## Do not
+
+- Do not register the `identity_provider` class yourself, or alias it under
+  `IdentityProviderInterface`: the bundle does both from the setting.
+- Do not serve `/userinfo` without a firewall carrying `OAuth2AuthenticatorConfig()`, and do not
+  send its token in the request body: the header is the only place it is read.
+- Do not list the prompt step on a stateless firewall, or on one that does not cover the login page
+  as well as the authorization endpoint.
+- Do not change `enable_auth_code_grant`, `response_type_class` or `enable_metadata_endpoint` in an
+  application `@configure`: a transform runs after this bundle's prepend, and the build is failed
+  by name.
+- Do not expect scope claims in the ID token — `name`, `email`, `address`, `phone_number` are
+  `/userinfo`'s — and do not expect an `id_token` from a refresh.
+- Do not put a claim set under `profile`, `email`, `address` or `phone`: an end-user who granted one
+  agreed to what the protocol says it reveals.
+- Do not register a consent listener at or above `AUTH_TIME_LISTENER_PRIORITY`: resolving a request
+  stops the listeners after it, and the sign-in time would never be recorded.
+- Do not try to move `/.well-known/openid-configuration` under a prefix: a client reads it at that
+  path under the issuer.
+- Do not claim certification. The OpenID Foundation suite is an optional manual run, described in
+  the package's `tests/conformance/README.md`, and its outcome is nothing this package states.

xtr_security_openid_connect_server/.agents/skills/xtr-security-openid-connect-server/references/configuration.md

@@ -0,0 +1,95 @@
+# Configuration
+
+Everything the OpenID Connect provider reads, where it is written, and what it refuses.
+
+## `OpenIdConnectServerConfig`
+
+Written in `<app>/config/packages/openid_connect_server.py`, returned from a `@configure`
+function. Frozen, and buildable with no arguments: the bundle builds and boots on these defaults.
+
+| Field | Type | Default | What it does |
+|---|---|---|---|
+| `identity_provider` | `type[IdentityProviderInterface] \| None` | `None` | The application's class that finds a signed-in end-user and the claims they hold. The bundle registers it and aliases it under `IdentityProviderInterface` |
+| `claim_sets` | `Mapping[str, tuple[str, ...]]` | `{}` | The claims a scope of the application's own reveals, by scope |
+| `id_token_ttl` | `timedelta \| None` | `None` | How long an ID token lasts. `None` has it expire with the access token answered beside it |
+| `login_path` | `str` | `"/login"` | Where an end-user asked to sign in again is sent |
+| `login_firewall` | `str` | `"main"` | The firewall signing them in there, whose session keeps the request to return to |
+| `authorize_path` | `str` | `"/authorize"` | Where this deployment serves the authorization endpoint, which is where the prompt step acts |
+
+### What it refuses, at build
+
+`__post_init__` raises `InvalidConfigurationError`, naming the setting and this file, when:
+
+- `login_path`, `login_firewall` or `authorize_path` is the empty string;
+- `id_token_ttl` is set and not positive, which would mint ID tokens already expired;
+- `claim_sets` holds a set for the empty scope;
+- `claim_sets` holds a set for `profile`, `email`, `address` or `phone` — the four scopes OpenID
+  Connect Core defines together with the claims they reveal. Give those claims a scope of the
+  application's own instead.
+
+### What it reports later, by name
+
+- `identity_provider` unset: the provider still builds, boots and runs the console. The first
+  request to `/userinfo` raises `InvalidConfigurationError` naming the setting and the file.
+- A stateless `login_firewall`: raised the first time a re-login is asked of it, naming
+  `stateless`, the firewall, `<app>/config/packages/security.py` and `login_firewall`.
+
+## The authorization server's settings this package reads
+
+Written in `<app>/config/packages/oauth2_server.py`, on `AuthorizationServerConfig`.
+
+| Setting | Read for |
+|---|---|
+| `issuer` | The `iss` every ID token claims, and the origin the document's `userinfo_endpoint` is built on. Never the request's `Host`. Unconfigured, `userinfo_endpoint` is left out |
+| `signature_algorithm` | The ID token's `alg`, the digest `at_hash` is taken with (for `EdDSA`, the one the server key's curve signs with: SHA-512 over Ed25519, SHAKE256 over Ed448), and the one entry in `id_token_signing_alg_values_supported` |
+| `auth_code_ttl`, `refresh_token_ttl`, `require_code_challenge_for_public_clients` | Handed to this package's flow, which the server hands no settings of its own |
+| `scopes.available` | `openid` is appended when the tuple names anything and lacks it. An empty tuple stays empty, so the authorization server's own error about it still fires |
+
+## The three settings this bundle puts in place
+
+`prepend_extension` sets them; `process` fails the build when the resolved configuration does not
+carry them, because an application `@configure` transform runs after a bundle's prepend.
+
+| Setting | Made | Why |
+|---|---|---|
+| `enable_auth_code_grant` | `False` | This package registers the flow answering `authorization_code`; two grants for one type are refused |
+| `response_type_class` | `IdTokenResponse` | The plain bearer answer cannot carry an `id_token`. A subclass of it is accepted |
+| `enable_metadata_endpoint` | left `True` | Without the description there is nothing for a client to discover the provider from |
+
+Each refusal names the setting, says this bundle set it, and points at
+`<app>/config/packages/oauth2_server.py`.
+
+## Claim sets
+
+`ClaimExtractor` holds the protocol's four, then whatever `claim_sets` adds, in the order given.
+`extract(scopes, claims)` keeps only the names a granted scope's set holds **and** the user holds;
+a later scope wins a name two sets both hold.
+
+| Scope | Claims it reveals |
+|---|---|
+| `profile` | `name`, `family_name`, `given_name`, `middle_name`, `nickname`, `preferred_username`, `profile`, `picture`, `website`, `gender`, `birthdate`, `zoneinfo`, `locale`, `updated_at` |
+| `email` | `email`, `email_verified` |
+| `address` | `address` |
+| `phone` | `phone_number`, `phone_number_verified` |
+
+`openid` itself has no set, and reveals nothing. Build sets by hand with
+`ClaimSetEntity(scope, claim_names)`, or bring a class of your own meeting
+`ClaimSetEntityInterface`.
+
+## The published document
+
+`OpenIdMetadataContributor` adds these to the authorization server's description, answered both at
+`/.well-known/openid-configuration` and at the server's own
+`/.well-known/oauth-authorization-server`.
+
+| Field | Value |
+|---|---|
+| `userinfo_endpoint` | `issuer` plus the path this application mounts the endpoint at, read on every call, so a routes file that moved it publishes where it now is. Left out with no issuer, or outside a served request |
+| `subject_types_supported` | `["public"]` |
+| `id_token_signing_alg_values_supported` | `[signature_algorithm]` — one entry, because there is one key |
+| `claims_supported` | Sorted: `sub`, `iss`, `aud`, `exp`, `iat`, `auth_time`, `nonce`, and every claim **name** of every claim set. Never a scope name |
+| `claims_parameter_supported`, `request_parameter_supported`, `request_uri_parameter_supported` | `False` |
+
+A deployment on the authorization server's `RS256` default publishes `RS256`, which is what
+Discovery 1.0 § 3 asks of the document. One configured for another algorithm publishes only that
+one.

xtr_security_openid_connect_server/.agents/skills/xtr-security-openid-connect-server/references/flows.md

@@ -0,0 +1,99 @@
+# Flows
+
+What a sign-in does end to end, and what each request parameter changes.
+
+## The authorization code flow, with `openid`
+
+1. The client sends the browser to `authorize_path` with `response_type=code`, `client_id`,
+   `redirect_uri`, `scope` containing `openid`, and usually `state`, `nonce`, `code_challenge` and
+   `code_challenge_method`. `GET` and a form-encoded `POST` both work.
+2. The login firewall's chain runs. The prompt step acts there when the request carries `prompt` or
+   `max_age`, and nothing else does.
+3. `OpenIdAuthCodeGrant.validate_authorization_request` reads the shipped request first — an
+   unknown client or an unregistered redirect is refused as it always was — then `nonce`, `prompt`
+   and `max_age`. A request asking for `openid` and naming no `redirect_uri` is `invalid_request`,
+   answered as a document, because it named nowhere to send a refusal.
+4. `OAuth2Events.AUTHORIZATION_REQUEST_RESOLVE` is dispatched. `stamp_auth_time` records the
+   sign-in time at priority `2048`; the application's consent listener, below it, approves, denies
+   or answers a page.
+5. The code is minted with the `nonce` and the sign-in time sealed into it beside what the shipped
+   flow seals, and the browser goes back to the redirect URI.
+6. The client redeems the code at `/token`. The shipped half runs first, so an unreadable, expired,
+   spent or another client's code is refused in the protocol's own words. Then the sign-in is read
+   back out of the code and handed to the answer.
+7. The answer is the bearer answer plus `id_token`, signed with the authorization server's key and
+   `kid`.
+
+## What the ID token carries
+
+| Claim | From |
+|---|---|
+| `iss` | `authorization_server.issuer` |
+| `sub` | The resource owner's identifier, as the code named it |
+| `aud` | The client's identifier, as a string |
+| `iat` | The clock, when the answer is built |
+| `exp` | `iat + id_token_ttl`, or the access token's own expiry when that setting is unset |
+| `auth_time` | The newest authentication proof on the firewall's token at the authorization endpoint. Omitted when unknown |
+| `nonce` | The `nonce` the authorization request carried. Omitted when it carried none |
+| `at_hash` | The left half of the digest of the access token string answered beside it, base64url without padding, under the digest the `alg` signs with — for `EdDSA`, the one its key's curve signs with: SHA-512 over Ed25519, 114 octets of SHAKE256 over Ed448 |
+
+Nothing else. `name`, `email`, `address` and `phone_number` are `/userinfo`'s, never the ID token's.
+
+An ID token is answered only when the grant handed the answer an identity **and** the granted
+scopes contain `openid`. The refresh grant hands none, so a refresh answer never carries one.
+
+## `prompt`
+
+Read as a space-separated set. A value this server does not act on, and `none` beside any other
+value, are `invalid_request` — refused rather than ignored, so a client never carries on believing
+it was honoured. `select_account` is therefore refused too.
+
+| Value | Nobody signed in | Signed in |
+|---|---|---|
+| (none) | The endpoint's own `access_denied`, or whatever the login firewall does | The flow goes on |
+| `none` | `login_required` at the validated redirect URI, with `state` echoed back | The flow goes on; the consent listener raises `consent_required(event)` if consent is still needed |
+| `login` | Redirect to `login_path` | Redirect to `login_path` — they sign in again |
+| `consent` | The login firewall's business; then the consent listener's | The consent listener shows its page |
+
+## `max_age`
+
+A whole number of seconds, zero or more; anything else is `invalid_request`.
+
+The sign-in's age is the newest authentication proof on the firewall's token, measured against the
+injected clock. A token that proves nothing — a remembered login — has no known sign-in time, so it
+is never fresh enough for any `max_age`.
+
+| State | Outcome |
+|---|---|
+| Fresh enough | The flow goes on; the ID token states `auth_time` |
+| Too old, or unknown | A re-login: redirect to `login_path`, the request parked |
+| Too old with `prompt=none` | `login_required` — no page may be shown |
+
+## The re-login round trip
+
+`prompt=login`, or an exceeded `max_age`, parks the authorization request in the login firewall's
+session and answers a `302` to `login_path`:
+
+1. The request kept is the original one with `login` taken out of `prompt`, and `prompt` dropped
+   when nothing is left in it — so the return trip goes on to the code instead of asking again. A
+   request that arrived as a posted form is kept as the `GET` the return trip makes.
+2. The end-user signs in on the login page. The firewall sends them back to the parked path.
+3. The chain runs again. `prompt` no longer asks for a re-login, the sign-in is new, and the flow
+   goes on.
+
+The firewall must keep a session for step 1. A stateless one raises `InvalidConfigurationError`
+naming `stateless`, the firewall and `login_firewall`.
+
+## `/userinfo`
+
+| Request | Answer |
+|---|---|
+| `GET` or form `POST` with a bearer token granted `openid`, naming an end-user | `200`, `application/json`, `cache-control: no-store`, `{"sub": …, **claims}` |
+| No token, or a token this server did not issue | `401` `invalid_token`, with a `Bearer` challenge |
+| A client-credentials token, whose caller names no end-user | `401` `invalid_token` |
+| A token not granted `openid` | `403` `insufficient_scope` |
+| A `POST` whose `Content-Type` is not `application/x-www-form-urlencoded`, or that names none — even with no body | `400` `invalid_request` |
+
+`sub` is answered first and is the identifier the ID token named, so a client can compare them; no
+claim of the identity provider's replaces it, not even one called `sub`. The token is read from the
+`Authorization` header only — a token in the form body alone is not read.

xtr_security_openid_connect_server/__init__.py

@@ -0,0 +1,21 @@
+"""OpenID Connect for the xtr OAuth 2.0 authorization server.
+
+:data:`AUTH_TIME_LISTENER_PRIORITY` is the priority the provider records the
+sign-in time at, on the authorization server's consent event; an application's
+consent listener runs below it.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .event_listener.auth_time_listener import AUTH_TIME_LISTENER_PRIORITY
+
+__all__ = ["AUTH_TIME_LISTENER_PRIORITY", "__version__"]
+
+try:
+    __version__ = version("xtr-security-openid-connect-server")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree with no installed metadata to read; having no
+    # version is better than refusing to import.
+    __version__ = "0+unknown"

xtr_security_openid_connect_server/_endpoint_paths.py

@@ -0,0 +1,32 @@
+"""Where each endpoint of the provider lives by default, and what its route is called.
+
+The route loaders contribute each route at its default path under its name;
+a routes file may move it, and whatever publishes its URL finds it by the
+endpoint it calls, so it is published where it is served.
+"""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+__all__ = ["CONFIGURATION_PATH", "ROUTE_NAMES", "USERINFO_PATH"]
+
+#: Where a client reads the claims of the end-user a token was issued for.
+USERINFO_PATH: Final = "/userinfo"
+
+#: Where a client discovers the provider. Fixed under the issuer, so a routes
+#: file leaves it at the root (OpenID Connect Discovery 1.0, Section 4).
+CONFIGURATION_PATH: Final = "/.well-known/openid-configuration"
+
+#: What each route is called, so an application can build a URL to one.
+#: Read-only: the route loaders read it and do not own it.
+ROUTE_NAMES: Final[Mapping[str, str]] = MappingProxyType(
+    {
+        USERINFO_PATH: "openid_connect_server_userinfo",
+        CONFIGURATION_PATH: "openid_connect_server_configuration",
+    },
+)

xtr_security_openid_connect_server/bundle/__init__.py

@@ -0,0 +1,17 @@
+"""The bundle wiring the OpenID Connect provider into an application.
+
+An application lists :class:`OpenIdConnectServerBundle`, which brings the
+OAuth 2.0 authorization server's bundle along, and configures it with an
+:class:`OpenIdConnectServerConfig`.
+
+:data:`PROMPT_LISTENER` is the qualifier of the chain step deciding ``prompt``
+and ``max_age``: the application lists it in the ``listeners`` of the firewall
+that signs end-users in.
+"""
+
+from __future__ import annotations
+
+from .openid_connect_server_bundle import PROMPT_LISTENER, OpenIdConnectServerBundle
+from .openid_connect_server_config import OpenIdConnectServerConfig
+
+__all__ = ["PROMPT_LISTENER", "OpenIdConnectServerBundle", "OpenIdConnectServerConfig"]