jaku.sh 1.0.0

package/src/agents/base-agent.js

@@ -0,0 +1,158 @@
+/**
+ * BaseAgent — Abstract base class for all JAKU agents.
+ * 
+ * Lifecycle: init() → run() → cleanup()
+ * 
+ * Subclasses must implement:
+ *   - name (string)
+ *   - dependencies (string[]) — names of agents that must complete before this one
+ *   - _execute(context) — the agent's main work
+ */
+export class BaseAgent {
+    constructor() {
+        if (new.target === BaseAgent) {
+            throw new Error('BaseAgent is abstract — extend it, do not instantiate directly.');
+        }
+
+        this._status = 'idle';       // idle → initializing → running → done → error
+        this._startTime = null;
+        this._endTime = null;
+        this._findings = [];
+        this._eventBus = null;
+        this._logger = null;
+        this._config = null;
+        this._context = null;
+    }
+
+    /** Agent display name (e.g. "JAKU-QA"). Must be overridden. */
+    get name() { throw new Error('Agent must define a name'); }
+
+    /** Agent names this agent depends on. Override to add dependencies. */
+    get dependencies() { return []; }
+
+    /** Current agent status. */
+    get status() { return this._status; }
+
+    /** Duration in ms (only valid after completion). */
+    get duration() {
+        if (!this._startTime) return 0;
+        const end = this._endTime || Date.now();
+        return end - this._startTime;
+    }
+
+    /** All findings collected by this agent. */
+    get findings() { return [...this._findings]; }
+
+    /**
+     * Initialize the agent with shared context.
+     * Called by the Orchestrator before run().
+     */
+    async init(context) {
+        this._status = 'initializing';
+        this._config = context.config;
+        this._logger = context.logger;
+        this._eventBus = context.eventBus;
+        this._context = context;
+
+        this._eventBus.emit('agent:registered', { agentName: this.name });
+        this._log(`Agent initialized`);
+    }
+
+    /**
+     * Execute the agent. Handles lifecycle, timing, and error boundaries.
+     * Do NOT override — implement _execute() instead.
+     */
+    async run() {
+        this._status = 'running';
+        this._startTime = Date.now();
+
+        this._eventBus.emit('agent:started', {
+            agentName: this.name,
+            timestamp: new Date().toISOString(),
+        });
+        this._log(`Agent started`);
+
+        try {
+            await this._execute(this._context);
+            this._status = 'done';
+            this._endTime = Date.now();
+
+            this._eventBus.emit('agent:completed', {
+                agentName: this.name,
+                timestamp: new Date().toISOString(),
+                duration: this.duration,
+                findingsCount: this._findings.length,
+            });
+            this._log(`Agent completed — ${this._findings.length} findings in ${this.duration}ms`);
+
+        } catch (error) {
+            this._status = 'error';
+            this._endTime = Date.now();
+
+            this._eventBus.emit('agent:error', {
+                agentName: this.name,
+                error: error.message,
+                timestamp: new Date().toISOString(),
+            });
+            this._log(`Agent error: ${error.message}`, 'error');
+            throw error;
+        }
+    }
+
+    /**
+     * Cleanup resources. Override in subclass if needed.
+     */
+    async cleanup() {
+        // Default: no-op. Subclasses can override for resource cleanup.
+    }
+
+    /**
+     * Main execution logic. Must be implemented by subclass.
+     */
+    async _execute(_context) {
+        throw new Error(`${this.name} must implement _execute()`);
+    }
+
+    /**
+     * Add a finding to this agent's collection and publish it.
+     */
+    addFinding(finding) {
+        this._findings.push(finding);
+        this._eventBus.emit('finding:new', {
+            finding,
+            agentName: this.name,
+        });
+    }
+
+    /**
+     * Add multiple findings at once.
+     */
+    addFindings(findings) {
+        for (const f of findings) {
+            this.addFinding(f);
+        }
+    }
+
+    /**
+     * Emit a progress update for UI consumption.
+     */
+    progress(phase, message, percent = null) {
+        this._eventBus.emit('agent:progress', {
+            agentName: this.name,
+            phase,
+            message,
+            progress: percent,
+        });
+    }
+
+    /**
+     * Internal logging helper.
+     */
+    _log(message, level = 'info') {
+        if (this._logger?.[level]) {
+            this._logger[level](`[${this.name}] ${message}`);
+        }
+    }
+}
+
+export default BaseAgent;

package/src/agents/crawl-agent.js

@@ -0,0 +1,175 @@
+import { BaseAgent } from './base-agent.js';
+import { Crawler } from '../core/crawler.js';
+
+/**
+ * JAKU-CRAWL — Discovery Agent
+ * 
+ * The first agent to run. Crawls the target URL to build a complete
+ * surface inventory (pages, forms, API endpoints, console errors).
+ * 
+ * Authentication is handled by the CLI before agents start.
+ * The pre-authenticated AuthManager is available via config._authManager.
+ * 
+ * Crawl flow:
+ *   1. Crawl unauthenticated surfaces first
+ *   2. Re-crawl with each authenticated role to discover auth-gated pages
+ *   3. Merge all surfaces into a unified inventory
+ * 
+ * Dependencies: none
+ */
+export class CrawlAgent extends BaseAgent {
+    get name() { return 'JAKU-CRAWL'; }
+    get dependencies() { return []; }
+
+    async _execute(context) {
+        const { config, logger } = context;
+
+        // Auth manager is pre-initialized by the CLI
+        const authManager = config._authManager || null;
+        context.authManager = authManager;
+
+        // ═══ Phase 1: Unauthenticated Crawl ═══
+        this.progress('crawl', 'Starting unauthenticated crawl...', 10);
+
+        const unauthCrawler = new Crawler(config, logger);
+        const unauthInventory = await unauthCrawler.crawl(config.target_url);
+
+        // ═══ Phase 2: Authenticated Crawls (one per role) ═══
+        const authInventories = new Map();
+
+        if (authManager?.isAuthenticated) {
+            const roles = authManager.roles;
+            for (let i = 0; i < roles.length; i++) {
+                const role = roles[i];
+                const pct = 20 + Math.floor((i / roles.length) * 60);
+                this.progress('crawl', `Crawling as "${role}"...`, pct);
+
+                try {
+                    const authState = authManager.getAuthState(role);
+                    const postLoginUrl = authManager.getPostLoginUrl(role);
+                    const seedLinks = authManager.getDiscoveredLinks(role);
+
+                    // Start from the post-login URL if available (e.g., /dashboard),
+                    // otherwise fall back to the target URL
+                    const startUrl = postLoginUrl || config.target_url;
+
+                    const authCrawler = new Crawler(config, logger);
+                    const authInv = await authCrawler.crawl(startUrl, authState, seedLinks);
+
+                    authInventories.set(role, authInv);
+                    logger?.info?.(`[JAKU-CRAWL] Authenticated crawl as "${role}": ${authInv.totalPages} pages, ${authInv.totalApis} APIs (started from ${startUrl})`);
+                } catch (err) {
+                    logger?.warn?.(`[JAKU-CRAWL] Authenticated crawl failed for "${role}": ${err.message}`);
+                }
+            }
+        }
+
+        // ═══ Phase 3: Merge Inventories ═══
+        const mergedInventory = this._mergeInventories(unauthInventory, authInventories);
+
+        // Store inventory in shared context for downstream agents
+        context.surfaceInventory = mergedInventory;
+
+        // Broadcast discovery to all listening agents
+        context.eventBus.emit('surface:discovered', {
+            inventory: mergedInventory,
+            agentName: this.name,
+        });
+
+        this.progress('crawl', `Discovery complete: ${mergedInventory.totalPages} pages, ${mergedInventory.totalApis} APIs, ${mergedInventory.totalForms} forms`, 100);
+
+        this._log(`Surface inventory: ${mergedInventory.totalPages} pages, ${mergedInventory.totalApis} APIs, ${mergedInventory.totalForms} forms`);
+
+        if (authManager?.isAuthenticated) {
+            this._log(`Authenticated roles: ${authManager.roles.join(', ')}`);
+
+            // Count auth-only surfaces
+            const unauthUrls = new Set(unauthInventory.pages.map(p => p.url));
+            const authOnlyPages = mergedInventory.pages.filter(p => !unauthUrls.has(p.url));
+            if (authOnlyPages.length > 0) {
+                this._log(`Auth-only pages discovered: ${authOnlyPages.length}`);
+            }
+        }
+    }
+
+    /**
+     * Merge unauthenticated and authenticated inventories into one.
+     * Deduplicates pages by URL, keeping the most informative version.
+     */
+    _mergeInventories(unauthInv, authInventories) {
+        const pageMap = new Map();
+        const apiMap = new Map();
+        const formMap = new Map();
+
+        const addPages = (pages, role = null) => {
+            for (const page of pages) {
+                const key = page.url;
+                if (!pageMap.has(key)) {
+                    pageMap.set(key, { ...page, roles: role ? [role] : ['anonymous'] });
+                } else {
+                    const existing = pageMap.get(key);
+                    if (role && !existing.roles.includes(role)) {
+                        existing.roles.push(role);
+                    }
+                }
+            }
+        };
+
+        const addApis = (apis, role = null) => {
+            for (const api of apis) {
+                const key = `${api.method}::${api.url}`;
+                if (!apiMap.has(key)) {
+                    apiMap.set(key, { ...api, roles: role ? [role] : ['anonymous'] });
+                } else {
+                    const existing = apiMap.get(key);
+                    if (role && !existing.roles.includes(role)) {
+                        existing.roles.push(role);
+                    }
+                }
+            }
+        };
+
+        const addForms = (forms, role = null) => {
+            for (const form of forms) {
+                const key = `${form.method}::${form.action}`;
+                if (!formMap.has(key)) {
+                    formMap.set(key, { ...form, roles: role ? [role] : ['anonymous'] });
+                } else {
+                    const existing = formMap.get(key);
+                    if (role && !existing.roles.includes(role)) {
+                        existing.roles.push(role);
+                    }
+                }
+            }
+        };
+
+        addPages(unauthInv.pages);
+        addApis(unauthInv.apiEndpoints || []);
+        addForms(unauthInv.forms || []);
+
+        for (const [role, inv] of authInventories) {
+            addPages(inv.pages, role);
+            addApis(inv.apiEndpoints || [], role);
+            addForms(inv.forms || [], role);
+        }
+
+        const pages = [...pageMap.values()];
+        const apiEndpoints = [...apiMap.values()];
+        const forms = [...formMap.values()];
+
+        return {
+            baseUrl: unauthInv.baseUrl,
+            pages,
+            apiEndpoints,
+            forms,
+            totalPages: pages.length,
+            totalApis: apiEndpoints.length,
+            totalForms: forms.length,
+            crawledAt: new Date().toISOString(),
+            authenticated: authInventories.size > 0,
+            roles: ['anonymous', ...authInventories.keys()],
+        };
+    }
+}
+
+export default CrawlAgent;

package/src/agents/event-bus.js

@@ -0,0 +1,59 @@
+import EventEmitter from 'events';
+
+/**
+ * EventBus — Central message bus for inter-agent communication.
+ * 
+ * Event types:
+ *   agent:registered   { agentName }
+ *   agent:started      { agentName, timestamp }
+ *   agent:progress     { agentName, phase, message, progress }
+ *   agent:completed    { agentName, timestamp, duration, findingsCount }
+ *   agent:error        { agentName, error, timestamp }
+ *   finding:new        { finding, agentName }
+ *   surface:discovered { inventory, agentName }
+ *   scan:started       { timestamp, modules }
+ *   scan:completed     { timestamp, duration, totalFindings }
+ */
+export class EventBus extends EventEmitter {
+    constructor() {
+        super();
+        this.setMaxListeners(50);
+        this._log = [];
+    }
+
+    /**
+     * Emit an event and record it in the audit log.
+     */
+    emit(event, data = {}) {
+        const entry = {
+            event,
+            data,
+            timestamp: new Date().toISOString(),
+        };
+        this._log.push(entry);
+        return super.emit(event, data);
+    }
+
+    /**
+     * Get the full event log for audit/debugging.
+     */
+    getLog() {
+        return [...this._log];
+    }
+
+    /**
+     * Get events filtered by type.
+     */
+    getEvents(eventType) {
+        return this._log.filter(e => e.event === eventType);
+    }
+
+    /**
+     * Clear the event log.
+     */
+    clearLog() {
+        this._log = [];
+    }
+}
+
+export default EventBus;