xpandurl 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aman Harsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# xpandurl
+
+Expand shortened URLs to their final destination. Follows the full redirect chain using Node.js built-in HTTP — zero runtime dependencies.
+
+```bash
+npx xpandurl https://bit.ly/xyz
+# https://example.com/the-real-page
+```
+
+## Install
+
+```bash
+npm install xpandurl
+# or
+bun add xpandurl
+```
+
+**Requires Node.js 18+**
+
+---
+
+## Library
+
+### `expand(url, options?)`
+
+Expands a single URL and returns the final destination.
+
+```ts
+import { expand } from 'xpandurl'
+
+const result = await expand('https://bit.ly/xyz')
+
+console.log(result.expandedUrl)      // 'https://example.com/the-real-page'
+console.log(result.statusCode)       // 200
+console.log(result.redirectChain)    // ['https://bit.ly/xyz', ...]
+```
+
+### `expandMany(urls, options?)`
+
+Expands multiple URLs concurrently. Always returns one result per input URL — failures are captured in `result.error` rather than throwing.
+
+```ts
+import { expandMany } from 'xpandurl'
+
+const results = await expandMany([
+  'https://bit.ly/a',
+  'https://t.co/b',
+  'https://tinyurl.com/c',
+])
+
+for (const result of results) {
+  if (result.error) {
+    console.error(`${result.originalUrl} failed: ${result.error}`)
+  } else {
+    console.log(`${result.originalUrl} → ${result.expandedUrl}`)
+  }
+}
+```
+
+---
+
+## API Reference
+
+### ExpandOptions
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `timeout` | `number` | `10000` | Request timeout in milliseconds |
+| `maxRedirects` | `number` | `10` | Maximum redirects to follow |
+| `userAgent` | `string` | Chrome UA | User-Agent header |
+| `headers` | `Record<string, string>` | — | Additional request headers |
+| `allowHttpDowngrade` | `boolean` | `true` | Allow redirects from `https:` to `http:`. Set to `false` to reject downgrades |
+| `allowedHosts` | `string[]` | — | If set, only follow redirects to these hostnames. Requests to any other host throw |
+| `blockPrivateIPs` | `boolean` | `true` | Block requests to loopback, RFC1918, link-local, and cloud metadata addresses |
+| `concurrency` | `number` | `5` | Max concurrent expansions (`expandMany` only) |
+
+### ExpandResult
+
+```ts
+interface ExpandResult {
+  originalUrl: string       // The URL you passed in
+  expandedUrl: string       // Final destination after all redirects
+  statusCode: number        // HTTP status of the final response
+  redirectChain: string[]   // Each intermediate URL (not including final)
+  error?: string            // Set on failure (expandMany only)
+}
+```
+
+### Error types
+
+All errors extend `ExpandError` which exposes a `url` property pointing to the URL that caused the failure.
+
+```ts
+import { ExpandError, TimeoutError, MaxRedirectsError, InvalidUrlError } from 'xpandurl'
+
+try {
+  await expand('https://bit.ly/xyz', { timeout: 3000, maxRedirects: 5 })
+} catch (err) {
+  if (err instanceof TimeoutError)      console.error('Timed out')
+  if (err instanceof MaxRedirectsError) console.error('Too many redirects')
+  if (err instanceof InvalidUrlError)   console.error('Bad URL or protocol')
+  if (err instanceof ExpandError)       console.error('Expansion failed:', err.url)
+}
+```
+
+---
+
+## CLI
+
+```bash
+npx xpandurl <url> [url2 ...] [options]
+```
+
+| Flag | Description |
+|---|---|
+| `--chain` | Print each redirect hop |
+| `--json` | Output as JSON |
+| `--timeout <ms>` | Request timeout in ms (default: 10000) |
+| `--help` | Show usage |
+
+### Rich output
+
+By default the CLI prints a human-readable summary for each URL:
+
+```
+  Original    https://bit.ly/xyz
+  Expanded    https://example.com/the-real-page
+  Status      200 OK
+  Security    ✓ HTTPS
+  Hops        2 redirects
+
+  Query Parameters (3)
+    utm_source    newsletter          TRACKING
+    ref           homepage            AFFILIATE
+    page          about               OTHER
+```
+
+- **Status** is color-coded: green for 2xx, yellow for 3xx, red for 4xx/5xx.
+- **Security** flags `⚠ HTTP` if the final URL is not HTTPS.
+- **Hops** is only shown when the URL required at least one redirect.
+- **Query Parameters** classifies each param as `TRACKING` (UTM, fbclid, gclid, …), `AFFILIATE` (ref, tag, partner, …), or `OTHER`.
+- Very long URLs are truncated in display mode. Use `--json` to get the full untruncated URL.
+
+Column widths in the summary block adjust based on label length; the example above is representative.
+
+Colors are automatically disabled when output is piped.
+
+### Examples
+
+```bash
+# Expand a single URL
+npx xpandurl https://bit.ly/xyz
+
+# Show the full redirect chain
+npx xpandurl https://bit.ly/xyz --chain
+
+# Expand multiple URLs at once
+npx xpandurl https://bit.ly/a https://t.co/b
+
+# Machine-readable JSON output (full URLs, no truncation)
+npx xpandurl https://bit.ly/xyz --json
+
+# Custom timeout
+npx xpandurl https://bit.ly/xyz --timeout 5000
+```
+
+---
+
+## Security
+
+This library makes outbound HTTP/S requests to arbitrary URLs and follows redirects. **Treat it as an SSRF primitive** — do not pass raw user input to `expand()` or `expandMany()` in a server-side context without caller-side controls.
+
+### Server-side usage
+
+When expanding user-supplied URLs on a server, apply restrictions:
+
+```ts
+const result = await expand(userSuppliedUrl, {
+  allowHttpDowngrade: false,              // reject https → http downgrades
+  allowedHosts: ['bit.ly', 't.co', 'tinyurl.com'], // only known shorteners
+  timeout: 5000,
+  maxRedirects: 5,
+})
+```
+
+### What this library does not protect against
+
+- **DNS rebinding** — `blockPrivateIPs` and `allowedHosts` check the URL hostname, not the resolved IP. A public hostname that resolves to a private IP at connection time is not blocked. Combine with network-level egress filtering if full SSRF protection is required.
+- **Response body content** — the library never reads or saves response bodies (it closes the connection after headers), so shell scripts and other payloads are not downloaded.
+
+### HTTPS → HTTP downgrade
+
+By default, redirects from `https:` to `http:` are permitted (common in the wild). Set `allowHttpDowngrade: false` to reject them.
+
+---
+
+## License
+
+MIT — [Aman Harsh](https://github.com/amanharshx)

package/dist/cli.cjs

@@ -0,0 +1,417 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/expand.ts
+var import_node_http = __toESM(require("http"), 1);
+var import_node_https = __toESM(require("https"), 1);
+
+// src/errors.ts
+var ExpandError = class extends Error {
+  constructor(message, url) {
+    super(message);
+    this.url = url;
+    this.name = "ExpandError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  url;
+};
+var TimeoutError = class extends ExpandError {
+  constructor(url, timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms`, url);
+    this.name = "TimeoutError";
+  }
+};
+var MaxRedirectsError = class extends ExpandError {
+  constructor(url, max) {
+    super(`Exceeded maximum of ${max} redirects`, url);
+    this.name = "MaxRedirectsError";
+  }
+};
+var InvalidUrlError = class extends ExpandError {
+  constructor(url) {
+    super(`Invalid or unsupported URL: ${url}`, url);
+    this.name = "InvalidUrlError";
+  }
+};
+
+// src/expand.ts
+var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_MAX_REDIRECTS = 10;
+var DEFAULT_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
+  "localhost",
+  "metadata.google.internal"
+  // GCP metadata
+]);
+function isPrivateHost(hostname) {
+  const h = hostname.toLowerCase();
+  if (BLOCKED_HOSTNAMES.has(h)) return true;
+  if (h === "::1" || h.startsWith("fe80:") || h.startsWith("fc") || h.startsWith("fd")) {
+    return true;
+  }
+  const parts = h.split(".");
+  if (parts.length !== 4) return false;
+  const octets = parts.map(Number);
+  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return false;
+  const [a, b] = octets;
+  return a === 0 || // 0.0.0.0/8      unspecified
+  a === 10 || // 10.0.0.0/8     RFC1918
+  a === 127 || // 127.0.0.0/8    loopback
+  a === 169 && b === 254 || // 169.254.0.0/16 link-local + cloud metadata
+  a === 172 && b >= 16 && b <= 31 || // 172.16.0.0/12 RFC1918
+  a === 192 && b === 168 || // 192.168.0.0/16 RFC1918
+  a === 255;
+}
+function makeRequest(url, options) {
+  return new Promise((resolve, reject) => {
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const lib = url.startsWith("https") ? import_node_https.default : import_node_http.default;
+    const req = lib.get(
+      url,
+      {
+        headers: {
+          "User-Agent": options.userAgent ?? DEFAULT_UA,
+          Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+          ...options.headers
+        }
+      },
+      (res) => {
+        const result = {
+          statusCode: res.statusCode ?? 0,
+          location: Array.isArray(res.headers.location) ? res.headers.location[0] : res.headers.location
+        };
+        resolve(result);
+        res.destroy();
+      }
+    );
+    req.setTimeout(timeout, () => {
+      req.destroy(new TimeoutError(url, timeout));
+    });
+    req.on("error", (err) => {
+      if (err instanceof TimeoutError) {
+        reject(err);
+        return;
+      }
+      reject(new ExpandError(err.message, url));
+    });
+  });
+}
+function assertHttpProtocol(url) {
+  let protocol;
+  try {
+    protocol = new URL(url).protocol;
+  } catch {
+    throw new InvalidUrlError(url);
+  }
+  if (protocol !== "http:" && protocol !== "https:") {
+    throw new InvalidUrlError(url);
+  }
+}
+function assertHostPolicy(url, options) {
+  const { hostname } = new URL(url);
+  if (options.blockPrivateIPs !== false && isPrivateHost(hostname)) {
+    throw new ExpandError(
+      `Requests to private/local hosts are blocked ("${hostname}"). Set blockPrivateIPs: false to allow.`,
+      url
+    );
+  }
+  if (options.allowedHosts && options.allowedHosts.length > 0) {
+    if (!options.allowedHosts.includes(hostname)) {
+      throw new ExpandError(
+        `"${hostname}" is not in the allowedHosts list`,
+        url
+      );
+    }
+  }
+}
+function assertRedirectPolicy(from, to, options) {
+  if (options.allowHttpDowngrade === false) {
+    const fromProto = new URL(from).protocol;
+    const toProto = new URL(to).protocol;
+    if (fromProto === "https:" && toProto === "http:") {
+      throw new ExpandError(
+        `HTTPS to HTTP downgrade blocked (set allowHttpDowngrade: true to permit)`,
+        from
+      );
+    }
+  }
+  assertHostPolicy(to, options);
+}
+async function expand(url, options = {}) {
+  assertHttpProtocol(url);
+  assertHostPolicy(url, options);
+  const max = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+  const chain = [];
+  let current = url;
+  for (let i = 0; i <= max; i++) {
+    const { statusCode, location } = await makeRequest(current, options);
+    const isRedirect = statusCode >= 300 && statusCode < 400;
+    if (isRedirect && location) {
+      chain.push(current);
+      const next = new URL(location, current).href;
+      assertHttpProtocol(next);
+      assertRedirectPolicy(current, next, options);
+      current = next;
+      continue;
+    }
+    return {
+      originalUrl: url,
+      expandedUrl: current,
+      statusCode,
+      redirectChain: chain
+    };
+  }
+  throw new MaxRedirectsError(url, max);
+}
+
+// src/expand-many.ts
+var DEFAULT_CONCURRENCY = 5;
+async function expandMany(urls, options = {}) {
+  const concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+  const results = [];
+  for (let i = 0; i < urls.length; i += concurrency) {
+    const batch = urls.slice(i, i + concurrency);
+    const settled = await Promise.allSettled(batch.map((url) => expand(url, options)));
+    for (let j = 0; j < settled.length; j++) {
+      const outcome = settled[j];
+      if (outcome.status === "fulfilled") {
+        results.push(outcome.value);
+      } else {
+        results.push({
+          originalUrl: urls[i + j],
+          expandedUrl: urls[i + j],
+          statusCode: 0,
+          redirectChain: [],
+          error: outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason)
+        });
+      }
+    }
+  }
+  return results;
+}
+
+// src/cli.ts
+var USE_COLOR = process.stdout.isTTY === true;
+var c = {
+  bold: (s) => USE_COLOR ? `\x1B[1m${s}\x1B[0m` : s,
+  dim: (s) => USE_COLOR ? `\x1B[2m${s}\x1B[0m` : s,
+  green: (s) => USE_COLOR ? `\x1B[32m${s}\x1B[0m` : s,
+  yellow: (s) => USE_COLOR ? `\x1B[33m${s}\x1B[0m` : s,
+  red: (s) => USE_COLOR ? `\x1B[31m${s}\x1B[0m` : s,
+  cyan: (s) => USE_COLOR ? `\x1B[36m${s}\x1B[0m` : s
+};
+var AFFILIATE_PARAMS = /* @__PURE__ */ new Set([
+  "ref",
+  "ref_",
+  "affiliate",
+  "aff_id",
+  "aff_sub",
+  "partner",
+  "social_share",
+  "referral",
+  "tag",
+  "associate"
+]);
+var TRACKING_PARAMS = /* @__PURE__ */ new Set([
+  "fbclid",
+  "gclid",
+  "msclkid",
+  "twclid",
+  "ttclid",
+  "li_fat_id",
+  "clickid",
+  "click_id",
+  "_ga",
+  "mc_eid"
+]);
+function paramType(key) {
+  const k = key.toLowerCase();
+  if (k.startsWith("utm_")) return "TRACKING";
+  if (TRACKING_PARAMS.has(k)) return "TRACKING";
+  if (AFFILIATE_PARAMS.has(k)) return "AFFILIATE";
+  return "OTHER";
+}
+var STATUS_TEXT = {
+  200: "OK",
+  201: "Created",
+  204: "No Content",
+  301: "Moved Permanently",
+  302: "Found",
+  303: "See Other",
+  307: "Temporary Redirect",
+  308: "Permanent Redirect",
+  400: "Bad Request",
+  401: "Unauthorized",
+  403: "Forbidden",
+  404: "Not Found",
+  429: "Too Many Requests",
+  500: "Internal Server Error",
+  502: "Bad Gateway",
+  503: "Service Unavailable"
+};
+function colorStatus(code) {
+  const text = `${code} ${STATUS_TEXT[code] ?? ""}`;
+  if (code >= 200 && code < 300) return c.green(text);
+  if (code >= 300 && code < 400) return c.yellow(text);
+  return c.red(text);
+}
+var MAX_URL_DISPLAY = 120;
+function sanitizeForDisplay(url) {
+  return url.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "").replace(/\x1b[^[]/g, "").replace(/[\u202A-\u202E\u2066-\u2069]/g, "").replace(/[\u200B-\u200F\u2028\u2029\uFEFF]/g, "").replace(/[\x00-\x1f\x7f]/g, "");
+}
+function truncateUrl(url) {
+  if (url.length <= MAX_URL_DISPLAY) return { display: url, truncated: false };
+  return { display: `${url.slice(0, 80)}...${url.slice(-37)}`, truncated: true };
+}
+function safeUrl(raw) {
+  return truncateUrl(sanitizeForDisplay(raw));
+}
+function printRich(result, showChain) {
+  if (result.error) {
+    console.error(`  ${c.red("\u2717")} ${safeUrl(result.originalUrl).display}`);
+    console.error(`    ${c.dim(result.error)}`);
+    return;
+  }
+  const isHttps = result.expandedUrl.startsWith("https://");
+  const hopCount = result.redirectChain.length;
+  const lbl = (s) => c.dim(s.padEnd(10));
+  const expanded = safeUrl(result.expandedUrl);
+  console.log();
+  console.log(`  ${lbl("Original")}  ${safeUrl(result.originalUrl).display}`);
+  console.log(`  ${lbl("Expanded")}  ${c.cyan(expanded.display)}`);
+  if (expanded.truncated) {
+    console.log(`  ${lbl("")}  ${c.dim("full URL available via --json")}`);
+  }
+  console.log(`  ${lbl("Status")}    ${colorStatus(result.statusCode)}`);
+  console.log(`  ${lbl("Security")}  ${isHttps ? c.green("\u2713 HTTPS") : c.yellow("\u26A0 HTTP")}`);
+  if (hopCount > 0) {
+    console.log(`  ${lbl("Hops")}      ${hopCount} redirect${hopCount === 1 ? "" : "s"}`);
+  }
+  if (showChain && hopCount > 0) {
+    console.log();
+    console.log(`  ${c.bold("Redirect Chain")}`);
+    result.redirectChain.forEach((url, i) => {
+      console.log(`    ${c.dim(`${i + 1}.`)} ${safeUrl(url).display}`);
+    });
+    console.log(`    ${c.dim("\u2192")} ${expanded.display}`);
+  }
+  let params;
+  try {
+    params = new URL(result.expandedUrl).searchParams;
+  } catch {
+    console.log();
+    return;
+  }
+  const entries = [...params.entries()];
+  if (entries.length > 0) {
+    console.log();
+    console.log(`  ${c.bold("Query Parameters")} ${c.dim(`(${entries.length})`)}`);
+    const keyWidth = Math.min(Math.max(...entries.map(([k]) => k.length), 8), 24);
+    for (const [key, value] of entries) {
+      const type = paramType(key);
+      const typeStr = type === "AFFILIATE" ? c.red(type) : type === "TRACKING" ? c.yellow(type) : c.dim(type);
+      const truncated = value.length > 40 ? `${value.slice(0, 37)}...` : value;
+      console.log(`    ${c.dim(key.padEnd(keyWidth + 2))} ${truncated.padEnd(42)} ${typeStr}`);
+    }
+  }
+  console.log();
+}
+var HELP = `
+Usage: xpandurl <url> [url2 ...] [options]
+
+Arguments:
+  url           One or more URLs to expand
+
+Options:
+  --chain       Show the full redirect chain
+  --json        Output results as JSON
+  --timeout     Request timeout in milliseconds (default: 10000)
+  --help        Show this help message
+
+Examples:
+  xpandurl https://bit.ly/xyz
+  xpandurl https://bit.ly/xyz --chain
+  xpandurl https://bit.ly/a https://t.co/b --json
+`.trim();
+function parseArgs(argv) {
+  const urls = [];
+  const options = {};
+  let showChain = false;
+  let jsonOutput = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help") {
+      console.log(HELP);
+      process.exit(0);
+    } else if (arg === "--chain") {
+      showChain = true;
+    } else if (arg === "--json") {
+      jsonOutput = true;
+    } else if (arg === "--timeout") {
+      const val = Number(argv[++i]);
+      if (!Number.isFinite(val) || val <= 0) {
+        console.error("Error: --timeout must be a positive number");
+        process.exit(1);
+      }
+      options.timeout = val;
+    } else if (arg.startsWith("--")) {
+      console.error(`Error: Unknown option "${arg}". Run with --help for usage.`);
+      process.exit(1);
+    } else {
+      urls.push(arg);
+    }
+  }
+  return { urls, options, showChain, jsonOutput };
+}
+async function main() {
+  const { urls, options, showChain, jsonOutput } = parseArgs(process.argv.slice(2));
+  if (urls.length === 0) {
+    console.error("Error: No URL provided.\n");
+    console.log(HELP);
+    process.exit(1);
+  }
+  try {
+    if (urls.length === 1) {
+      const result = await expand(urls[0], options);
+      if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        printRich(result, showChain);
+      }
+    } else {
+      const results = await expandMany(urls, options);
+      if (jsonOutput) {
+        console.log(JSON.stringify(results, null, 2));
+      } else {
+        results.forEach((result) => printRich(result, showChain));
+      }
+    }
+  } catch (err) {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+main();
+//# sourceMappingURL=cli.cjs.map