fastapi-fullstack 0.2.3__tar.gz → 0.2.4__tar.gz

{fastapi_fullstack-0.2.3 → fastapi_fullstack-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastapi-fullstack
-Version: 0.2.3
+Version: 0.2.4
 Summary: Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability.
 Project-URL: Homepage, https://github.com/vstorm-co/full-stack-ai-agent-template
 Project-URL: Documentation, https://github.com/vstorm-co/full-stack-ai-agent-template#readme

{fastapi_fullstack-0.2.3 → fastapi_fullstack-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-fullstack"
-version = "0.2.3"
+version = "0.2.4"
 description = "Full-stack FastAPI + Next.js template generator with PydanticAI/LangChain agents, WebSocket streaming, 20+ enterprise integrations, and Logfire/LangSmith observability. Ship AI apps fast. CLI tool to generate production-ready FastAPI + Next.js projects with AI agents, auth, and observability."
 readme = "README.md"
 requires-python = ">=3.11"

{fastapi_fullstack-0.2.3 → fastapi_fullstack-0.2.4}/template/{{cookiecutter.project_slug}}/backend/app/core/sanitize.py

@@ -3,17 +3,21 @@
 This module provides security-focused input sanitization functions:
 - HTML sanitization to prevent XSS attacks
 - Path traversal prevention for file operations
+- Webhook URL validation to prevent SSRF attacks
 - Common input cleaning utilities
 
 Note: SQL injection is prevented by using SQLAlchemy ORM with parameterized queries.
 """
 
 import html
+import ipaddress
 import os
 import re
+import socket
 import unicodedata
 from pathlib import Path
 from typing import TypeVar
+from urllib.parse import urlparse
 
 # Default allowed HTML tags for rich text content
 DEFAULT_ALLOWED_TAGS = frozenset({
@@ -28,6 +32,23 @@ DEFAULT_ALLOWED_ATTRIBUTES = {
     "acronym": frozenset({"title"}),
 }
 
+# Allowed URL schemes for webhook URLs
+WEBHOOK_ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+# Shared Address Space (RFC 6598) — CGNAT range.
+# Python 3.11+ no longer classifies 100.64.0.0/10 as private or reserved,
+# so we block it explicitly. Covers cloud metadata endpoints like
+# Alibaba Cloud's 100.100.100.200.
+_CGNAT_NETWORK = ipaddress.ip_network("100.64.0.0/10")
+
+
+class SSRFBlockedError(ValueError):
+    """Raised when a URL is blocked by SSRF protection.
+
+    Dedicated exception type to avoid fragile string matching when
+    distinguishing SSRF blocks from other ValueErrors.
+    """
+
 
 def sanitize_html(
     content: str,
@@ -150,6 +171,136 @@ def validate_safe_path(
     return full_path
 
 
+def _is_ip_blocked(ip_str: str) -> bool:
+    """Check if an IP address is private, reserved, loopback, or link-local.
+
+    Args:
+        ip_str: The IP address string to check.
+
+    Returns:
+        True if the address should be blocked, False if it's safe.
+    """
+    try:
+        addr = ipaddress.ip_address(ip_str)
+    except ValueError:
+        # If we can't parse it, block it to be safe
+        return True
+
+    return (
+        addr.is_private
+        or addr.is_reserved
+        or addr.is_loopback
+        or addr.is_link_local
+        or addr.is_multicast
+        or addr.is_unspecified
+        or addr in _CGNAT_NETWORK
+    )
+
+
+def validate_webhook_url(
+    url: str,
+    allowed_schemes: frozenset[str] | None = None,
+) -> str:
+    """Validate a webhook URL to prevent SSRF attacks.
+
+    Checks that the URL:
+    - Uses an allowed scheme (http/https only by default)
+    - Does not contain userinfo (credentials in the URL)
+    - Does not point to private, reserved, loopback, or link-local IP addresses
+    - Resolves via DNS to a public IP (prevents DNS rebinding attacks)
+
+    Args:
+        url: The webhook URL to validate.
+        allowed_schemes: Allowed URL schemes. Defaults to {"http", "https"}.
+
+    Returns:
+        The validated URL string.
+
+    Raises:
+        SSRFBlockedError: If the URL is blocked by SSRF protection.
+        ValueError: If the URL is malformed.
+
+    Example:
+        >>> validate_webhook_url("https://example.com/webhook")
+        "https://example.com/webhook"
+        >>> validate_webhook_url("http://169.254.169.254/latest/meta-data/")
+        Raises SSRFBlockedError
+    """
+    if allowed_schemes is None:
+        allowed_schemes = WEBHOOK_ALLOWED_SCHEMES
+
+    # Parse the URL
+    try:
+        parsed = urlparse(url)
+    except Exception as err:
+        raise ValueError(f"Invalid webhook URL: {url!r}") from err
+
+    # Validate scheme
+    if parsed.scheme not in allowed_schemes:
+        raise SSRFBlockedError(
+            f"URL scheme {parsed.scheme!r} is not allowed. "
+            f"Allowed schemes: {', '.join(sorted(allowed_schemes))}"
+        )
+
+    # Extract hostname
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError(f"Invalid webhook URL: no hostname found in {url!r}")
+
+    # Reject URLs with userinfo (credentials) to prevent URL parsing ambiguities
+    # e.g. http://user:pass@host/ or http://foo@169.254.169.254%00@public.com/
+    if parsed.username is not None or parsed.password is not None:
+        raise SSRFBlockedError(
+            "Webhook URL must not contain credentials (userinfo). "
+            "Remove the user:password@ portion from the URL."
+        )
+
+    # Try to parse hostname directly as an IP address
+    try:
+        addr = ipaddress.ip_address(hostname)
+        if _is_ip_blocked(str(addr)):
+            raise SSRFBlockedError(
+                f"Webhook URL blocked: {hostname!r} resolves to a private/internal "
+                f"address. SSRF protection does not allow requests to internal networks."
+            )
+        return url
+    except SSRFBlockedError:
+        raise
+    except ValueError:
+        # Not an IP literal — continue to DNS resolution below
+        pass
+
+    # Determine the correct default port based on the scheme
+    default_port = 443 if parsed.scheme == "https" else 80
+    port = parsed.port or default_port
+
+    # Resolve hostname via DNS and check all returned addresses
+    # TODO: socket.getaddrinfo() is blocking I/O — in async code paths
+    # (PostgreSQL, MongoDB) consider using loop.getaddrinfo() or run_in_executor.
+    try:
+        addr_infos = socket.getaddrinfo(hostname, port, proto=socket.IPPROTO_TCP)
+    except socket.gaierror as err:
+        raise SSRFBlockedError(
+            f"Webhook URL blocked: unable to resolve hostname {hostname!r}"
+        ) from err
+
+    if not addr_infos:
+        raise SSRFBlockedError(
+            f"Webhook URL blocked: hostname {hostname!r} did not resolve to any address"
+        )
+
+    for _family, _type, _proto, _canonname, sockaddr in addr_infos:
+        ip_str = sockaddr[0]
+        if _is_ip_blocked(ip_str):
+            raise SSRFBlockedError(
+                f"Webhook URL blocked: {hostname!r} resolves to private/internal "
+                f"address {ip_str!r}. SSRF protection does not allow requests to "
+                f"internal networks."
+            )
+
+    return url
+
+
 def sanitize_string(
     value: str,
     max_length: int | None = None,

{fastapi_fullstack-0.2.3 → fastapi_fullstack-0.2.4}/template/{{cookiecutter.project_slug}}/backend/app/services/webhook.py

@@ -13,7 +13,8 @@ from uuid import UUID
 import httpx
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.core.exceptions import NotFoundError
+from app.core.exceptions import NotFoundError, ValidationError
+from app.core.sanitize import SSRFBlockedError, validate_webhook_url
 from app.db.models.webhook import Webhook, WebhookDelivery
 from app.repositories import webhook_repo
 from app.schemas.webhook import WebhookCreate, WebhookUpdate
@@ -21,6 +22,14 @@ from app.schemas.webhook import WebhookCreate, WebhookUpdate
 logger = logging.getLogger(__name__)
 
 
+def _validate_url_or_raise_422(url: str) -> str:
+    """Validate a webhook URL; convert SSRF/ValueError into ValidationError (422)."""
+    try:
+        return validate_webhook_url(url)
+    except (SSRFBlockedError, ValueError) as exc:
+        raise ValidationError(message=str(exc)) from exc
+
+
 class WebhookService:
     """Service for webhook management and delivery."""
 
@@ -33,6 +42,9 @@ class WebhookService:
         user_id: UUID | None = None,
     ) -> Webhook:
         """Create a new webhook subscription."""
+        # Validate URL against SSRF before storing
+        _validate_url_or_raise_422(str(data.url))
+
         # Generate a secure secret for HMAC signing
         secret = secrets.token_urlsafe(32)
 
@@ -70,6 +82,10 @@ class WebhookService:
         data: WebhookUpdate,
     ) -> Webhook:
         """Update a webhook."""
+        # Validate new URL against SSRF if provided
+        if data.url is not None:
+            _validate_url_or_raise_422(str(data.url))
+
         webhook = await self.get_webhook(webhook_id)
         return await webhook_repo.update(self.db, webhook, data)
 
@@ -129,6 +145,9 @@ class WebhookService:
         payload: dict,
     ) -> dict:
         """Deliver a payload to a webhook with HMAC signature."""
+        # Re-validate URL at delivery time to prevent DNS rebinding attacks
+        _validate_url_or_raise_422(webhook.url)
+
         payload_json = json.dumps(payload, default=str)
 
         # Create HMAC signature
@@ -149,6 +168,9 @@ class WebhookService:
         await self.db.flush()
 
         try:
+            # SECURITY: follow_redirects defaults to False in httpx.
+            # Do NOT enable it — redirects could bypass SSRF validation
+            # by redirecting to an internal IP after the URL check passes.
             async with httpx.AsyncClient(timeout=30.0) as client:
                 response = await client.post(
                     webhook.url,
@@ -229,7 +251,8 @@ from datetime import UTC, datetime
 import httpx
 from sqlalchemy.orm import Session as DBSession
 
-from app.core.exceptions import NotFoundError
+from app.core.exceptions import NotFoundError, ValidationError
+from app.core.sanitize import SSRFBlockedError, validate_webhook_url
 from app.db.models.webhook import Webhook, WebhookDelivery
 from app.repositories import webhook_repo
 from app.schemas.webhook import WebhookCreate, WebhookUpdate
@@ -237,6 +260,14 @@ from app.schemas.webhook import WebhookCreate, WebhookUpdate
 logger = logging.getLogger(__name__)
 
 
+def _validate_url_or_raise_422(url: str) -> str:
+    """Validate a webhook URL; convert SSRF/ValueError into ValidationError (422)."""
+    try:
+        return validate_webhook_url(url)
+    except (SSRFBlockedError, ValueError) as exc:
+        raise ValidationError(message=str(exc)) from exc
+
+
 class WebhookService:
     """Service for webhook management and delivery."""
 
@@ -249,6 +280,9 @@ class WebhookService:
         user_id: str | None = None,
     ) -> Webhook:
         """Create a new webhook subscription."""
+        # Validate URL against SSRF before storing
+        _validate_url_or_raise_422(str(data.url))
+
         secret = secrets.token_urlsafe(32)
 
         return webhook_repo.create(
@@ -285,6 +319,10 @@ class WebhookService:
         data: WebhookUpdate,
     ) -> Webhook:
         """Update a webhook."""
+        # Validate new URL against SSRF if provided
+        if data.url is not None:
+            _validate_url_or_raise_422(str(data.url))
+
         webhook = self.get_webhook(webhook_id)
         return webhook_repo.update(self.db, webhook, data)
 
@@ -323,6 +361,9 @@ class WebhookService:
         payload: dict,
     ) -> dict:
         """Deliver a payload to a webhook with HMAC signature."""
+        # Re-validate URL at delivery time to prevent DNS rebinding attacks
+        _validate_url_or_raise_422(webhook.url)
+
         payload_json = json.dumps(payload, default=str)
         signature = self._create_signature(webhook.secret, payload_json)
 
@@ -341,6 +382,9 @@ class WebhookService:
         self.db.flush()
 
         try:
+            # SECURITY: follow_redirects defaults to False in httpx.
+            # Do NOT enable it — redirects could bypass SSRF validation
+            # by redirecting to an internal IP after the URL check passes.
             with httpx.Client(timeout=30.0) as client:
                 response = client.post(
                     webhook.url,
@@ -399,7 +443,8 @@ from datetime import UTC, datetime
 
 import httpx
 
-from app.core.exceptions import NotFoundError
+from app.core.exceptions import NotFoundError, ValidationError
+from app.core.sanitize import SSRFBlockedError, validate_webhook_url
 from app.db.models.webhook import Webhook, WebhookDelivery
 from app.repositories import webhook_repo
 from app.schemas.webhook import WebhookCreate, WebhookUpdate
@@ -407,6 +452,14 @@ from app.schemas.webhook import WebhookCreate, WebhookUpdate
 logger = logging.getLogger(__name__)
 
 
+def _validate_url_or_raise_422(url: str) -> str:
+    """Validate a webhook URL; convert SSRF/ValueError into ValidationError (422)."""
+    try:
+        return validate_webhook_url(url)
+    except (SSRFBlockedError, ValueError) as exc:
+        raise ValidationError(message=str(exc)) from exc
+
+
 class WebhookService:
     """Service for webhook management and delivery."""
 
@@ -416,6 +469,9 @@ class WebhookService:
         user_id: str | None = None,
     ) -> Webhook:
         """Create a new webhook subscription."""
+        # Validate URL against SSRF before storing
+        _validate_url_or_raise_422(str(data.url))
+
         secret = secrets.token_urlsafe(32)
 
         return await webhook_repo.create(
@@ -449,6 +505,10 @@ class WebhookService:
         data: WebhookUpdate,
     ) -> Webhook:
         """Update a webhook."""
+        # Validate new URL against SSRF if provided
+        if data.url is not None:
+            _validate_url_or_raise_422(str(data.url))
+
         webhook = await self.get_webhook(webhook_id)
         return await webhook_repo.update(webhook, data)
 
@@ -487,6 +547,9 @@ class WebhookService:
         payload: dict,
     ) -> dict:
         """Deliver a payload to a webhook with HMAC signature."""
+        # Re-validate URL at delivery time to prevent DNS rebinding attacks
+        _validate_url_or_raise_422(webhook.url)
+
         payload_json = json.dumps(payload, default=str)
         signature = self._create_signature(webhook.secret, payload_json)
 
@@ -504,6 +567,9 @@ class WebhookService:
         await delivery.insert()
 
         try:
+            # SECURITY: follow_redirects defaults to False in httpx.
+            # Do NOT enable it — redirects could bypass SSRF validation
+            # by redirecting to an internal IP after the URL check passes.
             async with httpx.AsyncClient(timeout=30.0) as client:
                 response = await client.post(
                     webhook.url,

fastapi_fullstack-0.2.4/template/{{cookiecutter.project_slug}}/backend/tests/test_ssrf.py

@@ -0,0 +1,207 @@
+"""Tests for SSRF protection in webhook URL validation.
+
+Covers validate_webhook_url() and _is_ip_blocked() from app.core.sanitize.
+"""
+
+from unittest.mock import patch
+
+import pytest
+
+from app.core.sanitize import (
+    SSRFBlockedError,
+    _is_ip_blocked,
+    validate_webhook_url,
+)
+
+
+# ---------------------------------------------------------------------------
+# _is_ip_blocked
+# ---------------------------------------------------------------------------
+
+
+class TestIsIpBlocked:
+    """Tests for the _is_ip_blocked helper."""
+
+    @pytest.mark.parametrize(
+        "ip",
+        [
+            "127.0.0.1",
+            "10.0.0.1",
+            "172.16.0.1",
+            "192.168.1.1",
+            "169.254.169.254",
+            "0.0.0.0",
+            "::1",
+            "fe80::1",
+            "fc00::1",
+            "100.100.100.200",  # CGNAT / Alibaba Cloud metadata
+            "100.64.0.1",  # CGNAT range start (RFC 6598)
+        ],
+    )
+    def test_blocked_ips(self, ip: str):
+        assert _is_ip_blocked(ip) is True
+
+    @pytest.mark.parametrize(
+        "ip",
+        [
+            "8.8.8.8",
+            "1.1.1.1",
+            "93.184.216.34",  # example.com
+            "2606:4700:4700::1111",  # Cloudflare public DNS IPv6
+        ],
+    )
+    def test_allowed_ips(self, ip: str):
+        assert _is_ip_blocked(ip) is False
+
+    def test_unparseable_ip_is_blocked(self):
+        """If we can't parse it, we block it (fail-closed)."""
+        assert _is_ip_blocked("not-an-ip") is True
+
+
+# ---------------------------------------------------------------------------
+# validate_webhook_url — scheme validation
+# ---------------------------------------------------------------------------
+
+
+class TestSchemeValidation:
+    """Blocked schemes must raise SSRFBlockedError."""
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "file:///etc/passwd",
+            "ftp://mirror.example.com/pub",
+            "gopher://evil.com/",
+            "data:text/html,<h1>hi</h1>",
+        ],
+    )
+    def test_blocked_schemes(self, url: str):
+        with pytest.raises(SSRFBlockedError):
+            validate_webhook_url(url)
+
+    def test_empty_scheme_is_rejected(self):
+        with pytest.raises((SSRFBlockedError, ValueError)):
+            validate_webhook_url("://example.com/hook")
+
+
+# ---------------------------------------------------------------------------
+# validate_webhook_url — IP-literal URLs
+# ---------------------------------------------------------------------------
+
+
+class TestDirectIpUrls:
+    """URLs with IP-address hostnames (no DNS involved)."""
+
+    @pytest.mark.parametrize(
+        "url",
+        [
+            "http://127.0.0.1/hook",
+            "https://169.254.169.254/latest/meta-data/",
+            "http://10.0.0.1:8080/callback",
+            "http://192.168.1.1/hook",
+            "http://[::1]/hook",
+            "http://0.0.0.0/hook",
+            "http://100.100.100.200/latest/meta-data/",  # CGNAT / Alibaba metadata
+        ],
+    )
+    def test_private_ip_blocked(self, url: str):
+        with pytest.raises(SSRFBlockedError):
+            validate_webhook_url(url)
+
+    def test_public_ip_allowed(self):
+        """A public IP should pass validation (DNS resolution is skipped)."""
+        url = "https://93.184.216.34/webhook"
+        assert validate_webhook_url(url) == url
+
+
+# ---------------------------------------------------------------------------
+# validate_webhook_url — DNS resolution to private IP
+# ---------------------------------------------------------------------------
+
+
+class TestDnsResolution:
+    """DNS resolving to a private IP must be blocked."""
+
+    def _mock_getaddrinfo_private(self, *args, **kwargs):
+        """Return a private IP for any hostname."""
+        return [
+            (2, 1, 6, "", ("127.0.0.1", 443)),
+        ]
+
+    def _mock_getaddrinfo_public(self, *args, **kwargs):
+        """Return a public IP for any hostname."""
+        return [
+            (2, 1, 6, "", ("93.184.216.34", 443)),
+        ]
+
+    def test_dns_resolves_to_private_ip(self):
+        with (
+            patch("app.core.sanitize.socket.getaddrinfo", self._mock_getaddrinfo_private),
+            pytest.raises(SSRFBlockedError),
+        ):
+            validate_webhook_url("https://evil.attacker.com/hook")
+
+    def test_dns_resolves_to_public_ip(self):
+        with patch("app.core.sanitize.socket.getaddrinfo", self._mock_getaddrinfo_public):
+            result = validate_webhook_url("https://example.com/webhook")
+            assert result == "https://example.com/webhook"
+
+
+# ---------------------------------------------------------------------------
+# validate_webhook_url — edge cases
+# ---------------------------------------------------------------------------
+
+
+class TestEdgeCases:
+    """Edge cases: empty URL, missing hostname, credentials in URL."""
+
+    def test_empty_url(self):
+        with pytest.raises((SSRFBlockedError, ValueError)):
+            validate_webhook_url("")
+
+    def test_no_hostname(self):
+        with pytest.raises(ValueError):
+            validate_webhook_url("https:///path")
+
+    def test_url_with_credentials_rejected(self):
+        """URLs with userinfo (user:pass@) should be rejected."""
+        with pytest.raises(SSRFBlockedError):
+            validate_webhook_url("http://user:pass@internal.example.com/hook")
+
+    def test_url_with_username_only_rejected(self):
+        with pytest.raises(SSRFBlockedError):
+            validate_webhook_url("http://admin@169.254.169.254/")
+
+    def test_allowed_https_url(self):
+        """A normal public URL should pass (mock DNS to avoid network calls)."""
+        with patch(
+            "app.core.sanitize.socket.getaddrinfo",
+            return_value=[(2, 1, 6, "", ("93.184.216.34", 443))],
+        ):
+            result = validate_webhook_url("https://example.com/webhook")
+            assert result == "https://example.com/webhook"
+
+    def test_allowed_http_url(self):
+        """An http:// URL to a public IP should also pass."""
+        with patch(
+            "app.core.sanitize.socket.getaddrinfo",
+            return_value=[(2, 1, 6, "", ("93.184.216.34", 80))],
+        ):
+            result = validate_webhook_url("http://example.com/webhook")
+            assert result == "http://example.com/webhook"
+
+
+# ---------------------------------------------------------------------------
+# SSRFBlockedError is a subclass of ValueError
+# ---------------------------------------------------------------------------
+
+
+class TestSSRFBlockedError:
+    """The dedicated exception type preserves backward compatibility."""
+
+    def test_is_value_error_subclass(self):
+        assert issubclass(SSRFBlockedError, ValueError)
+
+    def test_catchable_as_value_error(self):
+        with pytest.raises(ValueError):
+            raise SSRFBlockedError("blocked")