simple-module-billing 0.0.8__py3-none-any.whl

sm_billing/crypto.py

@@ -0,0 +1,89 @@
+"""Fernet encryption for the stored Stripe secrets.
+
+The pattern of ``sm_ai.crypto``, copied rather than imported: a published
+module must not depend on a sibling optional module. The key derives from the
+running app's ``secret_key`` (SHA-256 → urlsafe base64), installed by
+``BillingModule.register_settings``. Unlike the AI module there is no
+environment fallback — billing reads no environment, and the app's secret is
+always available once the module is registered.
+
+Stored format is ``enc:v1:<fernet token>``:
+
+- prefix present and decrypts        → plaintext secret
+- prefix present, decryption fails   → BillingKeyUnreadableError (secret_key changed)
+- no prefix                          → treated as plaintext, warned once per field
+  (covers values set through the generic Settings screen or set_setting.py)
+"""
+
+from __future__ import annotations
+
+import logging
+from base64 import urlsafe_b64encode
+from collections.abc import Callable
+from functools import lru_cache
+from hashlib import sha256
+
+from cryptography.fernet import Fernet, InvalidToken
+
+logger = logging.getLogger(__name__)
+
+ENC_PREFIX = "enc:v1:"
+
+_warned_plaintext: set[str] = set()
+_secret_provider: Callable[[], str] | None = None
+
+
+class BillingKeyUnreadableError(Exception):
+    """A stored secret was encrypted under a different ``secret_key``."""
+
+    def __init__(self, field: str) -> None:
+        super().__init__(
+            f"Billing setting {field!r} cannot be decrypted — the app's secret_key "
+            "changed since it was saved. Re-enter it on /admin/billing/connection."
+        )
+        self.field = field
+
+
+def set_secret_provider(provider: Callable[[], str]) -> None:
+    """Install the live-secret source (the running app's ``secret_key``)."""
+    global _secret_provider
+    _secret_provider = provider
+
+
+def _fernet() -> Fernet:
+    secret = _secret_provider() if _secret_provider is not None else ""
+    if not secret:
+        raise RuntimeError(
+            "The app has no secret_key — the billing module needs it to encrypt "
+            "stored Stripe secrets."
+        )
+    return _fernet_for(secret)
+
+
+@lru_cache(maxsize=4)
+def _fernet_for(secret: str) -> Fernet:
+    return Fernet(urlsafe_b64encode(sha256(secret.encode()).digest()))
+
+
+def encrypt_value(plain: str) -> str:
+    """Encrypt a secret for storage."""
+    return ENC_PREFIX + _fernet().encrypt(plain.encode()).decode()
+
+
+def decrypt_value(stored: str, field: str) -> str:
+    """Return the plaintext for a stored value (see module docstring)."""
+    if not stored:
+        return ""
+    if stored.startswith(ENC_PREFIX):
+        try:
+            return _fernet().decrypt(stored[len(ENC_PREFIX) :].encode()).decode()
+        except InvalidToken as exc:
+            raise BillingKeyUnreadableError(field) from exc
+    if field not in _warned_plaintext:
+        _warned_plaintext.add(field)
+        logger.warning(
+            "Billing setting %r is stored unencrypted; re-save it on "
+            "/admin/billing/connection to encrypt it.",
+            field,
+        )
+    return stored

sm_billing/deps.py

@@ -0,0 +1,67 @@
+"""FastAPI dependencies for the billing routes."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from simple_module_db.deps import get_db
+from sqlalchemy.ext.asyncio import AsyncSession
+from tenants.deps import ActiveTenantContext, require_active_tenant, require_user_id
+
+from sm_billing import constants as c
+from sm_billing.checkout import BillingService
+from sm_billing.context import BillingContext, billing_context
+from sm_billing.errors import BillingError
+
+ActiveTenant = Annotated[ActiveTenantContext, Depends(require_active_tenant)]
+
+
+def require_owner(ctx: ActiveTenant) -> ActiveTenantContext:
+    """Money decisions belong to the tenant's owner, not every manager."""
+    if ctx.role != c.TENANT_ROLE_OWNER:
+        raise BillingError("tenant_owner_required", 403)
+    return ctx
+
+
+Owner = Annotated[ActiveTenantContext, Depends(require_owner)]
+
+
+def get_billing_service(
+    request: Request, ctx: ActiveTenant, db: AsyncSession = Depends(get_db)
+) -> BillingService:
+    return BillingService(db, request.app, ctx.tenant_id)
+
+
+BillingServiceDep = Annotated[BillingService, Depends(get_billing_service)]
+
+
+def base_url(request: Request) -> str:
+    """Origin for provider return URLs: the setting, else this request's origin."""
+    configured = getattr(request.app.state, c.PACKAGE).settings.return_base_url
+    return (configured or str(request.base_url)).rstrip("/")
+
+
+def user_email(request: Request) -> str | None:
+    return getattr(getattr(request.state, "user", None), "email", None)
+
+
+async def get_context(request: Request, db: AsyncSession = Depends(get_db)) -> BillingContext:
+    """Active tenant, or a billing-suspended one its owner is restoring."""
+    require_user_id(request)
+    ctx = await billing_context(request, db)
+    if ctx is None:
+        raise BillingError("tenant_required", 403)
+    return ctx
+
+
+Context = Annotated[BillingContext, Depends(get_context)]
+
+
+def get_context_service(
+    request: Request, ctx: Context, db: AsyncSession = Depends(get_db)
+) -> BillingService:
+    return BillingService(db, request.app, ctx.tenant_id)
+
+
+ContextServiceDep = Annotated[BillingService, Depends(get_context_service)]

sm_billing/endpoints/admin_api.py

@@ -0,0 +1,93 @@
+"""Platform-admin billing API (``/api/billing/admin``). CSRF-checked."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from simple_module_db.deps import get_db
+from simple_module_hosting.csrf import RequiresCsrf
+from simple_module_hosting.permissions import RequiresPermission
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sm_billing import admin
+from sm_billing import constants as c
+from sm_billing.checkout import plan_out
+from sm_billing.plans import PlanService
+from sm_billing.schemas import (
+    AssignIn,
+    ConnectionIn,
+    ConnectionOut,
+    PlanIn,
+    PlanOut,
+    SubscriptionRow,
+)
+
+router = APIRouter(prefix="/admin", dependencies=[Depends(RequiresCsrf())])
+
+_VIEW = [Depends(RequiresPermission(c.PERM_PLATFORM_VIEW))]
+_MANAGE = [Depends(RequiresPermission(c.PERM_PLATFORM_MANAGE))]
+
+
+@router.get("/plans", response_model=list[PlanOut], dependencies=_VIEW)
+async def list_plans(db: AsyncSession = Depends(get_db)) -> list[PlanOut]:
+    return [plan_out(p) for p in await PlanService(db).list()]
+
+
+@router.post("/plans", response_model=PlanOut, status_code=201, dependencies=_MANAGE)
+async def create_plan(
+    body: PlanIn, request: Request, db: AsyncSession = Depends(get_db)
+) -> PlanOut:
+    return plan_out(await admin.save_plan(db, request.app, body, None))
+
+
+@router.put("/plans/{plan_id}", response_model=PlanOut, dependencies=_MANAGE)
+async def update_plan(
+    plan_id: int, body: PlanIn, request: Request, db: AsyncSession = Depends(get_db)
+) -> PlanOut:
+    return plan_out(await admin.save_plan(db, request.app, body, plan_id))
+
+
+@router.post("/plans/{plan_id}/archive", response_model=PlanOut, dependencies=_MANAGE)
+async def archive_plan(plan_id: int, db: AsyncSession = Depends(get_db)) -> PlanOut:
+    return plan_out(await PlanService(db).archive(plan_id))
+
+
+@router.get("/subscriptions", response_model=list[SubscriptionRow], dependencies=_VIEW)
+async def list_subscriptions(
+    request: Request,
+    status: str | None = None,
+    offset: int = 0,
+    db: AsyncSession = Depends(get_db),
+) -> list[SubscriptionRow]:
+    return await admin.subscription_rows(db, request.app, status=status, offset=max(0, offset))
+
+
+@router.post(
+    "/subscriptions/{tenant_id}/assign", response_model=SubscriptionRow, dependencies=_MANAGE
+)
+async def assign(
+    tenant_id: str, body: AssignIn, request: Request, db: AsyncSession = Depends(get_db)
+) -> SubscriptionRow:
+    await admin.assign(db, request.app, tenant_id, body)
+    return await admin.one_row(db, request.app, tenant_id)
+
+
+@router.post(
+    "/subscriptions/{tenant_id}/resync", response_model=SubscriptionRow, dependencies=_MANAGE
+)
+async def resync(
+    tenant_id: str, request: Request, db: AsyncSession = Depends(get_db)
+) -> SubscriptionRow:
+    await admin.resync(db, request.app, tenant_id)
+    return await admin.one_row(db, request.app, tenant_id)
+
+
+@router.get("/connection", response_model=ConnectionOut, dependencies=_VIEW)
+async def get_connection(request: Request) -> ConnectionOut:
+    return admin.connection_out(request.app)
+
+
+@router.put("/connection", response_model=ConnectionOut, dependencies=_MANAGE)
+async def put_connection(
+    body: ConnectionIn, request: Request, db: AsyncSession = Depends(get_db)
+) -> ConnectionOut:
+    return await admin.save_connection(db, request.app, body)

sm_billing/endpoints/admin_views.py

@@ -0,0 +1,70 @@
+"""Platform-admin billing screens under ``/admin/billing``. Reads only."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from simple_module_core.permissions import grants
+from simple_module_db.deps import get_db
+from simple_module_hosting.csrf import get_csrf_token
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import RequiresPermission, resolved_permissions_for
+from simple_module_inertia import InertiaResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sm_billing import admin
+from sm_billing import constants as c
+from sm_billing.checkout import plan_out
+from sm_billing.plans import PlanService
+
+router = APIRouter(dependencies=[Depends(RequiresPermission(c.PERM_PLATFORM_VIEW))])
+
+
+def _common(request: Request) -> dict:
+    services = getattr(request.app.state, c.PACKAGE)
+    return {
+        "csrf_token": get_csrf_token(request),
+        "can_manage": grants(resolved_permissions_for(request), c.PERM_PLATFORM_MANAGE),
+        "provider": services.provider.name if services.provider else "",
+        "checkout_available": bool(services.provider and services.provider.supports_checkout),
+    }
+
+
+@router.get("/plans", response_model=None)
+async def plans_page(
+    request: Request, inertia: InertiaDep, db: AsyncSession = Depends(get_db)
+) -> InertiaResponse:
+    plans = [plan_out(p).model_dump(mode="json") for p in await PlanService(db).list()]
+    return await inertia.render(
+        c._PAGE_PLANS,
+        {**_common(request), "plans": plans, "known_limit_keys": list(c.KNOWN_LIMIT_KEYS)},
+    )
+
+
+@router.get("/subscriptions", response_model=None)
+async def subscriptions_page(
+    request: Request, inertia: InertiaDep, db: AsyncSession = Depends(get_db)
+) -> InertiaResponse:
+    status = request.query_params.get("status") or None
+    rows = await admin.subscription_rows(db, request.app, status=status)
+    plans = [plan_out(p).model_dump(mode="json") for p in await PlanService(db).list()]
+    return await inertia.render(
+        c._PAGE_SUBSCRIPTIONS,
+        {
+            **_common(request),
+            "rows": [r.model_dump(mode="json") for r in rows],
+            "plans": plans,
+            "status_filter": status or "",
+        },
+    )
+
+
+@router.get("/connection", response_model=None)
+async def connection_page(request: Request, inertia: InertiaDep) -> InertiaResponse:
+    return await inertia.render(
+        c._PAGE_CONNECTION,
+        {
+            **_common(request),
+            "connection": admin.connection_out(request.app).model_dump(mode="json"),
+            "webhook_url": str(request.base_url).rstrip("/") + c.WEBHOOK_PATH,
+        },
+    )

sm_billing/endpoints/api.py

@@ -0,0 +1,61 @@
+"""Tenant billing API (``/api/billing``). CSRF-checked on every mutation."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from simple_module_core.permissions import grants
+from simple_module_hosting.csrf import RequiresCsrf
+from simple_module_hosting.permissions import RequiresPermission, resolved_permissions_for
+
+from sm_billing import constants as c
+from sm_billing.deps import (
+    BillingServiceDep,
+    Context,
+    ContextServiceDep,
+    Owner,
+    base_url,
+    user_email,
+)
+from sm_billing.errors import BillingError
+from sm_billing.schemas import PlanChoice, StatusOut, UrlOut
+
+router = APIRouter(dependencies=[Depends(RequiresCsrf())])
+
+_MANAGE = [Depends(RequiresPermission(c.PERM_MANAGE))]
+
+
+@router.get("/status", response_model=StatusOut)
+async def status(request: Request, ctx: Context, service: ContextServiceDep) -> StatusOut:
+    if not ctx.restore:
+        _require(request, c.PERM_VIEW)
+    return await service.status()
+
+
+@router.post("/checkout", response_model=UrlOut, dependencies=_MANAGE)
+async def checkout(
+    body: PlanChoice, request: Request, service: BillingServiceDep, _: Owner
+) -> UrlOut:
+    url = await service.checkout(
+        body.plan_id, body.interval, email=user_email(request), base=base_url(request)
+    )
+    return UrlOut(url=url)
+
+
+@router.post("/portal", response_model=UrlOut)
+async def portal(request: Request, ctx: Context, service: ContextServiceDep) -> UrlOut:
+    """Also open to the owner of a billing-suspended tenant — it is how they pay."""
+    if ctx.role != c.TENANT_ROLE_OWNER:
+        raise BillingError("tenant_owner_required", 403)
+    if not ctx.restore:
+        _require(request, c.PERM_MANAGE)
+    return UrlOut(url=await service.portal(base=base_url(request)))
+
+
+def _require(request: Request, permission: str) -> None:
+    if not grants(resolved_permissions_for(request), permission):
+        raise BillingError("forbidden", 403)
+
+
+@router.post("/change-plan", response_model=StatusOut, dependencies=_MANAGE)
+async def change_plan(body: PlanChoice, service: BillingServiceDep, _: Owner) -> StatusOut:
+    return await service.change_plan(body.plan_id, body.interval)

sm_billing/endpoints/routers.py

@@ -0,0 +1,26 @@
+"""Router wiring, kept out of ``module.py`` so the hooks stay one line."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+
+def include(api_router: APIRouter, view_router: APIRouter) -> None:
+    """Mount the tenant API, admin API, webhook and tenant views."""
+    from sm_billing.endpoints.admin_api import router as admin_api
+    from sm_billing.endpoints.api import router as api
+    from sm_billing.endpoints.views import router as views
+    from sm_billing.endpoints.webhooks import router as webhooks
+
+    api_router.include_router(admin_api)
+    api_router.include_router(api)
+    # No CSRF on the webhook: Stripe has no session, the signature is the auth.
+    view_router.include_router(webhooks)
+    view_router.include_router(views)
+
+
+def include_admin(admin_router: APIRouter) -> None:
+    """Mount the platform-admin Inertia views under ``/admin/billing``."""
+    from sm_billing.endpoints.admin_views import router as admin_views
+
+    admin_router.include_router(admin_views)

sm_billing/endpoints/views.py

@@ -0,0 +1,56 @@
+"""Tenant billing screen (``/billing/``). Reads only; mutations go through the API.
+
+The permission is checked in the handler rather than as a route dependency:
+a signed-in user with no active tenant holds no ``tenant:*`` role yet, and
+should be sent to pick an organisation, not shown a 403.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Request
+from fastapi.responses import RedirectResponse
+from simple_module_core.permissions import grants
+from simple_module_db.deps import get_db
+from simple_module_hosting.csrf import get_csrf_token
+from simple_module_hosting.inertia_deps import InertiaDep
+from simple_module_hosting.permissions import resolved_permissions_for
+from simple_module_inertia import InertiaResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from sm_billing import constants as c
+from sm_billing.checkout import BillingService
+from sm_billing.context import billing_context
+
+router = APIRouter()
+
+NO_TENANT_REDIRECT = "/tenants/?reason=tenant_required"
+
+
+def _perm(request: Request, permission: str) -> bool:
+    return grants(resolved_permissions_for(request), permission)
+
+
+@router.get("/", response_model=None)
+async def billing_page(
+    request: Request, inertia: InertiaDep, db: AsyncSession = Depends(get_db)
+) -> InertiaResponse | RedirectResponse:
+    ctx = await billing_context(request, db)
+    if ctx is None or (not ctx.restore and not _perm(request, c.PERM_VIEW)):
+        return RedirectResponse(NO_TENANT_REDIRECT, status_code=303)
+    service = BillingService(db, request.app, ctx.tenant_id)
+    # Restore mode is pay-only: no plan changes from a suspended organisation.
+    can_manage = (
+        not ctx.restore and _perm(request, c.PERM_MANAGE) and ctx.role == c.TENANT_ROLE_OWNER
+    )
+    status = await service.status()
+    return await inertia.render(
+        c._PAGE_BILLING,
+        {
+            "status": status.model_dump(mode="json"),
+            "plans": [p.model_dump(mode="json") for p in await service.public_plans()],
+            "can_manage": can_manage,
+            "restore": ctx.restore,
+            "csrf_token": get_csrf_token(request),
+            "checkout": request.query_params.get("checkout", ""),
+        },
+    )

sm_billing/endpoints/webhooks.py

@@ -0,0 +1,27 @@
+"""``POST /billing/webhooks/stripe`` — public; the signature is the authentication.
+
+Mounted on the view router (prefix ``/billing``) with no CSRF dependency, and
+exempted from ``AuthMiddleware`` in ``BillingModule.register_public_routes``.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+from sm_billing import constants as c
+from sm_billing.webhooks import process_webhook
+
+router = APIRouter()
+
+
+@router.post("/webhooks/stripe", include_in_schema=False)
+async def stripe_webhook(request: Request) -> JSONResponse:
+    services = getattr(request.app.state, c.PACKAGE)
+    provider = services.provider
+    if provider is None or provider.name != c.PROVIDER_STRIPE:
+        return JSONResponse({"detail": "stripe_not_configured"}, status_code=404)
+    status, detail = await process_webhook(
+        request.app, provider, await request.body(), request.headers
+    )
+    return JSONResponse({"detail": detail}, status_code=status)

sm_billing/entitlements.py

@@ -0,0 +1,30 @@
+"""``PlanEntitlements`` — the tenants entitlement seam, answered from plans.
+
+Installed as ``app.state.tenants.entitlements`` at startup. ``tenants`` reads
+that attribute per request, so consumers keep depending on its protocol and
+never import billing. Each call opens its own short session: callers (the
+tenants service, a consumer's route) hold their own and must not see ours.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import async_sessionmaker
+
+from sm_billing.resolve import effective_plan
+
+
+class PlanEntitlements:
+    def __init__(self, session_factory: async_sessionmaker) -> None:
+        self._session_factory = session_factory
+
+    async def limit(self, tenant_id: str, key: str) -> int | None:
+        """The plan's limit for ``key``; an absent key is unlimited (``None``)."""
+        async with self._session_factory() as session:
+            plan, _ = await effective_plan(session, tenant_id)
+        value = plan.limits.get(key)
+        return None if value is None else int(value)
+
+    async def has_feature(self, tenant_id: str, key: str) -> bool:
+        async with self._session_factory() as session:
+            plan, _ = await effective_plan(session, tenant_id)
+        return key in plan.features

sm_billing/errors.py

@@ -0,0 +1,41 @@
+"""Billing errors and their JSON mapping (``{"detail": code, ...}``)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+from sm_billing.contracts.provider import ProviderError
+from sm_billing.plans import PlanError
+
+logger = logging.getLogger(__name__)
+
+
+class BillingError(Exception):
+    def __init__(self, code: str, status_code: int = 400, **extra: Any) -> None:
+        super().__init__(code)
+        self.code = code
+        self.status_code = status_code
+        self.extra = extra
+
+
+async def _billing_error(_: Request, exc: BillingError) -> JSONResponse:
+    return JSONResponse({"detail": exc.code, **exc.extra}, status_code=exc.status_code)
+
+
+async def _plan_error(_: Request, exc: PlanError) -> JSONResponse:
+    return JSONResponse({"detail": exc.code}, status_code=exc.status_code)
+
+
+async def _provider_error(request: Request, exc: ProviderError) -> JSONResponse:
+    logger.warning("billing: provider call failed on %s: %s", request.url.path, exc)
+    return JSONResponse({"detail": "provider_error", "message": str(exc)}, status_code=502)
+
+
+def install_exception_handlers(app: FastAPI) -> None:
+    app.add_exception_handler(BillingError, _billing_error)
+    app.add_exception_handler(PlanError, _plan_error)
+    app.add_exception_handler(ProviderError, _provider_error)

sm_billing/hooks/useCheckoutPolling.ts

@@ -0,0 +1,50 @@
+import { useEffect, useState } from 'react';
+import { api, BILLING_API } from '../utils/api';
+import { isActivated } from '../utils/format';
+import type { Status } from '../utils/types';
+
+const INTERVAL_MS = 2000;
+const MAX_TRIES = 15;
+
+/**
+ * After Stripe redirects back with ``?checkout=success`` the webhook may not
+ * have landed yet — the redirect itself grants nothing. Poll the status until
+ * a provider subscription shows up, then hand it over; give up after ~30s.
+ */
+export function useCheckoutPolling(
+  active: boolean,
+  csrf: string,
+  onActivated: () => void,
+): 'idle' | 'waiting' | 'timeout' {
+  const [state, setState] = useState<'idle' | 'waiting' | 'timeout'>(active ? 'waiting' : 'idle');
+
+  useEffect(() => {
+    if (!active) return;
+    let tries = 0;
+    let cancelled = false;
+    const timer = setInterval(async () => {
+      tries += 1;
+      try {
+        const status = await api<Status>(`${BILLING_API}/status`, csrf);
+        if (!cancelled && isActivated(status)) {
+          clearInterval(timer);
+          setState('idle');
+          onActivated();
+          return;
+        }
+      } catch {
+        // Transient; keep polling until the budget runs out.
+      }
+      if (tries >= MAX_TRIES && !cancelled) {
+        clearInterval(timer);
+        setState('timeout');
+      }
+    }, INTERVAL_MS);
+    return () => {
+      cancelled = true;
+      clearInterval(timer);
+    };
+  }, [active, csrf, onActivated]);
+
+  return state;
+}