qx-auth 0.1.0__tar.gz

qx_auth-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+.eggs/
+sdist/
+wheels/
+*.egg-link
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.env.local
+
+# Dist artifacts
+dist/

qx_auth-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: qx-auth
+Version: 0.1.0
+Summary: Qx auth: JWT validation, OIDC client, RBAC primitives, policy engine, rate limiting
+Author: Qx Engineering
+License: MIT
+Requires-Python: >=3.14
+Requires-Dist: cryptography>=43.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyjwt[crypto]>=2.9.0
+Requires-Dist: qx-cache
+Requires-Dist: qx-core
+Requires-Dist: qx-di
+Requires-Dist: qx-http
+Description-Content-Type: text/markdown
+
+# qx-auth
+
+JWT validation, OIDC discovery, RBAC primitives, policy engine, and token-bucket rate limiting for the Qx framework.
+
+## What lives here
+
+- **`qx.auth.JwtValidator`** — validates and decodes JWT access tokens. Supports RS256/ES256 via JWKS endpoint, audience and issuer validation, and a pluggable `RevocationCheck`.
+- **`qx.auth.JwtSettings`** — Pydantic settings: JWKS URI, issuer, audience, algorithm, leeway.
+- **`qx.auth.Principal`** — decoded token claims: `subject`, `email`, `roles`, `permissions`, `tenant_id`, raw claims dict.
+- **`qx.auth.OidcDiscovery`** — fetches and caches the OpenID Connect discovery document (`/.well-known/openid-configuration`). Populates `JwtSettings` from the discovery endpoint automatically.
+- **`qx.auth.OidcConfiguration`** — parsed OIDC discovery document.
+- **`qx.auth.Role` / `Permission`** — value objects for RBAC. `Role` contains a set of `Permission` strings with wildcard matching (`orders.*` matches `orders.read`).
+- **`qx.auth.PolicyEvaluator`** — evaluates a list of `Policy` objects against a `Principal`. Policies are composable with `require_permission`, `require_any_permission`, and `require_all_permissions`.
+- **`qx.auth.TokenBucket`** — in-memory token-bucket rate limiter. Returns a `TokenBucketResult` with `allowed`, `remaining`, and `retry_after` — no exceptions.
+
+## Usage
+
+### JWT validation in a FastAPI route
+
+```python
+from qx.auth import JwtValidator, Principal
+from fastapi import Depends, HTTPException
+from fastapi.security import HTTPBearer
+
+security = HTTPBearer()
+validator = JwtValidator(settings.jwt)
+
+async def current_principal(token=Depends(security)) -> Principal:
+    result = await validator.validate(token.credentials)
+    if not result.is_success:
+        raise HTTPException(status_code=401)
+    return result.value
+```
+
+### Policy evaluation
+
+```python
+from qx.auth import PolicyEvaluator, require_permission
+
+evaluator = PolicyEvaluator([require_permission("users.write")])
+decision = evaluator.evaluate(principal)
+if not decision.allowed:
+    return Result.failure(ForbiddenError(...))
+```
+
+### Token-bucket rate limiting
+
+```python
+from qx.auth import TokenBucket
+
+bucket = TokenBucket(capacity=100, refill_rate=10)  # 10 tokens/sec
+
+result = bucket.consume(principal.subject)
+if not result.allowed:
+    return Result.failure(RateLimitedError(retry_after=result.retry_after))
+```
+
+## Design rules
+
+- `JwtValidator.validate()` returns `Result[Principal]` — it never raises. Callers decide how to translate validation failures to HTTP responses.
+- JWKS are cached and refreshed lazily on key-ID miss so a key rotation doesn't require a restart.
+- Permission wildcards follow a simple dot-separated scheme: `"orders.*"` grants all permissions starting with `"orders."`. Policies compose with AND (`require_all_permissions`) or OR (`require_any_permission`) semantics.

qx_auth-0.1.0/README.md

@@ -0,0 +1,62 @@
+# qx-auth
+
+JWT validation, OIDC discovery, RBAC primitives, policy engine, and token-bucket rate limiting for the Qx framework.
+
+## What lives here
+
+- **`qx.auth.JwtValidator`** — validates and decodes JWT access tokens. Supports RS256/ES256 via JWKS endpoint, audience and issuer validation, and a pluggable `RevocationCheck`.
+- **`qx.auth.JwtSettings`** — Pydantic settings: JWKS URI, issuer, audience, algorithm, leeway.
+- **`qx.auth.Principal`** — decoded token claims: `subject`, `email`, `roles`, `permissions`, `tenant_id`, raw claims dict.
+- **`qx.auth.OidcDiscovery`** — fetches and caches the OpenID Connect discovery document (`/.well-known/openid-configuration`). Populates `JwtSettings` from the discovery endpoint automatically.
+- **`qx.auth.OidcConfiguration`** — parsed OIDC discovery document.
+- **`qx.auth.Role` / `Permission`** — value objects for RBAC. `Role` contains a set of `Permission` strings with wildcard matching (`orders.*` matches `orders.read`).
+- **`qx.auth.PolicyEvaluator`** — evaluates a list of `Policy` objects against a `Principal`. Policies are composable with `require_permission`, `require_any_permission`, and `require_all_permissions`.
+- **`qx.auth.TokenBucket`** — in-memory token-bucket rate limiter. Returns a `TokenBucketResult` with `allowed`, `remaining`, and `retry_after` — no exceptions.
+
+## Usage
+
+### JWT validation in a FastAPI route
+
+```python
+from qx.auth import JwtValidator, Principal
+from fastapi import Depends, HTTPException
+from fastapi.security import HTTPBearer
+
+security = HTTPBearer()
+validator = JwtValidator(settings.jwt)
+
+async def current_principal(token=Depends(security)) -> Principal:
+    result = await validator.validate(token.credentials)
+    if not result.is_success:
+        raise HTTPException(status_code=401)
+    return result.value
+```
+
+### Policy evaluation
+
+```python
+from qx.auth import PolicyEvaluator, require_permission
+
+evaluator = PolicyEvaluator([require_permission("users.write")])
+decision = evaluator.evaluate(principal)
+if not decision.allowed:
+    return Result.failure(ForbiddenError(...))
+```
+
+### Token-bucket rate limiting
+
+```python
+from qx.auth import TokenBucket
+
+bucket = TokenBucket(capacity=100, refill_rate=10)  # 10 tokens/sec
+
+result = bucket.consume(principal.subject)
+if not result.allowed:
+    return Result.failure(RateLimitedError(retry_after=result.retry_after))
+```
+
+## Design rules
+
+- `JwtValidator.validate()` returns `Result[Principal]` — it never raises. Callers decide how to translate validation failures to HTTP responses.
+- JWKS are cached and refreshed lazily on key-ID miss so a key rotation doesn't require a restart.
+- Permission wildcards follow a simple dot-separated scheme: `"orders.*"` grants all permissions starting with `"orders."`. Policies compose with AND (`require_all_permissions`) or OR (`require_any_permission`) semantics.

qx_auth-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "qx-auth"
+version = "0.1.0"
+description = "Qx auth: JWT validation, OIDC client, RBAC primitives, policy engine, rate limiting"
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Qx Engineering" }]
+dependencies = [
+    "qx-core",
+    "qx-di",
+    "qx-cache",
+    "qx-http",
+    "pyjwt[crypto]>=2.9.0",
+    "httpx>=0.27.0",
+    "cryptography>=43.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qx"]

qx_auth-0.1.0/src/qx/auth/__init__.py

@@ -0,0 +1,45 @@
+"""Qx auth: JWT validation, OIDC, RBAC, policies, rate limiting."""
+
+from __future__ import annotations
+
+from qx.auth.jwt import JwtSettings, JwtValidator, Principal, RevocationCheck
+from qx.auth.oidc import OidcConfiguration, OidcDiscovery
+from qx.auth.policy import (
+    Decision,
+    Policy,
+    PolicyEvaluator,
+    PolicyResult,
+    require_all_permissions,
+    require_any_permission,
+    require_permission,
+)
+from qx.auth.rate_limit import TokenBucket, TokenBucketResult
+from qx.auth.rbac import Permission, Role
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Policy
+    "Decision",
+    # JWT
+    "JwtSettings",
+    "JwtValidator",
+    # OIDC
+    "OidcConfiguration",
+    "OidcDiscovery",
+    # RBAC
+    "Permission",
+    "Policy",
+    "PolicyEvaluator",
+    "PolicyResult",
+    "Principal",
+    "RevocationCheck",
+    "Role",
+    # Rate limit
+    "TokenBucket",
+    "TokenBucketResult",
+    "__version__",
+    "require_all_permissions",
+    "require_any_permission",
+    "require_permission",
+]

qx_auth-0.1.0/src/qx/auth/jwt/__init__.py

@@ -0,0 +1,249 @@
+"""JWT validation.
+
+Validates inbound JWTs against a configured issuer (typically Qx's own
+IdP, or any OIDC-compliant authority). Public keys come from the issuer's
+JWKS endpoint with TTL caching to avoid hammering the IdP on every request.
+
+What we validate:
+- Signature (RS256/ES256 by default; configurable list).
+- ``iss`` matches the configured issuer.
+- ``aud`` includes the configured audience.
+- ``exp`` is in the future (with a small clock-skew tolerance).
+- ``nbf`` is in the past (likewise).
+- Optional: ``azp`` (authorized party) for OIDC.
+
+What we don't do here:
+- Token revocation: that needs a separate check against a revocation store
+  (Redis-backed JTI deny-list, or token introspection). Plug it in via the
+  ``revocation_check`` hook.
+
+Output: a ``Principal`` value object that downstream code consumes — never
+the raw claims dict. Keeps the security boundary clean.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+from uuid import UUID
+
+import httpx
+import jwt
+from jwt import PyJWKClient
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from qx.core import (
+    InfrastructureError,
+    Result,
+    UnauthorizedError,
+)
+
+__all__ = [
+    "JwtSettings",
+    "JwtValidator",
+    "Principal",
+    "RevocationCheck",
+]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Principal:
+    """Authenticated identity.
+
+    The result of validating a JWT — pure value object, no JWT internals leak
+    past this point. Downstream policy / RBAC code consumes the ``permissions``
+    and ``roles`` collections.
+    """
+
+    subject: UUID
+    issuer: str
+    tenant_id: UUID | None = None
+    email: str | None = None
+    name: str | None = None
+    roles: frozenset[str] = field(default_factory=frozenset)
+    permissions: frozenset[str] = field(default_factory=frozenset)
+    scopes: frozenset[str] = field(default_factory=frozenset)
+    raw_claims: dict[str, Any] = field(default_factory=dict)
+
+    def has_role(self, role: str) -> bool:
+        return role in self.roles
+
+    def has_permission(self, permission: str) -> bool:
+        return permission in self.permissions
+
+    def has_scope(self, scope: str) -> bool:
+        return scope in self.scopes
+
+
+RevocationCheck = Callable[[str], Awaitable[bool]]
+"""Async function taking a JTI; returns True if revoked."""
+
+
+class JwtSettings(BaseSettings):
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix="QX_AUTH__JWT__",
+        extra="ignore",
+    )
+
+    issuer: str = Field(default="https://qx.local")
+    jwks_uri: str | None = None  # if None, fetch from {issuer}/.well-known/jwks.json
+    audience: str = "qx"
+    allowed_algorithms: tuple[str, ...] = ("RS256", "ES256")
+    leeway_seconds: int = 30
+    cache_keys_ttl_seconds: int = 3600
+
+
+class JwtValidator:
+    """Validate JWTs against a configured OIDC-compatible issuer."""
+
+    def __init__(
+        self,
+        settings: JwtSettings,
+        *,
+        revocation_check: RevocationCheck | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._settings = settings
+        self._revocation_check = revocation_check
+        self._http = http_client or httpx.AsyncClient(timeout=5.0)
+        self._jwks_uri = settings.jwks_uri or f"{settings.issuer.rstrip('/')}/.well-known/jwks.json"
+        # PyJWKClient caches keys internally with built-in TTL semantics.
+        self._jwk_client = PyJWKClient(
+            self._jwks_uri,
+            cache_keys=True,
+            lifespan=settings.cache_keys_ttl_seconds,
+        )
+
+    async def validate(self, token: str) -> Result[Principal]:  # noqa: PLR0911
+        # Pull the right key for this token's `kid` header.
+        try:
+            signing_key = self._jwk_client.get_signing_key_from_jwt(token).key
+        except jwt.exceptions.PyJWKClientError as exc:
+            return Result.failure(
+                InfrastructureError(
+                    code="auth.jwks_unavailable",
+                    message=f"could not fetch signing key: {exc}",
+                    cause=exc,
+                )
+            )
+        except Exception as exc:
+            return Result.failure(
+                UnauthorizedError(
+                    code="auth.invalid_token",
+                    message="token signature could not be verified",
+                    cause=exc,
+                )
+            )
+
+        try:
+            claims = jwt.decode(
+                token,
+                key=signing_key,
+                algorithms=list(self._settings.allowed_algorithms),
+                audience=self._settings.audience,
+                issuer=self._settings.issuer,
+                leeway=self._settings.leeway_seconds,
+                options={"require": ["exp", "iat", "iss", "aud", "sub"]},
+            )
+        except jwt.ExpiredSignatureError as exc:
+            return Result.failure(
+                UnauthorizedError(
+                    code="auth.token_expired",
+                    message="token expired",
+                    cause=exc,
+                )
+            )
+        except jwt.InvalidAudienceError as exc:
+            return Result.failure(
+                UnauthorizedError(
+                    code="auth.invalid_audience",
+                    message="token audience does not include this service",
+                    cause=exc,
+                )
+            )
+        except jwt.InvalidIssuerError as exc:
+            return Result.failure(
+                UnauthorizedError(
+                    code="auth.invalid_issuer",
+                    message="token issuer is not trusted",
+                    cause=exc,
+                )
+            )
+        except jwt.InvalidTokenError as exc:
+            return Result.failure(
+                UnauthorizedError(
+                    code="auth.invalid_token",
+                    message=f"token rejected: {exc}",
+                    cause=exc,
+                )
+            )
+
+        # Revocation hook.
+        jti = claims.get("jti")
+        if jti and self._revocation_check is not None:
+            try:
+                if await self._revocation_check(jti):
+                    return Result.failure(
+                        UnauthorizedError(
+                            code="auth.token_revoked",
+                            message="token has been revoked",
+                        )
+                    )
+            except Exception as exc:
+                # Fail closed on revocation-check infrastructure errors.
+                return Result.failure(
+                    InfrastructureError(
+                        code="auth.revocation_check_failed",
+                        message=f"revocation check failed: {exc}",
+                        cause=exc,
+                    )
+                )
+
+        # Map claims to Principal. Convention follows OIDC + a few Qx
+        # extensions (qx:permissions, qx:tenant).
+        try:
+            sub = UUID(claims["sub"])
+        except (KeyError, ValueError) as exc:
+            return Result.failure(
+                UnauthorizedError(
+                    code="auth.invalid_subject",
+                    message="sub claim is missing or not a UUID",
+                    cause=exc,
+                )
+            )
+
+        tenant_raw = claims.get("qx:tenant") or claims.get("tenant_id")
+        tenant_id: UUID | None = None
+        if tenant_raw:
+            try:
+                tenant_id = UUID(tenant_raw)
+            except ValueError:
+                # Tenant present but malformed — treat as unauth rather than ignore.
+                return Result.failure(
+                    UnauthorizedError(
+                        code="auth.invalid_tenant",
+                        message="tenant_id claim is malformed",
+                    )
+                )
+
+        roles = claims.get("qx:roles") or claims.get("roles") or []
+        permissions = claims.get("qx:permissions") or claims.get("permissions") or []
+        scopes_raw = claims.get("scope") or claims.get("scp") or ""
+        scopes = scopes_raw.split() if isinstance(scopes_raw, str) else list(scopes_raw)
+
+        principal = Principal(
+            subject=sub,
+            issuer=claims["iss"],
+            tenant_id=tenant_id,
+            email=claims.get("email"),
+            name=claims.get("name") or claims.get("preferred_username"),
+            roles=frozenset(roles),
+            permissions=frozenset(permissions),
+            scopes=frozenset(scopes),
+            raw_claims=claims,
+        )
+        return Result.success(principal)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()

qx_auth-0.1.0/src/qx/auth/oidc/__init__.py

@@ -0,0 +1,103 @@
+"""OIDC discovery client.
+
+For services that need full OIDC discovery (not just JWT validation against a
+known JWKS URI), this fetches the issuer's well-known config and exposes
+endpoints with sensible TTL caching.
+
+Used by:
+
+- ``JwtValidator`` when no ``jwks_uri`` is configured — fall back to discovery.
+- Services that initiate authorization code flows (rare server-to-server, but
+  used by admin tooling and console BFFs).
+
+Out of scope: the actual auth-code flow, PKCE state management, token storage.
+Qx's hosted UI handles browser-flow auth; this module is just the
+plumbing for backend services to validate the resulting tokens.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from qx.core import InfrastructureError, Result
+
+if TYPE_CHECKING:
+    import httpx
+
+__all__ = ["OidcConfiguration", "OidcDiscovery"]
+
+
+@dataclass(frozen=True)
+class OidcConfiguration:
+    issuer: str
+    authorization_endpoint: str | None
+    token_endpoint: str | None
+    userinfo_endpoint: str | None
+    jwks_uri: str
+    end_session_endpoint: str | None
+    introspection_endpoint: str | None
+    raw: dict[str, Any]
+
+
+class OidcDiscovery:
+    """Fetches and caches OIDC ``.well-known`` configuration."""
+
+    def __init__(
+        self,
+        http_client: httpx.AsyncClient,
+        *,
+        cache_ttl_seconds: int = 3600,
+    ) -> None:
+        self._http = http_client
+        self._ttl = cache_ttl_seconds
+        self._cache: dict[str, tuple[float, OidcConfiguration]] = {}
+        self._lock = asyncio.Lock()
+
+    async def fetch(self, issuer: str) -> Result[OidcConfiguration]:
+        now = time.monotonic()
+        cached = self._cache.get(issuer)
+        if cached is not None and (now - cached[0]) < self._ttl:
+            return Result.success(cached[1])
+
+        async with self._lock:
+            # Double-check inside the lock.
+            cached = self._cache.get(issuer)
+            if cached is not None and (now - cached[0]) < self._ttl:
+                return Result.success(cached[1])
+            url = f"{issuer.rstrip('/')}/.well-known/openid-configuration"
+            try:
+                resp = await self._http.get(url, timeout=5.0)
+                resp.raise_for_status()
+            except Exception as exc:
+                return Result.failure(
+                    InfrastructureError(
+                        code="oidc.discovery_failed",
+                        message=f"could not fetch {url}: {exc}",
+                        cause=exc,
+                    )
+                )
+            data = resp.json()
+            try:
+                config = OidcConfiguration(
+                    issuer=data["issuer"],
+                    authorization_endpoint=data.get("authorization_endpoint"),
+                    token_endpoint=data.get("token_endpoint"),
+                    userinfo_endpoint=data.get("userinfo_endpoint"),
+                    jwks_uri=data["jwks_uri"],
+                    end_session_endpoint=data.get("end_session_endpoint"),
+                    introspection_endpoint=data.get("introspection_endpoint"),
+                    raw=data,
+                )
+            except KeyError as exc:
+                return Result.failure(
+                    InfrastructureError(
+                        code="oidc.malformed_discovery",
+                        message=f"required discovery field missing: {exc}",
+                        cause=exc,
+                    )
+                )
+            self._cache[issuer] = (now, config)
+            return Result.success(config)

qx_auth-0.1.0/src/qx/auth/policy/__init__.py

@@ -0,0 +1,129 @@
+"""Policy evaluator.
+
+The policy layer answers: "is this principal allowed to perform this action
+on this resource?" Two flavors:
+
+- ``require_permission(perm)`` — the bread-and-butter RBAC check.
+- ``Policy`` — a composable predicate over (Principal, Resource) for cases
+  where pure RBAC isn't enough (e.g., "user can edit a comment if they own
+  it or have the ``moderate`` permission").
+
+Decisions are ``Allow`` / ``Deny``. Deny wins on conflict — this is the
+standard ABAC / Zanzibar convention; it's also less surprising for
+developers reading auth code.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from qx.auth.rbac import Permission
+from qx.core import ForbiddenError, Result
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from qx.auth.jwt import Principal
+
+__all__ = [
+    "Decision",
+    "Policy",
+    "PolicyEvaluator",
+    "PolicyResult",
+    "require_all_permissions",
+    "require_any_permission",
+    "require_permission",
+]
+
+
+class Decision(Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    NOT_APPLICABLE = "not_applicable"
+
+
+@dataclass(frozen=True)
+class PolicyResult:
+    decision: Decision
+    reason: str | None = None
+
+
+@dataclass(frozen=True)
+class Policy:
+    """A named policy with an async predicate."""
+
+    name: str
+    rule: Callable[[Principal, Any], Awaitable[PolicyResult]]
+
+
+def require_permission(permission: str) -> Policy:
+    """Policy that allows iff the principal has the named permission."""
+    perm = Permission(name=permission)
+
+    async def _rule(p: Principal, _resource: Any) -> PolicyResult:
+        if perm.matches(p.permissions):
+            return PolicyResult(Decision.ALLOW)
+        return PolicyResult(Decision.DENY, reason=f"missing required permission: {permission}")
+
+    return Policy(name=f"require_permission({permission})", rule=_rule)
+
+
+def require_any_permission(*permissions: str) -> Policy:
+    perms = [Permission(name=p) for p in permissions]
+
+    async def _rule(p: Principal, _resource: Any) -> PolicyResult:
+        if any(perm.matches(p.permissions) for perm in perms):
+            return PolicyResult(Decision.ALLOW)
+        return PolicyResult(
+            Decision.DENY,
+            reason=f"missing any of: {', '.join(permissions)}",
+        )
+
+    return Policy(name=f"require_any({permissions})", rule=_rule)
+
+
+def require_all_permissions(*permissions: str) -> Policy:
+    perms = [Permission(name=p) for p in permissions]
+
+    async def _rule(p: Principal, _resource: Any) -> PolicyResult:
+        missing = [perm.name for perm in perms if not perm.matches(p.permissions)]
+        if missing:
+            return PolicyResult(
+                Decision.DENY,
+                reason=f"missing required permissions: {', '.join(missing)}",
+            )
+        return PolicyResult(Decision.ALLOW)
+
+    return Policy(name=f"require_all({permissions})", rule=_rule)
+
+
+class PolicyEvaluator:
+    """Compose policies and evaluate them against a principal."""
+
+    def __init__(self, *policies: Policy) -> None:
+        self._policies = policies
+
+    async def evaluate(
+        self,
+        principal: Principal,
+        resource: Any = None,
+    ) -> Result[None]:
+        """Return success if all policies allow; failure otherwise.
+
+        Deny semantics: as soon as any policy returns DENY, we short-circuit
+        with that reason. NOT_APPLICABLE policies are skipped (a policy that
+        doesn't have an opinion on this principal is treated as silent).
+        """
+        for policy in self._policies:
+            outcome = await policy.rule(principal, resource)
+            if outcome.decision is Decision.DENY:
+                return Result.failure(
+                    ForbiddenError(
+                        code="authz.denied",
+                        message=outcome.reason or f"denied by {policy.name}",
+                        details={"policy": policy.name},
+                    )
+                )
+        return Result.success(None)

qx_auth-0.1.0/src/qx/auth/rate_limit/__init__.py

@@ -0,0 +1,129 @@
+"""Token-bucket rate limiter backed by Redis.
+
+A token bucket holds N tokens; consumers take a token to perform an action.
+Tokens refill at rate R per second up to capacity N. If the bucket is empty,
+the action is rejected with ``Result.failure(RateLimitedError(...))``.
+
+Implementation: Lua script that atomically computes the current bucket
+contents from a stored ``(last_refill_at, last_count)`` pair, decides whether
+to take a token, and writes back. The Lua script avoids the read-then-write
+race that plagues naive implementations.
+
+Buckets are namespaced by ``(scope, key)`` — e.g., ``("login", user_id)`` or
+``("api", api_key)``. Same scope, same refill rate; different rates need
+different bucket names.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from qx.core import RateLimitedError, Result
+
+if TYPE_CHECKING:
+    import redis.asyncio as aioredis
+
+__all__ = ["TokenBucket", "TokenBucketResult"]
+
+
+_LUA_TAKE = """
+-- KEYS[1] = bucket key
+-- ARGV[1] = capacity, ARGV[2] = refill_per_second, ARGV[3] = now (float seconds)
+-- ARGV[4] = take (int), ARGV[5] = ttl (int)
+local capacity = tonumber(ARGV[1])
+local refill = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local take = tonumber(ARGV[4])
+local ttl = tonumber(ARGV[5])
+
+local data = redis.call('HMGET', KEYS[1], 'count', 'last')
+local count = tonumber(data[1])
+local last = tonumber(data[2])
+
+if count == nil then
+    count = capacity
+    last = now
+end
+
+local elapsed = now - last
+if elapsed > 0 then
+    count = math.min(capacity, count + (elapsed * refill))
+end
+
+local allowed = 0
+if count >= take then
+    count = count - take
+    allowed = 1
+end
+
+redis.call('HMSET', KEYS[1], 'count', count, 'last', now)
+redis.call('EXPIRE', KEYS[1], ttl)
+return {allowed, count}
+"""
+
+
+@dataclass(frozen=True)
+class TokenBucketResult:
+    allowed: bool
+    remaining: float
+
+
+class TokenBucket:
+    """Token-bucket rate limiter for one (scope, key) pair."""
+
+    def __init__(
+        self,
+        client: aioredis.Redis,
+        *,
+        scope: str,
+        capacity: int,
+        refill_per_second: float,
+        namespace: str = "qx:rl",
+    ) -> None:
+        self._r = client
+        self._scope = scope
+        self._capacity = capacity
+        self._refill = refill_per_second
+        self._ns = namespace
+
+    def _key(self, key: str) -> str:
+        return f"{self._ns}:{self._scope}:{key}"
+
+    async def take(self, key: str, *, tokens: int = 1) -> TokenBucketResult:
+        # TTL should be long enough that an idle key stays around until it
+        # would fully refill — otherwise we'd lose state and grant new
+        # capacity. ``capacity / refill_per_second`` * 2 is a safe default.
+        ttl = max(int((self._capacity / max(self._refill, 0.001)) * 2), 60)
+        result = await self._r.eval(  # type: ignore[misc]
+            _LUA_TAKE,
+            1,
+            self._key(key),
+            str(self._capacity),
+            str(self._refill),
+            str(time.time()),
+            str(tokens),
+            str(ttl),
+        )
+        allowed = bool(result[0])
+        remaining = float(result[1])
+        return TokenBucketResult(allowed=allowed, remaining=remaining)
+
+    async def check(self, key: str, *, tokens: int = 1) -> Result[None]:
+        """Take a token and convert the outcome to a ``Result``."""
+        outcome = await self.take(key, tokens=tokens)
+        if outcome.allowed:
+            return Result.success(None)
+        return Result.failure(
+            RateLimitedError(
+                code="rate_limit.exceeded",
+                message=f"rate limit exceeded for {self._scope}:{key}",
+                details={
+                    "scope": self._scope,
+                    "remaining": outcome.remaining,
+                    "capacity": self._capacity,
+                    "refill_per_second": self._refill,
+                },
+            )
+        )

qx_auth-0.1.0/src/qx/auth/rbac/__init__.py

@@ -0,0 +1,74 @@
+"""RBAC primitives.
+
+Permissions are dotted strings::
+
+    organization.read
+    organization.users.invite
+    billing.invoice.refund
+
+Convention:
+- First segment = resource scope (organization, billing, …)
+- Last segment = action (read, write, delete, invite, refund, …)
+- Wildcards allowed at any segment: ``billing.*`` (anything on billing),
+  ``organization.users.*`` (anything on users in an organization).
+
+Roles are named bundles of permissions. The policy layer is permission-
+centric, not role-centric — roles are user-facing labels; permissions are
+what we actually check.
+
+Matching:
+- ``user.permissions`` resolves any wildcards at issue-time (JWT contains
+  expanded permissions, not roles → permissions; the IdP does that). The
+  matcher here just checks whether ``required`` is in the set.
+- Policy code calls ``Permission.matches(required, granted_set)`` which
+  handles literal + wildcard matches.
+
+Why not a generic ABAC engine here? ABAC is great but overkill for V1; you
+implement it via a custom ``Behavior`` that pulls request attributes and runs
+your own rules. The RBAC primitive is the 80% case.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["Permission", "Role"]
+
+
+@dataclass(frozen=True)
+class Permission:
+    """A required permission name."""
+
+    name: str
+
+    def matches(self, granted: frozenset[str]) -> bool:
+        """Check if any granted permission satisfies this requirement.
+
+        ``granted`` is the principal's expanded permission set. Wildcards in
+        granted permissions (``billing.*``) match any required permission
+        starting with the same prefix.
+        """
+        if self.name in granted:
+            return True
+        # Wildcard matching — walk granted set looking for ``prefix.*`` patterns.
+        for g in granted:
+            if g.endswith(".*"):
+                prefix = g[:-2]
+                if self.name == prefix or self.name.startswith(prefix + "."):
+                    return True
+            if g == "*":
+                return True
+        return False
+
+
+@dataclass(frozen=True)
+class Role:
+    """A named bundle of permissions.
+
+    The role-to-permissions mapping lives in the IdP (Qx itself). This
+    type is a convenience for downstream code that wants to reason about role
+    names — but actual authorization decisions check permissions, not roles.
+    """
+
+    name: str
+    permissions: frozenset[Permission] = frozenset()

qx_auth-0.1.0/tests/test_auth_unit.py

@@ -0,0 +1,228 @@
+"""Auth unit tests.
+
+Generates RSA key pair in-memory, mints test JWTs, exercises ``JwtValidator``
+against them. No live IdP, no live Redis — pure logic.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+from uuid import uuid4
+
+import jwt
+import pytest
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from qx.auth import (
+    Decision,
+    JwtSettings,
+    JwtValidator,
+    Permission,
+    PolicyEvaluator,
+    Principal,
+    require_all_permissions,
+    require_any_permission,
+    require_permission,
+)
+from qx.auth.policy import Policy, PolicyResult
+
+# ---- RSA key pair + JWKS fixture ----
+
+
+@pytest.fixture(scope="module")
+def rsa_key() -> Any:
+    return rsa.generate_private_key(public_exponent=65537, key_size=2048)
+
+
+@pytest.fixture(scope="module")
+def private_pem(rsa_key: Any) -> bytes:
+    return rsa_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+@pytest.fixture(scope="module")
+def public_pem(rsa_key: Any) -> bytes:
+    return rsa_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+
+
+def _make_token(private_pem: bytes, **overrides: Any) -> str:
+    now = int(time.time())
+    claims = {
+        "iss": "https://test.qx",
+        "aud": "qx",
+        "sub": str(uuid4()),
+        "iat": now,
+        "exp": now + 60,
+        "email": "ada@example.com",
+        "name": "Ada Lovelace",
+        "qx:permissions": ["organization.read", "billing.invoice.read"],
+        "qx:roles": ["admin"],
+        "scope": "openid profile",
+        **overrides,
+    }
+    return jwt.encode(claims, private_pem, algorithm="RS256", headers={"kid": "test"})
+
+
+class _StubJwkClient:
+    """Stand-in for PyJWKClient that just returns our static key."""
+
+    def __init__(self, signing_key: Any) -> None:
+        self._key = signing_key
+
+    def get_signing_key_from_jwt(self, _token: str) -> Any:
+        class _K:
+            pass
+
+        k = _K()
+        k.key = self._key
+        return k
+
+
+# ---- JWT validation ----
+
+
+async def test_valid_token_yields_principal(private_pem: bytes, public_pem: bytes) -> None:
+    settings = JwtSettings(issuer="https://test.qx", audience="qx")
+    validator = JwtValidator(settings)
+    validator._jwk_client = _StubJwkClient(public_pem)
+    token = _make_token(private_pem)
+    result = await validator.validate(token)
+    assert result.is_success
+    p = result.value
+    assert p.email == "ada@example.com"
+    assert "admin" in p.roles
+    assert Permission(name="organization.read").matches(p.permissions)
+
+
+async def test_expired_token_rejected(private_pem: bytes, public_pem: bytes) -> None:
+    settings = JwtSettings(issuer="https://test.qx", audience="qx", leeway_seconds=0)
+    validator = JwtValidator(settings)
+    validator._jwk_client = _StubJwkClient(public_pem)
+    token = _make_token(private_pem, exp=int(time.time()) - 60, iat=int(time.time()) - 120)
+    result = await validator.validate(token)
+    assert result.is_failure
+    assert result.error.code == "auth.token_expired"
+
+
+async def test_wrong_audience_rejected(private_pem: bytes, public_pem: bytes) -> None:
+    settings = JwtSettings(issuer="https://test.qx", audience="qx")
+    validator = JwtValidator(settings)
+    validator._jwk_client = _StubJwkClient(public_pem)
+    token = _make_token(private_pem, aud="someone-else")
+    result = await validator.validate(token)
+    assert result.is_failure
+    assert result.error.code == "auth.invalid_audience"
+
+
+async def test_wrong_issuer_rejected(private_pem: bytes, public_pem: bytes) -> None:
+    settings = JwtSettings(issuer="https://test.qx", audience="qx")
+    validator = JwtValidator(settings)
+    validator._jwk_client = _StubJwkClient(public_pem)
+    token = _make_token(private_pem, iss="https://imposter")
+    result = await validator.validate(token)
+    assert result.is_failure
+    assert result.error.code == "auth.invalid_issuer"
+
+
+async def test_invalid_signature_rejected(private_pem: bytes, public_pem: bytes) -> None:
+    # Generate a *different* keypair and sign with it; validator has the original public key.
+    rogue = rsa.generate_private_key(public_exponent=65537, key_size=2048).private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    settings = JwtSettings(issuer="https://test.qx", audience="qx")
+    validator = JwtValidator(settings)
+    validator._jwk_client = _StubJwkClient(public_pem)
+    token = _make_token(rogue)
+    result = await validator.validate(token)
+    assert result.is_failure
+    assert result.error.code == "auth.invalid_token"
+
+
+async def test_revoked_token_rejected(private_pem: bytes, public_pem: bytes) -> None:
+    async def revoked(_jti: str) -> bool:
+        return True
+
+    settings = JwtSettings(issuer="https://test.qx", audience="qx")
+    validator = JwtValidator(settings, revocation_check=revoked)
+    validator._jwk_client = _StubJwkClient(public_pem)
+    token = _make_token(private_pem, jti=str(uuid4()))
+    result = await validator.validate(token)
+    assert result.is_failure
+    assert result.error.code == "auth.token_revoked"
+
+
+# ---- RBAC ----
+
+
+def test_permission_literal_match() -> None:
+    assert Permission(name="billing.read").matches(frozenset({"billing.read"})) is True
+    assert Permission(name="billing.read").matches(frozenset({"billing.write"})) is False
+
+
+def test_permission_wildcard_match() -> None:
+    granted = frozenset({"billing.*"})
+    assert Permission(name="billing.read").matches(granted) is True
+    assert Permission(name="billing.invoice.refund").matches(granted) is True
+    assert Permission(name="organization.read").matches(granted) is False
+
+
+def test_permission_global_wildcard() -> None:
+    assert Permission(name="anything").matches(frozenset({"*"})) is True
+
+
+# ---- Policy evaluator ----
+
+
+def _principal(*permissions: str) -> Principal:
+    return Principal(
+        subject=uuid4(),
+        issuer="test",
+        permissions=frozenset(permissions),
+    )
+
+
+async def test_require_permission_allows_when_present() -> None:
+    e = PolicyEvaluator(require_permission("billing.read"))
+    r = await e.evaluate(_principal("billing.read"))
+    assert r.is_success
+
+
+async def test_require_permission_denies_when_absent() -> None:
+    e = PolicyEvaluator(require_permission("billing.read"))
+    r = await e.evaluate(_principal("organization.read"))
+    assert r.is_failure
+    assert r.error.code == "authz.denied"
+
+
+async def test_require_any_permission() -> None:
+    e = PolicyEvaluator(require_any_permission("billing.read", "billing.read.limited"))
+    r = await e.evaluate(_principal("billing.read.limited"))
+    assert r.is_success
+
+
+async def test_require_all_permissions() -> None:
+    e = PolicyEvaluator(require_all_permissions("billing.read", "billing.export"))
+    r = await e.evaluate(_principal("billing.read"))
+    assert r.is_failure
+    assert "billing.export" in (r.error.message or "")
+
+
+async def test_custom_policy() -> None:
+    async def owner_only(p: Principal, resource: Any) -> PolicyResult:
+        if resource.get("owner_id") == str(p.subject):
+            return PolicyResult(Decision.ALLOW)
+        return PolicyResult(Decision.DENY, reason="not owner")
+
+    e = PolicyEvaluator(Policy(name="owner_only", rule=owner_only))
+    user = _principal()
+    assert (await e.evaluate(user, {"owner_id": str(user.subject)})).is_success
+    assert (await e.evaluate(user, {"owner_id": str(uuid4())})).is_failure