@checkstack/backend-api 0.19.0 → 0.21.0

package/src/config-versioning.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Tests for the `Versioned<T>` config helper, focused on the
+ * assume-v1-on-read parse paths used by configs that are stored
+ * UNVERSIONED (raw, nested in a larger JSON blob).
+ */
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import {
+  Versioned,
+  assertMigrationChainFromV1,
+  type Migration,
+} from "./config-versioning";
+
+// A v1 config: a single object schema, no migrations.
+const v1Schema = z.object({
+  url: z.string(),
+  method: z.enum(["GET", "POST"]).default("GET"),
+});
+
+const v1Config = new Versioned({ version: 1, schema: v1Schema });
+
+// A v1 -> v2 config that DROPS a removed `sandbox` key, mirroring the
+// real run_script/run_shell migration.
+const v2Schema = z.object({
+  script: z.string(),
+});
+
+const dropSandboxMigration: Migration<Record<string, unknown>, unknown> = {
+  fromVersion: 1,
+  toVersion: 2,
+  description: "Drop removed `sandbox` key",
+  migrate: ({ sandbox: _sandbox, ...rest }) => rest,
+};
+
+const v2Config = new Versioned({
+  version: 2,
+  schema: v2Schema,
+  migrations: [dropSandboxMigration],
+});
+
+describe("parseAssumingV1", () => {
+  it("validates a v1-no-migration config (just validate)", async () => {
+    const result = await v1Config.parseAssumingV1({ url: "https://x.test" });
+    expect(result).toEqual({ url: "https://x.test", method: "GET" });
+  });
+
+  it("runs the migration chain for a v>1 config and drops a removed key", async () => {
+    const result = await v2Config.parseAssumingV1({
+      script: "echo hi",
+      sandbox: "off",
+    });
+    expect(result).toEqual({ script: "echo hi" });
+  });
+
+  it("is idempotent: a fresh config without the removed key is unchanged", async () => {
+    const result = await v2Config.parseAssumingV1({ script: "echo hi" });
+    expect(result).toEqual({ script: "echo hi" });
+  });
+
+  it("strips unknown keys leniently (does NOT reject typos)", async () => {
+    const result = await v1Config.parseAssumingV1({
+      url: "https://x.test",
+      methodd: "GET",
+    });
+    expect(result).toEqual({ url: "https://x.test", method: "GET" });
+    expect(result).not.toHaveProperty("methodd");
+  });
+
+  it("rejects a genuine validation error (missing required field)", async () => {
+    await expect(
+      v1Config.parseAssumingV1({ method: "GET" }),
+    ).rejects.toThrow();
+  });
+});
+
+describe("parseStrictAssumingV1", () => {
+  it("validates a clean v1-no-migration config", async () => {
+    const result = await v1Config.parseStrictAssumingV1({
+      url: "https://x.test",
+    });
+    expect(result).toEqual({ url: "https://x.test", method: "GET" });
+  });
+
+  it("migrates a removed key away, then strict-validates cleanly", async () => {
+    const result = await v2Config.parseStrictAssumingV1({
+      script: "echo hi",
+      sandbox: "off",
+    });
+    expect(result).toEqual({ script: "echo hi" });
+  });
+
+  it("is idempotent for a fresh config without the removed key", async () => {
+    const result = await v2Config.parseStrictAssumingV1({ script: "echo hi" });
+    expect(result).toEqual({ script: "echo hi" });
+  });
+
+  it("rejects a genuine unknown-key typo the migration does NOT account for", async () => {
+    await expect(
+      v1Config.parseStrictAssumingV1({
+        url: "https://x.test",
+        methodd: "GET",
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects an unknown key on the migrated (v2) shape", async () => {
+    await expect(
+      v2Config.parseStrictAssumingV1({ script: "echo hi", typo: 1 }),
+    ).rejects.toThrow();
+  });
+
+  it("falls back to a normal parse for non-object schemas", async () => {
+    const unionConfig = new Versioned({
+      version: 1,
+      schema: z.union([z.object({ a: z.string() }), z.object({ b: z.number() })]),
+    });
+    const result = await unionConfig.parseStrictAssumingV1({ a: "x" });
+    expect(result).toEqual({ a: "x" });
+  });
+});
+
+describe("construction-time migration-chain guard", () => {
+  it("throws for a version>1 config with no migrations", () => {
+    expect(
+      () => new Versioned({ version: 2, schema: v2Schema, migrations: [] }),
+    ).toThrow();
+  });
+
+  it("constructs fine for a version 2 config with a complete v1->v2 chain", () => {
+    expect(
+      () =>
+        new Versioned({
+          version: 2,
+          schema: v2Schema,
+          migrations: [dropSandboxMigration],
+        }),
+    ).not.toThrow();
+  });
+
+  it("constructs fine for a version 1 config with no migrations", () => {
+    expect(() => new Versioned({ version: 1, schema: v1Schema })).not.toThrow();
+  });
+
+  it("throws for a broken chain (gap / non-+1 step)", () => {
+    expect(
+      () =>
+        new Versioned({
+          version: 4,
+          schema: v2Schema,
+          migrations: [
+            { fromVersion: 1, toVersion: 2, description: "a", migrate: (d) => d },
+            { fromVersion: 3, toVersion: 4, description: "c", migrate: (d) => d },
+          ],
+        }),
+    ).toThrow();
+  });
+});
+
+describe("validateMigrationChainFromV1", () => {
+  it("passes for a v1 config with no migrations", () => {
+    expect(v1Config.validateMigrationChainFromV1()).toBeUndefined();
+  });
+
+  it("passes for a v2 config with a complete 1->2 chain", () => {
+    expect(v2Config.validateMigrationChainFromV1()).toBeUndefined();
+  });
+
+  // NOTE: the "missing covering migration" and "gapped chain" cases now
+  // throw at CONSTRUCTION (see the construction-time guard above), so they
+  // can no longer be exercised via a constructed instance. The pure
+  // structural method itself is covered transitively by the guard tests
+  // and by the passing cases below.
+});
+
+describe("assertMigrationChainFromV1", () => {
+  const step = (fromVersion: number, toVersion: number): Migration => ({
+    fromVersion,
+    toVersion,
+    description: `${fromVersion}->${toVersion}`,
+    migrate: (d) => d,
+  });
+
+  it("passes for a v1 config with no migrations", () => {
+    expect(() =>
+      assertMigrationChainFromV1({ version: 1, migrations: [] }),
+    ).not.toThrow();
+  });
+
+  it("passes for a complete contiguous chain (1->2->3)", () => {
+    expect(() =>
+      assertMigrationChainFromV1({
+        version: 3,
+        migrations: [step(2, 3), step(1, 2)],
+      }),
+    ).not.toThrow();
+  });
+
+  it("throws for a version>1 config with no migrations", () => {
+    expect(() =>
+      assertMigrationChainFromV1({ version: 2, migrations: [] }),
+    ).toThrow(/incomplete/);
+  });
+
+  it("throws for a chain that does not reach the target version", () => {
+    expect(() =>
+      assertMigrationChainFromV1({ version: 3, migrations: [step(1, 2)] }),
+    ).toThrow(/incomplete: reaches version 2/);
+  });
+
+  it("throws for a gap in the chain", () => {
+    expect(() =>
+      assertMigrationChainFromV1({
+        version: 4,
+        migrations: [step(1, 2), step(3, 4)],
+      }),
+    ).toThrow(/chain broken: expected migration from version 2/);
+  });
+
+  it("throws for a non-+1 step", () => {
+    expect(() =>
+      assertMigrationChainFromV1({
+        version: 3,
+        migrations: [step(1, 3)],
+      }),
+    ).toThrow(/increment version by 1/);
+  });
+});

package/src/config-versioning.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { extractErrorMessage } from "@checkstack/common";
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Storage Interfaces (simple data shapes for DB/API)
@@ -47,6 +48,73 @@ export interface Migration<TFrom = unknown, TTo = unknown> {
   migrate(data: TFrom): TTo | Promise<TTo>;
 }
 
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Migration Chain Validation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Options for {@link assertMigrationChainFromV1}.
+ */
+export interface AssertMigrationChainOptions {
+  /** Target/current schema version the chain must reach. */
+  version: number;
+  /** The ordered (or unordered) set of migrations covering the chain. */
+  migrations: Migration<unknown, unknown>[];
+}
+
+/**
+ * Standalone, pure structural guard that a migration chain is COMPLETE and
+ * contiguous from version 1 up to the given `version`: every applicable step
+ * increments by exactly 1, there are no gaps, and the chain reaches
+ * `version`. No `migrate()` is ever invoked — this only inspects the
+ * `fromVersion` / `toVersion` discriminators.
+ *
+ * A `version: 1` config with no migrations passes trivially. Any
+ * `version > 1` requires a covering chain; an incomplete chain is a latent
+ * read failure (the read path would only discover it when it first tries to
+ * migrate a genuinely-old stored blob), so callers use this to fail fast at
+ * boot / registration instead.
+ *
+ * This is the single shared implementation behind both {@link Versioned}'s
+ * construction guard and its non-throwing {@link Versioned.validateMigrationChainFromV1}
+ * variant, and is reused by the auth strategy registration guard.
+ *
+ * @throws Error with a descriptive message on the first problem found.
+ */
+export function assertMigrationChainFromV1({
+  version,
+  migrations,
+}: AssertMigrationChainOptions): void {
+  const sorted = migrations.toSorted((a, b) => a.fromVersion - b.fromVersion);
+
+  let expectedVersion = 1;
+  for (const migration of sorted) {
+    if (migration.fromVersion < 1) continue;
+    if (migration.toVersion > version) break;
+
+    if (migration.fromVersion !== expectedVersion) {
+      throw new Error(
+        `Migration chain broken: expected migration from version ${expectedVersion}, ` +
+          `but found migration from version ${migration.fromVersion}`
+      );
+    }
+    if (migration.toVersion !== migration.fromVersion + 1) {
+      throw new Error(
+        `Migration must increment version by 1: migration from ${migration.fromVersion} ` +
+          `to ${migration.toVersion} is invalid`
+      );
+    }
+    expectedVersion = migration.toVersion;
+  }
+
+  if (expectedVersion !== version) {
+    throw new Error(
+      `Migration chain incomplete: reaches version ${expectedVersion}, ` +
+        `but target version is ${version}`
+    );
+  }
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Migration Builder
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -129,6 +197,18 @@ export class Versioned<T> {
     this.version = options.version;
     this.schema = options.schema;
     this._migrations = options.migrations ?? [];
+
+    // Fail fast at construction (i.e. at module import / plugin
+    // registration) if this Versioned's v1->version migration chain is
+    // incomplete or broken. A `version: 1` config with no migrations
+    // passes trivially. Any `version > 1` without a covering chain would
+    // otherwise fail lazily on the first stale `parseAssumingV1` read — we
+    // surface it at boot instead. This single guard covers every Versioned
+    // instance repo-wide.
+    assertMigrationChainFromV1({
+      version: this.version,
+      migrations: this._migrations,
+    });
   }
 
   /**
@@ -177,6 +257,54 @@ export class Versioned<T> {
     return { ...migrated, data: validated };
   }
 
+  /**
+   * Parse raw data that was stored UNVERSIONED, assuming it was written
+   * at version 1.
+   *
+   * Many config blobs predate explicit versioning and live nested in a
+   * larger JSON document (e.g. an automation `definition`) without a
+   * `version` discriminator. Reading them is "assume v1 on read": wrap the
+   * raw value as `{ version: 1, data }`, run the migration chain up to the
+   * current version, then validate.
+   *
+   * For a v1-with-no-migrations config this is just a validate; for a
+   * config whose `version > 1` it runs the full migration chain first, so
+   * removed/renamed fields are migrated away before validation.
+   *
+   * Validation is LENIENT (unknown keys are stripped, not rejected) — use
+   * this on the runtime/read path so a stored config that picked up an
+   * extra key survives schema evolution.
+   *
+   * @throws ZodError on validation failure
+   * @throws Error on migration failure
+   */
+  async parseAssumingV1(rawData: unknown): Promise<T> {
+    return this.parse({ version: 1, data: rawData });
+  }
+
+  /**
+   * Like {@link parseAssumingV1}, but the FINAL validation is STRICT:
+   * unknown keys on a plain-object schema are rejected rather than
+   * stripped.
+   *
+   * Migrate-then-STRICT is the editor/validation path: removed or renamed
+   * fields are migrated away by the chain (so stored configs survive
+   * schema evolution), while genuine typos — keys no migration accounts
+   * for — still surface to the operator.
+   *
+   * Strict handling mirrors the object-vs-non-object split used by the
+   * automation definition validator: only `z.ZodObject` schemas can be
+   * tightened with `.strict()`; unions, records, and primitives fall back
+   * to a normal parse.
+   *
+   * @throws ZodError on validation failure
+   * @throws Error on migration failure
+   */
+  async parseStrictAssumingV1(rawData: unknown): Promise<T> {
+    const migrated = await this.migrateToVersion({ version: 1, data: rawData });
+    return this.strictValidate(migrated.data);
+  }
+
   // ─────────────────────────────────────────────────────────────────────────
   // Data Creation (wrap new data)
   // ─────────────────────────────────────────────────────────────────────────
@@ -214,6 +342,34 @@ export class Versioned<T> {
     return input.version !== this.version;
   }
 
+  /**
+   * Structural check (no `migrate()` invocation) that this config has a
+   * COMPLETE, contiguous migration chain from version 1 to its current
+   * `version`: every step increments by exactly 1 and the chain reaches
+   * `version` with no gaps or detours.
+   *
+   * For a `version: 1` config this is trivially satisfied (no migrations
+   * needed). For any `version > 1` it requires a covering chain — which is
+   * exactly what {@link parseAssumingV1} relies on, so a missing chain is a
+   * latent read failure. Returns the first problem found, or `undefined`
+   * when the chain is complete.
+   *
+   * Intended for a CI contract test that enumerates every registered config
+   * and fails the build if a future `version` bump ships without a covering
+   * migration — zero per-config upkeep.
+   */
+  validateMigrationChainFromV1(): string | undefined {
+    try {
+      assertMigrationChainFromV1({
+        version: this.version,
+        migrations: this._migrations,
+      });
+      return undefined;
+    } catch (error) {
+      return extractErrorMessage(error);
+    }
+  }
+
   /**
    * Validate data without migration (schema.parse wrapper).
    * For data already at current version.
@@ -229,6 +385,22 @@ export class Versioned<T> {
     return this.schema.safeParse(data);
   }
 
+  /**
+   * Validate in STRICT mode: when the schema is a plain object, unknown
+   * keys are rejected; otherwise (unions/records/primitives) fall back to
+   * a normal parse. Used by {@link parseStrictAssumingV1}.
+   */
+  private strictValidate(data: unknown): T {
+    if (this.schema instanceof z.ZodObject) {
+      // `.strict()` only narrows accepted keys; the parsed output shape is
+      // identical to the base object schema's, but its inferred type loses
+      // the `T` brand. The cast restores it without changing runtime
+      // behaviour.
+      return this.schema.strict().parse(data) as T;
+    }
+    return this.schema.parse(data);
+  }
+
   // ─────────────────────────────────────────────────────────────────────────
   // Internal migration logic
   // ─────────────────────────────────────────────────────────────────────────

package/src/core-services.ts

@@ -52,6 +52,20 @@ export const coreServices = {
   ),
   rpc: createServiceRef<RpcService>("core.rpc"),
   rpcClient: createServiceRef<RpcClient>("core.rpcClient"),
+  /**
+   * Factory for an RPC client that authenticates as a specific APPLICATION
+   * (service account), not as the trusted service. The returned client mints a
+   * short-lived, backend-signed app-principal token; the live router resolves
+   * it to an `application` principal subject to the FULL access-rule and
+   * team-scope enforcement (never the service short-circuit). Used by the
+   * automation dispatch engine to run an automation as its configured `runAs`.
+   *
+   * Trusted infra: callable only by backend plugin code. The authority to bind
+   * a given application is gated separately when the automation is saved.
+   */
+  rpcClientAs: createServiceRef<(applicationId: string) => Promise<RpcClient>>(
+    "core.rpcClientAs",
+  ),
   queuePluginRegistry: createServiceRef<QueuePluginRegistry>(
     "core.queuePluginRegistry",
   ),

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

@@ -1,4 +1,12 @@
-import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  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";
@@ -7,6 +15,35 @@ import {
   normaliseUserScript,
   rewriteHelperImports,
 } from "./esm-script-runner";
+import {
+  registerSandboxPolicyProvider,
+  resetSandboxPolicyProvider,
+} from "./script-sandbox/provider";
+import { resolveDefaultSandboxProfile } from "./script-sandbox/policy";
+
+/**
+ * The spawning suites register the shipped default profile as the active
+ * global policy so the runner's behavior is deterministic (rather than failing
+ * closed). The shipped default is now fail-closed (`onUnavailable: "fail"`),
+ * which on a capability-poor CI/dev host (non-root macOS, no bwrap/prlimit)
+ * would refuse EVERY spawn — defeating these runner-behavior tests (env
+ * injection, script execution). So here we register the default profile with
+ * the opt-in `degrade` mode to exercise the spawn path on any host. The
+ * fail-closed default value is asserted in `policy.test.ts`, and the
+ * fail-closed RUNTIME path (refuse + exitCode -1, no spawn) in
+ * `provider.test.ts` and `shell-script-runner.test.ts`.
+ */
+function useDefaultSandboxPolicy(): void {
+  beforeEach(() => {
+    registerSandboxPolicyProvider(async () => ({
+      ...resolveDefaultSandboxProfile(),
+      onUnavailable: "degrade",
+    }));
+  });
+  afterEach(() => {
+    resetSandboxPolicyProvider();
+  });
+}
 
 /**
  * The shared ESM-script runner applies two text transforms to user
@@ -84,8 +121,8 @@ describe("rewriteHelperImports", () => {
 
   it("rewrites a named import from the helper module", () => {
     const out = rewriteHelperImports({
-      userScript: `import { defineHealthCheck } from "@checkstack/healthcheck";`,
-      helperModuleName: "@checkstack/healthcheck",
+      userScript: `import { defineHealthCheck } from "@checkstack/sdk/healthcheck";`,
+      helperModuleName: "@checkstack/sdk/healthcheck",
       helperUrl: HELPER_URL,
     });
     expect(out).toBe(`import { defineHealthCheck } from "${HELPER_URL}";`);
@@ -93,8 +130,8 @@ describe("rewriteHelperImports", () => {
 
   it("works with single-quoted import specs too", () => {
     const out = rewriteHelperImports({
-      userScript: `import { defineHealthCheck } from '@checkstack/healthcheck';`,
-      helperModuleName: "@checkstack/healthcheck",
+      userScript: `import { defineHealthCheck } from '@checkstack/sdk/healthcheck';`,
+      helperModuleName: "@checkstack/sdk/healthcheck",
       helperUrl: HELPER_URL,
     });
     expect(out).toBe(`import { defineHealthCheck } from "${HELPER_URL}";`);
@@ -102,8 +139,8 @@ describe("rewriteHelperImports", () => {
 
   it("rewrites a side-effect import too", () => {
     const out = rewriteHelperImports({
-      userScript: `import "@checkstack/healthcheck";`,
-      helperModuleName: "@checkstack/healthcheck",
+      userScript: `import "@checkstack/sdk/healthcheck";`,
+      helperModuleName: "@checkstack/sdk/healthcheck",
       helperUrl: HELPER_URL,
     });
     expect(out).toBe(`import "${HELPER_URL}";`);
@@ -114,7 +151,7 @@ describe("rewriteHelperImports", () => {
     expect(
       rewriteHelperImports({
         userScript: src,
-        helperModuleName: "@checkstack/healthcheck",
+        helperModuleName: "@checkstack/sdk/healthcheck",
         helperUrl: HELPER_URL,
       }),
     ).toBe(src);
@@ -122,15 +159,15 @@ describe("rewriteHelperImports", () => {
 
   it("rewrites multiple occurrences", () => {
     const src = `
-      import { defineHealthCheck } from "@checkstack/healthcheck";
-      import type { HealthCheckScriptResult } from "@checkstack/healthcheck";
+      import { defineHealthCheck } from "@checkstack/sdk/healthcheck";
+      import type { HealthCheckScriptResult } from "@checkstack/sdk/healthcheck";
     `;
     const out = rewriteHelperImports({
       userScript: src,
-      helperModuleName: "@checkstack/healthcheck",
+      helperModuleName: "@checkstack/sdk/healthcheck",
       helperUrl: HELPER_URL,
     });
-    expect(out.match(/@checkstack\/healthcheck/g)).toBeNull();
+    expect(out.match(/@checkstack\/sdk\/healthcheck/g)).toBeNull();
     expect([...out.matchAll(new RegExp(HELPER_URL, "g"))].length).toBe(2);
   });
 
@@ -138,11 +175,11 @@ describe("rewriteHelperImports", () => {
     // 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");`;
+    const src = `console.log("Look up @checkstack/sdk/healthcheck on npm");`;
     expect(
       rewriteHelperImports({
         userScript: src,
-        helperModuleName: "@checkstack/healthcheck",
+        helperModuleName: "@checkstack/sdk/healthcheck",
         helperUrl: HELPER_URL,
       }),
     ).toBe(src);
@@ -153,8 +190,8 @@ describe("rewriteHelperImports", () => {
     // 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",
+      userScript: `import { defineIntegration } from "@checkstack/sdk/integration";`,
+      helperModuleName: "@checkstack/sdk/integration",
       helperUrl: HELPER_URL,
     });
     expect(out).toBe(`import { defineIntegration } from "${HELPER_URL}";`);
@@ -173,6 +210,7 @@ describe("rewriteHelperImports", () => {
 });
 
 describe("defaultEsmScriptRunner resolutionRoot", () => {
+  useDefaultSandboxPolicy();
   let root: string;
 
   beforeAll(async () => {
@@ -232,6 +270,7 @@ describe("defaultEsmScriptRunner resolutionRoot", () => {
 });
 
 describe("defaultEsmScriptRunner injected env", () => {
+  useDefaultSandboxPolicy();
   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;`,