feat(client): add fetchWithAuth for same-origin server routes

Full-stack apps serve their own server routes next to the frontend, and
those routes read the caller's identity from the Authorization header. The
access token lives in local storage and is attached to the SDK's own
clients, so a plain fetch("/api/orders") reaches the route anonymous — apps
work around it by reading the token and building the header by hand.

fetchWithAuth() is that fetch with the header already on it. It resolves the
path against the page and refuses anything landing on another origin, so an
absolute URL, a protocol-relative path or a backslash-prefixed one cannot
carry the token off-site. The token comes from the user axios client's
Authorization default, which follows setToken() and is cleared by logout(),
so a request never carries a token the user no longer has.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014tTNp16fczTqi3KQ7mGEKS

Author: netanelgilad

src/client.ts

@@ -8,6 +8,7 @@ import {
   createUserConnectorsModule,
 } from "./modules/connectors.js";
 import { getAccessToken } from "./utils/auth-utils.js";
+import { createFetchWithAuth } from "./utils/fetch-with-auth.js";
 import { createFunctionsModule } from "./modules/functions.js";
 import { createAgentsModule } from "./modules/agents.js";
 import { createAiGatewayModule } from "./modules/ai-gateway.js";
@@ -323,6 +324,9 @@ export function createClient(config: CreateClientConfig): Base44Client {
   const client = {
     ...userModules,
 
+    /** See {@link Base44Client.fetchWithAuth}. */
+    fetchWithAuth: createFetchWithAuth(axiosClient),
+
     /**
      * Sets a new authentication token for all subsequent requests.
      *

src/client.types.ts

@@ -147,6 +147,45 @@ export interface Base44Client {
   /** Cleanup function to disconnect WebSocket connections. Call when you're done with the client. */
   cleanup: () => void;
 
+  /**
+   * Calls one of your app's own server routes with the signed-in user's access token attached.
+   *
+   * Base44 keeps the user's access token in the browser's local storage, so a plain `fetch()` to your app's server routes arrives without it and the route sees an anonymous caller. `fetchWithAuth()` is the same `fetch()` with the `Authorization: Bearer <token>` header added, which is what lets a server route act on behalf of the signed-in user.
+   *
+   * Requests are restricted to your app's own origin so the token is never sent to a third party: pass a path such as `/api/orders`, not a full URL. An absolute URL, a protocol-relative path, or anything else that resolves to another origin throws. To call a Base44 backend function, use {@linkcode FunctionsModule.fetch | functions.fetch()}; for another origin, use plain `fetch()`.
+   *
+   * When no user is signed in the request is sent without an `Authorization` header, so routes that allow anonymous access keep working.
+   *
+   * This method is browser-only. In server code, read the caller's token from the incoming request instead.
+   *
+   * @param path - A path on your app's own origin, such as `/api/orders`.
+   * @param init - Optional [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) options such as `method`, `headers`, `body`, and `signal`. The auth header is added automatically; an `Authorization` header you set yourself is kept.
+   * @returns Promise resolving to a native [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
+   * @throws {Error} When `path` resolves to a different origin, or when called outside the browser.
+   *
+   * @example
+   * ```typescript
+   * // Call your app's own server route as the signed-in user
+   * const response = await base44.fetchWithAuth('/api/orders');
+   * const orders = await response.json();
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // POST with a JSON body
+   * const response = await base44.fetchWithAuth('/api/orders', {
+   *   method: 'POST',
+   *   headers: { 'Content-Type': 'application/json' },
+   *   body: JSON.stringify({ productId: 'abc', quantity: 2 }),
+   * });
+   *
+   * if (!response.ok) {
+   *   throw new Error(`Request failed: ${response.status}`);
+   * }
+   * ```
+   */
+  fetchWithAuth(path: string, init?: RequestInit): Promise<Response>;
+
   /**
    * Sets a new authentication token for all subsequent requests.
    *

src/utils/fetch-with-auth.ts

@@ -0,0 +1,68 @@
+import type { AxiosInstance } from "axios";
+
+/**
+ * Builds the client's `fetchWithAuth`: a `fetch` that attaches the signed-in
+ * user's access token, restricted to the app's own origin.
+ *
+ * @param axios - The user-scoped axios instance. Its `Authorization` default is
+ * the live token: it follows `setToken()` and is deleted on `logout()`, so a
+ * request never carries a token the user no longer has.
+ * @internal
+ */
+export function createFetchWithAuth(axios: AxiosInstance) {
+  const currentToken = (): string | null => {
+    const header = axios.defaults.headers.common["Authorization"];
+    if (typeof header !== "string" || !header.startsWith("Bearer ")) {
+      return null;
+    }
+    return header.slice("Bearer ".length) || null;
+  };
+
+  return async function fetchWithAuth(
+    path: string,
+    init: RequestInit = {}
+  ): Promise<Response> {
+    const url = resolveSameOriginUrl(path);
+    const headers = new Headers(init.headers);
+    const token = currentToken();
+
+    if (token && !headers.has("Authorization")) {
+      headers.set("Authorization", `Bearer ${token}`);
+    }
+
+    return fetch(url, { ...init, headers });
+  };
+}
+
+function resolveSameOriginUrl(path: string): string {
+  if (typeof path !== "string" || path === "") {
+    throw new Error("fetchWithAuth() requires a path, such as '/api/orders'.");
+  }
+
+  const location = typeof window !== "undefined" ? window.location : undefined;
+  if (!location?.href) {
+    throw new Error(
+      "fetchWithAuth() is only available in the browser. In server code, read the caller's token from the request instead — see createClientFromRequest()."
+    );
+  }
+
+  let pageUrl: URL;
+  let resolved: URL;
+  try {
+    pageUrl = new URL(location.href);
+    resolved = new URL(path, pageUrl);
+  } catch {
+    throw new Error(`fetchWithAuth() received an invalid path: "${path}".`);
+  }
+
+  // Resolving before comparing is what makes this safe: a protocol-relative
+  // path ("//evil.example"), a backslash ("/\\evil.example") and an absolute URL
+  // all land on another origin here, and are rejected the same way.
+  if (resolved.origin !== pageUrl.origin) {
+    throw new Error(
+      `fetchWithAuth() only sends requests to your app's own origin, so the access token never reaches a third party. "${path}" resolves to ${resolved.origin}. Use base44.functions.fetch() to call a Base44 backend function, or plain fetch() for another origin.`
+    );
+  }
+
+  return resolved.toString();
+}

tests/unit/fetch-with-auth.test.ts

@@ -0,0 +1,176 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { createClient } from "../../src/index.ts";
+
+const appId = "test-app-id";
+const origin = "https://my-app.base44.app";
+
+function makeLocalStorage(initial: Record<string, string> = {}) {
+  const store = new Map<string, string>(Object.entries(initial));
+  return {
+    getItem: (k: string) => (store.has(k) ? store.get(k)! : null),
+    setItem: (k: string, v: string) => {
+      store.set(k, v);
+    },
+    removeItem: (k: string) => {
+      store.delete(k);
+    },
+    clear: () => store.clear(),
+  };
+}
+
+function stubBrowser(storage = makeLocalStorage()) {
+  vi.stubGlobal("document", { referrer: "", visibilityState: "visible" });
+  vi.stubGlobal("window", {
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    history: { replaceState: vi.fn() },
+    location: {
+      href: `${origin}/dashboard`,
+      origin,
+      pathname: "/dashboard",
+      search: "",
+    },
+    localStorage: storage,
+  });
+  vi.stubGlobal("localStorage", storage);
+}
+
+const createTestClient = (token?: string) =>
+  createClient({
+    serverUrl: "",
+    appId,
+    token,
+    analytics: { enabled: false },
+  });
+
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  fetchMock = vi.fn().mockResolvedValue(new Response("{}"));
+  vi.stubGlobal("fetch", fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.clearAllMocks();
+});
+
+const lastCall = () => {
+  const [url, init] = fetchMock.mock.calls[0];
+  return { url, init, headers: new Headers(init.headers) };
+};
+
+describe("fetchWithAuth", () => {
+  test("attaches the user's token to a same-origin path", async () => {
+    stubBrowser();
+    const base44 = createTestClient("user-token");
+
+    await base44.fetchWithAuth("/api/orders");
+
+    const { url, headers } = lastCall();
+    expect(url).toBe(`${origin}/api/orders`);
+    expect(headers.get("Authorization")).toBe("Bearer user-token");
+  });
+
+  test("reads the token from local storage when the client was created without one", async () => {
+    stubBrowser(makeLocalStorage({ base44_access_token: "stored-token" }));
+    const base44 = createTestClient();
+
+    await base44.fetchWithAuth("/api/orders");
+
+    expect(lastCall().headers.get("Authorization")).toBe("Bearer stored-token");
+  });
+
+  test("uses the token set after login", async () => {
+    stubBrowser();
+    const base44 = createTestClient("old-token");
+
+    base44.setToken("new-token");
+    await base44.fetchWithAuth("/api/orders");
+
+    expect(lastCall().headers.get("Authorization")).toBe("Bearer new-token");
+  });
+
+  test("sends no auth header after logout", async () => {
+    stubBrowser();
+    const base44 = createTestClient("user-token");
+
+    base44.auth.logout();
+    // logout() navigates the page; the test keeps the stubbed location usable.
+    (globalThis as any).window.location.href = `${origin}/dashboard`;
+    await base44.fetchWithAuth("/api/orders");
+
+    expect(lastCall().headers.get("Authorization")).toBeNull();
+  });
+
+  test("sends no auth header when no user is signed in", async () => {
+    stubBrowser();
+    const base44 = createTestClient();
+
+    await base44.fetchWithAuth("/api/public");
+
+    expect(lastCall().headers.get("Authorization")).toBeNull();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("forwards init options and keeps a caller-set Authorization header", async () => {
+    stubBrowser();
+    const base44 = createTestClient("user-token");
+
+    await base44.fetchWithAuth("/api/orders", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: "Bearer caller-token",
+      },
+      body: JSON.stringify({ productId: "abc" }),
+    });
+
+    const { init, headers } = lastCall();
+    expect(init.method).toBe("POST");
+    expect(init.body).toBe(JSON.stringify({ productId: "abc" }));
+    expect(headers.get("Content-Type")).toBe("application/json");
+    expect(headers.get("Authorization")).toBe("Bearer caller-token");
+  });
+
+  test("resolves a path relative to the current page", async () => {
+    stubBrowser();
+    const base44 = createTestClient("user-token");
+
+    await base44.fetchWithAuth("api/orders");
+
+    expect(lastCall().url).toBe(`${origin}/api/orders`);
+  });
+
+  test.each([
+    ["an absolute URL", "https://evil.example/steal"],
+    ["a protocol-relative path", "//evil.example/steal"],
+    ["a backslash-prefixed path", "/\\evil.example/steal"],
+    ["an absolute URL on another port", `${origin}:8443/api/orders`],
+  ])("rejects %s", async (_label, path) => {
+    stubBrowser();
+    const base44 = createTestClient("user-token");
+
+    await expect(base44.fetchWithAuth(path)).rejects.toThrow(
+      /only sends requests to your app's own origin/
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("rejects an empty path", async () => {
+    stubBrowser();
+    const base44 = createTestClient("user-token");
+
+    await expect(base44.fetchWithAuth("")).rejects.toThrow(/requires a path/);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  test("throws outside the browser", async () => {
+    const base44 = createTestClient("user-token");
+
+    await expect(base44.fetchWithAuth("/api/orders")).rejects.toThrow(
+      /only available in the browser/
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});