feat(aauth): introspection-aauth, a Person Server and Access Server library

.github/workflows/ci.yml

@@ -111,7 +111,10 @@ jobs:
         run: uv sync --all-extras
 
       - name: Run tests with coverage
-        run: uv run pytest tests/ -v --cov=introspection_sdk --cov-report=term-missing --cov-report=xml
+        run: |
+          echo "## introspection-sdk coverage" >> "$GITHUB_STEP_SUMMARY"
+          uv run pytest tests/ -v --cov=introspection_sdk --cov-report=term-missing --cov-report=xml \
+            --cov-report="markdown-append:$GITHUB_STEP_SUMMARY"
 
       - name: Upload coverage report
         if: always()
@@ -205,3 +208,53 @@ jobs:
           node-version: "24"
       - name: Duplicate code stays under the threshold
         run: npx --yes jscpd@5.4.1
+
+  aauth:
+    # packages/introspection-aauth is its own distribution, with its own
+    # lock, coverage floor and duplicate-code check (its pyproject.toml and
+    # .jscpd.json).
+    name: introspection-aauth
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/introspection-aauth
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Run linting
+        run: uv run ruff check .
+
+      - name: Run type checking
+        run: uv run ty check introspection_aauth tests
+
+      - name: Run tests with coverage
+        run: |
+          echo "## introspection-aauth coverage" >> "$GITHUB_STEP_SUMMARY"
+          uv run pytest tests/ -v --cov=introspection_aauth --cov-report=term-missing \
+            --cov-report="markdown-append:$GITHUB_STEP_SUMMARY"
+
+      - name: Check dependencies
+        run: uv run deptry .
+
+      - name: Duplicate code stays at zero
+        run: npx --yes jscpd@5.4.1

.github/workflows/examples.yml

@@ -48,6 +48,12 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-uv-examples-
 
+      - name: Run the AAuth example
+        # Every party runs in process; it needs no secrets.
+        if: inputs.run_examples || startsWith(github.ref, 'refs/tags/v')
+        working-directory: examples
+        run: uv run -m introspection_examples.aauth.four_party
+
       - name: Run pattern examples
         # The docs' pattern pages show these modules' snippet regions.
         # patterns.add_to_your_app and patterns.web_chat also need a service

.release-please-manifest.json

@@ -1,3 +1,4 @@
 {
-  ".": "0.29.1"
+  ".": "0.29.1",
+  "packages/introspection-aauth": "0.0.0"
 }

AGENTS.md

@@ -122,6 +122,36 @@ uv run ty check
 These are enforced by `.pre-commit-config.yaml`. Don't disable hooks with
 `--no-verify` — fix the underlying issue.
 
+**No leading underscore on a class, constant or type variable.** Write
+`class RouteDocs`, `JSON_OBJECT`, `AnyServer = TypeVar("AnyServer", ...)`,
+never `class _Docs` or `_object`. A module keeps such a name private by
+leaving it out of its `__all__`, so a module that has private names defines
+`__all__`. Private methods and module functions keep their underscore. This
+is the rule for new code: about 76 underscore classes and constants remain in
+`introspection_sdk/`, `tests/` and `examples/`; rename one when you touch
+its module.
+
+**One file, one concept, named for it.** A module holds one class, or one
+family of closely related ones, and its name says which: `access_server_client.py`
+holds `AccessServerClient`, `directory.py` the `Directory` protocol and its
+default, `store.py` the `Store` protocol and its `MemoryStore`. A `models.py`
+holds a package's models, and `hooks.py` the protocols a host implements.
+Aim for 100 to 300 lines; a module far past that is a sign to split it, the
+exceptions being a `models.py` and a class that is legitimately that long, in
+which case its module holds that class alone.
+
+**Log and trace as the platform does.** A module that does meaningful work
+declares `logger = logging.getLogger(__name__)` and, where it has an
+operation worth a span, `tracer = trace.get_tracer(__name__)`, once, after its
+imports. A record has a fixed message and its values as `extra` fields:
+identifiers and enumerated values, never a token, personal data or a request
+body. A library never configures logging or a tracer provider; its host does.
+
+**Imports are absolute.** `from introspection_aauth.protocol.errors import
+InvalidToken`, never `from ..protocol.errors import InvalidToken`; ruff's
+TID252 enforces it. A test suite imports its own helpers relatively
+(`from .world import World`).
+
 ## Sync code generation
 
 Every class or function with an `Async*` twin is written once, as async
@@ -282,9 +312,9 @@ It needs the release tags locally (`git fetch --tags`).
 What counts as public: a module's `__all__` when it has one, otherwise every
 name without a leading underscore. Imported names are public only through
 `__all__`. `_`-prefixed modules (`_http.py`, `_errors.py`,
-`otel/_provider.py`, ...) and `_`-prefixed classes, functions and attributes
-are internal and free to change. To keep a new helper out of the contract,
-give it a leading underscore or leave it out of `__all__`.
+`otel/_provider.py`, ...) and `_`-prefixed functions and attributes are
+internal and free to change. To keep a new class or constant out of the
+contract, leave it out of `__all__`, never prefix it with an underscore.
 
 `-e scripts/griffe_reexports.py` loads a griffe extension that replaces
 each public alias whose target lives in `introspection_sdk` with the target

README.md

@@ -511,6 +511,14 @@ caller who is not a project administrator only ever gets their own
 connections. The routes need `connections:read`, `connections:write` and
 `connections:delete`.
 
+## Run an AAuth Person Server or Access Server
+
+[`introspection-aauth`](packages/introspection-aauth) is a separate package
+in this repository: an AAuth Person Server and Access Server
+(draft-hardt-oauth-aauth-protocol -11) over a store you provide, with
+FastAPI routers. `examples/introspection_examples/aauth/four_party.py` runs
+the four-party flow in one process.
+
 ## Environment variables
 
 ```shell

examples/introspection_examples/__init__.py

@@ -7,7 +7,7 @@
 
 from dotenv import load_dotenv
 
-from . import api, otel
+from introspection_examples import api, otel
 
 load_dotenv()
 

examples/introspection_examples/aauth/__init__.py

@@ -0,0 +1 @@
+"""AAuth Person Server and Access Server examples (introspection-aauth)."""