@nimbus-dev/sdk 1.1.2

package/src/testing/sandbox-contract.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  __defaultRunProbe,
+  type ProbeResult,
+  type ProbeRunner,
+  runSandboxContractTests,
+} from "./sandbox-contract.ts";
+
+function makeProbeRunner(
+  responses: ReadonlyArray<{ probe: string; arg?: string; result: ProbeResult }>,
+): { runner: ProbeRunner; calls: Array<{ probe: string; arg: string }> } {
+  const calls: Array<{ probe: string; arg: string }> = [];
+  const runner: ProbeRunner = (probe, arg) => {
+    calls.push({ probe, arg });
+    const match = responses.find(
+      (r) => r.probe === probe && (r.arg === undefined || r.arg === arg),
+    );
+    if (match === undefined) {
+      throw new Error(`unexpected probe call: ${probe} arg=${arg}`);
+    }
+    return match.result;
+  };
+  return { runner, calls };
+}
+
+function writeManifest(perms: unknown): string {
+  const dir = mkdtempSync(join(tmpdir(), "sdk-contract-stub-"));
+  const manifestPath = join(dir, "nimbus.extension.json");
+  writeFileSync(manifestPath, JSON.stringify({ id: "test", permissions: perms }));
+  return manifestPath;
+}
+
+describe("runSandboxContractTests", () => {
+  it("rejects when the manifest file does not exist", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sdk-contract-missing-"));
+    const manifestPath = join(dir, "missing.json");
+    await expect(runSandboxContractTests(manifestPath)).rejects.toThrow();
+  });
+
+  it("rejects when the manifest is not valid JSON", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sdk-contract-bad-"));
+    const manifestPath = join(dir, "nimbus.extension.json");
+    writeFileSync(manifestPath, "{not-json");
+    await expect(runSandboxContractTests(manifestPath)).rejects.toThrow();
+  });
+
+  it("handles a manifest with no declared network hosts without crashing", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "sdk-contract-empty-"));
+    const manifestPath = join(dir, "nimbus.extension.json");
+    writeFileSync(manifestPath, JSON.stringify({ id: "test.empty", permissions: {} }));
+    let outcome: "pass" | "fail" = "pass";
+    try {
+      await runSandboxContractTests(manifestPath);
+    } catch {
+      outcome = "fail";
+    }
+    if (process.platform === "win32") {
+      expect(outcome).toBe("pass");
+    } else {
+      expect(outcome).toBe("fail");
+    }
+  }, 30_000);
+
+  it("runs all three probes when manifest declares hosts (Linux/macOS)", async () => {
+    const manifestPath = writeManifest({ network: ["api.github.com"] });
+    const { runner, calls } = makeProbeRunner([
+      {
+        probe: "network-listed",
+        arg: "api.github.com",
+        result: { status: 0, stderr: "", stdout: "" },
+      },
+      { probe: "network-unlisted", arg: "", result: { status: 11, stderr: "", stdout: "" } },
+      { probe: "fs-denied", arg: "", result: { status: 10, stderr: "", stdout: "" } },
+    ]);
+    await runSandboxContractTests(manifestPath, { runProbe: runner, platform: "linux" });
+    expect(calls).toEqual([
+      { probe: "network-listed", arg: "api.github.com" },
+      { probe: "network-unlisted", arg: "" },
+      { probe: "fs-denied", arg: "" },
+    ]);
+  });
+
+  it("skips the network-unlisted probe on Windows", async () => {
+    const manifestPath = writeManifest({ network: ["api.github.com"] });
+    const { runner, calls } = makeProbeRunner([
+      { probe: "network-listed", result: { status: 0, stderr: "", stdout: "" } },
+      { probe: "fs-denied", result: { status: 10, stderr: "", stdout: "" } },
+    ]);
+    await runSandboxContractTests(manifestPath, { runProbe: runner, platform: "win32" });
+    expect(calls.map((c) => c.probe)).toEqual(["network-listed", "fs-denied"]);
+  });
+
+  it("throws when the listed-host probe exits non-zero", async () => {
+    const manifestPath = writeManifest({ network: ["api.github.com"] });
+    const { runner } = makeProbeRunner([
+      { probe: "network-listed", result: { status: 7, stderr: "connect refused", stdout: "" } },
+    ]);
+    await expect(
+      runSandboxContractTests(manifestPath, { runProbe: runner, platform: "linux" }),
+    ).rejects.toThrow(/network-listed probe failed for api\.github\.com.*exit 7.*connect refused/);
+  });
+
+  it("throws when the unlisted-host probe does NOT return exit 11", async () => {
+    const manifestPath = writeManifest({ network: ["api.github.com"] });
+    const { runner } = makeProbeRunner([
+      { probe: "network-listed", result: { status: 0, stderr: "", stdout: "" } },
+      {
+        probe: "network-unlisted",
+        result: { status: 2, stderr: "unexpected fetch success", stdout: "" },
+      },
+    ]);
+    await expect(
+      runSandboxContractTests(manifestPath, { runProbe: runner, platform: "linux" }),
+    ).rejects.toThrow(/network-unlisted probe should have failed.*exit 2.*platform-asymmetry/s);
+  });
+
+  it("throws when fs-denied probe does NOT return exit 10", async () => {
+    const manifestPath = writeManifest({});
+    const { runner } = makeProbeRunner([
+      { probe: "fs-denied", result: { status: 2, stderr: "unexpected file read", stdout: "" } },
+    ]);
+    await expect(
+      runSandboxContractTests(manifestPath, { runProbe: runner, platform: "linux" }),
+    ).rejects.toThrow(/fs-denied probe should have returned EACCES.*exit 2.*unexpected file read/s);
+  });
+
+  it("tolerates a manifest with `permissions: string[]` (legacy array form)", async () => {
+    const manifestPath = writeManifest(["read-files", "trash"]);
+    const { runner, calls } = makeProbeRunner([
+      { probe: "fs-denied", result: { status: 10, stderr: "", stdout: "" } },
+    ]);
+    await runSandboxContractTests(manifestPath, { runProbe: runner, platform: "linux" });
+    expect(calls).toEqual([{ probe: "fs-denied", arg: "" }]);
+  });
+
+  it("`__defaultRunProbe` returns a well-formed envelope on a probe that exits non-zero", () => {
+    const r = __defaultRunProbe("definitely-not-a-probe", "");
+    expect(typeof r.status).toBe("number");
+    expect(typeof r.stderr).toBe("string");
+    expect(typeof r.stdout).toBe("string");
+  }, 30_000);
+});

package/src/testing/sandbox-contract.ts

@@ -0,0 +1,155 @@
+/**
+ * `runSandboxContractTests` — verifies the declared sandbox permissions in a
+ * manifest match the runtime enforcement seen by a forked probe.
+ *
+ * Phase 5 T2 PR 1.
+ *
+ * Three probes run sequentially:
+ *
+ *   1. **network-listed** — for the first declared host in
+ *      `permissions.network`, a HEAD fetch must succeed (2xx–4xx).
+ *      Skipped if no hosts are declared.
+ *
+ *   2. **network-unlisted** — a fetch to `192.0.2.1` (TEST-NET-1, never
+ *      routable) must fail with ECONNREFUSED / EPERM / EHOSTUNREACH /
+ *      ENETUNREACH. Skipped on Windows because AppContainer network
+ *      filtering is host-allow + deny-by-default at a different layer — the
+ *      probe sees a generic socket failure that is indistinguishable from
+ *      the unsandboxed case. See `docs/sandbox.md#platform-asymmetry`.
+ *      Skipped on every platform if no hosts are declared (the
+ *      sandbox-runner would deny network entirely in that case, and the
+ *      probe's expectation collapses to "no network at all", which the
+ *      first probe doesn't exercise).
+ *
+ *   3. **fs-denied** — a read of a known-protected path
+ *      (`/etc/passwd` POSIX, `C:\Windows\System32\config\SAM` Windows)
+ *      must fail with EACCES / EPERM. This probe always runs.
+ *
+ * Each probe is invoked via `child_process.spawnSync(process.execPath, …)`
+ * directly. **The probe is *not* sandbox-wrapped by the SDK harness alone.**
+ * For the SDK to assert real enforcement, a wrapping helper (typically
+ * `packages/gateway/test/helpers/sandbox-harness.ts`) needs to fork
+ * `runSandboxContractTests` inside a process that is itself sandbox-wrapped,
+ * or substitute a sandboxed `execPath`.
+ *
+ * Used by:
+ *   - First-party connector contract tests via the gateway test harness.
+ *   - Third-party extension authors invoking
+ *     `import { runSandboxContractTests } from "@nimbus-dev/sdk/testing"`.
+ *
+ * When invoked **outside** a sandboxed harness on Linux/macOS, probes 2 and
+ * 3 will either succeed (return exit 2) — which the harness reports as a
+ * test failure — or fail with codes other than 10/11. Either way the harness
+ * throws. That's the third-party UX: "your contract test failed because the
+ * sandbox isn't enforcing the manifest", which is the correct signal even
+ * though the UX could be friendlier.
+ */
+
+import { spawnSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROBE_PATH = resolve(dirname(fileURLToPath(import.meta.url)), "sandbox-probe.ts");
+
+interface ManifestPermissions {
+  network?: string[];
+  filesystem?: { read?: string[]; write?: string[] };
+}
+
+interface Manifest {
+  id?: string;
+  permissions?: ManifestPermissions | unknown[];
+}
+
+export interface ProbeResult {
+  status: number;
+  stderr: string;
+  stdout: string;
+}
+
+/** Probe-runner shape — exposed for testability (see `__defaultRunProbe`). */
+export type ProbeRunner = (probe: string, arg: string) => ProbeResult;
+
+export interface RunSandboxContractTestsOptions {
+  /**
+   * Override the probe runner. Default is `__defaultRunProbe` (a
+   * `child_process.spawnSync` wrapper around the bundled probe binary).
+   * Tests inject a stub here; production callers leave this undefined.
+   */
+  runProbe?: ProbeRunner;
+  /**
+   * Override `process.platform` for testability of the Windows skip
+   * branch. Default is the live `process.platform`.
+   */
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Read the manifest at `manifestPath`, fork the probe binary for each
+ * declared capability + the FS-denied negative case, and throw if the
+ * observed enforcement does not match.
+ *
+ * Throws on first failure with a message that names the probe, the
+ * observed exit code, and the probe's stderr.
+ */
+export async function runSandboxContractTests(
+  manifestPath: string,
+  opts: RunSandboxContractTestsOptions = {},
+): Promise<void> {
+  const runProbe = opts.runProbe ?? __defaultRunProbe;
+  const platform = opts.platform ?? process.platform;
+
+  const raw = await readFile(manifestPath, "utf8");
+  const manifest = JSON.parse(raw) as Manifest;
+
+  const perms = manifest.permissions;
+  const objectForm = perms && typeof perms === "object" && !Array.isArray(perms) ? perms : null;
+  const hosts = objectForm?.network ?? [];
+
+  const firstHost = hosts[0];
+  if (firstHost !== undefined) {
+    const r = runProbe("network-listed", firstHost);
+    if (r.status !== 0) {
+      throw new Error(
+        `network-listed probe failed for ${firstHost}: exit ${r.status}; stderr: ${r.stderr.trim()}`,
+      );
+    }
+  }
+
+  if (platform !== "win32" && hosts.length > 0) {
+    const r = runProbe("network-unlisted", "");
+    if (r.status !== 11) {
+      throw new Error(
+        `network-unlisted probe should have failed with ECONNREFUSED/EPERM/EHOSTUNREACH/ENETUNREACH; ` +
+          `got exit ${r.status}; stderr: ${r.stderr.trim()}. ` +
+          `See docs/sandbox.md#platform-asymmetry.`,
+      );
+    }
+  }
+
+  const r3 = runProbe("fs-denied", "");
+  if (r3.status !== 10) {
+    throw new Error(
+      `fs-denied probe should have returned EACCES (exit 10); got exit ${r3.status}; ` +
+        `stderr: ${r3.stderr.trim()}.`,
+    );
+  }
+}
+
+/**
+ * Default probe runner — forks the bundled probe binary via
+ * `child_process.spawnSync`. Exported for direct use in test scaffolding
+ * that wants to assert the production wiring without re-implementing the
+ * `spawnSync` envelope.
+ */
+export function __defaultRunProbe(probe: string, arg: string): ProbeResult {
+  const result = spawnSync(process.execPath, [PROBE_PATH, `--probe=${probe}`, `--arg=${arg}`], {
+    encoding: "utf8",
+  });
+  return {
+    status: result.status ?? -1,
+    stderr: result.stderr ?? "",
+    stdout: result.stdout ?? "",
+  };
+}

package/src/testing/sandbox-probe.ts

@@ -0,0 +1,87 @@
+/**
+ * Sandbox probe binary — invoked by `runSandboxContractTests`.
+ *
+ * The probe is a tiny standalone program that the contract harness forks
+ * (typically wrapped by the gateway's sandbox runner) to exercise one
+ * specific capability and report the outcome via process exit code.
+ *
+ * Exit codes:
+ *   0  — expected pass (network reach to a listed host succeeded)
+ *   2  — unexpected outcome (test fails)
+ *   10 — expected EACCES/EPERM on filesystem read (sandbox enforced)
+ *   11 — expected ECONNREFUSED/EPERM/EHOSTUNREACH/ENETUNREACH on network
+ *
+ * Invocation:
+ *   bun sandbox-probe.ts --probe=<name> --arg=<value>
+ *
+ * Probes:
+ *   network-listed   — HEAD-fetch https://<arg>/ ; succeed if 2xx-4xx
+ *   network-unlisted — fetch http://192.0.2.1 (TEST-NET-1); succeed if blocked
+ *   fs-denied        — read a known-protected path; succeed if EACCES
+ */
+
+const probe = process.argv.find((a) => a.startsWith("--probe="))?.slice(8);
+const arg = process.argv.find((a) => a.startsWith("--arg="))?.slice(6);
+
+function errorCode(e: unknown): string | undefined {
+  return (
+    (e as { code?: string; cause?: { code?: string } }).code ??
+    (e as { cause?: { code?: string } }).cause?.code
+  );
+}
+
+async function probeNetworkListed(): Promise<number> {
+  const url = `https://${arg ?? ""}/`;
+  try {
+    const res = await fetch(url, { method: "HEAD" });
+    return res.status >= 200 && res.status < 500 ? 0 : 2;
+  } catch {
+    return 2;
+  }
+}
+
+async function probeNetworkUnlisted(): Promise<number> {
+  try {
+    await fetch("http://192.0.2.1");
+    return 2;
+  } catch (e: unknown) {
+    const code = errorCode(e);
+    if (
+      code === "ECONNREFUSED" ||
+      code === "EPERM" ||
+      code === "EHOSTUNREACH" ||
+      code === "ENETUNREACH"
+    ) {
+      return 11;
+    }
+    return 2;
+  }
+}
+
+async function probeFsDenied(): Promise<number> {
+  const path =
+    process.platform === "win32" ? String.raw`C:\Windows\System32\config\SAM` : "/etc/passwd";
+  try {
+    await Bun.file(path).text();
+    return 2;
+  } catch (e: unknown) {
+    const code = (e as { code?: string }).code;
+    if (code === "EACCES" || code === "EPERM" || code === "EBUSY") return 10;
+    return 2;
+  }
+}
+
+async function main(): Promise<void> {
+  if (probe === "network-listed") process.exit(await probeNetworkListed());
+  if (probe === "network-unlisted") process.exit(await probeNetworkUnlisted());
+  if (probe === "fs-denied") process.exit(await probeFsDenied());
+  process.exit(2);
+}
+
+// This standalone probe has no imports/exports of its own, but the top-level
+// `await main()` below requires the file to be a module. `export {}` is the
+// canonical module marker for that. (Sonar S7787 flags the specifier-less
+// export, but removing it makes the top-level await a compile error — TS1375.)
+export {}; // NOSONAR S7787: specifier-less export is the module marker required for the top-level `await main()` below (removing it is TS1375).
+
+await main();

package/src/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared types for Nimbus extensions
+ */
+
+export interface NimbusItem {
+  id: string;
+  service: string;
+  itemType: "file" | "folder" | "email" | "event" | "photo" | "task";
+  name: string;
+  mimeType?: string;
+  sizeBytes?: number;
+  createdAt?: number;
+  modifiedAt?: number;
+  url?: string;
+  parentId?: string;
+  rawMeta?: Record<string, unknown>;
+}
+
+export interface ExtensionManifest {
+  $schema?: string;
+  id: string;
+  displayName: string;
+  version: string;
+  description: string;
+  author: string;
+  homepage?: string;
+  icon?: string;
+  entrypoint: string;
+  runtime: "bun" | "node";
+  permissions: Array<"read" | "write" | "delete">;
+  hitlRequired: Array<"write" | "delete">;
+  oauth?: {
+    provider: string;
+    scopes: string[];
+    authUrl: string;
+    tokenUrl: string;
+    pkce: boolean;
+  };
+  syncInterval?: number;
+  tags?: string[];
+  minNimbusVersion: string;
+}