@checkstack/gitops-backend 0.3.7 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # @checkstack/gitops-backend
 
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [a57f7db]
+  - @checkstack/backend-api@0.20.0
+  - @checkstack/secrets-backend@0.1.1
+  - @checkstack/command-backend@0.1.33
+  - @checkstack/queue-api@0.3.8
+
+## 0.4.0
+
+### Minor Changes
+
+- b995afb: Surface per-variant config documentation for the `Automation` GitOps kind.
+
+  The GitOps editor and Kind Registry Browser now show the right config schema
+  for each automation trigger and provider action when authoring an
+  `Automation` YAML, mirroring how the `Healthcheck` kind documents its
+  strategy/collector configs:
+
+  - `triggers[].config` — one entry per registered trigger that declares a
+    `configSchema`, conditioned on the chosen `triggers[].event`.
+  - `actions[].config` — one entry per registered provider action,
+    conditioned on the chosen `actions[].action`.
+
+  New plugin-author contract on the entity kind registry:
+
+  - `@checkstack/gitops-common` / `@checkstack/gitops-backend`: add
+    `EntityKindRegistry.registerSpecSchemaDocumentationProvider(provider)`. The
+    provider is a thunk invoked on every `describeKinds()` (i.e. each time the
+    kind-browser RPC is queried), so the docs it returns reflect the current
+    state of whatever it reads — order-independent.
+
+  Why a lazy provider (and not the existing eager
+  `registerSpecSchemaDocumentation`): unlike Healthcheck, whose
+  strategy/collector registries are core services fully populated before any
+  plugin's `afterPluginsReady`, the automation trigger/action registries are
+  filled by other plugins across their `init` / `afterPluginsReady` phases with
+  no guaranteed ordering. Several plugins (catalog/maintenance/notification)
+  register their provider actions in their own `afterPluginsReady`, so the
+  previous one-shot eager registration snapshotted a half-populated (often
+  empty) registry and the Automation kind's "Additional Schemas" came up empty.
+  automation-backend now registers a provider instead, so trigger/action config
+  docs always reflect the fully-populated registries.
+
+  Documentation-only surface; no runtime reconcile behaviour changes.
+
+- 270ef29: Add the Secrets platform (Phase 1): a central, plugin-agnostic secret manager with a pluggable backend extension point, a cross-plugin resolver service, and a universal Jenkins-style masking layer.
+
+  - New packages: `secrets-common` (schemas, contract, `secrets.read`/`secrets.manage`, masking utils), `secrets-backend` (`SecretBackend` extension point, `secretResolverRef`/`secretAdminRef` services, run-scoped masking context, RPC router), `secrets-backend-local` (default AES-256-GCM backend, owns the `secrets` table promoted from gitops), `secrets-frontend` (admin Settings page).
+  - Resolution machinery (`resolveSecretsBySchema`, `SecretStore`, `${{ secrets.NAME }}` / `x-secret`) is promoted out of `gitops-backend` into `secrets-backend`. GitOps now resolves and manages secrets through the platform's service refs (single source of truth); its secret table is migrated without loss.
+  - Universal masking seam wired at the central script-output boundaries: automation `run_script` / `run_shell` artifacts and the in-UI test panel redact run-scoped secret values from `result`/`stdout`/`stderr`/`error` before persist/return. Phase 1 resolves no run-scoped secrets yet, so masking is a no-op until Phase 2; the seam guarantees the boundary exists.
+  - No endpoint returns a secret value to a browser: DTOs expose only name/metadata/`hasValue`.
+
+  BREAKING CHANGES: `gitops-backend` now depends on `secrets-backend` and resolves/manages secrets through it. The `secrets` table is owned by `secrets-backend-local`; the gitops `secrets` table is retained as a migration source but is no longer the source of truth.
+
+### Patch Changes
+
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+  - @checkstack/backend-api@0.19.0
+  - @checkstack/gitops-common@0.5.0
+  - @checkstack/secrets-backend@0.1.0
+  - @checkstack/command-backend@0.1.32
+  - @checkstack/queue-api@0.3.7
+
 ## 0.3.7
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/gitops-backend",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,11 +14,12 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.17.1",
-    "@checkstack/gitops-common": "0.4.1",
-    "@checkstack/common": "0.11.0",
-    "@checkstack/command-backend": "0.1.30",
-    "@checkstack/queue-api": "0.3.5",
+    "@checkstack/backend-api": "0.18.0",
+    "@checkstack/gitops-common": "0.4.2",
+    "@checkstack/common": "0.12.0",
+    "@checkstack/command-backend": "0.1.31",
+    "@checkstack/secrets-backend": "0.0.1",
+    "@checkstack/queue-api": "0.3.6",
     "@orpc/server": "^1.13.2",
     "drizzle-orm": "^0.45.0",
     "minimatch": "^10.0.0",
@@ -28,7 +29,7 @@
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.3.3",
+    "@checkstack/scripts": "0.3.4",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.3.5",
     "@types/node": "^20.0.0",

package/src/index.ts

@@ -17,9 +17,8 @@ import type {
 import { createEntityKindRegistry } from "./kind-registry";
 import { createGitOpsRouter } from "./router";
 import { setupSyncWorker } from "./sync/sync-worker";
-import { decrypt } from "@checkstack/backend-api";
+import { secretResolverRef, secretAdminRef } from "@checkstack/secrets-backend";
 import * as schema from "./schema";
-import { eq } from "drizzle-orm";
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Extension Points
@@ -75,6 +74,9 @@ export default createBackendPlugin({
       registerSpecSchemaDocumentation(params) {
         kindRegistry.registerSpecSchemaDocumentation(params);
       },
+      registerSpecSchemaDocumentationProvider(provider) {
+        kindRegistry.registerSpecSchemaDocumentationProvider(provider);
+      },
     });
 
     env.registerInit({
@@ -83,18 +85,38 @@ export default createBackendPlugin({
         logger: coreServices.logger,
         rpc: coreServices.rpc,
         queueManager: coreServices.queueManager,
+        secretResolver: secretResolverRef,
+        secretAdmin: secretAdminRef,
       },
-      init: async ({ logger, database, rpc, queueManager }) => {
+      init: async ({
+        logger,
+        database,
+        rpc,
+        queueManager,
+        secretResolver,
+        secretAdmin,
+      }) => {
         logger.debug("🔄 Initializing GitOps Backend...");
 
         const db = database as SafeDatabase<typeof schema>;
 
-        const router = createGitOpsRouter({ database: db, queueManager, kindRegistry });
+        const router = createGitOpsRouter({
+          database: db,
+          queueManager,
+          kindRegistry,
+          secretAdmin,
+          secretResolver,
+        });
         rpc.registerRouter(router, gitopsContract);
 
         logger.debug("✅ GitOps Backend initialized.");
       },
-      afterPluginsReady: async ({ logger, database, queueManager }) => {
+      afterPluginsReady: async ({
+        logger,
+        database,
+        queueManager,
+        secretResolver,
+      }) => {
         const registeredKinds = kindRegistry.getKinds();
         logger.debug(
           `🔄 GitOps: ${registeredKinds.length} entity kinds registered: ${registeredKinds.map((k) => k.kind).join(", ")}`,
@@ -102,19 +124,12 @@ export default createBackendPlugin({
 
         const db = database as SafeDatabase<typeof schema>;
 
-        // Create a SecretStore backed by the secrets table
+        // Resolve ${{ secrets.NAME }} via the central Secrets platform
+        // (secretResolverRef) instead of reading the gitops secrets table
+        // directly. The Secrets platform owns the table now.
         const secretStore = {
-          resolve: async (name: string): Promise<string> => {
-            const rows = await db
-              .select()
-              .from(schema.secrets)
-              .where(eq(schema.secrets.name, name));
-            const secret = rows[0];
-            if (!secret) {
-              throw new Error(`Secret not found: ${name}`);
-            }
-            return decrypt(secret.encryptedValue);
-          },
+          resolve: (name: string): Promise<string> =>
+            secretResolver.resolveSecret({ name }),
         };
 
         // Bootstrap sync worker

package/src/kind-registry.test.ts

@@ -355,4 +355,98 @@ describe("EntityKindRegistry", () => {
       expect(described[0].specSchemaDocumentation).toHaveLength(1);
     });
   });
+
+  describe("registerSpecSchemaDocumentationProvider", () => {
+    it("invokes providers on every describe, reflecting current state", () => {
+      const registry = createEntityKindRegistry();
+
+      registry.registerKind({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Automation",
+        specSchema: z.object({ actions: z.array(z.unknown()) }),
+        reconcile: async () => ({ entityId: "test-id" }),
+      });
+
+      // A mutable source the provider reads — modelling a registry that is
+      // populated AFTER the provider is registered.
+      const source: Array<{ id: string }> = [];
+      registry.registerSpecSchemaDocumentationProvider(() =>
+        source.map((s) => ({
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "Automation",
+          fieldPath: "actions[].config",
+          variantId: s.id,
+          label: s.id,
+          schema: z.object({}),
+        })),
+      );
+
+      // Empty at first describe.
+      expect(
+        registry.describeKinds()[0].specSchemaDocumentation,
+      ).toHaveLength(0);
+
+      // Source populated later (e.g. another plugin's afterPluginsReady).
+      source.push({ id: "jira" }, { id: "teams" });
+
+      const docs = registry.describeKinds()[0].specSchemaDocumentation;
+      expect(docs).toHaveLength(2);
+      expect(docs.map((d) => d.variantId).sort()).toEqual(["jira", "teams"]);
+      expect(docs[0].fieldPath).toBe("actions[].config");
+    });
+
+    it("merges provider docs with eagerly registered docs for the same kind", () => {
+      const registry = createEntityKindRegistry();
+
+      registry.registerKind({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Automation",
+        specSchema: z.object({
+          triggers: z.array(z.unknown()),
+          actions: z.array(z.unknown()),
+        }),
+        reconcile: async () => ({ entityId: "test-id" }),
+      });
+
+      registry.registerSpecSchemaDocumentation({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Automation",
+        fieldPath: "triggers[].config",
+        variantId: "eager",
+        label: "Eager",
+        schema: z.object({}),
+      });
+
+      registry.registerSpecSchemaDocumentationProvider(() => [
+        {
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "Automation",
+          fieldPath: "actions[].config",
+          variantId: "lazy",
+          label: "Lazy",
+          schema: z.object({}),
+        },
+      ]);
+
+      const docs = registry.describeKinds()[0].specSchemaDocumentation;
+      expect(docs.map((d) => d.variantId).sort()).toEqual(["eager", "lazy"]);
+    });
+
+    it("ignores provider docs whose kind has no base definition", () => {
+      const registry = createEntityKindRegistry();
+
+      registry.registerSpecSchemaDocumentationProvider(() => [
+        {
+          apiVersion: CHECKSTACK_API_VERSION,
+          kind: "Unregistered",
+          fieldPath: "config",
+          label: "X",
+          schema: z.object({}),
+        },
+      ]);
+
+      // No base definition for "Unregistered" → not described.
+      expect(registry.describeKinds()).toHaveLength(0);
+    });
+  });
 });

package/src/kind-registry.ts

@@ -5,6 +5,7 @@ import type {
   EntityKindExtensionDefinition,
   EntityKindRegistry,
   SpecSchemaDocumentation,
+  SpecSchemaDocumentationProvider,
 } from "@checkstack/gitops-common";
 import { entityMetadataSchema } from "@checkstack/gitops-common";
 
@@ -26,6 +27,13 @@ function kindKey(params: { apiVersion: string; kind: string }): string {
  */
 export function createEntityKindRegistry() {
   const kinds = new Map<string, RegisteredKind>();
+  /**
+   * Lazy documentation providers, invoked on every `describeKinds()` so the
+   * docs they return reflect the current state of whatever they read (e.g.
+   * the automation trigger/action registries, populated across plugins with
+   * no guaranteed ordering).
+   */
+  const docProviders: SpecSchemaDocumentationProvider[] = [];
 
   const registry: EntityKindRegistry & {
     /** Get a registered kind definition. */
@@ -148,6 +156,10 @@ export function createEntityKindRegistry() {
       });
     },
 
+    registerSpecSchemaDocumentationProvider(provider) {
+      docProviders.push(provider);
+    },
+
     getKind(params) {
       return kinds.get(kindKey(params))?.definition;
     },
@@ -209,7 +221,20 @@ export function createEntityKindRegistry() {
         }>;
       }> = [];
 
-      for (const registered of kinds.values()) {
+      // Collect lazy-provider docs once per describe, grouped by kind key.
+      // Each provider re-reads its source, so this reflects the current
+      // registry state (order-independent).
+      const providedDocsByKey = new Map<string, SpecSchemaDocumentation[]>();
+      for (const provider of docProviders) {
+        for (const entry of provider()) {
+          const key = kindKey(entry);
+          const list = providedDocsByKey.get(key) ?? [];
+          list.push(entry);
+          providedDocsByKey.set(key, list);
+        }
+      }
+
+      for (const [key, registered] of kinds.entries()) {
         if (!registered.definition) continue;
 
         const def = registered.definition;
@@ -222,16 +247,18 @@ export function createEntityKindRegistry() {
           }),
         );
 
-        const specSchemaDocumentation = registered.specSchemaDocumentation.map(
-          (doc) => ({
-            fieldPath: doc.fieldPath,
-            variantId: doc.variantId,
-            label: doc.label,
-            description: doc.description,
-            specSchema: toJsonSchema(doc.schema),
-            conditions: doc.conditions,
-          }),
-        );
+        const allDocs = [
+          ...registered.specSchemaDocumentation,
+          ...(providedDocsByKey.get(key) ?? []),
+        ];
+        const specSchemaDocumentation = allDocs.map((doc) => ({
+          fieldPath: doc.fieldPath,
+          variantId: doc.variantId,
+          label: doc.label,
+          description: doc.description,
+          specSchema: toJsonSchema(doc.schema),
+          conditions: doc.conditions,
+        }));
 
         result.push({
           apiVersion: def.apiVersion,

package/src/router.ts

@@ -1,10 +1,13 @@
 import { implement, ORPCError } from "@orpc/server";
 import { z } from "zod";
-import { autoAuthMiddleware, correlationMiddleware, type RpcContext } from "@checkstack/backend-api";
-import { encrypt, decrypt } from "@checkstack/backend-api";
+import { autoAuthMiddleware, correlationMiddleware, encrypt, type RpcContext } from "@checkstack/backend-api";
 import { gitopsContract, deriveSourceUrl } from "@checkstack/gitops-common";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import type { QueueManager } from "@checkstack/queue-api";
+import type {
+  SecretAdminService,
+  SecretResolverService,
+} from "@checkstack/secrets-backend";
 import type { InternalEntityKindRegistry } from "./kind-registry";
 import { triggerSyncForProvider, scheduleSyncForProvider, cancelSyncForProvider } from "./sync/sync-worker";
 import * as schema from "./schema";
@@ -26,12 +29,18 @@ export interface GitOpsRouterDeps {
   database: SafeDatabase<typeof schema>;
   queueManager: QueueManager;
   kindRegistry: InternalEntityKindRegistry;
+  /** Central Secrets platform admin service (single source of truth). */
+  secretAdmin: SecretAdminService;
+  /** Central Secrets platform resolver (service-only). */
+  secretResolver: SecretResolverService;
 }
 
 export const createGitOpsRouter = ({
   database: db,
   queueManager,
   kindRegistry,
+  secretAdmin,
+  secretResolver,
 }: GitOpsRouterDeps) => {
   // ─── Provenance ──────────────────────────────────────────────────────
 
@@ -312,92 +321,78 @@ export const createGitOpsRouter = ({
 
   // ─── Secret Management ───────────────────────────────────────────────
 
+  // Secret management is delegated to the central Secrets platform via
+  // secretAdminRef so there is a single source of truth. The gitops table
+  // is no longer the home of secrets (rows were migrated to the platform's
+  // local backend); these handlers proxy to keep the existing gitops UI
+  // working until it is retired.
   const listSecrets = os.listSecrets.handler(async () => {
-    const rows = await db.select().from(schema.secrets);
-    return rows.map((r) => ({
-      id: r.id,
-      name: r.name,
-      description: r.description,
-      createdAt: r.createdAt,
-      updatedAt: r.updatedAt,
+    const metadata = await secretAdmin.list();
+    return metadata.map((m) => ({
+      id: m.id,
+      name: m.name,
+      description: m.description,
+      createdAt: m.createdAt,
+      updatedAt: m.updatedAt,
     }));
   });
 
   const createSecret = os.createSecret.handler(async ({ input }) => {
-    // Check for duplicate name
-    const existing = await db
-      .select()
-      .from(schema.secrets)
-      .where(eq(schema.secrets.name, input.name));
-
-    if (existing[0]) {
+    const existing = await secretAdmin.list();
+    if (existing.some((m) => m.name === input.name)) {
       throw new ORPCError("CONFLICT", {
         message: `Secret with name "${input.name}" already exists`,
       });
     }
-
-    const id = uuidv4();
-    const encryptedValue = encrypt(input.value);
-    await db.insert(schema.secrets).values({
-      id,
+    await secretAdmin.setSecret({
       name: input.name,
-      encryptedValue,
+      value: input.value,
       description: input.description,
     });
-    return { id, name: input.name };
+    const after = await secretAdmin.list();
+    const meta = after.find((m) => m.name === input.name);
+    return { id: meta?.id ?? input.name, name: input.name };
   });
 
   const rotateSecret = os.rotateSecret.handler(async ({ input }) => {
-    const existing = await db
-      .select()
-      .from(schema.secrets)
-      .where(eq(schema.secrets.id, input.id));
-
-    if (!existing[0]) {
+    const existing = await secretAdmin.list();
+    const meta = existing.find((m) => m.id === input.id);
+    if (!meta) {
       throw new ORPCError("NOT_FOUND", {
         message: `Secret not found: ${input.id}`,
       });
     }
 
-    const encryptedValue = encrypt(input.value);
-    await db
-      .update(schema.secrets)
-      .set({ encryptedValue, updatedAt: new Date() })
-      .where(eq(schema.secrets.id, input.id));
+    await secretAdmin.setSecret({ name: meta.name, value: input.value });
 
     // Invalidate provenance for all entities referencing this secret
-    // so the next sync cycle re-reconciles them with the updated value
-    const secretName = existing[0].name;
+    // so the next sync cycle re-reconciles them with the updated value.
     await db
       .update(schema.provenance)
       .set({ lastSyncHash: "" })
-      .where(
-        sql`${secretName} = ANY(${schema.provenance.secretRefs})`,
-      );
+      .where(sql`${meta.name} = ANY(${schema.provenance.secretRefs})`);
 
     return { success: true };
   });
 
   const deleteSecret = os.deleteSecret.handler(async ({ input }) => {
-    await db.delete(schema.secrets).where(eq(schema.secrets.id, input.id));
-
+    const existing = await secretAdmin.list();
+    const meta = existing.find((m) => m.id === input.id);
+    if (meta) {
+      await secretAdmin.deleteSecret({ name: meta.name });
+    }
     return { success: true };
   });
 
   const resolveSecret = os.resolveSecret.handler(async ({ input }) => {
-    const rows = await db
-      .select()
-      .from(schema.secrets)
-      .where(eq(schema.secrets.name, input.name));
-
-    const secret = rows[0];
-    if (!secret) {
+    try {
+      const value = await secretResolver.resolveSecret({ name: input.name });
+      return { value };
+    } catch {
       throw new ORPCError("NOT_FOUND", {
         message: `Secret not found: ${input.name}`,
       });
     }
-
-    return { value: decrypt(secret.encryptedValue) };
   });
 
   const getSecretUsage = os.getSecretUsage.handler(async ({ input }) => {

package/src/secret-resolver.ts

@@ -1,221 +1,11 @@
-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.
+ * The schema-driven secret resolver was promoted to the central Secrets
+ * platform (`@checkstack/secrets-backend`). This module re-exports it so
+ * gitops's sync worker / reconciler keep their existing import paths while
+ * the canonical implementation + tests live in secrets-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 will NOT be resolved — the field must be annotated with
-   * `configString({ "x-secret": true })` for resolution to occur.
-   */
-  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 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 resolveSecretsBySchema(params: {
-  value: unknown;
-  schema: z.ZodTypeAny;
-  secretStore: SecretStore;
-}): Promise<SecretResolutionResult<unknown>> {
-  const { value, schema, secretStore } = params;
-  const warnings: string[] = [];
-  const resolved = await walkAndResolve({ value, schema, secretStore, warnings, path: "" });
-  return { resolved, 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 in the string
-  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;
-
-  // 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)!;
-  });
-}
+export {
+  resolveSecretsBySchema,
+  type SecretStore,
+  type SecretResolutionResult,
+} from "@checkstack/secrets-backend";

package/tsconfig.json

@@ -21,6 +21,9 @@
     },
     {
       "path": "../queue-api"
+    },
+    {
+      "path": "../secrets-backend"
     }
   ]
 }

package/src/secret-resolver.test.ts

@@ -1,325 +0,0 @@
-import { describe, it, expect } from "bun:test";
-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> = {
-      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", () => {
-  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 be resolved",
-        password: "${{ secrets.DB_PASS }}",
-      },
-      schema,
-      secretStore: mockSecretStore,
-    });
-
-    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 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", 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 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!" },
-        { name: "api", secret: "key-12345" },
-      ],
-    });
-  });
-
-  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 schema = z.object({
-      password: configString({ "x-secret": true }),
-    });
-
-    await expect(
-      resolveSecretsBySchema({
-        value: { password: "${{ secrets.NONEXISTENT }}" },
-        schema,
-        secretStore: mockSecretStore,
-      }),
-    ).rejects.toThrow("Secret not found: NONEXISTENT");
-  });
-
-  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).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([]);
-  });
-});