@utdk/isolate 0.1.0-dev.646adf4

package/__tests__/bridge.test.ts

@@ -0,0 +1,214 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  resolveAuthProvider,
+  resolveOperation,
+  extractAuthConfigs,
+  loadProviderClient,
+  createBridge,
+} from "../src/bridge.js";
+import type { UtdkAuthConfig } from "../src/types.js";
+
+// ---------------------------------------------------------------------------
+// resolveAuthProvider
+// ---------------------------------------------------------------------------
+
+describe("resolveAuthProvider", () => {
+  it("returns undefined when credentials are empty", () => {
+    const auth = resolveAuthProvider({});
+    expect(auth).toBeUndefined();
+  });
+
+  it("resolves BearerToken from api_key config with Bearer pattern", async () => {
+    const configs: UtdkAuthConfig[] = [
+      {
+        auth_type: "api_key",
+        api_key: "Bearer ${GITHUB_TOKEN}",
+        var_name: "Authorization",
+        location: "header",
+      } as unknown as UtdkAuthConfig,
+    ];
+    const auth = resolveAuthProvider({ GITHUB_TOKEN: "ghs_test123" }, configs);
+    expect(auth).toBeDefined();
+
+    const headers: Record<string, string> = {};
+    await auth!.authenticate(headers);
+    expect(headers["Authorization"]).toBe("Bearer ghs_test123");
+  });
+
+  it("resolves ApiKey from raw ${VAR_NAME} api_key pattern", async () => {
+    const configs: UtdkAuthConfig[] = [
+      {
+        auth_type: "api_key",
+        api_key: "${DD_API_KEY}",
+        var_name: "DD-API-Key",
+        location: "header",
+      } as unknown as UtdkAuthConfig,
+    ];
+    const auth = resolveAuthProvider({ DD_API_KEY: "dd_secret" }, configs);
+    expect(auth).toBeDefined();
+
+    const headers: Record<string, string> = {};
+    await auth!.authenticate(headers);
+    expect(headers["DD-API-Key"]).toBe("dd_secret");
+  });
+
+  it("resolves BearerToken from oauth2 ACCESS_TOKEN credential", async () => {
+    const configs: UtdkAuthConfig[] = [
+      { auth_type: "oauth2", flow: "authorization_code" },
+    ];
+    const auth = resolveAuthProvider(
+      { SPOTIFY_ACCESS_TOKEN: "eyJaccess" },
+      configs,
+    );
+    expect(auth).toBeDefined();
+
+    const headers: Record<string, string> = {};
+    await auth!.authenticate(headers);
+    expect(headers["Authorization"]).toBe("Bearer eyJaccess");
+  });
+
+  it("falls back to BearerToken with first credential when auth config is empty", async () => {
+    const auth = resolveAuthProvider({ SOME_TOKEN: "fallback-token" });
+    expect(auth).toBeDefined();
+
+    const headers: Record<string, string> = {};
+    await auth!.authenticate(headers);
+    expect(headers["Authorization"]).toBe("Bearer fallback-token");
+  });
+
+  it("credential value is never written to process.env", () => {
+    const originalEnv = { ...process.env };
+    resolveAuthProvider({ SECRET_KEY: "my-secret" });
+    // Verify process.env was not modified
+    expect(process.env).toEqual(originalEnv);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveOperation
+// ---------------------------------------------------------------------------
+
+describe("resolveOperation", () => {
+  it("resolves a simple top-level function", () => {
+    const fn = vi.fn();
+    const client = { getUser: fn };
+    const op = resolveOperation(client, "getUser");
+    expect(op).toBe(fn);
+  });
+
+  it("resolves a nested dot-notation path", () => {
+    const fn = vi.fn();
+    const client = { users: { getByUsername: fn } };
+    const op = resolveOperation(client, "users.getByUsername");
+    expect(op).toBe(fn);
+  });
+
+  it("resolves a deeply nested path", () => {
+    const fn = vi.fn();
+    const client = { a: { b: { c: fn } } };
+    const op = resolveOperation(client, "a.b.c");
+    expect(op).toBe(fn);
+  });
+
+  it("throws TypeError when intermediate segment is missing", () => {
+    const client = { users: {} };
+    expect(() => resolveOperation(client, "users.missing.fn")).toThrow(TypeError);
+  });
+
+  it("throws TypeError when operation is not a function", () => {
+    const client = { count: 42 };
+    expect(() => resolveOperation(client, "count")).toThrow(TypeError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractAuthConfigs
+// ---------------------------------------------------------------------------
+
+describe("extractAuthConfigs", () => {
+  it("returns empty array when module has no packageJson export", () => {
+    const mod: Record<string, unknown> = {};
+    expect(extractAuthConfigs(mod)).toEqual([]);
+  });
+
+  it("returns empty array when packageJson has no utdk field", () => {
+    const mod = { packageJson: { name: "@utdk/test" } };
+    expect(extractAuthConfigs(mod)).toEqual([]);
+  });
+
+  it("extracts auth array from packageJson.utdk.auth", () => {
+    const authConfig: UtdkAuthConfig[] = [
+      { auth_type: "api_key", api_key: "Bearer ${TOKEN}", var_name: "Authorization" },
+    ];
+    const mod = {
+      packageJson: {
+        name: "@utdk/test",
+        utdk: { auth: authConfig },
+      },
+    };
+    expect(extractAuthConfigs(mod)).toEqual(authConfig);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// loadProviderClient
+// ---------------------------------------------------------------------------
+
+describe("loadProviderClient", () => {
+  it("calls the create*Client factory with auth option", async () => {
+    const mockClient = { users: { getByUsername: vi.fn() } };
+    const createMockClient = vi.fn().mockResolvedValue(mockClient);
+    const mod = { createMockClient };
+
+    const auth = { authenticate: vi.fn() };
+    const result = await loadProviderClient(mod, auth);
+
+    expect(createMockClient).toHaveBeenCalledWith({ auth });
+    expect(result).toBe(mockClient);
+  });
+
+  it("calls the factory with empty options when no auth is provided", async () => {
+    const mockClient = {};
+    const createNoAuthClient = vi.fn().mockResolvedValue(mockClient);
+    const mod = { createNoAuthClient };
+
+    await loadProviderClient(mod, undefined);
+    expect(createNoAuthClient).toHaveBeenCalledWith({});
+  });
+
+  it("throws when no create*Client export is found", async () => {
+    const mod = { someOtherExport: "value" };
+    await expect(loadProviderClient(mod, undefined)).rejects.toThrow(
+      /does not export a create\*Client function/,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createBridge
+// ---------------------------------------------------------------------------
+
+describe("createBridge", () => {
+  it("returns an object with a call method", () => {
+    const op = vi.fn().mockResolvedValue({ id: 1 });
+    const bridge = createBridge({ operation: op });
+    expect(typeof bridge.call).toBe("function");
+  });
+
+  it("delegates call to the underlying operation", async () => {
+    const op = vi.fn().mockResolvedValue({ login: "octocat" });
+    const bridge = createBridge({ operation: op });
+
+    const result = await bridge.call({ username: "octocat" });
+
+    expect(op).toHaveBeenCalledWith({ username: "octocat" });
+    expect(result).toEqual({ login: "octocat" });
+  });
+
+  it("propagates errors from the operation", async () => {
+    const op = vi.fn().mockRejectedValue(new Error("API error"));
+    const bridge = createBridge({ operation: op });
+
+    await expect(bridge.call({})).rejects.toThrow("API error");
+  });
+});

package/__tests__/isolate.test.ts

@@ -0,0 +1,275 @@
+/**
+ * Integration tests for the Isolate runtime.
+ *
+ * These tests exercise the full execute() path using mock provider modules.
+ * Real network calls are avoided — all provider operations are vi.fn() mocks.
+ *
+ * Provider simulation:
+ *   - `@utdk/github`  → Bearer token auth, users.getByUsername operation
+ *   - `@utdk/spotify` → OAuth2 pre-resolved token, tracks.search operation
+ */
+
+import vm from "node:vm";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createBridge, resolveAuthProvider } from "../src/bridge.js";
+import { IsolateTimeoutError } from "../src/index.js";
+import { createSandboxContext } from "../src/sandbox.js";
+import type { UtdkAuthConfig } from "../src/types.js";
+
+// Reusable sandbox script (same one the Isolate uses internally)
+const SANDBOX_SCRIPT = new vm.Script("__bridge__.call(__args__)");
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Sandbox execution via bridge
+// ---------------------------------------------------------------------------
+
+describe("sandbox script invokes bridge.call", () => {
+  it("passes args to the operation and returns the result", async () => {
+    const operationFn = vi.fn().mockResolvedValue({ id: "track-123", name: "Bohemian Rhapsody" });
+    const bridge = createBridge({ operation: operationFn });
+    const args = { q: "Bohemian Rhapsody", limit: 1 };
+
+    const context = createSandboxContext({
+      extraGlobals: { __bridge__: bridge, __args__: args },
+    });
+
+    const result = await (SANDBOX_SCRIPT.runInContext(context) as Promise<unknown>);
+
+    expect(operationFn).toHaveBeenCalledWith(args);
+    expect(result).toEqual({ id: "track-123", name: "Bohemian Rhapsody" });
+  });
+
+  it("propagates errors thrown by the bridge", async () => {
+    const operationFn = vi.fn().mockRejectedValue(new Error("API error 429"));
+    const bridge = createBridge({ operation: operationFn });
+
+    const context = createSandboxContext({
+      extraGlobals: { __bridge__: bridge, __args__: {} },
+    });
+
+    await expect(SANDBOX_SCRIPT.runInContext(context) as Promise<unknown>).rejects.toThrow("API error 429");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Sandbox isolation
+// ---------------------------------------------------------------------------
+
+describe("sandbox isolation", () => {
+  it("process is not accessible inside the sandbox", () => {
+    const ctx = createSandboxContext();
+    const result = vm.runInContext("typeof process", ctx);
+    expect(result).toBe("undefined");
+  });
+
+  it("process.env is not accessible inside the sandbox", () => {
+    const ctx = createSandboxContext();
+    const result = vm.runInContext(
+      "try { typeof process.env } catch (e) { 'threw' }",
+      ctx,
+    );
+    expect(["threw", "undefined"]).toContain(result);
+  });
+
+  it("require is not accessible inside the sandbox", () => {
+    const ctx = createSandboxContext();
+    expect(vm.runInContext("typeof require", ctx)).toBe("undefined");
+  });
+
+  it("global is not accessible inside the sandbox", () => {
+    const ctx = createSandboxContext();
+    expect(vm.runInContext("typeof global", ctx)).toBe("undefined");
+  });
+
+  it("credentials are NOT injected as standalone sandbox globals", () => {
+    // Credentials must only flow through the bridge, never as top-level globals.
+    const ctx = createSandboxContext({
+      extraGlobals: {
+        __bridge__: { call: vi.fn().mockResolvedValue({}) },
+        __args__: {},
+        // GITHUB_TOKEN intentionally NOT added
+      },
+    });
+    expect(vm.runInContext("typeof GITHUB_TOKEN", ctx)).toBe("undefined");
+    expect(vm.runInContext("typeof SPOTIFY_ACCESS_TOKEN", ctx)).toBe("undefined");
+  });
+
+  it("state from one execution context does not leak to the next", () => {
+    const ctx1 = createSandboxContext();
+    const ctx2 = createSandboxContext();
+
+    vm.runInContext("var leakyVar = 'should-not-escape'", ctx1);
+
+    expect(vm.runInContext("typeof leakyVar", ctx2)).toBe("undefined");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Timeout enforcement
+// ---------------------------------------------------------------------------
+
+describe("timeout enforcement", () => {
+  it("rejects with TimeoutError when execution stalls", async () => {
+    const neverResolves = new Promise<never>(() => { /* stalled */ });
+    const bridge = { call: vi.fn().mockReturnValue(neverResolves) };
+
+    const ctx = createSandboxContext({
+      extraGlobals: { __bridge__: bridge, __args__: {} },
+    });
+
+    const resultPromise = SANDBOX_SCRIPT.runInContext(ctx) as Promise<unknown>;
+    const timeoutMs = 50;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => reject(new IsolateTimeoutError(timeoutMs)), timeoutMs);
+    });
+
+    await expect(Promise.race([resultPromise, timeoutPromise])).rejects.toMatchObject({
+      name: "TimeoutError",
+    });
+  }, 1_000);
+
+  it("TimeoutError message includes the configured timeout value", () => {
+    const err = new IsolateTimeoutError(5_000);
+    expect(err.message).toContain("5000ms");
+    expect(err.name).toBe("TimeoutError");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Credential injection — github simulation
+// ---------------------------------------------------------------------------
+
+describe("credential injection — github provider simulation", () => {
+  it("bearer token is injected via auth provider, NOT process.env", async () => {
+    const authConfigs: UtdkAuthConfig[] = [
+      {
+        auth_type: "api_key",
+        api_key: "Bearer ${GITHUB_TOKEN}",
+        var_name: "Authorization",
+      },
+    ];
+    const credentials = { GITHUB_TOKEN: "ghs_injected_by_gateway" };
+    const auth = resolveAuthProvider(credentials, authConfigs);
+
+    const headers: Record<string, string> = {};
+    await auth!.authenticate(headers);
+
+    expect(headers["Authorization"]).toBe("Bearer ghs_injected_by_gateway");
+    // process.env must NOT have been touched
+    expect(process.env["GITHUB_TOKEN"]).toBeUndefined();
+  });
+
+  it("executes github-like operation via sandbox bridge", async () => {
+    const mockUser = { login: "octocat", id: 1, type: "User" };
+    const getUserFn = vi.fn().mockResolvedValue(mockUser);
+
+    // Simulate how the client would be structured after createGithubClient()
+    const bridge = createBridge({
+      operation: (args) => getUserFn(args),
+    });
+
+    const context = createSandboxContext({
+      extraGlobals: { __bridge__: bridge, __args__: { username: "octocat" } },
+    });
+
+    const result = await (SANDBOX_SCRIPT.runInContext(context) as Promise<unknown>);
+
+    expect(getUserFn).toHaveBeenCalledWith({ username: "octocat" });
+    expect(result).toEqual(mockUser);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Credential injection — spotify simulation
+// ---------------------------------------------------------------------------
+
+describe("credential injection — spotify provider simulation", () => {
+  it("pre-resolved OAuth2 token is injected as BearerToken, NOT via process.env", async () => {
+    const authConfigs: UtdkAuthConfig[] = [
+      { auth_type: "oauth2", flow: "authorization_code" },
+    ];
+    // Gateway pre-resolves the OAuth2 exchange and provides the access token directly
+    const credentials = { SPOTIFY_ACCESS_TOKEN: "eyJspotify_access_token" };
+    const auth = resolveAuthProvider(credentials, authConfigs);
+
+    const headers: Record<string, string> = {};
+    await auth!.authenticate(headers);
+
+    expect(headers["Authorization"]).toBe("Bearer eyJspotify_access_token");
+    expect(process.env["SPOTIFY_ACCESS_TOKEN"]).toBeUndefined();
+    expect(process.env["SPOTIFY_CLIENT_SECRET"]).toBeUndefined();
+  });
+
+  it("executes spotify-like search operation via sandbox bridge", async () => {
+    const mockTracks = {
+      tracks: { items: [{ name: "Bohemian Rhapsody", id: "abc" }] },
+    };
+    const searchFn = vi.fn().mockResolvedValue(mockTracks);
+    const bridge = createBridge({ operation: searchFn });
+
+    const context = createSandboxContext({
+      extraGlobals: {
+        __bridge__: bridge,
+        __args__: { q: "Bohemian Rhapsody", type: "track", limit: 1 },
+      },
+    });
+
+    const result = await (SANDBOX_SCRIPT.runInContext(context) as Promise<unknown>);
+
+    expect(searchFn).toHaveBeenCalledWith({
+      q: "Bohemian Rhapsody",
+      type: "track",
+      limit: 1,
+    });
+    expect(result).toEqual(mockTracks);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Performance overhead measurement
+// ---------------------------------------------------------------------------
+
+describe("performance overhead", () => {
+  it("sandbox overhead is within acceptable bounds (<200ms for trivial calls)", async () => {
+    const operationFn = vi.fn().mockResolvedValue({ ok: true });
+    const bridge = createBridge({ operation: operationFn });
+    const args = { test: true };
+
+    const ITERATIONS = 5;
+    const sandboxDurations: number[] = [];
+    const directDurations: number[] = [];
+
+    for (let i = 0; i < ITERATIONS; i++) {
+      // Sandbox path
+      const ctx = createSandboxContext({
+        extraGlobals: { __bridge__: bridge, __args__: args },
+      });
+      const sandboxStart = performance.now();
+      await (SANDBOX_SCRIPT.runInContext(ctx) as Promise<unknown>);
+      sandboxDurations.push(performance.now() - sandboxStart);
+
+      // Direct call baseline
+      const directStart = performance.now();
+      await operationFn(args);
+      directDurations.push(performance.now() - directStart);
+    }
+
+    const avgSandbox = sandboxDurations.reduce((a, b) => a + b, 0) / ITERATIONS;
+    const avgDirect = directDurations.reduce((a, b) => a + b, 0) / ITERATIONS;
+    const overhead = avgSandbox - avgDirect;
+
+    console.log(
+      `[perf] avg sandbox: ${avgSandbox.toFixed(2)}ms, ` +
+      `avg direct: ${avgDirect.toFixed(2)}ms, ` +
+      `overhead: ${overhead.toFixed(2)}ms`,
+    );
+
+    // Context creation + vm.Script execution overhead should be well under 200ms
+    expect(avgSandbox).toBeLessThan(200);
+  });
+});

package/__tests__/sandbox.test.ts

@@ -0,0 +1,126 @@
+import vm from "node:vm";
+import { describe, it, expect } from "vitest";
+import { createSandboxContext } from "../src/sandbox.js";
+
+describe("createSandboxContext", () => {
+  it("creates a valid vm context", () => {
+    const ctx = createSandboxContext();
+    expect(vm.isContext(ctx)).toBe(true);
+  });
+
+  describe("isolation — blocked host APIs", () => {
+    it("does not expose process", () => {
+      const ctx = createSandboxContext();
+      const result = vm.runInContext("typeof process", ctx);
+      expect(result).toBe("undefined");
+    });
+
+    it("does not expose process.env (guard against prototype chain leakage)", () => {
+      const ctx = createSandboxContext();
+      // If `process` is undefined, accessing .env should throw or be undefined
+      const result = vm.runInContext(
+        "try { typeof process.env } catch (e) { 'threw' }",
+        ctx,
+      );
+      // Either 'threw' (TypeError: Cannot read properties of undefined) or 'undefined'
+      expect(["threw", "undefined"]).toContain(result);
+    });
+
+    it("does not expose require", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("typeof require", ctx)).toBe("undefined");
+    });
+
+    it("does not expose global", () => {
+      const ctx = createSandboxContext();
+      // `global` is Node.js-specific; not in context
+      expect(vm.runInContext("typeof global", ctx)).toBe("undefined");
+    });
+
+    it("does not expose Buffer", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("typeof Buffer", ctx)).toBe("undefined");
+    });
+
+    it("does not expose __dirname", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("typeof __dirname", ctx)).toBe("undefined");
+    });
+
+    it("does not expose __filename", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("typeof __filename", ctx)).toBe("undefined");
+    });
+  });
+
+  describe("safe globals — accessible inside sandbox", () => {
+    it("exposes JSON", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("JSON.stringify({ a: 1 })", ctx)).toBe('{"a":1}');
+    });
+
+    it("exposes Math", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("Math.max(2, 3)", ctx)).toBe(3);
+    });
+
+    it("exposes Date", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("typeof new Date()", ctx)).toBe("object");
+    });
+
+    it("exposes URL", () => {
+      const ctx = createSandboxContext();
+      const href = vm.runInContext('new URL("https://example.com").href', ctx);
+      expect(href).toBe("https://example.com/");
+    });
+
+    it("exposes Promise", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("typeof Promise.resolve", ctx)).toBe("function");
+    });
+
+    it("exposes setTimeout", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("typeof setTimeout", ctx)).toBe("function");
+    });
+
+    it("exposes TextEncoder / TextDecoder", () => {
+      const ctx = createSandboxContext();
+      expect(vm.runInContext("typeof TextEncoder", ctx)).toBe("function");
+      expect(vm.runInContext("typeof TextDecoder", ctx)).toBe("function");
+    });
+  });
+
+  describe("extraGlobals", () => {
+    it("injects arbitrary globals into the context", () => {
+      const ctx = createSandboxContext({
+        extraGlobals: { __answer__: 42 },
+      });
+      expect(vm.runInContext("__answer__", ctx)).toBe(42);
+    });
+
+    it("injected bridge object is callable from the sandbox", () => {
+      const bridge = { call: (args: unknown) => ({ echo: args }) };
+      const ctx = createSandboxContext({
+        extraGlobals: {
+          __bridge__: bridge,
+          __args__: { x: 1 },
+        },
+      });
+      const result = vm.runInContext("__bridge__.call(__args__)", ctx) as { echo: unknown };
+      expect(result.echo).toEqual({ x: 1 });
+    });
+  });
+
+  describe("context isolation between calls", () => {
+    it("state written in one context does not leak to another", () => {
+      const ctx1 = createSandboxContext();
+      const ctx2 = createSandboxContext();
+
+      vm.runInContext("var secret = 'ctx1-secret'", ctx1);
+
+      expect(vm.runInContext("typeof secret", ctx2)).toBe("undefined");
+    });
+  });
+});

package/dist/__tests__/bridge.test.d.ts

@@ -0,0 +1 @@
+export {};