sdlc-agent-4-enterprise-server 1.0.0

package/src/modules/web/handlers/DownloadFileHandler.ts

@@ -0,0 +1,66 @@
+/**
+ * Handler for download_file tool.
+ * Downloads files with size/extension validation.
+ */
+
+import type { ToolResult } from '../../../types/tool.js';
+import type { WebModuleConfig } from '../models/WebModuleConfig.js';
+import { SsrfGuard } from '../middleware/SsrfGuard.js';
+import { RateLimiter } from '../middleware/RateLimiter.js';
+import { validateUrl } from '../utils/UrlValidator.js';
+import { WebToolError } from '../models/WebError.js';
+import { successResult, errorResult } from '../models/WebToolResult.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+
+export class DownloadFileHandler {
+  constructor(private ssrfGuard: SsrfGuard, private rateLimiter: RateLimiter, private config: WebModuleConfig) {}
+
+  async handle(args: Record<string, unknown>): Promise<ToolResult> {
+    try {
+      const url = args.url as string;
+      const destPath = args.dest_path as string | undefined;
+      validateUrl(url);
+      await this.ssrfGuard.validate(url);
+      this.rateLimiter.consumeOrThrow('download_file');
+      const filename = this.resolveFilename(url, destPath);
+      this.validateExtension(filename);
+      const fullPath = this.resolvePath(filename);
+      const res = await fetch(url, { headers: { 'User-Agent': this.config.userAgent }, signal: AbortSignal.timeout(this.config.timeoutMs) });
+      if (!res.ok) throw new WebToolError('TIMEOUT', `Download failed: ${res.status}`);
+      const cl = parseInt(res.headers.get('content-length') || '0', 10);
+      if (cl > this.config.maxDownloadMb * 1024 * 1024) throw new WebToolError('CONTENT_TOO_LARGE', `File too large (max ${this.config.maxDownloadMb}MB)`);
+      const dir = path.dirname(fullPath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      if (res.body) { const s = Readable.fromWeb(res.body as never); await pipeline(s, fs.createWriteStream(fullPath)); }
+      const stats = fs.statSync(fullPath);
+      return successResult({ path: path.relative(this.config.workspace, fullPath), filename: path.basename(fullPath), size: stats.size, content_type: res.headers.get('content-type') || '' });
+    } catch (err) {
+      if (err instanceof WebToolError) return errorResult(err);
+      return errorResult(new WebToolError('TIMEOUT', (err as Error).message));
+    }
+  }
+
+  private resolveFilename(url: string, destPath?: string): string {
+    if (destPath) return destPath;
+    const urlPath = new URL(url).pathname;
+    return path.basename(urlPath) || 'download';
+  }
+
+  private validateExtension(filename: string): void {
+    const ext = path.extname(filename).toLowerCase();
+    if (this.config.blockedExtensions.includes(ext)) {
+      throw new WebToolError('BLOCKED_EXTENSION', `Blocked file type: ${ext}`);
+    }
+  }
+
+  private resolvePath(filename: string): string {
+    const resolved = path.resolve(this.config.workspace, filename);
+    if (!resolved.startsWith(this.config.workspace)) {
+      throw new WebToolError('INVALID_URL', 'Path must be within workspace');
+    }
+    return resolved;
+  }
+}

package/src/modules/web/handlers/FetchUrlHandler.ts

@@ -0,0 +1,93 @@
+/**
+ * Handler for the fetch_url tool.
+ * Fetches content from URLs with modes: full, truncated, selective.
+ */
+
+import type { ToolResult } from '../../../types/tool.js';
+import type { WebModuleConfig } from '../models/WebModuleConfig.js';
+import { SsrfGuard } from '../middleware/SsrfGuard.js';
+import { RateLimiter } from '../middleware/RateLimiter.js';
+import { ContentTruncator } from '../middleware/ContentTruncator.js';
+import { HtmlExtractor } from '../utils/HtmlExtractor.js';
+import { validateUrl } from '../utils/UrlValidator.js';
+import { WebToolError } from '../models/WebError.js';
+import { successResult, errorResult } from '../models/WebToolResult.js';
+
+export class FetchUrlHandler {
+  private htmlExtractor = new HtmlExtractor();
+
+  constructor(
+    private ssrfGuard: SsrfGuard,
+    private rateLimiter: RateLimiter,
+    private truncator: ContentTruncator,
+    private config: WebModuleConfig,
+  ) {}
+
+  async handle(args: Record<string, unknown>): Promise<ToolResult> {
+    try {
+      const url = args.url as string;
+      const mode = (args.mode as string) || 'full';
+      const maxLength = args.max_length as number | undefined;
+      const selector = args.selector as string | undefined;
+
+      validateUrl(url);
+      await this.ssrfGuard.validate(url);
+      this.rateLimiter.consumeOrThrow('fetch_url');
+
+      const response = await this.fetchWithTimeout(url);
+      const body = await response.text();
+      const content = this.processContent(body, mode, maxLength, selector);
+      const result = this.truncator.truncate(content, maxLength);
+
+      return successResult({
+        content: result.content,
+        metadata: {
+          status_code: response.status,
+          content_type: response.headers.get('content-type') || '',
+          content_length: result.originalLength,
+          title: this.extractTitle(body),
+          truncated: result.truncated,
+          url: response.url,
+        },
+      });
+    } catch (err) {
+      if (err instanceof WebToolError) return errorResult(err);
+      return errorResult(new WebToolError('TIMEOUT', (err as Error).message));
+    }
+  }
+
+  private async fetchWithTimeout(url: string): Promise<Response> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      return await fetch(url, {
+        signal: controller.signal,
+        headers: { 'User-Agent': this.config.userAgent },
+        redirect: 'follow',
+      });
+    } catch (err) {
+      if ((err as Error).name === 'AbortError') {
+        throw new WebToolError('TIMEOUT', `Request timed out after ${this.config.timeoutMs}ms`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private processContent(body: string, mode: string, maxLength?: number, selector?: string): string {
+    switch (mode) {
+      case 'selective':
+        return selector ? this.htmlExtractor.extractBySelector(body, selector) : this.htmlExtractor.toText(body);
+      case 'truncated':
+        return this.htmlExtractor.toText(body).slice(0, maxLength || 50000);
+      default:
+        return this.htmlExtractor.toText(body);
+    }
+  }
+
+  private extractTitle(html: string): string {
+    const match = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+    return match ? match[1].trim() : '';
+  }
+}

package/src/modules/web/handlers/GitBrowseHandler.ts

@@ -0,0 +1,70 @@
+/**
+ * Handler for git_clone_browse tool.
+ * Browses GitHub/GitLab repos via REST API.
+ */
+
+import type { ToolResult } from '../../../types/tool.js';
+import type { WebModuleConfig } from '../models/WebModuleConfig.js';
+import { RateLimiter } from '../middleware/RateLimiter.js';
+import { parseGitUrl } from '../utils/GitUrlParser.js';
+import { WebToolError } from '../models/WebError.js';
+import { successResult, errorResult } from '../models/WebToolResult.js';
+
+export class GitBrowseHandler {
+  constructor(private rateLimiter: RateLimiter, private config: WebModuleConfig) {}
+
+  async handle(args: Record<string, unknown>): Promise<ToolResult> {
+    try {
+      const repoUrl = args.repo_url as string;
+      const operation = (args.operation as string) || 'readme';
+      const filePath = args.path as string | undefined;
+      const ref = (args.ref as string) || 'HEAD';
+      const token = args.token as string | undefined;
+      this.rateLimiter.consumeOrThrow('git_clone_browse');
+      const parsed = parseGitUrl(repoUrl);
+      const headers: Record<string, string> = { 'User-Agent': this.config.userAgent };
+      if (token) headers['Authorization'] = `Bearer ${token}`;
+
+      if (parsed.host === 'github.com') {
+        return await this.github(parsed.owner, parsed.repo, operation, filePath, ref, headers);
+      }
+      return await this.gitlab(parsed.owner, parsed.repo, operation, filePath, ref, headers);
+    } catch (err) {
+      if (err instanceof WebToolError) return errorResult(err);
+      return errorResult(new WebToolError('TIMEOUT', (err as Error).message));
+    }
+  }
+
+  private async github(owner: string, repo: string, op: string, path?: string, ref?: string, headers?: Record<string, string>): Promise<ToolResult> {
+    const base = `https://api.github.com/repos/${owner}/${repo}`;
+    const url = op === 'tree' ? `${base}/git/trees/${ref}?recursive=1`
+      : op === 'read_file' ? `${base}/contents/${path}?ref=${ref}` : `${base}/readme`;
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(this.config.timeoutMs) });
+    if (res.status === 404) throw new WebToolError('DNS_FAILED', 'Repository or file not found');
+    if (!res.ok) throw new WebToolError('TIMEOUT', `GitHub API error: ${res.status}`);
+    const data = await res.json() as Record<string, unknown>;
+    return successResult(this.formatGH(op, data, owner, repo, ref));
+  }
+
+  private async gitlab(owner: string, repo: string, op: string, path?: string, ref?: string, headers?: Record<string, string>): Promise<ToolResult> {
+    const pid = encodeURIComponent(`${owner}/${repo}`);
+    const base = `https://gitlab.com/api/v4/projects/${pid}/repository`;
+    const url = op === 'tree' ? `${base}/tree?recursive=true&ref=${ref}`
+      : op === 'read_file' ? `${base}/files/${encodeURIComponent(path || '')}/raw?ref=${ref}`
+      : `${base}/files/README.md/raw?ref=${ref || 'main'}`;
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(this.config.timeoutMs) });
+    if (res.status === 404) throw new WebToolError('DNS_FAILED', 'Not found');
+    if (!res.ok) throw new WebToolError('TIMEOUT', `GitLab error: ${res.status}`);
+    const content = op === 'tree' ? await res.json() : await res.text();
+    return successResult({ content, repo: `${owner}/${repo}`, ref });
+  }
+
+  private formatGH(op: string, data: Record<string, unknown>, owner: string, repo: string, ref?: string): unknown {
+    if (op === 'tree') {
+      const tree = (data.tree as Array<{ path: string; type: string; size?: number }>) || [];
+      return { tree: tree.map(f => ({ path: f.path, type: f.type, size: f.size })), repo: `${owner}/${repo}`, ref, total_files: tree.length };
+    }
+    const content = data.encoding === 'base64' ? Buffer.from(data.content as string, 'base64').toString() : data.content;
+    return { content, path: data.path, size: data.size, encoding: 'utf-8' };
+  }
+}

package/src/modules/web/handlers/ReadWebpageHandler.ts

@@ -0,0 +1,59 @@
+/**
+ * Handler for read_webpage tool. Renders JS pages via Playwright.
+ */
+
+import type { ToolResult } from '../../../types/tool.js';
+import type { WebModuleConfig } from '../models/WebModuleConfig.js';
+import { SsrfGuard } from '../middleware/SsrfGuard.js';
+import { RateLimiter } from '../middleware/RateLimiter.js';
+import { ContentTruncator } from '../middleware/ContentTruncator.js';
+import { validateUrl } from '../utils/UrlValidator.js';
+import { WebToolError } from '../models/WebError.js';
+import { successResult, errorResult } from '../models/WebToolResult.js';
+import type { Browser } from 'playwright';
+
+export class ReadWebpageHandler {
+  private browser: Browser | null = null;
+  private activeContexts = 0;
+
+  constructor(private ssrfGuard: SsrfGuard, private rateLimiter: RateLimiter, private truncator: ContentTruncator, private config: WebModuleConfig) {}
+
+  async handle(args: Record<string, unknown>): Promise<ToolResult> {
+    try {
+      const url = args.url as string;
+      const waitFor = (args.wait_for as string) || 'networkidle';
+      const selector = args.selector as string | undefined;
+      const timeout = (args.timeout as number) || this.config.timeoutMs;
+      const blockRes = (args.block_resources as string[]) || ['image', 'font', 'media'];
+      validateUrl(url);
+      await this.ssrfGuard.validate(url);
+      this.rateLimiter.consumeOrThrow('read_webpage');
+      if (this.activeContexts >= this.config.maxBrowserContexts) throw new WebToolError('RATE_LIMITED', 'Max browser contexts reached');
+
+      const browser = await this.getBrowser();
+      const ctx = await browser.newContext({ userAgent: this.config.userAgent });
+      this.activeContexts++;
+      try {
+        const page = await ctx.newPage();
+        await page.route('**/*', r => blockRes.includes(r.request().resourceType()) ? r.abort() : r.continue());
+        const wt = waitFor === 'networkidle' ? 'networkidle' : waitFor === 'load' ? 'load' : 'domcontentloaded';
+        await page.goto(url, { timeout, waitUntil: wt as never });
+        if (waitFor === 'selector' && selector) await page.waitForSelector(selector, { timeout });
+        const content = selector ? (await page.locator(selector).textContent()) || '' : await page.innerText('body');
+        const title = await page.title();
+        const truncated = this.truncator.truncate(content);
+        return successResult({ content: truncated.content, title, url: page.url(), metadata: { partial: truncated.truncated } });
+      } finally { await ctx.close(); this.activeContexts--; }
+    } catch (err) {
+      if (err instanceof WebToolError) return errorResult(err);
+      return errorResult(new WebToolError('BROWSER_FAILED', (err as Error).message));
+    }
+  }
+
+  private async getBrowser(): Promise<Browser> {
+    if (!this.browser) { const { chromium } = await import('playwright'); this.browser = await chromium.launch({ headless: true }); }
+    return this.browser;
+  }
+
+  async shutdown(): Promise<void> { if (this.browser) { await this.browser.close(); this.browser = null; } }
+}

package/src/modules/web/handlers/WebSearchHandler.ts

@@ -0,0 +1,50 @@
+/**
+ * Handler for the web_search tool.
+ * Searches via SearXNG with DuckDuckGo fallback.
+ */
+
+import type { ToolResult } from '../../../types/tool.js';
+import type { WebModuleConfig } from '../models/WebModuleConfig.js';
+import { RateLimiter } from '../middleware/RateLimiter.js';
+import { WebToolError } from '../models/WebError.js';
+import { successResult, errorResult } from '../models/WebToolResult.js';
+
+interface SearchResult { title: string; url: string; snippet: string; }
+
+export class WebSearchHandler {
+  constructor(private rateLimiter: RateLimiter, private config: WebModuleConfig) {}
+
+  async handle(args: Record<string, unknown>): Promise<ToolResult> {
+    try {
+      const query = args.query as string;
+      if (!query?.trim()) throw new WebToolError('INVALID_URL', 'Search query cannot be empty');
+      const numResults = Math.min((args.num_results as number) || 5, 10);
+      const category = (args.category as string) || 'general';
+      const language = (args.language as string) || 'en';
+      this.rateLimiter.consumeOrThrow('web_search');
+
+      const results = await this.searchSearXNG(query, numResults, category, language)
+        .catch(() => this.searchDuckDuckGo(query, numResults));
+      return successResult({ results, total_found: results.length, search_engine: 'searxng' });
+    } catch (err) {
+      if (err instanceof WebToolError) return errorResult(err);
+      return errorResult(new WebToolError('TIMEOUT', (err as Error).message));
+    }
+  }
+
+  private async searchSearXNG(query: string, num: number, cat: string, lang: string): Promise<SearchResult[]> {
+    const url = `${this.config.searxngUrl}/search?q=${encodeURIComponent(query)}&format=json&categories=${cat}&language=${lang}`;
+    const res = await fetch(url, { signal: AbortSignal.timeout(this.config.timeoutMs) });
+    if (!res.ok) throw new Error(`SearXNG error: ${res.status}`);
+    const data = await res.json() as { results: Array<{ title: string; url: string; content: string }> };
+    return (data.results || []).slice(0, num).map(r => ({ title: r.title, url: r.url, snippet: r.content }));
+  }
+
+  private async searchDuckDuckGo(query: string, num: number): Promise<SearchResult[]> {
+    const url = `https://api.duckduckgo.com/?q=${encodeURIComponent(query)}&format=json&no_html=1`;
+    const res = await fetch(url, { signal: AbortSignal.timeout(this.config.timeoutMs) });
+    if (!res.ok) throw new WebToolError('TIMEOUT', 'Search service temporarily unavailable');
+    const data = await res.json() as { RelatedTopics: Array<{ Text: string; FirstURL: string }> };
+    return (data.RelatedTopics || []).slice(0, num).map(r => ({ title: r.Text?.slice(0, 60) || '', url: r.FirstURL || '', snippet: r.Text || '' }));
+  }
+}

package/src/modules/web/middleware/ContentTruncator.ts

@@ -0,0 +1,31 @@
+/**
+ * Content size enforcement middleware.
+ * Truncates responses exceeding configured maximum size.
+ */
+
+export interface TruncateResult {
+  content: string;
+  truncated: boolean;
+  originalLength: number;
+}
+
+export class ContentTruncator {
+  private maxBytes: number;
+
+  constructor(maxKb: number) {
+    this.maxBytes = maxKb * 1024;
+  }
+
+  truncate(content: string, customMax?: number): TruncateResult {
+    const limit = customMax ?? this.maxBytes;
+    const originalLength = content.length;
+    if (content.length <= limit) {
+      return { content, truncated: false, originalLength };
+    }
+    return {
+      content: content.slice(0, limit),
+      truncated: true,
+      originalLength,
+    };
+  }
+}

package/src/modules/web/middleware/RateLimiter.ts

@@ -0,0 +1,70 @@
+/**
+ * Token bucket rate limiter for WebModule tools.
+ * Each tool gets an independent bucket with configurable RPM.
+ */
+
+import { WebToolError } from '../models/WebError.js';
+
+interface TokenBucket {
+  tokens: number;
+  maxTokens: number;
+  refillRate: number;
+  lastRefill: number;
+}
+
+export interface ConsumeResult {
+  allowed: boolean;
+  remaining: number;
+  resetMs: number;
+}
+
+export class RateLimiter {
+  private buckets = new Map<string, TokenBucket>();
+  private maxTokens: number;
+  private refillRate: number;
+
+  constructor(rpm: number) {
+    this.maxTokens = rpm;
+    this.refillRate = rpm / 60_000;
+  }
+
+  consume(toolName: string): ConsumeResult {
+    const bucket = this.getBucket(toolName);
+    this.refill(bucket);
+    if (bucket.tokens >= 1) {
+      bucket.tokens -= 1;
+      return { allowed: true, remaining: Math.floor(bucket.tokens), resetMs: 0 };
+    }
+    const resetMs = Math.ceil((1 - bucket.tokens) / this.refillRate);
+    return { allowed: false, remaining: 0, resetMs };
+  }
+
+  consumeOrThrow(toolName: string): void {
+    const result = this.consume(toolName);
+    if (!result.allowed) {
+      throw new WebToolError('RATE_LIMITED',
+        `Rate limit exceeded. Reset in ${Math.ceil(result.resetMs / 1000)}s`,
+        { remaining: 0, resetMs: result.resetMs });
+    }
+  }
+
+  private getBucket(toolName: string): TokenBucket {
+    if (!this.buckets.has(toolName)) {
+      this.buckets.set(toolName, {
+        tokens: this.maxTokens,
+        maxTokens: this.maxTokens,
+        refillRate: this.refillRate,
+        lastRefill: Date.now(),
+      });
+    }
+    return this.buckets.get(toolName)!;
+  }
+
+  private refill(bucket: TokenBucket): void {
+    const now = Date.now();
+    const elapsed = now - bucket.lastRefill;
+    const tokensToAdd = elapsed * bucket.refillRate;
+    bucket.tokens = Math.min(bucket.maxTokens, bucket.tokens + tokensToAdd);
+    bucket.lastRefill = now;
+  }
+}

package/src/modules/web/middleware/SsrfGuard.ts

@@ -0,0 +1,82 @@
+/**
+ * SSRF (Server-Side Request Forgery) protection middleware.
+ * Validates URLs against blocklisted IP ranges and protocols.
+ */
+
+import { WebToolError } from '../models/WebError.js';
+import * as dns from 'dns/promises';
+import * as net from 'net';
+
+export class SsrfGuard {
+  private blocklist: string[];
+  private allowedProtocols = new Set(['http:', 'https:']);
+
+  constructor(blocklist: string[]) {
+    this.blocklist = blocklist;
+  }
+
+  async validate(urlStr: string): Promise<string> {
+    const url = this.parseUrl(urlStr);
+    this.checkProtocol(url);
+    const ip = await this.resolveHost(url.hostname);
+    this.checkIp(ip);
+    return ip;
+  }
+
+  isBlocked(ip: string): boolean {
+    return this.isPrivateIp(ip);
+  }
+
+  private parseUrl(urlStr: string): URL {
+    try { return new URL(urlStr); }
+    catch { throw new WebToolError('INVALID_URL', `Invalid URL: ${urlStr}`); }
+  }
+
+  private checkProtocol(url: URL): void {
+    if (!this.allowedProtocols.has(url.protocol)) {
+      throw new WebToolError('INVALID_URL', `Protocol not allowed: ${url.protocol}`);
+    }
+  }
+
+  private async resolveHost(hostname: string): Promise<string> {
+    if (net.isIP(hostname)) return hostname;
+    try {
+      const addrs = await dns.resolve4(hostname);
+      if (!addrs.length) throw new WebToolError('DNS_FAILED', `No addresses: ${hostname}`);
+      return addrs[0];
+    } catch (err) {
+      if (err instanceof WebToolError) throw err;
+      throw new WebToolError('DNS_FAILED', `Cannot resolve: ${hostname}`);
+    }
+  }
+
+  private checkIp(ip: string): void {
+    if (this.isPrivateIp(ip)) {
+      throw new WebToolError('SSRF_BLOCKED', `Blocked internal IP: ${ip}`, { ip });
+    }
+  }
+
+  private isPrivateIp(ip: string): boolean {
+    if (net.isIPv6(ip)) return this.isPrivateIpv6(ip);
+    return this.isPrivateIpv4(ip);
+  }
+
+  private isPrivateIpv4(ip: string): boolean {
+    const parts = ip.split('.').map(Number);
+    if (parts[0] === 127) return true;
+    if (parts[0] === 10) return true;
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return true;
+    if (parts[0] === 192 && parts[1] === 168) return true;
+    if (parts[0] === 169 && parts[1] === 254) return true;
+    if (parts[0] === 0) return true;
+    return false;
+  }
+
+  private isPrivateIpv6(ip: string): boolean {
+    const normalized = ip.toLowerCase();
+    if (normalized === '::1') return true;
+    if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true;
+    if (normalized.startsWith('fe80')) return true;
+    return false;
+  }
+}

package/src/modules/web/models/WebError.ts

@@ -0,0 +1,25 @@
+/**
+ * Custom error class for WebModule tools.
+ * Each error carries a machine-readable code for consistent error responses.
+ */
+
+export type WebErrorCode =
+  | 'SSRF_BLOCKED'
+  | 'RATE_LIMITED'
+  | 'TIMEOUT'
+  | 'CONTENT_TOO_LARGE'
+  | 'INVALID_URL'
+  | 'DNS_FAILED'
+  | 'BLOCKED_EXTENSION'
+  | 'BROWSER_FAILED';
+
+export class WebToolError extends Error {
+  constructor(
+    public readonly code: WebErrorCode,
+    message: string,
+    public readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = 'WebToolError';
+  }
+}

package/src/modules/web/models/WebModuleConfig.ts

@@ -0,0 +1,35 @@
+/**
+ * Configuration interface for WebModule.
+ * All values have sensible defaults, overridable via environment variables.
+ */
+
+export interface WebModuleConfig {
+  searxngUrl: string;
+  rateLimitRpm: number;
+  timeoutMs: number;
+  maxResponseKb: number;
+  maxDownloadMb: number;
+  maxBrowserContexts: number;
+  blockedExtensions: string[];
+  ssrfBlocklist: string[];
+  userAgent: string;
+  workspace: string;
+}
+
+export function loadWebConfig(workspace: string): WebModuleConfig {
+  return {
+    searxngUrl: process.env.WEB_SEARXNG_URL || 'http://localhost:8080',
+    rateLimitRpm: parseInt(process.env.WEB_RATE_LIMIT_RPM || '10', 10),
+    timeoutMs: parseInt(process.env.WEB_TIMEOUT_MS || '30000', 10),
+    maxResponseKb: parseInt(process.env.WEB_MAX_RESPONSE_KB || '100', 10),
+    maxDownloadMb: parseInt(process.env.WEB_MAX_DOWNLOAD_MB || '50', 10),
+    maxBrowserContexts: parseInt(process.env.WEB_MAX_BROWSER_CONTEXTS || '3', 10),
+    blockedExtensions: ['.exe', '.bat', '.cmd', '.ps1', '.sh', '.msi', '.scr'],
+    ssrfBlocklist: [
+      '127.0.0.0/8', '10.0.0.0/8', '172.16.0.0/12',
+      '192.168.0.0/16', '169.254.0.0/16', '::1/128', 'fc00::/7',
+    ],
+    userAgent: process.env.WEB_USER_AGENT || 'Kiro-WebModule/1.0',
+    workspace,
+  };
+}

package/src/modules/web/models/WebToolResult.ts

@@ -0,0 +1,23 @@
+/**
+ * Result type helpers for WebModule tool responses.
+ */
+
+import type { ToolResult } from '../../../types/tool.js';
+import { WebToolError } from './WebError.js';
+
+export function successResult(data: unknown): ToolResult {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    isError: false,
+  };
+}
+
+export function errorResult(error: WebToolError): ToolResult {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({ error: error.code, message: error.message, ...error.details }),
+    }],
+    isError: true,
+  };
+}

package/src/modules/web/utils/GitUrlParser.ts

@@ -0,0 +1,46 @@
+/**
+ * Git URL parser for GitHub/GitLab repositories.
+ * Extracts host, owner, repo, optional path and ref from URLs.
+ */
+
+import { WebToolError } from '../models/WebError.js';
+
+export interface ParsedGitUrl {
+  host: string;
+  owner: string;
+  repo: string;
+  path?: string;
+  ref?: string;
+}
+
+const SUPPORTED_HOSTS = new Set(['github.com', 'gitlab.com']);
+
+export function parseGitUrl(urlStr: string): ParsedGitUrl {
+  let url: URL;
+  try {
+    url = new URL(urlStr);
+  } catch {
+    throw new WebToolError('INVALID_URL', `Cannot parse repository URL: ${urlStr}`);
+  }
+
+  if (!SUPPORTED_HOSTS.has(url.hostname)) {
+    throw new WebToolError('INVALID_URL', `Unsupported git host: ${url.hostname}`);
+  }
+
+  const parts = url.pathname.split('/').filter(Boolean);
+  if (parts.length < 2) {
+    throw new WebToolError('INVALID_URL', `Cannot parse owner/repo from: ${urlStr}`);
+  }
+
+  const owner = parts[0];
+  const repo = parts[1].replace(/\.git$/, '');
+  let path: string | undefined;
+  let ref: string | undefined;
+
+  if (parts.length > 3 && (parts[2] === 'blob' || parts[2] === 'tree')) {
+    ref = parts[3];
+    path = parts.slice(4).join('/') || undefined;
+  }
+
+  return { host: url.hostname, owner, repo, path, ref };
+}