auths-fastapi 0.1.3__tar.gz

auths_fastapi-0.1.3/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+.venv/

auths_fastapi-0.1.3/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: auths-fastapi
+Version: 0.1.3
+Summary: FastAPI dependency authenticating an Auths-Presentation request into a typed Principal
+Project-URL: Homepage, https://auths.dev
+Project-URL: Repository, https://github.com/auths-dev/auths
+Project-URL: Documentation, https://docs.auths.dev
+Project-URL: Bug Tracker, https://github.com/auths-dev/auths/issues
+License: Apache-2.0
+Keywords: auth,did,fastapi,identity,keri,presentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Provides-Extra: client
+Requires-Dist: httpx>=0.27; extra == 'client'
+Provides-Extra: native
+Requires-Dist: auths>=0.1; extra == 'native'
+Description-Content-Type: text/markdown
+
+# auths-fastapi
+
+A FastAPI dependency that authenticates an `Auths-Presentation` request and yields a typed
+`Principal`, or raises `HTTPException`. It is the Python counterpart of the Axum reference
+middleware in `crates/auths-api/src/rp_auth.rs`: an injectable verifier, a real single-use
+challenge store, a verdict→status mapping, and a dependency that hands a handler a `Principal`
+**only on success**.
+
+## Scope
+
+- **First-party only.** The relying party trusts credentials issued under DIDs it has pinned
+  in `pinned_roots` (the `.auths/roots` model — DID-only; capabilities come from the verified
+  credential, never the request). There is no federation or third-party issuer discovery.
+- **Challenge mode is the default.** The interactive `GET /v1/auth/challenge` → single-use
+  nonce → present flow is the v1 path and the one this package mints. A TTL binding is opt-in
+  (non-interactive, no store entry to consume); within its TTL a TTL presentation can be
+  replayed, so prefer the challenge binding unless you have a reason not to.
+- **Single process.** The bundled `ChallengeStore` lives in one process's heap. Behind a load
+  balancer fronting N nodes a nonce minted on one node is unknown to another, and the
+  single-use guarantee holds only per node — supply a shared store backend for multi-node.
+
+## Security notes
+
+- The nonce and signature are **never logged** by this package; do not log the `Authorization`
+  header in your own middleware either.
+- 401 responses carry `WWW-Authenticate: Bearer` so generic clients treat them as a standard
+  auth challenge.
+- The expected audience is the relying party's **configured** audience, not the wire header.
+
+## Install
+
+```bash
+pip install auths-fastapi            # the dependency + challenge store (fake-verifier testable)
+pip install "auths-fastapi[native]"  # + the `auths` binding for the production verifier
+pip install "auths-fastapi[client]"  # + httpx for fetch_challenge
+```
+
+## Usage
+
+```python
+from fastapi import Depends, FastAPI
+from auths_fastapi import (
+    Capability, ChallengeStore, KeriPresentationVerifier, Principal,
+    PresentationInputs, auths_principal, challenge_router, configure, configure_mint,
+)
+
+AUDIENCE = "api.example.com"
+store = ChallengeStore(max_live=10_000)
+
+def load_inputs(credential_said: str) -> PresentationInputs:
+    # Resolve the credential SAID to its KEL/TEL inputs from your registry.
+    ...
+
+configure(KeriPresentationVerifier(
+    audience=AUDIENCE,
+    challenges=store,
+    load_inputs=load_inputs,
+    pinned_roots=frozenset({"did:keri:Eroot"}),
+))
+configure_mint(store, AUDIENCE)
+
+app = FastAPI()
+app.include_router(challenge_router)  # GET /v1/auth/challenge
+
+@app.post("/v1/deploy")
+async def deploy(principal: Principal = Depends(auths_principal(Capability("deploy:prod")))):
+    return {"deployed_by": principal.subject}
+```
+
+### Guard a whole group
+
+```python
+from fastapi import APIRouter, Depends
+
+admin = APIRouter(
+    prefix="/v1/admin",
+    dependencies=[Depends(auths_principal(Capability("admin:read")))],
+)
+
+@admin.get("/status")          # protected by the router-level dependency; no Principal needed
+async def admin_status():
+    return {"status": "ok"}
+```
+
+A route that does **not** depend on `auths_principal(...)` receives no `Principal` and is
+unauthenticated by construction.
+
+### Client flow
+
+```python
+from auths_fastapi import fetch_challenge
+
+issued = fetch_challenge("https://api.example.com/v1/auth/challenge")
+# sign over issued.nonce, build the Auths-Presentation token, send it in Authorization.
+```
+
+## Status mapping
+
+| Outcome                                                              | Status | Header                       |
+| ------------------------------------------------------------------- | ------ | ---------------------------- |
+| Verified, capability satisfied                                      | 200    | —                            |
+| Missing/malformed header, expired, revoked, wrong audience, replay, holder-not-current, unpinned issuer | 401 | `WWW-Authenticate: Bearer` |
+| Authenticated but missing the required capability                   | 403    | —                            |
+| Challenge store at capacity                                         | 503    | —                            |
+
+## Testing without the native binding
+
+The crypto verify step is injected behind the `PresentationVerifier` protocol. Tests supply a
+fake verifier over the **real** `ChallengeStore`, so replay/audience/expiry are genuinely
+exercised with no binding installed (see `tests/test_dependency.py`). Run `pytest`.

auths_fastapi-0.1.3/README.md

@@ -0,0 +1,110 @@
+# auths-fastapi
+
+A FastAPI dependency that authenticates an `Auths-Presentation` request and yields a typed
+`Principal`, or raises `HTTPException`. It is the Python counterpart of the Axum reference
+middleware in `crates/auths-api/src/rp_auth.rs`: an injectable verifier, a real single-use
+challenge store, a verdict→status mapping, and a dependency that hands a handler a `Principal`
+**only on success**.
+
+## Scope
+
+- **First-party only.** The relying party trusts credentials issued under DIDs it has pinned
+  in `pinned_roots` (the `.auths/roots` model — DID-only; capabilities come from the verified
+  credential, never the request). There is no federation or third-party issuer discovery.
+- **Challenge mode is the default.** The interactive `GET /v1/auth/challenge` → single-use
+  nonce → present flow is the v1 path and the one this package mints. A TTL binding is opt-in
+  (non-interactive, no store entry to consume); within its TTL a TTL presentation can be
+  replayed, so prefer the challenge binding unless you have a reason not to.
+- **Single process.** The bundled `ChallengeStore` lives in one process's heap. Behind a load
+  balancer fronting N nodes a nonce minted on one node is unknown to another, and the
+  single-use guarantee holds only per node — supply a shared store backend for multi-node.
+
+## Security notes
+
+- The nonce and signature are **never logged** by this package; do not log the `Authorization`
+  header in your own middleware either.
+- 401 responses carry `WWW-Authenticate: Bearer` so generic clients treat them as a standard
+  auth challenge.
+- The expected audience is the relying party's **configured** audience, not the wire header.
+
+## Install
+
+```bash
+pip install auths-fastapi            # the dependency + challenge store (fake-verifier testable)
+pip install "auths-fastapi[native]"  # + the `auths` binding for the production verifier
+pip install "auths-fastapi[client]"  # + httpx for fetch_challenge
+```
+
+## Usage
+
+```python
+from fastapi import Depends, FastAPI
+from auths_fastapi import (
+    Capability, ChallengeStore, KeriPresentationVerifier, Principal,
+    PresentationInputs, auths_principal, challenge_router, configure, configure_mint,
+)
+
+AUDIENCE = "api.example.com"
+store = ChallengeStore(max_live=10_000)
+
+def load_inputs(credential_said: str) -> PresentationInputs:
+    # Resolve the credential SAID to its KEL/TEL inputs from your registry.
+    ...
+
+configure(KeriPresentationVerifier(
+    audience=AUDIENCE,
+    challenges=store,
+    load_inputs=load_inputs,
+    pinned_roots=frozenset({"did:keri:Eroot"}),
+))
+configure_mint(store, AUDIENCE)
+
+app = FastAPI()
+app.include_router(challenge_router)  # GET /v1/auth/challenge
+
+@app.post("/v1/deploy")
+async def deploy(principal: Principal = Depends(auths_principal(Capability("deploy:prod")))):
+    return {"deployed_by": principal.subject}
+```
+
+### Guard a whole group
+
+```python
+from fastapi import APIRouter, Depends
+
+admin = APIRouter(
+    prefix="/v1/admin",
+    dependencies=[Depends(auths_principal(Capability("admin:read")))],
+)
+
+@admin.get("/status")          # protected by the router-level dependency; no Principal needed
+async def admin_status():
+    return {"status": "ok"}
+```
+
+A route that does **not** depend on `auths_principal(...)` receives no `Principal` and is
+unauthenticated by construction.
+
+### Client flow
+
+```python
+from auths_fastapi import fetch_challenge
+
+issued = fetch_challenge("https://api.example.com/v1/auth/challenge")
+# sign over issued.nonce, build the Auths-Presentation token, send it in Authorization.
+```
+
+## Status mapping
+
+| Outcome                                                              | Status | Header                       |
+| ------------------------------------------------------------------- | ------ | ---------------------------- |
+| Verified, capability satisfied                                      | 200    | —                            |
+| Missing/malformed header, expired, revoked, wrong audience, replay, holder-not-current, unpinned issuer | 401 | `WWW-Authenticate: Bearer` |
+| Authenticated but missing the required capability                   | 403    | —                            |
+| Challenge store at capacity                                         | 503    | —                            |
+
+## Testing without the native binding
+
+The crypto verify step is injected behind the `PresentationVerifier` protocol. Tests supply a
+fake verifier over the **real** `ChallengeStore`, so replay/audience/expiry are genuinely
+exercised with no binding installed (see `tests/test_dependency.py`). Run `pytest`.

auths_fastapi-0.1.3/auths_fastapi/__init__.py

@@ -0,0 +1,59 @@
+"""FastAPI middleware for Auths-Presentation request authentication.
+
+Public surface:
+* `auths_principal(capability)` — the FastAPI dependency yielding a verified `Principal`.
+* `configure` — install the process-wide `PresentationVerifier`.
+* `Principal` / `Capability` — the typed identity + authority models.
+* `ChallengeStore` / `IssuedChallenge` / `StoreFull` — the single-use challenge store.
+* `PresentationVerifier` (Protocol), `KeriPresentationVerifier`, `PresentationInputs`,
+  `PresentationDenied` — the injectable verify seam and its production impl.
+* `challenge_router` / `configure_mint` / `fetch_challenge` — the mint route + client helper.
+
+First-party only: the relying party trusts credentials issued under DIDs it has pinned
+(`pinned_roots`); there is no federation. The interactive challenge binding is the default.
+"""
+
+from .challenge_route import configure_mint, fetch_challenge
+from .challenge_route import router as challenge_router
+from .challenge_store import (
+    DEFAULT_CHALLENGE_TTL,
+    NONCE_LEN,
+    ChallengeStore,
+    IssuedChallenge,
+    StoreFull,
+)
+from .dependency import auths_principal, configure
+from .models import Capability, Principal
+from .verifier import (
+    KeriPresentationVerifier,
+    LoadInputs,
+    PresentationDenied,
+    PresentationInputs,
+    PresentationVerifier,
+    WirePresentation,
+    parse_presentation_header,
+    parse_presentation_token,
+)
+
+__all__ = [
+    "auths_principal",
+    "configure",
+    "Principal",
+    "Capability",
+    "ChallengeStore",
+    "IssuedChallenge",
+    "StoreFull",
+    "NONCE_LEN",
+    "DEFAULT_CHALLENGE_TTL",
+    "PresentationVerifier",
+    "KeriPresentationVerifier",
+    "PresentationInputs",
+    "PresentationDenied",
+    "LoadInputs",
+    "WirePresentation",
+    "parse_presentation_header",
+    "parse_presentation_token",
+    "challenge_router",
+    "configure_mint",
+    "fetch_challenge",
+]

auths_fastapi-0.1.3/auths_fastapi/challenge_route.py

@@ -0,0 +1,82 @@
+"""The `/v1/auth/challenge` mint route and a client-side fetch helper.
+
+Mirrors `auths_api::rp_auth::challenge_handler`: `GET /v1/auth/challenge` mints a fresh
+single-use nonce bound to the configured audience and returns `{nonce, not_after}`; at
+capacity it returns 503 rather than evicting a live nonce. `fetch_challenge` is the client
+counterpart (httpx) that fetches one for signing.
+
+The store is configured once via `configure_mint(...)`.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, HTTPException
+
+from .challenge_store import ChallengeStore, IssuedChallenge, StoreFull
+
+
+class _MintConfig:
+    """The once-configured store + audience the mint route uses."""
+
+    store: ChallengeStore | None = None
+    audience: str | None = None
+
+
+def configure_mint(store: ChallengeStore, audience: str) -> None:
+    """Install the store + audience the `/v1/auth/challenge` route mints against.
+
+    Args:
+    * `store`: The single-use challenge store (shared with the verifier).
+    * `audience`: This relying party's canonical audience.
+    """
+    _MintConfig.store = store
+    _MintConfig.audience = audience
+
+
+router = APIRouter()
+"""The mint router; include with `app.include_router(challenge_router)`."""
+
+
+@router.get("/v1/auth/challenge")
+async def challenge_handler() -> dict[str, str]:
+    """Mint a fresh CSPRNG nonce bound to this RP's audience.
+
+    Returns `{nonce, not_after}`; raises 503 when the bounded store is full and 500 if the
+    mint route was not configured.
+    """
+    store = _MintConfig.store
+    audience = _MintConfig.audience
+    if store is None or audience is None:
+        raise HTTPException(status_code=500, detail="challenge mint not configured")
+    try:
+        issued = store.issue(audience, datetime.now(timezone.utc))
+    except StoreFull as exc:
+        raise HTTPException(status_code=503, detail="challenge store full") from exc
+    return {"nonce": issued.nonce, "not_after": issued.not_after.isoformat()}
+
+
+def fetch_challenge(url: str) -> IssuedChallenge:
+    """Client helper: GET a challenge from `url` and parse it into an `IssuedChallenge`.
+
+    Requires the `client` extra (httpx). Raises on a non-200 (e.g. 503 when the store is
+    full).
+
+    Args:
+    * `url`: The full `/v1/auth/challenge` URL.
+
+    Usage:
+    ```python
+    issued = fetch_challenge("https://api.example.com/v1/auth/challenge")
+    ```
+    """
+    import httpx
+
+    response = httpx.get(url)
+    response.raise_for_status()
+    body = response.json()
+    return IssuedChallenge(
+        nonce=body["nonce"],
+        not_after=datetime.fromisoformat(body["not_after"]),
+    )

auths_fastapi-0.1.3/auths_fastapi/challenge_store.py

@@ -0,0 +1,121 @@
+"""Single-use challenge store for the interactive presentation path.
+
+Mirrors `auths_rp::challenge::InMemoryChallengeStore`: a CSPRNG nonce minted by `issue` is
+bound to an audience and consumed exactly once by `consume` (remove-on-read), giving genuine
+single-use replay protection with no global seen-cache. The store is bounded (`max_live`) and
+TTL-pruned so a `/v1/auth/challenge` flood cannot exhaust memory; at capacity `issue` raises
+`StoreFull` rather than evicting a live nonce. `consume` runs after the caller's cheap
+structural checks, so a third party cannot burn a legitimate client's nonce.
+
+The clock is injected (`now: datetime`) — there is no hidden wall-clock read; the HTTP
+boundary samples the clock and passes it down, matching the Rust clock-injection rule.
+"""
+
+from __future__ import annotations
+
+import base64
+import secrets
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+NONCE_LEN = 32
+"""The fixed nonce width, in bytes (matches `auths_rp::NONCE_LEN`)."""
+
+DEFAULT_CHALLENGE_TTL = timedelta(seconds=120)
+"""The default TTL ceiling for a minted challenge (matches `DEFAULT_CHALLENGE_TTL_SECS`)."""
+
+
+class StoreFull(Exception):
+    """The challenge store is at capacity — retry shortly (maps to HTTP 503)."""
+
+
+@dataclass(frozen=True)
+class IssuedChallenge:
+    """A freshly minted challenge handed to the client.
+
+    Args:
+    * `nonce`: The base64url (no-pad) single-use nonce the client signs over.
+    * `not_after`: The instant after which the challenge is no longer live.
+    """
+
+    nonce: str
+    not_after: datetime
+
+
+def _encode_nonce(raw: bytes) -> str:
+    """Encode raw nonce bytes as base64url without padding (the wire form)."""
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+class ChallengeStore:
+    """A bounded, TTL-pruned, single-use challenge store.
+
+    Single-process only (an in-heap map). A multi-node deployment behind a load balancer
+    must supply a shared backend so a nonce minted on one node is consumable on another and
+    the remove-on-read guarantee holds across nodes; see the Rust load-balancer caveat.
+
+    Args:
+    * `max_live`: The maximum number of live challenges before `issue` raises `StoreFull`.
+    * `ttl`: The lifetime of each minted challenge (defaults to 120s).
+
+    Usage:
+    ```python
+    store = ChallengeStore(max_live=10_000)
+    issued = store.issue("api.example.com", now)
+    assert store.consume("api.example.com", issued.nonce, now)
+    ```
+    """
+
+    def __init__(self, max_live: int, ttl: timedelta = DEFAULT_CHALLENGE_TTL) -> None:
+        self._max_live = max_live
+        self._ttl = ttl
+        self._lock = threading.Lock()
+        self._live: dict[tuple[str, str], datetime] = {}
+
+    def issue(self, audience: str, now: datetime) -> IssuedChallenge:
+        """Mint a fresh single-use challenge bound to `audience`.
+
+        Prunes expired entries first; at capacity raises `StoreFull` rather than evicting a
+        live nonce.
+
+        Args:
+        * `audience`: The relying party the presentation must bind to.
+        * `now`: The current time, injected at the boundary.
+        """
+        nonce = _encode_nonce(secrets.token_bytes(NONCE_LEN))
+        not_after = now + self._ttl
+        with self._lock:
+            self._prune(now)
+            if len(self._live) >= self._max_live:
+                raise StoreFull
+            self._live[(audience, nonce)] = not_after
+        return IssuedChallenge(nonce=nonce, not_after=not_after)
+
+    def consume(self, audience: str, nonce: str, now: datetime) -> bool:
+        """Consume a challenge once (remove-on-read), returning True exactly once.
+
+        A second consume of the same nonce, an expired one, a wrong-audience one, or an
+        unknown one all return False — the single-use replay protection. A wrong audience
+        does not burn the nonce, so a third party cannot consume a legitimate client's.
+
+        Args:
+        * `audience`: The audience the client claims to bind to.
+        * `nonce`: The base64url nonce the client presented.
+        * `now`: The current time, injected at the boundary.
+        """
+        key = (audience, nonce)
+        with self._lock:
+            not_after = self._live.pop(key, None)
+            return not_after is not None and not_after > now
+
+    def live_count(self) -> int:
+        """The number of currently-stored challenges (diagnostics / tests)."""
+        with self._lock:
+            return len(self._live)
+
+    def _prune(self, now: datetime) -> None:
+        """Drop every entry whose expiry has passed (caller holds the lock)."""
+        expired = [key for key, not_after in self._live.items() if not_after <= now]
+        for key in expired:
+            del self._live[key]

auths_fastapi-0.1.3/auths_fastapi/dependency.py

@@ -0,0 +1,110 @@
+"""The FastAPI dependency: `Auths-Presentation` header → typed `Principal` or `HTTPException`.
+
+Mirrors `auths_api::rp_auth`: a dependency factory `auths_principal(capability)` reads the
+`Authorization` header, calls the injected `PresentationVerifier` (which consumes the
+single-use challenge), enforces the capability, and RETURNS a `Principal` only on success. A
+route that does not depend on it never receives a `Principal`, and the same dependency can
+guard a whole `APIRouter` group via `dependencies=[Depends(...)]`.
+
+Status mapping: malformed/missing/expired/revoked/wrong-audience/holder-not-current → 401
+(with a `WWW-Authenticate: Bearer` header); missing capability → 403; store full → 503. The
+nonce and signature are never logged.
+
+The verifier is configured once via `configure(...)` (closed over by the factory) so handlers
+stay declarative; `auths_principal` reads it from a module-level holder.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Awaitable, Callable
+
+from fastapi import HTTPException, Request
+
+from .models import Capability, Principal
+from .verifier import PresentationDenied, PresentationVerifier
+
+# 401 responses MUST advertise the accepted scheme. We use `Bearer` (not the custom
+# `Auths-Presentation`) so generic HTTP clients/proxies treat it as a standard challenge,
+# matching the reference middleware's WWW-Authenticate contract.
+_WWW_AUTHENTICATE = {"WWW-Authenticate": "Bearer"}
+
+
+class _Config:
+    """The once-configured verifier the factory closes over (set via `configure`)."""
+
+    verifier: PresentationVerifier | None = None
+
+
+def configure(verifier: PresentationVerifier) -> None:
+    """Install the process-wide presentation verifier the dependency uses.
+
+    Call once at app startup with either the production `KeriPresentationVerifier` or a fake
+    (tests). All `auths_principal(...)` dependencies resolve against this verifier.
+
+    Args:
+    * `verifier`: The verifier (production or test fake) implementing `PresentationVerifier`.
+
+    Usage:
+    ```python
+    configure(KeriPresentationVerifier(audience, store, load_inputs, pinned_roots))
+    ```
+    """
+    _Config.verifier = verifier
+
+
+def _now() -> datetime:
+    """Sample the wall clock at the HTTP boundary (the presentation-layer clock read)."""
+    return datetime.now(timezone.utc)
+
+
+def _authenticate(request: Request, required: Capability | None) -> Principal:
+    """Run the header → verifier → capability pipeline, raising `HTTPException` on failure."""
+    verifier = _Config.verifier
+    if verifier is None:
+        raise HTTPException(status_code=500, detail="auths verifier not configured")
+
+    header = request.headers.get("Authorization")
+    if header is None:
+        raise HTTPException(
+            status_code=401, detail="authentication required", headers=_WWW_AUTHENTICATE
+        )
+
+    try:
+        principal = verifier.verify(header, _now())
+    except PresentationDenied as denied:
+        headers = _WWW_AUTHENTICATE if denied.status_code == 401 else None
+        raise HTTPException(
+            status_code=denied.status_code, detail=denied.detail, headers=headers
+        ) from denied
+
+    if required is not None and not principal.authorize(required):
+        raise HTTPException(status_code=403, detail="insufficient capability")
+
+    return principal
+
+
+def auths_principal(
+    capability: Capability | None = None,
+) -> Callable[[Request], Awaitable[Principal]]:
+    """Build a FastAPI dependency yielding a verified `Principal` (or raising `HTTPException`).
+
+    Use at the route level to receive the `Principal`, or at the router level
+    (`APIRouter(dependencies=[Depends(auths_principal(cap))])`) to guard a whole group without
+    binding the principal into each handler.
+
+    Args:
+    * `capability`: The capability the guarded route(s) require; omit to authenticate only.
+
+    Usage:
+    ```python
+    @app.post("/v1/deploy")
+    async def deploy(principal: Principal = Depends(auths_principal(Capability("deploy:prod")))):
+        ...
+    ```
+    """
+
+    async def dependency(request: Request) -> Principal:
+        return _authenticate(request, capability)
+
+    return dependency