@checkstack/gitops-common 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @checkstack/gitops-common
 
+## 0.2.0
+
+### Minor Changes
+
+- 8ef367a: Added `registerSpecSchemaDocumentation` to EntityKindRegistry to allow plugins to provide detailed JSON Schemas for specific configurations. The frontend now displays these registered schemas as dropdown alternatives, improving the developer experience when authoring GitOps configurations.
+- cb65e9d: ### Schema-driven secret resolution, rotation invalidation, and security hardening
+
+  **Breaking**: Replaced `{ secretRef: "..." }` object syntax with `${{ secrets.NAME }}` template interpolation. The `secretField()`, `secretRefSchema`, `isSecretRef`, `SecretRef`, and `ResolvedSecretField` exports have been removed from `@checkstack/gitops-common`.
+
+  **Breaking**: `ReconcileContext.resolveSecretsBySchema()` now returns `{ resolved: T; warnings: string[] }` instead of `T` directly. Plugins must destructure the result. Warnings contain messages for `${{ secrets.NAME }}` templates found in non-secret fields (fields without `x-secret` annotation).
+
+  **New features**:
+
+  - Secrets can be referenced in **any string field** using `${{ secrets.NAME }}` syntax
+  - Inline interpolation is supported: `"postgres://user:${{ secrets.DB_PASS }}@host/db"`
+  - Resolution is **schema-driven** — reuses the existing `configString({ "x-secret": true })` pattern from DynamicForm
+  - Secret rotation now automatically invalidates affected entities, triggering re-reconciliation on the next sync cycle
+  - New `getSecretUsage` RPC endpoint to look up which entities reference a given secret
+  - Secrets UI now shows an expandable usage panel per secret showing referencing entities
+  - Reconciliation warnings: templates in non-secret fields are detected and surfaced in the provenance UI
+  - New `secretNameSchema` and `SECRET_NAME_REGEX` exports for validating secret names
+
+  **Security**:
+
+  - Secret names are validated at creation: must start with a letter, contain only `[a-zA-Z0-9_-]`, max 63 chars
+  - Secrets are validated to exist at sync time but **not pre-resolved** into the spec
+  - Templates in `metadata` fields are **rejected** to prevent secret leaks via display fields
+  - Only fields with `x-secret` schema annotations get resolved — no escape hatch
+  - Templates in non-secret fields emit warnings (stored in provenance, visible in UI) instead of silently passing
+
+  **Migration**: Update YAML descriptors to use `${{ secrets.NAME }}` instead of `secretRef: name`. Remove `secretField()` imports from plugin schemas — use `configString({ "x-secret": true })` to annotate secret fields. Destructure `const { resolved } = await context.resolveSecretsBySchema({ value, schema })` (return type changed from `T` to `{ resolved: T; warnings: string[] }`).
+
 ## 0.1.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/gitops-common",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {

package/src/access.ts

@@ -15,7 +15,7 @@ export const gitopsAccess = {
     },
   }),
 
-  /** Secret management for secretRef values. */
+  /** Secret management for ${{ secrets.NAME }} template values. */
   secret: accessPair("secret", {
     read: {
       description: "View secret names (not values)",

package/src/entity-kind-registry.ts

@@ -25,6 +25,32 @@ export interface ReconcileContext {
     kind: string;
     entityName: string;
   }) => Promise<string | undefined>;
+  /**
+   * Schema-driven secret resolution.
+   *
+   * Walks the provided 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.
+   *
+   * Returns warnings for any templates found in non-secret fields — these
+   * templates will NOT be resolved and should be surfaced to the user.
+   *
+   * Use the plugin's actual typed schema (e.g., the strategy config schema)
+   * rather than the generic GitOps spec schema — the typed schema carries the
+   * `x-secret` annotations.
+   *
+   * @example
+   * ```typescript
+   * const { resolved, warnings } = await context.resolveSecretsBySchema({
+   *   value: entity.spec.config,
+   *   schema: strategy.config.schema,
+   * });
+   * ```
+   */
+  resolveSecretsBySchema: <T>(params: {
+    value: T;
+    schema: z.ZodTypeAny;
+  }) => Promise<{ resolved: T; warnings: string[] }>;
 }
 
 /**
@@ -43,7 +69,7 @@ export interface EntityKindDefinition<TSpec = unknown> {
 
   /**
    * Called when an entity of this kind is discovered or updated via GitOps.
-   * The entity's spec is fully validated and all secretRef values are resolved.
+   * The entity's spec is fully validated and all `${{ secrets.NAME }}` templates are resolved.
    *
    * Must return the plugin-specific entity ID (e.g., the catalog system UUID).
    * The reconciler engine stores this in provenance for generic frontend lookups.
@@ -101,6 +127,33 @@ export interface EntityKindExtensionDefinition<TExtensionSpec = unknown> {
   }) => Promise<void>;
 }
 
+/**
+ * Definition for documenting a specific field variant within a kind's spec.
+ */
+export interface SpecSchemaDocumentation {
+  /** Which field this documentation applies to (e.g., "config", "collectors[].config") */
+  fieldPath: string;
+  /** 
+   * Optional unique identifier for this variant.
+   * Useful when other variants depend on this one being selected.
+   */
+  variantId?: string;
+  /** Human-readable label shown in the dropdown (e.g., "HTTP Strategy") */
+  label: string;
+  /** Optional markdown description shown alongside the schema */
+  description?: string;
+  /** The Zod schema for this variant */
+  schema: z.ZodTypeAny;
+  /** 
+   * If specified, this variant will only be shown if the selected variant 
+   * in the target fieldPath matches one of the provided variantIds.
+   */
+  conditions?: Array<{
+    fieldPath: string;
+    variantIds: string[];
+  }>;
+}
+
 /**
  * The registry interface exposed via the Extension Point.
  * Plugins call these methods during their `register()` phase.
@@ -113,4 +166,12 @@ export interface EntityKindRegistry {
   registerKindExtension<TExtensionSpec>(
     definition: EntityKindExtensionDefinition<TExtensionSpec>,
   ): void;
+
+  /** Register documentation for a specific field variant within a kind's spec. */
+  registerSpecSchemaDocumentation(
+    params: {
+      apiVersion: string;
+      kind: string;
+    } & SpecSchemaDocumentation,
+  ): void;
 }

package/src/index.ts

@@ -7,11 +7,11 @@ export {
   type EntityMetadata,
 } from "./entity-envelope";
 export {
-  secretField,
-  secretRefSchema,
-  isSecretRef,
-  type SecretRef,
-  type ResolvedSecretField,
+  SECRET_NAME_REGEX,
+  SECRET_TEMPLATE_REGEX,
+  secretNameSchema,
+  secretTemplateSchema,
+  collectSecretNames,
 } from "./secret-field";
 export {
   entityRefSchema,
@@ -23,6 +23,7 @@ export {
   type EntityKindExtensionDefinition,
   type EntityKindRegistry,
   type ReconcileContext,
+  type SpecSchemaDocumentation,
 } from "./entity-kind-registry";
 export { gitopsAccess, gitopsAccessRules } from "./access";
 export { gitopsRoutes } from "./routes";

package/src/provenance-types.ts

@@ -19,6 +19,8 @@ export const provenanceSchema = z.object({
   lastSyncHash: z.string(),
   status: provenanceStatusSchema,
   errorMessage: z.string().nullable(),
+  /** Warnings about unresolved secret templates in non-secret fields. */
+  warnings: z.array(z.string()),
   lastSyncedAt: z.date(),
   createdAt: z.date(),
 });

package/src/rpc-contract.ts

@@ -6,6 +6,7 @@ import {
   provenanceStatusSchema,
   deletionPolicySchema,
 } from "./provenance-types";
+import { secretNameSchema } from "./secret-field";
 import { z } from "zod";
 
 export const gitopsContract = {
@@ -175,7 +176,7 @@ export const gitopsContract = {
   })
     .input(
       z.object({
-        name: z.string().min(1).max(63),
+        name: secretNameSchema,
         value: z.string().min(1),
         description: z.string().optional(),
       }),
@@ -218,6 +219,24 @@ export const gitopsContract = {
     .input(z.object({ name: z.string() }))
     .output(z.object({ value: z.string() })),
 
+  /** Look up which entities reference a given secret. */
+  getSecretUsage: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [gitopsAccess.secret.read],
+  })
+    .input(z.object({ secretName: z.string() }))
+    .output(
+      z.array(
+        z.object({
+          kind: z.string(),
+          entityName: z.string(),
+          repository: z.string(),
+          filePath: z.string(),
+        }),
+      ),
+    ),
+
   // ═══════════════════════════════════════════════════════════════════════════
   // KIND REGISTRY (browsing)
   // ═══════════════════════════════════════════════════════════════════════════
@@ -232,6 +251,7 @@ export const gitopsContract = {
       z.object({
         apiVersion: z.string(),
         kind: z.string(),
+        metadataSchema: z.record(z.string(), z.unknown()),
         specSchema: z.record(z.string(), z.unknown()),
         extensions: z.array(
           z.object({
@@ -239,6 +259,19 @@ export const gitopsContract = {
             specSchema: z.record(z.string(), z.unknown()),
           }),
         ),
+        specSchemaDocumentation: z.array(
+          z.object({
+            fieldPath: z.string(),
+            variantId: z.string().optional(),
+            label: z.string(),
+            description: z.string().optional(),
+            specSchema: z.record(z.string(), z.unknown()),
+            conditions: z.array(z.object({
+              fieldPath: z.string(),
+              variantIds: z.array(z.string()),
+            })).optional(),
+          }),
+        ),
       }),
     ),
   ),

package/src/secret-field.test.ts

@@ -1,50 +1,168 @@
 import { describe, it, expect } from "bun:test";
-import { secretField, isSecretRef, type SecretRef } from "./secret-field";
+import {
+  SECRET_TEMPLATE_REGEX,
+  secretNameSchema,
+  collectSecretNames,
+  secretTemplateSchema,
+} from "./secret-field";
 
-describe("secretField", () => {
-  const schema = secretField();
+describe("SECRET_TEMPLATE_REGEX", () => {
+  it("matches a simple secret template", () => {
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    const match = SECRET_TEMPLATE_REGEX.exec("${{ secrets.DB_PASS }}");
+    expect(match).not.toBeNull();
+    expect(match![1]).toBe("DB_PASS");
+  });
 
-  it("accepts a plain string value", () => {
-    const result = schema.safeParse("my-password");
-    expect(result.success).toBe(true);
-    if (result.success) expect(result.data).toBe("my-password");
+  it("matches templates with extra whitespace", () => {
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    const match = SECRET_TEMPLATE_REGEX.exec("${{  secrets.MY_KEY  }}");
+    expect(match).not.toBeNull();
+    expect(match![1]).toBe("MY_KEY");
   });
 
-  it("accepts a secretRef object", () => {
-    const result = schema.safeParse({ secretRef: "prod-db-password" });
-    expect(result.success).toBe(true);
-    if (result.success) {
-      expect(result.data).toEqual({ secretRef: "prod-db-password" });
+  it("matches hyphenated secret names", () => {
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    const match = SECRET_TEMPLATE_REGEX.exec("${{ secrets.prod-db-pass }}");
+    expect(match).not.toBeNull();
+    expect(match![1]).toBe("prod-db-pass");
+  });
+
+  it("matches multiple templates in one string", () => {
+    const str =
+      "postgres://${{ secrets.DB_USER }}:${{ secrets.DB_PASS }}@host/db";
+    const matches: string[] = [];
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = SECRET_TEMPLATE_REGEX.exec(str)) !== null) {
+      matches.push(match[1]);
     }
+    expect(matches).toEqual(["DB_USER", "DB_PASS"]);
   });
 
-  it("rejects a number", () => {
-    const result = schema.safeParse(42);
-    expect(result.success).toBe(false);
+  it("does not match plain strings", () => {
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    expect(SECRET_TEMPLATE_REGEX.exec("just a string")).toBeNull();
   });
 
-  it("rejects an object without secretRef", () => {
-    const result = schema.safeParse({ key: "value" });
-    expect(result.success).toBe(false);
+  it("does not match malformed templates", () => {
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    expect(SECRET_TEMPLATE_REGEX.exec("${ secrets.WRONG }")).toBeNull();
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    expect(SECRET_TEMPLATE_REGEX.exec("${{ notSecrets.WRONG }}")).toBeNull();
   });
+});
 
-  it("rejects secretRef with empty name", () => {
-    const result = schema.safeParse({ secretRef: "" });
+describe("secretTemplateSchema", () => {
+  it("accepts a valid template string", () => {
+    const result = secretTemplateSchema.safeParse("${{ secrets.MY_SECRET }}");
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects a plain string without template", () => {
+    const result = secretTemplateSchema.safeParse("just-a-string");
     expect(result.success).toBe(false);
   });
 });
 
-describe("isSecretRef", () => {
-  it("returns true for a SecretRef object", () => {
-    const ref: SecretRef = { secretRef: "my-secret" };
-    expect(isSecretRef(ref)).toBe(true);
+describe("collectSecretNames", () => {
+  it("extracts a single secret from a top-level string", () => {
+    const result = collectSecretNames({
+      value: { password: "${{ secrets.DB_PASS }}" },
+    });
+    expect(result).toEqual(["DB_PASS"]);
+  });
+
+  it("returns empty array when no secrets are referenced", () => {
+    const result = collectSecretNames({
+      value: { host: "localhost", port: 5432 },
+    });
+    expect(result).toEqual([]);
+  });
+
+  it("extracts secrets from nested objects", () => {
+    const result = collectSecretNames({
+      value: {
+        connection: {
+          host: "db.internal",
+          password: "${{ secrets.NESTED_PASS }}",
+        },
+      },
+    });
+    expect(result).toEqual(["NESTED_PASS"]);
+  });
+
+  it("extracts secrets from arrays", () => {
+    const result = collectSecretNames({
+      value: {
+        credentials: [
+          { name: "db", secret: "${{ secrets.DB_PASS }}" },
+          { name: "api", secret: "${{ secrets.API_KEY }}" },
+        ],
+      },
+    });
+    expect(result).toEqual(["DB_PASS", "API_KEY"]);
+  });
+
+  it("extracts multiple secrets from a single interpolated string", () => {
+    const result = collectSecretNames({
+      value: {
+        url: "postgres://${{ secrets.DB_USER }}:${{ secrets.DB_PASS }}@host/db",
+      },
+    });
+    expect(result).toEqual(["DB_USER", "DB_PASS"]);
+  });
+
+  it("deduplicates secret names", () => {
+    const result = collectSecretNames({
+      value: {
+        primary: "${{ secrets.SHARED }}",
+        secondary: "${{ secrets.SHARED }}",
+      },
+    });
+    expect(result).toEqual(["SHARED"]);
+  });
+
+  it("handles null and undefined values gracefully", () => {
+    const result = collectSecretNames({
+      value: { a: null, b: undefined, c: "${{ secrets.VALID }}" },
+    });
+    expect(result).toEqual(["VALID"]);
+  });
+
+  it("ignores non-string primitives", () => {
+    const result = collectSecretNames({
+      value: { num: 42, bool: true, str: "${{ secrets.ONLY_THIS }}" },
+    });
+    expect(result).toEqual(["ONLY_THIS"]);
+  });
+});
+
+describe("secretNameSchema", () => {
+  it.each(["DB_PASS", "my-secret", "ApiKey123", "a", "prod_db_pass_v2"])("accepts valid name: %s", (name) => {
+    expect(secretNameSchema.safeParse(name).success).toBe(true);
+  });
+
+  it.each([
+    "has space",
+    "has\ttab",
+    "123starts-with-digit",
+    "has.dot",
+    "no@special",
+    "no/slashes",
+    "${{ secrets.NOPE }}",
+    "",
+  ])("rejects invalid name: %s", (name) => {
+    expect(secretNameSchema.safeParse(name).success).toBe(false);
   });
 
-  it("returns false for a plain string", () => {
-    expect(isSecretRef("plain")).toBe(false);
+  it("rejects names exceeding 63 characters", () => {
+    const longName = "A".repeat(64);
+    expect(secretNameSchema.safeParse(longName).success).toBe(false);
   });
 
-  it("returns false for null", () => {
-    expect(isSecretRef(null)).toBe(false);
+  it("accepts names at the 63-character limit", () => {
+    const maxName = "A".repeat(63);
+    expect(secretNameSchema.safeParse(maxName).success).toBe(true);
   });
 });

package/src/secret-field.ts

@@ -1,47 +1,82 @@
 import { z } from "zod";
 
 /**
- * Schema for a secret reference object.
- * Used in YAML descriptors to reference secrets stored in the Checkstack secret store.
+ * Valid characters for a secret name: letters, digits, underscores, and hyphens.
+ * This must stay in sync with the capture group in {@link SECRET_TEMPLATE_REGEX}.
  */
-export const secretRefSchema = z.object({
-  secretRef: z.string().min(1, "Secret reference name must not be empty"),
-});
-
-export type SecretRef = z.infer<typeof secretRefSchema>;
+export const SECRET_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
 
 /**
- * Type guard to check if a value is a SecretRef object.
+ * Zod schema for validating secret names at creation time.
+ * Ensures the name can be referenced via `${{ secrets.NAME }}`.
  */
-export function isSecretRef(value: unknown): value is SecretRef {
-  if (value === null || value === undefined || typeof value !== "object") {
-    return false;
-  }
-  return (
-    "secretRef" in value &&
-    typeof (value as SecretRef).secretRef === "string"
+export const secretNameSchema = z
+  .string()
+  .min(1)
+  .max(63)
+  .regex(
+    SECRET_NAME_REGEX,
+    "Secret names must start with a letter and contain only letters, digits, underscores, or hyphens",
   );
-}
 
 /**
- * Creates a Zod schema for fields that accept either a plain string or a secret reference.
+ * Regex matching ${{ secrets.NAME }} template expressions in strings.
+ * Captures the secret name in group 1.
+ * Supports multiple occurrences within a single string value.
  *
- * In YAML descriptors, users can write either:
- * ```yaml
- * password: "dev-password"              # plain string
- * password:
- *   secretRef: production-db-creds      # reference to secret store
- * ```
- *
- * The GitOps reconciliation engine resolves all secretRef values before calling
- * plugin reconcilers, so plugins always receive plain strings.
+ * @example
+ * "${{ secrets.DB_PASS }}" → captures "DB_PASS"
+ * "postgres://u:${{ secrets.PASS }}@${{ secrets.HOST }}/db" → captures "PASS", "HOST"
  */
-export function secretField() {
-  return z.union([z.string(), secretRefSchema]);
-}
+export const SECRET_TEMPLATE_REGEX =
+  /\$\{\{\s*secrets\.([a-zA-Z0-9_-]+)\s*\}\}/g;
 
 /**
- * The resolved type of a secret field is always a string.
- * After the reconciliation engine resolves secretRefs, all values are plain strings.
+ * Zod schema for validating secret template strings.
+ * Matches strings containing at least one ${{ secrets.NAME }} pattern.
  */
-export type ResolvedSecretField = string;
+export const secretTemplateSchema = z.string().regex(
+  /\$\{\{\s*secrets\.[a-zA-Z0-9_-]+\s*\}\}/,
+  "Must contain a ${{ secrets.NAME }} reference",
+);
+
+/**
+ * Recursively walks a value and collects all unique secret names
+ * referenced via ${{ secrets.NAME }} patterns in string values.
+ *
+ * @returns Deduplicated array of secret names found in the value tree
+ */
+export function collectSecretNames(params: { value: unknown }): string[] {
+  const names = new Set<string>();
+  collectFromValue(params.value, names);
+  return [...names];
+}
+
+function collectFromValue(value: unknown, names: Set<string>): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  if (typeof value === "string") {
+    // Reset regex lastIndex for safe reuse (global flag)
+    SECRET_TEMPLATE_REGEX.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = SECRET_TEMPLATE_REGEX.exec(value)) !== null) {
+      names.add(match[1]);
+    }
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectFromValue(item, names);
+    }
+    return;
+  }
+
+  if (typeof value === "object") {
+    for (const val of Object.values(value)) {
+      collectFromValue(val, names);
+    }
+  }
+}