auths-fastapi 0.1.3__py3-none-any.whl

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/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/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/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

auths_fastapi/models.py

@@ -0,0 +1,69 @@
+"""Typed principal and capability models.
+
+Mirrors `auths_rp::principal` (`VerifiedPrincipal` / `Capability`): a `Principal` is
+constructed only by a verifier on a successful verdict, so possessing one is proof the
+holder demonstrated current key control. `authorize` returns a bool here (the FastAPI
+dependency raises on failure); the capability is a typed wrapper, never a bare string —
+authority is compared by value identity, not by magic-string equality at call sites.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Capability:
+    """A required-or-granted capability, compared by value (never a bare magic string).
+
+    Args:
+    * `name`: The capability string (e.g. `deploy:prod`).
+
+    Usage:
+    ```python
+    needed = Capability("deploy:prod")
+    assert needed == Capability("deploy:prod")
+    ```
+    """
+
+    name: str
+
+    def __str__(self) -> str:
+        return self.name
+
+
+@dataclass(frozen=True)
+class Principal:
+    """A verified, scoped identity yielded by a successful presentation verdict.
+
+    There is no path to a `Principal` other than a verifier returning one from a `VALID`
+    verdict, so a handler that receives a `Principal` is reachable only on an authenticated
+    request. Capabilities come from the verified credential, never from the request.
+
+    Args:
+    * `issuer`: The credential issuer AID.
+    * `subject`: The holder AID whose current key signed the presentation.
+    * `caps`: The granted capabilities (immutable tuple).
+    * `role`: An optional informational role claim.
+    * `expires_at`: An optional credential expiry (RFC-3339).
+
+    Usage:
+    ```python
+    principal = Principal(issuer="did:keri:E…", subject="did:keri:E…", caps=(Capability("deploy:prod"),))
+    assert principal.authorize(Capability("deploy:prod"))
+    ```
+    """
+
+    issuer: str
+    subject: str
+    caps: tuple[Capability, ...]
+    role: str | None = None
+    expires_at: str | None = None
+
+    def authorize(self, capability: Capability) -> bool:
+        """Whether this principal carries `capability`.
+
+        Args:
+        * `capability`: The capability the route/tool requires.
+        """
+        return capability in self.caps

auths_fastapi/verifier.py

@@ -0,0 +1,332 @@
+"""The injectable verification step: wire token → verified `Principal`.
+
+Mirrors `auths_api::rp_auth::PresentationVerifier`: the crypto check is behind a Protocol so
+the production KERI path and the tests share one dependency factory. The production
+`KeriPresentationVerifier` parses the wire token, consumes the single-use challenge against
+the REAL store, loads the KEL/TEL inputs (app-supplied), builds the camelCase
+`VerifyPresentationRequest` bundle, calls the native `auths.verify_presentation`, enforces
+pinned roots, and maps the status to a `Principal` or raises `PresentationDenied`.
+
+Tests inject a fake verifier over the same real `ChallengeStore`, so replay/audience are
+genuinely exercised with no native binding installed.
+
+The nonce and signature are never logged here or by callers.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Callable, Protocol
+
+from .challenge_store import ChallengeStore
+from .models import Capability, Principal
+
+
+class PresentationDenied(Exception):
+    """A presentation was rejected; `status_code` is the HTTP class to surface.
+
+    Args:
+    * `status_code`: 400/401/403/503 per the verdict-to-status mapping.
+    * `detail`: A coarse, non-sensitive reason (never the nonce or signature).
+    """
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(detail)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class PresentationVerifier(Protocol):
+    """Turn a wire token into a verified `Principal`, consuming its challenge.
+
+    The implementation owns the single-use consume so replay protection is enforced in one
+    place. It raises `PresentationDenied` on any failure and returns a `Principal` only on a
+    fully-valid, pinned-root presentation.
+    """
+
+    def verify(self, wire_token: str, now: datetime) -> Principal:
+        """Verify `wire_token` as of `now`, consuming its single-use challenge.
+
+        Args:
+        * `wire_token`: The base64url(JSON) token from the `Authorization` header.
+        * `now`: Verification time, injected at the HTTP boundary.
+        """
+        ...
+
+
+@dataclass(frozen=True)
+class WirePresentation:
+    """The untrusted wire shape decoded from the `Auths-Presentation` token.
+
+    Externally-tagged binding: exactly one of `challenge_nonce` / `ttl_nonce` is set.
+
+    Args:
+    * `credential_said`: The presented credential SAID.
+    * `audience`: The audience the client claims to bind to.
+    * `signature_b64url`: The presentation signature (base64url, no pad).
+    * `challenge_nonce`: The interactive-mode nonce (base64url), if challenge-bound.
+    * `ttl_nonce`: The TTL-mode nonce (base64url), if TTL-bound.
+    * `ttl_not_after`: The TTL-mode expiry (RFC-3339), if TTL-bound.
+    """
+
+    credential_said: str
+    audience: str
+    signature_b64url: str
+    challenge_nonce: str | None = None
+    ttl_nonce: str | None = None
+    ttl_not_after: str | None = None
+
+    @property
+    def nonce(self) -> str:
+        """The bound nonce regardless of mode (base64url)."""
+        value = self.challenge_nonce if self.challenge_nonce is not None else self.ttl_nonce
+        if value is None:
+            raise ValueError("presentation has no nonce")
+        return value
+
+
+def parse_presentation_token(token: str) -> WirePresentation:
+    """Decode a base64url(JSON) presentation token into a `WirePresentation`.
+
+    Raises `ValueError` on any structural problem; the caller maps that to HTTP 400/401.
+    The token is never logged.
+
+    Args:
+    * `token`: The base64url(JSON) value after the `Auths-Presentation ` scheme.
+    """
+    raw = base64.urlsafe_b64decode(_pad(token))
+    document = json.loads(raw)
+    binding = document["binding"]
+    if "challenge" in binding:
+        return WirePresentation(
+            credential_said=document["credential_said"],
+            audience=document["audience"],
+            signature_b64url=document["signature_b64"],
+            challenge_nonce=binding["challenge"]["nonce"],
+        )
+    if "ttl" in binding:
+        ttl = binding["ttl"]
+        return WirePresentation(
+            credential_said=document["credential_said"],
+            audience=document["audience"],
+            signature_b64url=document["signature_b64"],
+            ttl_nonce=ttl["nonce"],
+            ttl_not_after=ttl["not_after"],
+        )
+    raise ValueError("unknown presentation binding")
+
+
+def parse_presentation_header(authorization: str) -> WirePresentation:
+    """Parse an `Authorization: Auths-Presentation <token>` header value.
+
+    The scheme is case-sensitive and separated by exactly one space. Raises `ValueError`
+    (mapped to HTTP 400/401) for a missing/wrong scheme or a malformed token.
+
+    Args:
+    * `authorization`: The raw `Authorization` header value.
+    """
+    scheme, _, token = authorization.partition(" ")
+    if scheme != "Auths-Presentation":
+        raise ValueError("wrong Authorization scheme")
+    if not token.strip():
+        raise ValueError("missing presentation token")
+    return parse_presentation_token(token.strip())
+
+
+def _pad(b64url: str) -> str:
+    """Restore base64 padding stripped on the wire."""
+    return b64url + "=" * (-len(b64url) % 4)
+
+
+def _b64url_to_standard_b64(b64url: str) -> str:
+    """Re-encode a base64url (no-pad) value as standard base64 (the bundle's encoding).
+
+    The wire carries nonce/signature as URL-safe base64 without padding; the native
+    `VerifyPresentationRequest` expects standard base64. Decode then re-encode rather than
+    char-substituting so an invalid payload is caught here.
+
+    Args:
+    * `b64url`: A URL-safe, unpadded base64 string.
+    """
+    return base64.standard_b64encode(base64.urlsafe_b64decode(_pad(b64url))).decode("ascii")
+
+
+@dataclass(frozen=True)
+class PresentationInputs:
+    """The KEL/TEL inputs the app resolves for a credential SAID.
+
+    These are the registry-resolved documents the native verifier needs; the relying party
+    supplies them via the `load_inputs` callback so this package stays free of storage/Git.
+    Each KEL/TEL entry is a parsed JSON object (the native bundle embeds them inline).
+
+    Args:
+    * `credential`: The signed ACDC (`{"acdc": …, "signatureB64": …}`) object.
+    * `issuer_kel`: The issuer's key event log events.
+    * `subject_kel`: The subject (holder) KEL events.
+    * `delegator_kel`: The subject's delegator KEL events (empty if none).
+    * `tel`: The credential's transaction event log events.
+    * `receipts`: Witness receipts (empty under first-party `warn` policy).
+    """
+
+    credential: dict[str, object]
+    issuer_kel: list[dict[str, object]]
+    subject_kel: list[dict[str, object]]
+    delegator_kel: list[dict[str, object]] = field(default_factory=list)
+    tel: list[dict[str, object]] = field(default_factory=list)
+    receipts: list[dict[str, object]] = field(default_factory=list)
+
+
+# The app-supplied loader: credential SAID → registry-resolved inputs (raises on not-found).
+LoadInputs = Callable[[str], PresentationInputs]
+
+
+# Status strings on the native `PresentationStatus` enum that this module maps to HTTP.
+_STATUS_TO_HTTP = {
+    "VALID": 200,
+    "HOLDER_NOT_CURRENT_KEY": 401,
+    "WRONG_AUDIENCE": 401,
+    "NONCE_MISMATCH_OR_CONSUMED": 401,
+    "EXPIRED": 401,
+    "SUBJECT_KEL_INVALID": 401,
+    "CREDENTIAL_NOT_VALID": 401,
+    "MALFORMED_REQUEST": 400,
+    "INPUT_TOO_LARGE": 400,
+    "UNSUPPORTED_SCHEMA_VERSION": 400,
+    "UNKNOWN": 401,
+}
+
+
+class KeriPresentationVerifier:
+    """Production verifier: native KERI presentation authentication over an app registry.
+
+    Flow (mirrors `authenticate_presentation`): parse the wire token → consume the
+    single-use challenge against the real store → `load_inputs(credential_said)` →
+    build the camelCase `VerifyPresentationRequest` (re-encoding base64url → standard
+    base64) → `auths.verify_presentation(json)` → enforce pinned roots → map the status to a
+    `Principal` or raise `PresentationDenied`.
+
+    The expected audience is the relying party's CONFIGURED audience, never the wire header.
+    `pinned_roots` is a DID-only allowlist (the `.auths/roots` model): the verified issuer
+    (or its delegator root) must be pinned, else 401. Capabilities come from the credential,
+    never from the request.
+
+    Args:
+    * `audience`: This relying party's canonical audience (the trust source).
+    * `challenges`: The single-use challenge store shared with the mint route.
+    * `load_inputs`: Resolves a credential SAID to its KEL/TEL inputs (raises if absent).
+    * `pinned_roots`: The set of trusted issuer/delegator DIDs (fail-closed if empty).
+
+    Usage:
+    ```python
+    verifier = KeriPresentationVerifier(
+        audience="api.example.com",
+        challenges=store,
+        load_inputs=resolve_from_registry,
+        pinned_roots={"did:keri:Eroot"},
+    )
+    ```
+    """
+
+    def __init__(
+        self,
+        audience: str,
+        challenges: ChallengeStore,
+        load_inputs: LoadInputs,
+        pinned_roots: frozenset[str],
+    ) -> None:
+        self._audience = audience
+        self._challenges = challenges
+        self._load_inputs = load_inputs
+        self._pinned_roots = pinned_roots
+
+    def verify(self, wire_token: str, now: datetime) -> Principal:
+        try:
+            wire = parse_presentation_header(wire_token)
+        except (ValueError, KeyError, json.JSONDecodeError) as exc:
+            raise PresentationDenied(400, "malformed presentation") from exc
+
+        if not self._challenges.consume(wire.audience, wire.nonce, now):
+            raise PresentationDenied(401, "challenge replayed, expired, or unknown")
+
+        try:
+            inputs = self._load_inputs(wire.credential_said)
+        except LookupError as exc:
+            raise PresentationDenied(401, "credential could not be resolved") from exc
+
+        request = self._build_request(wire, inputs, now)
+        report = _verify_presentation_native(json.dumps(request))
+        return self._map_report(report)
+
+    def _build_request(
+        self, wire: WirePresentation, inputs: PresentationInputs, now: datetime
+    ) -> dict[str, object]:
+        """Assemble the camelCase `VerifyPresentationRequest` bundle for the native verifier.
+
+        Wire nonce/signature are base64url (no pad); the bundle wants standard base64, so they
+        are re-encoded here. The expected challenge is the configured store's nonce — the same
+        value that was just consumed — re-encoded the same way.
+        """
+        return {
+            "schemaVersion": 1,
+            "envelope": {
+                "credentialSaid": wire.credential_said,
+                "audience": wire.audience,
+                "binding": {
+                    "mode": "challenge",
+                    "nonceB64": _b64url_to_standard_b64(wire.nonce),
+                },
+                "signatureB64": _b64url_to_standard_b64(wire.signature_b64url),
+            },
+            "credential": inputs.credential,
+            "issuerKel": inputs.issuer_kel,
+            "subjectKel": inputs.subject_kel,
+            "delegatorKel": inputs.delegator_kel,
+            "tel": inputs.tel,
+            "receipts": inputs.receipts,
+            "witnessPolicy": "warn",
+            "audience": self._audience,
+            "expectedChallengeB64": _b64url_to_standard_b64(wire.nonce),
+            "now": now.isoformat(),
+        }
+
+    def _map_report(self, report: object) -> Principal:
+        """Map a native `PresentationReport` to a `Principal` or raise `PresentationDenied`."""
+        status = getattr(report, "status")
+        status_name = getattr(status, "name", str(status))
+        if status_name != "VALID":
+            raise PresentationDenied(
+                _STATUS_TO_HTTP.get(status_name, 401), "presentation rejected"
+            )
+
+        issuer = getattr(report, "issuer")
+        if issuer not in self._pinned_roots:
+            raise PresentationDenied(401, "issuer is not a pinned root")
+
+        caps = tuple(Capability(name) for name in (getattr(report, "caps") or []))
+        return Principal(
+            issuer=issuer,
+            subject=getattr(report, "subject"),
+            caps=caps,
+            role=getattr(report, "role", None),
+            expires_at=getattr(report, "expires_at", None),
+        )
+
+
+def _verify_presentation_native(request_json: str) -> object:
+    """Call the native `auths.verify_presentation`, importing the optional binding lazily.
+
+    Importing inside the call keeps the package importable (and its fake-verifier tests
+    runnable) with no native binding installed.
+
+    Args:
+    * `request_json`: The camelCase `VerifyPresentationRequest` JSON document.
+    """
+    import auths
+
+    # The native binding is an optional extra; do not couple static checking to whatever
+    # build is installed (its typed surface is the binding package's own concern).
+    native: Any = auths
+    return native.verify_presentation(request_json)

auths_fastapi-0.1.3.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+auths_fastapi/__init__.py,sha256=gALTbhuC_zhm83IvRjl_gjBbv_gK7ZdaVx_Moppumck,1909
+auths_fastapi/challenge_route.py,sha256=7OV6OItka_eGkBCHV06A0b1TapoDoNDqvqbeAj8P-LE,2665
+auths_fastapi/challenge_store.py,sha256=_eVoWEsMZQgc0NdJTbtbwWhm-is85q2iJ3viwQbhEqk,4770
+auths_fastapi/dependency.py,sha256=FPdB7cS9X5oiZqW1J9BirQeubjhrKzVnjue0MVKO9F8,4208
+auths_fastapi/models.py,sha256=GbhNWqzERs4u3qklTYTSZx_MzlUax0ZSugtTvSaPHgI,2226
+auths_fastapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auths_fastapi/verifier.py,sha256=ky1VTkdk4N-uOuARm0_DduxAF6CVSvWbTBY0ZPToVJ8,13041
+auths_fastapi-0.1.3.dist-info/METADATA,sha256=As_9A6TqBv7hkIL82DZsqNrk2QEquBD27-xM8liWgFY,5546
+auths_fastapi-0.1.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+auths_fastapi-0.1.3.dist-info/RECORD,,

auths_fastapi-0.1.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any