@checkstack/secrets-backend 0.1.0

package/src/secret-resolver.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from "bun:test";
+import { z } from "zod";
+import { configString } from "@checkstack/backend-api";
+import { resolveSecretsBySchema, type SecretStore } from "./secret-resolver";
+
+const mockSecretStore: SecretStore = {
+  resolve: async (name: string): Promise<string> => {
+    const secrets: Record<string, string> = {
+      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}`);
+    return value;
+  },
+};
+
+describe("resolveSecretsBySchema (promoted from gitops)", () => {
+  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({ host: "localhost", password: "s3cret!" });
+    expect(warnings).toEqual([]);
+  });
+
+  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 resolve",
+        password: "${{ secrets.DB_PASS }}",
+      },
+      schema,
+      secretStore: mockSecretStore,
+    });
+    expect(resolved).toEqual({
+      description: "Contains ${{ secrets.DB_PASS }} but should NOT resolve",
+      password: "s3cret!",
+    });
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain("description");
+  });
+
+  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",
+      },
+      schema,
+      secretStore: mockSecretStore,
+    });
+    expect(resolved).toEqual({
+      connectionString: "postgres://admin:s3cret!@db.production.internal/mydb",
+    });
+  });
+
+  it("resolves secrets in nested objects and arrays", 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!" },
+        { name: "api", secret: "key-12345" },
+      ],
+    });
+  });
+
+  it("throws when a referenced secret is not found", async () => {
+    const schema = z.object({
+      password: configString({ "x-secret": true }),
+    });
+    await expect(
+      resolveSecretsBySchema({
+        value: { password: "${{ secrets.NONEXISTENT }}" },
+        schema,
+        secretStore: mockSecretStore,
+      }),
+    ).rejects.toThrow("Secret not found: NONEXISTENT");
+  });
+});

package/src/secret-resolver.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+import { SECRET_TEMPLATE_REGEX } from "@checkstack/secrets-common";
+import { isSecretSchema } from "@checkstack/backend-api";
+
+/**
+ * Interface for resolving secret names to their decrypted values.
+ * Promoted out of `@checkstack/gitops-backend`.
+ */
+export interface SecretStore {
+  resolve: (name: string) => Promise<string>;
+}
+
+/**
+ * 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 are NOT resolved — the field must be
+   * annotated with `configString({ "x-secret": true })` for resolution.
+   */
+  warnings: string[];
+}
+
+/**
+ * Schema-driven secret resolver.
+ *
+ * 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 in non-secret fields are reported as warnings.
+ *
+ * Supports full-value templates and inline interpolation:
+ * - `"${{ secrets.DB_PASS }}"` → `"actual-password"`
+ * - `"postgres://u:${{ secrets.PASS }}@host/db"` → interpolated
+ */
+export async function resolveSecretsBySchema<T = unknown>(params: {
+  value: T;
+  schema: z.ZodTypeAny;
+  secretStore: SecretStore;
+}): Promise<SecretResolutionResult<T>> {
+  const { value, schema, secretStore } = params;
+  const warnings: string[] = [];
+  const resolved = await walkAndResolve({
+    value,
+    schema,
+    secretStore,
+    warnings,
+    path: "",
+  });
+  return { resolved: resolved as T, warnings };
+}
+
+// ─── 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;
+  }
+
+  // Leaf node: if this schema is marked x-secret, resolve templates.
+  if (isSecretSchema(schema)) {
+    if (typeof value === "string") {
+      return resolveTemplateString({ value, secretStore });
+    }
+    return value;
+  }
+
+  // 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;
+  }
+
+  // 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 result;
+  }
+
+  // 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;
+
+  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]);
+  }
+
+  if (secretNames.size === 0) {
+    return value;
+  }
+
+  const resolvedValues = new Map<string, string>();
+  for (const name of secretNames) {
+    resolvedValues.set(name, await secretStore.resolve(name));
+  }
+
+  SECRET_TEMPLATE_REGEX.lastIndex = 0;
+  return value.replaceAll(
+    SECRET_TEMPLATE_REGEX,
+    (_fullMatch, secretName: string) => resolvedValues.get(secretName)!,
+  );
+}

package/src/walk-secret-fields.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { isSecretSchema } from "@checkstack/backend-api";
+
+/**
+ * Generic schema-driven walk over `x-secret`-annotated string fields.
+ *
+ * This is the shared machinery behind both the runtime secret resolution
+ * (`resolveSecretsBySchema`) and the connection-credential consolidation
+ * (extract inline values to internal secrets / inflate references). It
+ * walks a value against its Zod schema exactly like the resolver does
+ * (objects, arrays, optional/default/nullable, discriminated + plain
+ * unions) and invokes `visit` for every `x-secret` STRING leaf, replacing
+ * that leaf with whatever `visit` returns.
+ *
+ * `visit` is async and receives the field path (for diagnostics) and the
+ * current string value. Non-secret fields are returned unchanged — so this
+ * never touches non-credential config, which is the whole point of acting
+ * only on `x-secret` fields.
+ */
+export async function walkSecretFields(params: {
+  value: unknown;
+  schema: z.ZodTypeAny;
+  visit: (input: { path: string; value: string }) => Promise<string>;
+}): Promise<unknown> {
+  return walk({
+    value: params.value,
+    schema: params.schema,
+    visit: params.visit,
+    path: "",
+  });
+}
+
+async function walk(params: {
+  value: unknown;
+  schema: z.ZodTypeAny;
+  visit: (input: { path: string; value: string }) => Promise<string>;
+  path: string;
+}): Promise<unknown> {
+  const { value, visit, path } = params;
+  const schema = unwrapZod(params.schema);
+
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // x-secret string leaf: hand it to the visitor.
+  if (isSecretSchema(schema)) {
+    if (typeof value === "string") {
+      return visit({ path: path || "(root)", value });
+    }
+    return value;
+  }
+
+  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 walk({
+          value: result[key],
+          schema: fieldSchema,
+          visit,
+          path: path ? `${path}.${key}` : key,
+        });
+      }
+    }
+    return result;
+  }
+
+  if (schema instanceof z.ZodArray && Array.isArray(value)) {
+    const elementSchema = schema.element as z.ZodTypeAny;
+    return Promise.all(
+      value.map((item, index) =>
+        walk({
+          value: item,
+          schema: elementSchema,
+          visit,
+          path: `${path}[${index}]`,
+        }),
+      ),
+    );
+  }
+
+  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 matched = options.find((option) => {
+      const discField = option.shape[discriminator];
+      return discField instanceof z.ZodLiteral
+        ? discField.value === discriminatorValue
+        : false;
+    });
+    if (matched) {
+      return walk({ value, schema: matched, visit, path });
+    }
+  }
+
+  if (
+    schema instanceof z.ZodUnion &&
+    typeof value === "object" &&
+    value !== null
+  ) {
+    const options = schema.options as z.ZodTypeAny[];
+    for (const option of options) {
+      if (option.safeParse(value).success) {
+        return walk({ value, schema: option, visit, path });
+      }
+    }
+  }
+
+  return value;
+}
+
+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;
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../backend"
+    },
+    {
+      "path": "../backend-api"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../dev-server"
+    },
+    {
+      "path": "../drizzle-helper"
+    },
+    {
+      "path": "../secrets-common"
+    },
+    {
+      "path": "../test-utils-backend"
+    }
+  ]
+}