@checkstack/backend-api 0.15.3 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @checkstack/backend-api
 
+## 0.16.0
+
+### Minor Changes
+
+- a06b899: Dead-code audit cleanup and a small platform of shared notification helpers.
+
+  **Removed (dead code)**
+
+  - `core/backend/src/plugin-manager/deregistration-guard.ts` deleted. The exported `assertCanDeregister()` was never called and was a less-complete version of the dependents+isUninstallable checks already done inline by `previewUninstallOriginator` / `uninstallOriginator` in `plugin-manager-orchestrator.ts`.
+  - `createMockQueueFactory` deprecated alias removed from `@checkstack/test-utils-backend`. Use `createMockQueueManager` directly.
+
+  **New shared helpers**
+
+  - `@checkstack/backend-api` now exports `requestTimeoutMs()` — a Zod field builder for outbound HTTP request timeouts (1s..60s, default 10s). Replaces hand-rolled `configNumber({}).min(1000).max(60_000).default(10_000)` in `integration-webhook-backend`, `integration-script-backend`, and `healthcheck-script-backend`'s inline collector.
+  - `@checkstack/notification-common` now exports `SubjectStatusSchema` / `SubjectStatus`, mirroring the existing `ImportanceSchema`.
+  - `@checkstack/notification-backend` now exports:
+    - `SUBJECT_STATUS_EMOJI` / `IMPORTANCE_EMOJI` — the shared status / importance emoji maps that Discord, Slack, Teams, Webex and Telegram previously each redefined inline.
+    - `postJson(opts)` — a timeout-bounded `fetch` wrapper that handles non-2xx logging and error mapping for webhook-style POSTs. Returns `{ ok: true, response } | { ok: false, error }`.
+
+  **Migrated to shared helpers**
+
+  - Discord, Slack, Gotify, Pushover notification backends now use `postJson`. Outer try/catch + per-plugin error mapping deleted (~140 LOC).
+  - Discord, Slack, Teams, Telegram, Webex notification backends now use `IMPORTANCE_EMOJI`. Discord, Slack, Teams use `SUBJECT_STATUS_EMOJI`.
+  - Teams, Webex, Backstage, Telegram kept their inline fetch/Bot logic: their error strings surface server response bodies to operators, or the transport isn't raw `fetch` (Telegram uses `grammy`'s `Bot`).
+
+  **API surface tightening**
+
+  - Per-plugin test-only re-exports in 6 notification backends (Pushover, Gotify, Backstage, Slack, Discord, Teams) and the `CertificateInfo` interface in `healthcheck-tls-backend/strategy.ts` are now JSDoc-tagged `@internal`. No behaviour change; signals that downstream consumers must not depend on them.
+
+- a06b899: Extract shared `EsmScriptRunner` + `ShellScriptRunner` utilities, fix HIGH-severity privilege amplification in the integration TS provider, and harden the integration shell setupGuide example.
+
+  **SECURITY FIX (HIGH)**
+
+  The integration TS provider (`@checkstack/integration-script-backend` → `scriptProvider`) previously executed user scripts via `new Function(script)` in the satellite's main V8 isolate. A user with `integrationAccess.manage` could read `globalThis.process.env` directly (`DATABASE_URL`, `JWT_SECRET`, queue credentials, signing keys, …) and exfiltrate them through `result.id` — which round-trips into `delivery_logs.externalId` and is readable via the `getDeliveryLog` ORPC procedure. The same permission grants no legitimate API to those secrets; this was a privilege amplification.
+
+  The provider now runs user scripts in a fresh Bun subprocess (matching the healthcheck inline-script collector model). The subprocess receives only a curated `SAFE_ENV_VARS` whitelist (`PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `LC_CTYPE`, `TZ`, `TMPDIR`, `HOSTNAME`, `SHELL`) — backend secrets are no longer visible to user code. Filesystem reads, network calls (`fetch`), and the rest of the Node/Bun standard library continue to work, just in an isolated process.
+
+  **BREAKING CHANGE (`@checkstack/integration-script-backend`)**
+
+  User scripts can no longer read the satellite process's environment variables (`process.env.DATABASE_URL` etc. return `undefined`). Scripts that legitimately need configuration should accept it via the provider's `script` field input, not by introspecting the host environment. The full Node/Bun stdlib remains available; only the env scrub is new.
+
+  **REFACTOR — new shared utilities in `@checkstack/backend-api`**
+
+  Both the healthcheck and integration plugins had near-identical inline implementations of "run a user script in a subprocess sandbox" (ESM path) and "run a user shell script through `sh -c`" (shell path). These are now canonical, single-source-of-truth utilities:
+
+  - **`defaultEsmScriptRunner.run({ script, context, timeoutMs, helperModuleName?, helperFunctionName? })`** — writes the user module to a fresh `mkdtemp` directory along with a generated runner module, spawns a Bun subprocess with `pickSafeEnv()`, parses the result back through a UUID-tagged stderr marker, and tears everything down in `finally` (`clearTimeout` + `proc.kill()` + recursive `rm`). The optional `helperModuleName` / `helperFunctionName` pair drops a sibling `_helpers.mjs` file and rewrites `import { <fn> } from "<module>"` to point at it (this is the trick that makes `@checkstack/healthcheck` / `@checkstack/integration` resolve at runtime even though they're not real npm packages).
+  - **`defaultShellScriptRunner.run({ script, timeoutMs, cwd?, env? })`** — invokes `sh -c <script>` via `Bun.spawn` with `SAFE_ENV_VARS` (user-supplied `env` merged on top), `Promise.race` timeout with `proc.kill()` on expiry, and the same `clearTimeout` + `proc.kill()` cleanup in `finally`.
+
+  Both runners expose `EsmScriptRunner` / `ShellScriptRunner` interfaces so tests can inject mocks without touching the spawn path. The four call sites (`plugins/healthcheck-script-backend/src/inline-script-collector.ts`, `strategy.ts` and `plugins/integration-script-backend/src/provider.ts`, `shell-provider.ts`) collapse from full inline implementations to ~8-line adapters.
+
+  **FIXES**
+
+  - Integration shell provider's `setupGuide` example replaced the unsafe `curl -d "{\"title\": \"$PAYLOAD_TITLE\"}"` JSON interpolation with a `jq -n --arg title "$PAYLOAD_TITLE" '{title: $title}'` pattern. The previous example demonstrated a shell-injection vulnerability whenever event payload values contained shell-special or JSON-special characters (which they can, since payloads come from other plugins / events / GitOps reconciles).
+  - The shared shell runner adds `clearTimeout` + idempotent `proc?.kill()` in `finally`, fixing a leaked event-loop timer in the integration shell provider's previous inline implementation.
+
+  **TESTS**
+
+  - New `core/backend-api/src/esm-script-runner.test.ts` covering `normaliseUserScript` + `rewriteHelperImports` across both healthcheck and integration helper-module names, including regex-metacharacter escape coverage.
+  - The plugin-local `inline-script-normaliser.test.ts` was deleted; the same coverage (plus more) lives at the canonical location with the utility.
+  - Integration TS provider console-logging tests updated: in the subprocess model, `console.warn` and `console.error` both write to stderr (Bun matches Node), so the provider forwards every stderr line to `logger.error`. `console.log({…})` uses Bun's native `util.inspect` format rather than `JSON.stringify`, so the JSON-logging test now asserts on substring presence instead of strict serialisation.
+
+  2047 tests pass, lint + typecheck clean.
+
+### Patch Changes
+
+- @checkstack/cache-api@0.3.3
+- @checkstack/queue-api@0.3.3
+- @checkstack/healthcheck-common@1.1.1
+
 ## 0.15.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./src/index.ts",
@@ -12,8 +12,8 @@
   "dependencies": {
     "@checkstack/common": "0.10.0",
     "@checkstack/healthcheck-common": "1.1.0",
-    "@checkstack/cache-api": "0.3.1",
-    "@checkstack/queue-api": "0.3.1",
+    "@checkstack/cache-api": "0.3.2",
+    "@checkstack/queue-api": "0.3.2",
     "@checkstack/signal-common": "0.2.3",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",

package/src/base-strategy-config.ts

@@ -24,3 +24,22 @@ export const baseStrategyConfigSchema = z.object({
  * Base config type that all strategy configs must satisfy.
  */
 export type BaseStrategyConfig = z.infer<typeof baseStrategyConfigSchema>;
+
+/**
+ * Shared timeout field for outbound HTTP requests (webhooks, integration
+ * deliveries, inline scripts). Standardises bounds and default across plugins
+ * so operators see a consistent UX in the config UI.
+ *
+ * Bounds: `1_000ms` to `60_000ms`, default `10_000ms`.
+ *
+ * @example
+ * ```typescript
+ * const provider = z.object({
+ *   url: configString({}).url(),
+ *   timeout: requestTimeoutMs().describe("Request timeout in milliseconds"),
+ * });
+ * ```
+ */
+export function requestTimeoutMs() {
+  return configNumber({}).min(1000).max(60_000).default(10_000);
+}

package/src/esm-script-runner.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, it } from "bun:test";
+import {
+  normaliseUserScript,
+  rewriteHelperImports,
+} from "./esm-script-runner";
+
+/**
+ * The shared ESM-script runner applies two text transforms to user
+ * source before writing it to a temp `.mjs` file:
+ *
+ *  1. `normaliseUserScript` — wraps legacy `return X;` style scripts in
+ *     an async IIFE so they're valid as a module's default export,
+ *     while leaving real ESM modules (those with top-level
+ *     `import`/`export`) untouched.
+ *
+ *  2. `rewriteHelperImports` — rewrites `from "<helperModuleName>"`
+ *     to point at a runtime helper file written next to the user
+ *     script.
+ *
+ * Both are easy to regress (a regex tweak that gets greedier than
+ * intended, an edge case with comments, …) and both directly affect
+ * whether user scripts run at all. Keep this suite tight.
+ *
+ * These were previously tested under
+ * `plugins/healthcheck-script-backend/src/inline-script-normaliser.test.ts`;
+ * the utilities now live in `@checkstack/backend-api` and are shared by
+ * both healthcheck (inline-script-collector) and integration
+ * (script-provider).
+ */
+
+describe("normaliseUserScript", () => {
+  it("wraps a bare `return` body in an async IIFE default export", () => {
+    const out = normaliseUserScript("return { success: true };");
+    expect(out).toContain("export default await (async () => {");
+    expect(out).toContain("return { success: true };");
+    expect(out).toContain("})();");
+  });
+
+  it("wraps a no-return body (side-effect script) the same way", () => {
+    const out = normaliseUserScript("console.log('hi');");
+    expect(out).toContain("export default await (async () => {");
+    expect(out).toContain("console.log('hi');");
+  });
+
+  it("leaves a real ESM module (with top-level `import`) untouched", () => {
+    const src = `import { loadavg } from "node:os";\nexport default { success: true };`;
+    expect(normaliseUserScript(src)).toBe(src);
+  });
+
+  it("leaves a module with only `export default` (no import) untouched", () => {
+    const src = `export default { success: true };`;
+    expect(normaliseUserScript(src)).toBe(src);
+  });
+
+  it("leaves a script with `export` after leading whitespace untouched", () => {
+    // Top-level matters regardless of leading whitespace — the regex is
+    // anchored with `^\s*` per-line via the `m` flag.
+    const src = `   export default 42;`;
+    expect(normaliseUserScript(src)).toBe(src);
+  });
+
+  it("treats indented `return`-style scripts as legacy (wraps them)", () => {
+    // Per current behaviour: only top-of-line `export`/`import` qualifies
+    // as ESM. Anything else gets wrapped. This is intentional — a script
+    // that contains the substring "import" inside a comment shouldn't be
+    // misclassified as ESM and have its `return` left dangling.
+    const src = `  // imports are great\n  return true;`;
+    expect(normaliseUserScript(src)).toContain("export default await");
+  });
+
+  it("appends a trailing newline before `})` so a trailing `//` comment doesn't swallow the brace", () => {
+    const out = normaliseUserScript("return true; // trailing comment");
+    // Confirm the wrapper structure didn't get clobbered by the comment.
+    expect(out).toMatch(/return true; \/\/ trailing comment\s*\n\}\)\(\)/);
+  });
+});
+
+describe("rewriteHelperImports", () => {
+  const HELPER_URL = "file:///tmp/checkstack-script-abc/_helpers.mjs";
+
+  it("rewrites a named import from the helper module", () => {
+    const out = rewriteHelperImports({
+      userScript: `import { defineHealthCheck } from "@checkstack/healthcheck";`,
+      helperModuleName: "@checkstack/healthcheck",
+      helperUrl: HELPER_URL,
+    });
+    expect(out).toBe(`import { defineHealthCheck } from "${HELPER_URL}";`);
+  });
+
+  it("works with single-quoted import specs too", () => {
+    const out = rewriteHelperImports({
+      userScript: `import { defineHealthCheck } from '@checkstack/healthcheck';`,
+      helperModuleName: "@checkstack/healthcheck",
+      helperUrl: HELPER_URL,
+    });
+    expect(out).toBe(`import { defineHealthCheck } from "${HELPER_URL}";`);
+  });
+
+  it("rewrites a side-effect import too", () => {
+    const out = rewriteHelperImports({
+      userScript: `import "@checkstack/healthcheck";`,
+      helperModuleName: "@checkstack/healthcheck",
+      helperUrl: HELPER_URL,
+    });
+    expect(out).toBe(`import "${HELPER_URL}";`);
+  });
+
+  it("leaves other imports alone", () => {
+    const src = `import { loadavg } from "node:os";\nimport fs from "node:fs/promises";`;
+    expect(
+      rewriteHelperImports({
+        userScript: src,
+        helperModuleName: "@checkstack/healthcheck",
+        helperUrl: HELPER_URL,
+      }),
+    ).toBe(src);
+  });
+
+  it("rewrites multiple occurrences", () => {
+    const src = `
+      import { defineHealthCheck } from "@checkstack/healthcheck";
+      import type { HealthCheckScriptResult } from "@checkstack/healthcheck";
+    `;
+    const out = rewriteHelperImports({
+      userScript: src,
+      helperModuleName: "@checkstack/healthcheck",
+      helperUrl: HELPER_URL,
+    });
+    expect(out.match(/@checkstack\/healthcheck/g)).toBeNull();
+    expect([...out.matchAll(new RegExp(HELPER_URL, "g"))].length).toBe(2);
+  });
+
+  it("doesn't rewrite the package name if it appears in a string literal", () => {
+    // Conservative regex: it only matches the spec position of an import
+    // statement (`from "..."` / `import "..."`). A string containing the
+    // package name elsewhere must be left alone.
+    const src = `console.log("Look up @checkstack/healthcheck on npm");`;
+    expect(
+      rewriteHelperImports({
+        userScript: src,
+        helperModuleName: "@checkstack/healthcheck",
+        helperUrl: HELPER_URL,
+      }),
+    ).toBe(src);
+  });
+
+  it("rewrites the integration helper module too (regex is parameterised)", () => {
+    // The shared runner is used by both healthcheck and integration
+    // plugins; the regex is built from the supplied `helperModuleName`.
+    // Sanity check that the integration variant works.
+    const out = rewriteHelperImports({
+      userScript: `import { defineIntegration } from "@checkstack/integration";`,
+      helperModuleName: "@checkstack/integration",
+      helperUrl: HELPER_URL,
+    });
+    expect(out).toBe(`import { defineIntegration } from "${HELPER_URL}";`);
+  });
+
+  it("escapes regex metacharacters in the helper module name", () => {
+    // Defence-in-depth: if someone ever passes a name with special
+    // chars, we don't want it interpreted as a regex.
+    const out = rewriteHelperImports({
+      userScript: `import x from "weird.pkg+name";`,
+      helperModuleName: "weird.pkg+name",
+      helperUrl: HELPER_URL,
+    });
+    expect(out).toBe(`import x from "${HELPER_URL}";`);
+  });
+});

package/src/esm-script-runner.ts

@@ -0,0 +1,467 @@
+import { spawn, type Subprocess } from "bun";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Shared sandbox for executing user-authored TypeScript / JavaScript
+ * modules in a fresh Bun subprocess.
+ *
+ * Used by both `@checkstack/healthcheck-script-backend` (the inline
+ * health-check collector) and `@checkstack/integration-script-backend`
+ * (the script integration provider). The two had near-identical inline
+ * implementations; this module is the canonical version.
+ *
+ * Why subprocess isolation matters:
+ *
+ *   Running user code via `new Function(script)` in the satellite's
+ *   own process gives the user `globalThis.process`, `node:fs`, etc.
+ *   — they can read every secret in `process.env` (DB URLs, signing
+ *   keys, queue creds) and exfiltrate them through the result. Even
+ *   `manage`-level users typically have no legitimate API for those
+ *   secrets, so in-process eval is a privilege amplification.
+ *
+ *   By spawning a separate Bun process with a curated `SAFE_ENV_VARS`
+ *   subset, the user's script gets the full Node/Bun standard library
+ *   to work with but cannot see the satellite's environment.
+ *
+ * Concurrency note: each `run()` invocation is fully isolated.
+ *
+ *   - `mkdtemp` guarantees a unique directory name (POSIX-atomic).
+ *   - The result-marker session id is a `randomUUID`, so each
+ *     subprocess's stderr is unambiguously its own — even if user
+ *     scripts happen to write text that looks like another invocation's
+ *     marker.
+ *   - The subprocess is launched with `cmd: [bun, runner.mjs]` whose
+ *     references to the temp dir are absolute paths in env/argv. Two
+ *     concurrent subprocesses can never read each other's user.mjs.
+ *
+ * Cleanup is `finally`-guaranteed: the timeout handle is cleared, any
+ * straggler subprocess is killed (idempotent on an already-exited
+ * process), and the temp dir is removed recursively — on success, on
+ * thrown error, AND on timeout.
+ */
+
+// =============================================================================
+// PUBLIC TYPES
+// =============================================================================
+
+export interface EsmScriptRunResult {
+  /** Raw value the user script returned (default export or legacy IIFE return). */
+  result?: unknown;
+  /** Error message if the script threw or failed to load. */
+  error?: string;
+  /** Stack trace if available. */
+  stack?: string;
+  /** Anything the script wrote to stdout — caller can surface as logs. */
+  stdout: string;
+  /** Anything the script wrote to stderr (with our result-marker stripped). */
+  stderr: string;
+  /** True if the timeout fired before the subprocess exited. */
+  timedOut: boolean;
+}
+
+export interface EsmScriptRunOptions {
+  /** User-supplied script source (modern ESM with `import`/`export`, or legacy `return X;`). */
+  script: string;
+  /** Object to expose as `globalThis.context` inside the subprocess. JSON-serialised; no functions / cycles. */
+  context: unknown;
+  /** Maximum execution time in milliseconds. */
+  timeoutMs: number;
+  /**
+   * Optional virtual module name that the user's script can `import`
+   * from. We write a sibling `_helpers.mjs` in the temp dir that
+   * exports a single identity function under `helperFunctionName`, and
+   * rewrite any `from "<helperModuleName>"` import in the user source
+   * to point at that file. Skipped if either field is omitted.
+   *
+   * @example
+   *   helperModuleName: "@checkstack/healthcheck"
+   *   helperFunctionName: "defineHealthCheck"
+   *   // editor: import { defineHealthCheck } from "@checkstack/healthcheck"
+   *   // runtime: import { defineHealthCheck } from "file:///tmp/.../_helpers.mjs"
+   */
+  helperModuleName?: string;
+  /** Name of the helper function injected as a global AND exported by the virtual module. */
+  helperFunctionName?: string;
+}
+
+/**
+ * Injectable interface. Production code calls
+ * `defaultEsmScriptRunner.run()`; tests can pass a mock to skip the
+ * actual subprocess spawn.
+ */
+export interface EsmScriptRunner {
+  run(options: EsmScriptRunOptions): Promise<EsmScriptRunResult>;
+}
+
+// =============================================================================
+// INTERNALS
+// =============================================================================
+
+/**
+ * Vars passed through to the subprocess. We intentionally do NOT
+ * forward the satellite's full env so backend secrets (DB URLs, API
+ * tokens, signing keys) never reach user-authored scripts. PATH / HOME
+ * / LANG / ... are kept so `node:child_process`, `node:fs`, and
+ * locale-sensitive APIs behave normally.
+ */
+const SAFE_ENV_VARS = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+  "TMPDIR",
+  "HOSTNAME",
+  "SHELL",
+];
+
+function pickSafeEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of SAFE_ENV_VARS) {
+    const value = process.env[key];
+    if (value !== undefined) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
+// =============================================================================
+// USER-SCRIPT NORMALISATION
+// =============================================================================
+
+const ESM_AT_TOP_LEVEL = /^\s*(import\s|export\s)/m;
+
+/**
+ * Make the user's source loadable as an ES module.
+ *
+ * Three shapes are supported:
+ *  1. **Real module** (contains `import` / `export` at top level) — used as-is.
+ *  2. **Legacy IIFE-style** (`return X;` at top level) — wrapped in an
+ *     async IIFE whose return value becomes the default export.
+ *  3. **Side-effect only** — treated as healthy unless it throws.
+ */
+export function normaliseUserScript(userScript: string): string {
+  if (ESM_AT_TOP_LEVEL.test(userScript)) {
+    return userScript;
+  }
+  // Trailing newline so a `// comment` on the last line doesn't swallow
+  // the closing brace.
+  return `export default await (async () => {\n${userScript}\n})();\n`;
+}
+
+/**
+ * Rewrite imports of a virtual module to point at a real on-disk
+ * helper file. The user writes a clean package import in the editor
+ * (with IntelliSense from the virtual ambient module), and at runtime
+ * we redirect it to a local sibling.
+ *
+ * The regex is anchored to the literal spec position of `from "..."` /
+ * `import "..."` — it doesn't touch substrings of comments or string
+ * literals.
+ */
+export function rewriteHelperImports({
+  userScript,
+  helperModuleName,
+  helperUrl,
+}: {
+  userScript: string;
+  helperModuleName: string;
+  helperUrl: string;
+}): string {
+  const escapedName = helperModuleName.replaceAll(
+    /[.*+?^${}()|[\]\\]/g,
+    String.raw`\$&`,
+  );
+  const fromRe = new RegExp(
+    String.raw`(from\s+)(["'])${escapedName}\2`,
+    "g",
+  );
+  const sideEffectRe = new RegExp(
+    String.raw`(import\s+)(["'])${escapedName}\2`,
+    "g",
+  );
+  return userScript
+    .replaceAll(fromRe, (_match, fromKw: string) =>
+      `${fromKw}${JSON.stringify(helperUrl)}`,
+    )
+    .replaceAll(sideEffectRe, (_match, importKw: string) =>
+      `${importKw}${JSON.stringify(helperUrl)}`,
+    );
+}
+
+// =============================================================================
+// RUNNER GENERATION
+// =============================================================================
+
+function buildHelperSource(helperFunctionName: string): string {
+  return `// Auto-generated. Identity helper that exists only so the editor can
+// type-check the user's return shape. The runtime is intentionally trivial.
+export function ${helperFunctionName}(value) { return value; }
+`;
+}
+
+function buildRunnerSource({
+  userScriptUrl,
+  contextJson,
+  helperFunctionName,
+  markerStart,
+  markerEnd,
+}: {
+  userScriptUrl: string;
+  contextJson: string;
+  helperFunctionName: string | undefined;
+  markerStart: string;
+  markerEnd: string;
+}): string {
+  const helperGlobal = helperFunctionName
+    ? `globalThis.${helperFunctionName} = (value) => value;\n`
+    : "";
+
+  // `String.raw` so embedded \n / \\ in the generated source survive
+  // verbatim to the temp file — the runner needs to write a real
+  // newline at runtime, which means the file on disk needs the two
+  // characters `\n` (not a real LF).
+  return String.raw`// Auto-generated runner for an inline user-script execution.
+// Sets up the user-facing globals, imports the user module, captures the
+// result, and writes it back to the parent through a stderr marker.
+
+globalThis.context = ${contextJson};
+${helperGlobal}
+const __markerStart = ${JSON.stringify(markerStart)};
+const __markerEnd = ${JSON.stringify(markerEnd)};
+
+function __emit(payload) {
+  // Single-line JSON, sandwiched between unique markers. The parent
+  // process does a lastIndexOf() to find it and is tolerant of
+  // arbitrary user output on stderr above.
+  process.stderr.write(__markerStart + JSON.stringify(payload) + __markerEnd + "\n");
+}
+
+try {
+  const __mod = await import(${JSON.stringify(userScriptUrl)});
+  let __result;
+  if (__mod && "default" in __mod && __mod.default !== undefined) {
+    const __def = __mod.default;
+    __result =
+      typeof __def === "function"
+        ? await __def(globalThis.context)
+        : __def;
+  }
+  __emit({ ok: true, result: __result ?? null });
+} catch (err) {
+  const __message =
+    err && typeof err === "object" && "message" in err
+      ? String(err.message)
+      : String(err);
+  const __stack =
+    err && typeof err === "object" && "stack" in err
+      ? String(err.stack)
+      : undefined;
+  __emit({ ok: false, error: __message, stack: __stack });
+  process.exit(1);
+}
+`;
+}
+
+// =============================================================================
+// MARKER PAYLOAD VALIDATION
+// =============================================================================
+
+type RunnerPayload =
+  | { ok: true; result: unknown }
+  | { ok: false; error: string; stack?: string };
+
+function isRunnerPayload(value: unknown): value is RunnerPayload {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  if (v.ok === true) return true;
+  if (v.ok === false && typeof v.error === "string") return true;
+  return false;
+}
+
+// =============================================================================
+// DEFAULT RUNNER
+// =============================================================================
+
+/**
+ * Default runner implementation. Production code should use this; tests
+ * can substitute a mock that conforms to {@link EsmScriptRunner}.
+ */
+export const defaultEsmScriptRunner: EsmScriptRunner = {
+  async run({
+    script,
+    context,
+    timeoutMs,
+    helperModuleName,
+    helperFunctionName,
+  }) {
+    const sessionId = randomUUID();
+    const markerStart = `##__CS_SCRIPT_RESULT_${sessionId}_START__##`;
+    const markerEnd = `##__CS_SCRIPT_RESULT_${sessionId}_END__##`;
+
+    const tmpDir = await mkdtemp(path.join(tmpdir(), "checkstack-script-"));
+    const userScriptPath = path.join(tmpDir, "user.mjs");
+    const runnerPath = path.join(tmpDir, "runner.mjs");
+
+    const hasHelper =
+      typeof helperModuleName === "string" &&
+      helperModuleName.length > 0 &&
+      typeof helperFunctionName === "string" &&
+      helperFunctionName.length > 0;
+    const helperPath = hasHelper ? path.join(tmpDir, "_helpers.mjs") : undefined;
+    const helperUrl = helperPath ? pathToFileURL(helperPath).href : undefined;
+
+    let proc: Subprocess | undefined;
+    let timedOut = false;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutHandle = setTimeout(() => {
+        timedOut = true;
+        proc?.kill();
+        reject(new Error("__TIMEOUT__"));
+      }, timeoutMs);
+    });
+
+    try {
+      // Helper module first so the user's
+      // `import { <fn> } from "<helperModuleName>"` (which we rewrite
+      // to point at this file's URL) resolves at module-evaluation time.
+      if (helperPath && helperFunctionName) {
+        await writeFile(helperPath, buildHelperSource(helperFunctionName), "utf8");
+      }
+
+      const normalisedSource = normaliseUserScript(script);
+      const userSource =
+        hasHelper && helperUrl
+          ? rewriteHelperImports({
+              userScript: normalisedSource,
+              helperModuleName: helperModuleName!,
+              helperUrl,
+            })
+          : normalisedSource;
+
+      await writeFile(userScriptPath, userSource, "utf8");
+      await writeFile(
+        runnerPath,
+        buildRunnerSource({
+          userScriptUrl: pathToFileURL(userScriptPath).href,
+          contextJson: JSON.stringify(context),
+          helperFunctionName: hasHelper ? helperFunctionName : undefined,
+          markerStart,
+          markerEnd,
+        }),
+        "utf8",
+      );
+
+      proc = spawn({
+        cmd: [process.execPath, runnerPath],
+        env: pickSafeEnv(),
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      let stdout: string;
+      let stderr: string;
+
+      try {
+        [stdout, stderr] = (await Promise.race([
+          Promise.all([
+            new Response(proc.stdout as ReadableStream).text(),
+            new Response(proc.stderr as ReadableStream).text(),
+            proc.exited,
+          ]),
+          timeoutPromise,
+        ])) as [string, string, number];
+      } catch (error) {
+        if (timedOut) {
+          return {
+            stdout: "",
+            stderr: "",
+            timedOut: true,
+            error: "Script execution timed out",
+          };
+        }
+        throw error;
+      }
+
+      // Pluck the runner payload out of stderr.
+      const startIdx = stderr.lastIndexOf(markerStart);
+      const endIdx = stderr.lastIndexOf(markerEnd);
+
+      let cleanStderr = stderr;
+      let payload: RunnerPayload | undefined;
+
+      if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const jsonStr = stderr.slice(startIdx + markerStart.length, endIdx);
+        try {
+          const parsed: unknown = JSON.parse(jsonStr);
+          if (isRunnerPayload(parsed)) {
+            payload = parsed;
+          }
+        } catch {
+          // Fall through to the "no marker" branch.
+        }
+        cleanStderr = (
+          stderr.slice(0, startIdx) + stderr.slice(endIdx + markerEnd.length)
+        )
+          .replace(/\n$/, "")
+          .trim();
+      }
+
+      if (!payload) {
+        // The runner never got far enough to emit — typically a syntax
+        // error in the user module or a hard crash. Surface whatever the
+        // subprocess wrote to stderr as the error.
+        return {
+          stdout: stdout.trim(),
+          stderr: cleanStderr,
+          timedOut: false,
+          error:
+            cleanStderr.length > 0
+              ? cleanStderr
+              : "Script exited without producing a result",
+        };
+      }
+
+      if (payload.ok) {
+        return {
+          result: payload.result,
+          stdout: stdout.trim(),
+          stderr: cleanStderr,
+          timedOut: false,
+        };
+      }
+
+      return {
+        error: payload.error,
+        stack: payload.stack,
+        stdout: stdout.trim(),
+        stderr: cleanStderr,
+        timedOut: false,
+      };
+    } finally {
+      // Order matters:
+      //   1. Clear the timer (otherwise a fast script leaks an
+      //      event-loop handle for up to `timeoutMs`).
+      //   2. Kill any straggler subprocess. `.kill()` is idempotent on
+      //      an already-exited process.
+      //   3. Remove the tempdir last — after the subprocess can no
+      //      longer be touching its files.
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+      proc?.kill();
+      await rm(tmpDir, { recursive: true, force: true }).catch(() => {
+        // Best-effort. Anything left in /tmp will be reaped by the OS.
+      });
+    }
+  },
+};

package/src/index.ts

@@ -1,3 +1,5 @@
+export * from "./esm-script-runner";
+export * from "./shell-script-runner";
 export * from "./service-ref";
 export * from "./extension-point";
 export * from "./core-services";

package/src/shell-script-runner.ts

@@ -0,0 +1,175 @@
+import { spawn, type Subprocess } from "bun";
+
+/**
+ * Shared sandbox for executing user-authored shell scripts through
+ * `sh -c`.
+ *
+ * Used by both `@checkstack/healthcheck-script-backend` (the shell
+ * health-check strategy) and `@checkstack/integration-script-backend`
+ * (the shell integration provider). The two had near-identical inline
+ * implementations; this module is the canonical version.
+ *
+ * Why a curated env: a script author already has authority to execute
+ * arbitrary shell, but we must not leak the satellite's own secrets to
+ * them. The forwarded env is the minimum needed for ordinary commands
+ * (`awk`, `curl`, `git`, locale-aware tools) to behave correctly:
+ * `PATH` so binaries resolve, `HOME` / `USER` so tools find their
+ * config, `LANG` / `LC_*` so output is parseable, `TZ` so timestamps
+ * are consistent, `TMPDIR` so `mktemp` works. Everything else
+ * (DB URLs, signing keys, queue creds, etc.) is dropped.
+ *
+ * Cleanup is `finally`-guaranteed: the timeout handle is cleared so a
+ * fast script doesn't leak an event-loop timer, and any straggler
+ * subprocess is `.kill()`-ed (idempotent on an already-exited
+ * process). This matches the pattern in the ESM script runner.
+ */
+
+// =============================================================================
+// PUBLIC TYPES
+// =============================================================================
+
+export interface ShellScriptRunResult {
+  /** Exit code reported by the subprocess. -1 if it never started or timed out. */
+  exitCode: number;
+  /** Captured stdout, trimmed of trailing newlines. */
+  stdout: string;
+  /** Captured stderr, trimmed of trailing newlines. */
+  stderr: string;
+  /** True if the timeout fired before the subprocess exited. */
+  timedOut: boolean;
+}
+
+export interface ShellScriptRunOptions {
+  /** Shell-script source. Fed verbatim to `sh -c`, so pipes, redirects, etc. work. */
+  script: string;
+  /** Maximum execution time in milliseconds. */
+  timeoutMs: number;
+  /** Optional working directory for the subprocess. */
+  cwd?: string;
+  /**
+   * Optional extra environment variables. Merged on top of the
+   * safe-vars whitelist (`PATH`, `HOME`, ...). User-supplied values
+   * win on key collision.
+   *
+   * Note: callers should validate the keys themselves if they need to
+   * forbid `LD_PRELOAD`, `NODE_OPTIONS`, etc. — at the shared-runner
+   * layer we accept whatever the caller passes, because the legitimate
+   * use cases (e.g. integration shell scripts injecting `PAYLOAD_*`
+   * vars) vary too much.
+   */
+  env?: Record<string, string>;
+}
+
+/**
+ * Injectable interface. Production code calls
+ * `defaultShellScriptRunner.run()`; tests can pass a mock to skip the
+ * actual subprocess spawn.
+ */
+export interface ShellScriptRunner {
+  run(options: ShellScriptRunOptions): Promise<ShellScriptRunResult>;
+}
+
+// =============================================================================
+// INTERNALS
+// =============================================================================
+
+/**
+ * Vars passed through to the subprocess. We intentionally do NOT
+ * forward the satellite's full env so backend secrets (DB URLs, API
+ * tokens, signing keys) never reach user-authored scripts.
+ */
+const SAFE_ENV_VARS = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+  "TMPDIR",
+  "HOSTNAME",
+  "SHELL",
+];
+
+function pickSafeEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of SAFE_ENV_VARS) {
+    const value = process.env[key];
+    if (value !== undefined) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
+// =============================================================================
+// DEFAULT RUNNER
+// =============================================================================
+
+/**
+ * Default runner implementation. Production code should use this; tests
+ * can substitute a mock that conforms to {@link ShellScriptRunner}.
+ */
+export const defaultShellScriptRunner: ShellScriptRunner = {
+  async run({ script, timeoutMs, cwd, env }) {
+    let proc: Subprocess | undefined;
+    let timedOut = false;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutHandle = setTimeout(() => {
+        timedOut = true;
+        proc?.kill();
+        reject(new Error("Script execution timed out"));
+      }, timeoutMs);
+    });
+
+    try {
+      // Execute through `sh -c` so the user's script can use pipes,
+      // redirects, variable expansion, conditionals, command
+      // substitution, etc. — i.e. behave like a real shell script
+      // rather than a single argv vector.
+      proc = spawn({
+        cmd: ["sh", "-c", script],
+        cwd,
+        env: { ...pickSafeEnv(), ...env },
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const [stdout, stderr, exitCode] = await Promise.race([
+        Promise.all([
+          new Response(proc.stdout as ReadableStream).text(),
+          new Response(proc.stderr as ReadableStream).text(),
+          proc.exited,
+        ]),
+        timeoutPromise,
+      ]);
+
+      return {
+        exitCode,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        timedOut: false,
+      };
+    } catch (error) {
+      if (timedOut) {
+        return {
+          exitCode: -1,
+          stdout: "",
+          stderr: "Script execution timed out",
+          timedOut: true,
+        };
+      }
+      throw error;
+    } finally {
+      if (timeoutHandle !== undefined) {
+        clearTimeout(timeoutHandle);
+      }
+      // Idempotent — no-op when the subprocess has already exited
+      // cleanly, but guarantees we never leave a runaway `sh` from
+      // an exception path.
+      proc?.kill();
+    }
+  },
+};