aso 0.2.0__py3-none-any.whl

aso/__init__.py

@@ -0,0 +1,3 @@
+"""Aso: a Laravel-style web framework for Python (FastAPI + Inertia.js)."""
+
+__version__ = "0.1.0.dev0"

aso/auth/__init__.py

@@ -0,0 +1,33 @@
+"""Authentication and authorization (T-38, T-39, T-40).
+
+```python
+from aso.auth import auth, Gate, Authenticatable, MustVerifyEmail
+from aso.auth.events import Registered, Login, Logout, Failed, Lockout
+
+class User(MustVerifyEmail, Authenticatable, Model):
+    ...
+
+if await auth().attempt({"email": email, "password": password}):
+    ...
+```
+"""
+
+from __future__ import annotations
+
+from aso.auth.authenticatable import Authenticatable, MustVerifyEmail
+from aso.auth.features import features
+from aso.auth.gate import Gate
+from aso.auth.guard import auth
+from aso.auth.password_broker import password_broker
+from aso.exceptions.types import AuthenticationException, AuthorizationException
+
+__all__ = [
+    "Authenticatable",
+    "AuthenticationException",
+    "AuthorizationException",
+    "Gate",
+    "MustVerifyEmail",
+    "auth",
+    "features",
+    "password_broker",
+]

aso/auth/authenticatable.py

@@ -0,0 +1,49 @@
+"""`Authenticatable` and `MustVerifyEmail` mixins (T-38, T-39).
+
+```python
+class User(MustVerifyEmail, Authenticatable, Model):
+    ...
+```
+
+Mix them in *before* `Model` so their defaults (like `__hidden__`) lose to anything the model
+itself declares, matching normal Python MRO.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+__all__ = ["Authenticatable", "MustVerifyEmail"]
+
+
+class Authenticatable:
+    """Adds `can()`/`cannot()` (T-39) and hides `password`/`remember_token` by default."""
+
+    __hidden__: tuple[str, ...] = ("password", "remember_token")
+
+    async def can(self, ability: str, *args: Any) -> bool:
+        from aso.auth.gate import Gate
+
+        return await Gate.for_user(self).allows(ability, *args)
+
+    async def cannot(self, ability: str, *args: Any) -> bool:
+        return not await self.can(ability, *args)
+
+
+class MustVerifyEmail:
+    """Turns on email verification for a user model (T-38)."""
+
+    def has_verified_email(self) -> bool:
+        return getattr(self, "email_verified_at", None) is not None
+
+    async def mark_email_as_verified(self) -> bool:
+        self.email_verified_at = datetime.now(UTC)
+        await self.save()  # type: ignore[attr-defined]
+        return True
+
+    async def send_email_verification_notification(self) -> None:
+        from aso.auth.mail import VerifyEmailMail
+        from aso.mail import Mail
+
+        await Mail.to(self.email).send(VerifyEmailMail(self))  # type: ignore[attr-defined]

aso/auth/events.py

@@ -0,0 +1,68 @@
+"""Authentication events (T-38, T-46): `from aso.auth.events import ...`.
+
+These carry the `User` model, so **their listeners cannot be queued** (`aso.events.Event.
+dispatch()` raises `JobNotSerializable` before running anything if any listener sets
+`queued = True`, T-46). `Failed.credentials` never contains the password; `Lockout` carries the
+email and IP instead of the whole request.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aso.events import Event
+
+__all__ = ["Failed", "Lockout", "Login", "Logout", "PasswordReset", "Registered", "Verified"]
+
+
+class Registered(Event):
+    """A user registered (T-38). Carries `user`."""
+
+    def __init__(self, user: Any) -> None:
+        self.user = user
+
+
+class Verified(Event):
+    """A user's email address was verified (T-38). Carries `user`."""
+
+    def __init__(self, user: Any) -> None:
+        self.user = user
+
+
+class PasswordReset(Event):
+    """A user reset their password through the password broker (T-38). Carries `user`."""
+
+    def __init__(self, user: Any) -> None:
+        self.user = user
+
+
+class Login(Event):
+    """A user logged in (T-38). Carries `user` and whether it was a "remember me" login."""
+
+    def __init__(self, user: Any, remember: bool = False) -> None:
+        self.user = user
+        self.remember = remember
+
+
+class Logout(Event):
+    """A user logged out (T-38). Carries `user`."""
+
+    def __init__(self, user: Any) -> None:
+        self.user = user
+
+
+class Failed(Event):
+    """`auth().attempt()`/`.validate()` rejected credentials (T-38). `user` is `None` when no
+    matching account was found. `credentials` never includes the password."""
+
+    def __init__(self, user: Any, credentials: dict[str, Any]) -> None:
+        self.user = user
+        self.credentials = {k: v for k, v in credentials.items() if k != "password"}
+
+
+class Lockout(Event):
+    """The login rate limit was hit (T-38). Carries `email` and `ip` (not the whole request)."""
+
+    def __init__(self, email: str, ip: str | None) -> None:
+        self.email = email
+        self.ip = ip

aso/auth/features.py

@@ -0,0 +1,15 @@
+"""`features.enabled(name)` (T-38): toggle built-in auth flows via `config("auth.features")`."""
+
+from __future__ import annotations
+
+__all__ = ["features"]
+
+
+class _Features:
+    def enabled(self, name: str) -> bool:
+        from aso.config import config
+
+        return name in (config("auth.features") or [])
+
+
+features = _Features()

aso/auth/gate.py

@@ -0,0 +1,187 @@
+"""`Gate` (T-39, D-030): `define`/`allows`/`denies`/`policy`/`authorize`, policy `before()`.
+
+Policies are plain classes (no base class) found by convention: `app.models.post.Post` ->
+`app.policies.post_policy.PostPolicy`. An explicit `Gate.policy(Post, PostPolicy)` mapping wins
+over the convention. Guests are denied without calling the policy (or gate) unless the ability
+method's `user` parameter is annotated `User | None` (Laravel's rule).
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import re
+import types
+import typing
+from collections.abc import Callable
+from typing import Any, ClassVar
+
+from aso.exceptions.types import AuthorizationException
+
+__all__ = ["AuthorizationException", "Gate"]
+
+
+def _snake(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).lower()
+
+
+def _policy_module_for(model_cls: type) -> str:
+    """`app.models.post` -> `app.policies.post_policy` (D-030's convention)."""
+    module = model_cls.__module__
+    if ".models." in module:
+        module = module.replace(".models.", ".policies.", 1)
+    elif module.startswith("models."):
+        module = "policies." + module[len("models.") :]
+    head, _, leaf = module.rpartition(".")
+    leaf = f"{leaf}_policy" if leaf else f"{_snake(model_cls.__name__)}_policy"
+    return f"{head}.{leaf}" if head else leaf
+
+
+def _allows_none(annotation: Any) -> bool:
+    if annotation is inspect.Parameter.empty:
+        return False
+    if annotation is type(None):
+        return True
+    origin = typing.get_origin(annotation)
+    if origin is typing.Union or isinstance(annotation, types.UnionType):
+        return type(None) in typing.get_args(annotation)
+    return False
+
+
+def _accepts_guest(callback: Callable[..., Any]) -> bool:
+    """Whether `callback`'s first (non-`self`) parameter is annotated to allow `None`.
+
+    Resolves only *that* parameter's annotation (not `typing.get_type_hints(callback)` on the
+    whole signature): a later parameter referencing a name the callback's module hasn't imported
+    (or, in tests, a class defined locally) must not make this conservative by accident.
+    """
+    try:
+        sig = inspect.signature(callback)
+    except (TypeError, ValueError):
+        return False
+    params = [p for p in sig.parameters.values() if p.name != "self"]
+    if not params:
+        return False
+    annotation = params[0].annotation
+    if isinstance(annotation, str):
+        try:
+            annotation = eval(annotation, getattr(callback, "__globals__", {}), None)  # noqa: S307
+        except Exception:
+            return False
+    return _allows_none(annotation)
+
+
+async def _call(callback: Callable[..., Any], *args: Any) -> Any:
+    result = callback(*args)
+    if inspect.isawaitable(result):
+        result = await result
+    return result
+
+
+class _UserGate:
+    """`Gate.for_user(user)`: check abilities for a specific user (`Authenticatable.can()`)."""
+
+    def __init__(self, user: Any) -> None:
+        self._user = user
+
+    async def allows(self, ability: str, *args: Any) -> bool:
+        return await Gate._check(self._user, ability, args)
+
+    async def denies(self, ability: str, *args: Any) -> bool:
+        return not await self.allows(ability, *args)
+
+
+class Gate:
+    """`Gate.define/allows/denies/policy/authorize` (T-39). Classmethods, like Laravel's facade."""
+
+    _gates: ClassVar[dict[str, Callable[..., Any]]] = {}
+    _policies: ClassVar[dict[type, type]] = {}
+    _policy_cache: ClassVar[dict[type, type | None]] = {}
+
+    @classmethod
+    def define(cls, ability: str, callback: Callable[..., Any]) -> None:
+        cls._gates[ability] = callback
+
+    @classmethod
+    def policy(cls, model_cls: type, policy_cls: type) -> None:
+        cls._policies[model_cls] = policy_cls
+        cls._policy_cache.pop(model_cls, None)
+
+    @classmethod
+    def for_user(cls, user: Any) -> _UserGate:
+        return _UserGate(user)
+
+    @classmethod
+    async def allows(cls, ability: str, *args: Any) -> bool:
+        from aso.auth.guard import auth
+
+        return await cls._check(auth().user(), ability, args)
+
+    @classmethod
+    async def denies(cls, ability: str, *args: Any) -> bool:
+        return not await cls.allows(ability, *args)
+
+    @classmethod
+    async def authorize(cls, ability: str, *args: Any) -> None:
+        if not await cls.allows(ability, *args):
+            raise AuthorizationException()
+
+    # ------------------------------------------------------------ resolution
+
+    @classmethod
+    def _resolve_policy(cls, model_cls: type) -> type | None:
+        explicit = cls._policies.get(model_cls)
+        if explicit is not None:
+            return explicit
+        if model_cls in cls._policy_cache:
+            return cls._policy_cache[model_cls]
+        policy_cls: type | None = None
+        try:
+            module = importlib.import_module(_policy_module_for(model_cls))
+            policy_cls = getattr(module, f"{model_cls.__name__}Policy", None)
+        except ImportError:
+            policy_cls = None
+        cls._policy_cache[model_cls] = policy_cls
+        return policy_cls
+
+    @classmethod
+    async def _check(cls, user: Any, ability: str, args: tuple[Any, ...]) -> bool:
+        if ability in cls._gates:
+            callback = cls._gates[ability]
+            if user is None and not _accepts_guest(callback):
+                return False
+            return bool(await _call(callback, user, *args))
+
+        subject = args[0] if args else None
+        model_cls = subject if isinstance(subject, type) else (type(subject) if subject is not None else None)
+        if model_cls is None:
+            return False
+        policy_cls = cls._resolve_policy(model_cls)
+        if policy_cls is None:
+            return False
+        method = getattr(policy_cls, ability, None)
+        if method is None or not callable(method):
+            return False
+        if user is None and not _accepts_guest(method):
+            return False
+        policy = policy_cls()
+        before = getattr(policy, "before", None)
+        if before is not None:
+            result = await _call(before, user, ability)
+            if result is True:
+                return True
+            if result is False:
+                return False
+        bound = getattr(policy, ability)
+        # `authorize("create", Post)` (a bare class, no instance yet): nothing to pass besides
+        # `user` -- Laravel's `create(User $user)` takes no second parameter either. An instance
+        # (or several arguments) is forwarded as given: `authorize("update", post)` ->
+        # `update(user, post)`.
+        call_args = () if len(args) == 1 and isinstance(args[0], type) else args
+        return bool(await _call(bound, user, *call_args))
+
+    @classmethod
+    def _reset_for_tests(cls) -> None:
+        cls._gates = {}
+        cls._policies = {}
+        cls._policy_cache = {}

aso/auth/guard.py

@@ -0,0 +1,247 @@
+"""`auth()`: the session guard (T-38).
+
+`user()`/`id()`/`check()`/`guest()`/`via_remember()` are synchronous: the user is loaded once per
+web request by `AuthenticateSession` (`middleware.py`) and cached on `context.current().user`.
+Everything that may touch the database or hash a password is `async`.
+
+`login()`/`logout()` do **not** call `session().regenerate()`/`.invalidate()` themselves (T-38:
+"Always call `session().regenerate()` after `login()` and `session().invalidate()` after
+`logout()`. The kit's controllers do this."); the one exception is a "remember me" cookie login,
+which `AuthenticateSession` regenerates itself since there is no controller in that path.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import secrets
+from typing import Any
+
+from aso import context
+from aso.exceptions.types import AuthenticationException, AuthorizationException
+
+__all__ = ["AuthenticationException", "AuthorizationException", "auth"]
+
+
+def guard_name() -> str:
+    from aso.config import config
+
+    return config("auth.defaults.guard", "web")
+
+
+def session_key() -> str:
+    return f"login_{guard_name()}"
+
+
+def password_hash_key() -> str:
+    return f"password_hash_{guard_name()}"
+
+
+def remember_cookie_name() -> str:
+    return f"remember_{guard_name()}"
+
+
+def _import_path(path: str) -> Any:
+    import importlib
+
+    module_path, _, attr = path.rpartition(".")
+    module = importlib.import_module(module_path)
+    return getattr(module, attr)
+
+
+def _user_model() -> type:
+    """The user model class, resolved from the guard's provider (`config/auth.py`, T-38)."""
+    from aso.config import config
+
+    guard = guard_name()
+    provider = config(f"auth.guards.{guard}.provider", "users")
+    path = config(f"auth.providers.{provider}.model", "app.models.user.User")
+    return _import_path(path)
+
+
+def _is_https() -> bool:
+    from aso.config import config
+
+    return str(config("app.url") or "").startswith("https://")
+
+
+def _build_set_cookie(name: str, value: str, *, max_age: int) -> str:
+    from starlette.responses import Response as StarletteResponse
+
+    resp = StarletteResponse()
+    resp.set_cookie(key=name, value=value, max_age=max_age, path="/", httponly=True, samesite="lax", secure=_is_https())
+    for key, raw in resp.raw_headers:
+        if key == b"set-cookie":
+            return raw.decode("latin-1")
+    raise RuntimeError("Could not build a Set-Cookie header.")  # pragma: no cover - defensive
+
+
+def _build_delete_cookie(name: str) -> str:
+    from starlette.responses import Response as StarletteResponse
+
+    resp = StarletteResponse()
+    resp.delete_cookie(key=name, path="/")
+    for key, raw in resp.raw_headers:
+        if key == b"set-cookie":
+            return raw.decode("latin-1")
+    raise RuntimeError("Could not build a Set-Cookie header.")  # pragma: no cover - defensive
+
+
+class _Guard:
+    """What `auth()` returns. One per call -- all state lives in `context.current()`."""
+
+    # ------------------------------------------------------------ sync reads
+
+    def user(self) -> Any:
+        ctx = context.current()
+        if ctx is None or ctx.user is context.UNRESOLVED:
+            return None
+        return ctx.user
+
+    def check(self) -> bool:
+        return self.user() is not None
+
+    def guest(self) -> bool:
+        return self.user() is None
+
+    def id(self) -> Any:
+        return getattr(self.user(), "id", None)
+
+    def via_remember(self) -> bool:
+        ctx = context.current()
+        return bool(ctx is not None and ctx.extras.get("auth.via_remember", False))
+
+    # ------------------------------------------------------------ async
+
+    async def attempt(self, credentials: dict[str, Any], remember: bool = False) -> bool:
+        from aso.auth.events import Failed
+        from aso.security import hash as hash_
+
+        password = str(credentials.get("password", ""))
+        lookup = {k: v for k, v in credentials.items() if k != "password"}
+        model_cls = _user_model()
+        user = await model_cls.where(**lookup).first() if lookup else None
+        stored_hash = getattr(user, "password", None) if user is not None else None
+        # Always run `hash.check` (even with a dummy hash when no user was found) so the
+        # response time does not reveal whether the email exists (T-38 "How it works").
+        valid = await asyncio.to_thread(hash_.check, password, stored_hash or _dummy_hash())
+        if user is None or not valid:
+            await Failed(user, credentials).dispatch()
+            return False
+        if await asyncio.to_thread(hash_.needs_rehash, stored_hash):
+            user.password = password  # the `Hashed` column re-hashes on assignment (T-40, T-31)
+            await user.save()
+        await self.login(user, remember=remember)
+        return True
+
+    async def validate(self, credentials: dict[str, Any]) -> bool:
+        from aso.security import hash as hash_
+
+        password = str(credentials.get("password", ""))
+        lookup = {k: v for k, v in credentials.items() if k != "password"}
+        model_cls = _user_model()
+        user = await model_cls.where(**lookup).first() if lookup else None
+        stored_hash = getattr(user, "password", None) if user is not None else None
+        valid = await asyncio.to_thread(hash_.check, password, stored_hash or _dummy_hash())
+        return user is not None and valid
+
+    async def login(self, user: Any, remember: bool = False) -> None:
+        from aso.auth.events import Login
+        from aso.session import session as get_session
+
+        s = get_session()
+        s.put(session_key(), user.id)
+        s.put(password_hash_key(), user.password)
+        ctx = context.current()
+        if ctx is not None:
+            ctx.user = user
+        if remember:
+            await self._remember(user)
+        await Login(user, remember).dispatch()
+
+    async def login_using_id(self, user_id: Any, remember: bool = False) -> Any:
+        model_cls = _user_model()
+        user = await model_cls.find(user_id)
+        if user is not None:
+            await self.login(user, remember=remember)
+        return user
+
+    async def logout(self) -> None:
+        from aso.auth.events import Logout
+        from aso.session import session as get_session
+
+        user = self.user()
+        try:
+            s = get_session()
+            s.forget(session_key(), password_hash_key())
+        except Exception:
+            pass
+        ctx = context.current()
+        if ctx is not None:
+            ctx.user = None
+            ctx.extras.pop("auth.via_remember", None)
+        if user is not None:
+            # Rotate `remember_token` so "remember me" cookies elsewhere stop working too.
+            user.remember_token = secrets.token_urlsafe(45)
+            await user.save()
+        self._forget_remember_cookie()
+        if user is not None:
+            await Logout(user).dispatch()
+
+    async def logout_other_devices(self, password: str) -> bool:
+        from aso.security import hash as hash_
+
+        user = self.user()
+        if user is None:
+            return False
+        valid = await asyncio.to_thread(hash_.check, password, user.password)
+        if not valid:
+            return False
+        user.password = password  # re-hash with a fresh salt: other sessions' stored hash goes stale
+        await user.save()
+        try:
+            from aso.session import session as get_session
+
+            get_session().put(password_hash_key(), user.password)
+        except Exception:
+            pass
+        return True
+
+    # ------------------------------------------------------------ remember-me cookie
+
+    async def _remember(self, user: Any) -> None:
+        from aso.config import config
+        from aso.security import crypt
+
+        if not getattr(user, "remember_token", None):
+            user.remember_token = secrets.token_urlsafe(45)
+            await user.save()
+        payload = f"{user.id}|{user.remember_token}|{user.password}"
+        token = crypt.encrypt(payload)
+        minutes = int(config("auth.remember_lifetime", 60 * 24 * 400))
+        header = _build_set_cookie(remember_cookie_name(), token, max_age=minutes * 60)
+        ctx = context.current()
+        if ctx is not None:
+            ctx.extras["auth.set_remember_cookie"] = header
+
+    def _forget_remember_cookie(self) -> None:
+        ctx = context.current()
+        if ctx is not None:
+            ctx.extras["auth.forget_remember_cookie"] = True
+
+
+_DUMMY_HASH: str | None = None
+
+
+def _dummy_hash() -> str:
+    """A real (but useless) hash to check against when no user was found, so a failed login by
+    an unknown email takes the same time as one by a known email (T-38 "How it works")."""
+    global _DUMMY_HASH
+    if _DUMMY_HASH is None:
+        from aso.security import hash as hash_
+
+        _DUMMY_HASH = hash_.make(secrets.token_urlsafe(32))
+    return _DUMMY_HASH
+
+
+def auth() -> _Guard:
+    return _Guard()

aso/auth/mail.py

@@ -0,0 +1,61 @@
+"""Built-in mailables the auth library sends itself (T-38): the password-reset link and the
+email-verification link. Plain-text content, so they need no app-provided view template."""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import timedelta
+from typing import Any
+from urllib.parse import quote
+
+from aso.mail import Content, Envelope, Mailable
+
+__all__ = ["ResetPasswordMail", "VerifyEmailMail"]
+
+
+class ResetPasswordMail(Mailable):
+    """Sent by `password_broker().send_reset_link()`. `/reset-password/{token}?email=...`."""
+
+    def __init__(self, email: str, token: str) -> None:
+        self.email = email
+        self.token = token
+
+    def envelope(self) -> Envelope:
+        return Envelope(subject="Reset Password Notification")
+
+    def content(self) -> Content:
+        return Content(text=f"You are receiving this email because we received a password reset "
+                             f"request for your account.\n\nReset your password: {self._url()}\n\n"
+                             f"If you did not request a password reset, no further action is required.")
+
+    def _url(self) -> str:
+        from aso.routing import route, url
+
+        try:
+            path = route("password.reset", {"token": self.token})
+        except (KeyError, RuntimeError):
+            path = f"/reset-password/{self.token}"
+        return f"{url(path)}?email={quote(self.email)}"
+
+
+class VerifyEmailMail(Mailable):
+    """Sent by `MustVerifyEmail.send_email_verification_notification()`. A temporary signed URL,
+    `/email/verify/{id}/{hash}?expires=...&signature=...` (T-21), valid for 60 minutes."""
+
+    def __init__(self, user: Any) -> None:
+        self.user = user
+
+    def envelope(self) -> Envelope:
+        return Envelope(subject="Verify Email Address")
+
+    def content(self) -> Content:
+        return Content(text=f"Please click the link below to verify your email address.\n\n{self._url()}\n\n"
+                             f"If you did not create an account, no further action is required.")
+
+    def _url(self) -> str:
+        from aso.routing import url
+
+        email_hash = hashlib.sha1(str(self.user.email).lower().encode()).hexdigest()
+        return url().temporary_signed_route(
+            "verification.verify", timedelta(minutes=60), {"id": self.user.id, "hash": email_hash}
+        )