@hachej/boring-sandbox 0.1.78 → 0.1.79

package/dist/providers/runsc/index.d.ts

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+
+declare const RunscPreflightConfigSchema: z.ZodEffects<z.ZodObject<{
+    stateRoot: z.ZodEffects<z.ZodString, string, string>;
+    digestMarkerPath: z.ZodEffects<z.ZodString, string, string>;
+    networkNamespace: z.ZodString;
+    nftTable: z.ZodString;
+    requiredBlockedCidrs: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+    cgroupRoot: z.ZodEffects<z.ZodString, string, string>;
+    workspaceCgroupRoot: z.ZodEffects<z.ZodString, string, string>;
+    binaries: z.ZodObject<{
+        runsc: z.ZodEffects<z.ZodString, string, string>;
+        ip: z.ZodEffects<z.ZodString, string, string>;
+        nft: z.ZodEffects<z.ZodString, string, string>;
+        cat: z.ZodEffects<z.ZodString, string, string>;
+        true: z.ZodEffects<z.ZodString, string, string>;
+    }, "strict", z.ZodTypeAny, {
+        runsc: string;
+        ip: string;
+        nft: string;
+        cat: string;
+        true: string;
+    }, {
+        runsc: string;
+        ip: string;
+        nft: string;
+        cat: string;
+        true: string;
+    }>;
+    expected: z.ZodObject<{
+        imageDigest: z.ZodString;
+        cpuPeriodMicros: z.ZodNumber;
+        cpuQuotaMicros: z.ZodNumber;
+        memoryBytes: z.ZodNumber;
+        pidsMax: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        imageDigest: string;
+        cpuPeriodMicros: number;
+        cpuQuotaMicros: number;
+        memoryBytes: number;
+        pidsMax: number;
+    }, {
+        imageDigest: string;
+        cpuPeriodMicros: number;
+        cpuQuotaMicros: number;
+        memoryBytes: number;
+        pidsMax: number;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    stateRoot: string;
+    digestMarkerPath: string;
+    networkNamespace: string;
+    nftTable: string;
+    expected: {
+        imageDigest: string;
+        cpuPeriodMicros: number;
+        cpuQuotaMicros: number;
+        memoryBytes: number;
+        pidsMax: number;
+    };
+    requiredBlockedCidrs: string[];
+    cgroupRoot: string;
+    workspaceCgroupRoot: string;
+    binaries: {
+        runsc: string;
+        ip: string;
+        nft: string;
+        cat: string;
+        true: string;
+    };
+}, {
+    stateRoot: string;
+    digestMarkerPath: string;
+    networkNamespace: string;
+    nftTable: string;
+    expected: {
+        imageDigest: string;
+        cpuPeriodMicros: number;
+        cpuQuotaMicros: number;
+        memoryBytes: number;
+        pidsMax: number;
+    };
+    requiredBlockedCidrs: string[];
+    cgroupRoot: string;
+    workspaceCgroupRoot: string;
+    binaries: {
+        runsc: string;
+        ip: string;
+        nft: string;
+        cat: string;
+        true: string;
+    };
+}>, {
+    stateRoot: string;
+    digestMarkerPath: string;
+    networkNamespace: string;
+    nftTable: string;
+    expected: {
+        imageDigest: string;
+        cpuPeriodMicros: number;
+        cpuQuotaMicros: number;
+        memoryBytes: number;
+        pidsMax: number;
+    };
+    requiredBlockedCidrs: string[];
+    cgroupRoot: string;
+    workspaceCgroupRoot: string;
+    binaries: {
+        runsc: string;
+        ip: string;
+        nft: string;
+        cat: string;
+        true: string;
+    };
+}, {
+    stateRoot: string;
+    digestMarkerPath: string;
+    networkNamespace: string;
+    nftTable: string;
+    expected: {
+        imageDigest: string;
+        cpuPeriodMicros: number;
+        cpuQuotaMicros: number;
+        memoryBytes: number;
+        pidsMax: number;
+    };
+    requiredBlockedCidrs: string[];
+    cgroupRoot: string;
+    workspaceCgroupRoot: string;
+    binaries: {
+        runsc: string;
+        ip: string;
+        nft: string;
+        cat: string;
+        true: string;
+    };
+}>;
+type RunscPreflightConfig = z.infer<typeof RunscPreflightConfigSchema>;
+declare function validateRunscPreflightConfig(value: unknown): RunscPreflightConfig;
+
+declare const RUNSC_PREFLIGHT_ERROR_CODES: {
+    readonly invalidConfig: "RUNSC_PREFLIGHT_INVALID_CONFIG";
+    readonly commandFailed: "RUNSC_PREFLIGHT_COMMAND_FAILED";
+    readonly invalidOutput: "RUNSC_PREFLIGHT_INVALID_OUTPUT";
+    readonly structuralMismatch: "RUNSC_PREFLIGHT_STRUCTURAL_MISMATCH";
+};
+declare const RUNSC_REQUIRED_BLOCKED_CIDRS: readonly ["10.0.0.0/8", "100.64.0.0/10", "169.254.0.0/16", "172.16.0.0/12", "192.168.0.0/16", "fc00::/7", "fe80::/10"];
+type RunscPreflightErrorCode = (typeof RUNSC_PREFLIGHT_ERROR_CODES)[keyof typeof RUNSC_PREFLIGHT_ERROR_CODES];
+interface RunscStructuralObservations {
+    runscVersionOutputValid: true;
+    digestMarkerMatchesExpected: true;
+    namespaceCommandSucceeded: true;
+    nftTableReadable: true;
+    configuredCidrTextPresent: true;
+    cgroupControllersPresent: readonly ["cpu", "memory", "pids"];
+    configuredLimitFilesMatchExpected: true;
+}
+/** Security properties that this structural preflight deliberately does not attest. */
+declare const RUNSC_UNPROVEN_SECURITY_FACTS: {
+    readonly systrapWorkload: "unknown";
+    readonly imageDigestBinding: "unknown";
+    readonly effectiveUid: "unknown";
+    readonly effectiveGid: "unknown";
+    readonly cgroupMembership: "unknown";
+    readonly resourceEnforcement: "unknown";
+    readonly networkIsolation: "unknown";
+    readonly metadataEgressDenied: "unknown";
+    readonly privateNetworkEgressDenied: "unknown";
+    readonly hostNetworkEgressDenied: "unknown";
+    readonly crossWorkspaceEgressDenied: "unknown";
+    readonly nftDropRulesEffective: "unknown";
+    readonly ociBundleUsed: "unknown";
+    readonly containerConfigurationUsed: "unknown";
+    readonly rootPathSafety: "unknown";
+    readonly hostRunnerEnforcement: "unknown";
+};
+type RunscUnprovenSecurityFacts = typeof RUNSC_UNPROVEN_SECURITY_FACTS;
+interface RunscPreflightErrorRecord {
+    code: RunscPreflightErrorCode;
+    message: string;
+}
+type RunscPreflightResult = {
+    status: "observed";
+    provider: "runsc";
+    productionReady: false;
+    observations: RunscStructuralObservations;
+    unproven: RunscUnprovenSecurityFacts;
+} | {
+    status: "failed";
+    provider: "runsc";
+    productionReady: false;
+    error: RunscPreflightErrorRecord;
+};
+
+declare class RunscPreflightError extends Error {
+    readonly code: RunscPreflightErrorCode;
+    constructor(code: RunscPreflightErrorCode, message: string);
+}
+
+interface RunscHostCommand {
+    file: string;
+    args: readonly string[];
+    timeoutMs: number;
+    maxOutputBytes: number;
+}
+interface RunscHostCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface RunscHostCommandRunner {
+    run(command: RunscHostCommand): Promise<unknown>;
+}
+declare function preflightRunsc(input: unknown, runner: RunscHostCommandRunner): Promise<RunscPreflightResult>;
+
+export { RUNSC_PREFLIGHT_ERROR_CODES, RUNSC_REQUIRED_BLOCKED_CIDRS, RUNSC_UNPROVEN_SECURITY_FACTS, type RunscHostCommand, type RunscHostCommandResult, type RunscHostCommandRunner, type RunscPreflightConfig, RunscPreflightError, type RunscPreflightErrorCode, type RunscPreflightErrorRecord, type RunscPreflightResult, type RunscStructuralObservations, type RunscUnprovenSecurityFacts, preflightRunsc, validateRunscPreflightConfig };

package/dist/providers/runsc/index.js

@@ -0,0 +1,280 @@
+// src/providers/runsc/config.ts
+import { isIP } from "net";
+import { isAbsolute, relative, resolve } from "path";
+import { z } from "zod";
+
+// src/shared/runsc.ts
+var RUNSC_PREFLIGHT_ERROR_CODES = {
+  invalidConfig: "RUNSC_PREFLIGHT_INVALID_CONFIG",
+  commandFailed: "RUNSC_PREFLIGHT_COMMAND_FAILED",
+  invalidOutput: "RUNSC_PREFLIGHT_INVALID_OUTPUT",
+  structuralMismatch: "RUNSC_PREFLIGHT_STRUCTURAL_MISMATCH"
+};
+var RUNSC_REQUIRED_BLOCKED_CIDRS = [
+  "10.0.0.0/8",
+  "100.64.0.0/10",
+  "169.254.0.0/16",
+  "172.16.0.0/12",
+  "192.168.0.0/16",
+  "fc00::/7",
+  "fe80::/10"
+];
+var RUNSC_UNPROVEN_SECURITY_FACTS = {
+  systrapWorkload: "unknown",
+  imageDigestBinding: "unknown",
+  effectiveUid: "unknown",
+  effectiveGid: "unknown",
+  cgroupMembership: "unknown",
+  resourceEnforcement: "unknown",
+  networkIsolation: "unknown",
+  metadataEgressDenied: "unknown",
+  privateNetworkEgressDenied: "unknown",
+  hostNetworkEgressDenied: "unknown",
+  crossWorkspaceEgressDenied: "unknown",
+  nftDropRulesEffective: "unknown",
+  ociBundleUsed: "unknown",
+  containerConfigurationUsed: "unknown",
+  rootPathSafety: "unknown",
+  hostRunnerEnforcement: "unknown"
+};
+
+// src/providers/runsc/errors.ts
+var RunscPreflightError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "RunscPreflightError";
+  }
+  code;
+};
+
+// src/providers/runsc/config.ts
+var SAFE_ID = /^[a-z0-9][a-z0-9_.-]{0,62}$/;
+var SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+var MIN_MEMORY_BYTES = 64 * 1024 * 1024;
+var AbsolutePath = z.string().min(1).max(4096).refine((value) => isAbsolute(value) && !value.includes("\0"));
+var Cidr = z.string().max(64).refine(isCidr);
+var PositiveInteger = z.number().int().positive().safe();
+var NonEmptyString = z.string().min(1);
+var RunscPreflightConfigSchema = z.object({
+  stateRoot: AbsolutePath,
+  digestMarkerPath: AbsolutePath,
+  networkNamespace: NonEmptyString.regex(SAFE_ID),
+  nftTable: NonEmptyString.regex(SAFE_ID),
+  requiredBlockedCidrs: z.array(Cidr).max(64),
+  cgroupRoot: AbsolutePath,
+  workspaceCgroupRoot: AbsolutePath,
+  binaries: z.object({
+    runsc: AbsolutePath,
+    ip: AbsolutePath,
+    nft: AbsolutePath,
+    cat: AbsolutePath,
+    true: AbsolutePath
+  }).strict(),
+  expected: z.object({
+    imageDigest: NonEmptyString.regex(SHA256_DIGEST),
+    cpuPeriodMicros: PositiveInteger,
+    cpuQuotaMicros: PositiveInteger,
+    memoryBytes: z.number().int().safe().min(MIN_MEMORY_BYTES),
+    pidsMax: z.number().int().min(16).max(65536)
+  }).strict()
+}).strict().superRefine((config, ctx) => {
+  if (!isChildPath(config.stateRoot, config.digestMarkerPath)) reject(ctx);
+  if (!isChildPath(config.cgroupRoot, config.workspaceCgroupRoot)) reject(ctx);
+  if (RUNSC_REQUIRED_BLOCKED_CIDRS.some((cidr) => !config.requiredBlockedCidrs.includes(cidr))) {
+    reject(ctx);
+  }
+  if (config.expected.cpuQuotaMicros > config.expected.cpuPeriodMicros * 64) reject(ctx);
+});
+function validateRunscPreflightConfig(value) {
+  const parsed = RunscPreflightConfigSchema.safeParse(value);
+  if (!parsed.success) invalid("config does not match the runsc preflight schema");
+  return parsed.data;
+}
+function reject(ctx) {
+  ctx.addIssue({ code: z.ZodIssueCode.custom, message: "cross-field constraint failed" });
+}
+function isChildPath(root, value) {
+  const child = resolve(value);
+  const rel = relative(resolve(root), child);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+function isCidr(value) {
+  const [address, prefix, extra] = value.split("/");
+  const family = address ? isIP(address) : 0;
+  if (!prefix || !/^\d+$/.test(prefix)) return false;
+  const prefixNumber = Number(prefix);
+  const maxPrefix = family === 4 ? 32 : family === 6 ? 128 : -1;
+  return !(extra !== void 0 || !Number.isInteger(prefixNumber) || prefixNumber < 0 || prefixNumber > maxPrefix);
+}
+function invalid(message) {
+  throw new RunscPreflightError(RUNSC_PREFLIGHT_ERROR_CODES.invalidConfig, message);
+}
+
+// src/providers/runsc/preflight.ts
+import { join } from "path";
+var PREFLIGHT_TIMEOUT_MS = 1e4;
+var PREFLIGHT_MAX_OUTPUT_BYTES = 256 * 1024;
+async function preflightRunsc(input, runner) {
+  try {
+    const config = validateRunscPreflightConfig(input);
+    const version = await runProbe(runner, "runsc version", config.binaries.runsc, ["--version"]);
+    assertVersionOutput(version.stdout);
+    const bundleDigest = await runProbe(runner, "digest marker", config.binaries.cat, [
+      config.digestMarkerPath
+    ]);
+    if (bundleDigest.stdout.trim() !== config.expected.imageDigest) {
+      throw new RunscPreflightError(
+        RUNSC_PREFLIGHT_ERROR_CODES.structuralMismatch,
+        "digest marker does not match the configured image digest"
+      );
+    }
+    await runProbe(runner, "network namespace", config.binaries.ip, [
+      "netns",
+      "exec",
+      config.networkNamespace,
+      config.binaries.true
+    ]);
+    const nft = await runProbe(runner, "nftables table", config.binaries.nft, [
+      "list",
+      "table",
+      "inet",
+      config.nftTable
+    ]);
+    for (const cidr of config.requiredBlockedCidrs) {
+      if (!nft.stdout.includes(cidr)) {
+        throw new RunscPreflightError(
+          RUNSC_PREFLIGHT_ERROR_CODES.structuralMismatch,
+          "nftables table output is missing configured CIDR text"
+        );
+      }
+    }
+    const controllers = await runProbe(runner, "cgroup v2 controllers", config.binaries.cat, [
+      join(config.cgroupRoot, "cgroup.controllers")
+    ]);
+    const controllerSet = new Set(controllers.stdout.trim().split(/\s+/));
+    for (const controller of ["cpu", "memory", "pids"]) {
+      if (!controllerSet.has(controller)) {
+        throw new RunscPreflightError(
+          RUNSC_PREFLIGHT_ERROR_CODES.structuralMismatch,
+          `cgroup v2 controller ${controller} is unavailable`
+        );
+      }
+    }
+    await verifyResourceLimits(config, runner);
+    return {
+      status: "observed",
+      provider: "runsc",
+      productionReady: false,
+      observations: {
+        runscVersionOutputValid: true,
+        digestMarkerMatchesExpected: true,
+        namespaceCommandSucceeded: true,
+        nftTableReadable: true,
+        configuredCidrTextPresent: true,
+        cgroupControllersPresent: ["cpu", "memory", "pids"],
+        configuredLimitFilesMatchExpected: true
+      },
+      unproven: RUNSC_UNPROVEN_SECURITY_FACTS
+    };
+  } catch (error) {
+    const normalized = normalizeError(error);
+    return {
+      status: "failed",
+      provider: "runsc",
+      productionReady: false,
+      error: { code: normalized.code, message: normalized.message }
+    };
+  }
+}
+async function runProbe(runner, label, file, args) {
+  let raw;
+  try {
+    raw = await runner.run({
+      file,
+      args,
+      timeoutMs: PREFLIGHT_TIMEOUT_MS,
+      maxOutputBytes: PREFLIGHT_MAX_OUTPUT_BYTES
+    });
+  } catch {
+    throw new RunscPreflightError(RUNSC_PREFLIGHT_ERROR_CODES.commandFailed, `${label} probe failed`);
+  }
+  const result = parseCommandResult(raw, label);
+  if (result.exitCode !== 0) {
+    throw new RunscPreflightError(RUNSC_PREFLIGHT_ERROR_CODES.commandFailed, `${label} probe failed`);
+  }
+  return result;
+}
+function assertVersionOutput(output) {
+  const line = output.split(/\r?\n/, 1)[0]?.trim() ?? "";
+  const match = /^runsc version\s+([a-z0-9][a-z0-9._+-]{0,127})$/i.exec(line);
+  if (!match?.[1]) {
+    throw new RunscPreflightError(
+      RUNSC_PREFLIGHT_ERROR_CODES.invalidOutput,
+      "runsc version output is invalid"
+    );
+  }
+}
+async function verifyResourceLimits(config, runner) {
+  const expected = config.expected;
+  const cpu = await runProbe(runner, "cgroup CPU limit", config.binaries.cat, [
+    join(config.workspaceCgroupRoot, "cpu.max")
+  ]);
+  const memory = await runProbe(runner, "cgroup memory limit", config.binaries.cat, [
+    join(config.workspaceCgroupRoot, "memory.max")
+  ]);
+  const pids = await runProbe(runner, "cgroup pid limit", config.binaries.cat, [
+    join(config.workspaceCgroupRoot, "pids.max")
+  ]);
+  const [quota, period, extra] = cpu.stdout.trim().split(/\s+/);
+  if (extra !== void 0 || quota !== String(expected.cpuQuotaMicros) || period !== String(expected.cpuPeriodMicros)) {
+    mismatch("CPU");
+  }
+  if (memory.stdout.trim() !== String(expected.memoryBytes)) mismatch("memory");
+  if (pids.stdout.trim() !== String(expected.pidsMax)) mismatch("pid");
+}
+function mismatch(resource) {
+  throw new RunscPreflightError(
+    RUNSC_PREFLIGHT_ERROR_CODES.structuralMismatch,
+    `cgroup ${resource} limit does not match the approved policy`
+  );
+}
+function parseCommandResult(value, label) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) invalidOutput(label);
+  const result = value;
+  if (!Number.isInteger(result.exitCode) || typeof result.stdout !== "string" || typeof result.stderr !== "string") {
+    invalidOutput(label);
+  }
+  const stdoutBytes = outputBytes(result.stdout);
+  const stderrBudget = PREFLIGHT_MAX_OUTPUT_BYTES - stdoutBytes;
+  if (stdoutBytes > PREFLIGHT_MAX_OUTPUT_BYTES || outputBytes(result.stderr) > stderrBudget) {
+    invalidOutput(label);
+  }
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr
+  };
+}
+function outputBytes(value) {
+  if (value.length > PREFLIGHT_MAX_OUTPUT_BYTES) return value.length;
+  return new TextEncoder().encode(value).byteLength;
+}
+function invalidOutput(label) {
+  throw new RunscPreflightError(
+    RUNSC_PREFLIGHT_ERROR_CODES.invalidOutput,
+    `${label} probe returned invalid output`
+  );
+}
+function normalizeError(error) {
+  if (error instanceof RunscPreflightError) return error;
+  return new RunscPreflightError(RUNSC_PREFLIGHT_ERROR_CODES.commandFailed, "runsc preflight failed");
+}
+export {
+  RUNSC_PREFLIGHT_ERROR_CODES,
+  RUNSC_REQUIRED_BLOCKED_CIDRS,
+  RUNSC_UNPROVEN_SECURITY_FACTS,
+  RunscPreflightError,
+  preflightRunsc,
+  validateRunscPreflightConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-sandbox",
-  "version": "0.1.78",
+  "version": "0.1.79",
   "type": "module",
   "license": "MIT",
   "description": "Sandbox provider contracts and implementations for Boring runtimes.",
@@ -24,9 +24,17 @@
     "./providers": {
       "types": "./dist/providers/index.d.ts",
       "import": "./dist/providers/index.js"
+    },
+    "./providers/runsc": {
+      "types": "./dist/providers/runsc/index.d.ts",
+      "import": "./dist/providers/runsc/index.js"
     }
   },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
   "devDependencies": {
+    "@types/node": "^22.20.0",
     "tsup": "^8.4.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"