@dichovsky/testrail-api-client 1.0.0 → 2.1.0

package/src/client-core.ts

@@ -1,7 +1,9 @@
 import type { TestRailConfig, CacheEntry } from './types.js';
 import { base64Encode, sleep } from './utils.js';
-import { TestRailApiError, TestRailValidationError } from './errors.js';
+import { TestRailApiError, TestRailValidationError, handleZodError } from './errors.js';
 import pkg from '../package.json' with { type: 'json' };
+import { isIP } from 'node:net';
+import { ZodError, type ZodType } from 'zod';
 
 const USER_AGENT = `${pkg.description}/${pkg.version}`;
 import {
@@ -15,15 +17,16 @@ import {
     DEFAULT_MAX_CACHE_SIZE,
     DEFAULT_RATE_LIMIT_MAX_REQUESTS,
     DEFAULT_RATE_LIMIT_WINDOW_MS,
+    DEFAULT_DNS_VALIDATION_MAX_WAIT_MS,
 } from './constants.js';
 
 // Reject loopback, link-local, and private-range hosts to prevent SSRF.
 // All requests carry a full Authorization header, making the client a credentialed
 // probe for internal services when baseUrl is attacker-controlled.
-// NOTE: This check is purely syntactic (regex on the hostname string). It does NOT
-// resolve DNS, so a public-looking hostname that resolves to a private IP, or a
-// DNS-rebinding attack, can still bypass this protection. For full SSRF prevention
-// use a network-level egress filter or a proxy that validates resolved addresses.
+// Protection combines syntactic checks (regex on hostname string) with DNS resolution:
+// validatePublicHost() resolves the hostname and checks resulting IPs. A DNS validation
+// promise is awaited briefly before each request. This blocks obvious private-host
+// resolutions but does not fully eliminate rebinding after initial validation.
 const PRIVATE_HOST_PATTERNS: RegExp[] = [
     /^localhost\.?$/i, // matches "localhost" with or without trailing dot
     /^127\./,
@@ -37,16 +40,89 @@ const PRIVATE_HOST_PATTERNS: RegExp[] = [
     /^0\./,
 ];
 
-function validatePublicHost(hostname: string): void {
-    // Strip enclosing brackets from IPv6 literals (e.g. "[::1]" → "::1")
+function isPrivateOrLoopbackIPv4(ip: string): boolean {
+    const octetParts = ip.split('.');
+    if (octetParts.length !== 4 || octetParts.some((part) => !/^\d+$/.test(part))) {
+        return false;
+    }
+
+    const octets = octetParts.map((part) => Number.parseInt(part, 10));
+    if (octets.some((part) => Number.isNaN(part) || part < 0 || part > 255)) {
+        return false;
+    }
+    const [o0, o1] = octets as [number, number, ...number[]];
+
+    return (
+        o0 === 0 ||
+        o0 === 10 ||
+        o0 === 127 ||
+        (o0 === 169 && o1 === 254) ||
+        (o0 === 172 && o1 >= 16 && o1 <= 31) ||
+        (o0 === 192 && o1 === 168)
+    );
+}
+
+function isPrivateOrLoopbackIP(ip: string, family?: number): boolean {
+    const [normalized] = ip.toLowerCase().split('%') as [string, ...string[]];
+    // Handle IPv4-mapped IPv6 addresses (e.g. ::ffff:127.0.0.1).
+    const mappedIPv4 = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    const mappedAddress = mappedIPv4?.[1];
+    if (mappedAddress !== undefined) {
+        return isPrivateOrLoopbackIPv4(mappedAddress);
+    }
+
+    const ipFamily = family ?? isIP(normalized);
+    if (ipFamily === 4) {
+        return isPrivateOrLoopbackIPv4(normalized);
+    }
+    if (ipFamily === 6) {
+        if (normalized === '::' || normalized === '::1') {
+            return true;
+        }
+
+        const [firstHextet] = normalized.split(':') as [string, ...string[]];
+        return (
+            firstHextet.startsWith('fc') ||
+            firstHextet.startsWith('fd') ||
+            firstHextet.startsWith('fe8') ||
+            firstHextet.startsWith('fe9') ||
+            firstHextet.startsWith('fea') ||
+            firstHextet.startsWith('feb')
+        );
+    }
+
+    return false;
+}
+
+async function validatePublicHost(hostname: string): Promise<void> {
     const bare = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;
-    for (const pattern of PRIVATE_HOST_PATTERNS) {
-        if (pattern.test(bare)) {
-            throw new TestRailValidationError(
-                `baseUrl resolves to a private/loopback host ("${hostname}"). ` +
-                    'Set allowPrivateHosts: true to allow on-premise deployments.',
-            );
+    const isPrivatePattern = PRIVATE_HOST_PATTERNS.some((pattern) => pattern.test(bare));
+    if (isPrivatePattern) {
+        throw new TestRailValidationError(
+            `baseUrl resolves to a private/loopback host ("${hostname}"). ` +
+                'Set allowPrivateHosts: true to allow on-premise deployments.',
+        );
+    }
+
+    try {
+        const dns = await import('node:dns/promises');
+        const lookups = await dns.lookup(bare, { all: true }).catch(() => []);
+        for (const lookup of lookups) {
+            if (lookup.address !== '' && isPrivateOrLoopbackIP(lookup.address, lookup.family)) {
+                throw new TestRailValidationError(
+                    `baseUrl resolves to a private/loopback host ("${hostname}" -> "${lookup.address}"). ` +
+                        'Set allowPrivateHosts: true to allow on-premise deployments.',
+                );
+            }
         }
+    } catch (err) {
+        if (err instanceof TestRailValidationError) throw err;
+        // DNS/import failures are ignored to avoid blocking valid public hosts
+        // when DNS is temporarily unavailable in constrained runtimes.
+        // eslint-disable-next-line no-console
+        console.warn(
+            `Warning: DNS host validation skipped due to lookup error: ${err instanceof Error ? err.message : 'Unknown error'}`,
+        );
     }
 }
 
@@ -98,6 +174,8 @@ export class TestRailClientCore {
     private cacheCleanupTimer: ReturnType<typeof setInterval> | undefined;
     private readonly rateLimiter: { maxRequests: number; windowMs: number; requests: number[] };
     private isDestroyed = false;
+    private readonly dnsValidationPromise: Promise<void> | undefined;
+    private dnsValidationError: TestRailValidationError | undefined;
 
     constructor(config: TestRailConfig) {
         this.validateConfig(config);
@@ -124,6 +202,21 @@ export class TestRailClientCore {
             requests: [],
         };
 
+        // Start async DNS host validation in the background and await it in request().
+        // If DNS resolves to a private IP, mark this client so all requests fail.
+        // The synchronous regex check in validateConfig already blocks obvious private addresses.
+        if (config.allowPrivateHosts !== true) {
+            // URL already validated by validateConfig — this parse cannot throw.
+            const url = new URL(config.baseUrl);
+            this.dnsValidationPromise = validatePublicHost(url.hostname).catch((err: unknown) => {
+                if (err instanceof TestRailValidationError) {
+                    this.dnsValidationError = err;
+                }
+            });
+        } else {
+            this.dnsValidationPromise = undefined;
+        }
+
         // Register this instance for automatic cleanup
         activeClients.add(this);
         registerProcessHandlers();
@@ -163,10 +256,19 @@ export class TestRailClientCore {
                 );
             }
 
-            // Block SSRF targets (loopback, link-local, private ranges) unless
-            // the caller explicitly opts in for on-premise/private-network deployments.
+            // Syntactic SSRF protection: reject obvious private hostnames synchronously.
+            // The async DNS check in validatePublicHost adds defence-in-depth for rebinding.
             if (config.allowPrivateHosts !== true) {
-                validatePublicHost(url.hostname);
+                const bare =
+                    url.hostname.startsWith('[') && url.hostname.endsWith(']')
+                        ? url.hostname.slice(1, -1)
+                        : url.hostname;
+                if (PRIVATE_HOST_PATTERNS.some((pattern) => pattern.test(bare))) {
+                    throw new TestRailValidationError(
+                        `baseUrl resolves to a private/loopback host ("${url.hostname}"). ` +
+                            'Set allowPrivateHosts: true to allow on-premise deployments.',
+                    );
+                }
             }
         } catch (err) {
             if (err instanceof TestRailValidationError) {
@@ -281,9 +383,10 @@ export class TestRailClientCore {
                 }
             }
             const waitTime = oldestRequest + this.rateLimiter.windowMs - now;
-            throw new TestRailApiError(
-                `Rate limit exceeded. Please wait ${Math.ceil(waitTime / 1000)} seconds before making another request.`,
-            );
+            throw new TestRailApiError(429, 'Too Many Requests', {
+                message: `Rate limit exceeded. Please wait ${Math.ceil(waitTime / 1000)} seconds before making another request.`,
+                waitTimeMs: waitTime,
+            });
         }
 
         this.rateLimiter.requests.push(now);
@@ -293,7 +396,7 @@ export class TestRailClientCore {
      * Validates that an ID is a positive integer.
      * @throws {TestRailValidationError} When ID is invalid
      */
-    protected validateId(id: number, name: string): void {
+    public validateId(id: number, name: string): void {
         if (typeof id !== 'number' || !Number.isInteger(id) || id <= 0) {
             throw new TestRailValidationError(`${name} must be a positive integer`);
         }
@@ -303,7 +406,7 @@ export class TestRailClientCore {
      * Validates that a string entry ID is non-empty.
      * @throws {TestRailValidationError} When entryId is not a non-empty string
      */
-    protected validateEntryId(entryId: string): void {
+    public validateEntryId(entryId: string): void {
         if (typeof entryId !== 'string' || entryId.trim() === '') {
             throw new TestRailValidationError('entryId must be a non-empty string');
         }
@@ -313,7 +416,7 @@ export class TestRailClientCore {
      * Validates optional pagination parameters.
      * @throws {TestRailValidationError} When limit is not a positive integer or offset is not a non-negative integer
      */
-    protected validatePaginationParams(limit?: number, offset?: number): void {
+    public validatePaginationParams(limit?: number, offset?: number): void {
         if (limit !== undefined) {
             if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
                 throw new TestRailValidationError('limit must be a positive integer');
@@ -332,7 +435,7 @@ export class TestRailClientCore {
      * Keys and values are automatically percent-encoded via `encodeURIComponent`.
      * Do NOT pre-encode values before passing them; doing so will cause double-encoding.
      */
-    protected buildEndpoint(base: string, params: Record<string, string | number | undefined> = {}): string {
+    public buildEndpoint(base: string, params: Record<string, string | number | undefined> = {}): string {
         const parts: string[] = [];
         for (const [key, value] of Object.entries(params)) {
             if (value !== undefined) {
@@ -459,7 +562,7 @@ export class TestRailClientCore {
      * @throws {TestRailApiError} When the API request fails or network error occurs
      * @throws {Error} When called after `destroy()`
      */
-    protected async request<T>(
+    public async request<T>(
         method: string,
         endpoint: string,
         data?: unknown,
@@ -471,6 +574,8 @@ export class TestRailClientCore {
             throw new Error('Cannot use TestRailClient after destroy() has been called');
         }
 
+        await this.awaitDnsValidation();
+
         // Check cache for GET requests
         if (method === 'GET' && !skipCache) {
             const cacheKey = `${method}:${endpoint}`;
@@ -523,12 +628,7 @@ export class TestRailClientCore {
                 // or secret values. Keep it in the structured `response` field for
                 // programmatic inspection but do not embed it in the message string,
                 // which callers commonly pass to loggers.
-                throw new TestRailApiError(
-                    `TestRail API error: ${response.status} ${response.statusText}`,
-                    response.status,
-                    response.statusText,
-                    errorText,
-                );
+                throw new TestRailApiError(response.status, response.statusText, errorText);
             }
 
             // Invalidate cache after mutating requests to avoid stale GET results.
@@ -554,7 +654,7 @@ export class TestRailClientCore {
 
                 return result;
             } catch {
-                throw new TestRailApiError('Invalid JSON response from TestRail API');
+                throw new TestRailApiError(0, 'Invalid JSON response from TestRail API');
             }
         } catch (error) {
             clearTimeout(timeoutId);
@@ -567,7 +667,7 @@ export class TestRailClientCore {
 
             // Don't retry timeout errors to avoid excessive wait times
             if (isAbortError) {
-                throw new TestRailApiError(`Request timeout after ${this.timeout}ms`);
+                throw new TestRailApiError(408, `Request timeout after ${this.timeout}ms`);
             }
 
             // Retry on network errors up to the maximum number of retries
@@ -576,12 +676,7 @@ export class TestRailClientCore {
                 return this.request<T>(method, endpoint, data, retryCount + 1, skipCache);
             }
 
-            throw new TestRailApiError(
-                `Network error: ${(error as Error).message}`,
-                undefined,
-                undefined,
-                (error as Error).message,
-            );
+            throw new TestRailApiError(0, `Network error: ${(error as Error).message}`, (error as Error).message);
         }
     }
 
@@ -596,7 +691,7 @@ export class TestRailClientCore {
      * @throws {TestRailApiError} When the API request fails or network error occurs
      * @throws {Error} When called after `destroy()`
      */
-    protected async requestMultipart<T>(
+    public async requestMultipart<T>(
         endpoint: string,
         file: globalThis.Blob | Uint8Array | globalThis.File,
         filename: string,
@@ -605,6 +700,8 @@ export class TestRailClientCore {
             throw new Error('Cannot use TestRailClient after destroy() has been called');
         }
 
+        await this.awaitDnsValidation();
+
         this.checkRateLimit();
 
         const url = `${this.baseUrl}/index.php?/api/v2/${endpoint}`;
@@ -638,12 +735,7 @@ export class TestRailClientCore {
 
             if (!response.ok) {
                 const errorText = await response.text().catch(() => 'Unknown error');
-                throw new TestRailApiError(
-                    `TestRail API error: ${response.status} ${response.statusText}`,
-                    response.status,
-                    response.statusText,
-                    errorText,
-                );
+                throw new TestRailApiError(response.status, response.statusText, errorText);
             }
 
             // Invalidate cache after upload
@@ -657,7 +749,7 @@ export class TestRailClientCore {
             try {
                 return JSON.parse(responseText) as T;
             } catch {
-                throw new TestRailApiError('Invalid JSON response from TestRail API');
+                throw new TestRailApiError(0, 'Invalid JSON response from TestRail API');
             }
         } catch (error) {
             clearTimeout(timeoutId);
@@ -668,15 +760,10 @@ export class TestRailClientCore {
 
             const isAbortError = (error as Error).name === 'AbortError';
             if (isAbortError) {
-                throw new TestRailApiError(`Request timeout after ${this.timeout}ms`);
+                throw new TestRailApiError(408, `Request timeout after ${this.timeout}ms`);
             }
 
-            throw new TestRailApiError(
-                `Network error: ${(error as Error).message}`,
-                undefined,
-                undefined,
-                (error as Error).message,
-            );
+            throw new TestRailApiError(0, `Network error: ${(error as Error).message}`, (error as Error).message);
         }
     }
 
@@ -688,11 +775,13 @@ export class TestRailClientCore {
      * @throws {TestRailApiError} When the API request fails or network error occurs
      * @throws {Error} When called after `destroy()`
      */
-    protected async requestBinary(endpoint: string, retryCount = 0): Promise<ArrayBuffer> {
+    public async requestBinary(endpoint: string, retryCount = 0): Promise<ArrayBuffer> {
         if (this.isDestroyed) {
             throw new Error('Cannot use TestRailClient after destroy() has been called');
         }
 
+        await this.awaitDnsValidation();
+
         this.checkRateLimit();
 
         const url = `${this.baseUrl}/index.php?/api/v2/${endpoint}`;
@@ -724,12 +813,7 @@ export class TestRailClientCore {
                     return this.requestBinary(endpoint, retryCount + 1);
                 }
 
-                throw new TestRailApiError(
-                    `TestRail API error: ${response.status} ${response.statusText}`,
-                    response.status,
-                    response.statusText,
-                    errorText,
-                );
+                throw new TestRailApiError(response.status, response.statusText, errorText);
             }
 
             return response.arrayBuffer();
@@ -742,7 +826,7 @@ export class TestRailClientCore {
 
             const isAbortError = (error as Error).name === 'AbortError';
             if (isAbortError) {
-                throw new TestRailApiError(`Request timeout after ${this.timeout}ms`);
+                throw new TestRailApiError(408, `Request timeout after ${this.timeout}ms`);
             }
 
             if (retryCount < this.maxRetries) {
@@ -750,12 +834,44 @@ export class TestRailClientCore {
                 return this.requestBinary(endpoint, retryCount + 1);
             }
 
-            throw new TestRailApiError(
-                `Network error: ${(error as Error).message}`,
-                undefined,
-                undefined,
-                (error as Error).message,
-            );
+            throw new TestRailApiError(0, `Network error: ${(error as Error).message}`, (error as Error).message);
+        }
+    }
+
+    private async awaitDnsValidation(): Promise<void> {
+        if (this.dnsValidationPromise !== undefined) {
+            let timeoutId: ReturnType<typeof setTimeout> | undefined;
+            try {
+                await Promise.race([
+                    this.dnsValidationPromise,
+                    new Promise<void>((resolve) => {
+                        timeoutId = setTimeout(resolve, DEFAULT_DNS_VALIDATION_MAX_WAIT_MS);
+                    }),
+                ]);
+            } finally {
+                if (timeoutId !== undefined) {
+                    clearTimeout(timeoutId);
+                }
+            }
+        }
+
+        if (this.dnsValidationError !== undefined) {
+            throw this.dnsValidationError;
+        }
+    }
+
+    /**
+     * Validates `data` against `schema` and returns it typed as `T`.
+     * @throws {TestRailValidationError} When data does not conform to schema
+     */
+    public parse<T>(schema: ZodType, data: unknown): T {
+        try {
+            return schema.parse(data) as T;
+        } catch (err) {
+            if (err instanceof ZodError) {
+                throw handleZodError(err);
+            }
+            throw err;
         }
     }
 }