guest-auth 0.1.1__tar.gz

guest_auth-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check src tests
+      - name: Pytest
+        run: pytest -v

guest_auth-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+# Publish to PyPI via OpenID Connect "trusted publishing" — no API token.
+# Triggered by pushing a version tag (e.g. `git tag v0.1.1 && git push origin v0.1.1`).
+# The tagged commit's pyproject.toml `version` is what gets published, so bump
+# it in the same commit you tag.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write   # required for PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" build
+
+      - name: Lint & test (gate the release)
+        run: |
+          ruff check src tests
+          pytest -v
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

guest_auth-0.1.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+.DS_Store

guest_auth-0.1.1/LICENSE

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

guest_auth-0.1.1/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: guest-auth
+Version: 0.1.1
+Summary: A static-allowlist invite-token gate for pre-production demos and invite-only previews (pure-ASGI middleware for Starlette / FastAPI apps).
+Project-URL: Homepage, https://github.com/ecoop/guest-auth
+Project-URL: Repository, https://github.com/ecoop/guest-auth
+Project-URL: Issues, https://github.com/ecoop/guest-auth/issues
+Author: Eric Cooper
+License: MIT License
+        
+        Copyright (c) 2026 Eric Cooper
+        
+        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.
+License-File: LICENSE
+Keywords: asgi,auth,demo,fastapi,invite,starlette
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: starlette>=0.35
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# guest-auth
+
+**Not a replacement for real authentication.** A static-allowlist invite-token gate for pre-production demos and invite-only previews. Pure-ASGI middleware that plugs into any Starlette / FastAPI app in ~5 lines.
+
+Give a tester a link like `https://your-app.example.com/?token=tok_abc123`; the middleware validates the token against an allowlist you own, exchanges it for an `httpOnly` cookie, and attaches an identity (`token` + human-readable `recipient` label) to the request via a `ContextVar` that reaches sync endpoints in the threadpool as well.
+
+The library was extracted from [Pitchcraft](https://github.com/ecoop/pitchcraft) and is consumed there in production; [Rulebook](https://github.com/ecoop/rulebook) and JobScout are scheduled to adopt it.
+
+**Adopting this in a new app?** See [`docs/integration.md`](docs/integration.md) for the DI pattern, the `app_state.py` template, gotchas (init order, pure-ASGI vs `BaseHTTPMiddleware`, ContextVar propagation), and the constructor reference.
+
+---
+
+## What this is NOT
+
+Naming a library `*-auth` invites expectations it doesn't meet. To be explicit:
+
+- **No password handling, no MFA, no OAuth / OIDC, no account lifecycle.** The credential is an opaque token you generate and hand to a tester.
+- **No token rotation, expiry, revocation-list, or signed cookies.** The cookie is httpOnly + Secure + SameSite=Lax with a 30-day convenience lifetime; revoking access means removing the token from the allowlist and redeploying.
+- **No rate limiting.** Compose one separately (e.g. [`llm-guardrails`](https://github.com/ecoop/llm-guardrails) ships an IP rate limiter).
+- **Not audited for adversarial threat models.** This is a gate to keep pre-production URLs off the open web and attribute per-tester activity, not a substitute for real identity infrastructure. If you're gating production PII or payment flows, use something else.
+
+The value the library provides — a well-scoped ASGI middleware that publishes a per-request identity ContextVar that reaches sync endpoints — is genuinely useful and hard to get right (the "pure-ASGI vs `BaseHTTPMiddleware`" trap is subtle). Everything above is deferred, not planned.
+
+---
+
+## Install
+
+```bash
+pip install guest-auth
+```
+
+Requires Python 3.11+. The only runtime dependency is `starlette`, which any ASGI host already has.
+
+---
+
+## Quick example
+
+```python
+from dataclasses import dataclass, field
+from fastapi import FastAPI
+from guest_auth import InviteAuthMiddleware, get_current_guest
+
+
+@dataclass
+class Settings:
+    demo_mode: bool = True
+    invite_tokens: dict = field(
+        default_factory=lambda: {"tok_abc123": "Jane Tester"}
+    )
+
+
+settings = Settings()
+app = FastAPI()
+
+
+@app.get("/")
+def home():
+    guest = get_current_guest()
+    return {"welcome": guest.recipient if guest else "anonymous"}
+
+
+app.add_middleware(
+    InviteAuthMiddleware,
+    config=settings,
+    # Optional — pre-rendered HTML for the 401 / welcome page.
+    # Omit to use the built-in "This site is currently invite-only." body.
+    welcome_html="<h1>Preview build</h1><p>Ask jane@example.com for a link.</p>",
+)
+```
+
+Now:
+
+- `GET /?token=tok_abc123` → 302 to `/`, sets `guest_session` cookie.
+- `GET /` with the cookie → returns `{"welcome": "Jane Tester"}`.
+- `GET /` without a cookie → 401 with the welcome page.
+- Flip `settings.demo_mode = False` → gate becomes a complete pass-through with no restart.
+
+---
+
+## Core concepts
+
+### `GuestAuthConfig` (Protocol)
+
+The middleware takes a `config` object that satisfies:
+
+```python
+class GuestAuthConfig(Protocol):
+    demo_mode: bool
+    invite_tokens: Mapping[str, str]  # token → recipient label
+```
+
+Both attributes are read at request time, so mutating a live `config` instance (a pydantic `BaseSettings`, a dataclass, whatever) takes effect on the next request without rebuilding the middleware.
+
+### `GuestIdentity` + `get_current_guest()`
+
+On a successful cookie match, the middleware sets a request-scoped `ContextVar` with `GuestIdentity(token=..., recipient=...)`. Anywhere downstream — sync or async, including code paths in Starlette's threadpool — `get_current_guest()` returns it or `None`.
+
+Because the middleware is pure-ASGI (not `BaseHTTPMiddleware`), the `ContextVar` survives into the threadpool that runs `def` (sync) endpoints. See the [integration doc](docs/integration.md#gotchas) for why this matters.
+
+### `PathScopedContextVarMiddleware` (bonus)
+
+An adjacent generic that ships in the same package: match a regex against `scope["path"]`, publish an extracted value on a caller-supplied `ContextVar` for the duration of the request. Same pure-ASGI rationale as the auth middleware. Use for `/api/things/{id}/…` style path-scoped ContextVars (session IDs, tenant IDs, whatever).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ecoop/guest-auth
+cd guest-auth
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+CI runs on Python 3.11 and 3.12 via [GitHub Actions](.github/workflows/ci.yml).
+
+## Versioning
+
+Currently `v0.1.1`. Semver from `v1.0.0` onward; anything before is "shipped but pre-stable API — expect breaking changes."
+
+## Contributing
+
+Issues and pull requests welcome. For substantive changes, open an issue first — this library has a deliberately small surface and staying small is a feature.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+_Last updated: 2026-08-06_

guest_auth-0.1.1/README.md

@@ -0,0 +1,133 @@
+# guest-auth
+
+**Not a replacement for real authentication.** A static-allowlist invite-token gate for pre-production demos and invite-only previews. Pure-ASGI middleware that plugs into any Starlette / FastAPI app in ~5 lines.
+
+Give a tester a link like `https://your-app.example.com/?token=tok_abc123`; the middleware validates the token against an allowlist you own, exchanges it for an `httpOnly` cookie, and attaches an identity (`token` + human-readable `recipient` label) to the request via a `ContextVar` that reaches sync endpoints in the threadpool as well.
+
+The library was extracted from [Pitchcraft](https://github.com/ecoop/pitchcraft) and is consumed there in production; [Rulebook](https://github.com/ecoop/rulebook) and JobScout are scheduled to adopt it.
+
+**Adopting this in a new app?** See [`docs/integration.md`](docs/integration.md) for the DI pattern, the `app_state.py` template, gotchas (init order, pure-ASGI vs `BaseHTTPMiddleware`, ContextVar propagation), and the constructor reference.
+
+---
+
+## What this is NOT
+
+Naming a library `*-auth` invites expectations it doesn't meet. To be explicit:
+
+- **No password handling, no MFA, no OAuth / OIDC, no account lifecycle.** The credential is an opaque token you generate and hand to a tester.
+- **No token rotation, expiry, revocation-list, or signed cookies.** The cookie is httpOnly + Secure + SameSite=Lax with a 30-day convenience lifetime; revoking access means removing the token from the allowlist and redeploying.
+- **No rate limiting.** Compose one separately (e.g. [`llm-guardrails`](https://github.com/ecoop/llm-guardrails) ships an IP rate limiter).
+- **Not audited for adversarial threat models.** This is a gate to keep pre-production URLs off the open web and attribute per-tester activity, not a substitute for real identity infrastructure. If you're gating production PII or payment flows, use something else.
+
+The value the library provides — a well-scoped ASGI middleware that publishes a per-request identity ContextVar that reaches sync endpoints — is genuinely useful and hard to get right (the "pure-ASGI vs `BaseHTTPMiddleware`" trap is subtle). Everything above is deferred, not planned.
+
+---
+
+## Install
+
+```bash
+pip install guest-auth
+```
+
+Requires Python 3.11+. The only runtime dependency is `starlette`, which any ASGI host already has.
+
+---
+
+## Quick example
+
+```python
+from dataclasses import dataclass, field
+from fastapi import FastAPI
+from guest_auth import InviteAuthMiddleware, get_current_guest
+
+
+@dataclass
+class Settings:
+    demo_mode: bool = True
+    invite_tokens: dict = field(
+        default_factory=lambda: {"tok_abc123": "Jane Tester"}
+    )
+
+
+settings = Settings()
+app = FastAPI()
+
+
+@app.get("/")
+def home():
+    guest = get_current_guest()
+    return {"welcome": guest.recipient if guest else "anonymous"}
+
+
+app.add_middleware(
+    InviteAuthMiddleware,
+    config=settings,
+    # Optional — pre-rendered HTML for the 401 / welcome page.
+    # Omit to use the built-in "This site is currently invite-only." body.
+    welcome_html="<h1>Preview build</h1><p>Ask jane@example.com for a link.</p>",
+)
+```
+
+Now:
+
+- `GET /?token=tok_abc123` → 302 to `/`, sets `guest_session` cookie.
+- `GET /` with the cookie → returns `{"welcome": "Jane Tester"}`.
+- `GET /` without a cookie → 401 with the welcome page.
+- Flip `settings.demo_mode = False` → gate becomes a complete pass-through with no restart.
+
+---
+
+## Core concepts
+
+### `GuestAuthConfig` (Protocol)
+
+The middleware takes a `config` object that satisfies:
+
+```python
+class GuestAuthConfig(Protocol):
+    demo_mode: bool
+    invite_tokens: Mapping[str, str]  # token → recipient label
+```
+
+Both attributes are read at request time, so mutating a live `config` instance (a pydantic `BaseSettings`, a dataclass, whatever) takes effect on the next request without rebuilding the middleware.
+
+### `GuestIdentity` + `get_current_guest()`
+
+On a successful cookie match, the middleware sets a request-scoped `ContextVar` with `GuestIdentity(token=..., recipient=...)`. Anywhere downstream — sync or async, including code paths in Starlette's threadpool — `get_current_guest()` returns it or `None`.
+
+Because the middleware is pure-ASGI (not `BaseHTTPMiddleware`), the `ContextVar` survives into the threadpool that runs `def` (sync) endpoints. See the [integration doc](docs/integration.md#gotchas) for why this matters.
+
+### `PathScopedContextVarMiddleware` (bonus)
+
+An adjacent generic that ships in the same package: match a regex against `scope["path"]`, publish an extracted value on a caller-supplied `ContextVar` for the duration of the request. Same pure-ASGI rationale as the auth middleware. Use for `/api/things/{id}/…` style path-scoped ContextVars (session IDs, tenant IDs, whatever).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/ecoop/guest-auth
+cd guest-auth
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+```
+
+CI runs on Python 3.11 and 3.12 via [GitHub Actions](.github/workflows/ci.yml).
+
+## Versioning
+
+Currently `v0.1.1`. Semver from `v1.0.0` onward; anything before is "shipped but pre-stable API — expect breaking changes."
+
+## Contributing
+
+Issues and pull requests welcome. For substantive changes, open an issue first — this library has a deliberately small surface and staying small is a feature.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+_Last updated: 2026-08-06_

guest_auth-0.1.1/docs/integration.md

@@ -0,0 +1,201 @@
+# Integration Guide
+
+How to adopt `guest-auth` in a Python ASGI application. This is the practical companion to the [README](../README.md) — the README explains *what* the library does; this doc explains *how* to wire it into your app.
+
+**Reference implementation:** [Pitchcraft](https://github.com/ecoop/pitchcraft) consumes this library in production. Its [`app_state.py`](https://github.com/ecoop/pitchcraft/blob/main/app_state.py) is the canonical adoption pattern; the file pointers throughout this doc are all in that repo.
+
+---
+
+## Install
+
+```bash
+pip install guest-auth
+```
+
+Requires Python 3.11+. The only runtime dependency is `starlette` (which every ASGI host already has), so the install stays lean.
+
+---
+
+## The dependency-injection pattern
+
+The library **takes zero configuration from the host app.** The `InviteAuthMiddleware` constructor takes explicit arguments; there are no module singletons inside the library, no config imports, no environment-variable reads.
+
+The host app is responsible for:
+
+1. Reading its own config (which env vars, which allowlist source).
+2. Constructing the middleware at app-factory time with those values.
+3. Exposing anything downstream needs (e.g. `get_current_guest`) through a facade module rather than reaching into `guest_auth` directly if you'd like to keep the seam narrow.
+
+Pitchcraft's [`app_state.py`](https://github.com/ecoop/pitchcraft/blob/main/app_state.py) is the working example for the broader "singleton facade" pattern. The auth-specific slice looks like this:
+
+```python
+# app_state.py — the singleton facade
+from typing import Optional
+from starlette.middleware import Middleware
+
+from guest_auth import InviteAuthMiddleware
+
+
+_welcome_html: Optional[str] = None
+
+
+def initialize(settings) -> None:
+    """Called from main.py at startup, before the FastAPI app factory."""
+    global _welcome_html
+    _welcome_html = _render_welcome_html(settings.welcome_md_path)
+
+
+def guest_auth_middleware(settings) -> Middleware:
+    """Return the middleware ready to slot into ``FastAPI(middleware=[...])``
+    or ``app.add_middleware(...)``. Read once at app-factory time.
+    """
+    return Middleware(
+        InviteAuthMiddleware,
+        config=settings,
+        welcome_html=_welcome_html,
+    )
+
+
+def _render_welcome_html(md_path) -> str:
+    """Host-side: render your welcome copy. The library takes pre-rendered
+    HTML so it stays free of markdown / filesystem dependencies.
+    """
+    ...
+```
+
+Then in `main.py`:
+
+```python
+# main.py — order matters
+from config import settings
+
+import app_state
+app_state.initialize(settings)  # BEFORE the FastAPI app is built
+
+from fastapi import FastAPI
+app = FastAPI()
+app.add_middleware(
+    InviteAuthMiddleware,
+    config=settings,
+    welcome_html=app_state._welcome_html,
+)
+```
+
+Consumers of the identity import `get_current_guest` directly — it's a plain function that reads a `ContextVar`, safe to call from anywhere:
+
+```python
+from guest_auth import get_current_guest
+
+def some_endpoint():
+    guest = get_current_guest()
+    if guest is not None:
+        log.info("request from %s (%s)", guest.recipient, guest.token[:8])
+```
+
+---
+
+## Gotchas
+
+### 1. Pure-ASGI is load-bearing — do NOT use `BaseHTTPMiddleware`
+
+The middleware is a pure ASGI class (`__call__(scope, receive, send)`), not `BaseHTTPMiddleware` and not `@app.middleware("http")`. This is not a stylistic choice.
+
+Both `BaseHTTPMiddleware` and the `@app.middleware` decorator run the downstream app in a **separate anyio task**. Any `ContextVar` set inside their `dispatch` reaches the endpoint *only if the endpoint happens to run in the same task*. FastAPI's sync (`def`) endpoints run in Starlette's threadpool — a different task — and the `ContextVar` propagation there is unreliable.
+
+`InviteAuthMiddleware` sets the identity `ContextVar` from the same task the endpoint runs in, so it propagates into the threadpool along with the copy anyio takes when it launches the sync worker. If you find yourself wrapping this middleware in another `BaseHTTPMiddleware` layer, understand that any ContextVars *that layer* sets won't reach sync endpoints — that's a Starlette-level issue independent of this library.
+
+The generic sibling `PathScopedContextVarMiddleware` follows the same pattern for the same reason.
+
+### 2. Init order — `initialize()` before FastAPI app-factory
+
+If you're using a facade like the one above, call `app_state.initialize(...)` **before** the FastAPI app is constructed and its routers imported. Once routers are imported, decorators have already fired; anything they closed over (config values, middleware factories) is snapshotted.
+
+The middleware itself is fine either way — it reads config at request time — but any *rendering* your facade does at `initialize()` (like the welcome HTML) needs to be ready before whoever calls it.
+
+### 3. Config is read at request time, not construction time
+
+The middleware reads `config.demo_mode` and `config.invite_tokens` on every request via attribute lookup. Two implications:
+
+- **Tests** can `monkeypatch.setattr(settings, "invite_tokens", {"tok_x": "Test"})` on a live app and the next request picks it up.
+- **Production hot-swap**: if your config source is mutable (a reload signal, a file watcher), pushing a new allowlist value into the same instance flips the gate without a restart.
+
+If you specifically want construction-time snapshotting instead, wrap your config in an immutable dataclass and pass a fresh instance.
+
+### 4. Cookie name is a module constant, not per-instance
+
+`guest_auth.COOKIE_NAME = "guest_session"`. If you run two apps on the same origin and want per-app cookies, you need one of:
+
+- Deploy them on different domains / paths so cookies don't collide.
+- Fork the library and change the constant (there is no constructor arg for it in v0.1.0 — that's a candidate for v0.2).
+
+---
+
+## Constructor reference
+
+### `InviteAuthMiddleware`
+
+```python
+InviteAuthMiddleware(
+    app,                              # ASGI app being wrapped
+    config,                           # object exposing demo_mode + invite_tokens
+    *,
+    welcome_html: str | None = None,  # pre-rendered 401 / welcome body
+)
+```
+
+| Arg | Type | Purpose |
+|---|---|---|
+| `app` | `ASGIApp` | Downstream app the middleware wraps. Populated automatically when using `app.add_middleware()`. |
+| `config` | `GuestAuthConfig` | Any object with `demo_mode: bool` and `invite_tokens: Mapping[str, str]`. Attribute-read per request. |
+| `welcome_html` | `str \| None` | Pre-rendered HTML body injected verbatim into the library's page chrome. `None` uses a minimal built-in fallback. |
+
+### `PathScopedContextVarMiddleware`
+
+```python
+PathScopedContextVarMiddleware(
+    app,
+    *,
+    pattern: re.Pattern | str,             # matched against scope["path"]
+    contextvar: ContextVar[Any],           # target var to publish onto
+    extractor: Callable[[re.Match], Any] = lambda m: m.group(1),
+)
+```
+
+| Arg | Type | Purpose |
+|---|---|---|
+| `pattern` | `re.Pattern \| str` | Matched with `.match()` — anchor with `^` for a prefix match. String is compiled internally. |
+| `contextvar` | `ContextVar[Any]` | Value stored on match; `None` on non-match. Reset after each request. |
+| `extractor` | `Callable` | How to turn the `re.Match` into the stored value. Default: first capture group. |
+
+### `GuestIdentity`
+
+```python
+@dataclass(frozen=True)
+class GuestIdentity:
+    token: str        # the credential itself
+    recipient: str    # human-readable label from the allowlist
+```
+
+### Module-level constants + functions
+
+| Name | Purpose |
+|---|---|
+| `COOKIE_NAME = "guest_session"` | Cookie the middleware sets and reads. |
+| `COOKIE_MAX_AGE = 60 * 60 * 24 * 30` | 30 days, in seconds. Convenience lifetime, not token expiry. |
+| `get_current_guest() -> GuestIdentity \| None` | Read the current request's identity, or `None` outside a request or when demo mode is off. |
+
+---
+
+## Reference implementation: Pitchcraft
+
+Files worth skimming, in priority order:
+
+1. [`app_state.py`](https://github.com/ecoop/pitchcraft/blob/main/app_state.py) — singleton facade pattern.
+2. [`api/main.py`](https://github.com/ecoop/pitchcraft/blob/main/api/main.py) — how the middleware slots into the FastAPI app-factory.
+3. [`api/observability.py`](https://github.com/ecoop/pitchcraft/blob/main/api/observability.py) — a consumer of `get_current_guest()` in the request path.
+
+---
+
+## Getting help
+
+For questions on the adoption pattern that aren't covered here: open an issue on this repo, or point at the Pitchcraft reference files above — they're the working ground truth.