devfortress-sdk 4.2.0

package/dist/types.d.ts

@@ -0,0 +1,217 @@
+/**
+ * DevFortress SDK v3.0.0 — Type Definitions
+ *
+ * Covers:
+ * - Event types & severity levels
+ * - SDK configuration & enrichment hooks
+ * - Threat events & webhook payloads
+ * - Token alias interfaces
+ * - AbuseIPDB types
+ */
+/** Closed-loop protection mode:
+ * - 'external': SDK → DevFortress Platform → webhook → response (default)
+ * - 'internal': 3-tier local engine, no platform calls (enterprise/air-gap)
+ * - 'hybrid':   Internal evaluates first, external enriches asynchronously
+ */
+export type CLMode = 'external' | 'internal' | 'hybrid';
+export type EventType = 'auth_failure' | 'validation_error' | 'rate_limit_exceeded' | '5xx_error' | '4xx_error' | 'suspicious_pattern' | 'sql_injection_attempt' | 'xss_attempt' | 'custom' | 'login_brute_force' | 'credential_stuffing' | 'password_spray' | 'honeypot_triggered' | 'sql_injection' | 'auth_endpoint_scan' | 'recon_scan' | 'bot_signature' | 'brute_force' | 'token_replay' | 'privilege_escalation' | 'suspicious_ip' | 'anomalous_volume' | 'geo_anomaly';
+export type SeverityLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export type ThreatSeverity = 'low' | 'medium' | 'high' | 'critical';
+/** Authentication phase when the event occurred:
+ * - 'pre_auth':  Before authentication (login attempts, public endpoint attacks)
+ * - 'post_auth': After authentication (session-based threats, privilege escalation)
+ */
+export type AuthPhase = 'pre_auth' | 'post_auth';
+/** Action taken by the protection system in response to the threat */
+export type ActionTaken = 'blocked' | 'rate_limited' | 'session_revoked' | 'captcha_challenged' | 'flagged' | 'allowed' | 'monitored';
+export interface LiveThreatEvent {
+    eventType: EventType;
+    timestamp?: string;
+    ip: string;
+    method?: string;
+    path?: string;
+    userAgent?: string | null;
+    statusCode?: number | null;
+    responseTime?: number | null;
+    metadata?: Record<string, unknown>;
+    severity?: SeverityLevel;
+    reason?: string;
+    userId?: string | null;
+    sessionId?: string | null;
+    appId?: string;
+    environment?: string;
+    compositeScore?: number;
+    abuseipdb?: AbuseIPDBScore;
+    /** Closed-loop protection mode active when event was captured */
+    clMode?: CLMode;
+    /** Whether event occurred pre-auth or post-auth */
+    authPhase?: AuthPhase;
+    /** Action taken by the protection system */
+    actionTaken?: ActionTaken;
+    /** Response latency in milliseconds (time from request to SDK event emission) */
+    responseLatencyMs?: number;
+    /** Whether user session remained active after the action was taken */
+    sessionActiveAfterAction?: boolean;
+}
+export interface DevFortressClientOptions {
+    apiKey: string;
+    endpoint?: string;
+    timeout?: number;
+    retries?: number;
+    debug?: boolean;
+}
+export interface DevFortressConfig {
+    apiKey: string;
+    appId: string;
+    environment?: string;
+    debug?: boolean;
+    endpoint?: string;
+    timeout?: number;
+    retries?: number;
+    enrichment?: EnrichmentConfig;
+    alertThresholds?: Partial<Record<string, ThreatSeverity>>;
+    responseWebhook?: {
+        url: string;
+        secret: string;
+    };
+    cache?: {
+        driver: 'redis' | 'memory';
+        url?: string;
+        ttl?: number;
+    };
+    /** Closed-loop protection mode. Default: 'external' */
+    mode?: CLMode;
+    /** Subscription tier for feature gating */
+    tier?: 'starter' | 'pro' | 'enterprise';
+    /** Whether the hybrid add-on is enabled (Pro tier only) */
+    hybridAddonEnabled?: boolean;
+    /** Internal closed-loop engine configuration (for 'internal' or 'hybrid' mode) */
+    internalCL?: {
+        /** Fail-closed (block on error) or fail-open. Default: 'closed' */
+        failMode?: 'closed' | 'open';
+        /** Custom Tier 2 scorer */
+        tier2Scorer?: (request: unknown) => Promise<number> | number;
+        /** Score threshold for auto-block. Default: 85 */
+        blockThreshold?: number;
+        /** Rate limit: max requests per window. Default: 100 */
+        rateLimitMax?: number;
+        /** Rate limit window in ms. Default: 60000 */
+        rateLimitWindowMs?: number;
+    };
+    /** Circuit breaker config for hybrid mode fallback */
+    circuitBreaker?: {
+        /** Failures before opening circuit. Default: 3 */
+        failureThreshold?: number;
+        /** Time before testing recovery in ms. Default: 60000 */
+        recoveryTimeMs?: number;
+    };
+}
+export interface EnrichmentConfig {
+    getUserId?: (req: unknown) => string | null | Promise<string | null>;
+    getSessionId?: (req: unknown) => string | null | Promise<string | null>;
+    getIP?: (req: unknown) => string | null;
+}
+export interface ObserveResult {
+    flagged: boolean;
+    event_id: string;
+    confidence: number;
+}
+export interface ObserveOptions {
+    meta?: Record<string, unknown>;
+    skipEnrichment?: boolean;
+}
+export interface ThreatEvent {
+    event_id: string;
+    threat_type: string;
+    severity: ThreatSeverity;
+    confidence: number;
+    composite_score: number;
+    ip: string;
+    identity: {
+        user_id: string | null;
+        session_id: string | null;
+    };
+    geo?: {
+        country: string;
+        city: string;
+    };
+    abuseipdb?: AbuseIPDBScore;
+    endpoint: string;
+    method: string;
+    timestamp: string;
+    meta: Record<string, unknown>;
+}
+export interface ActionReport {
+    success: boolean;
+    actions: string[];
+    reason?: string;
+    meta?: Record<string, unknown>;
+}
+export interface AbuseIPDBScore {
+    score: number;
+    isTor: boolean;
+    isDatacenter: boolean;
+    distinctUsers?: number;
+    fromCache?: boolean;
+}
+export interface AbuseIPDBCheckResult {
+    abuseConfidenceScore: number;
+    totalReports: number;
+    numDistinctUsers: number;
+    isTor: boolean;
+    usageType: string;
+    countryCode: string;
+    lastReportedAt: string | null;
+    isp: string;
+}
+export interface CompositeScoreResult {
+    score: number;
+    severity: ThreatSeverity;
+    abuseScore: number;
+    isTor: boolean;
+    isDatacenter: boolean;
+    distinctUsers: number;
+    fromCache: boolean;
+}
+export interface TokenAliasData {
+    realToken: string;
+    userId: string;
+    createdAt: number;
+}
+export interface DevFortressMiddlewareOptions extends DevFortressClientOptions {
+    captureBody?: boolean;
+    captureHeaders?: boolean;
+    excludePaths?: string[];
+    sanitize?: (data: Record<string, unknown>) => Record<string, unknown>;
+    onRequest?: (req: unknown) => Partial<LiveThreatEvent> | null;
+    onError?: (error: Error) => void;
+    mode?: CLMode;
+}
+export interface ApiResponse {
+    success: boolean;
+    message?: string;
+    eventId?: string;
+}
+export interface WebhookPayload {
+    event_id: string;
+    action: string;
+    threat_type: string;
+    severity: ThreatSeverity;
+    confidence: number;
+    composite_score: number;
+    ip: string;
+    identity: {
+        user_id: string | null;
+        session_id: string | null;
+    };
+    geo?: {
+        country: string;
+        city: string;
+    };
+    abuseipdb?: AbuseIPDBScore;
+    endpoint: string;
+    method: string;
+    timestamp: string;
+    meta: Record<string, unknown>;
+}
+export type ThreatHandler = (event: ThreatEvent) => Promise<void> | void;

package/dist/types.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * DevFortress SDK v3.0.0 — Type Definitions
+ *
+ * Covers:
+ * - Event types & severity levels
+ * - SDK configuration & enrichment hooks
+ * - Threat events & webhook payloads
+ * - Token alias interfaces
+ * - AbuseIPDB types
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "devfortress-sdk",
+  "version": "4.2.0",
+  "description": "DevFortress SDK — API and application security with automated threat response, session privacy, and AI agent observability.",
+  "main": "dist/index.js",
+  "browser": "dist/browser.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./browser": {
+      "import": "./dist/browser.js",
+      "require": "./dist/browser.js",
+      "types": "./dist/browser.d.ts"
+    },
+    "./quick": {
+      "import": "./dist/quick.js",
+      "require": "./dist/quick.js",
+      "types": "./dist/quick.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "devfortress-init": "./bin/devfortress-init.js"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/client.js",
+    "dist/client.d.ts",
+    "dist/browser.js",
+    "dist/browser.d.ts",
+    "dist/quick.js",
+    "dist/quick.d.ts",
+    "dist/types.js",
+    "dist/types.d.ts",
+    "dist/circuit-breaker.js",
+    "dist/circuit-breaker.d.ts",
+    "dist/middleware/express.js",
+    "dist/middleware/express.d.ts",
+    "bin/devfortress-init.js",
+    "src/middleware/fastapi.py",
+    "src/middleware/flask.py",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "devfortress",
+    "security",
+    "api-security",
+    "application-security",
+    "threat-detection",
+    "monitoring",
+    "automated-response",
+    "webhook",
+    "express",
+    "nodejs",
+    "agent-security",
+    "ai-agents",
+    "closed-loop",
+    "session-privacy"
+  ],
+  "author": "DevFortress Team",
+  "license": "BUSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/duncan982/devfortress.git",
+    "directory": "packages/devfortress-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/duncan982/devfortress/issues"
+  },
+  "homepage": "https://devfortress.net",
+  "sideEffects": false,
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/express": "^4.17.21 || ^5.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^30.2.0",
+    "@types/jest": "^30.0.0"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  }
+}

package/src/middleware/fastapi.py

@@ -0,0 +1,232 @@
+"""
+DevFortress FastAPI Middleware
+
+Automatically monitors FastAPI applications for security events and sends
+them to the DevFortress surveillance API.
+
+Usage:
+    from devfortress_middleware import DevFortressMiddleware
+
+    app = FastAPI()
+    app.add_middleware(
+        DevFortressMiddleware,
+        api_key="your-api-key",
+        endpoint="https://www.devfortress.net/api/events/ingest"
+    )
+"""
+
+import time
+import re
+import json
+import asyncio
+from typing import Optional, List, Dict, Any, Callable
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+try:
+    import httpx
+    HAS_HTTPX = True
+except ImportError:
+    HAS_HTTPX = False
+
+try:
+    from urllib.request import Request as URLRequest, urlopen
+    from urllib.error import URLError
+    HAS_URLLIB = True
+except ImportError:
+    HAS_URLLIB = False
+
+
+# SQL Injection patterns
+SQL_PATTERNS = [
+    re.compile(r"(\bor\b.*=.*)", re.IGNORECASE),
+    re.compile(r"(\bunion\b.*\bselect\b)", re.IGNORECASE),
+    re.compile(r"(\bdrop\b.*\btable\b)", re.IGNORECASE),
+    re.compile(r"('\s*or\s*'1'\s*=\s*'1)", re.IGNORECASE),
+]
+
+# XSS patterns
+XSS_PATTERNS = [
+    re.compile(r"<script[^>]*>[\s\S]*?</script>", re.IGNORECASE),
+    re.compile(r"javascript:", re.IGNORECASE),
+    re.compile(r"onerror\s*=\s*", re.IGNORECASE),
+    re.compile(r"onload\s*=\s*", re.IGNORECASE),
+]
+
+# Path traversal patterns
+TRAVERSAL_PATTERNS = [
+    re.compile(r"\.\.[/\\]"),
+    re.compile(r"/etc/passwd", re.IGNORECASE),
+]
+
+
+class DevFortressMiddleware(BaseHTTPMiddleware):
+    """FastAPI middleware for DevFortress security monitoring."""
+
+    def __init__(
+        self,
+        app,
+        api_key: str,
+        endpoint: str = "https://www.devfortress.net/api/events/ingest",
+        exclude_paths: Optional[List[str]] = None,
+        capture_headers: bool = False,
+        debug: bool = False,
+        on_error: Optional[Callable[[Exception], None]] = None,
+    ):
+        super().__init__(app)
+        self.api_key = api_key
+        self.endpoint = endpoint
+        self.exclude_paths = exclude_paths or ["/health", "/docs", "/openapi.json"]
+        self.capture_headers = capture_headers
+        self.debug = debug
+        self.on_error = on_error
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        # Skip excluded paths
+        if any(request.url.path.startswith(p) for p in self.exclude_paths):
+            return await call_next(request)
+
+        start_time = time.time()
+        response: Optional[Response] = None
+
+        try:
+            response = await call_next(request)
+        except Exception as exc:
+            # Track server error
+            await self._track_event(
+                request=request,
+                status_code=500,
+                response_time=time.time() - start_time,
+                event_type="5xx_error",
+                severity="HIGH",
+                reason=f"Unhandled exception: {str(exc)}",
+            )
+            raise
+
+        response_time = time.time() - start_time
+        status_code = response.status_code
+
+        # Determine event type
+        event_type = None
+        severity = "LOW"
+        reason = None
+
+        if status_code in (401, 403):
+            event_type = "auth_failure"
+            severity = "MEDIUM"
+            reason = "Authentication or authorization failed"
+        elif status_code in (400, 422):
+            event_type = "validation_error"
+            severity = "LOW"
+            reason = "Request validation failed"
+        elif status_code == 429:
+            event_type = "rate_limit_exceeded"
+            severity = "MEDIUM"
+            reason = "Rate limit exceeded"
+        elif status_code >= 500:
+            event_type = "5xx_error"
+            severity = "HIGH"
+            reason = f"Server error: {status_code}"
+        elif status_code >= 400:
+            event_type = "4xx_error"
+            severity = "LOW"
+            reason = f"Client error: {status_code}"
+
+        # Check suspicious patterns
+        suspicious = self._detect_suspicious(request)
+        if suspicious:
+            event_type = "suspicious_pattern"
+            severity = "HIGH"
+            reason = f"Suspicious patterns: {', '.join(suspicious)}"
+
+        if event_type:
+            # Fire and forget
+            asyncio.create_task(
+                self._track_event(
+                    request=request,
+                    status_code=status_code,
+                    response_time=response_time,
+                    event_type=event_type,
+                    severity=severity,
+                    reason=reason,
+                )
+            )
+
+        return response
+
+    async def _track_event(
+        self,
+        request: Request,
+        status_code: int,
+        response_time: float,
+        event_type: str,
+        severity: str,
+        reason: Optional[str] = None,
+    ):
+        """Send event to DevFortress API."""
+        ip = (
+            request.headers.get("x-forwarded-for", "").split(",")[0].strip()
+            or request.headers.get("x-real-ip", "")
+            or (request.client.host if request.client else "0.0.0.0")
+        )
+
+        payload: Dict[str, Any] = {
+            "eventType": event_type,
+            "ip": ip,
+            "method": request.method,
+            "path": str(request.url.path),
+            "userAgent": request.headers.get("user-agent"),
+            "statusCode": status_code,
+            "responseTime": round(response_time * 1000),
+            "severity": severity,
+            "reason": reason,
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        }
+
+        if self.capture_headers:
+            payload["metadata"] = {"headers": dict(request.headers)}
+
+        try:
+            if HAS_HTTPX:
+                async with httpx.AsyncClient(timeout=5.0) as client:
+                    await client.post(
+                        self.endpoint,
+                        json=payload,
+                        headers={
+                            "Content-Type": "application/json",
+                            "X-DevFortress-Key": self.api_key,
+                        },
+                    )
+            elif HAS_URLLIB:
+                req = URLRequest(
+                    self.endpoint,
+                    data=json.dumps(payload).encode("utf-8"),
+                    headers={
+                        "Content-Type": "application/json",
+                        "X-DevFortress-Key": self.api_key,
+                    },
+                    method="POST",
+                )
+                urlopen(req, timeout=5)
+        except Exception as exc:
+            if self.on_error:
+                self.on_error(exc)
+            elif self.debug:
+                print(f"[DevFortress] Failed to send event: {exc}")  # noqa: T201
+
+    def _detect_suspicious(self, request: Request) -> List[str]:
+        """Detect suspicious patterns in the request."""
+        patterns_found = []
+        url_str = str(request.url)
+        query_str = str(request.query_params)
+        check_str = f"{url_str} {query_str}"
+
+        if any(p.search(check_str) for p in SQL_PATTERNS):
+            patterns_found.append("sql_injection")
+        if any(p.search(check_str) for p in XSS_PATTERNS):
+            patterns_found.append("xss")
+        if any(p.search(check_str) for p in TRAVERSAL_PATTERNS):
+            patterns_found.append("path_traversal")
+
+        return patterns_found