masks-client 0.2.0__tar.gz

masks_client-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

masks_client-0.2.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## [0.2.0](https://github.com/masksrb/masks/compare/python-v0.1.0...python-v0.2.0) (2026-10-13)
+
+
+### Features
+
+* **python:** a FastAPI app keeps its sessions in an async store, so waiting on Redis or a database holds up no other request ([f285a95](https://github.com/masksrb/masks/commit/f285a9521f9a40552c5f63d0318653b333c39d87))
+* **python:** a FastAPI app signs people in through masks, guards routes by privilege, and accepts tokens ([6265b69](https://github.com/masksrb/masks/commit/6265b696fd4c53b33879afeac20704e5ff28539d))
+* **python:** a Python app signs people in with the code flow, shakes hands with masks, and holds delegations ([f649f92](https://github.com/masksrb/masks/commit/f649f92e62baadaf4a16bbb1893c418a20e8e4b4))
+* **python:** a sign-in checks that masks still knows the app, and sends it back through the handshake when not ([d1a16cd](https://github.com/masksrb/masks/commit/d1a16cd442ef55e3b724d181c72b0f71f0389ba1))
+* **python:** a verifier remembers DPoP proofs in a replay store that several processes can share ([209c4ca](https://github.com/masksrb/masks/commit/209c4ca460de76ae8d01f1b64a6b45683c8643d4))
+* **python:** an app enrolls and unenrolls its own machines, introspects tokens, and exchanges them ([9bc4070](https://github.com/masksrb/masks/commit/9bc4070ec296f1d9e345da89a471192a99b7f8c8))
+* **python:** Django and Flask apps sign people in through masks with the same routes and privileges ([a662f29](https://github.com/masksrb/masks/commit/a662f29a7134ba01d42f811f9bd6d902f0732873))
+* **python:** requests that share an expired sign-in refresh it once, and back-channel logout ends cookie sessions ([7b5d731](https://github.com/masksrb/masks/commit/7b5d731a75af344fad66c0c4fda6385a751b6936))
+
+
+### Fixes
+
+* **python:** a session holds to the issuer that signed it in, a back-channel request over 64 KB is refused unread, and an answer that changes the session stays out of shared caches ([443c695](https://github.com/masksrb/masks/commit/443c695046e018db13aa795dd034dc86393393fc))
+* **python:** a signed-in person's picture is the app's avatar route when masks holds a photo, so it no longer answers 401 in the browser ([ac6283b](https://github.com/masksrb/masks/commit/ac6283b5b5569e1c740aa4e5bfd0a938179a5f8e))
+* **python:** a verifier that cannot reach its keys or replay store answers 503 instead of rejecting the token ([0396e55](https://github.com/masksrb/masks/commit/0396e55fd80793e225ec1893f51fbdaf60c53da0))
+* **python:** Flask and Django read the session only when a request needs it, cap a back-channel request at 64 KB, and refuse an async store at startup ([09ccf0e](https://github.com/masksrb/masks/commit/09ccf0e38bc3124df6ce3ccd51c4dcab31906a85))
+* **python:** signing out everywhere returns to a registered address, and no other site can sign anyone out ([e12d0ec](https://github.com/masksrb/masks/commit/e12d0ec3ba8042eca34a97dbe2e65598b701d73f))
+* **python:** the Reconnect button on the connection page reaches masks, and no other site can frame a masks page ([4e204e0](https://github.com/masksrb/masks/commit/4e204e0f972e8109b15fc885d04e8e6e926a91d3))
+
+
+### Documentation
+
+* each language has a group under Reference, with an overview, a page per framework, and its API reference ([64b7837](https://github.com/masksrb/masks/commit/64b7837e0484d11ddd5b4d926fc4aa800c06ed81))
+* each language's guide sits in the sidebar, and Other languages is gone ([86e863f](https://github.com/masksrb/masks/commit/86e863f52d92c7aaf9649d284e70787e17ac1b6e))
+* each SDK keeps a TODO of the cleanups, security follow-ups, and testing left from the framework integrations ([4c4353b](https://github.com/masksrb/masks/commit/4c4353b63713700034c78f3d3c0b3b45ac7b50b3))
+* **python:** the Python SDK installs from its release tag, since masks-client is not on PyPI yet ([f59ee0f](https://github.com/masksrb/masks/commit/f59ee0f5a93001a0e315684ede4b37e25c79e177))
+* **python:** the TODO records the live FastAPI run and what it left out ([2840e96](https://github.com/masksrb/masks/commit/2840e967840f3c744b729d31bfc896733d15844c))
+* **python:** the TODO records the live Flask run ([765c5b1](https://github.com/masksrb/masks/commit/765c5b15e99c734ddc7bb93b00dd8e16e332d3b3))
+
+## 0.1.0 (2026-10-11)
+
+
+### Features
+
+* **python:** a Python service or machine signs in to masks as itself with a key, holds its tokens to a second key with DPoP, enrolls with an initial access token, and an API checks those tokens ([ecbc546](https://github.com/masksrb/masks/commit/ecbc5460507ab7a2e1a99e4d17325266ced7d14d))

masks_client-0.2.0/LICENSE

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

masks_client-0.2.0/PKG-INFO

@@ -0,0 +1,316 @@
+Metadata-Version: 2.5
+Name: masks-client
+Version: 0.2.0
+Summary: Sign a Python service or machine in to masks, hold its tokens to a key with DPoP, and check masks access tokens in an API.
+Project-URL: Homepage, https://masks.pages.dev
+Project-URL: Source, https://github.com/masksrb/masks/tree/main/python
+Project-URL: Changelog, https://github.com/masksrb/masks/blob/main/python/CHANGELOG.md
+Author-email: Jon Geiger <jon@geiger.to>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,dpop,masks,oauth,openid-connect
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.5
+Requires-Dist: cryptography>=44
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: pyjwt>=2.10
+Provides-Extra: django
+Requires-Dist: django>=5.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3.1; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# masks for Python
+
+`masks-client` connects a Python web app, service, or machine to masks. It signs
+people in, gets tokens as a client, and checks them as an API. Every call has a synchronous form and an
+`async` one.
+
+```sh
+pip install "masks-client @ git+https://github.com/masksrb/masks@python-v0.1.0#subdirectory=python"
+```
+
+The package installs from its release tag and is not on PyPI yet. It imports as
+`masks` and needs Python 3.10 or later.
+
+| Covers | |
+| --- | --- |
+| Discovery | The issuer's document, checked against the address it was fetched from. |
+| Registration | Redeeming an initial access token, then reading, updating, and deleting the client. |
+| Enrollment | An app asking for initial access tokens for its own machines, and unenrolling them. |
+| Client authentication | `client_secret_basic`, `client_secret_post`, `private_key_jwt`, and `none`. |
+| Grants | Client credentials, refresh tokens, the device flow, and token exchange. |
+| DPoP | Tokens held to a key, and proofs on every request an `httpx` client sends. |
+| Revocation | Access and refresh tokens. |
+| Introspection | Asking the issuer whether a token is still active. |
+| Checking tokens | `at+jwt` access tokens, including DPoP-bound ones, in any framework or as ASGI middleware. |
+
+`masks.fastapi`, `masks.django`, and `masks.flask` sign people in to a web app.
+See [Python apps](https://masks.pages.dev/reference/python/) for the walkthrough and
+[masks-client](https://masks.pages.dev/reference/python/client/) for every setting and
+call.
+
+## A machine signs in as itself
+
+A machine keeps two P-256 keys. One signs its client assertions and the other
+holds its tokens, so a token copied off the machine is useless without the key.
+
+```python
+import json
+import masks
+
+key = masks.Key.generate()
+dpop = masks.Key.generate()
+
+saved = json.dumps({"key": key.to_jwk(), "dpop": dpop.to_jwk()})
+key = masks.Key.from_jwk(json.loads(saved)["key"])
+```
+
+`to_jwk()` writes the private key, so keep the file readable only by the
+machine's service user. `key.jwks()` is the public half to register.
+
+```python
+issuer = masks.discover("https://auth.example.com")
+
+client = masks.Client(issuer, client_id, key=key, dpop=dpop)
+token = client.client_credentials(scope=["files:read"], resource=["https://files.example.com"])
+```
+
+The client authenticates with `client_secret_basic` when `secret` is set and
+with `private_key_jwt` when `key` is. Pass `method` to choose another. When
+`dpop` is set, a token that comes back unbound is refused.
+
+## Enrolling with an initial access token
+
+A manager approves the client in masks, and masks gives out an initial access
+token for it. The machine redeems the token once and keeps what comes back.
+
+```python
+registration = masks.Client.register(issuer, masks.ClientMetadata(), initial_access_token)
+client = masks.Client.from_registration(issuer, registration, key=key, dpop=dpop)
+```
+
+`read_registration`, `update_registration`, and `delete_registration` manage
+the client with its registration access token. They send that token only to the
+issuer's own origin.
+
+## Enrolling machines as an app
+
+An approved app that has claimed a namespace enrolls machines of its own, such
+as an agent it installs on each computer. It asks the issuer's
+`enrollment_endpoint` for an initial access token and hands the token to the
+machine, which registers with it as above.
+
+```python
+app = masks.Client(issuer, app_id, secret=app_secret)
+
+enrollment = app.enroll(scope=["xixo:agent"], client_name="nas", expires_in=900)
+enrollment.initial_access_token
+enrollment.expires_at
+```
+
+The app authenticates the way it does at the token endpoint. Every scope must
+fall under one of the app's namespaces. `expires_in` is between 60 and 3600
+seconds and defaults to 15 minutes. The token is spent the first time a machine
+registers with it.
+
+```python
+app.unenroll(machine_client_id)
+```
+
+`unenroll` archives the machine and revokes every token it holds. Unenrolling
+it again succeeds as well. A client the app did not enroll raises `masks.Error`
+with `status` 404.
+
+## Calling an API
+
+`client.auth` returns an `httpx.Auth` that fetches and reuses tokens and signs
+each request. It sends tokens only to the origins it is given, and `httpx`
+drops the token when a redirect leaves that origin.
+
+```python
+import httpx
+
+source = client.credentials_source(scope=["files:read"], resource=["https://files.example.com"])
+
+with httpx.Client(auth=client.auth(source, "https://files.example.com")) as api:
+    response = api.get("https://files.example.com/files")
+```
+
+A held token goes out as `Authorization: DPoP` with a fresh proof, and a server
+that asks for a DPoP nonce is answered once. `refresh_source` renews a token
+with its refresh token and hands each rotated token to `keep` to be saved.
+
+## Exchanging a token
+
+`exchange` trades a token for a new one under RFC 8693. A service that receives
+a caller's access token exchanges it for a token to another API, acting on the
+caller's behalf.
+
+```python
+token = client.exchange(
+    subject_token,
+    scope=["files:read"],
+    resource=["https://files.example.com"],
+    requested_lifetime=300,
+)
+```
+
+The subject is an access token unless `subject_token_type` says
+`masks.ID_TOKEN_TYPE`. `actor_token` names another party in the token's `act`
+claim. The new token lasts no longer than the subject token. When the client
+has a `dpop` key the new token is held to it, and a subject token held to a key
+is exchanged only with a proof from that same key.
+
+`requested_token_type=masks.UPSTREAM_ACCESS_TOKEN_TYPE` with a connection's id
+in `audience` releases the access token masks holds for that connection through
+a delegation. That token is a Bearer token from the provider, so it comes back
+unbound with `issued_token_type` naming the upstream type.
+
+## Async
+
+`masks.AsyncClient` has the same methods as `masks.Client`, awaited, and
+`masks.adiscover` discovers an issuer.
+
+```python
+issuer = await masks.adiscover("https://auth.example.com")
+
+async with masks.AsyncClient(issuer, client_id, key=key, dpop=dpop) as client:
+    source = client.credentials_source(resource=["https://files.example.com"])
+
+    async with httpx.AsyncClient(auth=client.auth(source, "https://files.example.com")) as api:
+        response = await api.get("https://files.example.com/files")
+```
+
+## The device flow
+
+A machine with no browser shows a code that a person approves on another
+device.
+
+```python
+device = client.device_authorization(scope=["openid", "offline_access"])
+print(f"Open {device.verification_uri} and enter {device.user_code}")
+
+token = client.await_device(device)
+```
+
+`await_device` polls at the interval masks names, slows down when asked, and
+stops when the code expires. The synchronous form takes a `timeout` in seconds,
+and the async form stops when its task is cancelled.
+
+## Checking access tokens
+
+`masks.Verifier` checks a token from any framework. Pass the method, the URL
+the client used, and the request's headers.
+
+```python
+verifier = masks.Verifier(issuer, "https://files.example.com", public_url="https://files.example.com")
+
+claims = verifier.authenticate(request.method, request.url, request.headers)
+claims.has_scope("files:read")
+```
+
+The verifier checks the signature against the issuer's published keys, the
+`at+jwt` type, the issuer, the audience, and the expiry. A DPoP-bound token
+needs a proof signed by its key, made for this method and URL, made in the last
+minute, and not seen before. A failed check raises `masks.InvalidToken`.
+
+When the verifier cannot reach the issuer's keys, or its replay store fails, it
+raises `masks.Unavailable`. The token may still be good, so answer `503` and
+let the client try again with the same token.
+
+Set `public_url` when a proxy sits in front of the API, since a proof names the
+address the client used.
+
+### Replayed proofs
+
+A verifier keeps the proofs it has seen in the process's memory. An API that
+runs in several processes passes `replay` an object whose `first(key,
+expires_in)` answers `True` only the first time it sees a key across every
+process, and `False` after that, for `expires_in` seconds.
+
+```python
+class RedisReplay:
+    def __init__(self, redis):
+        self.redis = redis
+
+    def first(self, key, expires_in):
+        return bool(self.redis.set(f"dpop:{key}", 1, nx=True, ex=expires_in))
+
+
+verifier = masks.Verifier(issuer, "https://files.example.com", replay=RedisReplay(redis))
+```
+
+`AsyncVerifier` also takes a store whose `first` is a coroutine, and
+`Verifier` raises `TypeError` when given one. An answer of `False` raises
+`masks.InvalidToken`. When the store raises or answers anything other than
+`True` or `False`, the verifier raises `masks.Unavailable` from the store's
+error. `masks.MemoryReplayStore` is the default, and one instance can be shared
+between verifiers in the same process.
+
+### Introspection
+
+A verifier that checks the JWT sees a revoked token as valid until it expires.
+`introspect` asks the issuer.
+
+```python
+found = client.introspect(token, "access_token")
+found.active and found.has_scope("files:read")
+```
+
+The issuer answers `active` only to the client the token was issued to, or to
+an approved client whose resources include one of the token's audiences. A
+token that is not active has no scopes. An answer that names another issuer
+raises `masks.Error`.
+
+### ASGI and FastAPI
+
+`masks.asgi.Middleware` checks every request with an `AsyncVerifier` and
+answers `401` with `WWW-Authenticate` challenges when the check fails. It
+answers `503` with no challenge when the verifier raises `masks.Unavailable`.
+The claims are at `request.state.masks_claims`.
+
+```python
+from fastapi import Depends, FastAPI, HTTPException, Request
+from masks.asgi import Middleware
+
+verifier = masks.AsyncVerifier(issuer, "https://files.example.com", public_url="https://files.example.com")
+
+app = FastAPI()
+app.add_middleware(Middleware, verifier=verifier)
+
+
+def reading(request: Request) -> masks.Claims:
+    claims = request.state.masks_claims
+
+    if not claims.has_scope("files:read"):
+        raise HTTPException(403)
+
+    return claims
+
+
+@app.get("/files")
+async def files(claims: masks.Claims = Depends(reading)):
+    return {"for": claims.subject}
+```
+
+### Django and Flask
+
+Call `Verifier.authenticate` in a view decorator or a `before_request` hook.
+In Django, pass `request.method`, `request.build_absolute_uri()`, and
+`request.headers`. In Flask, pass `request.method`, `request.url`, and
+`request.headers`. Answer `401` when it raises `masks.InvalidToken`, and `503`
+when it raises `masks.Unavailable`.
+
+## Plain HTTP
+
+Every URL is `https`, except on this machine: `localhost`, a `.localhost` name,
+or a loopback address. `allow_plain_http=True` on `discover` lifts that for a
+private network.

masks_client-0.2.0/README.md

@@ -0,0 +1,287 @@
+# masks for Python
+
+`masks-client` connects a Python web app, service, or machine to masks. It signs
+people in, gets tokens as a client, and checks them as an API. Every call has a synchronous form and an
+`async` one.
+
+```sh
+pip install "masks-client @ git+https://github.com/masksrb/masks@python-v0.1.0#subdirectory=python"
+```
+
+The package installs from its release tag and is not on PyPI yet. It imports as
+`masks` and needs Python 3.10 or later.
+
+| Covers | |
+| --- | --- |
+| Discovery | The issuer's document, checked against the address it was fetched from. |
+| Registration | Redeeming an initial access token, then reading, updating, and deleting the client. |
+| Enrollment | An app asking for initial access tokens for its own machines, and unenrolling them. |
+| Client authentication | `client_secret_basic`, `client_secret_post`, `private_key_jwt`, and `none`. |
+| Grants | Client credentials, refresh tokens, the device flow, and token exchange. |
+| DPoP | Tokens held to a key, and proofs on every request an `httpx` client sends. |
+| Revocation | Access and refresh tokens. |
+| Introspection | Asking the issuer whether a token is still active. |
+| Checking tokens | `at+jwt` access tokens, including DPoP-bound ones, in any framework or as ASGI middleware. |
+
+`masks.fastapi`, `masks.django`, and `masks.flask` sign people in to a web app.
+See [Python apps](https://masks.pages.dev/reference/python/) for the walkthrough and
+[masks-client](https://masks.pages.dev/reference/python/client/) for every setting and
+call.
+
+## A machine signs in as itself
+
+A machine keeps two P-256 keys. One signs its client assertions and the other
+holds its tokens, so a token copied off the machine is useless without the key.
+
+```python
+import json
+import masks
+
+key = masks.Key.generate()
+dpop = masks.Key.generate()
+
+saved = json.dumps({"key": key.to_jwk(), "dpop": dpop.to_jwk()})
+key = masks.Key.from_jwk(json.loads(saved)["key"])
+```
+
+`to_jwk()` writes the private key, so keep the file readable only by the
+machine's service user. `key.jwks()` is the public half to register.
+
+```python
+issuer = masks.discover("https://auth.example.com")
+
+client = masks.Client(issuer, client_id, key=key, dpop=dpop)
+token = client.client_credentials(scope=["files:read"], resource=["https://files.example.com"])
+```
+
+The client authenticates with `client_secret_basic` when `secret` is set and
+with `private_key_jwt` when `key` is. Pass `method` to choose another. When
+`dpop` is set, a token that comes back unbound is refused.
+
+## Enrolling with an initial access token
+
+A manager approves the client in masks, and masks gives out an initial access
+token for it. The machine redeems the token once and keeps what comes back.
+
+```python
+registration = masks.Client.register(issuer, masks.ClientMetadata(), initial_access_token)
+client = masks.Client.from_registration(issuer, registration, key=key, dpop=dpop)
+```
+
+`read_registration`, `update_registration`, and `delete_registration` manage
+the client with its registration access token. They send that token only to the
+issuer's own origin.
+
+## Enrolling machines as an app
+
+An approved app that has claimed a namespace enrolls machines of its own, such
+as an agent it installs on each computer. It asks the issuer's
+`enrollment_endpoint` for an initial access token and hands the token to the
+machine, which registers with it as above.
+
+```python
+app = masks.Client(issuer, app_id, secret=app_secret)
+
+enrollment = app.enroll(scope=["xixo:agent"], client_name="nas", expires_in=900)
+enrollment.initial_access_token
+enrollment.expires_at
+```
+
+The app authenticates the way it does at the token endpoint. Every scope must
+fall under one of the app's namespaces. `expires_in` is between 60 and 3600
+seconds and defaults to 15 minutes. The token is spent the first time a machine
+registers with it.
+
+```python
+app.unenroll(machine_client_id)
+```
+
+`unenroll` archives the machine and revokes every token it holds. Unenrolling
+it again succeeds as well. A client the app did not enroll raises `masks.Error`
+with `status` 404.
+
+## Calling an API
+
+`client.auth` returns an `httpx.Auth` that fetches and reuses tokens and signs
+each request. It sends tokens only to the origins it is given, and `httpx`
+drops the token when a redirect leaves that origin.
+
+```python
+import httpx
+
+source = client.credentials_source(scope=["files:read"], resource=["https://files.example.com"])
+
+with httpx.Client(auth=client.auth(source, "https://files.example.com")) as api:
+    response = api.get("https://files.example.com/files")
+```
+
+A held token goes out as `Authorization: DPoP` with a fresh proof, and a server
+that asks for a DPoP nonce is answered once. `refresh_source` renews a token
+with its refresh token and hands each rotated token to `keep` to be saved.
+
+## Exchanging a token
+
+`exchange` trades a token for a new one under RFC 8693. A service that receives
+a caller's access token exchanges it for a token to another API, acting on the
+caller's behalf.
+
+```python
+token = client.exchange(
+    subject_token,
+    scope=["files:read"],
+    resource=["https://files.example.com"],
+    requested_lifetime=300,
+)
+```
+
+The subject is an access token unless `subject_token_type` says
+`masks.ID_TOKEN_TYPE`. `actor_token` names another party in the token's `act`
+claim. The new token lasts no longer than the subject token. When the client
+has a `dpop` key the new token is held to it, and a subject token held to a key
+is exchanged only with a proof from that same key.
+
+`requested_token_type=masks.UPSTREAM_ACCESS_TOKEN_TYPE` with a connection's id
+in `audience` releases the access token masks holds for that connection through
+a delegation. That token is a Bearer token from the provider, so it comes back
+unbound with `issued_token_type` naming the upstream type.
+
+## Async
+
+`masks.AsyncClient` has the same methods as `masks.Client`, awaited, and
+`masks.adiscover` discovers an issuer.
+
+```python
+issuer = await masks.adiscover("https://auth.example.com")
+
+async with masks.AsyncClient(issuer, client_id, key=key, dpop=dpop) as client:
+    source = client.credentials_source(resource=["https://files.example.com"])
+
+    async with httpx.AsyncClient(auth=client.auth(source, "https://files.example.com")) as api:
+        response = await api.get("https://files.example.com/files")
+```
+
+## The device flow
+
+A machine with no browser shows a code that a person approves on another
+device.
+
+```python
+device = client.device_authorization(scope=["openid", "offline_access"])
+print(f"Open {device.verification_uri} and enter {device.user_code}")
+
+token = client.await_device(device)
+```
+
+`await_device` polls at the interval masks names, slows down when asked, and
+stops when the code expires. The synchronous form takes a `timeout` in seconds,
+and the async form stops when its task is cancelled.
+
+## Checking access tokens
+
+`masks.Verifier` checks a token from any framework. Pass the method, the URL
+the client used, and the request's headers.
+
+```python
+verifier = masks.Verifier(issuer, "https://files.example.com", public_url="https://files.example.com")
+
+claims = verifier.authenticate(request.method, request.url, request.headers)
+claims.has_scope("files:read")
+```
+
+The verifier checks the signature against the issuer's published keys, the
+`at+jwt` type, the issuer, the audience, and the expiry. A DPoP-bound token
+needs a proof signed by its key, made for this method and URL, made in the last
+minute, and not seen before. A failed check raises `masks.InvalidToken`.
+
+When the verifier cannot reach the issuer's keys, or its replay store fails, it
+raises `masks.Unavailable`. The token may still be good, so answer `503` and
+let the client try again with the same token.
+
+Set `public_url` when a proxy sits in front of the API, since a proof names the
+address the client used.
+
+### Replayed proofs
+
+A verifier keeps the proofs it has seen in the process's memory. An API that
+runs in several processes passes `replay` an object whose `first(key,
+expires_in)` answers `True` only the first time it sees a key across every
+process, and `False` after that, for `expires_in` seconds.
+
+```python
+class RedisReplay:
+    def __init__(self, redis):
+        self.redis = redis
+
+    def first(self, key, expires_in):
+        return bool(self.redis.set(f"dpop:{key}", 1, nx=True, ex=expires_in))
+
+
+verifier = masks.Verifier(issuer, "https://files.example.com", replay=RedisReplay(redis))
+```
+
+`AsyncVerifier` also takes a store whose `first` is a coroutine, and
+`Verifier` raises `TypeError` when given one. An answer of `False` raises
+`masks.InvalidToken`. When the store raises or answers anything other than
+`True` or `False`, the verifier raises `masks.Unavailable` from the store's
+error. `masks.MemoryReplayStore` is the default, and one instance can be shared
+between verifiers in the same process.
+
+### Introspection
+
+A verifier that checks the JWT sees a revoked token as valid until it expires.
+`introspect` asks the issuer.
+
+```python
+found = client.introspect(token, "access_token")
+found.active and found.has_scope("files:read")
+```
+
+The issuer answers `active` only to the client the token was issued to, or to
+an approved client whose resources include one of the token's audiences. A
+token that is not active has no scopes. An answer that names another issuer
+raises `masks.Error`.
+
+### ASGI and FastAPI
+
+`masks.asgi.Middleware` checks every request with an `AsyncVerifier` and
+answers `401` with `WWW-Authenticate` challenges when the check fails. It
+answers `503` with no challenge when the verifier raises `masks.Unavailable`.
+The claims are at `request.state.masks_claims`.
+
+```python
+from fastapi import Depends, FastAPI, HTTPException, Request
+from masks.asgi import Middleware
+
+verifier = masks.AsyncVerifier(issuer, "https://files.example.com", public_url="https://files.example.com")
+
+app = FastAPI()
+app.add_middleware(Middleware, verifier=verifier)
+
+
+def reading(request: Request) -> masks.Claims:
+    claims = request.state.masks_claims
+
+    if not claims.has_scope("files:read"):
+        raise HTTPException(403)
+
+    return claims
+
+
+@app.get("/files")
+async def files(claims: masks.Claims = Depends(reading)):
+    return {"for": claims.subject}
+```
+
+### Django and Flask
+
+Call `Verifier.authenticate` in a view decorator or a `before_request` hook.
+In Django, pass `request.method`, `request.build_absolute_uri()`, and
+`request.headers`. In Flask, pass `request.method`, `request.url`, and
+`request.headers`. Answer `401` when it raises `masks.InvalidToken`, and `503`
+when it raises `masks.Unavailable`.
+
+## Plain HTTP
+
+Every URL is `https`, except on this machine: `localhost`, a `.localhost` name,
+or a loopback address. `allow_plain_http=True` on `discover` lifts that for a
+private network.