@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/dispatch/render.test.ts

@@ -53,6 +53,40 @@ describe("renderConfig", () => {
     expect(out).toEqual({ ts: "const x = {{ trigger.payload.title }};" });
   });
 
+  it("leaves x-secret-env fields verbatim so ${{ secrets.NAME }} survives", () => {
+    // The secret syntax embeds `{{ secrets.NAME }}`; without the skip the
+    // engine would evaluate it (no `secrets` in scope) and collapse the value
+    // to "$", failing config validation. See the secretEnv dispatch bug.
+    const out = renderConfig({
+      config: {
+        secretEnv: { secret: "${{ secrets.SECRET }}" },
+        message: "hi {{ trigger.payload.title }}",
+      },
+      jsonSchema: {
+        properties: {
+          secretEnv: { "x-secret-env": true },
+          message: { type: "string" },
+        },
+      },
+      context,
+      filters,
+    });
+    expect(out).toEqual({
+      secretEnv: { secret: "${{ secrets.SECRET }}" },
+      message: "hi Outage",
+    });
+  });
+
+  it("leaves a single x-secret field verbatim", () => {
+    const out = renderConfig({
+      config: { token: "${{ secrets.API_TOKEN }}" },
+      jsonSchema: { properties: { token: { "x-secret": true } } },
+      context,
+      filters,
+    });
+    expect(out).toEqual({ token: "${{ secrets.API_TOKEN }}" });
+  });
+
   it("falls back to plain rendering when no schema is supplied", () => {
     const out = renderConfig({
       config: { a: "{{ trigger.payload.title }}" },

package/src/dispatch/render.ts

@@ -47,15 +47,33 @@ function hasCodeEditorType(propSchema: unknown): boolean {
 }
 
 /**
- * Render an action's top-level `config`, skipping native-code fields.
+ * True for a secret-bearing field: a single `${{ secrets.NAME }}` reference
+ * (`x-secret`) or a secret→env mapping whose values are such references
+ * (`x-secret-env`). These MUST NOT be template-rendered: the secret syntax
+ * `${{ secrets.NAME }}` embeds `{{ … }}`, so the `{{ secrets.NAME }}` inside
+ * collides with automation interpolation and the engine would evaluate it
+ * (against a scope with no `secrets`), collapsing the value to `$` before the
+ * secret resolver ever runs. Passing these fields through verbatim keeps the
+ * reference intact for resolution at run/test time.
+ */
+function hasSecretType(propSchema: unknown): boolean {
+  const rec = asRecord(propSchema);
+  return rec["x-secret"] === true || rec["x-secret-env"] === true;
+}
+
+/**
+ * Render an action's top-level `config`, skipping native-code and secret
+ * fields.
  *
- * Identical to {@link renderValue} for every field EXCEPT those whose
- * JSON schema declares an `x-editor-types` of `shell` / `typescript` /
- * `javascript`: those are returned verbatim so any `{{ }}` stays literal.
- * This removes the deprecated "templates inside a code field" path so it
- * can't be used by accident — code fields get run data via `context` /
- * env vars instead. Falls back to {@link renderValue} when the config
- * isn't a plain object or no schema is available.
+ * Identical to {@link renderValue} for every field EXCEPT those whose JSON
+ * schema declares an `x-editor-types` of `shell` / `typescript` /
+ * `javascript` (code fields), or `x-secret` / `x-secret-env` (secret fields):
+ * those are returned verbatim. Code fields keep any `{{ }}` literal (they get
+ * run data via `context` / env vars). Secret fields keep their
+ * `${{ secrets.NAME }}` reference intact for the secret resolver — rendering
+ * them would evaluate the embedded `{{ secrets.NAME }}` and destroy the
+ * reference. Falls back to {@link renderValue} when the config isn't a plain
+ * object or no schema is available.
  */
 export function renderConfig(args: {
   config: unknown;
@@ -70,9 +88,11 @@ export function renderConfig(args: {
   const properties = asRecord(jsonSchema?.["properties"]);
   const out: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(asRecord(config))) {
-    out[key] = hasCodeEditorType(properties[key])
-      ? value
-      : renderValue(value, context, filters);
+    const propSchema = properties[key];
+    out[key] =
+      hasCodeEditorType(propSchema) || hasSecretType(propSchema)
+        ? value
+        : renderValue(value, context, filters);
   }
   return out;
 }

package/src/dispatch/reseed-run-secrets.ts

@@ -0,0 +1,230 @@
+import { createServiceRef, type ServiceRef } from "@checkstack/backend-api";
+import { extractErrorMessage } from "@checkstack/common";
+import type { AutomationDefinition, Action } from "@checkstack/automation-common";
+
+import type { RunSecretRegistry } from "./run-secret-registry";
+
+/**
+ * Cross-pod mask re-seeding for resume / stalled-recovery.
+ *
+ * The run-wide masking registry (see {@link RunSecretRegistry}) is
+ * IN-MEMORY and per-process: it only holds the secret values a run resolved
+ * on THIS pod. Capture happens lazily, as actions resolve secrets through
+ * the wrapped `getService`.
+ *
+ * That breaks across pods. When pod A resolves a connection credential and
+ * the run SUSPENDS (`wait_for_trigger` / `delay` / `wait_until`), and pod B
+ * later resumes that run with a FRESH, empty registry, every masking choke
+ * point on pod B (step output, run error, scope snapshot, artifact data)
+ * runs against an EMPTY mask set. Any persisted value that still contains
+ * pod-A's resolved secret — e.g. an error string, a scope variable carried
+ * over the suspension, or an artifact echoing a credential — would be
+ * written UNMASKED, leaking it to `getRunScopeForReplay` and the run-detail
+ * UI. This is the deferred "L2 cross-pod masking" gap.
+ *
+ * The fix: BEFORE pod B walks/persists anything, RE-SEED its registry by
+ * re-resolving the automation's DECLARED secret refs — the `secretEnv`
+ * mappings and the `connectionId` references the definition uses — through
+ * the run's already-wrapped `getService`. The wrapper auto-registers every
+ * resolved value, so pod B re-populates exactly the least-privilege mask
+ * set the run is allowed to see (Jenkins-style, by-value). Re-resolving is
+ * the SAME set the run resolves during normal execution, so it grants no
+ * extra access.
+ *
+ * Best-effort by construction: a declared secret that no longer resolves
+ * (rotated / deleted) simply isn't added to the mask set — the run would
+ * have failed re-resolving it during the walk anyway. A resolution failure
+ * here must never abort the resume, so each ref is resolved independently
+ * and failures are swallowed (the engine surfaces a genuinely-missing
+ * secret when the action re-runs).
+ */
+
+/** Shapes of the two value-returning services we re-resolve through. */
+interface ResolverLike {
+  resolveForRun(input: { secretEnv: Record<string, string> }): Promise<{
+    env: Record<string, string>;
+    masking: unknown;
+  }>;
+}
+interface ConnectionStoreLike {
+  getConnectionWithCredentials(
+    connectionId: string,
+  ): Promise<{ config: Record<string, unknown> } | undefined>;
+}
+
+function hasResolveForRun(s: unknown): s is ResolverLike {
+  return (
+    typeof s === "object" &&
+    s !== null &&
+    typeof (s as ResolverLike).resolveForRun === "function"
+  );
+}
+function hasConnectionCredentials(s: unknown): s is ConnectionStoreLike {
+  return (
+    typeof s === "object" &&
+    s !== null &&
+    typeof (s as ConnectionStoreLike).getConnectionWithCredentials ===
+      "function"
+  );
+}
+
+/** The declared secret references found by walking a definition's actions. */
+interface DeclaredSecretRefs {
+  /** Distinct `secretEnv` mappings (`{ ENV: "${{ secrets.NAME }}" }`). */
+  secretEnvMaps: Record<string, string>[];
+  /** Distinct, literal `connectionId` values referenced by action configs. */
+  connectionIds: Set<string>;
+}
+
+/**
+ * Collect every `secretEnv` map and literal `connectionId` declared in an
+ * automation's action configs, walking the full nested action tree
+ * (choose / parallel / repeat / sequence). Templated connection ids (those
+ * containing a `${{ … }}` expression) are skipped — they can only be
+ * resolved against live scope, and the action that uses them re-registers
+ * its credential when it re-runs.
+ */
+export function collectDeclaredSecretRefs(
+  definition: AutomationDefinition,
+): DeclaredSecretRefs {
+  const secretEnvMaps: Record<string, string>[] = [];
+  const connectionIds = new Set<string>();
+
+  const visitConfig = (config: Record<string, unknown>): void => {
+    const secretEnv = config.secretEnv;
+    if (isStringRecord(secretEnv) && Object.keys(secretEnv).length > 0) {
+      secretEnvMaps.push(secretEnv);
+    }
+    const connectionId = config.connectionId;
+    if (
+      typeof connectionId === "string" &&
+      connectionId.length > 0 &&
+      !connectionId.includes("${{")
+    ) {
+      connectionIds.add(connectionId);
+    }
+  };
+
+  const visit = (action: Action): void => {
+    if ("action" in action && isPlainObject(action.config)) {
+      visitConfig(action.config);
+    }
+    if ("choose" in action) {
+      for (const branch of action.choose) visitAll(branch.sequence);
+      if (action.else) visitAll(action.else);
+    }
+    if ("parallel" in action) visitAll(action.parallel);
+    if ("repeat" in action) visitAll(action.repeat.sequence);
+    if ("sequence" in action) visitAll(action.sequence);
+  };
+
+  const visitAll = (actions: ReadonlyArray<Action>): void => {
+    for (const action of actions) visit(action);
+  };
+
+  visitAll(definition.actions);
+  return { secretEnvMaps, connectionIds };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  return (
+    isPlainObject(value) &&
+    Object.values(value).every((v) => typeof v === "string")
+  );
+}
+
+export interface ReseedRunSecretRegistryArgs {
+  /**
+   * The run's ALREADY-WRAPPED `getService` (the same one the engine threads
+   * through dispatch). Resolving the secret resolver / connection store
+   * through it auto-registers every resolved value into the run's mask set.
+   */
+  getService: <T>(ref: ServiceRef<T>) => Promise<T>;
+  registry: RunSecretRegistry;
+  runId: string;
+  definition: AutomationDefinition;
+  /** Service-ref id of the secret resolver (`secretResolverRef.id`). */
+  resolverRefId: string;
+  /** Service-ref id of the connection store (`connectionStoreRef.id`). */
+  connectionStoreRefId: string;
+  logger?: { debug(msg: string): void; warn(msg: string): void };
+}
+
+/**
+ * Re-resolve an automation's declared secret refs through the run's wrapped
+ * `getService`, re-populating the run's in-memory mask set on the resuming
+ * pod. Call this on `resumeRun` / `recoverStalledRun` BEFORE walking the
+ * tree, so the masking choke points have the full mask set on the new pod.
+ */
+export async function reseedRunSecretRegistry(
+  args: ReseedRunSecretRegistryArgs,
+): Promise<void> {
+  const { secretEnvMaps, connectionIds } = collectDeclaredSecretRefs(
+    args.definition,
+  );
+  if (secretEnvMaps.length === 0 && connectionIds.size === 0) return;
+
+  // Resolve the two services once through the wrapped getService. The
+  // wrapper returns the value-registering proxies, so the calls below feed
+  // the run's mask set.
+  let resolver: ResolverLike | undefined;
+  let connectionStore: ConnectionStoreLike | undefined;
+
+  if (secretEnvMaps.length > 0) {
+    try {
+      const svc = await args.getService(
+        createServiceRef<unknown>(args.resolverRefId),
+      );
+      if (hasResolveForRun(svc)) resolver = svc;
+    } catch (error) {
+      args.logger?.warn(
+        `reseed: could not resolve secret resolver for run ${args.runId}: ${extractErrorMessage(error)}`,
+      );
+    }
+  }
+  if (connectionIds.size > 0) {
+    try {
+      const svc = await args.getService(
+        createServiceRef<unknown>(args.connectionStoreRefId),
+      );
+      if (hasConnectionCredentials(svc)) connectionStore = svc;
+    } catch (error) {
+      args.logger?.warn(
+        `reseed: could not resolve connection store for run ${args.runId}: ${extractErrorMessage(error)}`,
+      );
+    }
+  }
+
+  if (resolver) {
+    for (const secretEnv of secretEnvMaps) {
+      try {
+        // The wrapped resolver registers every resolved value as a side
+        // effect; we don't need the returned env.
+        await resolver.resolveForRun({ secretEnv });
+      } catch (error) {
+        // A rotated/missing secret would fail the action's own re-run; here
+        // we just skip adding it to the mask set.
+        args.logger?.debug(
+          `reseed: secretEnv re-resolve skipped for run ${args.runId}: ${extractErrorMessage(error)}`,
+        );
+      }
+    }
+  }
+
+  if (connectionStore) {
+    for (const connectionId of connectionIds) {
+      try {
+        await connectionStore.getConnectionWithCredentials(connectionId);
+      } catch (error) {
+        args.logger?.debug(
+          `reseed: connection re-resolve skipped for run ${args.runId} (${connectionId}): ${extractErrorMessage(error)}`,
+        );
+      }
+    }
+  }
+}
+

package/src/dispatch/run-secret-registry.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect } from "bun:test";
+import type { ServiceRef } from "@checkstack/backend-api";
+import {
+  createRunSecretRegistry,
+  wrapGetServiceForRun,
+} from "./run-secret-registry";
+
+const RUN = "run-1";
+
+describe("RunSecretRegistry", () => {
+  it("masks registered values out of text + deep payloads for a run", () => {
+    const reg = createRunSecretRegistry();
+    reg.register(RUN, ["sk-live-9999", "db-pass-7777"]);
+    expect(reg.maskText(RUN, "auth=sk-live-9999")).toBe("auth=****");
+    expect(reg.maskDeep(RUN, { token: "db-pass-7777", n: 1 })).toEqual({
+      token: "****",
+      n: 1,
+    });
+  });
+
+  it("is least-privilege: a value NOT registered for the run is not masked", () => {
+    const reg = createRunSecretRegistry();
+    reg.register(RUN, ["resolved-in-run"]);
+    // A different secret that this run never resolved must pass through.
+    expect(reg.maskText(RUN, "x=some-other-secret")).toBe("x=some-other-secret");
+    // And a value registered for a DIFFERENT run doesn't leak across.
+    reg.register("run-2", ["run-2-secret"]);
+    expect(reg.maskText(RUN, "y=run-2-secret")).toBe("y=run-2-secret");
+  });
+
+  it("masks step output via the stepId link", () => {
+    const reg = createRunSecretRegistry();
+    reg.register(RUN, ["step-secret-abc"]);
+    reg.linkStep("step-1", RUN);
+    expect(reg.maskTextForStep("step-1", "v=step-secret-abc")).toBe("v=****");
+    expect(reg.maskDeepForStep("step-1", { v: "step-secret-abc" })).toEqual({
+      v: "****",
+    });
+    // An unknown step is a no-op (no run link).
+    expect(reg.maskTextForStep("unknown", "v=step-secret-abc")).toBe(
+      "v=step-secret-abc",
+    );
+  });
+
+  it("drop() clears a run's values + step links (memory-only)", () => {
+    const reg = createRunSecretRegistry();
+    reg.register(RUN, ["gone-after-drop"]);
+    reg.linkStep("step-1", RUN);
+    reg.drop(RUN);
+    expect(reg.maskText(RUN, "x=gone-after-drop")).toBe("x=gone-after-drop");
+    expect(reg.maskTextForStep("step-1", "x=gone-after-drop")).toBe(
+      "x=gone-after-drop",
+    );
+  });
+});
+
+describe("wrapGetServiceForRun", () => {
+  function ref(id: string): ServiceRef<unknown> {
+    return { id, T: undefined, toString: () => id };
+  }
+
+  interface ResolverShape {
+    resolveSecret(input: { name: string }): Promise<string>;
+    resolveForRun(input: {
+      secretEnv: Record<string, string>;
+    }): Promise<{ env: Record<string, string>; masking: unknown }>;
+    resolveBySchema(input: {
+      value: unknown;
+      schema: unknown;
+    }): Promise<{ resolved: unknown; warnings: string[] }>;
+  }
+  interface StoreShape {
+    getConnectionWithCredentials(
+      id: string,
+    ): Promise<{ config: Record<string, unknown> } | undefined>;
+    listConnections(): Promise<unknown[]>;
+  }
+
+  /** A getService that returns `svc` for any ref. */
+  function constGetService<S>(svc: S): <T>(r: ServiceRef<T>) => Promise<T> {
+    return <T>(_r: ServiceRef<T>) => Promise.resolve(svc as unknown as T);
+  }
+
+  it("registers values resolved via the resolver service (resolveForRun + resolveSecret)", async () => {
+    const reg = createRunSecretRegistry();
+    const resolver: ResolverShape = {
+      resolveSecret: async () => "single-secret",
+      resolveForRun: async () => ({
+        env: { A: "env-secret-1", B: "env-secret-2" },
+        masking: {},
+      }),
+      resolveBySchema: async () => ({
+        resolved: { password: "schema-secret" },
+        warnings: [],
+      }),
+    };
+    const wrapped = wrapGetServiceForRun({
+      getService: constGetService(resolver),
+      runId: RUN,
+      registry: reg,
+      resolverRefId: "secrets.resolver",
+      connectionStoreRefId: "integration.connectionStore",
+    });
+    const svc = await wrapped(ref("secrets.resolver") as ServiceRef<ResolverShape>);
+    await svc.resolveForRun({ secretEnv: {} });
+    await svc.resolveSecret({ name: "x" });
+    await svc.resolveBySchema({ value: {}, schema: {} });
+    // Every resolved value is now in the run's mask set.
+    expect(reg.maskText(RUN, "env-secret-1 env-secret-2 single-secret schema-secret")).toBe(
+      "**** **** **** ****",
+    );
+  });
+
+  it("L3: forwards a non-intercepted resolver method untouched (Proxy + Reflect.get)", async () => {
+    const reg = createRunSecretRegistry();
+    // Resolver carries an extra method the wrapper does NOT intercept; a
+    // hand-built literal would have dropped it.
+    const resolver: ResolverShape & {
+      describeNamedSecret: (name: string) => string;
+    } = {
+      resolveSecret: async (_input: { name: string }) =>
+        "intercepted-secret-value",
+      resolveForRun: async (_input: { secretEnv: Record<string, string> }) => ({
+        env: {},
+        masking: {},
+      }),
+      resolveBySchema: async (_input: { value: unknown; schema: unknown }) => ({
+        resolved: {},
+        warnings: [],
+      }),
+      // Not one of the three value-returning methods — must survive.
+      describeNamedSecret: (name: string) => `meta:${name}`,
+    };
+    const wrapped = wrapGetServiceForRun({
+      getService: constGetService(resolver),
+      runId: RUN,
+      registry: reg,
+      resolverRefId: "secrets.resolver",
+      connectionStoreRefId: "integration.connectionStore",
+    });
+    const svc = (await wrapped(
+      ref("secrets.resolver") as ServiceRef<typeof resolver>,
+    )) as typeof resolver;
+    // The non-intercepted method is forwarded via Reflect.get, not dropped.
+    expect(typeof svc.describeNamedSecret).toBe("function");
+    expect(svc.describeNamedSecret("API")).toBe("meta:API");
+    // And the intercepted method still registers its resolved value.
+    await svc.resolveSecret({ name: "x" });
+    expect(reg.maskText(RUN, "v=intercepted-secret-value")).toBe("v=****");
+  });
+
+  it("registers values resolved via the connection store credentials", async () => {
+    const reg = createRunSecretRegistry();
+    const store: StoreShape = {
+      getConnectionWithCredentials: async () => ({
+        config: { baseUrl: "https://x", apiToken: "conn-cred-secret" },
+      }),
+      // an unrelated passthrough method
+      listConnections: async () => [],
+    };
+    const wrapped = wrapGetServiceForRun({
+      getService: constGetService(store),
+      runId: RUN,
+      registry: reg,
+      resolverRefId: "secrets.resolver",
+      connectionStoreRefId: "integration.connectionStore",
+    });
+    const svc = await wrapped(
+      ref("integration.connectionStore") as ServiceRef<StoreShape>,
+    );
+    await svc.getConnectionWithCredentials("c1");
+    expect(reg.maskText(RUN, "token=conn-cred-secret")).toBe("token=****");
+    // Passthrough methods still work.
+    expect(await svc.listConnections()).toEqual([]);
+  });
+
+  it("passes other services through untouched", async () => {
+    const reg = createRunSecretRegistry();
+    const other = { foo: () => "bar" };
+    const wrapped = wrapGetServiceForRun({
+      getService: constGetService(other),
+      runId: RUN,
+      registry: reg,
+      resolverRefId: "secrets.resolver",
+      connectionStoreRefId: "integration.connectionStore",
+    });
+    expect(await wrapped(ref("some.other.service"))).toBe(other);
+  });
+});