docorbit 0.1.0 → 0.1.2

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";