feat(proxy): implement proxy socket auth flow

Author: ex3ndr

README.md

@@ -75,7 +75,7 @@ for await (const event of stream.events) {
 
 By default, data commands return markdown. Use `--json` to print raw JSON.
 
-- `login` - Log in interactively, or with `--token <token>` / `--token-stdin`.
+- `login` - Log in interactively, with `--token <token>` / `--token-stdin`, or via proxy with `--proxy <url|socket>`.
 - `status` - Show current authentication status.
 - `logout` - Log out and clear stored credentials.
 
@@ -120,12 +120,42 @@ By default, data commands return markdown. Use `--json` to print raw JSON.
 
 - `sync` - Export your Bee data to markdown files for AI agents. Options: `--output <dir>`, `--recent-days N`, `--only <facts|todos|daily|conversations>`.
 
-- `proxy` - Start a local HTTP proxy for the Bee API. Options: `--port N`.
+- `proxy` - Start a local Bee API proxy. Options: `--port N`, `--socket [path]`.
 
 - `ping` - Run a quick connectivity check. Use `--count N` to repeat.
 
 - `version` - Print the CLI version. Use `--json` for JSON output.
 
+## Proxy Authentication
+
+Use proxy auth when another trusted local process handles Bee API authentication and this CLI should send requests through it.
+
+### Configure Proxy Mode
+
+```bash
+# HTTP proxy
+bee login --proxy http://127.0.0.1:8787
+
+# Unix socket proxy
+bee login --proxy ~/.bee/proxy.sock
+```
+
+This saves proxy config to `~/.bee/proxy-{env}.json`. When proxy config exists, it takes precedence over stored token auth.
+
+### Start Local Proxy Server
+
+```bash
+# TCP listener (default auto-picks from 8787)
+bee proxy
+bee proxy --port 8787
+
+# Unix socket listener (default: ~/.bee/proxy.sock)
+bee proxy --socket
+bee proxy --socket /tmp/bee-proxy.sock
+```
+
+In socket mode, the CLI removes stale socket files before listening.
+
 ## Stream Events
 
 Use `bee stream` to receive server-sent events (SSE). You can filter events with

sources/client.proxy.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createProxyClient } from "@/client";
+
+type BunServer = ReturnType<typeof Bun.serve>;
+
+const activeServers: BunServer[] = [];
+const cleanupPaths: string[] = [];
+
+afterEach(() => {
+  for (const server of activeServers.splice(0, activeServers.length)) {
+    server.stop(true);
+  }
+  for (const path of cleanupPaths.splice(0, cleanupPaths.length)) {
+    rmSync(path, { recursive: true, force: true });
+  }
+});
+
+describe("proxy client", () => {
+  it("routes HTTP proxy requests through configured base URL", async () => {
+    let seenPath = "";
+    let seenAuthorization: string | null = null;
+
+    const upstream = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: (request) => {
+        const url = new URL(request.url);
+        seenPath = `${url.pathname}${url.search}`;
+        seenAuthorization = request.headers.get("authorization");
+        return Response.json({ ok: true });
+      },
+    });
+    activeServers.push(upstream);
+
+    const client = createProxyClient("prod", {
+      address: `http://127.0.0.1:${upstream.port}`,
+    });
+
+    const response = await client.fetch("/v1/me?x=1", { method: "GET" });
+    expect(response.ok).toBe(true);
+    expect(seenPath).toBe("/v1/me?x=1");
+    expect(seenAuthorization).toBeNull();
+  });
+
+  it("routes unix socket proxy requests with unix fetch option", async () => {
+    let seenPath = "";
+    const dir = mkdtempSync(join(tmpdir(), "bee-cli-proxy-client-"));
+    cleanupPaths.push(dir);
+    const socketPath = join(dir, "proxy.sock");
+
+    const upstream = Bun.serve({
+      unix: socketPath,
+      fetch: (request) => {
+        const url = new URL(request.url);
+        seenPath = url.pathname;
+        return Response.json({ ok: true });
+      },
+    });
+    activeServers.push(upstream);
+
+    const client = createProxyClient("prod", { address: socketPath });
+    const response = await client.fetch("/v1/me", { method: "GET" });
+
+    expect(response.ok).toBe(true);
+    expect(seenPath).toBe("/v1/me");
+    expect(client.isProxy).toBe(true);
+  });
+});

sources/client.ts

@@ -1,16 +1,25 @@
 import { getEnvironmentConfig, type Environment } from "@/environment";
+import type { ProxyConfig } from "@/secureStore";
+import {
+  expandHomePath,
+  isSocketPath,
+  normalizeProxyAddress,
+} from "@/utils/proxyAddress";
 
 type TlsOptions = {
   ca?: string | string[];
 };
 
 type FetchInit = RequestInit & {
   tls?: TlsOptions;
+  unix?: string;
 };
 
 export type DeveloperClient = {
   env: Environment;
   baseUrl: string;
+  isProxy: boolean;
+  proxyAddress?: string;
   fetch: (path: string, init?: FetchInit) => Promise<Response>;
 };
 
@@ -21,6 +30,7 @@ export function createDeveloperClient(env: Environment): DeveloperClient {
   return {
     env,
     baseUrl: config.apiUrl,
+    isProxy: false,
     fetch: (path, init) => {
       const url = new URL(path, config.apiUrl);
       const requestInit: FetchInit = init
@@ -30,3 +40,54 @@ export function createDeveloperClient(env: Environment): DeveloperClient {
     },
   };
 }
+
+export function createProxyClient(
+  env: Environment,
+  proxyConfig: ProxyConfig
+): DeveloperClient {
+  const address = normalizeProxyAddress(proxyConfig.address);
+  if (!address) {
+    throw new Error("Proxy address cannot be empty.");
+  }
+
+  if (isSocketPath(address)) {
+    const socketPath = expandHomePath(address);
+    const baseUrl = "http://localhost/";
+    return {
+      env,
+      baseUrl,
+      isProxy: true,
+      proxyAddress: address,
+      fetch: (path, init) => {
+        const url = new URL(path, baseUrl);
+        const requestInit: FetchInit = init ? { ...init, unix: socketPath } : { unix: socketPath };
+        return fetch(url, requestInit);
+      },
+    };
+  }
+
+  let baseUrl: string;
+  try {
+    const parsed = new URL(address);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error("Proxy URL must start with http:// or https://.");
+    }
+    baseUrl = parsed.toString();
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Invalid proxy address: ${error.message}`);
+    }
+    throw new Error("Invalid proxy address.");
+  }
+
+  return {
+    env,
+    baseUrl,
+    isProxy: true,
+    proxyAddress: address,
+    fetch: (path, init) => {
+      const url = new URL(path, baseUrl);
+      return fetch(url, init);
+    },
+  };
+}

sources/client/clientApi.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import type { CommandContext } from "@/commands/types";
+import { createProxyClient } from "@/client";
+import { requireClientToken, requestClientJson } from "./clientApi";
+
+type BunServer = ReturnType<typeof Bun.serve>;
+
+const activeServers: BunServer[] = [];
+
+afterEach(() => {
+  for (const server of activeServers.splice(0, activeServers.length)) {
+    server.stop(true);
+  }
+});
+
+describe("client API auth", () => {
+  it("skips token requirement in proxy mode", async () => {
+    const context: CommandContext = {
+      env: "prod",
+      client: createProxyClient("prod", { address: "http://127.0.0.1:8787" }),
+    };
+
+    await expect(requireClientToken(context)).resolves.toBeNull();
+  });
+
+  it("does not inject Authorization header in proxy mode requests", async () => {
+    let seenAuthorization: string | null = null;
+    const proxy = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch: (request) => {
+        seenAuthorization = request.headers.get("authorization");
+        return Response.json({ ok: true });
+      },
+    });
+    activeServers.push(proxy);
+
+    const context: CommandContext = {
+      env: "prod",
+      client: createProxyClient("prod", {
+        address: `http://127.0.0.1:${proxy.port}`,
+      }),
+    };
+
+    const data = await requestClientJson(context, "/v1/me", { method: "GET" });
+    expect(data).toEqual({ ok: true });
+    expect(seenAuthorization).toBeNull();
+  });
+});

sources/client/clientApi.ts

@@ -13,7 +13,11 @@ type JsonRequestInit = RequestInit & {
   json?: JsonValue;
 };
 
-export async function requireClientToken(context: CommandContext): Promise<string> {
+export async function requireClientToken(context: CommandContext): Promise<string | null> {
+  if (context.client.isProxy) {
+    return null;
+  }
+
   const token = await loadToken(context.env);
   if (!token) {
     throw new Error('Not logged in. Run "bee login" first.');
@@ -28,7 +32,9 @@ export async function requestClientJson(
 ): Promise<unknown> {
   const token = await requireClientToken(context);
   const headers = new Headers(init.headers);
-  headers.set("Authorization", `Bearer ${token}`);
+  if (token) {
+    headers.set("Authorization", `Bearer ${token}`);
+  }
 
   let body = init.body;
   if (init.json !== undefined) {

sources/client/clientMe.ts

@@ -15,7 +15,7 @@ const MAX_BACKOFF_MS = 30000;
 
 export async function fetchClientMe(
   context: CommandContext,
-  token: string
+  token?: string
 ): Promise<ClientUser> {
   const response = await fetchWithRetry(context, token);
 
@@ -44,18 +44,21 @@ export async function fetchClientMe(
 
 async function fetchWithRetry(
   context: CommandContext,
-  token: string
+  token?: string
 ): Promise<Response> {
   let lastError: Error | null = null;
   let lastErrorType: "network" | "server" | null = null;
 
   for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
     try {
+      const headers = new Headers();
+      if (token) {
+        headers.set("Authorization", `Bearer ${token}`);
+      }
+
       const response = await context.client.fetch("/v1/me", {
         method: "GET",
-        headers: {
-          Authorization: `Bearer ${token}`,
-        },
+        headers,
       });
 
       if (response.status >= 500 && response.status < 600) {