@checkstack/backend-api 0.18.0 → 0.20.0

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

@@ -1,5 +1,9 @@
-import { describe, expect, it } from "bun:test";
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import {
+  defaultEsmScriptRunner,
   normaliseUserScript,
   rewriteHelperImports,
 } from "./esm-script-runner";
@@ -167,3 +171,91 @@ describe("rewriteHelperImports", () => {
     expect(out).toBe(`import x from "${HELPER_URL}";`);
   });
 });
+
+describe("defaultEsmScriptRunner resolutionRoot", () => {
+  let root: string;
+
+  beforeAll(async () => {
+    // A throwaway "store" with a node_modules holding one fake package.
+    root = await mkdtemp(path.join(tmpdir(), "cs-resroot-"));
+    const pkgDir = path.join(root, "node_modules", "fake-pkg");
+    await mkdir(pkgDir, { recursive: true });
+    await writeFile(
+      path.join(pkgDir, "package.json"),
+      JSON.stringify({ name: "fake-pkg", version: "1.0.0", main: "index.mjs" }),
+    );
+    await writeFile(
+      path.join(pkgDir, "index.mjs"),
+      "export const greeting = 'hello-from-pkg';\n",
+    );
+  });
+
+  afterAll(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it("lets a script import a package from <resolutionRoot>/node_modules", async () => {
+    const res = await defaultEsmScriptRunner.run({
+      script: `import { greeting } from "fake-pkg";\nexport default greeting;`,
+      context: {},
+      timeoutMs: 15_000,
+      resolutionRoot: root,
+    });
+    expect(res.error).toBeUndefined();
+    expect(res.result).toBe("hello-from-pkg");
+  });
+
+  it("cannot resolve the package without a resolutionRoot (backward-compatible isolation)", async () => {
+    const res = await defaultEsmScriptRunner.run({
+      script: `import { greeting } from "fake-pkg";\nexport default greeting;`,
+      context: {},
+      timeoutMs: 15_000,
+    });
+    // No resolutionRoot -> runs under os.tmpdir(), no node_modules -> the
+    // import fails. Either an error is surfaced or no result is produced.
+    expect(res.result).toBeUndefined();
+    expect(res.error).toBeDefined();
+  });
+
+  it("does NOT auto-install a missing package from the registry (degradation)", async () => {
+    // A real, installable package name that is NOT in any resolutionRoot.
+    // With auto-install disabled in the per-run bunfig, Bun must error
+    // instead of silently fetching it from the registry.
+    const res = await defaultEsmScriptRunner.run({
+      script: `import isodd from "is-odd";\nexport default typeof isodd;`,
+      context: {},
+      timeoutMs: 20_000,
+    });
+    expect(res.result).toBeUndefined();
+    expect(res.error).toBeDefined();
+  });
+});
+
+describe("defaultEsmScriptRunner injected env", () => {
+  it("exposes injected env vars as process.env in the subprocess", async () => {
+    const res = await defaultEsmScriptRunner.run({
+      script: `export default process.env.API_TOKEN ?? null;`,
+      context: {},
+      timeoutMs: 15_000,
+      env: { API_TOKEN: "injected-secret-value" },
+    });
+    expect(res.error).toBeUndefined();
+    expect(res.result).toBe("injected-secret-value");
+  });
+
+  it("does NOT expose backend env that was not injected (isolation intact)", async () => {
+    // A backend secret present in the parent process must NOT leak through
+    // unless it was explicitly injected for this run.
+    process.env.__CS_TEST_BACKEND_SECRET = "must-not-leak";
+    try {
+      const res = await defaultEsmScriptRunner.run({
+        script: `export default process.env.__CS_TEST_BACKEND_SECRET ?? null;`,
+        context: {},
+        timeoutMs: 15_000,
+      });
+      expect(res.result).toBeNull();
+    } finally {
+      delete process.env.__CS_TEST_BACKEND_SECRET;
+    }
+  });
+});

package/src/esm-script-runner.ts

@@ -86,6 +86,34 @@ export interface EsmScriptRunOptions {
   helperModuleName?: string;
   /** Name of the helper function injected as a global AND exported by the virtual module. */
   helperFunctionName?: string;
+  /**
+   * Optional directory the per-run temp dir is created *inside*, so Node /
+   * Bun module resolution walks up to `<resolutionRoot>/node_modules` and
+   * the user's script can `import` managed npm packages.
+   *
+   * When unset (the default), the per-run dir is created under
+   * `os.tmpdir()` exactly as before - backward-compatible, no node_modules
+   * visible, isolation unchanged. The script-packages reconciler points
+   * this at `<store>/current` (the atomically-flipped symlink to the
+   * active materialized tree).
+   *
+   * Execution isolation is unchanged either way: the subprocess still gets
+   * only `SAFE_ENV_VARS`, so packages cannot read backend secrets.
+   */
+  resolutionRoot?: string;
+  /**
+   * Extra environment variables injected into the subprocess for THIS run
+   * only, merged on top of `SAFE_ENV_VARS`. The Secrets platform uses this
+   * to inject a run's resolved secret -> env allowlist (decision 5,
+   * least-privilege): only the consumer's declared secrets are injected,
+   * memory-only, for the lifetime of this run. It deliberately does NOT
+   * widen the ambient `SAFE_ENV_VARS` whitelist — the values live only in
+   * this options object and the spawned process env.
+   *
+   * The user's script reads these as `process.env.ENV_NAME`. On a key
+   * collision with a safe var, the injected value wins.
+   */
+  env?: Record<string, string>;
 }
 
 /**
@@ -301,14 +329,22 @@ export const defaultEsmScriptRunner: EsmScriptRunner = {
     timeoutMs,
     helperModuleName,
     helperFunctionName,
+    resolutionRoot,
+    env: injectedEnv,
   }) {
     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-"));
+    // When a `resolutionRoot` is given, create the per-run dir *inside* it
+    // so module resolution walks up to `<resolutionRoot>/node_modules`.
+    // Otherwise fall back to `os.tmpdir()` (today's behavior - no
+    // node_modules visible, fully backward compatible).
+    const tmpBase = resolutionRoot ?? tmpdir();
+    const tmpDir = await mkdtemp(path.join(tmpBase, "checkstack-script-"));
     const userScriptPath = path.join(tmpDir, "user.mjs");
     const runnerPath = path.join(tmpDir, "runner.mjs");
+    const bunfigPath = path.join(tmpDir, "bunfig.toml");
 
     const hasHelper =
       typeof helperModuleName === "string" &&
@@ -348,6 +384,14 @@ export const defaultEsmScriptRunner: EsmScriptRunner = {
             })
           : normalisedSource;
 
+      // Disable Bun auto-install in the per-run dir ALWAYS. Without this,
+      // `import "any-package"` silently fetches from the registry (verified
+      // empirically), defeating the whole managed-allowlist model. With it,
+      // an import resolves ONLY against the reconciled `<resolutionRoot>/
+      // node_modules` (when set) and otherwise fails fast - the clear
+      // degradation the package feature requires.
+      await writeFile(bunfigPath, '[install]\nauto = "disable"\n', "utf8");
+
       await writeFile(userScriptPath, userSource, "utf8");
       await writeFile(
         runnerPath,
@@ -363,7 +407,14 @@ export const defaultEsmScriptRunner: EsmScriptRunner = {
 
       proc = spawn({
         cmd: [process.execPath, runnerPath],
-        env: pickSafeEnv(),
+        // CWD = the per-run dir so Bun reads its `bunfig.toml`
+        // (auto-install disabled) and resolves modules from
+        // `<resolutionRoot>/node_modules` when set.
+        cwd: tmpDir,
+        // Per-run injected env wins over the safe-vars whitelist. The
+        // injected secret values live only here + the child process; they
+        // never widen the ambient SAFE_ENV_VARS.
+        env: { ...pickSafeEnv(), ...injectedEnv },
         stdout: "pipe",
         stderr: "pipe",
       });

package/src/index.ts

@@ -33,3 +33,4 @@ export * from "./incremental-aggregation";
 export * from "./aggregated-result";
 export * from "./ws-registry";
 export * from "./readiness-registry";
+export * from "./advisory-lock";

package/src/plugin-system.ts

@@ -85,6 +85,20 @@ export type BackendPluginRegistry = {
     ) => Promise<void>;
   }) => void;
   registerService: <S>(ref: ServiceRef<S>, impl: S) => void;
+  /**
+   * Resolve a platform service registered by another plugin under `ref`,
+   * using THIS plugin's identity as the consumer (for audit / scoped
+   * factories). Mirrors the standard dependency-injection resolution used
+   * for declared `deps`, but allows resolving ARBITRARY cross-plugin refs
+   * at runtime — the path used by the automation dispatch engine to hand
+   * `getService` to provider actions at execute time.
+   *
+   * Resolves the service, or throws a clear error if `ref` is not
+   * registered (it never silently returns `undefined`). Safe to call from
+   * `init` / `afterPluginsReady` onward, by which point services are
+   * registered.
+   */
+  getService: <S>(ref: ServiceRef<S>) => Promise<S>;
   registerExtensionPoint: <T>(ref: ExtensionPoint<T>, impl: T) => void;
   getExtensionPoint: <T>(ref: ExtensionPoint<T>) => T;
   /**

package/src/schema-utils.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { configString, withConfigMeta } from "./zod-config";
+import { toJsonSchema } from "./schema-utils";
+
+describe("toJsonSchema x-* metadata", () => {
+  test("propagates x-script-testable and x-editor-types onto the field", () => {
+    const schema = z.object({
+      script: configString({
+        "x-editor-types": ["typescript"],
+        "x-script-testable": true,
+      }),
+    });
+
+    const json = toJsonSchema(schema) as {
+      properties: Record<string, Record<string, unknown>>;
+    };
+
+    expect(json.properties.script?.["x-script-testable"]).toBe(true);
+    expect(json.properties.script?.["x-editor-types"]).toEqual(["typescript"]);
+  });
+
+  test("omits x-script-testable when not set", () => {
+    const schema = z.object({
+      plain: configString({}),
+    });
+    const json = toJsonSchema(schema) as {
+      properties: Record<string, Record<string, unknown>>;
+    };
+    expect("x-script-testable" in (json.properties.plain ?? {})).toBe(false);
+  });
+
+  test("propagates x-secret-env onto a record field via withConfigMeta", () => {
+    const schema = z.object({
+      secretEnv: withConfigMeta(z.record(z.string(), z.string()), {
+        "x-secret-env": true,
+      }),
+    });
+    const json = toJsonSchema(schema) as {
+      properties: Record<string, Record<string, unknown>>;
+    };
+    expect(json.properties.secretEnv?.["x-secret-env"]).toBe(true);
+  });
+});

package/src/schema-utils.ts

@@ -67,6 +67,12 @@ function addSchemaMetadata(
       if (meta["x-editor-types"]) {
         jsonField["x-editor-types"] = meta["x-editor-types"];
       }
+      if (meta["x-script-testable"]) {
+        jsonField["x-script-testable"] = true;
+      }
+      if (meta["x-secret-env"]) {
+        jsonField["x-secret-env"] = true;
+      }
       if (meta["x-hidden-when"]) {
         jsonField["x-hidden-when"] = meta["x-hidden-when"];
       }

package/src/zod-config.ts

@@ -38,6 +38,22 @@ export interface ConfigMeta {
    * - "formdata": Key/value pair editor (URL-encoded)
    */
   "x-editor-types"?: EditorType[];
+  /**
+   * Mark this field as an inline script that can be tested in-UI. When the
+   * editor renders the field (via `MultiTypeEditorField`) and the owning
+   * page supplies a `scriptTestRenderer`, a test panel appears beneath the
+   * editor so operators can run the script against a sample context.
+   */
+  "x-script-testable"?: boolean;
+  /**
+   * Mark a record field as a secret -> env mapping
+   * (`{ ENV_NAME: "${{ secrets.NAME }}" }`). The editor renders a
+   * dedicated key (env name) + secret-name picker, with the available
+   * names supplied to `DynamicForm` via `secretNames` (from the secrets
+   * plugin's `listSecretNames`). Without the marker the record falls back
+   * to the plain JSON editor.
+   */
+  "x-secret-env"?: boolean;
 }
 
 /**
@@ -164,3 +180,20 @@ export function configBoolean(meta: ConfigMeta) {
   schema.register(configRegistry, meta);
   return schema;
 }
+
+/**
+ * Attach config metadata to an existing schema (e.g. a `z.record`) and
+ * return it. Use this when a field's base schema is defined elsewhere
+ * (such as `secretEnvMappingSchema` from `@checkstack/secrets-common`) but
+ * still needs editor metadata like `x-secret-env`.
+ */
+export function withConfigMeta<T extends z.ZodTypeAny>(
+  schema: T,
+  meta: ConfigMeta,
+): T {
+  // The registry is typed `z.registry<ConfigMeta>()`, so registering the
+  // meta is sound; the generic `T` confuses zod's conditional `.register`
+  // overload, so register through the base schema type.
+  (schema as z.ZodTypeAny).register(configRegistry, meta);
+  return schema;
+}