profclaw 0.0.1-beta.1

package/dist/security/ssrf-guard.js

@@ -0,0 +1,266 @@
+/**
+ * SSRF (Server-Side Request Forgery) Guard
+ *
+ * Prevents SSRF attacks by validating URLs before requests.
+ * Features:
+ * - DNS rebinding defense (resolve before connect)
+ * - Private IP / CIDR blocking (RFC 1918, loopback, link-local, cloud metadata)
+ * - Redirect chain validation with re-resolution
+ * - URL scheme validation (http/https only)
+ * - Configurable host allowlist
+ */
+import { promises as dns } from 'dns';
+import { isIP } from 'net';
+import { logger } from '../utils/logger.js';
+// Default blocked CIDR ranges
+/** RFC 1918 + special-use ranges to block */
+const DEFAULT_BLOCKED_CIDRS = [
+    '0.0.0.0/8', // "This" network
+    '10.0.0.0/8', // Private (Class A)
+    '100.64.0.0/10', // Carrier-grade NAT
+    '127.0.0.0/8', // Loopback
+    '169.254.0.0/16', // Link-local (includes cloud metadata 169.254.169.254)
+    '172.16.0.0/12', // Private (Class B)
+    '192.0.0.0/24', // IETF Protocol Assignments
+    '192.0.2.0/24', // Documentation (TEST-NET-1)
+    '192.168.0.0/16', // Private (Class C)
+    '198.18.0.0/15', // Benchmarking
+    '198.51.100.0/24', // Documentation (TEST-NET-2)
+    '203.0.113.0/24', // Documentation (TEST-NET-3)
+    '224.0.0.0/4', // Multicast
+    '240.0.0.0/4', // Reserved
+    '255.255.255.255/32', // Broadcast
+];
+/** Known cloud metadata endpoints to block */
+const METADATA_HOSTS = new Set([
+    '169.254.169.254', // AWS, GCP, Azure
+    'metadata.google.internal', // GCP
+    'metadata.internal', // Generic cloud
+]);
+const DEFAULT_CONFIG = {
+    enabled: true,
+    allowedHosts: [],
+    blockedCidrs: DEFAULT_BLOCKED_CIDRS,
+    maxRedirects: 5,
+    dnsResolutionTimeout: 3000,
+    allowedSchemes: ['http', 'https'],
+};
+function parseCidr(cidr) {
+    const parts = cidr.split('/');
+    if (parts.length !== 2)
+        return null;
+    const ip = parts[0];
+    const prefix = parseInt(parts[1], 10);
+    if (isNaN(prefix) || prefix < 0 || prefix > 32)
+        return null;
+    const ipInt = ipToInt(ip);
+    if (ipInt === null)
+        return null;
+    const maskInt = prefix === 0 ? 0 : (~0 << (32 - prefix)) >>> 0;
+    return { networkInt: (ipInt & maskInt) >>> 0, maskInt };
+}
+function ipToInt(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return null;
+    let result = 0;
+    for (const part of parts) {
+        const num = parseInt(part, 10);
+        if (isNaN(num) || num < 0 || num > 255)
+            return null;
+        result = (result << 8) | num;
+    }
+    return result >>> 0;
+}
+function isIpInCidr(ip, cidr) {
+    const ipInt = ipToInt(ip);
+    if (ipInt === null)
+        return false;
+    return ((ipInt & cidr.maskInt) >>> 0) === cidr.networkInt;
+}
+// SSRF Guard
+export class SsrfGuard {
+    config;
+    parsedCidrs;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        // Pre-parse CIDR ranges for performance
+        this.parsedCidrs = this.config.blockedCidrs
+            .map(parseCidr)
+            .filter((c) => c !== null);
+    }
+    /**
+     * Validate a URL before making a request
+     * Resolves DNS and checks against blocked ranges
+     */
+    async validateUrl(rawUrl) {
+        if (!this.config.enabled) {
+            return { allowed: true, risk: 'LOW' };
+        }
+        // Parse URL
+        let url;
+        try {
+            url = new URL(rawUrl);
+        }
+        catch {
+            return {
+                allowed: false,
+                reason: `Invalid URL: ${rawUrl}`,
+                risk: 'MEDIUM',
+            };
+        }
+        // Check scheme
+        const scheme = url.protocol.replace(':', '');
+        if (!this.config.allowedSchemes.includes(scheme)) {
+            return {
+                allowed: false,
+                reason: `Blocked URL scheme: ${scheme}. Only ${this.config.allowedSchemes.join(', ')} allowed`,
+                risk: 'HIGH',
+            };
+        }
+        const hostname = normalizeHostname(url.hostname);
+        // Check if host is explicitly allowed (bypass)
+        if (this.config.allowedHosts.includes(hostname)) {
+            return { allowed: true, risk: 'LOW' };
+        }
+        // Check cloud metadata endpoints
+        if (METADATA_HOSTS.has(hostname)) {
+            logger.warn(`[SsrfGuard] Blocked cloud metadata access: ${hostname}`, { component: 'SsrfGuard' });
+            return {
+                allowed: false,
+                reason: `Access to cloud metadata endpoint blocked: ${hostname}`,
+                risk: 'CRITICAL',
+            };
+        }
+        // If the hostname is already an IP, check directly
+        if (isIP(hostname)) {
+            return this.checkIp(hostname);
+        }
+        // Resolve DNS and check resolved IPs (prevents DNS rebinding)
+        try {
+            const ips = await this.resolveWithTimeout(hostname);
+            if (ips.length === 0) {
+                return {
+                    allowed: false,
+                    reason: `DNS resolution returned no addresses for: ${hostname}`,
+                    risk: 'MEDIUM',
+                };
+            }
+            // Check ALL resolved IPs - block if any resolve to private range
+            for (const ip of ips) {
+                const result = this.checkIp(ip);
+                if (!result.allowed) {
+                    logger.warn(`[SsrfGuard] Hostname ${hostname} resolved to blocked IP: ${ip}`, { component: 'SsrfGuard' });
+                    return {
+                        allowed: false,
+                        reason: `Hostname ${hostname} resolves to blocked IP ${ip}: ${result.reason}`,
+                        risk: result.risk,
+                    };
+                }
+            }
+            return { allowed: true, risk: 'LOW' };
+        }
+        catch (error) {
+            // DNS failure - block by default for safety
+            const message = error instanceof Error ? error.message : String(error);
+            logger.warn(`[SsrfGuard] DNS resolution failed for ${hostname}: ${message}`, { component: 'SsrfGuard' });
+            return {
+                allowed: false,
+                reason: `DNS resolution failed for ${hostname}: ${message}`,
+                risk: 'MEDIUM',
+            };
+        }
+    }
+    /**
+     * Validate a redirect target (re-resolve DNS for each hop)
+     */
+    async validateRedirect(redirectUrl, hopCount) {
+        if (hopCount >= this.config.maxRedirects) {
+            return {
+                allowed: false,
+                reason: `Too many redirects (max: ${this.config.maxRedirects})`,
+                risk: 'MEDIUM',
+            };
+        }
+        return this.validateUrl(redirectUrl);
+    }
+    /**
+     * Check if an IP address is in a blocked range
+     */
+    checkIp(ip) {
+        // Check IPv4
+        if (isIP(ip) === 4) {
+            // Check loopback
+            if (ip.startsWith('127.')) {
+                return { allowed: false, reason: 'Loopback address blocked', risk: 'HIGH' };
+            }
+            // Check against all blocked CIDRs
+            for (const cidr of this.parsedCidrs) {
+                if (isIpInCidr(ip, cidr)) {
+                    return {
+                        allowed: false,
+                        reason: `IP ${ip} is in blocked range`,
+                        risk: 'HIGH',
+                    };
+                }
+            }
+            return { allowed: true, risk: 'LOW' };
+        }
+        // Check IPv6
+        if (isIP(ip) === 6) {
+            const lower = ip.toLowerCase();
+            // Loopback
+            if (lower === '::1') {
+                return { allowed: false, reason: 'IPv6 loopback blocked', risk: 'HIGH' };
+            }
+            // Link-local
+            if (lower.startsWith('fe80:')) {
+                return { allowed: false, reason: 'IPv6 link-local blocked', risk: 'HIGH' };
+            }
+            // Unique local (fc00::/7)
+            if (lower.startsWith('fc') || lower.startsWith('fd')) {
+                return { allowed: false, reason: 'IPv6 unique-local blocked', risk: 'HIGH' };
+            }
+            // IPv4-mapped IPv6 (::ffff:x.x.x.x)
+            const v4Match = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+            if (v4Match) {
+                return this.checkIp(v4Match[1]);
+            }
+            return { allowed: true, risk: 'LOW' };
+        }
+        // Unknown format
+        return { allowed: false, reason: `Unrecognized IP format: ${ip}`, risk: 'MEDIUM' };
+    }
+    /**
+     * Get current config
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // Private
+    async resolveWithTimeout(hostname) {
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error('DNS resolution timeout')), this.config.dnsResolutionTimeout);
+        });
+        const resolvePromise = dns.resolve4(hostname);
+        return Promise.race([resolvePromise, timeoutPromise]);
+    }
+}
+// Helpers
+function normalizeHostname(hostname) {
+    // Strip IPv6 brackets
+    if (hostname.startsWith('[') && hostname.endsWith(']')) {
+        return hostname.slice(1, -1);
+    }
+    return hostname.toLowerCase();
+}
+// Singleton
+let instance = null;
+export function getSsrfGuard() {
+    return instance;
+}
+export function createSsrfGuard(config) {
+    instance = new SsrfGuard(config);
+    return instance;
+}
+//# sourceMappingURL=ssrf-guard.js.map

package/dist/security/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Security Guard Types
+ *
+ * Shared types for input-level security guards:
+ * prompt injection, SSRF, filesystem, audit scanning.
+ */
+export type RiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+export interface GuardResult {
+    allowed: boolean;
+    reason?: string;
+    risk: RiskLevel;
+    /** Score 0-100 representing severity */
+    score?: number;
+}
+export interface PromptGuardConfig {
+    enabled: boolean;
+    /** Maximum input length in characters (default 50000) */
+    maxInputLength: number;
+    /** Length of canary token marker (default 16) */
+    canaryTokenLength: number;
+    /** Jailbreak detection patterns */
+    jailbreakPatterns: RegExp[];
+    /** Score threshold to block (default 50) */
+    blockThreshold: number;
+    /** Score threshold to warn (default 25) */
+    warnThreshold: number;
+}
+export interface CanaryToken {
+    token: string;
+    createdAt: number;
+    conversationId?: string;
+}
+export interface SsrfGuardConfig {
+    enabled: boolean;
+    /** Hosts that bypass private IP checks */
+    allowedHosts: string[];
+    /** CIDR ranges to block (RFC 1918, link-local, loopback) */
+    blockedCidrs: string[];
+    /** Maximum redirect hops to follow (default 5) */
+    maxRedirects: number;
+    /** DNS resolution timeout in ms (default 3000) */
+    dnsResolutionTimeout: number;
+    /** Allowed URL schemes (default: http, https) */
+    allowedSchemes: string[];
+}
+export type FsOperation = 'read' | 'write' | 'delete' | 'list';
+export interface FsGuardConfig {
+    enabled: boolean;
+    /** Paths the agent is allowed to access */
+    allowedPaths: string[];
+    /** Paths that are always blocked */
+    blockedPaths: string[];
+    /** Whether to resolve symlinks before checking (default true) */
+    followSymlinks: boolean;
+    /** Blocked filename patterns (e.g., .env*) */
+    blockedPatterns: string[];
+}
+export interface AuditScannerConfig {
+    enabled: boolean;
+    /** Patterns that indicate dangerous code in skills */
+    dangerousPatterns: RegExp[];
+    /** Whether to log alerts when patterns match */
+    alertOnMatch: boolean;
+}
+export interface ScanFinding {
+    pattern: string;
+    match: string;
+    line: number;
+    risk: RiskLevel;
+    description: string;
+}
+export interface ScanResult {
+    source: string;
+    findings: ScanFinding[];
+    riskLevel: RiskLevel;
+    scannedAt: number;
+}
+export interface ConfigValidationResult {
+    valid: boolean;
+    warnings: Array<{
+        field: string;
+        message: string;
+        risk: RiskLevel;
+    }>;
+}
+export interface IsolationContext {
+    conversationId: string;
+    userId?: string;
+    /** Memory paths this conversation is allowed to access */
+    allowedMemoryPaths: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/security/types.js

@@ -0,0 +1,8 @@
+/**
+ * Security Guard Types
+ *
+ * Shared types for input-level security guards:
+ * prompt injection, SSRF, filesystem, audit scanning.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/route-loader.d.ts

@@ -0,0 +1,15 @@
+import type { Context, Hono } from 'hono';
+import { type DeploymentMode } from '../core/deployment.js';
+type RouteApp = Pick<Hono, 'all'>;
+type RouteInstance = Pick<Hono, 'fetch'>;
+type RouteLoader = () => Promise<RouteInstance>;
+export interface RouteDefinition {
+    id: string;
+    mountPaths: string[];
+    load: RouteLoader;
+}
+export declare function createLazyRouteHandler(definition: RouteDefinition, mountPath: string): (c: Context) => Promise<Response>;
+export declare function getRouteDefinitionsForMode(mode: DeploymentMode): RouteDefinition[];
+export declare function registerRouteModules(app: RouteApp, mode: DeploymentMode): Promise<void>;
+export {};
+//# sourceMappingURL=route-loader.d.ts.map

package/dist/server/route-loader.js

@@ -0,0 +1,135 @@
+import { hasCapabilityForMode } from '../core/deployment.js';
+function normalizeMountedPath(pathname, mountPath) {
+    if (pathname === mountPath) {
+        return '/';
+    }
+    if (pathname.startsWith(`${mountPath}/`)) {
+        return pathname.slice(mountPath.length) || '/';
+    }
+    return pathname;
+}
+export function createLazyRouteHandler(definition, mountPath) {
+    let routePromise = null;
+    return async (c) => {
+        if (!routePromise) {
+            routePromise = definition.load();
+        }
+        const route = await routePromise;
+        const url = new URL(c.req.url);
+        url.pathname = normalizeMountedPath(url.pathname, mountPath);
+        let executionCtx;
+        try {
+            executionCtx = c.executionCtx;
+        }
+        catch {
+            executionCtx = undefined;
+        }
+        return route.fetch(new Request(url, c.req.raw), c.env, executionCtx);
+    };
+}
+function namedRoute(importer, exportName) {
+    return async () => (await importer())[exportName];
+}
+function defaultRoute(importer) {
+    return async () => (await importer()).default;
+}
+// Core routes loaded in all modes (pico, mini, pro)
+const CORE_ROUTE_DEFINITIONS = [
+    { id: 'tasks', mountPaths: ['/api/tasks'], load: namedRoute(() => import('../routes/tasks.js'), 'tasksRoutes') },
+    { id: 'agents', mountPaths: ['/api/agents'], load: namedRoute(() => import('../routes/agents.js'), 'agentsRoutes') },
+    { id: 'chat', mountPaths: ['/api/chat'], load: namedRoute(() => import('../routes/chat.js'), 'chatRoutes') },
+    { id: 'webchat', mountPaths: ['/api/chat/webchat'], load: namedRoute(() => import('../routes/webchat.js'), 'webchatRoutes') },
+    { id: 'gateway', mountPaths: ['/api/gateway'], load: namedRoute(() => import('../routes/gateway.js'), 'gatewayRoutes') },
+    { id: 'hooks', mountPaths: ['/api/hook'], load: namedRoute(() => import('../routes/hooks.js'), 'hooksRoutes') },
+    { id: 'tools', mountPaths: ['/api/tools'], load: defaultRoute(() => import('../routes/tools.js')) },
+    { id: 'auth', mountPaths: ['/auth', '/api/auth'], load: namedRoute(() => import('../routes/auth.js'), 'authRoutes') },
+    { id: 'settings', mountPaths: ['/api/settings'], load: namedRoute(() => import('../routes/settings.js'), 'settingsRoutes') },
+    { id: 'security', mountPaths: ['/api/security'], load: defaultRoute(() => import('../routes/security.js')) },
+];
+// Dashboard/UI routes (gated on web_ui capability)
+const DASHBOARD_ROUTE_DEFINITIONS = [
+    { id: 'setup', mountPaths: ['/api/setup'], load: namedRoute(() => import('../routes/setup.js'), 'setupRoutes') },
+    { id: 'oobe', mountPaths: ['/api/oobe'], load: namedRoute(() => import('../routes/oobe.js'), 'oobeRoutes') },
+    { id: 'memory', mountPaths: ['/api/memory'], load: namedRoute(() => import('../routes/memory.js'), 'memoryRoutes') },
+    { id: 'skills', mountPaths: ['/api/skills'], load: namedRoute(() => import('../routes/skills.js'), 'skillsRoutes') },
+    { id: 'openapi', mountPaths: ['/api/docs'], load: namedRoute(() => import('../routes/openapi.js'), 'openApiRoutes') },
+    { id: 'mcp', mountPaths: ['/api/mcp'], load: namedRoute(() => import('../routes/mcp.js'), 'mcpRoutes') },
+    { id: 'costs', mountPaths: ['/api/costs'], load: namedRoute(() => import('../routes/costs.js'), 'costsRoutes') },
+    { id: 'tunnels', mountPaths: ['/api/tunnels'], load: namedRoute(() => import('../routes/tunnels.js'), 'tunnelsRoutes') },
+    { id: 'voice', mountPaths: ['/api/voice'], load: namedRoute(() => import('../routes/voice.js'), 'voiceRoutes') },
+];
+// Plugin routes (gated on plugins capability)
+const PLUGINS_ROUTE_DEFINITIONS = [
+    { id: 'plugins', mountPaths: ['/api/plugins'], load: namedRoute(() => import('../routes/plugins.js'), 'pluginsRoutes') },
+    { id: 'clawhub', mountPaths: ['/api/clawhub'], load: namedRoute(() => import('../routes/clawhub.js'), 'clawhubRoutes') },
+];
+// Notification routes (gated on notifications capability)
+const NOTIFICATIONS_ROUTE_DEFINITIONS = [
+    { id: 'push', mountPaths: ['/api/push'], load: namedRoute(() => import('../routes/push.js'), 'pushRoutes') },
+];
+const WEB_UI_ROUTE_DEFINITIONS = [
+    { id: 'dlq', mountPaths: ['/api/dlq'], load: namedRoute(() => import('../routes/dlq.js'), 'dlqRoutes') },
+    { id: 'summaries', mountPaths: ['/api/summaries'], load: namedRoute(() => import('../routes/summaries.js'), 'summariesRoutes') },
+    { id: 'tokens', mountPaths: ['/api/tokens'], load: namedRoute(() => import('../routes/tokens.js'), 'tokensRoutes') },
+    { id: 'search', mountPaths: ['/api/search'], load: namedRoute(() => import('../routes/search.js'), 'searchRoutes') },
+    { id: 'stats', mountPaths: ['/api/stats'], load: namedRoute(() => import('../routes/stats.js'), 'statsRoutes') },
+    { id: 'users', mountPaths: ['/api/users'], load: namedRoute(() => import('../routes/users.js'), 'userRoutes') },
+    { id: 'devices', mountPaths: ['/api/devices'], load: namedRoute(() => import('../routes/devices.js'), 'devicesRoutes') },
+    { id: 'notifications', mountPaths: ['/api/notifications'], load: namedRoute(() => import('../routes/notifications.js'), 'notificationsRoutes') },
+];
+const CRON_ROUTE_DEFINITIONS = [
+    { id: 'cron', mountPaths: ['/api/cron'], load: namedRoute(() => import('../routes/cron.js'), 'cronRoutes') },
+];
+const INTEGRATION_ROUTE_DEFINITIONS = [
+    { id: 'tickets', mountPaths: ['/api/tickets'], load: namedRoute(() => import('../routes/tickets.js'), 'ticketsRoutes') },
+    { id: 'projects', mountPaths: ['/api/projects'], load: namedRoute(() => import('../routes/projects.js'), 'projectsRoutes') },
+    { id: 'labels', mountPaths: ['/api'], load: namedRoute(() => import('../routes/labels.js'), 'labelsRoutes') },
+    { id: 'webhooks', mountPaths: ['/webhooks'], load: namedRoute(() => import('../routes/webhooks.js'), 'webhooksRoutes') },
+];
+const SYNC_ROUTE_DEFINITIONS = [
+    { id: 'sync', mountPaths: ['/api/sync'], load: defaultRoute(() => import('../routes/sync.js')) },
+    { id: 'import', mountPaths: ['/api/import'], load: namedRoute(() => import('../routes/import.js'), 'importRoutes') },
+    { id: 'backup', mountPaths: ['/api/backup'], load: namedRoute(() => import('../routes/backup.js'), 'backupRoutes') },
+];
+const CHAT_CHANNEL_ROUTE_DEFINITIONS = [
+    { id: 'telegram', mountPaths: ['/api/telegram'], load: namedRoute(() => import('../routes/telegram.js'), 'telegramRoutes') },
+    { id: 'whatsapp', mountPaths: ['/api/whatsapp'], load: namedRoute(() => import('../routes/whatsapp.js'), 'whatsappRoutes') },
+    { id: 'discord', mountPaths: ['/api/discord'], load: namedRoute(() => import('../routes/discord.js'), 'discordRoutes') },
+];
+export function getRouteDefinitionsForMode(mode) {
+    const definitions = [...CORE_ROUTE_DEFINITIONS];
+    if (hasCapabilityForMode(mode, 'web_ui')) {
+        definitions.push(...DASHBOARD_ROUTE_DEFINITIONS);
+        definitions.push(...WEB_UI_ROUTE_DEFINITIONS);
+    }
+    if (hasCapabilityForMode(mode, 'plugins')) {
+        definitions.push(...PLUGINS_ROUTE_DEFINITIONS);
+    }
+    if (hasCapabilityForMode(mode, 'notifications')) {
+        definitions.push(...NOTIFICATIONS_ROUTE_DEFINITIONS);
+    }
+    if (hasCapabilityForMode(mode, 'cron')) {
+        definitions.push(...CRON_ROUTE_DEFINITIONS);
+    }
+    if (hasCapabilityForMode(mode, 'integrations')) {
+        definitions.push(...INTEGRATION_ROUTE_DEFINITIONS);
+    }
+    if (hasCapabilityForMode(mode, 'sync_engine')) {
+        definitions.push(...SYNC_ROUTE_DEFINITIONS);
+    }
+    if (hasCapabilityForMode(mode, 'chat_channels')) {
+        definitions.push(...CHAT_CHANNEL_ROUTE_DEFINITIONS);
+    }
+    return definitions;
+}
+export async function registerRouteModules(app, mode) {
+    const mountEntries = getRouteDefinitionsForMode(mode)
+        .flatMap((definition) => definition.mountPaths.map((mountPath) => ({ definition, mountPath })))
+        .sort((a, b) => b.mountPath.length - a.mountPath.length);
+    for (const { definition, mountPath } of mountEntries) {
+        const handler = createLazyRouteHandler(definition, mountPath);
+        app.all(mountPath, handler);
+        app.all(`${mountPath}/*`, handler);
+    }
+}
+//# sourceMappingURL=route-loader.js.map

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import { Hono } from 'hono';
+declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export { app };
+export declare function broadcastEvent(eventType: string, data: unknown): void;
+//# sourceMappingURL=server.d.ts.map