devfortress-sdk 4.2.0

package/bin/devfortress-init.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * DevFortress CLI Init Tool
+ *
+ * Usage: npx devfortress-init
+ *
+ * Scaffolds DevFortress SDK integration into your project:
+ * 1. Detects framework (Express, Next.js, Fastify, Hono)
+ * 2. Creates devfortress.config.ts with zero-config defaults
+ * 3. Shows integration snippet for your framework
+ * 4. Target: under 3 minutes from install to first event
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+function ask(question) {
+  return new Promise(resolve => {
+    rl.question(question, resolve);
+  });
+}
+
+function detectFramework() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')
+    );
+    const deps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+    };
+    if (deps.next) return 'nextjs';
+    if (deps.express) return 'express';
+    if (deps.fastify) return 'fastify';
+    if (deps.hono) return 'hono';
+  } catch {
+    /* no package.json */
+  }
+  return 'unknown';
+}
+
+const SNIPPETS = {
+  express: `// In your Express app entry point (e.g. app.ts or server.ts)
+import { devFortressMiddleware } from 'devfortress-sdk';
+
+// Add before your routes:
+app.use(devFortressMiddleware({
+  apiKey: process.env.DEVFORTRESS_API_KEY!,
+  debug: process.env.NODE_ENV !== 'production',
+}));`,
+
+  nextjs: `// In your Next.js middleware.ts (root of project)
+import df from 'devfortress-sdk/quick';
+
+const client = df.init({
+  apiKey: process.env.DEVFORTRESS_API_KEY!,
+  debug: process.env.NODE_ENV !== 'production',
+});
+
+// In your API routes:
+export async function POST(req: NextRequest) {
+  await client.observe(req);
+  // ... your handler
+}`,
+
+  fastify: `// In your Fastify server setup
+import df from 'devfortress-sdk/quick';
+
+const client = df.init({
+  apiKey: process.env.DEVFORTRESS_API_KEY!,
+  debug: process.env.NODE_ENV !== 'production',
+});
+
+fastify.addHook('onRequest', async (request) => {
+  await client.observe(request.raw);
+});`,
+
+  hono: `// In your Hono app
+import df from 'devfortress-sdk/quick';
+
+const client = df.init({
+  apiKey: process.env.DEVFORTRESS_API_KEY!,
+  debug: process.env.NODE_ENV !== 'production',
+});
+
+app.use('*', async (c, next) => {
+  await client.observe(c.req.raw);
+  await next();
+});`,
+
+  unknown: `// Generic integration
+import df from 'devfortress-sdk/quick';
+
+const client = df.init({
+  apiKey: process.env.DEVFORTRESS_API_KEY!,
+  debug: true,
+});
+
+// Call observe() on every inbound request:
+await client.observe(request);`,
+};
+
+async function main() {
+  console.log('');
+  console.log('🛡️  DevFortress SDK Setup');
+  console.log('─'.repeat(40));
+  console.log('');
+
+  const framework = detectFramework();
+  console.log(
+    `📦 Detected framework: ${framework === 'unknown' ? 'Could not detect' : framework}`
+  );
+  console.log('');
+
+  const apiKey = await ask(
+    '🔑 Enter your DevFortress API key (from dashboard): '
+  );
+  if (!apiKey || !apiKey.startsWith('df_')) {
+    console.log('');
+    console.log(
+      '⚠️  API key should start with "df_". Get one at https://devfortress.net/dashboard/settings/api-keys'
+    );
+    console.log('');
+    console.log('Continuing with placeholder...');
+  }
+
+  const privacy = await ask('🔒 Privacy mode? (standard/strict) [standard]: ');
+  const privacyMode = privacy === 'strict' ? 'strict' : 'standard';
+
+  // Create config file
+  const configContent = `/**
+ * DevFortress Configuration
+ * Generated by devfortress-init on ${new Date().toISOString().split('T')[0]}
+ */
+
+import df from 'devfortress-sdk/quick';
+
+export const devfortress = df.init({
+  apiKey: process.env.DEVFORTRESS_API_KEY || '${apiKey || 'df_your_api_key'}',
+  privacy: '${privacyMode}',
+  debug: process.env.NODE_ENV !== 'production',
+});
+`;
+
+  const configPath = path.join(process.cwd(), 'devfortress.config.ts');
+  if (fs.existsSync(configPath)) {
+    const overwrite = await ask(
+      `⚠️  ${configPath} exists. Overwrite? (y/n) [n]: `
+    );
+    if (overwrite !== 'y') {
+      console.log('Skipping config file creation.');
+    } else {
+      fs.writeFileSync(configPath, configContent);
+      console.log(`✅ Created ${configPath}`);
+    }
+  } else {
+    fs.writeFileSync(configPath, configContent);
+    console.log(`✅ Created ${configPath}`);
+  }
+
+  // Add env variable
+  const envPath = path.join(process.cwd(), '.env.local');
+  const envLine = `DEVFORTRESS_API_KEY=${apiKey || 'df_your_api_key'}`;
+  if (fs.existsSync(envPath)) {
+    const envContent = fs.readFileSync(envPath, 'utf8');
+    if (!envContent.includes('DEVFORTRESS_API_KEY')) {
+      fs.appendFileSync(envPath, `\n${envLine}\n`);
+      console.log('✅ Added DEVFORTRESS_API_KEY to .env.local');
+    } else {
+      console.log('ℹ️  DEVFORTRESS_API_KEY already in .env.local');
+    }
+  } else {
+    fs.writeFileSync(envPath, `${envLine}\n`);
+    console.log('✅ Created .env.local with DEVFORTRESS_API_KEY');
+  }
+
+  // Show integration snippet
+  console.log('');
+  console.log('📝 Integration snippet for your framework:');
+  console.log('─'.repeat(40));
+  console.log('');
+  console.log(SNIPPETS[framework] || SNIPPETS.unknown);
+  console.log('');
+  console.log('─'.repeat(40));
+  console.log('');
+  console.log('🚀 Next steps:');
+  console.log('   1. Add the integration snippet to your app');
+  console.log('   2. Start your development server');
+  console.log('   3. Make a request — see it in your DevFortress dashboard');
+  console.log('');
+  console.log('📖 Full docs: https://devfortress.net/docs/developer-guide');
+  console.log(
+    '🔒 Privacy info: https://devfortress.net/privacy/data-collected'
+  );
+  console.log('');
+
+  rl.close();
+}
+
+main().catch(console.error);

package/dist/browser.d.ts

@@ -0,0 +1,61 @@
+/**
+ * DevFortress SDK - Browser Entry Point
+ *
+ * Lightweight browser-compatible client for sending security events
+ * from client-side applications. Uses fetch API instead of axios.
+ *
+ * @packageDocumentation
+ */
+export type { DevFortressClientOptions, LiveThreatEvent, EventType, SeverityLevel, ApiResponse, } from './types';
+import type { DevFortressClientOptions } from './types';
+/** @deprecated Use DevFortressClientOptions instead */
+export type BrowserClientOptions = DevFortressClientOptions;
+export declare class DevFortressBrowserClient {
+    private apiKey;
+    private endpoint;
+    private timeout;
+    private retries;
+    private debug;
+    constructor(options: DevFortressClientOptions);
+    /**
+     * Track a security event from the browser
+     */
+    trackEvent(event: {
+        eventType: string;
+        ip?: string;
+        method?: string;
+        path?: string;
+        userAgent?: string;
+        statusCode?: number;
+        responseTime?: number;
+        metadata?: Record<string, unknown>;
+        severity?: string;
+        reason?: string;
+        timestamp?: string;
+    }): Promise<{
+        success: boolean;
+        eventId?: string;
+        message?: string;
+    }>;
+    /**
+     * Track a page error as a security event
+     */
+    trackError(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Track a failed API response
+     */
+    trackApiFailure(url: string, status: number, method?: string): void;
+    /**
+     * Install global error handler for automatic tracking
+     */
+    installGlobalErrorHandler(): () => void;
+    /**
+     * Test connection to the surveillance API
+     */
+    testConnection(): Promise<boolean>;
+    private sendWithRetry;
+}
+/**
+ * Create a pre-configured browser client instance
+ */
+export declare function createBrowserClient(options: DevFortressClientOptions): DevFortressBrowserClient;

package/dist/browser.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * DevFortress SDK - Browser Entry Point
+ *
+ * Lightweight browser-compatible client for sending security events
+ * from client-side applications. Uses fetch API instead of axios.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevFortressBrowserClient = void 0;
+exports.createBrowserClient = createBrowserClient;
+const DEFAULT_ENDPOINT = 'https://www.devfortress.net/api/events/ingest';
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_RETRIES = 3;
+class DevFortressBrowserClient {
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error('DevFortressBrowserClient: apiKey is required');
+        }
+        this.apiKey = options.apiKey;
+        this.endpoint = options.endpoint || DEFAULT_ENDPOINT;
+        this.timeout = options.timeout || DEFAULT_TIMEOUT;
+        this.retries = options.retries || DEFAULT_RETRIES;
+        this.debug = options.debug || false;
+        // Warn if endpoint is not HTTPS
+        if (this.endpoint.startsWith('http://') &&
+            !this.endpoint.includes('localhost') &&
+            !this.endpoint.includes('127.0.0.1')) {
+            // eslint-disable-next-line no-console
+            console.warn('[DevFortress] WARNING: Using non-HTTPS endpoint. API key will be transmitted in cleartext.');
+        }
+    }
+    /**
+     * Track a security event from the browser
+     */
+    async trackEvent(event) {
+        const payload = {
+            ...event,
+            ip: event.ip || 'browser-client',
+            userAgent: event.userAgent ||
+                (typeof navigator !== 'undefined' ? navigator.userAgent : undefined),
+            timestamp: event.timestamp || new Date().toISOString(),
+        };
+        return this.sendWithRetry(payload, 1);
+    }
+    /**
+     * Track a page error as a security event
+     */
+    trackError(error, context) {
+        this.trackEvent({
+            eventType: 'custom',
+            reason: error.message,
+            metadata: {
+                stack: error.stack,
+                ...context,
+            },
+            severity: 'MEDIUM',
+        }).catch(() => {
+            // Silently fail - don't crash the app for telemetry
+        });
+    }
+    /**
+     * Track a failed API response
+     */
+    trackApiFailure(url, status, method = 'GET') {
+        let eventType = 'custom';
+        let severity = 'LOW';
+        if (status === 401 || status === 403) {
+            eventType = 'auth_failure';
+            severity = 'MEDIUM';
+        }
+        else if (status === 429) {
+            eventType = 'rate_limit_exceeded';
+            severity = 'MEDIUM';
+        }
+        else if (status >= 500) {
+            eventType = '5xx_error';
+            severity = 'HIGH';
+        }
+        else if (status >= 400) {
+            eventType = '4xx_error';
+            severity = 'LOW';
+        }
+        this.trackEvent({
+            eventType,
+            method,
+            path: url,
+            statusCode: status,
+            severity,
+            reason: `API ${method} ${url} returned ${status}`,
+        }).catch(() => {
+            // Silently fail
+        });
+    }
+    /**
+     * Install global error handler for automatic tracking
+     */
+    installGlobalErrorHandler() {
+        if (typeof window === 'undefined')
+            return () => { };
+        const handler = (event) => {
+            this.trackError(event.error || new Error(event.message), {
+                filename: event.filename,
+                lineno: event.lineno,
+                colno: event.colno,
+            });
+        };
+        const rejectionHandler = (event) => {
+            const error = event.reason instanceof Error
+                ? event.reason
+                : new Error(String(event.reason));
+            this.trackError(error, { type: 'unhandledRejection' });
+        };
+        window.addEventListener('error', handler);
+        window.addEventListener('unhandledrejection', rejectionHandler);
+        // Return cleanup function
+        return () => {
+            window.removeEventListener('error', handler);
+            window.removeEventListener('unhandledrejection', rejectionHandler);
+        };
+    }
+    /**
+     * Test connection to the surveillance API
+     */
+    async testConnection() {
+        try {
+            await this.trackEvent({
+                eventType: 'custom',
+                ip: 'browser-test',
+                metadata: { test: true },
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async sendWithRetry(payload, attempt) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(this.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-DevFortress-Key': this.apiKey,
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                // Don't retry on client errors
+                if (response.status < 500) {
+                    const errorData = await response.json().catch(() => ({}));
+                    throw new Error(errorData.message || `HTTP ${response.status}`);
+                }
+                throw new Error(`Server error: ${response.status}`);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (attempt < this.retries) {
+                const backoff = Math.pow(2, attempt) * 500;
+                if (this.debug) {
+                    // eslint-disable-next-line no-console
+                    console.log(`[DevFortress] Retrying in ${backoff}ms (attempt ${attempt}/${this.retries})`);
+                }
+                await new Promise(resolve => setTimeout(resolve, backoff));
+                return this.sendWithRetry(payload, attempt + 1);
+            }
+            throw error;
+        }
+    }
+}
+exports.DevFortressBrowserClient = DevFortressBrowserClient;
+/**
+ * Create a pre-configured browser client instance
+ */
+function createBrowserClient(options) {
+    return new DevFortressBrowserClient(options);
+}

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,68 @@
+/**
+ * DevFortress SDK — Platform Circuit Breaker
+ *
+ * Monitors connectivity to the DevFortress platform and provides
+ * automatic failover from external to internal closed-loop mode.
+ *
+ * Three states:
+ *   - CLOSED:    Platform is reachable, external CL is active
+ *   - OPEN:      Platform is unreachable, internal CL takes over
+ *   - HALF-OPEN: Testing if platform has recovered
+ *
+ * Transition rules:
+ *   CLOSED → OPEN:      After `failureThreshold` consecutive failures
+ *   OPEN → HALF-OPEN:   After `recoveryTimeMs` elapsed
+ *   HALF-OPEN → CLOSED: First successful call
+ *   HALF-OPEN → OPEN:   First failed call
+ *
+ * @packageDocumentation
+ */
+export type CircuitState = 'closed' | 'open' | 'half-open';
+export interface CircuitBreakerConfig {
+    /** Number of consecutive failures before opening the circuit. Default: 3 */
+    failureThreshold?: number;
+    /** Time in ms to wait before testing recovery. Default: 60_000 (1 min) */
+    recoveryTimeMs?: number;
+    /** Callback when circuit state changes */
+    onStateChange?: (from: CircuitState, to: CircuitState, reason: string) => void;
+}
+export declare class PlatformCircuitBreaker {
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private failureThreshold;
+    private recoveryTimeMs;
+    private onStateChange?;
+    constructor(config?: CircuitBreakerConfig);
+    /**
+     * Check if external platform calls should be attempted.
+     * Returns true if the circuit allows external calls (CLOSED or HALF-OPEN).
+     */
+    shouldCallExternal(): boolean;
+    /**
+     * Record a successful external call.
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed external call.
+     */
+    recordFailure(): void;
+    /**
+     * Get current circuit state.
+     */
+    getState(): CircuitState;
+    /**
+     * Get diagnostics info.
+     */
+    getDiagnostics(): {
+        state: CircuitState;
+        failureCount: number;
+        lastFailureTime: number;
+        msUntilRecoveryAttempt: number;
+    };
+    /**
+     * Force reset the circuit breaker to closed state.
+     */
+    reset(): void;
+    private transition;
+}

package/dist/circuit-breaker.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * DevFortress SDK — Platform Circuit Breaker
+ *
+ * Monitors connectivity to the DevFortress platform and provides
+ * automatic failover from external to internal closed-loop mode.
+ *
+ * Three states:
+ *   - CLOSED:    Platform is reachable, external CL is active
+ *   - OPEN:      Platform is unreachable, internal CL takes over
+ *   - HALF-OPEN: Testing if platform has recovered
+ *
+ * Transition rules:
+ *   CLOSED → OPEN:      After `failureThreshold` consecutive failures
+ *   OPEN → HALF-OPEN:   After `recoveryTimeMs` elapsed
+ *   HALF-OPEN → CLOSED: First successful call
+ *   HALF-OPEN → OPEN:   First failed call
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformCircuitBreaker = void 0;
+class PlatformCircuitBreaker {
+    constructor(config = {}) {
+        this.state = 'closed';
+        this.failureCount = 0;
+        this.lastFailureTime = 0;
+        this.failureThreshold = config.failureThreshold ?? 3;
+        this.recoveryTimeMs = config.recoveryTimeMs ?? 60000;
+        this.onStateChange = config.onStateChange;
+    }
+    /**
+     * Check if external platform calls should be attempted.
+     * Returns true if the circuit allows external calls (CLOSED or HALF-OPEN).
+     */
+    shouldCallExternal() {
+        if (this.state === 'closed')
+            return true;
+        if (this.state === 'open') {
+            // Check if recovery time has elapsed
+            if (Date.now() - this.lastFailureTime >= this.recoveryTimeMs) {
+                this.transition('half-open', 'recovery_timeout_elapsed');
+                return true; // Allow one test call
+            }
+            return false;
+        }
+        // half-open — allow the test call
+        return true;
+    }
+    /**
+     * Record a successful external call.
+     */
+    recordSuccess() {
+        if (this.state === 'half-open') {
+            this.transition('closed', 'test_call_succeeded');
+        }
+        this.failureCount = 0;
+    }
+    /**
+     * Record a failed external call.
+     */
+    recordFailure() {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        if (this.state === 'half-open') {
+            this.transition('open', 'test_call_failed');
+            return;
+        }
+        if (this.state === 'closed' && this.failureCount >= this.failureThreshold) {
+            this.transition('open', `${this.failureCount}_consecutive_failures`);
+        }
+    }
+    /**
+     * Get current circuit state.
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get diagnostics info.
+     */
+    getDiagnostics() {
+        const msUntilRecovery = this.state === 'open'
+            ? Math.max(0, this.recoveryTimeMs - (Date.now() - this.lastFailureTime))
+            : 0;
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            lastFailureTime: this.lastFailureTime,
+            msUntilRecoveryAttempt: msUntilRecovery,
+        };
+    }
+    /**
+     * Force reset the circuit breaker to closed state.
+     */
+    reset() {
+        this.transition('closed', 'manual_reset');
+        this.failureCount = 0;
+        this.lastFailureTime = 0;
+    }
+    transition(to, reason) {
+        const from = this.state;
+        if (from === to)
+            return;
+        this.state = to;
+        if (this.onStateChange) {
+            try {
+                this.onStateChange(from, to, reason);
+            }
+            catch {
+                // Callback errors should not break the circuit breaker
+            }
+        }
+    }
+}
+exports.PlatformCircuitBreaker = PlatformCircuitBreaker;

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DevFortress API Client
+ * Core client for sending events to DevFortress surveillance API
+ */
+import type { DevFortressClientOptions, LiveThreatEvent, ApiResponse } from './types';
+export declare class DevFortressClient {
+    private apiKey;
+    private endpoint;
+    private timeout;
+    private retries;
+    private debug;
+    private axios;
+    constructor(options: DevFortressClientOptions);
+    /**
+     * Track a security event
+     */
+    trackEvent(event: LiveThreatEvent): Promise<ApiResponse>;
+    /**
+     * Send event with automatic retry logic
+     */
+    private sendWithRetry;
+    /**
+     * Test connection to surveillance API
+     */
+    testConnection(): Promise<boolean>;
+}