specforge-api 0.1.4__tar.gz → 0.1.5__tar.gz

{specforge_api-0.1.4 → specforge_api-0.1.5}/.gitignore

@@ -38,3 +38,11 @@ pnpm-debug.log*
 *.swo
 .DS_Store
 Thumbs.db
+
+# Environment & Secrets (SEC-008)
+.env
+.env.*
+*.env
+*.key
+*.pem
+secrets/

{specforge_api-0.1.4 → specforge_api-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: specforge-api
-Version: 0.1.4
+Version: 0.1.5
 Summary: The interactive API client and automated contract testing engine for Python.
 Project-URL: Homepage, https://github.com/specforge-api/specforge
 Project-URL: Documentation, https://specforge-api.github.io/specforge/
@@ -47,7 +47,7 @@ Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: all
 Requires-Dist: fastapi>=0.100.0; extra == 'all'
-Requires-Dist: flask>=2.0.0; extra == 'all'
+Requires-Dist: flask>=2.3.0; extra == 'all'
 Requires-Dist: rich>=13.0.0; extra == 'all'
 Requires-Dist: typer>=0.9.0; extra == 'all'
 Provides-Extra: cli
@@ -66,7 +66,7 @@ Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
 Provides-Extra: fastapi
 Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
 Provides-Extra: flask
-Requires-Dist: flask>=2.0.0; extra == 'flask'
+Requires-Dist: flask>=2.3.0; extra == 'flask'
 Description-Content-Type: text/markdown
 
 # SpecForge ⚡

{specforge_api-0.1.4 → specforge_api-0.1.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specforge-api"
-version = "0.1.4"
+version = "0.1.5"
 description = "The interactive API client and automated contract testing engine for Python."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -43,11 +43,11 @@ dependencies = [
 
 [project.optional-dependencies]
 fastapi = ["fastapi>=0.100.0"]
-flask = ["flask>=2.0.0"]
+flask = ["flask>=2.3.0"]
 cli = ["typer>=0.9.0", "rich>=13.0.0"]
 all = [
     "fastapi>=0.100.0",
-    "flask>=2.0.0",
+    "flask>=2.3.0",
     "typer>=0.9.0",
     "rich>=13.0.0"
 ]

{specforge_api-0.1.4 → specforge_api-0.1.5}/src/specforge/__init__.py

@@ -5,7 +5,7 @@ from specforge.parser.openapi3 import OpenAPIParser
 from specforge.testing.exporters.pytest_export import PytestExporter
 from specforge.testing.planner import TestPlanner
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"
 
 # Conditionally import FastAPI adapter if available
 try:

specforge_api-0.1.5/src/specforge/adapters/fastapi.py

@@ -0,0 +1,116 @@
+"""FastAPI adapter for SpecForge interactive documentation and contract testing."""
+
+from collections.abc import Sequence
+from typing import Any, Optional
+
+try:
+    from fastapi import FastAPI, Request, Response  # type: ignore
+    from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse  # type: ignore
+except ImportError:
+    FastAPI = None  # type: ignore
+
+from specforge.config import SpecForgeConfig
+from specforge.parser.openapi3 import OpenAPIParser
+from specforge.testing.exporters.pytest_export import PytestExporter
+from specforge.testing.planner import TestPlanner
+from specforge.utils.html_injector import render_html
+
+
+class SpecForge:
+    """Mounts the SpecForge interactive client and boundary test suite onto a FastAPI application."""
+
+    def __init__(
+        self,
+        app: Any,
+        path: str = "/docs",
+        title: str = "SpecForge API Studio",
+        spec_url: Optional[str] = None,
+        theme: str = "dark",
+        enable_tests: bool = True,
+        disable_default_docs: bool = False,
+        enable_api_endpoints: bool = True,
+        dependencies: Optional[Sequence[Any]] = None,
+        api_dependencies: Optional[Sequence[Any]] = None,
+        **kwargs: Any,
+    ):
+        if FastAPI is None:
+            raise ImportError(
+                "FastAPI is not installed. Install it with `pip install specforge[fastapi]`."
+            )
+
+        self.app = app
+        self.path = path
+        self.spec_url = spec_url or getattr(app, "openapi_url", "/openapi.json")
+        self.dependencies = list(dependencies) if dependencies else []
+        self.api_dependencies = list(api_dependencies) if api_dependencies is not None else self.dependencies
+
+        self.config = SpecForgeConfig(
+            title=title,
+            path=path,
+            spec_url=self.spec_url,
+            theme=theme,  # type: ignore
+            enable_tests=enable_tests,
+            enable_api_endpoints=enable_api_endpoints,
+            **kwargs,
+        )
+
+        if disable_default_docs and hasattr(app, "docs_url"):
+            app.docs_url = None
+
+        self._register_routes()
+
+    def _register_routes(self) -> None:
+        """Register the documentation UI and test plan endpoints on the FastAPI app."""
+
+        @self.app.get(
+            self.path,
+            response_class=HTMLResponse,
+            include_in_schema=False,
+            dependencies=self.dependencies,
+        )
+        async def specforge_docs_endpoint(request: Request) -> Response:
+            html = render_html(self.config)
+            return HTMLResponse(content=html)
+
+        if self.config.enable_api_endpoints:
+            @self.app.get(
+                "/specforge/api/plan",
+                response_class=JSONResponse,
+                include_in_schema=False,
+                dependencies=self.api_dependencies,
+            )
+            async def specforge_test_plan_endpoint(request: Request) -> Response:
+                # Generate or retrieve active OpenAPI specification
+                raw_spec: dict[str, Any] = self.app.openapi()
+                parser = OpenAPIParser(raw_spec)
+                spec_model = parser.parse()
+
+                plans = []
+                for op in spec_model.operations:
+                    plan = TestPlanner.plan_operation_tests(op)
+                    plans.append(plan.to_dict())
+
+                return JSONResponse(content={"plans": plans})
+
+            @self.app.get(
+                "/specforge/api/export-pytest",
+                response_class=PlainTextResponse,
+                include_in_schema=False,
+                dependencies=self.api_dependencies,
+            )
+            async def specforge_export_pytest_endpoint(request: Request) -> Response:
+                raw_spec: dict[str, Any] = self.app.openapi()
+                parser = OpenAPIParser(raw_spec)
+                spec_model = parser.parse()
+
+                all_test_cases = []
+                for op in spec_model.operations:
+                    plan = TestPlanner.plan_operation_tests(op)
+                    all_test_cases.extend(plan.test_cases)
+
+                base_url = str(request.base_url).rstrip("/")
+                code = PytestExporter.export(all_test_cases, base_url=base_url)
+                return PlainTextResponse(
+                    content=code,
+                    headers={"Content-Disposition": 'attachment; filename="test_api_contracts.py"'},
+                )

{specforge_api-0.1.4 → specforge_api-0.1.5}/src/specforge/adapters/flask.py

@@ -3,7 +3,7 @@
 from typing import Any, Optional
 
 try:
-    from flask import (
+    from flask import (  # type: ignore
         Blueprint,
         Flask,
         Response,
@@ -29,6 +29,7 @@ class SpecForge:
         title: str = "SpecForge API Studio",
         theme: str = "dark",
         enable_tests: bool = True,
+        enable_api_endpoints: bool = True,
         spec_dict: Optional[dict[str, Any]] = None,
         **kwargs: Any,
     ):
@@ -46,6 +47,7 @@ class SpecForge:
             spec_url=spec_url,
             theme=theme,  # type: ignore
             enable_tests=enable_tests,
+            enable_api_endpoints=enable_api_endpoints,
             **kwargs,
         )
 
@@ -60,19 +62,20 @@ class SpecForge:
             html = render_html(self.config, self.spec_dict)
             return Response(html, mimetype="text/html")
 
-        @bp.route("/specforge/api/plan", methods=["GET"])
-        def specforge_plan() -> Any:
-            if not self.spec_dict:
-                return jsonify({"error": "SpecForge Flask adapter requires spec_dict for test planning."}), 400
+        if self.config.enable_api_endpoints:
+            @bp.route("/specforge/api/plan", methods=["GET"])
+            def specforge_plan() -> Any:
+                if not self.spec_dict:
+                    return jsonify({"error": "SpecForge Flask adapter requires spec_dict for test planning."}), 400
 
-            parser = OpenAPIParser(self.spec_dict)
-            spec_model = parser.parse()
+                parser = OpenAPIParser(self.spec_dict)
+                spec_model = parser.parse()
 
-            plans = []
-            for op in spec_model.operations:
-                plan = TestPlanner.plan_operation_tests(op)
-                plans.append(plan.to_dict())
+                plans = []
+                for op in spec_model.operations:
+                    plan = TestPlanner.plan_operation_tests(op)
+                    plans.append(plan.to_dict())
 
-            return jsonify({"plans": plans})
+                return jsonify({"plans": plans})
 
         self.app.register_blueprint(bp)

{specforge_api-0.1.4 → specforge_api-0.1.5}/src/specforge/cli/main.py

@@ -1,9 +1,12 @@
 """Command-line interface for SpecForge."""
 
 import argparse
+import ipaddress
 import json
+import socket
 import sys
 import time
+import urllib.parse
 import urllib.request
 from pathlib import Path
 from typing import Any
@@ -15,17 +18,82 @@ from specforge.testing.exporters.pytest_export import PytestExporter
 from specforge.testing.invariants import TestStatus, evaluate_test_result
 from specforge.testing.planner import TestPlanner
 
+MAX_SPEC_SIZE = 10 * 1024 * 1024  # 10 MB maximum specification size
+DEFAULT_FETCH_TIMEOUT = 30.0  # seconds
+
+# Blocked metadata and link-local networks to mitigate cloud metadata SSRF
+BLOCKED_IP_NETWORKS = (
+    ipaddress.ip_network("169.254.0.0/16"),   # IPv4 Link-local / Cloud metadata (AWS, GCP, Azure, DigitalOcean)
+    ipaddress.ip_network("fd00:ec2::/64"),    # AWS IMDSv6
+    ipaddress.ip_network("fe80::/10"),        # IPv6 Link-local
+    ipaddress.ip_network("224.0.0.0/4"),      # Multicast
+    ipaddress.ip_network("ff00::/8"),         # IPv6 Multicast
+)
+
+
+def _validate_spec_url(url: str) -> None:
+    """Validate that a URL uses supported schemes and does not target cloud metadata endpoints."""
+    parsed = urllib.parse.urlparse(url)
+    scheme = parsed.scheme.lower()
+    if scheme not in ("http", "https"):
+        raise ValueError(f"Unsupported URL scheme: {scheme!r}. Only 'http' and 'https' are allowed.")
+
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError(f"Invalid URL: missing hostname in {url!r}")
+
+    # Check if the hostname itself is an IP or resolves to blocked ranges
+    try:
+        ip = ipaddress.ip_address(hostname)
+        for net in BLOCKED_IP_NETWORKS:
+            if ip in net:
+                raise ValueError(f"Access to link-local/cloud metadata address {ip} is blocked for security.")
+    except ValueError as e:
+        if "blocked for security" in str(e):
+            raise
+        # Hostname is a domain name, attempt address lookup
+        try:
+            addr_info = socket.getaddrinfo(hostname, None)
+            for res in addr_info:
+                ip = ipaddress.ip_address(res[4][0])
+                for net in BLOCKED_IP_NETWORKS:
+                    if ip in net:
+                        raise ValueError(f"URL resolves to blocked link-local/cloud metadata address: {ip}")
+        except socket.gaierror:
+            # DNS resolution errors will be raised cleanly by urlopen
+            pass
+
+
+class _RestrictedRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Enforces scheme and SSRF validation on redirects."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        _validate_spec_url(newurl)
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
 
 def fetch_spec(target: str) -> dict[str, Any]:
     """Load OpenAPI JSON/YAML from a local file or remote HTTP URL."""
-    if target.startswith("http://") or target.startswith("https://"):
+    target_lower = target.lower()
+    if target_lower.startswith(("http://", "https://")):
+        _validate_spec_url(target)
+        opener = urllib.request.build_opener(_RestrictedRedirectHandler)
         req = urllib.request.Request(target, headers={"User-Agent": "SpecForge-CLI"})
-        with urllib.request.urlopen(req) as response:
-            content = response.read().decode("utf-8")
+        with opener.open(req, timeout=DEFAULT_FETCH_TIMEOUT) as response:
+            raw_bytes = response.read(MAX_SPEC_SIZE + 1)
+            if len(raw_bytes) > MAX_SPEC_SIZE:
+                raise ValueError(f"Remote specification exceeds maximum allowed size ({MAX_SPEC_SIZE // (1024 * 1024)} MB).")
+            content = raw_bytes.decode("utf-8")
+    elif "://" in target:
+        scheme = target.split("://", 1)[0]
+        raise ValueError(f"Unsupported URL scheme: {scheme!r}. Only 'http' and 'https' are allowed.")
     else:
+        # Treat as local filesystem path
         path = Path(target)
         if not path.exists():
             raise FileNotFoundError(f"Spec file not found at: {target}")
+        if path.stat().st_size > MAX_SPEC_SIZE:
+            raise ValueError(f"Local specification file exceeds maximum allowed size ({MAX_SPEC_SIZE // (1024 * 1024)} MB).")
         content = path.read_text(encoding="utf-8")
 
     try:
@@ -117,6 +185,9 @@ def run_test_command(args: argparse.Namespace) -> int:
     # Export to pytest if requested
     if args.export_pytest:
         out_path = Path(args.export_pytest)
+        if out_path.exists() and out_path.is_dir():
+            print(f"\n\033[1;31mError: Export path is a directory: {out_path}\033[0m")
+            return 1
         code = PytestExporter.export(all_test_cases, base_url=base_url)
         out_path.write_text(code, encoding="utf-8")
         print(f"\n🐍 \033[32mExported Pytest suite to: {out_path.resolve()}\033[0m")

{specforge_api-0.1.4 → specforge_api-0.1.5}/src/specforge/config.py

@@ -22,6 +22,7 @@ class SpecForgeConfig:
     custom_css: Optional[str] = None
     logo_url: Optional[str] = None
     export_pytest: bool = True
+    enable_api_endpoints: bool = True
 
     def to_dict(self) -> dict[str, Any]:
         """Convert configuration to dictionary for injection into frontend client."""
@@ -39,4 +40,5 @@ class SpecForgeConfig:
             "headers": self.headers,
             "logo_url": self.logo_url,
             "export_pytest": self.export_pytest,
+            "enable_api_endpoints": self.enable_api_endpoints,
         }

{specforge_api-0.1.4 → specforge_api-0.1.5}/src/specforge/testing/exporters/pytest_export.py

@@ -1,7 +1,5 @@
 """Pytest code generator for SpecForge test plans."""
 
-import json
-
 from specforge.testing.invariants import TestCase
 
 
@@ -19,19 +17,18 @@ class PytestExporter:
         cases_repr: list[str] = []
 
         for tc in test_cases:
-            payload_json = json.dumps(tc.payload) if tc.payload is not None else "None"
-            query_json = json.dumps(tc.query_params) if tc.query_params else "None"
-            desc_escaped = tc.description.replace('"', '\\"')
+            payload_repr = repr(tc.payload)
+            query_repr = repr(tc.query_params)
 
             case_str = (
                 f'    (\n'
-                f'        "{tc.endpoint}",\n'
-                f'        "{tc.method.upper()}",\n'
-                f'        {payload_json},\n'
-                f'        {query_json},\n'
+                f'        {repr(tc.endpoint)},\n'
+                f'        {repr(tc.method.upper())},\n'
+                f'        {payload_repr},\n'
+                f'        {query_repr},\n'
                 f'        {tc.expected_status},\n'
                 f'        {tc.is_negative_test},\n'
-                f'        "{desc_escaped}",\n'
+                f'        {repr(tc.description)},\n'
                 f'    ),'
             )
             cases_repr.append(case_str)
@@ -43,7 +40,7 @@ class PytestExporter:
 import pytest
 import httpx
 
-BASE_URL = "{base_url}"
+BASE_URL = {repr(base_url)}
 
 @pytest.mark.parametrize(
     "endpoint,method,payload,query_params,expected_status,is_negative,description",

{specforge_api-0.1.4 → specforge_api-0.1.5}/src/specforge/testing/invariants.py

@@ -1,5 +1,7 @@
 """Test invariants, status evaluations, and result data structures."""
 
+import json
+import shlex
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
@@ -153,18 +155,16 @@ def evaluate_test_result(
 
 
 def build_curl_command(test_case: TestCase, base_url: str = "http://localhost:8000") -> str:
-    """Generate a clean cURL reproduction command for a test case."""
-    import json
-
+    """Generate a clean, shell-escaped cURL reproduction command for a test case."""
     url = f"{base_url.rstrip('/')}{test_case.endpoint}"
-    cmd_parts = [f"curl -X {test_case.method.upper()} '{url}'"]
+    cmd_parts = [f"curl -X {shlex.quote(test_case.method.upper())} {shlex.quote(url)}"]
 
     for h_name, h_val in test_case.headers.items():
-        cmd_parts.append(f"-H '{h_name}: {h_val}'")
+        cmd_parts.append(f"-H {shlex.quote(f'{h_name}: {h_val}')}")
 
     if test_case.payload is not None:
         cmd_parts.append("-H 'Content-Type: application/json'")
-        payload_str = json.dumps(test_case.payload).replace("'", "'\\''")
-        cmd_parts.append(f"-d '{payload_str}'")
+        payload_str = json.dumps(test_case.payload)
+        cmd_parts.append(f"-d {shlex.quote(payload_str)}")
 
     return " \\\n  ".join(cmd_parts)

{specforge_api-0.1.4 → specforge_api-0.1.5}/src/specforge/utils/html_injector.py

@@ -12,6 +12,20 @@ def get_asset_html_path() -> Path:
     return Path(__file__).parent.parent / "assets" / "index.html"
 
 
+def _html_safe_json(data: Any) -> str:
+    """Serialize data to JSON safe for embedding in HTML <script> tags.
+
+    Prevents </script> breakout and HTML comment injection by escaping
+    sensitive characters using standard Unicode JSON escape sequences.
+    """
+    return (
+        json.dumps(data)
+        .replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("&", "\\u0026")
+    )
+
+
 def render_html(
     config: SpecForgeConfig,
     spec_dict: Optional[dict[str, Any]] = None,
@@ -31,7 +45,7 @@ def render_html(
     if spec_dict is not None:
         config_data["embedded_spec"] = spec_dict
 
-    config_json = json.dumps(config_data)
+    config_json = _html_safe_json(config_data)
     replacement = f"<script>window.__SPECFORGE_CONFIG__ = {config_json};</script>"
 
     # Replace placeholder or insert into <head>

specforge_api-0.1.4/src/specforge/adapters/fastapi.py

@@ -1,101 +0,0 @@
-"""FastAPI adapter for SpecForge interactive documentation and contract testing."""
-
-from typing import Any, Optional
-
-try:
-    from fastapi import FastAPI, Request, Response
-    from fastapi.responses import HTMLResponse, JSONResponse, PlainTextResponse
-except ImportError:
-    FastAPI = None  # type: ignore
-
-from specforge.config import SpecForgeConfig
-from specforge.parser.openapi3 import OpenAPIParser
-from specforge.testing.exporters.pytest_export import PytestExporter
-from specforge.testing.planner import TestPlanner
-from specforge.utils.html_injector import render_html
-
-
-class SpecForge:
-    """Mounts the SpecForge interactive client and boundary test suite onto a FastAPI application."""
-
-    def __init__(
-        self,
-        app: Any,
-        path: str = "/docs",
-        title: str = "SpecForge API Studio",
-        spec_url: Optional[str] = None,
-        theme: str = "dark",
-        enable_tests: bool = True,
-        disable_default_docs: bool = False,
-        **kwargs: Any,
-    ):
-        if FastAPI is None:
-            raise ImportError(
-                "FastAPI is not installed. Install it with `pip install specforge[fastapi]`."
-            )
-
-        self.app = app
-        self.path = path
-        self.spec_url = spec_url or getattr(app, "openapi_url", "/openapi.json")
-
-        self.config = SpecForgeConfig(
-            title=title,
-            path=path,
-            spec_url=self.spec_url,
-            theme=theme,  # type: ignore
-            enable_tests=enable_tests,
-            **kwargs,
-        )
-
-        if disable_default_docs and hasattr(app, "docs_url"):
-            app.docs_url = None
-
-        self._register_routes()
-
-    def _register_routes(self) -> None:
-        """Register the documentation UI and test plan endpoints on the FastAPI app."""
-
-        @self.app.get(self.path, response_class=HTMLResponse, include_in_schema=False)
-        async def specforge_docs_endpoint(request: Request) -> Response:
-            html = render_html(self.config)
-            return HTMLResponse(content=html)
-
-        @self.app.get(
-            "/specforge/api/plan",
-            response_class=JSONResponse,
-            include_in_schema=False,
-        )
-        async def specforge_test_plan_endpoint(request: Request) -> Response:
-            # Generate or retrieve active OpenAPI specification
-            raw_spec: dict[str, Any] = self.app.openapi()
-            parser = OpenAPIParser(raw_spec)
-            spec_model = parser.parse()
-
-            plans = []
-            for op in spec_model.operations:
-                plan = TestPlanner.plan_operation_tests(op)
-                plans.append(plan.to_dict())
-
-            return JSONResponse(content={"plans": plans})
-
-        @self.app.get(
-            "/specforge/api/export-pytest",
-            response_class=PlainTextResponse,
-            include_in_schema=False,
-        )
-        async def specforge_export_pytest_endpoint(request: Request) -> Response:
-            raw_spec: dict[str, Any] = self.app.openapi()
-            parser = OpenAPIParser(raw_spec)
-            spec_model = parser.parse()
-
-            all_test_cases = []
-            for op in spec_model.operations:
-                plan = TestPlanner.plan_operation_tests(op)
-                all_test_cases.extend(plan.test_cases)
-
-            base_url = str(request.base_url).rstrip("/")
-            code = PytestExporter.export(all_test_cases, base_url=base_url)
-            return PlainTextResponse(
-                content=code,
-                headers={"Content-Disposition": 'attachment; filename="test_api_contracts.py"'},
-            )