n8n-nodes-dominusnode 1.0.0

package/src/shared/auth.ts

@@ -0,0 +1,272 @@
+/**
+ * Authentication and security utilities for the DomiNode n8n integration.
+ *
+ * Provides:
+ * - Credential sanitization (redact dn_live_/dn_test_ keys from errors)
+ * - Prototype pollution prevention (strip dangerous keys from parsed JSON)
+ * - DNS rebinding protection (resolve hostnames, check all IPs)
+ * - Authenticated HTTP client for the DomiNode REST API
+ *
+ * @module
+ */
+
+import dns from "dns/promises";
+import { isPrivateIp } from "./ssrf";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CREDENTIAL_RE = /dn_(live|test)_[a-zA-Z0-9]+/g;
+const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const MAX_RESPONSE_BYTES = 10 * 1024 * 1024; // 10 MB
+const SANCTIONED_COUNTRIES = new Set(["CU", "IR", "KP", "RU", "SY"]);
+
+export { SANCTIONED_COUNTRIES };
+
+// ---------------------------------------------------------------------------
+// Credential sanitization
+// ---------------------------------------------------------------------------
+
+/**
+ * Redact DomiNode API keys from error messages to prevent credential leakage.
+ */
+export function sanitizeError(message: string): string {
+  return message.replace(CREDENTIAL_RE, "***");
+}
+
+// ---------------------------------------------------------------------------
+// Prototype pollution prevention
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively remove __proto__, constructor, and prototype keys from an object.
+ * Prevents prototype pollution when parsing untrusted JSON.
+ */
+export function stripDangerousKeys(obj: unknown, depth = 0): void {
+  if (depth > 50 || !obj || typeof obj !== "object") return;
+  if (Array.isArray(obj)) {
+    for (const item of obj) stripDangerousKeys(item, depth + 1);
+    return;
+  }
+  const record = obj as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    if (DANGEROUS_KEYS.has(key)) {
+      delete record[key];
+    } else if (record[key] && typeof record[key] === "object") {
+      stripDangerousKeys(record[key], depth + 1);
+    }
+  }
+}
+
+/**
+ * Parse JSON safely, stripping prototype pollution vectors.
+ */
+export function safeJsonParse<T>(text: string): T {
+  const parsed = JSON.parse(text);
+  stripDangerousKeys(parsed);
+  return parsed as T;
+}
+
+// ---------------------------------------------------------------------------
+// DNS rebinding protection
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a hostname and verify none of the resolved IPs are private.
+ * Prevents DNS rebinding attacks where a hostname initially resolves to a
+ * public IP during validation but later resolves to a private IP.
+ */
+export async function checkDnsRebinding(hostname: string): Promise<void> {
+  // Skip if hostname is already an IP literal
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(hostname) || hostname.startsWith("[")) {
+    return;
+  }
+
+  // Check IPv4 addresses
+  try {
+    const addresses = await dns.resolve4(hostname);
+    for (const addr of addresses) {
+      if (isPrivateIp(addr)) {
+        throw new Error(`Hostname resolves to private IP ${addr}`);
+      }
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOTFOUND") {
+      throw new Error(`Could not resolve hostname: ${hostname}`);
+    }
+    if (err instanceof Error && err.message.includes("private IP")) throw err;
+  }
+
+  // Check IPv6 addresses
+  try {
+    const addresses = await dns.resolve6(hostname);
+    for (const addr of addresses) {
+      if (isPrivateIp(addr)) {
+        throw new Error(`Hostname resolves to private IPv6 ${addr}`);
+      }
+    }
+  } catch (err) {
+    // Re-throw if we detected a private IPv6 address
+    if (err instanceof Error && err.message.includes("private IPv6")) throw err;
+    // IPv6 resolution failure is acceptable
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Period to date range helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a human-readable period string to ISO date range.
+ * Backend expects since/until ISO dates, NOT a days integer.
+ */
+export function periodToDateRange(period: string): { since: string; until: string } {
+  const now = new Date();
+  const until = now.toISOString();
+  let since: Date;
+
+  switch (period) {
+    case "day":
+      since = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+      break;
+    case "week":
+      since = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+      break;
+    case "month":
+    default:
+      since = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+      break;
+  }
+
+  return { since: since.toISOString(), until };
+}
+
+// ---------------------------------------------------------------------------
+// DominusNodeAuth — authenticated HTTP client
+// ---------------------------------------------------------------------------
+
+/**
+ * Authenticated HTTP client for the DomiNode REST API.
+ *
+ * Lazily authenticates on first request using the API key via the
+ * /api/auth/verify-key endpoint. Automatically retries on 401 (token expired).
+ */
+export class DominusNodeAuth {
+  private token: string | null = null;
+  private authPromise: Promise<void> | null = null;
+
+  constructor(
+    private apiKey: string,
+    private baseUrl: string,
+    private timeoutMs: number = 30000,
+  ) {
+    if (!apiKey || typeof apiKey !== "string") {
+      throw new Error("apiKey is required and must be a non-empty string");
+    }
+  }
+
+  /**
+   * Ensure the client is authenticated. Lazily authenticates on first call.
+   * Concurrent calls share the same auth promise to avoid duplicate requests.
+   */
+  async ensureAuth(): Promise<void> {
+    if (this.token) return;
+    if (!this.authPromise) {
+      this.authPromise = this.authenticate().finally(() => {
+        this.authPromise = null;
+      });
+    }
+    await this.authPromise;
+  }
+
+  /**
+   * Make an authenticated API request.
+   *
+   * @param method - HTTP method (GET, POST, PATCH, DELETE)
+   * @param path - API path (e.g., /api/wallet)
+   * @param body - Optional request body (will be JSON-serialized)
+   * @returns Parsed response body
+   * @throws {Error} On HTTP errors or response size violations
+   */
+  async apiRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+    await this.ensureAuth();
+
+    if (!this.token) throw new Error("Not authenticated");
+
+    const url = `${this.baseUrl}${path}`;
+
+    const headers: Record<string, string> = {
+      "User-Agent": "n8n-nodes-dominusnode/1.0.0",
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.token}`,
+    };
+
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(this.timeoutMs),
+      redirect: "error",
+    });
+
+    const contentLength = parseInt(response.headers.get("content-length") ?? "0", 10);
+    if (contentLength > MAX_RESPONSE_BYTES) {
+      throw new Error("Response body too large");
+    }
+
+    const responseText = await response.text();
+    if (responseText.length > MAX_RESPONSE_BYTES) {
+      throw new Error("Response body exceeds size limit");
+    }
+
+    if (!response.ok) {
+      // On 401, clear token so ensureAuth will re-authenticate
+      if (response.status === 401) {
+        this.token = null;
+      }
+      let message: string;
+      try {
+        const parsed = JSON.parse(responseText);
+        message = parsed.error ?? parsed.message ?? responseText;
+      } catch {
+        message = responseText;
+      }
+      if (message.length > 500) message = message.slice(0, 500) + "... [truncated]";
+      throw new Error(`API error ${response.status}: ${sanitizeError(message)}`);
+    }
+
+    return responseText ? safeJsonParse(responseText) : {};
+  }
+
+  /**
+   * Clear auth token, forcing re-authentication on next request.
+   */
+  clearToken(): void {
+    this.token = null;
+  }
+
+  private async authenticate(): Promise<void> {
+    const response = await fetch(`${this.baseUrl}/api/auth/verify-key`, {
+      method: "POST",
+      headers: {
+        "User-Agent": "n8n-nodes-dominusnode/1.0.0",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ apiKey: this.apiKey }),
+      signal: AbortSignal.timeout(this.timeoutMs),
+      redirect: "error",
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Authentication failed (${response.status}): ${sanitizeError(text.slice(0, 500))}`);
+    }
+
+    const data = safeJsonParse<{ token: string }>(await response.text());
+    if (!data.token) {
+      throw new Error("Authentication response missing token");
+    }
+    this.token = data.token;
+  }
+}

package/src/shared/constants.ts

@@ -0,0 +1,11 @@
+/**
+ * Constants shared across all DomiNode n8n nodes.
+ *
+ * @module
+ */
+
+/** HTTP methods allowed for proxied fetch (read-only to prevent abuse). */
+export const ALLOWED_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+/** Maximum response body length returned to n8n workflows. */
+export const MAX_BODY_TRUNCATE = 4000;

package/src/shared/ssrf.ts

@@ -0,0 +1,257 @@
+/**
+ * SSRF prevention utilities for the DomiNode n8n integration.
+ *
+ * Blocks private IPs, localhost, internal hostnames, embedded credentials,
+ * hex/octal/decimal-encoded IPs, IPv4-mapped IPv6, IPv4-compatible IPv6,
+ * Teredo (2001:0000::/32), 6to4 (2002::/16), CGNAT, multicast, .localhost,
+ * .local, .internal, .arpa TLDs, and IPv6 zone IDs.
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Blocked hostnames
+// ---------------------------------------------------------------------------
+
+const BLOCKED_HOSTNAMES = new Set([
+  "localhost",
+  "localhost.localdomain",
+  "ip6-localhost",
+  "ip6-loopback",
+  "[::1]",
+  "[::ffff:127.0.0.1]",
+  "0.0.0.0",
+  "[::]",
+  "metadata.google.internal",
+  "169.254.169.254",
+]);
+
+// ---------------------------------------------------------------------------
+// IPv4 normalization (hex, octal, decimal integer)
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize non-standard IPv4 representations to standard dotted-decimal.
+ * Handles decimal integers (2130706433), hex (0x7f000001), and octal (0177.0.0.1).
+ *
+ * @returns Normalized dotted-decimal string or null if not a recognizable IP.
+ */
+export function normalizeIpv4(hostname: string): string | null {
+  // Single decimal integer (e.g., 2130706433 = 127.0.0.1)
+  if (/^\d+$/.test(hostname)) {
+    const n = parseInt(hostname, 10);
+    if (n >= 0 && n <= 0xffffffff) {
+      return `${(n >>> 24) & 0xff}.${(n >>> 16) & 0xff}.${(n >>> 8) & 0xff}.${n & 0xff}`;
+    }
+  }
+
+  // Hex notation (e.g., 0x7f000001)
+  if (/^0x[0-9a-fA-F]+$/i.test(hostname)) {
+    const n = parseInt(hostname, 16);
+    if (n >= 0 && n <= 0xffffffff) {
+      return `${(n >>> 24) & 0xff}.${(n >>> 16) & 0xff}.${(n >>> 8) & 0xff}.${n & 0xff}`;
+    }
+  }
+
+  // Octal or mixed-radix octets (e.g., 0177.0.0.1)
+  const parts = hostname.split(".");
+  if (parts.length === 4) {
+    const octets: number[] = [];
+    for (const part of parts) {
+      let val: number;
+      if (/^0x[0-9a-fA-F]+$/i.test(part)) {
+        val = parseInt(part, 16);
+      } else if (/^0\d+$/.test(part)) {
+        val = parseInt(part, 8);
+      } else if (/^\d+$/.test(part)) {
+        val = parseInt(part, 10);
+      } else {
+        return null;
+      }
+      if (isNaN(val) || val < 0 || val > 255) return null;
+      octets.push(val);
+    }
+    return octets.join(".");
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Private IP detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a hostname/IP is a private, loopback, link-local, CGNAT,
+ * multicast, or other reserved address.
+ *
+ * Handles:
+ * - Standard IPv4 private ranges (10/8, 172.16/12, 192.168/16, 127/8, 0/8)
+ * - CGNAT (100.64/10)
+ * - Multicast (224/4) and reserved (240+)
+ * - Link-local (169.254/16)
+ * - IPv6 loopback (::1), unspecified (::), ULA (fc00::/7), link-local (fe80::/10)
+ * - IPv4-mapped IPv6 (::ffff:x.x.x.x), IPv4-compatible IPv6 (::x.x.x.x)
+ * - Teredo tunneling (2001:0000::/32) — embeds IPv4 in last 32 bits
+ * - 6to4 (2002::/16) — embeds IPv4 in bits 16-48
+ * - Bracketed IPv6 ([::1])
+ * - IPv6 zone IDs (%eth0)
+ */
+export function isPrivateIp(hostname: string): boolean {
+  let ip = hostname.replace(/^\[|\]$/g, "");
+
+  // Strip IPv6 zone ID (%25eth0, %eth0)
+  const zoneIdx = ip.indexOf("%");
+  if (zoneIdx !== -1) {
+    ip = ip.substring(0, zoneIdx);
+  }
+
+  const normalized = normalizeIpv4(ip);
+  const checkIp = normalized ?? ip;
+
+  // IPv4 private ranges
+  const ipv4Match = checkIp.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (ipv4Match) {
+    const a = Number(ipv4Match[1]);
+    const b = Number(ipv4Match[2]);
+    if (a === 0) return true;                          // 0.0.0.0/8
+    if (a === 10) return true;                         // 10.0.0.0/8
+    if (a === 127) return true;                        // 127.0.0.0/8
+    if (a === 169 && b === 254) return true;           // 169.254.0.0/16
+    if (a === 172 && b >= 16 && b <= 31) return true;  // 172.16.0.0/12
+    if (a === 192 && b === 168) return true;           // 192.168.0.0/16
+    if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 CGNAT
+    if (a >= 224) return true;                         // multicast + reserved
+    return false;
+  }
+
+  // IPv6 private ranges
+  const ipLower = ip.toLowerCase();
+  if (ipLower === "::1") return true;
+  if (ipLower === "::") return true;
+  if (ipLower.startsWith("fc") || ipLower.startsWith("fd")) return true;
+  if (ipLower.startsWith("fe80")) return true;
+
+  // IPv4-mapped IPv6 (::ffff:x.x.x.x or ::ffff:HHHH:HHHH)
+  if (ipLower.startsWith("::ffff:")) {
+    const embedded = ipLower.slice(7);
+    if (embedded.includes(".")) return isPrivateIp(embedded);
+    // Hex form: ::ffff:7f00:0001
+    const hexParts = embedded.split(":");
+    if (hexParts.length === 2) {
+      const hi = parseInt(hexParts[0], 16);
+      const lo = parseInt(hexParts[1], 16);
+      if (!isNaN(hi) && !isNaN(lo)) {
+        const reconstructed = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+        return isPrivateIp(reconstructed);
+      }
+    }
+    return isPrivateIp(embedded);
+  }
+
+  // IPv4-compatible IPv6 (::x.x.x.x or ::HHHH:HHHH without ffff)
+  if (ipLower.startsWith("::") && !ipLower.startsWith("::ffff:")) {
+    const rest = ipLower.slice(2);
+    if (rest && rest.includes(".")) return isPrivateIp(rest);
+    // Hex form: ::7f00:0001
+    const hexParts = rest.split(":");
+    if (hexParts.length === 2 && hexParts[0] && hexParts[1]) {
+      const hi = parseInt(hexParts[0], 16);
+      const lo = parseInt(hexParts[1], 16);
+      if (!isNaN(hi) && !isNaN(lo)) {
+        const reconstructed = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+        return isPrivateIp(reconstructed);
+      }
+    }
+  }
+
+  // Teredo tunneling (2001:0000::/32) — last 32 bits are inverted client IPv4
+  if (ipLower.startsWith("2001:0000:") || ipLower.startsWith("2001:0:")) {
+    const segments = ipLower.split(":");
+    if (segments.length >= 8) {
+      const hi = parseInt(segments[6], 16);
+      const lo = parseInt(segments[7], 16);
+      if (!isNaN(hi) && !isNaN(lo)) {
+        // Teredo inverts the IPv4 bits
+        const invertedIp = `${((hi >> 8) & 0xff) ^ 0xff}.${(hi & 0xff) ^ 0xff}.${((lo >> 8) & 0xff) ^ 0xff}.${(lo & 0xff) ^ 0xff}`;
+        return isPrivateIp(invertedIp);
+      }
+    }
+    // If we can't parse it, block conservatively
+    return true;
+  }
+
+  // 6to4 (2002::/16) — bits 16-48 contain the embedded IPv4
+  if (ipLower.startsWith("2002:")) {
+    const segments = ipLower.split(":");
+    if (segments.length >= 3) {
+      const hi = parseInt(segments[1], 16);
+      const lo = parseInt(segments[2], 16);
+      if (!isNaN(hi) && !isNaN(lo)) {
+        const embeddedIp = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
+        return isPrivateIp(embeddedIp);
+      }
+    }
+    return true;
+  }
+
+  // IPv6 multicast (ff00::/8)
+  if (ipLower.startsWith("ff")) return true;
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// URL validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a URL for safety before sending through the proxy.
+ * Blocks private IPs, localhost, internal hostnames, non-HTTP(S) protocols,
+ * and embedded credentials.
+ *
+ * @throws {Error} If the URL is invalid or targets a private/blocked address.
+ */
+export function validateUrl(url: string): URL {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Only http: and https: protocols are supported, got ${parsed.protocol}`);
+  }
+
+  const hostname = parsed.hostname.toLowerCase();
+
+  if (BLOCKED_HOSTNAMES.has(hostname)) {
+    throw new Error("Requests to localhost/loopback addresses are blocked");
+  }
+
+  if (isPrivateIp(hostname)) {
+    throw new Error("Requests to private/internal IP addresses are blocked");
+  }
+
+  // .localhost TLD (RFC 6761)
+  if (hostname.endsWith(".localhost")) {
+    throw new Error("Requests to localhost/loopback addresses are blocked");
+  }
+
+  // Internal network hostnames
+  if (
+    hostname.endsWith(".local") ||
+    hostname.endsWith(".internal") ||
+    hostname.endsWith(".arpa")
+  ) {
+    throw new Error("Requests to internal network hostnames are blocked");
+  }
+
+  // Block embedded credentials in URL
+  if (parsed.username || parsed.password) {
+    throw new Error("URLs with embedded credentials are not allowed");
+  }
+
+  return parsed;
+}