nat-engine 1__py3-none-any.whl

mannf/product/billing/stripe_billing.py

@@ -0,0 +1,906 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Stripe billing integration for NAT self-serve SaaS onboarding.
+
+Provides:
+- ``create_checkout_session`` — Stripe Checkout for plan sign-up
+- ``create_portal_session``   — Stripe Customer Portal for subscription management
+- ``handle_webhook_event``    — Process Stripe webhook events
+- ``generate_api_key``        — Generate ``nat_pk_<32-hex>`` keys, hash for storage
+
+All Stripe calls are gated on ``STRIPE_SECRET_KEY`` being set.  If it is not
+set the public helpers raise ``StripeNotConfiguredError`` which the server
+layer translates into 503 Service Unavailable.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import secrets
+import uuid
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Sentinel exception
+# ---------------------------------------------------------------------------
+
+
+class StripeNotConfiguredError(RuntimeError):
+    """Raised when STRIPE_SECRET_KEY is absent and a Stripe feature is requested."""
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_stripe():
+    """Return the ``stripe`` module, configured with the secret key.
+
+    Raises:
+        StripeNotConfiguredError: if ``STRIPE_SECRET_KEY`` is not set.
+        ImportError: if the ``stripe`` package is not installed.
+    """
+    secret_key = os.environ.get("STRIPE_SECRET_KEY", "")
+    if not secret_key:
+        raise StripeNotConfiguredError(
+            "STRIPE_SECRET_KEY is not set. Billing features are disabled."
+        )
+
+    import stripe  # noqa: PLC0415
+
+    stripe.api_key = secret_key
+    return stripe
+
+
+# ---------------------------------------------------------------------------
+# API key generation
+# ---------------------------------------------------------------------------
+
+
+def generate_api_key() -> tuple[str, str, str]:
+    """Generate a new API key in ``nat_pk_<32-hex>`` format.
+
+    Returns:
+        A 3-tuple of ``(plaintext_key, key_hash, key_prefix)`` where:
+        - ``plaintext_key`` is the full key shown *once* to the customer.
+        - ``key_hash`` is the SHA-256 hex digest stored in the database.
+        - ``key_prefix`` is the first 8 characters of the plaintext key
+          (e.g. ``nat_pk_a``) used for display/identification.
+    """
+    random_hex = secrets.token_hex(32)  # 64 hex chars — 32 bytes of entropy
+    plaintext_key = f"nat_pk_{random_hex}"
+    key_hash = hashlib.sha256(plaintext_key.encode()).hexdigest()
+    key_prefix = plaintext_key[:8]
+    return plaintext_key, key_hash, key_prefix
+
+
+# ---------------------------------------------------------------------------
+# Stripe Checkout
+# ---------------------------------------------------------------------------
+
+
+def create_checkout_session(
+    plan_tier: str,
+    success_url: str,
+    cancel_url: str,
+    module_addons: list[str] | None = None,
+) -> str:
+    """Create a Stripe Checkout Session for the given plan tier.
+
+    Args:
+        plan_tier: One of ``"pro"``, ``"team"``, or ``"enterprise"``.
+        success_url: URL Stripe redirects to after successful payment.
+        cancel_url: URL Stripe redirects to if the customer cancels.
+        module_addons: Optional list of scan module names to include as
+                       add-on line items (e.g. ``["visual", "performance"]``).
+                       Each module must have a configured
+                       ``STRIPE_PRICE_ID_<MODULE>`` env var.
+
+    Returns:
+        The Stripe Checkout Session URL.
+
+    Raises:
+        StripeNotConfiguredError: if ``STRIPE_SECRET_KEY`` is not set.
+        ValueError: if the plan tier has no configured Stripe price ID, or if
+                    a requested module add-on has no configured price ID.
+    """
+    from mannf.product.billing.plans import get_plan, get_module_price_id  # noqa: PLC0415
+
+    stripe = _get_stripe()
+
+    plan = get_plan(plan_tier)
+    if not plan.stripe_price_id:
+        raise ValueError(
+            f"No Stripe price ID configured for plan '{plan_tier}'. "
+            f"Set the STRIPE_PRICE_ID_{plan_tier.upper()} environment variable."
+        )
+
+    line_items: list[dict] = [{"price": plan.stripe_price_id, "quantity": 1}]
+
+    addons = module_addons or []
+    for module in addons:
+        price_id = get_module_price_id(module)
+        if not price_id:
+            raise ValueError(
+                f"No Stripe price ID configured for module add-on '{module}'. "
+                f"Set the STRIPE_PRICE_ID_{module.upper()} environment variable."
+            )
+        line_items.append({"price": price_id, "quantity": 1})
+
+    session = stripe.checkout.Session.create(
+        mode="subscription",
+        line_items=line_items,
+        success_url=success_url,
+        cancel_url=cancel_url,
+        metadata={
+            "plan_tier": plan_tier,
+            "plan_name": plan.display_name,
+            "product_id": plan.stripe_product_id or "",
+            "module_addons": ",".join(addons),
+        },
+    )
+    return session.url
+
+
+# ---------------------------------------------------------------------------
+# Stripe Customer Portal
+# ---------------------------------------------------------------------------
+
+
+def create_portal_session(stripe_customer_id: str, return_url: str) -> str:
+    """Create a Stripe Customer Portal session for subscription management.
+
+    Args:
+        stripe_customer_id: The ``cus_…`` customer ID stored on the tenant.
+        return_url: URL to redirect to after the portal session ends.
+
+    Returns:
+        The Stripe Customer Portal session URL.
+
+    Raises:
+        StripeNotConfiguredError: if ``STRIPE_SECRET_KEY`` is not set.
+    """
+    stripe = _get_stripe()
+
+    session = stripe.billing_portal.Session.create(
+        customer=stripe_customer_id,
+        return_url=return_url,
+    )
+    return session.url
+
+
+# ---------------------------------------------------------------------------
+# Webhook handler
+# ---------------------------------------------------------------------------
+
+
+def handle_webhook_event(payload: bytes, sig_header: str) -> dict[str, Any]:
+    """Verify and dispatch a Stripe webhook event.
+
+    The function verifies the signature using ``STRIPE_WEBHOOK_SECRET``, then
+    handles the following event types:
+
+    - ``checkout.session.completed`` — creates a Tenant and ApiKey in the DB
+    - ``customer.subscription.updated`` — updates the tenant's plan tier
+    - ``customer.subscription.deleted`` — deactivates the tenant
+
+    Args:
+        payload: The raw request body bytes from Stripe.
+        sig_header: The value of the ``Stripe-Signature`` HTTP header.
+
+    Returns:
+        A dict describing the action taken, e.g.
+        ``{"action": "tenant_created", "tenant_id": "…"}``.
+
+    Raises:
+        StripeNotConfiguredError: if ``STRIPE_SECRET_KEY`` is not set.
+        stripe.error.SignatureVerificationError: if the signature is invalid.
+    """
+    stripe = _get_stripe()
+
+    webhook_secret = os.environ.get("STRIPE_WEBHOOK_SECRET", "")
+    if not webhook_secret:
+        raise StripeNotConfiguredError(
+            "STRIPE_WEBHOOK_SECRET is not set. Webhook signature verification is disabled."
+        )
+
+    event = stripe.Webhook.construct_event(payload, sig_header, webhook_secret)
+
+    event_type: str = event["type"]
+    event_data: dict = event["data"]["object"]
+
+    logger.info("Received Stripe webhook event: %s", event_type)
+
+    if event_type == "checkout.session.completed":
+        return _handle_checkout_completed(event_data)
+    elif event_type == "customer.subscription.updated":
+        return _handle_subscription_updated(event_data)
+    elif event_type == "customer.subscription.deleted":
+        return _handle_subscription_deleted(event_data)
+    elif event_type == "invoice.payment_failed":
+        return _handle_payment_failed(event_data)
+    elif event_type == "invoice.paid":
+        return _handle_invoice_paid(event_data)
+    elif event_type == "charge.refunded":
+        return _handle_charge_refunded(event_data)
+    else:
+        return {"action": "ignored", "event_type": event_type}
+
+
+# ---------------------------------------------------------------------------
+# Private event handlers (synchronous DB writes via asyncio.run or direct)
+# ---------------------------------------------------------------------------
+
+
+def _handle_checkout_completed(session_data: dict) -> dict[str, Any]:
+    """Handle ``checkout.session.completed`` — provision Tenant + ApiKey.
+
+    Idempotent: if a Tenant with this ``stripe_customer_id`` already exists
+    (e.g. created by the sync endpoint), the plan and quotas are updated
+    instead of creating a duplicate.
+    """
+    import asyncio  # noqa: PLC0415
+
+    customer_id: str = session_data.get("customer", "")
+    customer_email: str = session_data.get("customer_details", {}).get("email", "")
+    customer_name: str = session_data.get("customer_details", {}).get("name", "") or customer_email
+    subscription_id: str = session_data.get("subscription", "")
+    metadata: dict = session_data.get("metadata", {})
+    plan_tier: str = metadata.get("plan_tier", "free")
+    module_addons_raw: str = metadata.get("module_addons", "")
+    module_addons: list[str] = [m for m in module_addons_raw.split(",") if m]
+
+    plaintext_key, key_hash, key_prefix = generate_api_key()
+
+    coro = _upsert_tenant_from_checkout(
+        customer_id=customer_id,
+        customer_email=customer_email,
+        customer_name=customer_name,
+        subscription_id=subscription_id,
+        plan_tier=plan_tier,
+        key_hash=key_hash,
+        key_prefix=key_prefix,
+        module_addons=module_addons,
+    )
+    try:
+        asyncio.get_running_loop()
+        # Running inside an async context (e.g. FastAPI) — schedule as task
+        asyncio.ensure_future(coro)
+        asyncio.ensure_future(_log_checkout_event(customer_id, customer_email, plan_tier))
+    except RuntimeError:
+        # No running event loop — drive synchronously
+        try:
+            asyncio.run(coro)
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Failed to create tenant from checkout: %s", exc)
+
+    return {
+        "action": "tenant_created",
+        "customer_id": customer_id,
+        "plan_tier": plan_tier,
+        "api_key_prefix": key_prefix,
+        "plaintext_key": plaintext_key,
+        "module_addons": module_addons,
+    }
+
+
+async def _log_checkout_event(customer_id: str, customer_email: str, plan_tier: str) -> None:
+    """Fire-and-forget: log a billing audit event for checkout completion."""
+    from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+
+    tenant_id = await _resolve_tenant_id_by_customer(customer_id)
+    await log_billing_event(
+        "tenant.created",
+        tenant_id=tenant_id,
+        source="stripe",
+        details={
+            "stripe_customer_id": customer_id,
+            "customer_email": customer_email,
+            "plan_tier": plan_tier,
+        },
+    )
+
+
+def _handle_subscription_updated(subscription_data: dict) -> dict[str, Any]:
+    """Handle ``customer.subscription.updated`` — sync plan tier, quotas, and module add-ons."""
+    import asyncio  # noqa: PLC0415
+
+    customer_id: str = subscription_data.get("customer", "")
+    subscription_id: str = subscription_data.get("id", "")
+    # Resolve plan tier from the first item's price metadata or product metadata
+    items = subscription_data.get("items", {}).get("data", [])
+    plan_tier = "free"
+    if items:
+        price_meta = items[0].get("price", {}).get("metadata", {})
+        plan_tier = price_meta.get("plan_tier", "free")
+
+    # Detect module add-ons by matching subscription item product IDs against
+    # MODULE_PRODUCTS.  Items after the first are treated as add-on line items.
+    from mannf.product.billing.plans import MODULE_PRODUCTS  # noqa: PLC0415
+
+    module_addons: list[str] = []
+    for item in items[1:]:
+        product_id = item.get("price", {}).get("product", "")
+        for module_name, module_product_id in MODULE_PRODUCTS.items():
+            if module_product_id and product_id == module_product_id:
+                module_addons.append(module_name)
+
+    logger.info(
+        "Subscription updated: customer=%s subscription=%s new_plan=%s module_addons=%s",
+        customer_id,
+        subscription_id,
+        plan_tier,
+        module_addons,
+    )
+
+    coro = _update_tenant_plan(
+        customer_id,
+        plan_tier,
+        subscription_id=subscription_id,
+        module_addons=module_addons,
+    )
+    try:
+        asyncio.get_running_loop()
+        asyncio.ensure_future(coro)
+        asyncio.ensure_future(_log_subscription_updated_event(customer_id, plan_tier, subscription_id))
+    except RuntimeError:
+        try:
+            asyncio.run(coro)
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Failed to update tenant plan: %s", exc)
+
+    return {
+        "action": "plan_updated",
+        "customer_id": customer_id,
+        "plan_tier": plan_tier,
+        "module_addons": module_addons,
+    }
+
+
+async def _log_subscription_updated_event(
+    customer_id: str, plan_tier: str, subscription_id: str
+) -> None:
+    """Fire-and-forget: log a billing audit event for subscription update."""
+    from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+
+    tenant_id = await _resolve_tenant_id_by_customer(customer_id)
+    await log_billing_event(
+        "plan.changed",
+        tenant_id=tenant_id,
+        source="stripe",
+        details={
+            "stripe_customer_id": customer_id,
+            "stripe_subscription_id": subscription_id,
+            "plan_tier": plan_tier,
+        },
+    )
+
+
+def _handle_subscription_deleted(subscription_data: dict) -> dict[str, Any]:
+    """Handle ``customer.subscription.deleted`` — deactivate tenant."""
+    import asyncio  # noqa: PLC0415
+
+    customer_id: str = subscription_data.get("customer", "")
+
+    coro = _deactivate_tenant(customer_id)
+    try:
+        asyncio.get_running_loop()
+        asyncio.ensure_future(coro)
+        asyncio.ensure_future(_log_subscription_deleted_event(customer_id))
+    except RuntimeError:
+        try:
+            asyncio.run(coro)
+        except Exception as exc:  # noqa: BLE001
+            logger.error("Failed to deactivate tenant: %s", exc)
+
+    return {
+        "action": "tenant_deactivated",
+        "customer_id": customer_id,
+    }
+
+
+async def _log_subscription_deleted_event(customer_id: str) -> None:
+    """Fire-and-forget: log a billing audit event for subscription cancellation."""
+    from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+
+    tenant_id = await _resolve_tenant_id_by_customer(customer_id)
+    await log_billing_event(
+        "subscription.cancelled",
+        tenant_id=tenant_id,
+        source="stripe",
+        details={"stripe_customer_id": customer_id},
+    )
+
+
+def _handle_payment_failed(invoice_data: dict) -> dict[str, Any]:
+    """Handle ``invoice.payment_failed`` — log the event for audit trail.
+
+    Does not immediately deactivate the tenant — Stripe handles retry
+    logic and sends ``customer.subscription.deleted`` after the grace
+    period expires.
+    """
+    import asyncio  # noqa: PLC0415
+
+    customer_id: str = invoice_data.get("customer", "")
+    invoice_id: str = invoice_data.get("id", "")
+    attempt_count: int = invoice_data.get("attempt_count", 0)
+
+    logger.warning(
+        "Payment failed: customer=%s invoice=%s attempt=%d — grace period active",
+        customer_id,
+        invoice_id,
+        attempt_count,
+    )
+
+    try:
+        asyncio.get_running_loop()
+        asyncio.ensure_future(_log_payment_failed_event(customer_id, invoice_id, attempt_count))
+    except RuntimeError:
+        pass
+
+    return {
+        "action": "payment_failed_logged",
+        "customer_id": customer_id,
+        "invoice_id": invoice_id,
+        "attempt_count": attempt_count,
+    }
+
+
+async def _log_payment_failed_event(
+    customer_id: str, invoice_id: str, attempt_count: int
+) -> None:
+    """Fire-and-forget: log a billing audit event for payment failure."""
+    from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+    from mannf.product.billing.notifications import dispatch_billing_notification  # noqa: PLC0415
+
+    tenant_id = await _resolve_tenant_id_by_customer(customer_id)
+    await log_billing_event(
+        "payment.failed",
+        tenant_id=tenant_id,
+        source="stripe",
+        details={
+            "stripe_customer_id": customer_id,
+            "stripe_invoice_id": invoice_id,
+            "attempt_count": attempt_count,
+        },
+    )
+    await dispatch_billing_notification(
+        "payment.failed",
+        tenant_id=tenant_id,
+        details={
+            "stripe_customer_id": customer_id,
+            "stripe_invoice_id": invoice_id,
+            "attempt_count": attempt_count,
+        },
+    )
+
+
+def _handle_invoice_paid(invoice_data: dict) -> dict[str, Any]:
+    """Handle ``invoice.paid`` — log successful payment."""
+    import asyncio  # noqa: PLC0415
+
+    customer_id: str = invoice_data.get("customer", "")
+    invoice_id: str = invoice_data.get("id", "")
+    amount_paid: int = invoice_data.get("amount_paid", 0)
+
+    logger.info(
+        "Invoice paid: customer=%s invoice=%s amount=%d",
+        customer_id,
+        invoice_id,
+        amount_paid,
+    )
+
+    try:
+        asyncio.get_running_loop()
+        asyncio.ensure_future(_log_invoice_paid_event(customer_id, invoice_id, amount_paid))
+    except RuntimeError:
+        pass
+
+    return {
+        "action": "payment_succeeded_logged",
+        "customer_id": customer_id,
+        "invoice_id": invoice_id,
+        "amount_paid": amount_paid,
+    }
+
+
+async def _log_invoice_paid_event(
+    customer_id: str, invoice_id: str, amount_paid: int
+) -> None:
+    """Fire-and-forget: log a billing audit event for successful payment."""
+    from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+
+    tenant_id = await _resolve_tenant_id_by_customer(customer_id)
+    await log_billing_event(
+        "payment.succeeded",
+        tenant_id=tenant_id,
+        source="stripe",
+        details={
+            "stripe_customer_id": customer_id,
+            "stripe_invoice_id": invoice_id,
+            "amount_paid_cents": amount_paid,
+        },
+    )
+
+
+def _handle_charge_refunded(charge_data: dict) -> dict[str, Any]:
+    """Handle ``charge.refunded`` — log refund event."""
+    import asyncio  # noqa: PLC0415
+
+    customer_id: str = charge_data.get("customer", "")
+    charge_id: str = charge_data.get("id", "")
+    amount_refunded: int = charge_data.get("amount_refunded", 0)
+
+    logger.info(
+        "Charge refunded: customer=%s charge=%s amount_refunded=%d",
+        customer_id,
+        charge_id,
+        amount_refunded,
+    )
+
+    try:
+        asyncio.get_running_loop()
+        asyncio.ensure_future(_log_charge_refunded_event(customer_id, charge_id, amount_refunded))
+    except RuntimeError:
+        pass
+
+    return {
+        "action": "charge_refunded_logged",
+        "customer_id": customer_id,
+        "charge_id": charge_id,
+        "amount_refunded": amount_refunded,
+    }
+
+
+async def _log_charge_refunded_event(
+    customer_id: str, charge_id: str, amount_refunded: int
+) -> None:
+    """Fire-and-forget: log a billing audit event for a refund."""
+    from mannf.product.billing.audit import log_billing_event  # noqa: PLC0415
+
+    tenant_id = await _resolve_tenant_id_by_customer(customer_id)
+    await log_billing_event(
+        "charge.refunded",
+        tenant_id=tenant_id,
+        source="stripe",
+        details={
+            "stripe_customer_id": customer_id,
+            "stripe_charge_id": charge_id,
+            "amount_refunded_cents": amount_refunded,
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Async DB helpers
+# ---------------------------------------------------------------------------
+
+
+async def _resolve_tenant_id_by_customer(customer_id: str) -> str | None:
+    """Return the tenant UUID string for a Stripe customer ID, or None."""
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return None
+
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import Tenant  # noqa: PLC0415
+
+        async with _async_session_factory() as session:
+            stmt = select(Tenant.id).where(Tenant.stripe_customer_id == customer_id)
+            result = await session.execute(stmt)
+            row = result.scalar_one_or_none()
+            return str(row) if row else None
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_resolve_tenant_id_by_customer failed: %s", exc)
+        return None
+
+
+async def _create_tenant_and_key(
+    *,
+    customer_id: str,
+    customer_email: str,
+    customer_name: str,
+    subscription_id: str,
+    plan_tier: str,
+    key_hash: str,
+    key_prefix: str,
+) -> None:
+    """Async helper: create a Tenant + ApiKey row in the database."""
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+        from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            logger.warning("No database configured — skipping tenant creation")
+            return
+
+        from mannf.product.models import ApiKey, Tenant  # noqa: PLC0415
+
+        plan = get_plan(plan_tier)
+
+        async with _async_session_factory() as session:
+            tenant = Tenant(
+                id=uuid.uuid4(),
+                name=customer_name,
+                email=customer_email,
+                plan_tier=plan_tier,
+                stripe_customer_id=customer_id,
+                stripe_subscription_id=subscription_id,
+                monthly_scan_quota=plan.monthly_scan_quota,
+                monthly_security_scan_quota=plan.monthly_security_scan_quota,
+                max_concurrent_scans=plan.max_concurrent_scans,
+                is_active=True,
+            )
+            session.add(tenant)
+            await session.flush()
+
+            api_key_obj = ApiKey(
+                id=uuid.uuid4(),
+                tenant_id=tenant.id,
+                key_hash=key_hash,
+                key_prefix=key_prefix,
+                label="Default",
+                is_active=True,
+            )
+            session.add(api_key_obj)
+            await session.commit()
+
+        logger.info(
+            "Created tenant %s (plan=%s) from Stripe checkout", tenant.id, plan_tier
+        )
+    except ImportError:
+        logger.warning("SQLAlchemy models not available — skipping tenant creation")
+    except Exception as exc:  # noqa: BLE001
+        logger.error("_create_tenant_and_key failed: %s", exc)
+
+
+async def _upsert_tenant_from_checkout(
+    *,
+    customer_id: str,
+    customer_email: str,
+    customer_name: str,
+    subscription_id: str,
+    plan_tier: str,
+    key_hash: str,
+    key_prefix: str,
+    module_addons: list[str] | None = None,
+) -> None:
+    """Idempotent checkout completion: update existing tenant or create new one.
+
+    If a Tenant with this ``stripe_customer_id`` already exists (e.g. created
+    by the sync endpoint), update its plan, quotas, and subscription ID.
+    Otherwise, create a new Tenant + ApiKey as ``_create_tenant_and_key`` does.
+    """
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+        from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            logger.warning("No database configured — skipping tenant upsert")
+            return
+
+        from sqlalchemy import select  # noqa: PLC0415
+        from mannf.product.models import ApiKey, Tenant  # noqa: PLC0415
+
+        plan = get_plan(plan_tier)
+        addons = module_addons or []
+
+        async with _async_session_factory() as session:
+            stmt = select(Tenant).where(Tenant.stripe_customer_id == customer_id)
+            result = await session.execute(stmt)
+            existing = result.scalar_one_or_none()
+
+            if existing is not None:
+                # Tenant already exists — update plan, quotas, subscription
+                existing.plan_tier = plan_tier
+                existing.monthly_scan_quota = plan.monthly_scan_quota
+                existing.monthly_security_scan_quota = plan.monthly_security_scan_quota
+                existing.max_concurrent_scans = plan.max_concurrent_scans
+                if subscription_id:
+                    existing.stripe_subscription_id = subscription_id
+                if addons and hasattr(existing, "module_addons"):
+                    existing.module_addons = addons
+                await session.commit()
+                logger.info(
+                    "Updated existing tenant %s (plan=%s, addons=%s) from Stripe checkout",
+                    existing.id,
+                    plan_tier,
+                    addons,
+                )
+            else:
+                # No existing tenant — create Tenant + ApiKey
+                tenant_kwargs: dict = dict(
+                    id=uuid.uuid4(),
+                    name=customer_name,
+                    email=customer_email,
+                    plan_tier=plan_tier,
+                    stripe_customer_id=customer_id,
+                    stripe_subscription_id=subscription_id,
+                    monthly_scan_quota=plan.monthly_scan_quota,
+                    monthly_security_scan_quota=plan.monthly_security_scan_quota,
+                    max_concurrent_scans=plan.max_concurrent_scans,
+                    is_active=True,
+                )
+                tenant = Tenant(**tenant_kwargs)
+                session.add(tenant)
+                await session.flush()
+
+                api_key_obj = ApiKey(
+                    id=uuid.uuid4(),
+                    tenant_id=tenant.id,
+                    key_hash=key_hash,
+                    key_prefix=key_prefix,
+                    label="Default",
+                    is_active=True,
+                )
+                session.add(api_key_obj)
+                await session.commit()
+                logger.info(
+                    "Created tenant %s (plan=%s, addons=%s) from Stripe checkout",
+                    tenant.id,
+                    plan_tier,
+                    addons,
+                )
+    except ImportError:
+        logger.warning("SQLAlchemy models not available — skipping tenant upsert")
+    except Exception as exc:  # noqa: BLE001
+        logger.error("_upsert_tenant_from_checkout failed: %s", exc)
+
+
+async def _update_tenant_plan(
+    customer_id: str,
+    plan_tier: str,
+    *,
+    subscription_id: str = "",
+    module_addons: list[str] | None = None,
+) -> None:
+    """Async helper: update Tenant.plan_tier, quota columns, subscription ID, and module add-ons."""
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return
+
+        from sqlalchemy import select, update  # noqa: PLC0415
+        from mannf.product.models import Tenant  # noqa: PLC0415
+        from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+
+        plan = get_plan(plan_tier)
+        values: dict = {
+            "plan_tier": plan_tier,
+            "monthly_scan_quota": plan.monthly_scan_quota,
+            "monthly_security_scan_quota": plan.monthly_security_scan_quota,
+            "max_concurrent_scans": plan.max_concurrent_scans,
+        }
+        if subscription_id:
+            values["stripe_subscription_id"] = subscription_id
+
+        async with _async_session_factory() as session:
+            # Update base plan fields
+            stmt = (
+                update(Tenant)
+                .where(Tenant.stripe_customer_id == customer_id)
+                .values(**values)
+            )
+            await session.execute(stmt)
+
+            # Update module_addons if the model supports it and addons were provided
+            if module_addons is not None:
+                result = await session.execute(
+                    select(Tenant).where(Tenant.stripe_customer_id == customer_id)
+                )
+                tenant = result.scalar_one_or_none()
+                if tenant is not None and hasattr(tenant, "module_addons"):
+                    tenant.module_addons = module_addons
+
+            await session.commit()
+
+        logger.info(
+            "Updated tenant plan for customer %s to %s (addons=%s)",
+            customer_id,
+            plan_tier,
+            module_addons,
+        )
+    except ImportError:
+        pass
+    except Exception as exc:  # noqa: BLE001
+        logger.error("_update_tenant_plan failed: %s", exc)
+
+
+async def _deactivate_tenant(customer_id: str) -> None:
+    """Async helper: set Tenant.is_active = False."""
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            return
+
+        from sqlalchemy import update  # noqa: PLC0415
+        from mannf.product.models import Tenant  # noqa: PLC0415
+
+        async with _async_session_factory() as session:
+            stmt = (
+                update(Tenant)
+                .where(Tenant.stripe_customer_id == customer_id)
+                .values(is_active=False)
+            )
+            await session.execute(stmt)
+            await session.commit()
+
+        logger.info("Deactivated tenant for customer %s", customer_id)
+    except ImportError:
+        pass
+    except Exception as exc:  # noqa: BLE001
+        logger.error("_deactivate_tenant failed: %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# Free-plan direct signup (no Stripe)
+# ---------------------------------------------------------------------------
+
+
+async def create_free_tenant(name: str, email: str) -> dict[str, Any]:
+    """Create a free-tier Tenant + ApiKey directly (no Stripe needed).
+
+    Returns a dict containing the tenant record and the plaintext API key
+    (shown once).
+
+    Raises:
+        RuntimeError: if the database is not configured.
+    """
+    try:
+        from mannf.product.database import _async_session_factory, _build_engine  # noqa: PLC0415
+
+        if _build_engine() is None or _async_session_factory is None:
+            raise RuntimeError("Database not configured — cannot create tenant")
+
+        from mannf.product.models import ApiKey, Tenant  # noqa: PLC0415
+        from mannf.product.billing.plans import get_plan  # noqa: PLC0415
+
+        plan = get_plan("free")
+        plaintext_key, key_hash, key_prefix = generate_api_key()
+
+        async with _async_session_factory() as session:
+            tenant = Tenant(
+                id=uuid.uuid4(),
+                name=name,
+                email=email,
+                plan_tier="free",
+                monthly_scan_quota=plan.monthly_scan_quota,
+                monthly_security_scan_quota=plan.monthly_security_scan_quota,
+                max_concurrent_scans=plan.max_concurrent_scans,
+                is_active=True,
+            )
+            session.add(tenant)
+            await session.flush()
+
+            api_key_obj = ApiKey(
+                id=uuid.uuid4(),
+                tenant_id=tenant.id,
+                key_hash=key_hash,
+                key_prefix=key_prefix,
+                label="Default",
+                is_active=True,
+            )
+            session.add(api_key_obj)
+            await session.commit()
+
+        logger.info("Created free tenant %s (%s)", tenant.id, email)
+        return {
+            "tenant_id": str(tenant.id),
+            "email": email,
+            "plan": "free",
+            "api_key": plaintext_key,
+        }
+
+    except ImportError as exc:
+        raise RuntimeError("Database models not available") from exc