@checkstack/backend-api 0.20.0 → 0.21.1

package/src/config-versioning.ts

@@ -1,4 +1,6 @@
 import { z } from "zod";
+import { extractErrorMessage } from "@checkstack/common";
+import type { Migration } from "@checkstack/common";
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Storage Interfaces (simple data shapes for DB/API)
@@ -33,18 +35,78 @@ export interface VersionedPluginRecord<T = unknown> extends VersionedRecord<T> {
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 /**
- * Type-safe migration from one data version to another.
- * Used for backward-compatible schema evolution.
+ * The canonical `Migration` definition now lives in `@checkstack/common` so
+ * that low-level packages (`@checkstack/cache-api`, `@checkstack/queue-api`)
+ * can reference it without depending on `backend-api` and creating a
+ * publish-time dependency cycle. Re-exported here for backward compatibility.
  */
-export interface Migration<TFrom = unknown, TTo = unknown> {
-  /** Version number migrating from */
-  fromVersion: number;
-  /** Version number migrating to (must be fromVersion + 1) */
-  toVersion: number;
-  /** Human-readable description of what this migration does */
-  description: string;
-  /** Migration function that transforms old data to new format */
-  migrate(data: TFrom): TTo | Promise<TTo>;
+export type { Migration } from "@checkstack/common";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 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}`
+    );
+  }
 }
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -129,6 +191,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 +251,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 +336,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 +379,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;`,