@checkstack/gitops-backend 0.1.1 → 0.2.0

package/src/secret-resolver.test.ts

@@ -1,11 +1,15 @@
 import { describe, it, expect } from "bun:test";
-import { resolveSecrets } from "./secret-resolver";
+import { z } from "zod";
+import { configString } from "@checkstack/backend-api";
+import { resolveSecretsBySchema } from "./secret-resolver";
 
 const mockSecretStore = {
   resolve: async (name: string): Promise<string> => {
     const secrets: Record<string, string> = {
-      "prod-db-password": "s3cret!",
-      "api-key": "key-12345",
+      DB_PASS: "s3cret!",
+      API_KEY: "key-12345",
+      DB_USER: "admin",
+      DB_HOST: "db.production.internal",
     };
     const value = secrets[name];
     if (!value) throw new Error(`Secret not found: ${name}`);
@@ -13,52 +17,110 @@ const mockSecretStore = {
   },
 };
 
-describe("resolveSecrets", () => {
-  it("resolves a top-level secretRef", async () => {
-    const spec = { password: { secretRef: "prod-db-password" } };
-    const resolved = await resolveSecrets({
-      spec,
+describe("resolveSecretsBySchema", () => {
+  it("resolves a field marked with x-secret", async () => {
+    const schema = z.object({
+      host: z.string(),
+      password: configString({ "x-secret": true }),
+    });
+
+    const { resolved, warnings } = await resolveSecretsBySchema({
+      value: { host: "localhost", password: "${{ secrets.DB_PASS }}" },
+      schema,
       secretStore: mockSecretStore,
     });
-    expect(resolved).toEqual({ password: "s3cret!" });
+
+    expect(resolved).toEqual({ host: "localhost", password: "s3cret!" });
+    expect(warnings).toEqual([]);
   });
 
-  it("leaves plain strings untouched", async () => {
-    const spec = { host: "localhost", port: 5432 };
-    const resolved = await resolveSecrets({
-      spec,
+  it("leaves non-secret fields untouched and emits warnings", async () => {
+    const schema = z.object({
+      description: z.string(),
+      password: configString({ "x-secret": true }),
+    });
+
+    const { resolved, warnings } = await resolveSecretsBySchema({
+      value: {
+        description: "Contains ${{ secrets.DB_PASS }} but should NOT be resolved",
+        password: "${{ secrets.DB_PASS }}",
+      },
+      schema,
       secretStore: mockSecretStore,
     });
-    expect(resolved).toEqual({ host: "localhost", port: 5432 });
+
+    expect(resolved).toEqual({
+      description: "Contains ${{ secrets.DB_PASS }} but should NOT be resolved",
+      password: "s3cret!",
+    });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("description");
+    expect(warnings[0]).toContain("not marked as a secret field");
   });
 
-  it("resolves nested secretRefs", async () => {
-    const spec = {
-      connection: {
-        host: "db.internal",
-        password: { secretRef: "prod-db-password" },
+  it("resolves inline interpolation in secret fields", async () => {
+    const schema = z.object({
+      connectionString: configString({ "x-secret": true }),
+    });
+
+    const { resolved } = await resolveSecretsBySchema({
+      value: {
+        connectionString:
+          "postgres://${{ secrets.DB_USER }}:${{ secrets.DB_PASS }}@${{ secrets.DB_HOST }}/mydb",
       },
-    };
-    const resolved = await resolveSecrets({
-      spec,
+      schema,
       secretStore: mockSecretStore,
     });
+
+    expect(resolved).toEqual({
+      connectionString:
+        "postgres://admin:s3cret!@db.production.internal/mydb",
+    });
+  });
+
+  it("resolves secrets in nested objects", async () => {
+    const schema = z.object({
+      connection: z.object({
+        host: z.string(),
+        password: configString({ "x-secret": true }),
+      }),
+    });
+
+    const { resolved, warnings } = await resolveSecretsBySchema({
+      value: {
+        connection: { host: "db.internal", password: "${{ secrets.DB_PASS }}" },
+      },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
     expect(resolved).toEqual({
       connection: { host: "db.internal", password: "s3cret!" },
     });
+    expect(warnings).toEqual([]);
   });
 
-  it("resolves secretRefs in arrays", async () => {
-    const spec = {
-      credentials: [
-        { name: "db", secret: { secretRef: "prod-db-password" } },
-        { name: "api", secret: { secretRef: "api-key" } },
-      ],
-    };
-    const resolved = await resolveSecrets({
-      spec,
+  it("resolves secrets in arrays of objects", async () => {
+    const schema = z.object({
+      credentials: z.array(
+        z.object({
+          name: z.string(),
+          secret: configString({ "x-secret": true }),
+        }),
+      ),
+    });
+
+    const { resolved } = await resolveSecretsBySchema({
+      value: {
+        credentials: [
+          { name: "db", secret: "${{ secrets.DB_PASS }}" },
+          { name: "api", secret: "${{ secrets.API_KEY }}" },
+        ],
+      },
+      schema,
       secretStore: mockSecretStore,
     });
+
     expect(resolved).toEqual({
       credentials: [
         { name: "db", secret: "s3cret!" },
@@ -67,20 +129,197 @@ describe("resolveSecrets", () => {
     });
   });
 
+  it("handles optional secret fields", async () => {
+    const schema = z.object({
+      password: configString({ "x-secret": true }).optional(),
+    });
+
+    const { resolved } = await resolveSecretsBySchema({
+      value: { password: "${{ secrets.DB_PASS }}" },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    expect(resolved).toEqual({ password: "s3cret!" });
+  });
+
+  it("handles default-wrapped secret fields", async () => {
+    const schema = z.object({
+      password: configString({ "x-secret": true }).default("fallback"),
+    });
+
+    const { resolved } = await resolveSecretsBySchema({
+      value: { password: "${{ secrets.DB_PASS }}" },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    expect(resolved).toEqual({ password: "s3cret!" });
+  });
+
+  it("returns non-secret objects unchanged", async () => {
+    const schema = z.object({
+      host: z.string(),
+      port: z.number(),
+    });
+
+    const { resolved, warnings } = await resolveSecretsBySchema({
+      value: { host: "localhost", port: 5432 },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    expect(resolved).toEqual({ host: "localhost", port: 5432 });
+    expect(warnings).toEqual([]);
+  });
+
+  it("handles null and undefined values gracefully", async () => {
+    const schema = z.object({
+      password: configString({ "x-secret": true }).optional(),
+    });
+
+    const { resolved } = await resolveSecretsBySchema({
+      value: { password: undefined },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    expect(resolved).toEqual({ password: undefined });
+  });
+
   it("throws when a referenced secret is not found", async () => {
-    const spec = { password: { secretRef: "nonexistent" } };
+    const schema = z.object({
+      password: configString({ "x-secret": true }),
+    });
+
     await expect(
-      resolveSecrets({ spec, secretStore: mockSecretStore }),
-    ).rejects.toThrow("Secret not found: nonexistent");
+      resolveSecretsBySchema({
+        value: { password: "${{ secrets.NONEXISTENT }}" },
+        schema,
+        secretStore: mockSecretStore,
+      }),
+    ).rejects.toThrow("Secret not found: NONEXISTENT");
   });
 
-  it("handles null and undefined values gracefully", async () => {
-    const spec = { a: null, b: undefined, c: "value" };
-    const resolved = await resolveSecrets({
-      spec,
+  it("resolves templates with extra whitespace", async () => {
+    const schema = z.object({
+      password: configString({ "x-secret": true }),
+    });
+
+    const { resolved } = await resolveSecretsBySchema({
+      value: { password: "${{  secrets.DB_PASS  }}" },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    expect(resolved).toEqual({ password: "s3cret!" });
+  });
+
+  it("preserves fields not in the schema (extra keys in value)", async () => {
+    const schema = z.object({
+      password: configString({ "x-secret": true }),
+    });
+
+    const { resolved } = await resolveSecretsBySchema({
+      value: {
+        password: "${{ secrets.DB_PASS }}",
+        extraField: "should remain",
+      },
+      schema,
       secretStore: mockSecretStore,
     });
-    expect(resolved.a).toBeNull();
-    expect(resolved.c).toBe("value");
+
+    expect(resolved).toEqual({
+      password: "s3cret!",
+      extraField: "should remain",
+    });
+  });
+
+  it("does not resolve secret templates in secret fields when no template is present", async () => {
+    const schema = z.object({
+      password: configString({ "x-secret": true }),
+    });
+
+    const { resolved } = await resolveSecretsBySchema({
+      value: { password: "plain-password" },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    expect(resolved).toEqual({ password: "plain-password" });
+  });
+
+  // ─── Warning tests ──────────────────────────────────────────────────────
+
+  it("warns for template in nested non-secret field with correct path", async () => {
+    const schema = z.object({
+      connection: z.object({
+        host: z.string(),
+        password: configString({ "x-secret": true }),
+      }),
+    });
+
+    const { resolved, warnings } = await resolveSecretsBySchema({
+      value: {
+        connection: {
+          host: "${{ secrets.DB_HOST }}",
+          password: "${{ secrets.DB_PASS }}",
+        },
+      },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    // Password resolved, host left as-is
+    expect(resolved).toEqual({
+      connection: {
+        host: "${{ secrets.DB_HOST }}",
+        password: "s3cret!",
+      },
+    });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("connection.host");
+  });
+
+  it("warns for template in array element non-secret field with index", async () => {
+    const schema = z.object({
+      items: z.array(
+        z.object({
+          label: z.string(),
+          secret: configString({ "x-secret": true }),
+        }),
+      ),
+    });
+
+    const { warnings } = await resolveSecretsBySchema({
+      value: {
+        items: [
+          { label: "${{ secrets.DB_PASS }}", secret: "${{ secrets.DB_PASS }}" },
+        ],
+      },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("items[0].label");
+  });
+
+  it("emits no warnings when all templates are in secret fields", async () => {
+    const schema = z.object({
+      password: configString({ "x-secret": true }),
+      apiKey: configString({ "x-secret": true }),
+    });
+
+    const { warnings } = await resolveSecretsBySchema({
+      value: {
+        password: "${{ secrets.DB_PASS }}",
+        apiKey: "${{ secrets.API_KEY }}",
+      },
+      schema,
+      secretStore: mockSecretStore,
+    });
+
+    expect(warnings).toEqual([]);
   });
 });

package/src/secret-resolver.ts

@@ -1,4 +1,6 @@
-import { isSecretRef } from "@checkstack/gitops-common";
+import { z } from "zod";
+import { SECRET_TEMPLATE_REGEX } from "@checkstack/gitops-common";
+import { isSecretSchema } from "@checkstack/backend-api";
 
 /**
  * Interface for resolving secret names to their decrypted values.
@@ -8,47 +10,212 @@ export interface SecretStore {
 }
 
 /**
- * Recursively walks a parsed spec object and resolves any `{ secretRef: "name" }`
- * values by looking them up in the secret store.
+ * Result of schema-driven secret resolution.
+ */
+export interface SecretResolutionResult<T> {
+  /** The value with x-secret fields resolved. */
+  resolved: T;
+  /**
+   * Warnings for `${{ secrets.NAME }}` templates found in non-secret fields.
+   * These templates will NOT be resolved — the field must be annotated with
+   * `configString({ "x-secret": true })` for resolution to occur.
+   */
+  warnings: string[];
+}
+
+/**
+ * Schema-driven secret resolver.
  *
- * After resolution, all secretRef objects are replaced with plain strings.
- * This function is called by the reconciliation engine before invoking plugin reconcilers.
+ * Walks a Zod schema to find fields annotated with `configString({ "x-secret": true })`,
+ * then resolves `${{ secrets.NAME }}` templates **only** in those fields.
+ * Non-secret fields are returned as-is, preventing accidental leaks into display fields.
+ *
+ * Templates found in non-secret fields are reported as warnings — the value
+ * is still returned unmodified, but the caller can surface these to the user.
+ *
+ * Supports both full-value templates and inline interpolation:
+ * - `"${{ secrets.DB_PASS }}"` → `"actual-password"`
+ * - `"postgres://user:${{ secrets.PASS }}@host/db"` → `"postgres://user:actual-password@host/db"`
  */
-export async function resolveSecrets(params: {
-  spec: Record<string, unknown>;
+export async function resolveSecretsBySchema(params: {
+  value: unknown;
+  schema: z.ZodTypeAny;
   secretStore: SecretStore;
-}): Promise<Record<string, unknown>> {
-  const { spec, secretStore } = params;
-  return resolveValue(spec, secretStore) as Promise<Record<string, unknown>>;
+}): Promise<SecretResolutionResult<unknown>> {
+  const { value, schema, secretStore } = params;
+  const warnings: string[] = [];
+  const resolved = await walkAndResolve({ value, schema, secretStore, warnings, path: "" });
+  return { resolved, warnings };
 }
 
-async function resolveValue(
-  value: unknown,
-  secretStore: SecretStore,
-): Promise<unknown> {
+// ─── Recursive Walker ──────────────────────────────────────────────────────
+
+async function walkAndResolve(params: {
+  value: unknown;
+  schema: z.ZodTypeAny;
+  secretStore: SecretStore;
+  warnings: string[];
+  path: string;
+}): Promise<unknown> {
+  const { value, secretStore, warnings, path } = params;
+  const schema = unwrapZod(params.schema);
+
   if (value === null || value === undefined) {
     return value;
   }
 
-  // Check if this value is a secretRef object
-  if (isSecretRef(value)) {
-    return secretStore.resolve(value.secretRef);
+  // Leaf node: if this schema is marked x-secret, resolve templates in the string
+  if (isSecretSchema(schema)) {
+    if (typeof value === "string") {
+      return resolveTemplateString({ value, secretStore });
+    }
+    return value;
   }
 
-  // Recurse into arrays
-  if (Array.isArray(value)) {
-    return Promise.all(value.map((item) => resolveValue(item, secretStore)));
+  // Non-secret string leaf: check for unresolved templates and warn
+  if (typeof value === "string" && containsSecretTemplate(value)) {
+    const fieldPath = path || "(root)";
+    warnings.push(
+      `Field "${fieldPath}" contains a secret template but is not marked as a secret field. ` +
+        `Add configString({ "x-secret": true }) to the schema for this field to enable resolution.`,
+    );
+    return value;
   }
 
-  // Recurse into plain objects
-  if (typeof value === "object") {
-    const resolved: Record<string, unknown> = {};
-    for (const [key, val] of Object.entries(value)) {
-      resolved[key] = await resolveValue(val, secretStore);
+  // Object: recurse into each property using the schema's shape
+  if (schema instanceof z.ZodObject && typeof value === "object" && !Array.isArray(value)) {
+    const shape = schema.shape as Record<string, z.ZodTypeAny>;
+    const result: Record<string, unknown> = { ...(value as Record<string, unknown>) };
+
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+      if (key in result) {
+        result[key] = await walkAndResolve({
+          value: result[key],
+          schema: fieldSchema,
+          secretStore,
+          warnings,
+          path: path ? `${path}.${key}` : key,
+        });
+      }
     }
-    return resolved;
+
+    return result;
   }
 
-  // Primitives pass through
+  // Array: recurse into each element using the element schema
+  if (schema instanceof z.ZodArray && Array.isArray(value)) {
+    const elementSchema = schema.element as z.ZodTypeAny;
+    return Promise.all(
+      value.map((item, index) =>
+        walkAndResolve({
+          value: item,
+          schema: elementSchema,
+          secretStore,
+          warnings,
+          path: `${path}[${index}]`,
+        }),
+      ),
+    );
+  }
+
+  // Discriminated union: find the matching variant and recurse
+  if (schema instanceof z.ZodDiscriminatedUnion && typeof value === "object" && value !== null) {
+    const discriminator = (schema.def as { discriminator: string }).discriminator;
+    const discriminatorValue = (value as Record<string, unknown>)[discriminator];
+    const options = schema.options as z.ZodObject<z.ZodRawShape>[];
+    const matchedVariant = options.find((option) => {
+      const discField = option.shape[discriminator];
+      if (discField instanceof z.ZodLiteral) {
+        return discField.value === discriminatorValue;
+      }
+      return false;
+    });
+
+    if (matchedVariant) {
+      return walkAndResolve({ value, schema: matchedVariant, secretStore, warnings, path });
+    }
+  }
+
+  // Union (oneOf/anyOf without discriminator): try each variant
+  if (schema instanceof z.ZodUnion && typeof value === "object" && value !== null) {
+    const options = schema.options as z.ZodTypeAny[];
+    for (const option of options) {
+      const parsed = option.safeParse(value);
+      if (parsed.success) {
+        return walkAndResolve({ value, schema: option, secretStore, warnings, path });
+      }
+    }
+  }
+
+  // No schema match — return value unchanged
   return value;
 }
+
+/**
+ * Quick check whether a string contains any `${{ secrets.NAME }}` pattern.
+ */
+function containsSecretTemplate(value: string): boolean {
+  SECRET_TEMPLATE_REGEX.lastIndex = 0;
+  return SECRET_TEMPLATE_REGEX.test(value);
+}
+
+// ─── Zod Unwrapping ────────────────────────────────────────────────────────
+
+/**
+ * Unwraps Optional, Default, and Nullable wrappers to get the inner schema.
+ */
+function unwrapZod(schema: z.ZodTypeAny): z.ZodTypeAny {
+  let unwrapped = schema;
+
+  if (unwrapped instanceof z.ZodOptional) {
+    unwrapped = unwrapped.unwrap() as z.ZodTypeAny;
+  }
+
+  if (unwrapped instanceof z.ZodDefault) {
+    unwrapped = unwrapped.def.innerType as z.ZodTypeAny;
+  }
+
+  if (unwrapped instanceof z.ZodNullable) {
+    unwrapped = unwrapped.unwrap() as z.ZodTypeAny;
+  }
+
+  return unwrapped;
+}
+
+// ─── Template Resolution ───────────────────────────────────────────────────
+
+/**
+ * Resolves all `${{ secrets.NAME }}` patterns in a string.
+ * Each unique secret name is resolved once (cached per call) to avoid duplicate lookups.
+ */
+async function resolveTemplateString(params: {
+  value: string;
+  secretStore: SecretStore;
+}): Promise<string> {
+  const { value, secretStore } = params;
+
+  // Collect all secret names first
+  const secretNames = new Set<string>();
+  SECRET_TEMPLATE_REGEX.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = SECRET_TEMPLATE_REGEX.exec(value)) !== null) {
+    secretNames.add(match[1]);
+  }
+
+  // No templates found — return as-is
+  if (secretNames.size === 0) {
+    return value;
+  }
+
+  // Resolve all unique secret names
+  const resolvedValues = new Map<string, string>();
+  for (const name of secretNames) {
+    resolvedValues.set(name, await secretStore.resolve(name));
+  }
+
+  // Replace all template expressions with resolved values
+  SECRET_TEMPLATE_REGEX.lastIndex = 0;
+  return value.replaceAll(SECRET_TEMPLATE_REGEX, (_fullMatch, secretName: string) => {
+    return resolvedValues.get(secretName)!;
+  });
+}

package/src/sync/reconciler-delete.test.ts

@@ -42,6 +42,8 @@ describe("Kind delete reconciler wiring", () => {
           error: () => {},
         },
         resolveEntityRef: async () => undefined,
+        resolveSecretsBySchema: async <T>(params: { value: T }): Promise<{ resolved: T; warnings: string[] }> =>
+          ({ resolved: params.value, warnings: [] }),
       },
     });
 
@@ -105,6 +107,8 @@ describe("Kind delete reconciler wiring", () => {
             error: () => {},
           },
           resolveEntityRef: async () => undefined,
+          resolveSecretsBySchema: async <T>(params: { value: T }): Promise<{ resolved: T; warnings: string[] }> =>
+            ({ resolved: params.value, warnings: [] }),
         },
       }),
     ).rejects.toThrow("DB connection failed");