apiblaze 0.4.13 → 0.5.0

package/README.md

@@ -69,6 +69,7 @@ Every chat turn shows its cost.
 | Command | What it does |
 |---|---|
 | `apiblaze create --target <url>` | Make an API from a backend (no account needed) |
+| `apiblaze sidecar` | Route a Next.js app's external `fetch()` calls through APIblaze (one command) |
 | `apiblaze dev [port]` | Put your localhost behind a public URL |
 | `apiblaze login` / `logout` | Sign in / out (logout asks producer or consumer) |
 | `apiblaze whoami` | Who am I — both Producer and Consumer |
@@ -130,7 +131,37 @@ shows both, and `logout` asks which to drop.
 
 On Ctrl+C the tunnel is cleanly deregistered.
 
-### Zero-setup conveniences
+## Sidecar — proxy a Next.js app's egress
+
+`apiblaze sidecar` wires your Next.js backend so its outbound `fetch()` calls
+transparently route through APIblaze. Each distinct upstream origin (Stripe, an
+internal API, anything) lazily becomes a first-class APIblaze proxy on first use
+— so you get identity, rate-limits, quotas, and audit wrapped around APIs that
+have none of it, with no per-call changes.
+
+```bash
+cd my-next-app
+npx apiblaze sidecar     # logs you in, mints a scoped key, wires it up
+npm install apiblaze
+npm run dev              # then open http://localhost:3000/abz-inspector
+```
+
+The command mints a **scoped data-plane key** (create/use proxies for one team,
+nothing else) into gitignored `.env.local` as `APIBLAZE_TOKEN` + `APIBLAZE_TENANT`.
+Your control-plane login stays in `~/.apiblaze` and never enters the project. It
+also writes `instrumentation.ts`:
+
+```ts
+import { register as apiblaze } from "apiblaze/sidecar";
+export function register() { apiblaze(); }
+```
+
+The interceptor is stateless and fail-open: if it can't reach APIblaze it falls
+back to a direct fetch, so it never breaks your app. External HTTPS origins are
+intercepted; same-origin, localhost/private, and known analytics/CDN noise are
+left alone.
+
+## How it works
 
 - **No project yet?** If none of your projects point at this machine, `apiblaze dev`
   offers to spin up a throwaway dev proxy (random name like `braveotter42`) pointed at

package/dist/index.js

@@ -25,10 +25,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/index.ts
 var import_commander = require("commander");
-var import_chalk28 = __toESM(require("chalk"));
+var import_chalk29 = __toESM(require("chalk"));
 
 // package.json
-var version = "0.4.13";
+var version = "0.5.0";
 
 // src/types.ts
 var ApiError = class extends Error {
@@ -105,9 +105,9 @@ async function createProxyAnonymous(body) {
   }
   return res.json();
 }
-async function apiFetch(path3, options = {}) {
+async function apiFetch(path4, options = {}) {
   const token = getAccessToken();
-  const url = `${DASHBOARD_BASE}${path3}`;
+  const url = `${DASHBOARD_BASE}${path4}`;
   const res = await fetch(url, {
     ...options,
     headers: {
@@ -132,12 +132,12 @@ async function apiFetch(path3, options = {}) {
   }
   return res.json();
 }
-async function agentCall(path3, method, body) {
+async function agentCall(path4, method, body) {
   const token = getAccessToken();
   const res = await fetch(`${DASHBOARD_BASE}/api/cli/agents`, {
     method: "POST",
     headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
-    body: JSON.stringify({ path: path3, method, body })
+    body: JSON.stringify({ path: path4, method, body })
   });
   let data = null;
   try {
@@ -420,11 +420,11 @@ function decodeJwt(token) {
     return null;
   }
 }
-function maskPath(path3) {
-  const q = path3.indexOf("?");
-  if (q < 0) return path3;
-  const base = path3.slice(0, q);
-  const query = path3.slice(q + 1);
+function maskPath(path4) {
+  const q = path4.indexOf("?");
+  if (q < 0) return path4;
+  const base = path4.slice(0, q);
+  const query = path4.slice(q + 1);
   const masked = query.split("&").map((pair) => {
     const eq = pair.indexOf("=");
     if (eq < 0) return pair;
@@ -3037,6 +3037,192 @@ async function runConsumerApikeys(opts) {
   else console.log(import_chalk27.default.dim("  Key created; run `apiblaze consumer apikeys` to reveal it if it expires."));
 }
 
+// src/commands/sidecar.ts
+var import_chalk28 = __toESM(require("chalk"));
+var import_ora13 = __toESM(require("ora"));
+var fs6 = __toESM(require("fs"));
+var path3 = __toESM(require("path"));
+function detectNextProject(root) {
+  const hasConfig = ["next.config.js", "next.config.mjs", "next.config.ts"].some((f) => fs6.existsSync(path3.join(root, f)));
+  let hasDep = false;
+  try {
+    const pkg = JSON.parse(fs6.readFileSync(path3.join(root, "package.json"), "utf8"));
+    hasDep = !!(pkg.dependencies?.next || pkg.devDependencies?.next);
+  } catch {
+  }
+  const appDir = fs6.existsSync(path3.join(root, "app")) || fs6.existsSync(path3.join(root, "src", "app"));
+  const pagesDir = fs6.existsSync(path3.join(root, "pages")) || fs6.existsSync(path3.join(root, "src", "pages"));
+  return {
+    found: hasConfig || hasDep || appDir || pagesDir,
+    router: appDir ? "app" : pagesDir ? "pages" : null
+  };
+}
+function upsertEnvLocal(root, token, tenant2) {
+  const p = path3.join(root, ".env.local");
+  let existing = "";
+  try {
+    existing = fs6.readFileSync(p, "utf8");
+  } catch {
+  }
+  const hadToken = /^APIBLAZE_TOKEN=/m.test(existing);
+  let next = existing;
+  const set = (k, v) => {
+    if (new RegExp(`^${k}=`, "m").test(next)) next = next.replace(new RegExp(`^${k}=.*$`, "m"), `${k}=${v}`);
+    else next = (next && !next.endsWith("\n") ? next + "\n" : next) + `${k}=${v}
+`;
+  };
+  set("APIBLAZE_TOKEN", token);
+  set("APIBLAZE_TENANT", tenant2);
+  fs6.writeFileSync(p, next);
+  return hadToken ? "rotated" : existing ? "reused" : "created";
+}
+function ensureGitignored(root) {
+  const p = path3.join(root, ".gitignore");
+  let content = "";
+  try {
+    content = fs6.readFileSync(p, "utf8");
+  } catch {
+  }
+  if (!/^\.env\.local$/m.test(content) && !/^\.env\*/m.test(content)) {
+    fs6.writeFileSync(p, (content && !content.endsWith("\n") ? content + "\n" : content) + ".env.local\n");
+  }
+}
+function wireInstrumentation(root) {
+  const candidates = ["instrumentation.ts", "instrumentation.js", path3.join("src", "instrumentation.ts")];
+  const existing = candidates.map((c) => path3.join(root, c)).find((f) => fs6.existsSync(f));
+  const body = `import { register as apiblaze } from "apiblaze/sidecar";
+
+export function register() {
+  apiblaze();
+}
+`;
+  if (!existing) {
+    fs6.writeFileSync(path3.join(root, "instrumentation.ts"), body);
+    return "created";
+  }
+  const cur = fs6.readFileSync(existing, "utf8");
+  if (cur.includes("apiblaze/sidecar")) return "present";
+  if (/export\s+function\s+register\s*\(/.test(cur)) {
+    const patched = `import { register as apiblaze } from "apiblaze/sidecar";
+` + cur.replace(/export\s+function\s+register\s*\(\s*\)\s*\{/, (m) => `${m}
+  apiblaze();`);
+    fs6.writeFileSync(existing, patched);
+    return "patched";
+  }
+  fs6.writeFileSync(existing, `import { register as apiblaze } from "apiblaze/sidecar";
+${cur}
+// apiblaze(): call apiblaze() inside your register() export.
+`);
+  return "patched";
+}
+var INSPECTOR_PAGE = `// AUTO-GENERATED by \`apiblaze sidecar\` \u2014 dev-only smoke test. Safe to delete.
+// Proves the whole lazy path: interception \u2192 edge auth \u2192 auto-provision \u2192
+// header transform \u2192 convergence. Fires a fetch at httpbingo THROUGH the sidecar
+// and echoes what the upstream actually received.
+export const dynamic = "force-dynamic";
+
+async function probe() {
+  const res = await fetch("https://httpbingo.org/headers", {
+    headers: { "x-api-key": "demo-secret-value" },
+    cache: "no-store",
+  });
+  const body = await res.json().catch(() => ({}));
+  return { status: res.status, sidecar: res.headers.get("x-abz-sidecar"), echo: body };
+}
+
+export default async function Page() {
+  if (process.env.NODE_ENV === "production") {
+    return <main style={{ padding: 24 }}>Inspector is disabled in production.</main>;
+  }
+  let result: any = null, error: string | null = null;
+  try { result = await probe(); } catch (e: any) { error = e?.message ?? String(e); }
+  const ok = result && result.status === 200;
+  return (
+    <main style={{ fontFamily: "ui-monospace, monospace", padding: 24, lineHeight: 1.6 }}>
+      <h1>APIblaze sidecar inspector</h1>
+      <p>{ok ? "\u2705 intercepted + relayed" : "\u26A0\uFE0F check the result below"}</p>
+      <p>edge path: <b>{result?.sidecar ?? "(no x-abz-sidecar header \u2014 was the fetch intercepted?)"}</b>
+         {" "}(first call \u2192 "miss"; after ~60s of propagation, provisioned path)</p>
+      <p>The upstream echoes the headers it received \u2014 you should see <code>x-api-key</code>
+         (the marker suffix stripped), and NOT <code>x-abz-target</code> or any APIblaze identity header.</p>
+      {error && <pre style={{ color: "crimson" }}>{error}</pre>}
+      <pre>{JSON.stringify(result?.echo ?? {}, null, 2)}</pre>
+      <form><button formAction="" style={{ padding: "8px 16px" }}>Run again</button></form>
+      <p style={{ opacity: 0.6 }}>Delete app/abz-inspector/ (or pages/abz-inspector) before shipping.</p>
+    </main>
+  );
+}
+`;
+function generateInspector(root, router) {
+  try {
+    if (router === "pages") {
+      const dir2 = fs6.existsSync(path3.join(root, "src", "pages")) ? path3.join(root, "src", "pages") : path3.join(root, "pages");
+      const f2 = path3.join(dir2, "abz-inspector.tsx");
+      fs6.writeFileSync(f2, INSPECTOR_PAGE);
+      return path3.relative(root, f2);
+    }
+    const base = fs6.existsSync(path3.join(root, "src", "app")) ? path3.join(root, "src", "app") : path3.join(root, "app");
+    const dir = path3.join(base, "abz-inspector");
+    fs6.mkdirSync(dir, { recursive: true });
+    const f = path3.join(dir, "page.tsx");
+    fs6.writeFileSync(f, INSPECTOR_PAGE);
+    return path3.relative(root, f);
+  } catch {
+    return null;
+  }
+}
+async function runSidecar(opts) {
+  const root = path3.resolve(opts.dir ?? process.cwd());
+  if (!loadCredentials()) {
+    console.log(import_chalk28.default.dim("Not logged in \u2014 starting APIblaze login first..."));
+    await runLogin();
+  }
+  const detected = detectNextProject(root);
+  if (!detected.found) {
+    console.log(import_chalk28.default.yellow(`No Next.js project detected in ${root}.`));
+    console.log("Create one first (e.g. `npx create-next-app`), then re-run `apiblaze sidecar` inside it.");
+    return;
+  }
+  const { teamId, teamName } = await resolveTeam(opts.team);
+  const spinner = (0, import_ora13.default)("Minting a scoped sidecar key...").start();
+  let key, tenant2, keyId;
+  try {
+    const out = await admin({
+      method: "POST",
+      path: `/teams/${encodeURIComponent(teamId)}/developer-keys`,
+      body: { role: "sidecar", description: `sidecar key for ${path3.basename(root)}` },
+      summary: `Mint a sidecar data-plane key for team ${teamName ?? teamId}`
+    });
+    key = out.key;
+    tenant2 = out.tenant;
+    keyId = out.key_id;
+    spinner.succeed("Sidecar key minted.");
+  } catch (err) {
+    spinner.fail("Key mint failed.");
+    throw err;
+  }
+  const envState = upsertEnvLocal(root, key, tenant2);
+  ensureGitignored(root);
+  console.log(`  ${import_chalk28.default.green("\u2713")} .env.local ${envState} (APIBLAZE_TOKEN, APIBLAZE_TENANT) \u2014 gitignored`);
+  const wireState = wireInstrumentation(root);
+  console.log(`  ${import_chalk28.default.green("\u2713")} instrumentation.ts ${wireState} (register apiblaze/sidecar)`);
+  console.log(`  ${import_chalk28.default.dim("\u2022")} install the runtime dep:  ${import_chalk28.default.cyan("npm install apiblaze")}`);
+  let inspectorPath = null;
+  if (!opts.noInspector) {
+    inspectorPath = generateInspector(root, detected.router);
+    if (inspectorPath) console.log(`  ${import_chalk28.default.green("\u2713")} inspector at ${inspectorPath}  \u2192  visit /abz-inspector (dev only)`);
+  }
+  console.log("");
+  console.log(import_chalk28.default.bold("Done. Next steps:"));
+  console.log(`  1. ${import_chalk28.default.cyan("npm install apiblaze")}`);
+  console.log(`  2. ${import_chalk28.default.cyan("npm run dev")} then open ${import_chalk28.default.underline("http://localhost:3000/abz-inspector")}`);
+  console.log(`  3. Your external https fetches now route through APIblaze \u2014 see them in the dashboard (badged "auto-provisioned").`);
+  console.log("");
+  console.log(import_chalk28.default.dim(`  Key id ${keyId} \xB7 revoke anytime:  apiblaze apikeys revoke ${keyId}`));
+  if (inspectorPath) console.log(import_chalk28.default.dim(`  Remove the inspector before shipping:  rm -rf ${path3.dirname(inspectorPath)}`));
+  console.log(import_chalk28.default.dim("  The control-plane login stays in ~/.apiblaze \u2014 it never entered this project."));
+}
+
 // src/index.ts
 var program = new import_commander.Command();
 program.name("apiblaze").description("APIblaze CLI \u2014 create & manage API proxies and run dev tunnels").version(version).option("-v, --verbose", "Print the exact series of API calls each command makes (curl-equivalent you could run yourself)");
@@ -3076,11 +3262,12 @@ var agent = program.command("agent").description("Chat with an assistant that bu
 agent.command("authz").description("Chat to design and turn on access rules for an API").argument("<project>", "Project name or id").argument("[apiVersion]", "API version (defaults to the project's)").action(action((project, apiVersion) => runAuthz(project, apiVersion)));
 agent.command("openapi").description("Chat to build your API spec from real traffic").argument("<project>", "Project name or id").argument("[apiVersion]", "API version (defaults to the project's)").action(action((project, apiVersion) => runOpenapi(project, apiVersion)));
 agent.command("mcp").description("Chat to build an MCP server for an API").argument("<project>", "Project name or id").argument("[apiVersion]", "API version (defaults to the project's)").option("--environment <env>", "Environment to publish (default: prod)").action(action((project, apiVersion, opts) => runMcp(project, apiVersion, opts)));
+program.command("sidecar").description("Wire a Next.js app to route its external fetches through APIblaze (one command)").option("--team <id|name>", "Team to provision under (defaults to your active team)").option("--dir <path>", "Project directory (defaults to cwd)").option("--no-inspector", "Skip generating the dev-only /abz-inspector smoke-test page").option("-y, --yes", "Skip prompts").action(action((opts) => runSidecar({ team: opts.team, dir: opts.dir, yes: opts.yes, noInspector: opts.inspector === false })));
 program.command("dev").description("Put your localhost behind a public URL (dev tunnel)").argument("[port]", "Local port to tunnel (positional; overrides --port)").option("-p, --port <number>", "Local port to tunnel", "3000").option("-o, --capture-file <path>", "Stream full request/response traffic to a file (JSON lines)").action(async (port, opts) => {
   try {
     const resolved = parseInt(port ?? opts.port, 10);
     if (Number.isNaN(resolved)) {
-      console.error(import_chalk28.default.red(`Invalid port: ${port ?? opts.port}`));
+      console.error(import_chalk29.default.red(`Invalid port: ${port ?? opts.port}`));
       process.exit(1);
     }
     await runDev({ port: resolved, captureFile: opts.captureFile });
@@ -3127,7 +3314,7 @@ program.command("projects").description("List the projects in your team").action
   }
 });
 program.command("delete").description("Delete a proxy and everything under it (asks first)").argument("<project>", "Project name or id (see `apiblaze projects`)").argument("[version]", "API version (defaults to the first match)").option("--team <id|name>", "Team the project is in (defaults to active team)").option("-y, --yes", "Skip the confirmation prompt").option("--json", "Output machine-readable JSON").action(action((project, version2, opts) => runDelete(project, version2, opts)));
-program.command("export").description("Export everything to migrate off apiblaze (no lock-in): config, users, keys + fidelity report").argument("<project>", "Project name or id (see `apiblaze projects`)").argument("[version]", "API version (defaults to the first match)").option("--kong", "Produce a runnable Kong OSS bundle (decK config + plugins + docker-compose)").option("--data", "Target-neutral data export (default)").option("--secrets", "Include decrypted producer-supplied secrets (member role; audit-logged)").option("--keys <mode>", "API-key export: hashes (default, consumers keep keys) | mint | none").option("--no-consumers", "Skip the end-user lane (users, groups, keys)").option("-o, --out <file>", "Output zip path").option("--team <id|name>", "Team the project is in (defaults to active team)").action(action((project, version2, opts) => runExport(project, version2, { ...opts, noConsumers: opts.consumers === false })));
+program.command("export").description("Export config and data for migration out of APIblaze (Kong, ...)").argument("<project>", "Project name or id (see `apiblaze projects`)").argument("[version]", "API version (defaults to the first match)").option("--kong", "Produce a runnable Kong OSS bundle (decK config + plugins + docker-compose)").option("--data", "Plain data export (default)").option("--secrets", "Include decrypted producer-supplied secrets (member role; audit-logged)").option("--keys <mode>", "API-key export: hashes (default, consumers keep keys) | mint | none").option("--no-consumers", "Skip the end-user lane (users, groups, keys)").option("-o, --out <file>", "Output zip path").option("--team <id|name>", "Team the project is in (defaults to active team)").action(action((project, version2, opts) => runExport(project, version2, { ...opts, noConsumers: opts.consumers === false })));
 program.command("target").description("Change where a proxy forwards requests").argument("<project>", "Project name or id").requiredOption("--url <url>", "Target URL to forward to").option("--env <env>", "Environment to scope the target to (e.g. prod, dev)").option("--team <id|name>", "Team the project is in").option("--apiversion <version>", "API version (defaults to the first match)").option("--json", "Output machine-readable JSON").action(action((project, opts) => runTargetSet(project, opts)));
 program.command("throttle").description("Set rate limits and quotas for a proxy").argument("<project>", "Project name or id").option("--rate <n>", "User rate limit (requests/sec)").option("--end-user-rate <n>", "Per-end-user rate limit (requests/sec)").option("--quota <n>", "Proxy quota (requests/period)").option("--period <p>", "Quota period: daily | weekly | monthly").option("--team <id|name>", "Team the project is in").option("--apiversion <version>", "API version").option("--json", "Output machine-readable JSON").action(action((project, opts) => runThrottleSet(project, opts)));
 program.command("rename").description("Change a proxy's display name").argument("<project>", "Project name or id").requiredOption("--display-name <name>", "New human-friendly display name").option("--team <id|name>", "Team the project is in").option("--apiversion <version>", "API version").option("--json", "Output machine-readable JSON").action(action((project, opts) => runRename(project, opts)));
@@ -3153,8 +3340,8 @@ spec.command("get").description("Print the current OpenAPI document").argument("
 spec.command("set").description("Replace the stored OpenAPI spec from a local file").argument("<project>", "Project name or id").requiredOption("--file <path>", "OpenAPI JSON or YAML file to upload").option("--team <id|name>", "Team the project is in").option("--apiversion <version>", "API version").option("--json", "Output machine-readable JSON").action(action((project, opts) => runSpecSet(project, opts)));
 var HELP_GROUPS = [
   { title: "Chat", commands: ["agent"] },
-  { title: "Setup", commands: ["login", "create", "dev", "claim", "team", "whoami", "logout"] },
-  { title: "Control plane commands", commands: ["projects", "tenant", "domain", "delete", "target", "throttle", "rename", "spec"] },
+  { title: "Setup", commands: ["login", "create", "sidecar", "dev", "claim", "team", "whoami", "logout"] },
+  { title: "Control plane commands", commands: ["projects", "tenant", "domain", "delete", "target", "throttle", "rename", "spec", "export"] },
   { title: "Data plane commands", commands: [
     { parent: "consumer", sub: "login" },
     { parent: "consumer", sub: "apikeys" }
@@ -3173,7 +3360,7 @@ function groupedCommandHelp() {
       const sub = byName.get(e.parent)?.commands.find((s) => s.name() === e.sub);
       return sub ? `  ${helpLabel(e).padEnd(width)}${sub.description()}` : "";
     }).filter(Boolean).join("\n");
-    return `${import_chalk28.default.bold(g.title)}
+    return `${import_chalk29.default.bold(g.title)}
 ${rows}`;
   }).join("\n\n");
 }
@@ -3199,13 +3386,13 @@ Examples:
 `);
 function printError(err) {
   if (err instanceof ApiError) {
-    console.error(import_chalk28.default.red(`
+    console.error(import_chalk29.default.red(`
 API error (${err.status}): ${err.message}`));
   } else if (err instanceof Error) {
-    console.error(import_chalk28.default.red(`
+    console.error(import_chalk29.default.red(`
 Error: ${err.message}`));
   } else {
-    console.error(import_chalk28.default.red("\nUnknown error"));
+    console.error(import_chalk29.default.red("\nUnknown error"));
   }
 }
 program.parse(process.argv);

package/dist/sidecar/index.d.mts

@@ -0,0 +1,50 @@
+/**
+ * apiblaze/sidecar — the egress interceptor.
+ * Spec: specs/sidecar/apiblaze-sidecar-implementation-spec.md §11.
+ *
+ * Import in a Next.js backend to route outbound fetch() calls through APIblaze:
+ *
+ *   // instrumentation.ts
+ *   import { register as apiblaze } from "apiblaze/sidecar";
+ *   export function register() { apiblaze(); }
+ *
+ *   // or next.config.js
+ *   import { withApiblaze } from "apiblaze/sidecar";
+ *   export default withApiblaze({ /* your next config *\/ });
+ *
+ * Reads APIBLAZE_TOKEN + APIBLAZE_TENANT from env. STATELESS — it never learns
+ * whether a proxy exists; it applies the same transform on call 1 and call N.
+ * All state lives at the edge. If either env var is missing it no-ops with a
+ * single boot warning and NEVER breaks the app.
+ */
+interface SidecarOptions {
+    token?: string;
+    tenant?: string;
+    /** Extra origin globs to never intercept (in addition to the noise denylist). */
+    exclude?: string[];
+    /** Only intercept these origin globs (when set, everything else passes direct). */
+    include?: string[];
+    /** Suppress the boot log line. */
+    quiet?: boolean;
+}
+/**
+ * Install the interceptor. Wraps the current globalThis.fetch (which Next has
+ * already patched for cache semantics) so caching survives — we only reroute the
+ * actual egress. Idempotent: safe to call from both next.config and
+ * instrumentation without double-wrapping.
+ */
+declare function register(opts?: SidecarOptions): void;
+/**
+ * next.config wrapper: injects instrumentation registration. Returns the config
+ * with `instrumentationHook` enabled (Next <15) — on Next 15+ instrumentation is
+ * always on, so the flag is a harmless no-op. The actual register() call still
+ * needs an instrumentation.ts (the scaffolder writes one); this wrapper mainly
+ * exists as the documented most-zero entry point and to enable the hook.
+ */
+declare function withApiblaze<T extends Record<string, unknown>>(nextConfig?: T): T;
+declare const _default: {
+    register: typeof register;
+    withApiblaze: typeof withApiblaze;
+};
+
+export { type SidecarOptions, _default as default, register, withApiblaze };

package/dist/sidecar/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * apiblaze/sidecar — the egress interceptor.
+ * Spec: specs/sidecar/apiblaze-sidecar-implementation-spec.md §11.
+ *
+ * Import in a Next.js backend to route outbound fetch() calls through APIblaze:
+ *
+ *   // instrumentation.ts
+ *   import { register as apiblaze } from "apiblaze/sidecar";
+ *   export function register() { apiblaze(); }
+ *
+ *   // or next.config.js
+ *   import { withApiblaze } from "apiblaze/sidecar";
+ *   export default withApiblaze({ /* your next config *\/ });
+ *
+ * Reads APIBLAZE_TOKEN + APIBLAZE_TENANT from env. STATELESS — it never learns
+ * whether a proxy exists; it applies the same transform on call 1 and call N.
+ * All state lives at the edge. If either env var is missing it no-ops with a
+ * single boot warning and NEVER breaks the app.
+ */
+interface SidecarOptions {
+    token?: string;
+    tenant?: string;
+    /** Extra origin globs to never intercept (in addition to the noise denylist). */
+    exclude?: string[];
+    /** Only intercept these origin globs (when set, everything else passes direct). */
+    include?: string[];
+    /** Suppress the boot log line. */
+    quiet?: boolean;
+}
+/**
+ * Install the interceptor. Wraps the current globalThis.fetch (which Next has
+ * already patched for cache semantics) so caching survives — we only reroute the
+ * actual egress. Idempotent: safe to call from both next.config and
+ * instrumentation without double-wrapping.
+ */
+declare function register(opts?: SidecarOptions): void;
+/**
+ * next.config wrapper: injects instrumentation registration. Returns the config
+ * with `instrumentationHook` enabled (Next <15) — on Next 15+ instrumentation is
+ * always on, so the flag is a harmless no-op. The actual register() call still
+ * needs an instrumentation.ts (the scaffolder writes one); this wrapper mainly
+ * exists as the documented most-zero entry point and to enable the hook.
+ */
+declare function withApiblaze<T extends Record<string, unknown>>(nextConfig?: T): T;
+declare const _default: {
+    register: typeof register;
+    withApiblaze: typeof withApiblaze;
+};
+
+export { type SidecarOptions, _default as default, register, withApiblaze };

package/dist/sidecar/index.js

@@ -0,0 +1,192 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sidecar/index.ts
+var sidecar_exports = {};
+__export(sidecar_exports, {
+  default: () => sidecar_default,
+  register: () => register,
+  withApiblaze: () => withApiblaze
+});
+module.exports = __toCommonJS(sidecar_exports);
+var ABZ_TARGET_HEADER = "x-abz-target";
+var MARK_SUFFIX = "-abz-target";
+var DATA_PLANE = "abz.run";
+var NOISE_DENYLIST = [
+  "google-analytics.com",
+  "googletagmanager.com",
+  "segment.io",
+  "segment.com",
+  "sentry.io",
+  "ingest.sentry.io",
+  "posthog.com",
+  "mixpanel.com",
+  "amplitude.com",
+  "datadoghq.com",
+  "newrelic.com",
+  "nr-data.net",
+  "honeycomb.io",
+  "launchdarkly.com",
+  "statsigapi.net",
+  "plausible.io",
+  "hotjar.com",
+  "fullstory.com",
+  "intercom.io",
+  "avatars.githubusercontent.com",
+  "gravatar.com",
+  "googleusercontent.com",
+  "cloudfront.net",
+  "akamaihd.net",
+  "fastly.net",
+  "imgix.net",
+  "cloudinary.com",
+  "unsplash.com",
+  "twimg.com",
+  "fbcdn.net",
+  "registry.npmjs.org",
+  "pypi.org",
+  "github.io"
+];
+var installed = false;
+function canonicalizeOrigin(input) {
+  try {
+    const u = new URL(input);
+    if (u.protocol !== "https:") return null;
+    const port = u.port && u.port !== "443" ? `:${u.port}` : "";
+    return `https://${u.hostname.toLowerCase()}${port}`;
+  } catch {
+    return null;
+  }
+}
+async function sha256Hex(s) {
+  const data = new TextEncoder().encode(s);
+  const buf = await globalThis.crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function sidecarHost(tenant, canonicalOrigin) {
+  const h = await sha256Hex(`${tenant}|${canonicalOrigin}`);
+  return `sc${h.slice(0, 16)}.${DATA_PLANE}`;
+}
+function hostMatchesGlob(host, glob) {
+  const g = glob.toLowerCase();
+  if (g.startsWith("*.")) {
+    const base = g.slice(2);
+    return host === base || host.endsWith(`.${base}`);
+  }
+  return host === g;
+}
+function isNoise(host) {
+  return NOISE_DENYLIST.some((d) => host === d || host.endsWith(`.${d}`));
+}
+function isPrivateOrLocal(host) {
+  if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return true;
+  if (/^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return true;
+  if (/^169\.254\./.test(host)) return true;
+  return false;
+}
+function shouldIntercept(cfg, url) {
+  if (url.protocol !== "https:") return false;
+  const host = url.hostname.toLowerCase();
+  if (host.endsWith(DATA_PLANE) || host.endsWith("tryabz.run") || host.endsWith("apiblaze.com")) return false;
+  if (isPrivateOrLocal(host)) return false;
+  if (isNoise(host)) return false;
+  if (cfg.exclude.some((g) => hostMatchesGlob(host, g))) return false;
+  if (cfg.include.length > 0 && !cfg.include.some((g) => hostMatchesGlob(host, g))) return false;
+  return true;
+}
+async function rewrite(cfg, input) {
+  const url = new URL(input.url);
+  if (!shouldIntercept(cfg, url)) return null;
+  const origin = canonicalizeOrigin(url.origin);
+  if (!origin) return null;
+  const host = await sidecarHost(cfg.tenant, origin);
+  const newUrl = new URL(input.url);
+  newUrl.protocol = "https:";
+  newUrl.host = host;
+  newUrl.pathname = `/1.0.0/prod${url.pathname === "/" ? "" : url.pathname}`;
+  const headers = new Headers(input.headers);
+  const marked = new Headers();
+  headers.forEach((value, name) => {
+    const n = name.toLowerCase();
+    if (n === "authorization") {
+      marked.set(`authorization${MARK_SUFFIX}`, value);
+      return;
+    }
+    if (n.startsWith("x-") && !n.startsWith("x-abz-")) {
+      marked.set(`${n}${MARK_SUFFIX}`, value);
+      return;
+    }
+    marked.set(n, value);
+  });
+  marked.set(ABZ_TARGET_HEADER, origin);
+  marked.set("x-api-key", cfg.token);
+  return new Request(newUrl.toString(), {
+    method: input.method,
+    headers: marked,
+    body: input.body,
+    redirect: "manual",
+    // @ts-expect-error duplex needed for streaming bodies on some runtimes
+    duplex: input.body ? "half" : void 0
+  });
+}
+function resolveConfig(opts) {
+  const token = opts?.token ?? process.env.APIBLAZE_TOKEN;
+  const tenant = opts?.tenant ?? process.env.APIBLAZE_TENANT;
+  if (!token || !tenant) {
+    if (!opts?.quiet) {
+      console.warn("[apiblaze/sidecar] APIBLAZE_TOKEN and APIBLAZE_TENANT are required \u2014 interceptor is OFF (fetches pass through unchanged).");
+    }
+    return null;
+  }
+  return { token, tenant, exclude: opts?.exclude ?? [], include: opts?.include ?? [] };
+}
+function register(opts) {
+  if (installed) return;
+  const cfg = resolveConfig(opts);
+  if (!cfg) return;
+  const original = globalThis.fetch;
+  if (typeof original !== "function") return;
+  const wrapped = async (input, init) => {
+    try {
+      const req = new Request(input, init);
+      const rewritten = await rewrite(cfg, req);
+      if (rewritten) return original(rewritten);
+    } catch (err) {
+      if (!opts?.quiet) console.warn("[apiblaze/sidecar] passthrough after interceptor error:", err?.message);
+    }
+    return original(input, init);
+  };
+  wrapped.__apiblaze = true;
+  globalThis.fetch = wrapped;
+  installed = true;
+  if (!opts?.quiet) console.log(`[apiblaze/sidecar] active \u2014 external fetches route through ${cfg.tenant}'s APIblaze plane.`);
+}
+function withApiblaze(nextConfig = {}) {
+  register();
+  const experimental = { ...nextConfig.experimental };
+  if (experimental.instrumentationHook === void 0) experimental.instrumentationHook = true;
+  return { ...nextConfig, experimental };
+}
+var sidecar_default = { register, withApiblaze };
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register,
+  withApiblaze
+});

package/dist/sidecar/index.mjs

@@ -0,0 +1,166 @@
+// src/sidecar/index.ts
+var ABZ_TARGET_HEADER = "x-abz-target";
+var MARK_SUFFIX = "-abz-target";
+var DATA_PLANE = "abz.run";
+var NOISE_DENYLIST = [
+  "google-analytics.com",
+  "googletagmanager.com",
+  "segment.io",
+  "segment.com",
+  "sentry.io",
+  "ingest.sentry.io",
+  "posthog.com",
+  "mixpanel.com",
+  "amplitude.com",
+  "datadoghq.com",
+  "newrelic.com",
+  "nr-data.net",
+  "honeycomb.io",
+  "launchdarkly.com",
+  "statsigapi.net",
+  "plausible.io",
+  "hotjar.com",
+  "fullstory.com",
+  "intercom.io",
+  "avatars.githubusercontent.com",
+  "gravatar.com",
+  "googleusercontent.com",
+  "cloudfront.net",
+  "akamaihd.net",
+  "fastly.net",
+  "imgix.net",
+  "cloudinary.com",
+  "unsplash.com",
+  "twimg.com",
+  "fbcdn.net",
+  "registry.npmjs.org",
+  "pypi.org",
+  "github.io"
+];
+var installed = false;
+function canonicalizeOrigin(input) {
+  try {
+    const u = new URL(input);
+    if (u.protocol !== "https:") return null;
+    const port = u.port && u.port !== "443" ? `:${u.port}` : "";
+    return `https://${u.hostname.toLowerCase()}${port}`;
+  } catch {
+    return null;
+  }
+}
+async function sha256Hex(s) {
+  const data = new TextEncoder().encode(s);
+  const buf = await globalThis.crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function sidecarHost(tenant, canonicalOrigin) {
+  const h = await sha256Hex(`${tenant}|${canonicalOrigin}`);
+  return `sc${h.slice(0, 16)}.${DATA_PLANE}`;
+}
+function hostMatchesGlob(host, glob) {
+  const g = glob.toLowerCase();
+  if (g.startsWith("*.")) {
+    const base = g.slice(2);
+    return host === base || host.endsWith(`.${base}`);
+  }
+  return host === g;
+}
+function isNoise(host) {
+  return NOISE_DENYLIST.some((d) => host === d || host.endsWith(`.${d}`));
+}
+function isPrivateOrLocal(host) {
+  if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return true;
+  if (/^127\./.test(host) || /^10\./.test(host) || /^192\.168\./.test(host)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return true;
+  if (/^169\.254\./.test(host)) return true;
+  return false;
+}
+function shouldIntercept(cfg, url) {
+  if (url.protocol !== "https:") return false;
+  const host = url.hostname.toLowerCase();
+  if (host.endsWith(DATA_PLANE) || host.endsWith("tryabz.run") || host.endsWith("apiblaze.com")) return false;
+  if (isPrivateOrLocal(host)) return false;
+  if (isNoise(host)) return false;
+  if (cfg.exclude.some((g) => hostMatchesGlob(host, g))) return false;
+  if (cfg.include.length > 0 && !cfg.include.some((g) => hostMatchesGlob(host, g))) return false;
+  return true;
+}
+async function rewrite(cfg, input) {
+  const url = new URL(input.url);
+  if (!shouldIntercept(cfg, url)) return null;
+  const origin = canonicalizeOrigin(url.origin);
+  if (!origin) return null;
+  const host = await sidecarHost(cfg.tenant, origin);
+  const newUrl = new URL(input.url);
+  newUrl.protocol = "https:";
+  newUrl.host = host;
+  newUrl.pathname = `/1.0.0/prod${url.pathname === "/" ? "" : url.pathname}`;
+  const headers = new Headers(input.headers);
+  const marked = new Headers();
+  headers.forEach((value, name) => {
+    const n = name.toLowerCase();
+    if (n === "authorization") {
+      marked.set(`authorization${MARK_SUFFIX}`, value);
+      return;
+    }
+    if (n.startsWith("x-") && !n.startsWith("x-abz-")) {
+      marked.set(`${n}${MARK_SUFFIX}`, value);
+      return;
+    }
+    marked.set(n, value);
+  });
+  marked.set(ABZ_TARGET_HEADER, origin);
+  marked.set("x-api-key", cfg.token);
+  return new Request(newUrl.toString(), {
+    method: input.method,
+    headers: marked,
+    body: input.body,
+    redirect: "manual",
+    // @ts-expect-error duplex needed for streaming bodies on some runtimes
+    duplex: input.body ? "half" : void 0
+  });
+}
+function resolveConfig(opts) {
+  const token = opts?.token ?? process.env.APIBLAZE_TOKEN;
+  const tenant = opts?.tenant ?? process.env.APIBLAZE_TENANT;
+  if (!token || !tenant) {
+    if (!opts?.quiet) {
+      console.warn("[apiblaze/sidecar] APIBLAZE_TOKEN and APIBLAZE_TENANT are required \u2014 interceptor is OFF (fetches pass through unchanged).");
+    }
+    return null;
+  }
+  return { token, tenant, exclude: opts?.exclude ?? [], include: opts?.include ?? [] };
+}
+function register(opts) {
+  if (installed) return;
+  const cfg = resolveConfig(opts);
+  if (!cfg) return;
+  const original = globalThis.fetch;
+  if (typeof original !== "function") return;
+  const wrapped = async (input, init) => {
+    try {
+      const req = new Request(input, init);
+      const rewritten = await rewrite(cfg, req);
+      if (rewritten) return original(rewritten);
+    } catch (err) {
+      if (!opts?.quiet) console.warn("[apiblaze/sidecar] passthrough after interceptor error:", err?.message);
+    }
+    return original(input, init);
+  };
+  wrapped.__apiblaze = true;
+  globalThis.fetch = wrapped;
+  installed = true;
+  if (!opts?.quiet) console.log(`[apiblaze/sidecar] active \u2014 external fetches route through ${cfg.tenant}'s APIblaze plane.`);
+}
+function withApiblaze(nextConfig = {}) {
+  register();
+  const experimental = { ...nextConfig.experimental };
+  if (experimental.instrumentationHook === void 0) experimental.instrumentationHook = true;
+  return { ...nextConfig, experimental };
+}
+var sidecar_default = { register, withApiblaze };
+export {
+  sidecar_default as default,
+  register,
+  withApiblaze
+};

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "apiblaze",
-  "version": "0.4.13",
-  "description": "Dev tunnel CLI for APIblaze — route localhost projects through your APIblaze endpoints",
+  "version": "0.5.0",
+  "description": "APIblaze CLI + sidecar — manage API proxies, run dev tunnels, and route a Next.js app's egress through APIblaze with one command",
   "keywords": [
     "apiblaze",
     "dev-tunnel",
     "cloudflared",
     "api",
-    "proxy"
+    "proxy",
+    "sidecar",
+    "nextjs",
+    "egress"
   ],
   "license": "MIT",
   "author": "APIblaze",
@@ -15,6 +18,15 @@
     "apiblaze": "dist/index.js"
   },
   "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./sidecar": {
+      "types": "./dist/sidecar/index.d.ts",
+      "import": "./dist/sidecar/index.mjs",
+      "require": "./dist/sidecar/index.js",
+      "default": "./dist/sidecar/index.js"
+    }
+  },
   "files": [
     "dist/",
     "README.md"