fbi-proxy 1.15.0 → 1.17.0

package/ts/install-port-forward.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env bun
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+const ANCHOR_NAME = "com.snomiao.fbi-proxy";
+const ANCHOR_FILE = `/etc/pf.anchors/${ANCHOR_NAME}`;
+const PLIST_FILE = `/Library/LaunchDaemons/${ANCHOR_NAME}-pf.plist`;
+
+const argv = await yargs(hideBin(process.argv))
+  .option("from", {
+    type: "number",
+    default: 443,
+    description: "Public-facing port to redirect (privileged)",
+  })
+  .option("to", {
+    type: "number",
+    default: 8443,
+    description: "Backend port the oxmgr-managed proxy listens on",
+  })
+  .option("uninstall", {
+    type: "boolean",
+    default: false,
+    description: "Remove the pf rule and LaunchDaemon",
+  })
+  .help().argv;
+
+if (process.platform !== "darwin") {
+  console.error("install-port-forward: macOS only (pf rules)");
+  process.exit(2);
+}
+
+if (argv.uninstall) {
+  const script = [
+    `launchctl unload "${PLIST_FILE}" 2>/dev/null`,
+    `rm -f "${PLIST_FILE}" "${ANCHOR_FILE}"`,
+    `pfctl -a ${ANCHOR_NAME} -F all 2>/dev/null`,
+    "echo uninstalled",
+  ].join("\n");
+  runAsRoot(script);
+  process.exit(0);
+}
+
+// pf-rdr is loopback-only here because fbi.com resolves to 127.0.0.1 via local
+// DNS. If you ever expose this on a real interface, widen the rule.
+const anchorContent = `rdr pass on lo0 inet proto tcp from any to any port ${argv.from} -> 127.0.0.1 port ${argv.to}\n`;
+
+const plistContent = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${ANCHOR_NAME}-pf</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/sh</string>
+    <string>-c</string>
+    <string>/sbin/pfctl -E 2>/dev/null; /sbin/pfctl -a ${ANCHOR_NAME} -f ${ANCHOR_FILE}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>/var/log/${ANCHOR_NAME}-pf.out.log</string>
+  <key>StandardErrorPath</key><string>/var/log/${ANCHOR_NAME}-pf.err.log</string>
+</dict>
+</plist>
+`;
+
+if (alreadyInstalledFor(argv.from, argv.to)) {
+  console.log(
+    `pf forward :${argv.from} -> :${argv.to} already installed and active`,
+  );
+  process.exit(0);
+}
+
+console.log(
+  `installing pf forward :${argv.from} -> :${argv.to} via macOS auth dialog…`,
+);
+
+// Single elevated shell — writes both files, loads the LaunchDaemon, and
+// applies the rule immediately so we don't wait for a reboot.
+const heredoc = (path: string, body: string) =>
+  `cat > "${path}" <<'__FBI_PROXY_PF_EOF__'\n${body}__FBI_PROXY_PF_EOF__`;
+
+const script = [
+  heredoc(ANCHOR_FILE, anchorContent),
+  `chmod 644 "${ANCHOR_FILE}"`,
+  heredoc(PLIST_FILE, plistContent),
+  `chown root:wheel "${PLIST_FILE}"`,
+  `chmod 644 "${PLIST_FILE}"`,
+  `launchctl unload "${PLIST_FILE}" 2>/dev/null || true`,
+  `launchctl load -w "${PLIST_FILE}"`,
+  `/sbin/pfctl -E 2>/dev/null || true`,
+  `/sbin/pfctl -a ${ANCHOR_NAME} -f "${ANCHOR_FILE}"`,
+  `echo OK`,
+].join("\n");
+
+const status = runAsRoot(script);
+if (status !== 0) {
+  console.error(`pf forward install failed (exit ${status})`);
+  process.exit(1);
+}
+
+if (alreadyInstalledFor(argv.from, argv.to)) {
+  console.log(
+    `pf forward :${argv.from} -> :${argv.to} active. LaunchDaemon: ${PLIST_FILE}`,
+  );
+} else {
+  console.warn(
+    `pf forward installed but verification failed — check 'sudo pfctl -a ${ANCHOR_NAME} -s nat'`,
+  );
+}
+
+function runAsRoot(script: string): number {
+  const hasTty = !!process.stdin.isTTY;
+  if (hasTty && process.getuid?.() !== 0) {
+    const result = spawnSync("sudo", ["sh", "-c", script], {
+      stdio: "inherit",
+    });
+    return result.status ?? 1;
+  }
+  if (process.getuid?.() === 0) {
+    const result = spawnSync("sh", ["-c", script], { stdio: "inherit" });
+    return result.status ?? 1;
+  }
+  // GUI password dialog — works without TTY (Claude Code, oxmgr children, etc.)
+  const prompt =
+    `fbi-proxy needs administrator access to install a pf port-forward ` +
+    `(:${argv.from} → :${argv.to}) and its boot LaunchDaemon.`;
+  const osascript = `do shell script ${appleScriptQuote(script)} with prompt ${appleScriptQuote(prompt)} with administrator privileges`;
+  const result = spawnSync("osascript", ["-e", osascript], {
+    stdio: "inherit",
+  });
+  return result.status ?? 1;
+}
+
+function alreadyInstalledFor(from: number, to: number): boolean {
+  if (!existsSync(ANCHOR_FILE) || !existsSync(PLIST_FILE)) return false;
+  // -s nat needs root to read the runtime rule table on most setups
+  const probe = spawnSync(
+    "sudo",
+    ["-n", "/sbin/pfctl", "-a", ANCHOR_NAME, "-s", "nat"],
+    {
+      stdio: ["ignore", "pipe", "ignore"],
+    },
+  );
+  if (probe.status !== 0) return false;
+  const out = probe.stdout?.toString() ?? "";
+  return out.includes(`port = ${from}`) && out.includes(`port ${to}`);
+}
+
+function appleScriptQuote(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}

package/ts/routes.ts

@@ -27,6 +27,12 @@ export type RouteConfig = {
    * `{name:multi}` (one or more dot-segments — for DNS-passthrough).
    */
   match: string;
+  /**
+   * Optional path-prefix matcher. When set, the rule only matches
+   * requests whose path falls under this prefix; among host-matching
+   * rules the longest matching prefix wins. Forwarded upstream as-is.
+   */
+  path?: string;
   /**
    * Target template. Expanded with placeholder captures from `match`.
    * E.g. `"127.0.0.1:{port}"`.
@@ -46,6 +52,15 @@ export type RoutesFile = {
   routes: RouteConfig[];
 };
 
+/**
+ * Compose-style per-project config (`fbi-proxy.yaml`). The top-level
+ * `name` is the namespace (defaults to the directory name when omitted).
+ */
+export type ComposeFile = {
+  name?: string;
+  routes: RouteConfig[];
+};
+
 /** Result type for `validateRoute`. */
 export type ValidationResult =
   | { valid: true }
@@ -108,9 +123,19 @@ export function parseRoutesYaml(yaml: string): RoutesFile {
         headers[hk] = hv;
       }
     }
+    let path: string | undefined;
+    if (e.path != null) {
+      if (typeof e.path !== "string") {
+        throw new Error(
+          `routes.yaml: entry '${e.name}': \`path\` must be a string`,
+        );
+      }
+      path = e.path;
+    }
     routes.push({
       name: e.name,
       match: e.match,
+      ...(path != null ? { path } : {}),
       target: e.target,
       headers,
     });
@@ -118,6 +143,28 @@ export function parseRoutesYaml(yaml: string): RoutesFile {
   return { version: 1, routes };
 }
 
+/**
+ * Parse a compose-style `fbi-proxy.yaml`. Reuses the route validation in
+ * `parseRoutesYaml`. Returns the namespace (`name`, possibly undefined)
+ * and the parsed routes.
+ */
+export function parseComposeYaml(yaml: string): ComposeFile {
+  const raw = YAML.parse(yaml);
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("fbi-proxy.yaml must be a YAML mapping at the top level");
+  }
+  const obj = raw as Record<string, unknown>;
+  if (obj.name != null && typeof obj.name !== "string") {
+    throw new Error("fbi-proxy.yaml: `name` must be a string");
+  }
+  // parseRoutesYaml validates the `routes` list + each entry; version is
+  // optional in a compose file so default it in.
+  const { routes } = parseRoutesYaml(
+    YAML.stringify({ version: 1, routes: obj.routes ?? [] }),
+  );
+  return { name: obj.name as string | undefined, routes };
+}
+
 const PLACEHOLDER_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const VALID_KINDS = new Set(["", "int", "slug", "multi"]);
 
@@ -164,6 +211,9 @@ export function validateRoute(r: RouteConfig): ValidationResult {
   if (!r.match) return { valid: false, reason: "route `match` is required" };
   if (!r.target) return { valid: false, reason: "route `target` is required" };
 
+  if (r.path != null && !r.path.startsWith("/"))
+    return { valid: false, reason: "route `path` must start with '/'" };
+
   if (!bracesBalanced(r.match))
     return { valid: false, reason: "unbalanced braces in `match`" };
   if (!bracesBalanced(r.target))

package/ts/rulesCli.ts

@@ -0,0 +1,166 @@
+/**
+ * `fbi-proxy up | down | ps | config` — compose-style management of
+ * runtime routing rules. Each project ships an `fbi-proxy.yaml` whose
+ * top-level `name` is the namespace; rules are stored as conf.d
+ * fragments and applied live via the loopback admin API.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import YAML from "yaml";
+import { parseComposeYaml, validateRoute, type RouteConfig } from "./routes";
+import {
+  applyRules,
+  deleteRules,
+  listRules,
+  type RuleInfo,
+} from "./adminClient";
+
+const DEFAULT_FILE = "fbi-proxy.yaml";
+
+export const RULES_SUBCOMMANDS = new Set(["up", "down", "ps", "config"]);
+
+/** Derive the namespace: explicit `-p` > compose `name` > directory name. */
+function resolveNamespace(
+  explicit: string | undefined,
+  composeName: string | undefined,
+  filePath: string,
+): string {
+  if (explicit) return explicit;
+  if (composeName) return composeName;
+  // directory of the compose file (or CWD for stdin) — like docker compose.
+  return path.basename(path.dirname(path.resolve(filePath)));
+}
+
+function loadCompose(file: string): { name?: string; routes: RouteConfig[] } {
+  if (!existsSync(file)) {
+    throw new Error(
+      `[fbi-proxy] ${file} not found. Create one (compose-style):\n` +
+        `  name: my-app\n  routes:\n    - name: web\n      match: fbi.com\n      path: /\n      target: localhost:3000`,
+    );
+  }
+  const compose = parseComposeYaml(readFileSync(file, "utf8"));
+  for (const r of compose.routes) {
+    const v = validateRoute(r);
+    if (!v.valid) {
+      throw new Error(`[fbi-proxy] ${file}: rule '${r.name}': ${v.reason}`);
+    }
+  }
+  return compose;
+}
+
+function printRulesTable(rules: RuleInfo[]): void {
+  if (rules.length === 0) {
+    console.log("(no rules)");
+    return;
+  }
+  const rows = rules.map((r) => ({
+    NAMESPACE: r.namespace,
+    NAME: r.name,
+    MATCH: r.match,
+    PATH: r.path ?? "*",
+    TARGET: r.target,
+  }));
+  const cols = ["NAMESPACE", "NAME", "MATCH", "PATH", "TARGET"] as const;
+  const widths = Object.fromEntries(
+    cols.map((c) => [
+      c,
+      Math.max(c.length, ...rows.map((row) => String(row[c]).length)),
+    ]),
+  ) as Record<(typeof cols)[number], number>;
+  const fmt = (row: Record<string, string>) =>
+    cols.map((c) => String(row[c]).padEnd(widths[c])).join("  ");
+  console.log(fmt(Object.fromEntries(cols.map((c) => [c, c]))));
+  for (const row of rows) console.log(fmt(row));
+}
+
+/**
+ * Entry point dispatched from cli.ts when the first positional arg is one
+ * of `up|down|ps|config`. Returns the process exit code.
+ */
+export async function runRulesCli(rawArgs: string[]): Promise<number> {
+  const argv = await yargs(rawArgs)
+    .scriptName("fbi-proxy")
+    .command("up", "Apply this project's fbi-proxy.yaml to the running proxy")
+    .command("down", "Remove this project's rules from the running proxy")
+    .command("ps", "List active rules across all namespaces")
+    .command("config", "Print the merged resolved routing table")
+    .option("file", {
+      alias: "f",
+      type: "string",
+      default: DEFAULT_FILE,
+      description: "Path to the compose file",
+    })
+    .option("project", {
+      alias: "p",
+      type: "string",
+      description:
+        "Override the namespace (defaults to compose `name` or dir name)",
+    })
+    .option("output", {
+      alias: "o",
+      type: "string",
+      choices: ["table", "json", "yaml"] as const,
+      default: "table",
+      description: "Output format for ps/config",
+    })
+    .help().argv;
+
+  const cmd = String(argv._[0]);
+
+  try {
+    switch (cmd) {
+      case "up": {
+        const compose = loadCompose(argv.file);
+        const ns = resolveNamespace(argv.project, compose.name, argv.file);
+        const body = YAML.stringify({ version: 1, routes: compose.routes });
+        const applied = await applyRules(ns, body);
+        console.log(
+          `[fbi-proxy] up: namespace '${ns}' (${compose.routes.length} rule(s))`,
+        );
+        printRulesTable(applied.filter((r) => r.namespace === ns));
+        return 0;
+      }
+      case "down": {
+        // Namespace can come from -p, or the compose file if present.
+        let ns = argv.project;
+        if (!ns) {
+          const compose = existsSync(argv.file) ? loadCompose(argv.file) : null;
+          ns = resolveNamespace(undefined, compose?.name, argv.file);
+        }
+        const res = await deleteRules(ns);
+        console.log(
+          res.removed
+            ? `[fbi-proxy] down: removed namespace '${ns}'`
+            : `[fbi-proxy] down: namespace '${ns}' was not present`,
+        );
+        return 0;
+      }
+      case "ps":
+      case "config": {
+        const rules = await listRules();
+        if (argv.output === "json") {
+          console.log(JSON.stringify(rules, null, 2));
+        } else if (argv.output === "yaml") {
+          console.log(YAML.stringify(rules));
+        } else {
+          printRulesTable(rules);
+        }
+        return 0;
+      }
+      default:
+        console.error(`[fbi-proxy] unknown command '${cmd}'`);
+        return 2;
+    }
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e));
+    return 1;
+  }
+}
+
+/** Convenience for standalone invocation/testing. */
+if (import.meta.main) {
+  runRulesCli(hideBin(process.argv)).then((code) => process.exit(code));
+}