Triple-C/app/src/lib/urlRelay.ts

/**
 * URL relay — host side of `container/triple-c-open`.
 *
 * A CLI inside the container has no browser. When it wants to open a URL
 * (`gh auth login`, `aws sso login`, `gcloud auth login`, anything honouring
 * `$BROWSER` or shelling out to `xdg-open`), the container-side shim writes
 *
 *     ESC ] 7777 ; open ; <base64(url)> BEL
 *
 * to its controlling terminal. xterm.js routes that to an OSC 7777 handler,
 * which lands here.
 *
 * THE CONTAINER IS THE UNTRUSTED SIDE OF THIS BOUNDARY. Everything arriving
 * over the relay is attacker-controlled if the sandboxed agent misbehaves, so
 * this module is a validator first and a convenience second:
 *
 *  - only `http:` and `https:` survive — `file:`, `javascript:`, `data:` and
 *    every custom/registered URI handler are rejected. A container able to
 *    make the host open arbitrary schemes could reach local files, in-page
 *    script, or any protocol handler the OS has registered, which is a real
 *    escalation out of the sandbox.
 *  - embedded credentials (`https://user:pass@host`) are rejected: they are a
 *    display-spoofing vector in the confirmation toast and in the address bar.
 *  - control characters, whitespace and oversized payloads are rejected before
 *    parsing, so the relay can't be used to smuggle escape sequences or to
 *    push a megabyte of text into the UI.
 *  - the URL is returned in WHATWG-normalized form, so what the user is shown
 *    in the toast is exactly what gets opened.
 *
 * Opening is never automatic — see `RelayRateLimiter` and the confirmation
 * toast in TerminalView.
 */

/** Private OSC identifier used by the relay. Chosen to avoid the numbers in
 *  common use (0-19, 22, 52, 104, 110-119, 133, 777, 1337). */
export const URL_RELAY_OSC = 7777;

/** Hard cap on a relayed URL. Real OAuth URLs run to a few hundred chars. */
export const MAX_RELAY_URL_LENGTH = 8192;

/**
 * Validate a URL the container asked the host to open.
 *
 * @returns the normalized URL, or `null` if it must not be opened.
 */
export function sanitizeRelayUrl(raw: unknown): string | null {
  if (typeof raw !== "string") return null;

  const candidate = raw.trim();
  if (candidate.length === 0) return null;
  if (candidate.length > MAX_RELAY_URL_LENGTH) return null;

  // No whitespace or control characters anywhere. Rejecting these before
  // parsing matters: `new URL()` silently strips tabs/newlines, so
  // "java\nscript:alert(1)" would otherwise parse as a javascript: URL.
  // eslint-disable-next-line no-control-regex
  if (/[\s\u0000-\u0020\u007f]/.test(candidate)) return null;

  let parsed: URL;
  try {
    parsed = new URL(candidate);
  } catch {
    return null;
  }

  // Scheme allowlist. Nothing else, ever.
  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;

  // A special-scheme URL with no host is nonsense and, on some platforms,
  // resolves in surprising ways.
  if (parsed.hostname === "") return null;

  // Embedded credentials spoof the displayed origin.
  if (parsed.username !== "" || parsed.password !== "") return null;

  const normalized = parsed.toString();
  if (normalized.length > MAX_RELAY_URL_LENGTH) return null;

  return normalized;
}

/**
 * Parse the payload of an OSC 7777 sequence (everything between `ESC]7777;`
 * and the terminator).
 *
 * Expected shape: `open;<base64(url)>`. The URL is base64-encoded so that a
 * `;`, a BEL or an ESC inside it cannot break out of the sequence.
 *
 * @returns the validated URL, or `null` if the payload is malformed or the
 *          URL fails {@link sanitizeRelayUrl}.
 */
export function parseUrlRelayOsc(data: string): string | null {
  if (typeof data !== "string") return null;

  const sep = data.indexOf(";");
  if (sep === -1) return null;

  const verb = data.slice(0, sep);
  if (verb !== "open") return null;

  const payload = data.slice(sep + 1);
  if (payload.length === 0) return null;
  // base64 of the length cap, plus slack for padding.
  if (payload.length > MAX_RELAY_URL_LENGTH * 2) return null;
  if (!/^[A-Za-z0-9+/]+=*$/.test(payload)) return null;

  let decoded: string;
  try {
    const binary = atob(payload);
    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
    decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
  } catch {
    return null;
  }

  return sanitizeRelayUrl(decoded);
}

/**
 * Throttles relay requests so a runaway (or hostile) process in the container
 * can't bury the UI in prompts.
 *
 * Two limits: a sliding window on total requests, and a short dedup window so
 * a retry loop around a single URL produces one prompt rather than twenty.
 */
export class RelayRateLimiter {
  private readonly maxInWindow: number;
  private readonly windowMs: number;
  private readonly dedupeMs: number;
  private timestamps: number[] = [];
  private lastUrl: string | null = null;
  private lastUrlAt = 0;

  constructor(maxInWindow = 5, windowMs = 10_000, dedupeMs = 5_000) {
    this.maxInWindow = maxInWindow;
    this.windowMs = windowMs;
    this.dedupeMs = dedupeMs;
  }

  /** @returns true if this request should be surfaced to the user. */
  allow(url: string, now: number = Date.now()): boolean {
    if (url === this.lastUrl && now - this.lastUrlAt < this.dedupeMs) {
      this.lastUrlAt = now;
      return false;
    }

    this.timestamps = this.timestamps.filter((t) => now - t < this.windowMs);
    if (this.timestamps.length >= this.maxInWindow) return false;

    this.timestamps.push(now);
    this.lastUrl = url;
    this.lastUrlAt = now;
    return true;
  }
}