Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

23.8 KB
Raw Blame
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import assert from "node:assert/strict";
import http from "node:http";
import test from "node:test";

import {
  ConnectionConfig,
  DefaultAdapterFactory,
  SandboxApiException,
} from "../dist/index.js";
import {
  FilesystemAdapter,
  IsolatedFilesystemAdapter,
  createExecdClient,
  createRedirectSafeFetch,
  hasProtectedHeaders,
  isSameOrigin,
  stripCredentialHeaders,
  stripProtectedHeaders,
  _resetClientIpCacheForTest,
  _setClientIpForTest,
} from "../dist/internal.js";

/** Start a throwaway HTTP server on an ephemeral 127.0.0.1 port. */
function startServer(handler) {
  return new Promise((resolve) => {
    const server = http.createServer(handler);
    server.listen(0, "127.0.0.1", () => {
      const { port } = server.address();
      resolve({
        server,
        origin: `http://127.0.0.1:${port}`,
        close: () =>
          new Promise((done) => {
            server.closeAllConnections?.();
            server.close(() => done());
          }),
      });
    });
  });
}

test("protected header helpers are case-insensitive and origin-aware", () => {
  const headers = new Headers({
    "Open-Sandbox-Api-Key": "secret",
    "opensandbox-egress-auth": "egress",
    "X-Custom": "keep",
  });
  assert.equal(hasProtectedHeaders(headers), true);
  stripProtectedHeaders(headers);
  assert.equal(headers.has("open-sandbox-api-key"), false);
  assert.equal(headers.has("opensandbox-egress-auth"), false);
  assert.equal(headers.get("x-custom"), "keep");
  assert.equal(hasProtectedHeaders(new Headers({ "X-Custom": "keep" })), false);

  const creds = new Headers({
    authorization: "Bearer t",
    cookie: "session=1",
    "proxy-authorization": "Basic p",
    "x-keep": "v",
  });
  stripCredentialHeaders(creds);
  assert.equal(creds.has("authorization"), false);
  assert.equal(creds.has("cookie"), false);
  assert.equal(creds.has("proxy-authorization"), false);
  assert.equal(creds.get("x-keep"), "v");

  assert.equal(isSameOrigin(new URL("https://a.test/x"), new URL("https://a.test:443/y")), true);
  assert.equal(isSameOrigin(new URL("http://a.test/x"), new URL("http://a.test:80/y")), true);
  assert.equal(isSameOrigin(new URL("https://a.test"), new URL("http://a.test")), false);
  assert.equal(isSameOrigin(new URL("https://a.test"), new URL("https://a.test:8443")), false);
});

test("cross-origin redirect strips protected headers but keeps other headers", async () => {
  let sourceHeaders;
  let targetHeaders;
  const target = await startServer((req, res) => {
    targetHeaders = req.headers;
    res.writeHead(200, { "content-type": "text/plain" });
    res.end("ok");
  });
  const source = await startServer((req, res) => {
    sourceHeaders = req.headers;
    res.writeHead(302, { location: `${target.origin}/final` });
    res.end();
  });

  try {
    const safeFetch = createRedirectSafeFetch(source.origin, fetch);
    const res = await safeFetch(`${source.origin}/start`, {
      headers: {
        "OPEN-SANDBOX-API-KEY": "tenant-secret",
        "OPENSANDBOX-EGRESS-AUTH": "egress-secret",
        "X-Custom": "keep-me",
      },
    });

    assert.equal(res.status, 200);
    // Credentials are still sent to the origin they were configured for.
    assert.equal(sourceHeaders["open-sandbox-api-key"], "tenant-secret");
    // ...but never replayed to the redirect target.
    assert.equal(targetHeaders["open-sandbox-api-key"], undefined);
    assert.equal(targetHeaders["opensandbox-egress-auth"], undefined);
    // Non-protected headers are untouched.
    assert.equal(targetHeaders["x-custom"], "keep-me");
  } finally {
    await source.close();
    await target.close();
  }
});

test("cross-origin redirect strips standard credential headers too", async () => {
  const calls = [];
  const baseFetch = async (input, init) => {
    const request = new Request(input, init);
    calls.push(Object.fromEntries(request.headers));
    if (calls.length === 1) {
      return new Response(null, { status: 302, headers: { location: "http://other.test/final" } });
    }
    return new Response("ok", { status: 200 });
  };
  const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch);

  await safeFetch("http://a.test/start", {
    headers: {
      "OPEN-SANDBOX-API-KEY": "tenant-secret",
      Authorization: "Bearer user-token",
      Cookie: "session=abc",
      "X-Custom": "keep-me",
    },
  });

  assert.equal(calls.length, 2);
  // The configured origin still receives everything.
  assert.equal(calls[0]["authorization"], "Bearer user-token");
  assert.equal(calls[0]["cookie"], "session=abc");
  // The cross-origin hop drops standard credentials (mirroring native fetch).
  assert.equal(calls[1]["authorization"], undefined);
  assert.equal(calls[1]["cookie"], undefined);
  assert.equal(calls[1]["open-sandbox-api-key"], undefined);
  // Non-credential headers survive.
  assert.equal(calls[1]["x-custom"], "keep-me");
});

test("307/308 redirects replay a Request body instead of surfacing the 3xx", async () => {
  const calls = [];
  const baseFetch = async (input, init) => {
    const request = new Request(input, init);
    calls.push({ url: request.url, method: request.method, body: await request.text() });
    if (calls.length === 1) {
      return new Response(null, { status: 308, headers: { location: "http://other.test/final" } });
    }
    return new Response("ok", { status: 200 });
  };
  const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch);

  // openapi-fetch passes a Request object carrying a JSON body.
  const payload = JSON.stringify({ name: "sandbox" });
  const request = new Request("http://a.test/start", {
    method: "POST",
    headers: { "content-type": "application/json", "OPEN-SANDBOX-API-KEY": "tenant-secret" },
    body: payload,
  });

  const res = await safeFetch(request);
  assert.equal(res.status, 200);
  assert.equal(calls.length, 2);
  assert.equal(calls[0].method, "POST");
  assert.equal(calls[1].method, "POST");
  assert.equal(calls[1].url, "http://other.test/final");
  assert.equal(calls[1].body, payload);
});

test("the request signal is carried across redirected hops", async () => {
  const controller = new AbortController();
  const signals = [];
  const baseFetch = async (input, init) => {
    const request = new Request(input, init);
    signals.push(request.signal);
    if (signals.length === 1) {
      return new Response(null, { status: 302, headers: { location: "http://other.test/final" } });
    }
    // Simulate a stalled target that only settles on abort.
    await Promise.race([
      new Promise((resolve) =>
        request.signal.addEventListener("abort", resolve, { once: true }),
      ),
      new Promise((resolve) => setTimeout(resolve, 2000)),
    ]);
    if (request.signal.aborted) throw request.signal.reason;
    return new Response("late", { status: 200 });
  };
  const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch);

  const request = new Request("http://a.test/start", {
    headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
    signal: controller.signal,
  });
  const promise = safeFetch(request);
  setTimeout(() => controller.abort(new Error("cancelled")), 10);

  await assert.rejects(promise, /cancelled/);
  assert.equal(signals.length, 2);
  assert.equal(signals[1].aborted, true);
});

test("Request-level fetch options survive the rebuild of every guarded hop", async () => {
  const inits = [];
  const baseFetch = async (input, init) => {
    inits.push(init);
    if (inits.length === 1) {
      return new Response(null, { status: 307, headers: { location: "http://other.test/final" } });
    }
    return new Response("ok", { status: 200 });
  };
  const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch);

  const request = new Request("http://a.test/start", {
    method: "POST",
    body: "payload",
    headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
    credentials: "include",
    cache: "no-store",
    referrerPolicy: "no-referrer",
  });

  const res = await safeFetch(request);
  assert.equal(res.status, 200);
  assert.equal(inits.length, 2);
  for (const init of inits) {
    // Options that only live on the Request input must be copied onto the
    // rebuilt (url, init) hop instead of falling back to platform defaults.
    assert.equal(init.credentials, "include");
    assert.equal(init.cache, "no-store");
    assert.equal(init.referrerPolicy, "no-referrer");
    // ...while the loop keeps ownership of the redirect mode.
    assert.equal(init.redirect, "manual");
  }
});

test("the overall redirect deadline bounds the first URL-input hop", async () => {
  const signals = [];
  const baseFetch = async (input, init) => {
    signals.push(init?.signal);
    await new Promise((resolve) => {
      init?.signal?.addEventListener("abort", resolve, { once: true });
      setTimeout(resolve, 1000);
    });
    if (init?.signal?.aborted) throw init.signal.reason;
    return new Response("late", { status: 200 });
  };
  const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch, {
    overallTimeoutMs: 20,
  });

  await assert.rejects(
    safeFetch("http://a.test/start", { headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" } }),
    /Redirect chain timed out/,
  );
  // A string/URL input used to take the header-less first hop without any
  // signal, so the overall deadline only started at the first redirect.
  assert.equal(signals.length, 1);
  assert.equal(signals[0].aborted, true);
});

test("a non-finite or negative overall deadline disables it", async () => {
  // ConnectionConfig treats requestTimeoutSeconds <= 0 or Infinity as "no
  // timeout"; the redirect guard must not turn that into an immediate abort.
  for (const overallTimeoutMs of [Infinity, -1000]) {
    const baseFetch = async (input, init) => {
      await new Promise((resolve) => setTimeout(resolve, 50));
      if (init?.signal?.aborted) throw init.signal.reason;
      return new Response("ok", { status: 200 });
    };
    const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch, { overallTimeoutMs });

    const res = await safeFetch("http://a.test/start", {
      headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
    });
    assert.equal(await res.text(), "ok", `overallTimeoutMs=${overallTimeoutMs}`);
  }
});

test("303 and POST 301/302 convert to GET and drop entity headers", async () => {
  const calls = [];
  const baseFetch = async (input, init) => {
    const request = new Request(input, init);
    calls.push({
      method: request.method,
      headers: Object.fromEntries(request.headers),
      body: await request.text(),
    });
    if (calls.length === 1) {
      return new Response(null, { status: 303, headers: { location: "http://other.test/final" } });
    }
    return new Response("ok", { status: 200 });
  };
  const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch);

  const request = new Request("http://a.test/start", {
    method: "POST",
    headers: { "content-type": "application/json", "OPEN-SANDBOX-API-KEY": "tenant-secret" },
    body: JSON.stringify({ a: 1 }),
  });

  const res = await safeFetch(request);
  assert.equal(res.status, 200);
  assert.equal(calls[1].method, "GET");
  assert.equal(calls[1].body, "");
  assert.equal(calls[1].headers["content-type"], undefined);
});

test("a Request carrying redirect: manual is not followed", async () => {
  const calls = [];
  const baseFetch = async (input, init) => {
    const request = new Request(input, init);
    calls.push(request.url);
    return new Response(null, { status: 302, headers: { location: "http://other.test/final" } });
  };
  const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch);

  const request = new Request("http://a.test/start", {
    method: "GET",
    headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
    redirect: "manual",
  });

  const res = await safeFetch(request);
  assert.equal(res.status, 302);
  // Only the original request was issued; the redirect was not chased.
  assert.equal(calls.length, 1);
});

test("non-HTTP(S) Location values are surfaced, not followed", async () => {
  const calls = [];
  const baseFetch = async (input, init) => {
    calls.push(new Request(input, init).url);
    return new Response(null, {
      status: 302,
      headers: { location: "data:application/json,%7B%7D" },
    });
  };
  const safeFetch = createRedirectSafeFetch("http://a.test", baseFetch);

  const res = await safeFetch("http://a.test/start", {
    headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
  });
  assert.equal(res.status, 302);
  assert.equal(calls.length, 1);
});

test("same-origin redirect preserves protected headers", async () => {
  let finalHeaders;
  const server = await startServer((req, res) => {
    if (req.url === "/start") {
      res.writeHead(302, { location: "/final" });
      res.end();
      return;
    }
    finalHeaders = req.headers;
    res.writeHead(200);
    res.end("ok");
  });

  try {
    const safeFetch = createRedirectSafeFetch(server.origin, fetch);
    const res = await safeFetch(`${server.origin}/start`, {
      headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
    });
    assert.equal(res.status, 200);
    assert.equal(finalHeaders["open-sandbox-api-key"], "tenant-secret");
  } finally {
    await server.close();
  }
});

test("requests without protected headers keep default follow behavior", async () => {
  let targetHeaders;
  const target = await startServer((req, res) => {
    targetHeaders = req.headers;
    res.writeHead(200);
    res.end("ok");
  });
  const source = await startServer((req, res) => {
    res.writeHead(302, { location: `${target.origin}/final` });
    res.end();
  });

  try {
    const safeFetch = createRedirectSafeFetch(source.origin, fetch);
    const res = await safeFetch(`${source.origin}/start`, {
      headers: { "X-Custom": "keep-me" },
    });
    assert.equal(res.status, 200);
    assert.equal(targetHeaders["x-custom"], "keep-me");
  } finally {
    await source.close();
    await target.close();
  }
});

test("an explicit redirect mode is never overridden", async () => {
  let targetHit = false;
  const target = await startServer((req, res) => {
    targetHit = true;
    res.writeHead(200);
    res.end();
  });
  const source = await startServer((req, res) => {
    res.writeHead(302, { location: `${target.origin}/final` });
    res.end();
  });

  try {
    const safeFetch = createRedirectSafeFetch(source.origin, fetch);
    const res = await safeFetch(`${source.origin}/start`, {
      headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
      redirect: "manual",
    });
    assert.equal(res.status, 302);
    assert.equal(targetHit, false);
  } finally {
    await source.close();
    await target.close();
  }
});

test("too many redirects fail instead of looping forever", async () => {
  const server = await startServer((req, res) => {
    res.writeHead(302, { location: "/loop" });
    res.end();
  });

  try {
    const safeFetch = createRedirectSafeFetch(server.origin, fetch, { maxRedirects: 2 });
    await assert.rejects(
      () =>
        safeFetch(`${server.origin}/loop`, {
          headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
        }),
      /Too many redirects/,
    );
  } finally {
    await server.close();
  }
});

test("opaque (browser) redirects fail closed instead of leaking credentials", async () => {
  // Browsers report `redirect: "manual"` as an opaque redirect: type
  // "opaqueredirect" with status 0. The status check must not short-circuit
  // before this is detected.
  const opaqueRedirect = { status: 0, type: "opaqueredirect", headers: new Headers() };
  const safeFetch = createRedirectSafeFetch("http://a.test", async () => opaqueRedirect);

  await assert.rejects(
    () =>
      safeFetch("http://a.test/start", {
        headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
      }),
    (err) => {
      assert.ok(err instanceof SandboxApiException);
      assert.match(err.message, /cannot be inspected/);
      return true;
    },
  );
});

test("a status-0 response without an inspectable target fails closed", async () => {
  const zeroStatus = { status: 0, type: "default", headers: new Headers() };
  const safeFetch = createRedirectSafeFetch("http://a.test", async () => zeroStatus);

  await assert.rejects(
    () =>
      safeFetch("http://a.test/start", {
        headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
      }),
    (err) => err instanceof SandboxApiException,
  );
});

test("requests without protected headers pass opaque responses through", async () => {
  // Disable the client-IP guard so nothing needs protection on this request.
  _resetClientIpCacheForTest();
  const opaqueRedirect = { status: 0, type: "opaqueredirect", headers: new Headers() };
  const safeFetch = createRedirectSafeFetch("http://a.test", async () => opaqueRedirect);

  const res = await safeFetch("http://a.test/start", { headers: { "X-Custom": "v" } });
  assert.equal(res, opaqueRedirect);
});

test("file uploads never follow redirects and surface the 3xx", async () => {
  let targetHit = false;
  const target = await startServer((req, res) => {
    targetHit = true;
    res.writeHead(200, { "content-type": "application/json" });
    res.end("{}");
  });
  const source = await startServer((req, res) => {
    res.writeHead(302, { location: `${target.origin}/files/upload` });
    res.end();
  });

  try {
    const opts = {
      baseUrl: source.origin,
      headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
      fetch,
    };
    const adapter = new FilesystemAdapter(createExecdClient(opts), opts);

    await assert.rejects(
      () => adapter.writeFiles([{ path: "/tmp/a.txt", data: "hello" }]),
      (err) => {
        assert.ok(err instanceof SandboxApiException);
        assert.equal(err.statusCode, 302);
        return true;
      },
    );
    assert.equal(targetHit, false);
  } finally {
    await source.close();
    await target.close();
  }
});

test("DefaultAdapterFactory strips protected headers on cross-origin data-plane redirects", async () => {
  let targetHeaders;
  const target = await startServer((req, res) => {
    targetHeaders = req.headers;
    res.writeHead(200, { "content-type": "text/plain" });
    res.end("ok");
  });
  const source = await startServer((req, res) => {
    res.writeHead(302, { location: `${target.origin}/ping` });
    res.end();
  });

  try {
    const connectionConfig = new ConnectionConfig({ domain: "unused.test" });
    connectionConfig._fetch = fetch;
    connectionConfig._sseFetch = fetch;

    const execd = new DefaultAdapterFactory().createExecdStack({
      connectionConfig,
      execdBaseUrl: source.origin,
      endpointHeaders: { "OPENSANDBOX-EGRESS-AUTH": "egress-secret" },
    });

    assert.equal(await execd.health.ping(), true);
    assert.equal(targetHeaders["opensandbox-egress-auth"], undefined);
  } finally {
    await source.close();
    await target.close();
  }
});

test("cross-origin hops drop the client-IP header added by the transport", async () => {
  let sourceHeaders;
  let targetHeaders;
  const target = await startServer((req, res) => {
    targetHeaders = req.headers;
    res.writeHead(200, { "content-type": "text/plain" });
    res.end("ok");
  });
  const source = await startServer((req, res) => {
    sourceHeaders = req.headers;
    res.writeHead(302, { location: `${target.origin}/ping` });
    res.end();
  });

  _setClientIpForTest("10.9.8.7");
  const connectionConfig = new ConnectionConfig({ domain: "unused.test" }).withTransportIfMissing();
  try {
    const execd = new DefaultAdapterFactory().createExecdStack({
      connectionConfig,
      execdBaseUrl: source.origin,
      endpointHeaders: { "OPENSANDBOX-EGRESS-AUTH": "egress-secret" },
    });

    assert.equal(await execd.health.ping(), true);
    // The configured origin still sees the SDK host's IP...
    assert.equal(sourceHeaders["open-sandbox-client-ip"], "10.9.8.7");
    // ...but the redirect target does not.
    assert.equal(targetHeaders["open-sandbox-client-ip"], undefined);
  } finally {
    await connectionConfig.closeTransport();
    _resetClientIpCacheForTest();
    await source.close();
    await target.close();
  }
});

test("guards a transport-injected client-IP without caller protected headers", async () => {
  let sourceHeaders;
  let targetHeaders;
  const target = await startServer((req, res) => {
    targetHeaders = req.headers;
    res.writeHead(200, { "content-type": "text/plain" });
    res.end("ok");
  });
  const source = await startServer((req, res) => {
    sourceHeaders = req.headers;
    res.writeHead(302, { location: `${target.origin}/ping` });
    res.end();
  });

  _setClientIpForTest("10.9.8.7");
  const connectionConfig = new ConnectionConfig({ domain: "unused.test" }).withTransportIfMissing();
  try {
    // No protected headers from the caller: only the transport-injected
    // client-IP makes this request need the guard.
    const execd = new DefaultAdapterFactory().createExecdStack({
      connectionConfig,
      execdBaseUrl: source.origin,
    });

    assert.equal(await execd.health.ping(), true);
    assert.equal(sourceHeaders["open-sandbox-client-ip"], "10.9.8.7");
    assert.equal(targetHeaders["open-sandbox-client-ip"], undefined);
  } finally {
    await connectionConfig.closeTransport();
    _resetClientIpCacheForTest();
    await source.close();
    await target.close();
  }
});

test("same-origin redirect chains keep the client-IP on every hop", async () => {
  const hops = [];
  const server = await startServer((req, res) => {
    hops.push({ url: req.url, clientIp: req.headers["open-sandbox-client-ip"] });
    if (req.url === "/ping") {
      res.writeHead(302, { location: "/ping2" });
      res.end();
      return;
    }
    if (req.url === "/ping2") {
      res.writeHead(302, { location: "/ping3" });
      res.end();
      return;
    }
    res.writeHead(200, { "content-type": "text/plain" });
    res.end("ok");
  });

  _setClientIpForTest("10.9.8.7");
  const connectionConfig = new ConnectionConfig({ domain: "unused.test" }).withTransportIfMissing();
  try {
    const execd = new DefaultAdapterFactory().createExecdStack({
      connectionConfig,
      execdBaseUrl: server.origin,
      endpointHeaders: { "OPENSANDBOX-EGRESS-AUTH": "egress-secret" },
    });

    assert.equal(await execd.health.ping(), true);
    assert.equal(hops.length, 3);
    for (const hop of hops) {
      assert.equal(hop.clientIp, "10.9.8.7");
    }
  } finally {
    await connectionConfig.closeTransport();
    _resetClientIpCacheForTest();
    await server.close();
  }
});

test("isolated file uploads never follow redirects and surface the 3xx", async () => {
  let targetHit = false;
  const target = await startServer((req, res) => {
    targetHit = true;
    res.writeHead(200, { "content-type": "application/json" });
    res.end("{}");
  });
  const source = await startServer((req, res) => {
    res.writeHead(302, {
      location: `${target.origin}/v1/isolated/session/s1/files/upload`,
    });
    res.end();
  });

  try {
    const opts = {
      baseUrl: source.origin,
      sessionId: "s1",
      headers: { "OPEN-SANDBOX-API-KEY": "tenant-secret" },
      fetch,
    };
    const adapter = new IsolatedFilesystemAdapter(createExecdClient(opts), opts);

    await assert.rejects(
      () => adapter.writeFiles([{ path: "/tmp/a.txt", data: "hello" }]),
      (err) => {
        assert.ok(err instanceof SandboxApiException);
        assert.equal(err.statusCode, 302);
        return true;
      },
    );
    assert.equal(targetHit, false);
  } finally {
    await source.close();
    await target.close();
  }
});