index.js

import express from 'express';

const app = express();
const PORT = process.env.PORT || 3000;
const FETCH_TIMEOUT_MS = 10000;

// --- Helpers ---

// Patterns that identify non-public addresses — block these to prevent SSRF.
const PRIVATE_HOST_PATTERNS = [
  /^localhost$/i,
  /^127\./,
  /^10\./,
  /^192\.168\./,
  /^172\.(1[6-9]|2\d|3[01])\./,
  /^\[?::1\]?$/,           // IPv6 loopback
  /^\[?fc[0-9a-f]{2}:/i,  // IPv6 unique-local (fc00::/7)
];

/**
 * Returns { valid: true } for a URL that is safe to fetch, or
 * { valid: false, reason: string } otherwise.
 *
 * Accepts any HTTPS URL whose hostname is not a private/loopback address,
 * so Cloudinary CNAME and private-CDN hostnames all pass through.
 */
function validateFetchTarget(urlString) {
  let parsed;
  try {
    parsed = new URL(urlString);
  } catch {
    return { valid: false, reason: 'Invalid URL — could not be parsed.' };
  }

  if (parsed.protocol !== 'https:') {
    return { valid: false, reason: 'Only HTTPS URLs are supported.' };
  }

  const host = parsed.hostname;
  if (PRIVATE_HOST_PATTERNS.some((p) => p.test(host))) {
    return { valid: false, reason: 'Private, loopback, or link-local addresses are not allowed.' };
  }

  return { valid: true };
}

/**
 * Constructs a Cloudinary delivery URL from its components.
 *
 * Supports three routing models:
 *
 * 1. Standard  (default)
 *    https://res.cloudinary.com/{cloud_name}/{asset_type}/{delivery_type}/[transformation/]{public_id}
 *
 * 2. CNAME  (custom_domain provided, private_cdn = false)
 *    https://{custom_domain}/{cloud_name}/{asset_type}/{delivery_type}/[transformation/]{public_id}
 *    The CNAME is mapped to res.cloudinary.com; the path is identical to standard.
 *
 * 3. Private CDN / subdomain delivery  (private_cdn = true)
 *    No custom_domain → https://{cloud_name}-res.cloudinary.com/{asset_type}/{delivery_type}/[transformation/]{public_id}
 *    With custom_domain → https://{custom_domain}/{asset_type}/{delivery_type}/[transformation/]{public_id}
 *    The CDN handles cloud routing, so the cloud name is NOT in the path.
 */
function buildCloudinaryUrl(cloudName, assetType, deliveryType, transformation, publicId, customDomain, privateCdn) {
  let origin;

  if (privateCdn) {
    // Private CDN / subdomain delivery — cloud name moves out of the path.
    origin = customDomain
      ? `https://${customDomain}`
      : `https://${encodeURIComponent(cloudName)}-res.cloudinary.com`;
  } else {
    // Standard or CNAME — cloud name stays in the path.
    origin = customDomain
      ? `https://${customDomain}`
      : 'https://res.cloudinary.com';
  }

  const segments = [origin];

  if (!privateCdn) {
    // Cloud name is part of the path for standard and CNAME delivery.
    segments.push(encodeURIComponent(cloudName));
  }

  segments.push(encodeURIComponent(assetType));
  segments.push(encodeURIComponent(deliveryType));

  if (transformation && transformation.trim()) {
    segments.push(transformation.trim());
  }

  // Public IDs may contain slashes and dots — preserve them as-is.
  segments.push(publicId);

  return segments.join('/');
}

/**
 * Fetches only the response headers for a given URL (body is never read/buffered).
 * Returns a structured result object.
 */
async function checkCloudinaryUrl(url) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);

  let response;
  try {
    response = await fetch(url, {
      signal: controller.signal,
      headers: { 'User-Agent': 'CloudinaryURLDebugger/1.0' },
    });
  } catch (err) {
    clearTimeout(timer);
    if (err.name === 'AbortError') {
      return {
        success: false,
        http_status: null,
        cld_error: null,
        message: `Request timed out after ${FETCH_TIMEOUT_MS / 1000} seconds. The origin may be unreachable.`,
        url,
      };
    }
    return {
      success: false,
      http_status: null,
      cld_error: null,
      message: `Network error: ${err.message}`,
      url,
    };
  } finally {
    clearTimeout(timer);
  }

  // Cancel the body immediately — we only care about headers.
  try { await response.body?.cancel(); } catch { /* ignore */ }

  const cldError = response.headers.get('x-cld-error');
  const status = response.status;

  if (cldError) {
    return {
      success: false,
      http_status: status,
      cld_error: cldError,
      message: `Cloudinary returned an error: ${cldError}`,
      url,
    };
  }

  if (response.ok) {
    return {
      success: true,
      http_status: status,
      cld_error: null,
      message: 'The asset was delivered successfully. No Cloudinary errors were detected.',
      url,
    };
  }

  return {
    success: false,
    http_status: status,
    cld_error: null,
    message: `The request failed with HTTP ${status}. No x-cld-error header was present.`,
    url,
  };
}

// --- Routes ---

/**
 * GET /debug-url
 *
 * Query params:
 *   url  (required) — a Cloudinary delivery URL (res.cloudinary.com, a CNAME, or a private-CDN hostname)
 *
 * Examples:
 *   /debug-url?url=https://res.cloudinary.com/demo/image/upload/sample.jpg
 *   /debug-url?url=https://media.example.com/demo/image/upload/sample.jpg
 *   /debug-url?url=https://demo-res.cloudinary.com/image/upload/sample.jpg
 */
app.get('/debug-url', async (req, res) => {
  const { url } = req.query;

  if (!url) {
    return res.status(400).json({
      success: false,
      error: 'Missing required query parameter: url',
      usage: '/debug-url?url=https://res.cloudinary.com/{cloud_name}/...',
    });
  }

  const check = validateFetchTarget(url);
  if (!check.valid) {
    return res.status(400).json({ success: false, error: check.reason });
  }

  const result = await checkCloudinaryUrl(url);
  return res.json(result);
});

/**
 * GET /debug-components
 *
 * Query params:
 *   cloud_name     (required) — Cloudinary cloud name
 *   asset_type     (required) — e.g. image, video, raw
 *   delivery_type  (required) — e.g. upload, fetch, private, authenticated
 *   public_id      (required) — public ID of the asset, including file extension if needed
 *   transformation (optional) — transformation string, e.g. w_300,c_fill
 *   custom_domain  (optional) — custom hostname for CNAME or private-CDN delivery
 *                               e.g. media.example.com
 *   private_cdn    (optional) — set to "true" for private-CDN / subdomain delivery,
 *                               where the cloud name is NOT part of the URL path.
 *                               Without custom_domain this produces {cloud_name}-res.cloudinary.com.
 *                               With custom_domain the CDN is assumed to handle cloud routing.
 *
 * Examples:
 *   Standard:
 *     /debug-components?cloud_name=demo&asset_type=image&delivery_type=upload&public_id=sample.jpg
 *   CNAME:
 *     /debug-components?cloud_name=demo&asset_type=image&delivery_type=upload&public_id=sample.jpg&custom_domain=media.example.com
 *   Private CDN (subdomain delivery, no custom domain):
 *     /debug-components?cloud_name=demo&asset_type=image&delivery_type=upload&public_id=sample.jpg&private_cdn=true
 *   Private CDN with custom domain:
 *     /debug-components?cloud_name=demo&asset_type=image&delivery_type=upload&public_id=sample.jpg&custom_domain=cdn.example.com&private_cdn=true
 */
app.get('/debug-components', async (req, res) => {
  const {
    cloud_name,
    asset_type,
    delivery_type,
    transformation = '',
    public_id,
    custom_domain = '',
    private_cdn = 'false',
  } = req.query;

  const missing = ['cloud_name', 'asset_type', 'delivery_type', 'public_id'].filter(
    (p) => !req.query[p]
  );
  if (missing.length) {
    return res.status(400).json({
      success: false,
      error: `Missing required query parameter(s): ${missing.join(', ')}`,
      required: ['cloud_name', 'asset_type', 'delivery_type', 'public_id'],
      optional: ['transformation', 'custom_domain', 'private_cdn'],
    });
  }

  const isPrivateCdn = private_cdn === 'true' || private_cdn === '1';

  if (custom_domain) {
    // Validate the custom domain produces a safe HTTPS URL before building.
    const domainCheck = validateFetchTarget(`https://${custom_domain}/`);
    if (!domainCheck.valid) {
      return res.status(400).json({ success: false, error: `Invalid custom_domain: ${domainCheck.reason}` });
    }
  }

  const url = buildCloudinaryUrl(
    cloud_name, asset_type, delivery_type, transformation, public_id, custom_domain, isPrivateCdn
  );
  const result = await checkCloudinaryUrl(url);

  // Include the constructed URL so Fin can show it to the user.
  result.constructed_url = url;

  return res.json(result);
});

/**
 * GET /
 * API discovery — describes both endpoints for Fin's data connector schema.
 */
app.get('/', (_req, res) => {
  res.json({
    name: 'Cloudinary URL Debugger',
    description:
      'Checks Cloudinary delivery URLs and returns the x-cld-error response header to help diagnose delivery failures. The asset itself is never returned.',
    endpoints: {
      '/debug-url': {
        method: 'GET',
        description:
          'Debug a full Cloudinary URL. Accepts res.cloudinary.com URLs, CNAME hostnames, and private-CDN hostnames.',
        params: {
          url: '(required) Full HTTPS Cloudinary delivery URL — res.cloudinary.com, a CNAME, or a private-CDN host',
        },
      },
      '/debug-components': {
        method: 'GET',
        description:
          'Construct a Cloudinary URL from its components and debug it. Supports standard, CNAME, and private-CDN delivery.',
        params: {
          cloud_name: '(required) Your Cloudinary cloud name',
          asset_type: '(required) Asset type: image | video | raw',
          delivery_type:
            '(required) Delivery type: upload | fetch | private | authenticated | sprite | facebook | twitter | youtube | vimeo',
          transformation:
            '(optional) Transformation string, e.g. w_300,c_fill or f_auto,q_auto',
          public_id:
            '(required) Public ID of the asset, including file extension if not using f_auto',
          custom_domain:
            '(optional) Custom hostname for CNAME or private-CDN delivery, e.g. media.example.com',
          private_cdn:
            '(optional) Set to "true" for private-CDN / subdomain delivery where the cloud name is NOT in the URL path. Without custom_domain this produces a {cloud_name}-res.cloudinary.com URL.',
        },
      },
    },
  });
});

// Local dev — Vercel handles its own listener in production.
if (process.env.NODE_ENV !== 'production') {
  app.listen(PORT, () => {
    console.log(`Cloudinary URL Debugger listening on port ${PORT}`);
  });
}

export default app;