maily-server 0.4.0__py3-none-any.whl

maily/__init__.py

@@ -0,0 +1,9 @@
+"""Local multi-provider mail API."""
+
+from .client import Maily, SyncMaily
+
+# Keep in sync with the `version` in pyproject.toml and with the standalone
+# client at client/client.py (it reads its own __version__ for auto-updates).
+__version__ = "0.4.0"  # x-release-please-version
+
+__all__ = ["Maily", "SyncMaily", "__version__"]

maily/app/authz.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import secrets
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Annotated, Final
+
+from fastapi import Depends, Header, HTTPException, Request, Security
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..db.models import ApiKey, Mailbox
+from .deps import SessionDep, api_key_header
+
+_API_KEY_HEADER: Final[dict[str, str]] = {"X-MailTM-Error": "api_key"}
+_INVALID_DETAIL: Final[str] = "invalid api key"
+_FORBIDDEN_DETAIL: Final[str] = "forbidden"
+
+
+def utcnow_naive() -> datetime:
+    """UTC now without tzinfo, matching stored naive expiry timestamps."""
+    return datetime.now(timezone.utc).replace(tzinfo=None)
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    """Caller resolved from the env root key or an issued api_keys row."""
+
+    is_root: bool
+    key: ApiKey | None
+
+
+@dataclass(frozen=True, slots=True)
+class Scope:
+    """Parsed scope_json. Invalid JSON is the deny scope, not an exception.
+
+    ``providers_open`` is true only for a parsed empty ``providers`` list,
+    which means every provider. A deny scope leaves it false so bad JSON
+    cannot be confused with "all providers".
+    """
+
+    providers: tuple[str, ...]
+    parent_ids: tuple[int, ...]
+    actions: frozenset[str]
+    providers_open: bool
+
+
+def _invalid_api_key() -> HTTPException:
+    return HTTPException(status_code=401, detail=_INVALID_DETAIL, headers=_API_KEY_HEADER)
+
+
+def _forbidden() -> HTTPException:
+    return HTTPException(status_code=403, detail=_FORBIDDEN_DETAIL)
+
+
+def presented_secret(
+    x_api_key: str | None,
+    authorization: str | None,
+) -> str | None:
+    """X-API-Key wins; otherwise Authorization: Bearer, same as require_api_key."""
+    if x_api_key:
+        return x_api_key
+    if authorization is None or not authorization.lower().startswith("bearer "):
+        return None
+    token = authorization[7:].strip()
+    if not token:
+        return None
+    return token
+
+
+def secret_sha256(secret: str) -> str:
+    """Hex SHA-256 of the raw presented secret. Ciphertext is never touched."""
+    return hashlib.sha256(secret.encode()).hexdigest()
+
+
+def _is_root_secret(presented: str, expected: str) -> bool:
+    if not expected or not presented:
+        return False
+    return secrets.compare_digest(presented.encode("utf-8"), expected.encode("utf-8"))
+
+
+def _deny_scope() -> Scope:
+    return Scope(providers=(), parent_ids=(), actions=frozenset(), providers_open=False)
+
+
+def parse_scope(scope_json: str) -> Scope:
+    """Parse scope_json. Any malformed payload denies every check."""
+    try:
+        raw = json.loads(scope_json)
+    except json.JSONDecodeError:
+        return _deny_scope()
+    if not isinstance(raw, dict):
+        return _deny_scope()
+    return _scope_from_payload(raw)
+
+
+def _scope_from_payload(payload: dict[str, object]) -> Scope:
+    providers = payload.get("providers")
+    parent_ids = payload.get("parent_ids")
+    actions = payload.get("actions")
+    if not isinstance(providers, list) or not isinstance(parent_ids, list):
+        return _deny_scope()
+    if not isinstance(actions, list):
+        return _deny_scope()
+    return _scope_from_lists(providers, parent_ids, actions)
+
+
+def _scope_from_lists(
+    providers: list[object],
+    parent_ids: list[object],
+    actions: list[object],
+) -> Scope:
+    provider_names = _strings(providers)
+    parent_id_values = _parent_ids(parent_ids)
+    action_names = _strings(actions)
+    if provider_names is None or parent_id_values is None or action_names is None:
+        return _deny_scope()
+    return Scope(
+        providers=provider_names,
+        parent_ids=parent_id_values,
+        actions=frozenset(action_names),
+        providers_open=len(provider_names) == 0,
+    )
+
+
+def _strings(items: list[object]) -> tuple[str, ...] | None:
+    names: list[str] = []
+    for item in items:
+        if not isinstance(item, str):
+            return None
+        names.append(item)
+    return tuple(names)
+
+
+def _parent_ids(items: list[object]) -> tuple[int, ...] | None:
+    ids: list[int] = []
+    for item in items:
+        if isinstance(item, bool) or not isinstance(item, int):
+            return None
+        ids.append(item)
+    return tuple(ids)
+
+
+def _expired(key: ApiKey, now: datetime) -> bool:
+    expires_at = key.expires_at
+    if expires_at is None:
+        return False
+    return expires_at <= now
+
+
+async def _lookup_key(session: AsyncSession, digest: str) -> ApiKey | None:
+    result = await session.execute(select(ApiKey).where(ApiKey.secret_sha256 == digest))
+    return result.scalar_one_or_none()
+
+
+async def require_principal(
+    request: Request,
+    session: SessionDep,
+    authorization: Annotated[str | None, Header()] = None,
+    x_api_key: Annotated[str | None, Security(api_key_header)] = None,
+) -> Principal:
+    """Resolve the caller. Empty env key is root. Env match is root before any lookup."""
+    expected: str = request.app.state.settings.api_key
+    if not expected:
+        return Principal(is_root=True, key=None)
+    presented = presented_secret(x_api_key, authorization)
+    if presented is None:
+        raise _invalid_api_key()
+    if _is_root_secret(presented, expected):
+        return Principal(is_root=True, key=None)
+    key = await _lookup_key(session, secret_sha256(presented))
+    if key is None or _expired(key, utcnow_naive()):
+        raise _invalid_api_key()
+    return Principal(is_root=False, key=key)
+
+
+PrincipalDep = Annotated[Principal, Depends(require_principal)]
+
+
+def action_allowed(principal: Principal, *names: str) -> bool:
+    """True when root, or when every named action is in the issued key's scope."""
+    if principal.is_root:
+        return True
+    key = principal.key
+    if key is None:
+        return False
+    scope = parse_scope(key.scope_json)
+    return all(name in scope.actions for name in names)
+
+
+def require_action(*names: str) -> Callable[..., Awaitable[Principal]]:
+    """Dependency factory. Every named action must be present. Root bypasses."""
+
+    async def _require(principal: PrincipalDep) -> Principal:
+        if not action_allowed(principal, *names):
+            raise _forbidden()
+        return principal
+
+    return _require
+
+
+async def require_root(principal: PrincipalDep) -> Principal:
+    """Issued keys are 403. Root (including open mode) passes."""
+    if not principal.is_root:
+        raise _forbidden()
+    return principal
+
+
+RootDep = Annotated[Principal, Depends(require_root)]
+StatsRead = Annotated[Principal, Depends(require_action("stats:read"))]
+RetentionRead = Annotated[Principal, Depends(require_action("retention:read"))]
+RetentionWrite = Annotated[Principal, Depends(require_action("retention:write"))]
+ParentsAdd = Annotated[Principal, Depends(require_action("parents:add"))]
+ParentsRead = Annotated[Principal, Depends(require_action("parents:read"))]
+MailboxesWrite = Annotated[Principal, Depends(require_action("mailboxes:write"))]
+MailboxesRead = Annotated[Principal, Depends(require_action("mailboxes:read"))]
+
+
+def owns_mailbox(principal: Principal, mailbox: Mailbox) -> bool:
+    """Root owns every mailbox. An issued key owns only rows stamped with its id."""
+    if principal.is_root:
+        return True
+    key = principal.key
+    if key is None:
+        return False
+    return mailbox.owner_key_id == key.id
+
+
+def provider_allowed(principal: Principal, slug: str) -> bool:
+    """Empty providers means every slug. Invalid scope denies. Root always allowed."""
+    if principal.is_root:
+        return True
+    key = principal.key
+    if key is None:
+        return False
+    scope = parse_scope(key.scope_json)
+    if scope.providers_open:
+        return True
+    return slug in scope.providers
+
+
+def parent_allowed(principal: Principal, parent_id: int) -> bool:
+    """Empty parent_ids means none. Root always allowed. Invalid scope denies."""
+    if principal.is_root:
+        return True
+    key = principal.key
+    if key is None:
+        return False
+    scope = parse_scope(key.scope_json)
+    return parent_id in scope.parent_ids

maily/app/deps.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import secrets
+from collections.abc import AsyncIterator
+from typing import Annotated
+
+from fastapi import Depends, Header, HTTPException, Request, Security
+from fastapi.security import APIKeyHeader
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..providers.registry import ProviderRegistry
+from ..settings import Settings
+
+api_key_header = APIKeyHeader(
+    name="X-API-Key",
+    auto_error=False,
+    description="API key (required only when the server runs with MAILY_API_KEY set).",
+)
+
+
+def get_settings(request: Request) -> Settings:
+    return request.app.state.settings
+
+
+def get_registry(request: Request) -> ProviderRegistry:
+    return request.app.state.registry
+
+
+async def get_session(request: Request) -> AsyncIterator[AsyncSession]:
+    factory = request.app.state.session_factory
+    async with factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def require_api_key(
+    request: Request,
+    authorization: Annotated[str | None, Header()] = None,
+    x_api_key: Annotated[str | None, Security(api_key_header)] = None,
+) -> None:
+    expected: str = request.app.state.settings.api_key
+    if not expected:
+        return
+    provided = x_api_key
+    if not provided and authorization and authorization.lower().startswith("bearer "):
+        provided = authorization[7:].strip()
+    if not provided or not secrets.compare_digest(provided, expected):
+        # Header lets the UI distinguish this 401 from a provider-auth 401
+        # (Gmail token expired → MailAuthError) which must NOT trigger the
+        # API-key prompt.
+        raise HTTPException(
+            status_code=401,
+            detail="invalid api key",
+            headers={"X-MailTM-Error": "api_key"},
+        )
+
+
+SettingsDep = Annotated[Settings, Depends(get_settings)]
+RegistryDep = Annotated[ProviderRegistry, Depends(get_registry)]
+SessionDep = Annotated[AsyncSession, Depends(get_session)]  # type: ignore[assignment]

maily/app/errors.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import logging
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from ..exceptions import (
+    MailAPIError,
+    MailAuthError,
+    MailConflictError,
+    MailNotFoundError,
+    MailRateLimitError,
+    MailValidationError,
+)
+
+logger = logging.getLogger("maily.errors")
+
+
+def _json(
+    status: int,
+    detail: str,
+    headers: dict[str, str] | None = None,
+    code: str | None = None,
+) -> JSONResponse:
+    body: dict[str, str] = {"detail": detail}
+    if code:
+        body["code"] = code
+    return JSONResponse(body, status_code=status, headers=headers)
+
+
+def register_errors(app: FastAPI) -> None:
+    @app.exception_handler(StarletteHTTPException)
+    async def _http(_req: Request, exc: StarletteHTTPException) -> JSONResponse:
+        # Generic HTTPException (raise HTTPException(...) in routers / deps).
+        # The API-key 401 (X-MailTM-Error: api_key) gets a machine-readable
+        # `code` so the UI no longer depends on headers or detail strings only.
+        headers = dict(exc.headers or {})
+        body: dict[str, str] = {"detail": str(exc.detail)}
+        if headers.get("X-MailTM-Error") == "api_key":
+            body["code"] = "api_key"
+        return JSONResponse(body, status_code=exc.status_code, headers=headers)
+
+    @app.exception_handler(RequestValidationError)
+    async def _validation(_req: Request, exc: RequestValidationError) -> JSONResponse:
+        return JSONResponse(
+            {"detail": exc.errors(), "code": "validation_error"},
+            status_code=422,
+        )
+
+    @app.exception_handler(MailNotFoundError)
+    async def _not_found(_req: Request, exc: MailNotFoundError) -> JSONResponse:
+        return _json(404, str(exc), code="not_found")
+
+    @app.exception_handler(MailValidationError)
+    async def _bad(_req: Request, exc: MailValidationError) -> JSONResponse:
+        return _json(400, str(exc), code="validation_error")
+
+    @app.exception_handler(MailAuthError)
+    async def _auth(_req: Request, exc: MailAuthError) -> JSONResponse:
+        # 401 collides with the API-key check; the header lets the UI tell
+        # "Google rejected the account token" apart from "server needs a key".
+        return _json(
+            401,
+            str(exc),
+            headers={"X-MailTM-Error": "provider_auth"},
+            code="provider_auth",
+        )
+
+    @app.exception_handler(MailConflictError)
+    async def _conflict(_req: Request, exc: MailConflictError) -> JSONResponse:
+        return _json(409, str(exc), code="conflict")
+
+    @app.exception_handler(MailRateLimitError)
+    async def _rate(_req: Request, exc: MailRateLimitError) -> JSONResponse:
+        return _json(429, str(exc), code="rate_limit")
+
+    @app.exception_handler(MailAPIError)
+    async def _api(_req: Request, exc: MailAPIError) -> JSONResponse:
+        return _json(502, str(exc), code="upstream")
+
+    @app.exception_handler(KeyError)
+    async def _key(_req: Request, exc: KeyError) -> JSONResponse:
+        # registry.get raises KeyError for an unknown provider slug
+        return _json(404, str(exc).strip("'\""), code="not_found")
+
+    @app.exception_handler(Exception)
+    async def _internal(req: Request, exc: Exception) -> JSONResponse:
+        logger.exception("unhandled error on %s %s", req.method, req.url.path)
+        return _json(500, "Internal server error", code="internal")

maily/app/main.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager, suppress
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from loguru import logger
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from .. import __version__
+from ..db.engine import SessionFactory, make_engine
+from ..http import HttpClient
+from ..providers.gmail.db_store import DbGmailStore
+from ..providers.gmail.oauth import GmailOAuth
+from ..providers.gmail.service import GmailProvider
+from ..providers.registry import ProviderRegistry, create_public_providers
+from ..settings import Settings, get_settings
+from .errors import register_errors
+from .middleware.origin import OriginGuard
+from .routers.admin import router as admin_router
+from .routers.gmail import public as gmail_public
+from .routers.gmail import router as gmail_router
+from .routers.health import router as health_router
+from .routers.keys import me_router as keys_me_router
+from .routers.keys import router as keys_router
+from .routers.mailboxes import router as mailboxes_router
+from .routers.messages import router as messages_router
+from .routers.providers import router as providers_router
+from .services import domain_cache as dc
+from .services import provider_headers as ph
+from .services import stats_history
+from .services.retention import retention_worker, run_sweep
+
+OPENAPI_TAGS = [
+    {
+        "name": "System",
+        "description": "Liveness, readiness and client-facing configuration.",
+    },
+    {
+        "name": "Providers",
+        "description": "Enabled temp-mail providers and their usable posting targets.",
+    },
+    {
+        "name": "Mailboxes",
+        "description": "Create, list, look up and delete disposable mailboxes.",
+    },
+    {
+        "name": "Messages",
+        "description": "Read, mark, delete and download messages for a mailbox.",
+    },
+    {
+        "name": "Gmail",
+        "description": "Import Gmail accounts, OAuth pairing and per-account sync.",
+    },
+    {
+        "name": "Admin",
+        "description": "Operational controls: retention TTLs, domain cache and Gmail credentials.",
+    },
+    {
+        "name": "Keys",
+        "description": "Issued API keys are root-only except GET /me.",
+    },
+]
+
+
+_LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1"})
+
+
+def _refuse_open_bind(settings: Settings) -> None:
+    host = settings.host.strip().lower()
+    if settings.api_key or host in _LOOPBACK_HOSTS:
+        return
+    raise RuntimeError(
+        "Refusing to listen on a non-loopback address without an API key. "
+        "Set MAILY_API_KEY or bind MAILY_HOST to 127.0.0.1."
+    )
+
+
+def _run_migrations(url: str) -> None:
+    from alembic import command
+    from alembic.config import Config
+
+    cfg = Config()
+    root = Path(__file__).resolve().parents[3]
+    alembic_dir = root / "alembic"
+    if not alembic_dir.is_dir():
+        cwd_alembic = Path.cwd() / "alembic"
+        if cwd_alembic.is_dir():
+            alembic_dir = cwd_alembic
+        else:
+            for parent in Path(__file__).resolve().parents:
+                if (parent / "alembic").is_dir():
+                    alembic_dir = parent / "alembic"
+                    break
+    cfg.set_main_option("script_location", str(alembic_dir))
+    cfg.set_main_option("sqlalchemy.url", url.replace("sqlite+aiosqlite", "sqlite"))
+    command.upgrade(cfg, "head")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    settings: Settings = app.state.settings
+    _refuse_open_bind(settings)
+    # Resolve (and pin) the Fernet key before any request can race to mint one.
+    settings.resolved_secret_key()
+    engine: AsyncEngine = make_engine(
+        settings.database_url,
+        busy_timeout_ms=settings.sqlite_busy_timeout_ms,
+    )
+    _run_migrations(settings.database_url)
+    factory = SessionFactory(engine)
+    # Seed the ledger's receive-counters from messages that predate the ledger,
+    # so the 7-day incoming chart doesn't fall back to live rows and then
+    # silently lose past days to retention deletes. Idempotent per day.
+    async with factory() as session:
+        seeded = await stats_history.backfill_received(session)
+        await session.commit()
+        if seeded:
+            logger.info(
+                "stats: seeded message_received for {} day/provider bucket(s)",
+                seeded,
+            )
+    http = HttpClient(proxy=settings.proxy)
+    secret = settings.resolved_secret_key()
+    store = DbGmailStore(factory, secret)
+    try:
+        cid, csec = settings.gmail_client()
+    except RuntimeError:
+        cid, csec = "", ""
+    oauth = GmailOAuth(
+        cid,
+        csec,
+        http,
+        token_uri=settings.gmail_token_uri,
+        auth_uri=settings.gmail_auth_uri,
+    )
+    if not cid:
+        from .services import gmail_config as gcfg
+
+        async with factory() as session:
+            db_creds = await gcfg.get_creds(session, secret)
+        if db_creds:
+            oauth.configure(*db_creds)
+    gmail = GmailProvider(store, oauth, http)
+    registry = ProviderRegistry(
+        [
+            gmail,
+            *create_public_providers(http=http, settings=settings),
+        ]
+    )
+    await ph.bootstrap(factory, http, registry, settings)
+    app.state.engine = engine
+    app.state.session_factory = factory
+    app.state.registry = registry
+    app.state.http = http
+    app.state.gmail = gmail
+    app.state.oauth = oauth
+    app.state.oauth_states = {}
+    sweep_lock = asyncio.Lock()
+    app.state.sweep_lock = sweep_lock
+
+    sweep_task = asyncio.create_task(
+        retention_worker(
+            lambda: run_sweep(
+                factory, getattr(app.state, "registry", registry), settings, lock=sweep_lock
+            ),
+            settings.retention_interval_seconds,
+        )
+    )
+    cache_task = asyncio.create_task(dc.domain_cache_worker(factory, registry, settings))
+    headers_task = asyncio.create_task(
+        ph.provider_headers_worker(factory, http, registry, settings)
+    )
+    try:
+        yield
+    finally:
+        for task in (sweep_task, cache_task, headers_task):
+            task.cancel()
+        with suppress(asyncio.CancelledError):
+            await sweep_task
+        with suppress(asyncio.CancelledError):
+            await cache_task
+        with suppress(asyncio.CancelledError):
+            await headers_task
+        await registry.close()
+        await http.close()
+        await engine.dispose()
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    settings = settings or get_settings()
+    app = FastAPI(
+        title="maily",
+        version=__version__,
+        lifespan=lifespan,
+        description=(
+            "Local multi-provider temporary-email API. "
+            "Most endpoints require the `X-API-Key` header (see Admin → API key in the dashboard)."
+        ),
+        openapi_tags=OPENAPI_TAGS,
+        docs_url=None,
+        redoc_url=None,
+        swagger_ui_parameters={
+            "docExpansion": "none",
+            "filter": True,
+            "displayRequestDuration": True,
+            "persistAuthorization": True,
+        },
+    )
+    app.state.settings = settings
+    register_errors(app)
+    app.include_router(health_router)
+    app.include_router(gmail_public)
+    app.include_router(providers_router)
+    app.include_router(gmail_router)
+    app.include_router(mailboxes_router)
+    app.include_router(messages_router)
+    app.include_router(admin_router)
+    app.include_router(keys_me_router)
+    app.include_router(keys_router)
+    app.add_middleware(OriginGuard)
+    static_dir = Path(__file__).resolve().parents[1] / "static"
+
+    @app.get("/docs", include_in_schema=False)
+    async def docs(_: Request) -> FileResponse:
+        return FileResponse(static_dir / "docs.html")
+
+    if static_dir.is_dir():
+        app.mount("/", StaticFiles(directory=static_dir, html=True), name="static")
+    return app
+
+
+def run() -> None:
+    import uvicorn
+
+    settings = get_settings()
+    uvicorn.run(
+        "maily.app.main:create_app",
+        factory=True,
+        host=settings.host,
+        port=settings.port,
+    )
+
+
+if __name__ == "__main__":
+    run()