linumiq-invoice/app/services/invoice/safeFetch.server.ts

/**
 * SSRF-hardened `fetch` for use whenever the URL we're about to call could
 * be influenced by user input (shop settings, Shopify-supplied product
 * image URLs, DB-stored Files URLs, …).
 *
 * Defenses:
 *   - Only `https:` is allowed by default. `http:` is allowed only for
 *     localhost when `NODE_ENV !== "production"` (handy for local dev).
 *   - Hostname is DNS-resolved and every returned address is checked
 *     against private / loopback / link-local / unique-local ranges.
 *   - The connection is then forced to the resolved IP (with the original
 *     Host header preserved) to defeat DNS-rebinding.
 *   - A hard request timeout is enforced (default 5 s).
 *   - Response size is capped while reading; we abort once the limit is
 *     exceeded instead of buffering the whole body first.
 *   - Redirects are not followed — if the caller wants a redirected target
 *     they have to re-validate it explicitly.
 *
 * The helper returns the raw bytes plus the response status / content-type
 * so callers can decide what to do with them.
 */
import { lookup as dnsLookup } from "node:dns/promises";
import net from "node:net";
import { Agent as HttpAgent } from "node:http";
import { Agent as HttpsAgent } from "node:https";
import http from "node:http";
import https from "node:https";

export interface SafeFetchOptions {
  /** Hard cap in bytes; the read aborts as soon as this is exceeded. */
  maxBytes?: number;
  /** Total request timeout in milliseconds (default 5000). */
  timeoutMs?: number;
  /** Optional `Accept` header. */
  accept?: string;
  /**
   * If non-empty, only hosts whose lowercase name equals one of these or
   * ends with `.<entry>` are allowed. Useful for locking calls to known
   * good CDNs (e.g. `cdn.shopify.com`).
   */
  allowedHosts?: string[];
}

export interface SafeFetchResult {
  status: number;
  contentType: string | null;
  bytes: Uint8Array;
  bytesRead: number;
}

export class SafeFetchError extends Error {
  readonly code: string;
  constructor(code: string, message: string) {
    super(message);
    this.code = code;
    this.name = "SafeFetchError";
  }
}

const DEFAULT_TIMEOUT_MS = 5_000;
const DEFAULT_MAX_BYTES = 8 * 1024 * 1024; // 8 MB

function isPrivateIpv4(ip: string): boolean {
  const parts = ip.split(".").map((n) => parseInt(n, 10));
  if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n) || n < 0 || n > 255)) {
    // Treat malformed addresses as unsafe.
    return true;
  }
  const [a, b] = parts;
  if (a === 10) return true;
  if (a === 127) return true;
  if (a === 0) return true;
  if (a === 169 && b === 254) return true; // link-local + AWS metadata
  if (a === 172 && b >= 16 && b <= 31) return true;
  if (a === 192 && b === 168) return true;
  if (a === 192 && b === 0) return true; // 192.0.0.0/24, 192.0.2.0/24
  if (a === 198 && (b === 18 || b === 19)) return true;
  if (a >= 224) return true; // multicast / reserved
  return false;
}

function isPrivateIpv6(ip: string): boolean {
  const lower = ip.toLowerCase();
  if (lower === "::1" || lower === "::") return true;
  if (lower.startsWith("fe80:")) return true; // link-local
  if (lower.startsWith("fc") || lower.startsWith("fd")) return true; // ULA
  if (lower.startsWith("ff")) return true; // multicast
  // IPv4-mapped: ::ffff:a.b.c.d — apply IPv4 rules
  if (lower.startsWith("::ffff:")) {
    const v4 = lower.slice(7);
    if (v4.includes(".")) return isPrivateIpv4(v4);
  }
  return false;
}

function isPrivateAddress(ip: string, family: number): boolean {
  if (family === 4) return isPrivateIpv4(ip);
  if (family === 6) return isPrivateIpv6(ip);
  return true;
}

function hostMatchesAllowlist(hostname: string, allowed: string[] | undefined): boolean {
  if (!allowed || allowed.length === 0) return true;
  const h = hostname.toLowerCase();
  return allowed.some((entry) => {
    const e = entry.toLowerCase();
    return h === e || h.endsWith(`.${e}`);
  });
}

/**
 * Resolves a hostname to an IPv4/IPv6 address that has been vetted against
 * the private/loopback ranges. Throws `SafeFetchError` if no safe address
 * can be obtained.
 */
async function resolveSafeAddress(hostname: string): Promise<{ address: string; family: number }> {
  // If the hostname is already an IP literal, validate it directly.
  if (net.isIP(hostname)) {
    const family = net.isIPv6(hostname) ? 6 : 4;
    if (isPrivateAddress(hostname, family)) {
      throw new SafeFetchError("blocked-address", `Refusing to connect to private address ${hostname}`);
    }
    return { address: hostname, family };
  }
  let results: { address: string; family: number }[];
  try {
    results = await dnsLookup(hostname, { all: true });
  } catch (err) {
    throw new SafeFetchError("dns-failed", `DNS lookup failed for ${hostname}: ${(err as Error).message}`);
  }
  for (const r of results) {
    if (isPrivateAddress(r.address, r.family)) {
      throw new SafeFetchError("blocked-address", `${hostname} resolves to private address ${r.address}`);
    }
  }
  const first = results[0];
  if (!first) throw new SafeFetchError("dns-empty", `${hostname} resolved to no addresses`);
  return { address: first.address, family: first.family };
}

/**
 * Performs an SSRF-safe HTTP(S) GET. Throws `SafeFetchError` for policy
 * violations; throws plain `Error` for transport failures (mirroring the
 * standard `fetch` error model).
 */
export async function safeFetch(rawUrl: string, opts: SafeFetchOptions = {}): Promise<SafeFetchResult> {
  let url: URL;
  try {
    url = new URL(rawUrl);
  } catch {
    throw new SafeFetchError("bad-url", `Invalid URL: ${rawUrl}`);
  }

  const allowHttp =
    process.env.NODE_ENV !== "production" &&
    (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1");
  if (url.protocol !== "https:" && !(url.protocol === "http:" && allowHttp)) {
    throw new SafeFetchError("bad-scheme", `Refusing non-https URL: ${url.protocol}//${url.hostname}`);
  }

  if (!hostMatchesAllowlist(url.hostname, opts.allowedHosts)) {
    throw new SafeFetchError("host-not-allowed", `Host ${url.hostname} is not on the allowlist`);
  }

  const { address, family } = await resolveSafeAddress(url.hostname);

  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;

  // Pin the resolved IP. We pass an Agent with a custom `lookup` that always
  // returns our pre-validated address, so the actual TCP connect can't be
  // re-resolved to something else (DNS-rebinding defense).
  const pinnedLookup = (
    _hostname: string,
    _options: unknown,
    cb: (err: NodeJS.ErrnoException | null, address: string, family: number) => void,
  ) => cb(null, address, family);

  const isHttps = url.protocol === "https:";
  const agent = isHttps
    ? new HttpsAgent({ keepAlive: false, lookup: pinnedLookup as never })
    : new HttpAgent({ keepAlive: false, lookup: pinnedLookup as never });

  const headers: Record<string, string> = {
    Host: url.host,
    "User-Agent": "linumiq-invoice/1.0 (+https://linumiq.com)",
  };
  if (opts.accept) headers["Accept"] = opts.accept;

  const requestOptions: http.RequestOptions = {
    method: "GET",
    host: url.hostname,
    port: url.port ? parseInt(url.port, 10) : isHttps ? 443 : 80,
    path: `${url.pathname}${url.search}`,
    headers,
    agent,
    // Defeat redirects (Node's http doesn't follow by default).
  };

  return new Promise<SafeFetchResult>((resolve, reject) => {
    const lib = isHttps ? https : http;
    const req = lib.request(requestOptions, (res) => {
      const status = res.statusCode ?? 0;
      // Reject 3xx — caller must explicitly re-call with the new URL.
      if (status >= 300 && status < 400) {
        res.resume();
        reject(new SafeFetchError("redirect-not-allowed", `Refusing redirect ${status} from ${rawUrl}`));
        return;
      }
      const chunks: Buffer[] = [];
      let total = 0;
      res.on("data", (chunk: Buffer) => {
        total += chunk.length;
        if (total > maxBytes) {
          res.destroy(new SafeFetchError("too-large", `Response exceeded ${maxBytes} bytes`));
          return;
        }
        chunks.push(chunk);
      });
      res.on("end", () => {
        const buf = Buffer.concat(chunks, total);
        resolve({
          status,
          contentType: res.headers["content-type"] ?? null,
          bytes: new Uint8Array(buf),
          bytesRead: total,
        });
      });
      res.on("error", (err) => reject(err));
    });
    req.setTimeout(timeoutMs, () => {
      req.destroy(new SafeFetchError("timeout", `Request to ${url.hostname} exceeded ${timeoutMs}ms`));
    });
    req.on("error", (err) => reject(err));
    req.end();
  });
}

/** Common allowlist for Shopify-served assets (CDN + Files). */
export const SHOPIFY_CDN_HOSTS = ["cdn.shopify.com", "shopifycdn.com", "shopify.com"];