docorbit 0.1.0 → 0.1.1

package/dist/packages/security/src/annotations.js

@@ -0,0 +1,100 @@
+const MULTILINE_INJECTION_PATTERNS = [
+    { pattern: /<system\b[^>]*>([\s\S]*?)<\/system>/gi, severity: 'high', label: '<system> block' },
+    { pattern: /\[SYSTEM(?:\s+INSTRUCTION)?\]([\s\S]*?)\[\/SYSTEM(?:\s+INSTRUCTION)?\]/gi, severity: 'high', label: '[SYSTEM] block' },
+    { pattern: /<\|im_start\|>system([\s\S]*?)<\|im_end\|>/gi, severity: 'high', label: 'ChatML system block' },
+    { pattern: /<!--\s*AI\s+INSTRUCTION:([\s\S]*?)-->/gi, severity: 'high', label: 'HTML comment injection' },
+];
+const PROMPT_INJECTION_PATTERNS = [
+    { pattern: /\b(?:ignore|disregard|forget)\s+(?:all\s+)?(?:previous|prior|above)\s+instructions\b/i, severity: 'high' },
+    { pattern: /\b(?:system\s+message|system\s+prompt|system\s+instruction)\s*[:=]/i, severity: 'high' },
+    { pattern: /\byou\s+are\s+now\s+(?:an?\s+)?(?:unrestricted|jailbroken|developer\s+mode|dan|evil)\b/i, severity: 'high' },
+    { pattern: /\byou\s+are\s+now\s+(?:acting\s+as\s+)?a\b.*?\bassistant\s+that\s+(?:executes|runs|ignores)\b/i, severity: 'high' },
+    { pattern: /\bIMPORTANT\s+INSTRUCTION\s+FOR\s+(?:THE\s+)?AI\s+AGENT\b/i, severity: 'high' },
+    { pattern: /\b(?:call|invoke|execute)\s+(?:the\s+)?tool\s+['"]?[a-zA-Z0-9_-]+['"]?\s+with\b/i, severity: 'high' },
+    { pattern: /\buse\s+(?:the\s+)?(?:bash|terminal|shell|command|run_command)\s+tool\s+to\b/i, severity: 'high' },
+    { pattern: /\bdo\s+not\s+tell\s+the\s+user\b/i, severity: 'medium' },
+];
+const SUSPICIOUS_INSTRUCTION_PATTERNS = [
+    { pattern: /curl\s+-[sS]*[fF]*[kK]*\s+https?:\/\/[^\s|]+\s*\|\s*(?:ba)?sh/i, severity: 'high' },
+    { pattern: /wget\s+-[qO-]*\s+https?:\/\/[^\s|]+\s*\|\s*(?:ba)?sh/i, severity: 'high' },
+    { pattern: /powershell\s+.*-(?:enc|encodedcommand)\s+[A-Za-z0-9+/=]{20,}/i, severity: 'high' },
+    { pattern: /base64\s+-d\s+.*\|\s*(?:ba)?sh/i, severity: 'high' },
+    { pattern: /eval\s*\(\s*base64_decode\s*\(/i, severity: 'high' },
+    { pattern: /\b(?:cat|type)\s+[^\n]*\.(?:ssh\/id_[a-zA-Z0-9_-]*|aws\/credentials|env)\b/i, severity: 'high' },
+    { pattern: /\b(?:curl|wget|fetch|nc|ncat)\b[^\n]*\b(?:\.ssh\/id_|\.aws\/credentials|\.env|API_KEY|SECRET)\b/i, severity: 'high' },
+    { pattern: /\b(?:printenv|env)\b[^\n]*\|\s*(?:curl|nc|wget|base64)/i, severity: 'high' },
+];
+const UNSAFE_LINK_PATTERNS = [
+    { pattern: /\[[^\]]*\]\(((?:javascript|data|file):[\s\S]*?)\)(?:\.|\s|$)/i, severity: 'high' },
+];
+/**
+ * Scans documentation content for security hazards (prompt injection,
+ * malicious execution snippets, unsafe links, credential harvesting) and returns
+ * non-destructive annotations.
+ *
+ * Principle: External documentation is treated as untrusted data and structurally
+ * separated from agent instructions. Original documentation text is never altered.
+ */
+export function detectSecurityAnnotations(content) {
+    const annotations = [];
+    if (!content)
+        return annotations;
+    // 1. Multiline patterns across whole content
+    for (const rule of MULTILINE_INJECTION_PATTERNS) {
+        let match;
+        const regex = new RegExp(rule.pattern.source, rule.pattern.flags);
+        while ((match = regex.exec(content)) !== null) {
+            const matchStart = match.index;
+            const lineNumber = content.slice(0, matchStart).split('\n').length;
+            annotations.push({
+                type: 'prompt_injection_suspected',
+                location: `Line ${lineNumber} (${rule.label})`,
+                evidence: match[0].slice(0, 150).trim(),
+                severity: rule.severity,
+            });
+        }
+    }
+    // 2. Line-by-line checks
+    const lines = content.split('\n');
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+        const line = lines[lineIdx];
+        const loc = `Line ${lineIdx + 1}`;
+        // Prompt injection checks
+        for (const rule of PROMPT_INJECTION_PATTERNS) {
+            const match = line.match(rule.pattern);
+            if (match) {
+                annotations.push({
+                    type: 'prompt_injection_suspected',
+                    location: loc,
+                    evidence: match[0].trim(),
+                    severity: rule.severity,
+                });
+            }
+        }
+        // Suspicious shell execution / credential theft checks
+        for (const rule of SUSPICIOUS_INSTRUCTION_PATTERNS) {
+            const match = line.match(rule.pattern);
+            if (match) {
+                annotations.push({
+                    type: 'suspicious_instruction',
+                    location: loc,
+                    evidence: match[0].trim(),
+                    severity: rule.severity,
+                });
+            }
+        }
+        // Unsafe link protocols check
+        for (const rule of UNSAFE_LINK_PATTERNS) {
+            const match = line.match(rule.pattern);
+            if (match) {
+                annotations.push({
+                    type: 'unsafe_link',
+                    location: loc,
+                    evidence: match[1] || match[0],
+                    severity: rule.severity,
+                });
+            }
+        }
+    }
+    return annotations;
+}

package/dist/packages/security/src/index.js

@@ -0,0 +1,2 @@
+export * from "./ssrf.js";
+export * from "./annotations.js";

package/dist/packages/security/src/ssrf.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Checks whether an IPv4 or IPv6 address is in a private, link-local, loopback,
+ * or cloud provider metadata range.
+ */
+export declare function isPrivateOrBlockedIp(ip: string): boolean;
+export interface SsrfValidationOptions {
+    allowLocalhostForTesting?: boolean;
+}
+/**
+ * Validates a target URL against SSRF threats:
+ * - Ensures valid HTTP/HTTPS protocol
+ * - Validates hostname does not resolve to private or loopback IP
+ */
+export declare function validateTargetUrl(urlStr: string, options?: SsrfValidationOptions): Promise<{
+    url: URL;
+    resolvedIp: string;
+}>;

package/dist/packages/security/src/ssrf.js

@@ -0,0 +1,132 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { SsrfError } from "../../shared/src/index.js";
+/**
+ * Checks whether an IPv4 or IPv6 address is in a private, link-local, loopback,
+ * or cloud provider metadata range.
+ */
+export function isPrivateOrBlockedIp(ip) {
+    // IPv4 check
+    if (isIP(ip) === 4) {
+        const parts = ip.split('.').map(Number);
+        if (parts.length !== 4 || parts.some(isNaN))
+            return true;
+        const [b0, b1, b2, b3] = parts;
+        // 0.0.0.0/8 (Current network)
+        if (b0 === 0)
+            return true;
+        // 127.0.0.0/8 (Loopback)
+        if (b0 === 127)
+            return true;
+        // 10.0.0.0/8 (RFC 1918 Private)
+        if (b0 === 10)
+            return true;
+        // 172.16.0.0/12 (RFC 1918 Private: 172.16.0.0 - 172.31.255.255)
+        if (b0 === 172 && b1 >= 16 && b1 <= 31)
+            return true;
+        // 192.168.0.0/16 (RFC 1918 Private)
+        if (b0 === 192 && b1 === 168)
+            return true;
+        // 169.254.0.0/16 (Link-local & AWS/GCP/Azure instance metadata 169.254.169.254)
+        if (b0 === 169 && b1 === 254)
+            return true;
+        // 100.64.0.0/10 (Carrier-grade NAT)
+        if (b0 === 100 && b1 >= 64 && b1 <= 127)
+            return true;
+        // 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (TEST-NET-1, 2, 3)
+        if (b0 === 192 && b1 === 0 && b2 === 2)
+            return true;
+        if (b0 === 198 && b1 === 51 && b2 === 100)
+            return true;
+        if (b0 === 203 && b1 === 0 && b2 === 113)
+            return true;
+        // 224.0.0.0/4 (Multicast) & 240.0.0.0/4 (Reserved)
+        if (b0 >= 224)
+            return true;
+        return false;
+    }
+    // IPv6 check
+    if (isIP(ip) === 6) {
+        const normalized = ip.toLowerCase();
+        // ::1 (Loopback)
+        if (normalized === '::1' || normalized === '0:0:0:0:0:0:0:1')
+            return true;
+        // :: (Unspecified)
+        if (normalized === '::' || normalized === '0:0:0:0:0:0:0:0')
+            return true;
+        // fc00::/7 (Unique local addresses / private)
+        if (normalized.startsWith('fc') || normalized.startsWith('fd'))
+            return true;
+        // fe80::/10 (Link-local unicast)
+        if (normalized.startsWith('fe8') || normalized.startsWith('fe9') || normalized.startsWith('fea') || normalized.startsWith('feb')) {
+            return true;
+        }
+        // IPv4-mapped IPv6 addresses (::ffff:x.x.x.x)
+        if (normalized.startsWith('::ffff:')) {
+            const ipv4Part = normalized.slice(7);
+            return isPrivateOrBlockedIp(ipv4Part);
+        }
+        return false;
+    }
+    return true; // Not a recognized IP, block by default
+}
+/**
+ * Validates a target URL against SSRF threats:
+ * - Ensures valid HTTP/HTTPS protocol
+ * - Validates hostname does not resolve to private or loopback IP
+ */
+export async function validateTargetUrl(urlStr, options = {}) {
+    let url;
+    try {
+        url = new URL(urlStr);
+    }
+    catch {
+        throw new SsrfError(`Malformed target URL: "${urlStr}"`);
+    }
+    // Protocol check
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new SsrfError(`Disallowed protocol "${url.protocol}". Only http: and https: are allowed.`);
+    }
+    const hostname = url.hostname.toLowerCase();
+    const cleanHost = (hostname.startsWith('[') && hostname.endsWith(']'))
+        ? hostname.slice(1, -1)
+        : hostname;
+    // Handle explicit localhost / loopback strings
+    if (cleanHost === 'localhost' || cleanHost === '127.0.0.1' || cleanHost === '::1') {
+        if (options.allowLocalhostForTesting) {
+            return { url, resolvedIp: cleanHost === 'localhost' ? '127.0.0.1' : cleanHost };
+        }
+        throw new SsrfError(`Access to localhost is prohibited for security.`, '127.0.0.1', cleanHost);
+    }
+    // If the hostname itself is a literal IP address (IPv4 or IPv6)
+    if (isIP(cleanHost)) {
+        if (isPrivateOrBlockedIp(cleanHost)) {
+            if (options.allowLocalhostForTesting && (cleanHost === '127.0.0.1' || cleanHost === '::1')) {
+                return { url, resolvedIp: cleanHost };
+            }
+            throw new SsrfError(`Access to private/blocked IP address "${cleanHost}" is prohibited.`, cleanHost, cleanHost);
+        }
+        return { url, resolvedIp: cleanHost };
+    }
+    // Resolve hostname via DNS
+    try {
+        const res = await lookup(cleanHost, { all: true });
+        if (!res || res.length === 0) {
+            throw new SsrfError(`Hostname "${cleanHost}" could not be resolved via DNS.`);
+        }
+        for (const record of res) {
+            if (isPrivateOrBlockedIp(record.address)) {
+                if (options.allowLocalhostForTesting && (record.address === '127.0.0.1' || record.address === '::1')) {
+                    continue;
+                }
+                throw new SsrfError(`Hostname "${cleanHost}" resolved to blocked/private IP address "${record.address}".`, record.address, cleanHost);
+            }
+        }
+        return { url, resolvedIp: res[0].address };
+    }
+    catch (err) {
+        if (err instanceof SsrfError)
+            throw err;
+        throw new SsrfError(`DNS resolution failure for host "${cleanHost}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/packages/shared/src/errors.d.ts

@@ -0,0 +1,22 @@
+export declare class DocOrbitError extends Error {
+    code: string;
+    constructor(message: string, code?: string);
+}
+export declare class SsrfError extends DocOrbitError {
+    ip?: string;
+    host?: string;
+    constructor(message: string, ip?: string, host?: string);
+}
+export declare class FetchTimeoutError extends DocOrbitError {
+    timeoutMs?: number;
+    constructor(message: string, timeoutMs?: number);
+}
+export declare class PayloadTooLargeError extends DocOrbitError {
+    byteCount?: number;
+    maxBytes?: number;
+    constructor(message: string, byteCount?: number, maxBytes?: number);
+}
+export declare class ValidationError extends DocOrbitError {
+    validationDetails?: unknown;
+    constructor(message: string, validationDetails?: unknown);
+}

package/dist/packages/shared/src/errors.js

@@ -0,0 +1,44 @@
+export class DocOrbitError extends Error {
+    code;
+    constructor(message, code = 'DOCORBIT_ERROR') {
+        super(message);
+        this.name = 'DocOrbitError';
+        this.code = code;
+    }
+}
+export class SsrfError extends DocOrbitError {
+    ip;
+    host;
+    constructor(message, ip, host) {
+        super(message, 'SSRF_BLOCKED');
+        this.name = 'SsrfError';
+        this.ip = ip;
+        this.host = host;
+    }
+}
+export class FetchTimeoutError extends DocOrbitError {
+    timeoutMs;
+    constructor(message, timeoutMs) {
+        super(message, 'FETCH_TIMEOUT');
+        this.name = 'FetchTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class PayloadTooLargeError extends DocOrbitError {
+    byteCount;
+    maxBytes;
+    constructor(message, byteCount, maxBytes) {
+        super(message, 'PAYLOAD_TOO_LARGE');
+        this.name = 'PayloadTooLargeError';
+        this.byteCount = byteCount;
+        this.maxBytes = maxBytes;
+    }
+}
+export class ValidationError extends DocOrbitError {
+    validationDetails;
+    constructor(message, validationDetails) {
+        super(message, 'VALIDATION_FAILED');
+        this.name = 'ValidationError';
+        this.validationDetails = validationDetails;
+    }
+}

package/dist/packages/shared/src/hashing.d.ts

@@ -0,0 +1,3 @@
+export declare function computeSha256(content: string | Buffer): string;
+export declare function computeContentHash(content: string): string;
+export declare function estimateTokenCount(text: string): number;

package/dist/packages/shared/src/hashing.js

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto';
+export function computeSha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export function computeContentHash(content) {
+    // Normalize line endings and line-by-line trailing whitespace for canonical stability
+    const normalized = content
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n')
+        .split('\n')
+        .map(line => line.trimEnd())
+        .join('\n')
+        .trim();
+    return computeSha256(normalized);
+}
+export function estimateTokenCount(text) {
+    // Heuristic: roughly ~4 characters per token for English and Markdown/code
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}

package/dist/packages/shared/src/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./hashing.js";