apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/frameworks/js/__init__.py

@@ -0,0 +1,8 @@
+"""JavaScript/TypeScript framework plugins."""
+
+from .express_plugin import ExpressPlugin
+from .fastify_plugin import FastifyPlugin  # noqa: F401 — triggers registration
+from .graphql_plugin import JavaScriptGraphQLPlugin
+from .nestjs_plugin import NestJSPlugin
+
+__all__ = ["ExpressPlugin", "FastifyPlugin", "JavaScriptGraphQLPlugin", "NestJSPlugin"]

apisec_code_bolt/frameworks/js/express_plugin.py

@@ -0,0 +1,391 @@
+"""
+Express.js framework plugin.
+
+Extracts HTTP routes registered via express.Router() and app.get/post/etc.
+Handles:
+- Direct method calls: app.get('/path', handler)
+- Router instance: router.post('/path', handler)
+- Path parameters: /users/:id → /users/{id}
+- Cross-file prefix from url_prefix_map (populated by url_prefix_resolver)
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import TYPE_CHECKING, Any
+
+from ...core.types import (
+    AuthDependencyType,
+    AuthSchemeType,
+    CodeLocation,
+    Confidence,
+    Framework,
+    HttpMethod,
+    Language,
+    ParameterLocation,
+    QualifiedName,
+)
+from ...parsing.base import ParsedFile
+from ..base import (
+    BaseFrameworkPlugin,
+    ExtractedAuthDependency,
+    ExtractedAuthScheme,
+    ExtractedDependency,
+    ExtractedMiddleware,
+    ExtractedParameter,
+    ExtractedRoute,
+    FrameworkPluginRegistry,
+)
+
+if TYPE_CHECKING:
+    from ...parsing.services import AnalysisContext
+
+logger = logging.getLogger(__name__)
+
+# HTTP methods handled by Express router
+_EXPRESS_HTTP_METHODS: frozenset[str] = frozenset(
+    {
+        "get",
+        "post",
+        "put",
+        "patch",
+        "delete",
+        "options",
+        "head",
+        "all",
+    }
+)
+
+# Regex to convert Express :param to {param}
+_PARAM_RE = re.compile(r":([A-Za-z_]\w*)")
+
+# ── Auth detection constants ──────────────────────────────────────────────────
+
+# Module names (or fragments) that indicate JWT auth
+_JWT_MODULE_HINTS = (
+    "jsonwebtoken",
+    "express-jwt",
+    "passport-jwt",
+    "jwt-simple",
+)
+
+# Variable/import name substrings that indicate an auth middleware
+_AUTH_MIDDLEWARE_HINTS = (
+    "auth",
+    "authentication",
+    "authorize",
+    "authorization",
+    "jwt",
+    "passport",
+    "token",
+    "apikey",
+    "api_key",
+    "bearer",
+    "security",
+    "verify",
+    "guard",
+)
+
+# Variable name substrings that indicate API key middleware
+_API_KEY_HINTS = ("apikey", "api_key", "apikeyrepo", "header.api_key")
+
+# Call names that indicate JWT operations
+_JWT_CALL_HINTS = ("jwt.verify", "jwt.sign", "jwt.decode", "jwt.validate", "JWT.validate")
+
+
+def _colon_to_curly(path: str) -> str:
+    """Convert Express-style :param to OpenAPI-style {param}."""
+    return _PARAM_RE.sub(r"{\1}", path)
+
+
+def _extract_path_params(path: str) -> list[ExtractedParameter]:
+    """Extract path parameters from a route path string."""
+    return [
+        ExtractedParameter(name=m.group(1), location=ParameterLocation.PATH)
+        for m in _PARAM_RE.finditer(path)
+    ]
+
+
+class ExpressPlugin(BaseFrameworkPlugin):
+    """
+    Framework plugin for Express.js.
+
+    Detects Express usage and extracts route definitions from
+    router.get/post/put/delete/patch/options/head/all() calls.
+    """
+
+    FRAMEWORK = Framework.EXPRESS
+    LANGUAGE = Language.JAVASCRIPT
+    DETECTION_IMPORTS: frozenset[str] = frozenset({"express"})
+
+    def detect(self, parsed_file: ParsedFile) -> bool:
+        """Detect Express by looking for 'express' in imports."""
+        for imp in parsed_file.imports:
+            if imp.module == "express" or imp.module.startswith("express/"):
+                return True
+            # require('express') parsed as an import with module='express'
+            for name in imp.names:
+                if name == "express":
+                    return True
+        return False
+
+    def extract_routes(
+        self,
+        parsed_file: ParsedFile,
+        context: AnalysisContext | None = None,
+    ) -> list[ExtractedRoute]:
+        """Extract Express route registrations from call sites."""
+        routes: list[ExtractedRoute] = []
+
+        # Get per-file prefix from cross-file prefix map (if available)
+        file_prefix = ""
+        if context and context.language_services:
+            prefix_map = context.language_services.get("_url_prefix_map")
+            if prefix_map:
+                # Use resolved path so symlinks (e.g. /var→/private/var on macOS)
+                # don't cause mismatches with the resolver's map keys.
+                file_key = str(parsed_file.path.resolve())
+                prefixes = prefix_map.get(file_key, [])
+                if prefixes:
+                    file_prefix = prefixes[0]  # Use the first prefix
+
+        for call in parsed_file.call_sites:
+            if not call.is_method_call:
+                continue
+
+            method_lower = call.callee_name.lower()
+            if method_lower not in _EXPRESS_HTTP_METHODS:
+                continue
+
+            # First argument must be a string literal (the path)
+            if not call.arguments:
+                continue
+
+            path_arg = call.arguments[0]
+            if not path_arg.is_literal or not isinstance(path_arg.literal_value, str):
+                continue
+
+            raw_path = path_arg.literal_value
+            path = _colon_to_curly(raw_path)
+
+            # Apply file-level prefix
+            if file_prefix:
+                path = file_prefix.rstrip("/") + "/" + path.lstrip("/")
+
+            # Normalize double slashes and strip trailing slash (except root)
+            path = re.sub(r"/+", "/", path)
+            if not path.startswith("/"):
+                path = "/" + path
+            if path != "/" and path.endswith("/"):
+                path = path.rstrip("/")
+
+            # Get handler name from second argument (variable or arrow function)
+            handler_name = "<anonymous>"
+            if len(call.arguments) > 1:
+                handler_arg = call.arguments[1]
+                if handler_arg.is_variable and handler_arg.variable_name:
+                    handler_name = handler_arg.variable_name
+                elif handler_arg.is_expression and handler_arg.expression_text:
+                    handler_name = "<arrow>"
+
+            # HTTP method
+            http_method = _method_from_str(method_lower)
+
+            # Path params (from original raw path)
+            path_params = _extract_path_params(raw_path)
+
+            routes.append(
+                ExtractedRoute(
+                    method=http_method,
+                    path=path,
+                    handler_function=QualifiedName(
+                        module=parsed_file.path.stem,
+                        name=handler_name,
+                    ),
+                    handler_location=call.location,
+                    path_params=path_params,
+                )
+            )
+
+        return routes
+
+    def extract_dependencies(self, parsed_file: ParsedFile) -> list[ExtractedDependency]:
+        return []
+
+    def extract_auth_schemes(self, parsed_file: ParsedFile) -> list[ExtractedAuthScheme]:
+        """
+        Detect Express auth scheme definitions.
+
+        Covers:
+        - JWT library imports (jsonwebtoken, express-jwt, passport-jwt) → JWT_BEARER
+        - Local JWT class/util imports (files named 'jwt', 'JWT', 'authentication')
+        - API key patterns: imports of local files named 'apikey', 'api-key'
+        - JWT call sites (jwt.verify, JWT.validate) in the file
+        """
+        schemes: list[ExtractedAuthScheme] = []
+        seen: set[str] = set()
+        file_loc = CodeLocation(file=parsed_file.path, line=1)
+
+        def _add(name: str, scheme_type: AuthSchemeType) -> None:
+            if name not in seen:
+                seen.add(name)
+                schemes.append(
+                    ExtractedAuthScheme(
+                        scheme_type=scheme_type,
+                        name=name,
+                        location=file_loc,
+                        confidence=Confidence.HIGH,
+                    )
+                )
+
+        # ── Import-based detection ───────────────────────────────────────────
+        for imp in parsed_file.imports:
+            mod = imp.module.lower()
+            # Third-party JWT packages
+            if any(hint in mod for hint in _JWT_MODULE_HINTS):
+                _add("JwtBearer", AuthSchemeType.JWT_BEARER)
+            # Local module paths that look like JWT/auth utilities
+            elif imp.module.startswith((".", "/")):
+                stem = mod.rsplit("/", 1)[-1]
+                if any(hint in stem for hint in ("jwt", "authentication", "auth")):
+                    _add("JwtBearer", AuthSchemeType.JWT_BEARER)
+                elif any(hint in stem for hint in ("apikey", "api-key", "api_key")):
+                    _add("ApiKey", AuthSchemeType.API_KEY_HEADER)
+            # passport
+            elif mod.startswith("passport"):
+                _add("Passport", AuthSchemeType.JWT_BEARER)
+
+        # ── Call-site-based detection ────────────────────────────────────────
+        for call in parsed_file.call_sites:
+            callee = call.callee_name.lower()
+            if callee in ("verify", "validate", "decode") and call.is_method_call:
+                _add("JwtBearer", AuthSchemeType.JWT_BEARER)
+            elif callee == "authenticate":
+                _add("Passport", AuthSchemeType.JWT_BEARER)
+
+        return schemes
+
+    def extract_auth_dependencies(
+        self,
+        parsed_file: ParsedFile,
+        known_scheme_names: set[str] | None = None,
+        **kwargs: Any,
+    ) -> list[ExtractedAuthDependency]:
+        """
+        Detect Express auth middleware applied via router.use().
+
+        Covers:
+        - router.use(authentication, ...) — JWT auth middleware by variable name
+        - router.use(apikey) — API key middleware by variable name
+        - router.use(authentication, role(RoleCode.WRITER), authorization) — role chain
+        - router.use(role(RoleCode.X)) — extracts role name from role() call
+
+        Auth middleware is identified by name heuristic: variables whose names
+        contain 'auth', 'authentication', 'authorization', 'apikey', 'jwt', etc.
+        Role names are extracted from role(RoleCode.X) call arguments.
+        """
+        deps: list[ExtractedAuthDependency] = []
+
+        # Build set of locally imported names that hint at auth
+        auth_imports: set[str] = set()
+        for imp in parsed_file.imports:
+            mod_lower = imp.module.lower()
+            is_auth_module = any(h in mod_lower for h in _AUTH_MIDDLEWARE_HINTS)
+            for name in imp.names:
+                if is_auth_module or any(h in name.lower() for h in _AUTH_MIDDLEWARE_HINTS):
+                    auth_imports.add(name)
+
+        for call in parsed_file.call_sites:
+            if not call.is_method_call:
+                continue
+            if call.callee_name.lower() != "use":
+                continue
+            if not call.arguments:
+                continue
+
+            # Collect auth middleware names and roles from args
+            middleware_names: list[str] = []
+            requires_roles: list[str] = []
+
+            for arg in call.arguments:
+                if arg.is_variable and arg.variable_name:
+                    vname = arg.variable_name
+                    if (
+                        any(h in vname.lower() for h in _AUTH_MIDDLEWARE_HINTS)
+                        or vname in auth_imports
+                    ):
+                        middleware_names.append(vname)
+                elif arg.is_expression and arg.expression_text:
+                    expr = arg.expression_text
+                    # Detect role(RoleCode.X) or role('X') call
+                    role_match = re.match(r"role\s*\(\s*(?:RoleCode\.)?([A-Za-z_]\w*)\s*\)", expr)
+                    if role_match:
+                        requires_roles.append(role_match.group(1))
+                    # Detect passport.authenticate('strategy')
+                    elif "authenticate" in expr.lower():
+                        strat_match = re.search(r"authenticate\s*\(\s*['\"]([^'\"]+)['\"]", expr)
+                        if strat_match:
+                            middleware_names.append(f"passport:{strat_match.group(1)}")
+                        else:
+                            middleware_names.append("passport")
+                    # Other expression-based middleware with auth hint
+                    elif any(h in expr.lower() for h in _AUTH_MIDDLEWARE_HINTS):
+                        name_hint = expr.split("(")[0].strip()
+                        middleware_names.append(name_hint)
+
+            if not middleware_names and not requires_roles:
+                continue
+
+            uses_schemes: list[str] = []
+            for name in middleware_names:
+                low = name.lower()
+                if any(h in low for h in ("jwt", "authentication", "bearer", "token")):
+                    if "JwtBearer" not in uses_schemes:
+                        uses_schemes.append("JwtBearer")
+                elif any(h in low for h in _API_KEY_HINTS):
+                    if "ApiKey" not in uses_schemes:
+                        uses_schemes.append("ApiKey")
+                elif "passport" in low:
+                    if "Passport" not in uses_schemes:
+                        uses_schemes.append("Passport")
+
+            loc = call.location or CodeLocation(file=parsed_file.path, line=1)
+            dep_name = "+".join(middleware_names) if middleware_names else "role"
+            deps.append(
+                ExtractedAuthDependency(
+                    name=dep_name,
+                    qualified_name=QualifiedName(
+                        module=parsed_file.path.stem,
+                        name=dep_name,
+                    ),
+                    location=loc,
+                    dependency_type=AuthDependencyType.MIDDLEWARE,
+                    uses_schemes=uses_schemes,
+                    requires_roles=requires_roles,
+                    confidence=Confidence.HIGH,
+                )
+            )
+
+        return deps
+
+    def extract_middleware(self, parsed_file: ParsedFile) -> list[ExtractedMiddleware]:
+        return []
+
+
+def _method_from_str(method: str) -> HttpMethod:
+    """Convert a lowercase HTTP method string to HttpMethod enum."""
+    _MAP = {
+        "get": HttpMethod.GET,
+        "post": HttpMethod.POST,
+        "put": HttpMethod.PUT,
+        "patch": HttpMethod.PATCH,
+        "delete": HttpMethod.DELETE,
+        "options": HttpMethod.OPTIONS,
+        "head": HttpMethod.HEAD,
+        "all": HttpMethod.GET,  # 'all' → GET as a fallback
+    }
+    return _MAP.get(method, HttpMethod.GET)
+
+
+FrameworkPluginRegistry.register(ExpressPlugin())