pywire-auth 0.1.1__py3-none-any.whl

pywire_auth/__init__.py

@@ -0,0 +1,58 @@
+"""pywire-auth — OAuth2 / OIDC providers and identity store adapters.
+
+Public API:
+
+- :func:`connect_auth` — single integration entry point
+- :class:`AuthActions` — one-call claim/session mutations (`app.state.auth`)
+- :class:`AuthMiddleware` — ASGI middleware that populates scope['user']
+- :class:`LocalIdP` + :class:`TokenIssuer` — database-backed local provider
+- OIDC providers: :class:`GoogleProvider`, :class:`GitHubProvider`,
+  :class:`MicrosoftProvider`, :class:`FacebookProvider`,
+  :class:`Auth0Provider`, :class:`GenericOIDCProvider`
+- Store adapters: :class:`MemoryAuthStore`, :class:`SQLAlchemyAuthStore`
+  (requires ``pip install pywire-auth[sqlalchemy]``)
+- Structural interfaces: :class:`AuthStore`, :class:`OIDCProvider`,
+  :class:`BaseOAuth2Provider`, :class:`BaseOIDCProvider`
+"""
+
+from pywire_auth._protocols import AuthStore, OIDCProvider
+from pywire_auth.actions import AuthActions
+from pywire_auth.integration import connect_auth
+from pywire_auth.middleware import AuthMiddleware
+from pywire_auth.local import LocalIdP, TokenIssuer
+from pywire_auth.providers import (
+    Auth0Provider,
+    BaseOAuth2Provider,
+    BaseOIDCProvider,
+    FacebookProvider,
+    GenericOIDCProvider,
+    GitHubProvider,
+    GoogleProvider,
+    MicrosoftProvider,
+)
+from pywire_auth.stores import MemoryAuthStore
+
+try:
+    from pywire_auth.stores.sqlalchemy import SQLAlchemyAuthStore
+except ImportError:
+    SQLAlchemyAuthStore = None  # type: ignore[assignment,misc]
+
+__all__ = [
+    "Auth0Provider",
+    "AuthActions",
+    "AuthMiddleware",
+    "AuthStore",
+    "BaseOAuth2Provider",
+    "BaseOIDCProvider",
+    "FacebookProvider",
+    "GenericOIDCProvider",
+    "GitHubProvider",
+    "GoogleProvider",
+    "LocalIdP",
+    "MemoryAuthStore",
+    "MicrosoftProvider",
+    "SQLAlchemyAuthStore",
+    "OIDCProvider",
+    "TokenIssuer",
+    "connect_auth",
+]

pywire_auth/_protocols.py

@@ -0,0 +1,67 @@
+"""Structural interfaces for auth providers and stores."""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+    Protocol,
+    Tuple,
+    runtime_checkable,
+)
+
+from pywire.auth import Claim, ClaimsPrincipal
+
+
+@runtime_checkable
+class AuthStore(Protocol):
+    """Persistent user + identity store.
+
+    Used by the local IdP and by account-linking flows. Apps using only
+    external OIDC providers don't need a store.
+    """
+
+    async def get_user(self, user_id: str) -> Optional[Dict[str, Any]]: ...
+
+    async def find_by_provider(
+        self, provider: str, subject: str
+    ) -> Optional[Dict[str, Any]]: ...
+
+    async def create_user(self, **fields: Any) -> str: ...
+
+    async def update_user(self, user_id: str, **fields: Any) -> None: ...
+
+    async def link_provider(
+        self,
+        user_id: str,
+        provider: str,
+        subject: str,
+        claims: Optional[Dict[str, Any]] = None,
+    ) -> None: ...
+
+    async def get_password_hash(self, user_id: str) -> Optional[str]: ...
+
+    async def set_password_hash(self, user_id: str, hash: str) -> None: ...
+
+
+class OIDCProvider(Protocol):
+    """Structural shape for OAuth2/OIDC login providers."""
+
+    name: str
+    scopes: List[str]
+
+    async def authorize_url(
+        self, *, redirect_uri: str, state: str, nonce: str
+    ) -> str: ...
+
+    async def exchange_code(
+        self, *, code: str, redirect_uri: str, state: str, nonce: str
+    ) -> Tuple[ClaimsPrincipal, Dict[str, Any]]: ...
+
+    async def refresh(
+        self, refresh_token: str
+    ) -> Optional[Tuple[ClaimsPrincipal, Dict[str, Any]]]: ...
+
+    def map_claims(self, raw: Dict[str, Any]) -> List[Claim]: ...

pywire_auth/actions.py

@@ -0,0 +1,163 @@
+"""AuthActions — one-call claim/session mutations for live auth.
+
+Writing a new claim to a logged-in user touches three storage layers:
+
+1. The ``AuthStore`` — permanent user row; survives logout/login.
+2. The session store — per-login principal snapshot; survives reload.
+3. The ``AuthChannel`` — in-memory fan-out; updates every live tab now.
+
+App code shouldn't have to know about any of that. ``AuthActions`` bundles
+all three behind a small surface. ``connect_auth`` constructs one per app
+and stashes it on ``app.state.auth``; pages use it like::
+
+    await app.state.auth.grant(self.user, self.request, "role", "admin")
+    await app.state.auth.revoke_claim(self.user, self.request, "role")
+    await app.state.auth.revoke_session(self.user, self.request)
+
+Every method runs all three writes in the right order so a hard reload,
+a fresh login, and every concurrent tab stay consistent.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any, Dict, Iterable, List, Optional
+
+from pywire.auth import (
+    Claim,
+    ClaimsPrincipal,
+    clear_principal_from_session,
+    write_principal_to_session,
+)
+
+
+def _bare_user_id(principal: ClaimsPrincipal) -> str:
+    """Strip the ``<provider>:`` prefix — auth stores key on the bare id."""
+    if not principal.user_id:
+        return ""
+    return principal.user_id.split(":", 1)[-1]
+
+
+def _claims_to_dict(claims: Iterable[Claim]) -> Dict[str, str]:
+    """Collapse the claim list to a dict for ``AuthStore.update_user``.
+
+    Strips ``sub`` / ``email`` because LocalIdP re-emits them from the
+    user row's top-level columns on every :meth:`principal_for_user`.
+    Including them in ``record['claims']`` would just cause duplicates.
+    """
+    return {c.type: c.value for c in claims if c.type not in ("sub", "email")}
+
+
+class AuthActions:
+    """Bundles AuthStore + session + channel writes for claim/session ops."""
+
+    def __init__(self, app: Any) -> None:
+        self._app = app
+
+    # --- claim mutations ---
+
+    async def update_claims(
+        self,
+        principal: ClaimsPrincipal,
+        request: Any,
+        claims: List[Claim],
+    ) -> ClaimsPrincipal:
+        """Replace the principal's claims. Writes through all three layers."""
+        new_principal = replace(
+            principal,
+            is_authenticated=True,
+            claims=list(claims),
+        )
+
+        store = self._auth_store()
+        if store is not None:
+            raw_uid = _bare_user_id(principal)
+            if raw_uid:
+                await store.update_user(raw_uid, claims=_claims_to_dict(claims))
+
+        await self._write_session(request, new_principal)
+
+        channel = getattr(self._app, "_auth_channel", None)
+        if channel is not None and principal.user_id:
+            await channel.update_principal(principal.user_id, principal=new_principal)
+
+        return new_principal
+
+    async def grant(
+        self,
+        principal: ClaimsPrincipal,
+        request: Any,
+        claim_type: str,
+        claim_value: str,
+    ) -> ClaimsPrincipal:
+        """Add or overwrite a claim, keeping the rest untouched."""
+        remaining = [c for c in principal.claims if c.type != claim_type]
+        return await self.update_claims(
+            principal,
+            request,
+            remaining + [Claim(type=claim_type, value=claim_value)],
+        )
+
+    async def revoke_claim(
+        self,
+        principal: ClaimsPrincipal,
+        request: Any,
+        claim_type: str,
+    ) -> ClaimsPrincipal:
+        """Drop every claim of the given type. No-op if none exist."""
+        filtered = [c for c in principal.claims if c.type != claim_type]
+        return await self.update_claims(principal, request, filtered)
+
+    # --- session lifecycle ---
+
+    async def revoke_session(
+        self,
+        principal: ClaimsPrincipal,
+        request: Any,
+    ) -> None:
+        """Clear this session's auth + fire a channel-wide revoke.
+
+        The WS live-auth loop translates the channel event into a
+        navigate-away for each connected tab; the current tab's session
+        is also cleared so a hard reload lands on the login page via
+        the ``!auth`` guard.
+        """
+        session_store = getattr(self._app, "session_store", None)
+        sid = self._session_id(request)
+        if session_store is not None and sid:
+            data = await session_store.get(sid) or {}
+            clear_principal_from_session(data)
+            data.pop("_refresh_token", None)
+            await session_store.set(
+                sid, data, ttl=getattr(self._app, "session_ttl", 1800)
+            )
+
+        channel = getattr(self._app, "_auth_channel", None)
+        if channel is not None and principal.user_id:
+            await channel.revoke(principal.user_id)
+
+    # --- helpers ---
+
+    def _auth_store(self) -> Any:
+        state = getattr(getattr(self._app, "app", None), "state", None)
+        return getattr(state, "auth_store", None) if state is not None else None
+
+    async def _write_session(
+        self, request: Any, principal: ClaimsPrincipal
+    ) -> None:
+        session_store = getattr(self._app, "session_store", None)
+        sid = self._session_id(request)
+        if session_store is None or not sid:
+            return
+        data = await session_store.get(sid) or {}
+        write_principal_to_session(data, principal)
+        await session_store.set(
+            sid, data, ttl=getattr(self._app, "session_ttl", 1800)
+        )
+
+    @staticmethod
+    def _session_id(request: Any) -> Optional[str]:
+        scope = getattr(request, "scope", None)
+        if scope is None:
+            return None
+        return scope.get("pywire_session_id")

pywire_auth/integration.py

@@ -0,0 +1,132 @@
+"""Single integration entry point — ``connect_auth(app, ...)``.
+
+Mounts login/callback/logout routes (plus LocalIdP routes when
+``local_idp=`` is passed), auto-installs :class:`SessionMiddleware`
+when missing, installs ``AuthMiddleware``, and wires ``PolicyEngine``
++ ``AuthChannel`` onto the app. Apps that only use external OIDC
+providers need nothing more.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Iterable, Optional
+
+from pywire.auth import (
+    ClaimsPrincipal,
+    MemoryAuthChannel,
+    PolicyEngine,
+)
+from starlette.requests import Request
+
+from pywire_auth.actions import AuthActions
+from pywire_auth.middleware import AuthMiddleware
+from pywire_auth.routes import _RouteContext, build_routes
+
+
+def connect_auth(
+    app: Any,
+    *,
+    providers: Iterable[Any] = (),
+    local_idp: Optional[Any] = None,
+    policy_engine: Optional[PolicyEngine] = None,
+    auth_channel: Optional[Any] = None,
+    prefix: str = "/auth",
+    default_next: str = "/",
+    session_ttl: Optional[int] = None,
+    secret_key: Optional[str] = None,
+    on_login: Optional[Callable[[ClaimsPrincipal, Request], Awaitable[None]]] = None,
+    on_logout: Optional[Callable[[ClaimsPrincipal, Request], Awaitable[None]]] = None,
+) -> Any:
+    """Attach auth routes + middleware to a PyWire app.
+
+    Returns the ``PolicyEngine`` so policies can be registered directly:
+
+        engine = connect_auth(app, providers=[GoogleProvider(...)])
+        engine.add_policy("AdminOnly", requires_claim=("role", "admin"))
+
+    Pass ``local_idp=LocalIdP(...)`` to mount default password/JWT
+    endpoints at ``{prefix}/local/{register,login,token,verify-token,revoke}``.
+    """
+    engine = policy_engine or PolicyEngine()
+    channel = auth_channel or MemoryAuthChannel()
+
+    providers_by_name = {p.name: p for p in providers}
+
+    ctx = _RouteContext(
+        providers=providers_by_name,
+        session_store=app.session_store,
+        session_ttl=session_ttl or getattr(app, "session_ttl", 1800),
+        auth_channel=channel,
+        default_next=default_next,
+        on_login=on_login,
+        on_logout=on_logout,
+    )
+
+    for route in build_routes(ctx, prefix, local_idp=local_idp):
+        app.app.router.routes.insert(0, route)
+
+    effective_secret = (
+        secret_key or getattr(app, "_session_secret", None) or _resolve_secret(app)
+    )
+    if not effective_secret:
+        raise RuntimeError(
+            "connect_auth requires secret_key (or PYWIRE_SESSION_SECRET "
+            "set on the app) for session cookie verification"
+        )
+
+    # Auto-install SessionMiddleware when missing — interactive-mode PyWire
+    # apps skip it by default (WS owns state), but connect_auth's routes
+    # and AuthMiddleware both need scope["pywire_session_id"] to exist on
+    # HTTP requests.
+    _ensure_session_middleware(app, effective_secret)
+
+    app.add_middleware(
+        AuthMiddleware,
+        session_store=app.session_store,
+        secret_key=effective_secret,
+        policy_engine=engine,
+        auth_channel=channel,
+    )
+
+    app._auth_engine = engine
+    app._auth_channel = channel
+    app._auth_providers = providers_by_name
+    app._auth_local_idp = local_idp
+
+    # Also expose on the Starlette app's state so pages can access shared
+    # auth state via `app.state.X` without importing main/state.
+    _app_state = app.app.state
+    _app_state.auth_engine = engine
+    _app_state.auth_channel = channel
+    _app_state.auth_providers = list(providers_by_name.keys())
+    _app_state.local_idp = local_idp
+    if local_idp is not None:
+        _app_state.auth_store = local_idp.store
+    # Single entry point for claim/session mutations — bundles
+    # auth_store + session + channel writes so app code never reaches
+    # into all three directly. See pywire_auth.actions.AuthActions.
+    _app_state.auth = AuthActions(app)
+
+    return engine
+
+
+def _ensure_session_middleware(app: Any, secret: str) -> None:
+    """Install ``SessionMiddleware`` if it isn't already on the stack."""
+    from pywire.runtime.session_middleware import SessionMiddleware
+
+    installed = getattr(app.app, "user_middleware", []) or []
+    if any(getattr(mw, "cls", None) is SessionMiddleware for mw in installed):
+        return
+
+    app.add_middleware(
+        SessionMiddleware,
+        session_store=app.session_store,
+        session_ttl=getattr(app, "session_ttl", 1800),
+        secret_key=secret,
+    )
+
+
+def _resolve_secret(app: Any) -> Optional[str]:
+    from pywire.config import env
+
+    return env("PYWIRE_SESSION_SECRET")

pywire_auth/local/__init__.py

@@ -0,0 +1,20 @@
+"""Local identity provider — DB-backed, OIDC-native.
+
+Issues its own signed id_tokens so downstream code treats a
+password-authenticated user identically to an external OIDC login.
+Users handle registration and login UI themselves; this module only
+exposes backend APIs.
+
+Usage:
+
+    from pywire_auth import LocalIdP, MemoryAuthStore
+    idp = LocalIdP(store=MemoryAuthStore(), secret="<long random>")
+    user_id = await idp.create_user(email="a@b.c", password="hunter2")
+    principal = await idp.verify_credentials(email="a@b.c", password="hunter2")
+"""
+
+from pywire_auth.local.idp import LocalIdP
+from pywire_auth.local.routes import build_local_routes
+from pywire_auth.local.token import TokenIssuer
+
+__all__ = ["LocalIdP", "TokenIssuer", "build_local_routes"]

pywire_auth/local/idp.py

@@ -0,0 +1,201 @@
+"""LocalIdP — DB-backed identity provider with Argon2 password hashing."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerifyMismatchError
+
+from pywire.auth import Claim, ClaimsPrincipal
+from pywire.config import env as _env
+
+from pywire_auth._protocols import AuthStore
+from pywire_auth.local.token import TokenIssuer
+from pywire_auth.stores.memory import MemoryAuthStore
+
+logger = logging.getLogger(__name__)
+
+
+def _default_store() -> AuthStore:
+    return MemoryAuthStore()
+
+
+@dataclass
+class LocalIdP:
+    """DB-backed identity provider with OIDC-native token issuance.
+
+    - Registration: :meth:`create_user`
+    - Login (password): :meth:`verify_credentials` → ``ClaimsPrincipal``
+    - Machine tokens: :meth:`issue_id_token` → signed JWT
+
+    Defaults tuned for the zero-boilerplate path:
+
+    - ``store`` defaults to an in-memory :class:`MemoryAuthStore` — good
+      for dev, replace with a SQLAlchemy-backed store for production.
+    - ``secret`` falls back to the ``LOCAL_IDP_SECRET`` env var when
+      empty. If neither is provided, construction raises so the error
+      surfaces at boot rather than at first token-issue.
+
+    The ``audience`` defaults to the issuer for single-app deployments;
+    override per :meth:`issue_id_token` for multi-audience setups.
+    """
+
+    store: AuthStore = field(default_factory=_default_store)
+    # Supply one of: secret (HS256), OR configure a TokenIssuer explicitly.
+    # When empty, reads LOCAL_IDP_SECRET from the environment.
+    secret: str = ""
+    issuer: str = "pywire-auth-local"
+    audience: str = ""
+    token_issuer: Optional[TokenIssuer] = None
+    _hasher: PasswordHasher = field(default_factory=PasswordHasher, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.token_issuer is None:
+            secret = self.secret or _env("LOCAL_IDP_SECRET") or ""
+            if not secret:
+                raise ValueError(
+                    "LocalIdP requires a signing secret. Pass secret=... "
+                    "(HS256), set the LOCAL_IDP_SECRET env var, or supply "
+                    "an explicit token_issuer=TokenIssuer(...)."
+                )
+            self.secret = secret
+            self.token_issuer = TokenIssuer(
+                issuer=self.issuer, algorithm="HS256", secret=secret
+            )
+        else:
+            # Ensure the issuer string matches any external token_issuer.
+            self.issuer = self.token_issuer.issuer
+        if not self.audience:
+            self.audience = self.issuer
+
+    # --- Registration + credential flows ---
+
+    async def create_user(
+        self,
+        *,
+        email: str,
+        password: str,
+        claims: Optional[Dict[str, Any]] = None,
+        name: str = "",
+        **extra: Any,
+    ) -> str:
+        existing = await self.store.find_by_provider("local", email)
+        if existing is not None:
+            raise ValueError(f"User with email {email!r} already exists")
+
+        user_id = await self.store.create_user(
+            email=email, name=name, claims=claims or {}, **extra
+        )
+        pw_hash = self._hasher.hash(password)
+        await self.store.set_password_hash(user_id, pw_hash)
+        await self.store.link_provider(
+            user_id, "local", email, claims=claims or {"email": email}
+        )
+        return user_id
+
+    async def verify_credentials(
+        self, *, email: str, password: str
+    ) -> Optional[ClaimsPrincipal]:
+        record = await self.store.find_by_provider("local", email)
+        if record is None:
+            return None
+        user_id = record.get("user_id")
+        if not user_id:
+            return None
+
+        pw_hash = await self.store.get_password_hash(user_id)
+        if not pw_hash:
+            return None
+
+        try:
+            self._hasher.verify(pw_hash, password)
+        except VerifyMismatchError:
+            return None
+        except Exception:
+            logger.warning("Unexpected argon2 verify error", exc_info=True)
+            return None
+
+        if self._hasher.check_needs_rehash(pw_hash):
+            new_hash = self._hasher.hash(password)
+            await self.store.set_password_hash(user_id, new_hash)
+
+        return await self.principal_for_user(user_id)
+
+    async def change_password(
+        self, *, user_id: str, old_password: str, new_password: str
+    ) -> bool:
+        pw_hash = await self.store.get_password_hash(user_id)
+        if not pw_hash:
+            return False
+        try:
+            self._hasher.verify(pw_hash, old_password)
+        except VerifyMismatchError:
+            return False
+        await self.store.set_password_hash(user_id, self._hasher.hash(new_password))
+        return True
+
+    async def reset_password(self, *, user_id: str, new_password: str) -> None:
+        """Admin-side password reset (skips old-password check)."""
+        await self.store.set_password_hash(user_id, self._hasher.hash(new_password))
+
+    # --- Principal + token flows ---
+
+    async def principal_for_user(self, user_id: str) -> Optional[ClaimsPrincipal]:
+        record = await self.store.get_user(user_id)
+        if record is None:
+            return None
+        return _principal_from_record(record, provider_prefix="local")
+
+    def issue_id_token(
+        self,
+        *,
+        user_id: str,
+        claims: Optional[Dict[str, Any]] = None,
+        ttl: Optional[int] = None,
+        audience: Optional[str] = None,
+    ) -> str:
+        assert self.token_issuer is not None
+        return self.token_issuer.issue(
+            subject=user_id,
+            audience=audience or self.audience,
+            claims=claims,
+            ttl=ttl,
+        )
+
+    def verify_id_token(
+        self, token: str, *, audience: Optional[str] = None
+    ) -> Optional[Dict[str, Any]]:
+        assert self.token_issuer is not None
+        return self.token_issuer.verify(token, audience=audience or self.audience)
+
+    async def principal_from_id_token(self, token: str) -> Optional[ClaimsPrincipal]:
+        payload = self.verify_id_token(token)
+        if payload is None:
+            return None
+        user_id = str(payload.get("sub") or "")
+        if not user_id:
+            return None
+        return await self.principal_for_user(user_id)
+
+
+def _principal_from_record(
+    record: Dict[str, Any], *, provider_prefix: str = "local"
+) -> ClaimsPrincipal:
+    user_id = str(record.get("user_id", ""))
+    email = record.get("email")
+    name = str(record.get("name") or email or "")
+    claims: List[Claim] = [Claim(type="sub", value=user_id)]
+    if email:
+        claims.append(Claim(type="email", value=str(email)))
+    for ctype, cvalue in (record.get("claims") or {}).items():
+        claims.append(Claim(type=str(ctype), value=str(cvalue)))
+    return ClaimsPrincipal(
+        is_authenticated=True,
+        name=name,
+        user_id=f"{provider_prefix}:{user_id}" if user_id else "",
+        claims=claims,
+        raw=dict(record),
+    )