@griffin-app/griffin-plan-executor 0.1.0

package/src/secrets/registry.ts

@@ -0,0 +1,234 @@
+/**
+ * Secret provider registry for managing multiple secret providers.
+ */
+
+import type {
+  SecretProvider,
+  SecretRefData,
+  SecretResolveOptions,
+} from "./types.js";
+import { SecretResolutionError } from "./types.js";
+
+/**
+ * Registry for managing and accessing secret providers.
+ * Supports multiple providers simultaneously (e.g., env + aws + vault).
+ */
+export class SecretProviderRegistry {
+  private providers = new Map<string, SecretProvider>();
+
+  /**
+   * Register a secret provider.
+   * @param provider - The provider to register
+   * @throws Error if a provider with the same name is already registered
+   */
+  register(provider: SecretProvider): void {
+    if (this.providers.has(provider.name)) {
+      throw new Error(
+        `Secret provider "${provider.name}" is already registered`,
+      );
+    }
+    this.providers.set(provider.name, provider);
+  }
+
+  /**
+   * Unregister a secret provider by name.
+   * @param name - The provider name to remove
+   * @returns true if the provider was removed, false if it wasn't registered
+   */
+  unregister(name: string): boolean {
+    return this.providers.delete(name);
+  }
+
+  /**
+   * Get a registered provider by name.
+   * @param name - The provider name
+   * @throws Error if the provider is not registered
+   */
+  get(name: string): SecretProvider {
+    const provider = this.providers.get(name);
+    if (!provider) {
+      const available = [...this.providers.keys()];
+      throw new SecretResolutionError(
+        `Secret provider "${name}" is not configured. Available providers: ${
+          available.length > 0 ? available.join(", ") : "(none)"
+        }`,
+        { provider: name, ref: "" },
+      );
+    }
+    return provider;
+  }
+
+  /**
+   * Check if a provider is registered.
+   */
+  has(name: string): boolean {
+    return this.providers.has(name);
+  }
+
+  /**
+   * Get all registered provider names.
+   */
+  getProviderNames(): string[] {
+    return [...this.providers.keys()];
+  }
+
+  /**
+   * Resolve a secret reference using the appropriate provider.
+   * @param secretRef - The secret reference data
+   * @returns The resolved secret value
+   * @throws SecretResolutionError if resolution fails
+   */
+  async resolve(secretRef: SecretRefData): Promise<string> {
+    const provider = this.get(secretRef.provider);
+
+    try {
+      return await provider.resolve(secretRef.ref, {
+        version: secretRef.version,
+        field: secretRef.field,
+      });
+    } catch (error) {
+      if (error instanceof SecretResolutionError) {
+        throw error;
+      }
+      throw new SecretResolutionError(
+        `Failed to resolve secret "${secretRef.provider}:${secretRef.ref}": ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        {
+          provider: secretRef.provider,
+          ref: secretRef.ref,
+          cause: error,
+        },
+      );
+    }
+  }
+
+  /**
+   * Resolve multiple secrets, grouped by provider for efficiency.
+   * @param refs - Array of secret reference data
+   * @returns Map of "provider:ref" to resolved value
+   * @throws SecretResolutionError if any resolution fails (fail-fast)
+   */
+  async resolveMany(refs: SecretRefData[]): Promise<Map<string, string>> {
+    if (refs.length === 0) {
+      return new Map();
+    }
+
+    // Group refs by provider
+    const byProvider = new Map<
+      string,
+      Array<{ ref: string; options?: SecretResolveOptions; key: string }>
+    >();
+
+    for (const secretRef of refs) {
+      const key = this.makeKey(secretRef);
+      const group = byProvider.get(secretRef.provider) || [];
+      group.push({
+        ref: secretRef.ref,
+        options: {
+          version: secretRef.version,
+          field: secretRef.field,
+        },
+        key,
+      });
+      byProvider.set(secretRef.provider, group);
+    }
+
+    // Resolve each provider's secrets
+    const results = new Map<string, string>();
+
+    for (const [providerName, providerRefs] of byProvider) {
+      const provider = this.get(providerName);
+
+      // Use batch resolution if available, otherwise resolve individually
+      if (provider.resolveMany) {
+        const batchRefs = providerRefs.map((r) => ({
+          ref: r.ref,
+          options: r.options,
+        }));
+
+        try {
+          const batchResults = await provider.resolveMany(batchRefs);
+
+          for (const providerRef of providerRefs) {
+            const value = batchResults.get(providerRef.ref);
+            if (value === undefined) {
+              throw new SecretResolutionError(
+                `Secret "${providerName}:${providerRef.ref}" not found in batch results`,
+                { provider: providerName, ref: providerRef.ref },
+              );
+            }
+            results.set(providerRef.key, value);
+          }
+        } catch (error) {
+          if (error instanceof SecretResolutionError) {
+            throw error;
+          }
+          throw new SecretResolutionError(
+            `Batch resolution failed for provider "${providerName}": ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+            {
+              provider: providerName,
+              ref: providerRefs[0]?.ref || "",
+              cause: error,
+            },
+          );
+        }
+      } else {
+        // Resolve individually (fail-fast on first error)
+        for (const providerRef of providerRefs) {
+          try {
+            const value = await provider.resolve(
+              providerRef.ref,
+              providerRef.options,
+            );
+            results.set(providerRef.key, value);
+          } catch (error) {
+            if (error instanceof SecretResolutionError) {
+              throw error;
+            }
+            throw new SecretResolutionError(
+              `Failed to resolve secret "${providerName}:${providerRef.ref}": ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+              { provider: providerName, ref: providerRef.ref, cause: error },
+            );
+          }
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Validate all registered providers.
+   * @throws Error if any provider validation fails
+   */
+  async validateAll(): Promise<void> {
+    for (const [name, provider] of this.providers) {
+      if (provider.validate) {
+        try {
+          await provider.validate();
+        } catch (error) {
+          throw new Error(
+            `Provider "${name}" validation failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Create a unique key for a secret reference (for caching/deduplication).
+   */
+  makeKey(secretRef: SecretRefData): string {
+    const parts = [secretRef.provider, secretRef.ref];
+    if (secretRef.version) parts.push(`v:${secretRef.version}`);
+    if (secretRef.field) parts.push(`f:${secretRef.field}`);
+    return parts.join(":");
+  }
+}

package/src/secrets/resolver.ts

@@ -0,0 +1,249 @@
+/**
+ * Secret resolution utilities for test plans.
+ */
+
+import { TestPlanV1, Node } from "griffin/types";
+import { NodeType } from "griffin/schema";
+import type { SecretProviderRegistry } from "./registry.js";
+import type { SecretRef, SecretRefData } from "./types.js";
+import { isSecretRef } from "./types.js";
+
+/**
+ * Collected secret references from a plan.
+ */
+interface CollectedSecrets {
+  /** All unique secret references found */
+  refs: SecretRefData[];
+  /** Paths where secrets were found (for substitution) */
+  paths: Array<{
+    path: (string | number)[];
+    secretRef: SecretRefData;
+  }>;
+}
+
+/**
+ * Recursively collect all secret references from a value.
+ * @param value - The value to scan
+ * @param currentPath - Current path in the object tree
+ * @param collected - Accumulator for found secrets
+ */
+function collectSecretsFromValue(
+  value: unknown,
+  currentPath: (string | number)[],
+  collected: CollectedSecrets,
+): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  if (isSecretRef(value)) {
+    collected.refs.push(value.$secret);
+    collected.paths.push({
+      path: [...currentPath],
+      secretRef: value.$secret,
+    });
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      collectSecretsFromValue(value[i], [...currentPath, i], collected);
+    }
+    return;
+  }
+
+  if (typeof value === "object") {
+    for (const [key, val] of Object.entries(value)) {
+      collectSecretsFromValue(val, [...currentPath, key], collected);
+    }
+  }
+}
+
+/**
+ * Collect all secret references from a test plan.
+ * Scans endpoint headers and bodies for $secret markers.
+ */
+export function collectSecretsFromPlan(plan: TestPlanV1): CollectedSecrets {
+  const collected: CollectedSecrets = {
+    refs: [],
+    paths: [],
+  };
+
+  for (let nodeIndex = 0; nodeIndex < plan.nodes.length; nodeIndex++) {
+    const node = plan.nodes[nodeIndex];
+
+    // Only endpoints can have secrets (in headers and body)
+    if (node.type !== NodeType.ENDPOINT) {
+      continue;
+    }
+
+    //const endpoint = node;
+
+    // Scan headers
+    if (node.headers) {
+      for (const [headerKey, headerValue] of Object.entries(node.headers)) {
+        collectSecretsFromValue(
+          headerValue,
+          ["nodes", nodeIndex, "headers", headerKey],
+          collected,
+        );
+      }
+    }
+
+    // Scan body
+    if (node.body !== undefined) {
+      collectSecretsFromValue(
+        node.body,
+        ["nodes", nodeIndex, "body"],
+        collected,
+      );
+    }
+  }
+
+  // Deduplicate refs by creating a unique key
+  const seen = new Set<string>();
+  const uniqueRefs: SecretRefData[] = [];
+
+  for (const ref of collected.refs) {
+    const key = `${ref.provider}:${ref.ref}:${ref.version || ""}:${ref.field || ""}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      uniqueRefs.push(ref);
+    }
+  }
+
+  collected.refs = uniqueRefs;
+  return collected;
+}
+
+/**
+ * Set a value at a path in an object.
+ * Creates intermediate objects/arrays as needed.
+ */
+function setAtPath(
+  obj: unknown,
+  path: (string | number)[],
+  value: unknown,
+): void {
+  if (path.length === 0) {
+    return;
+  }
+
+  let current: any = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    if (current[key] === undefined) {
+      // Create intermediate object or array based on next key type
+      current[key] = typeof path[i + 1] === "number" ? [] : {};
+    }
+    current = current[key];
+  }
+
+  current[path[path.length - 1]] = value;
+}
+
+/**
+ * Deep clone a value.
+ */
+function deepClone<T>(value: T): T {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * Resolve all secrets in a plan and return a new plan with substituted values.
+ * The original plan is not modified.
+ *
+ * @param plan - The test plan containing secret references
+ * @param registry - The secret provider registry
+ * @returns A new plan with all secrets resolved to their values
+ * @throws SecretResolutionError if any secret cannot be resolved (fail-fast)
+ */
+export async function resolveSecretsInPlan(
+  plan: TestPlanV1,
+  registry: SecretProviderRegistry,
+): Promise<TestPlanV1> {
+  // Collect all secret references
+  const collected = collectSecretsFromPlan(plan);
+
+  if (collected.refs.length === 0) {
+    // No secrets to resolve
+    return plan;
+  }
+
+  // Resolve all secrets (fail-fast on any error)
+  const resolved = await registry.resolveMany(collected.refs);
+
+  // Clone the plan for modification
+  const resolvedPlan = deepClone(plan);
+
+  // Substitute resolved values at each path
+  for (const { path, secretRef } of collected.paths) {
+    const key = registry.makeKey(secretRef);
+    const value = resolved.get(key);
+
+    if (value === undefined) {
+      // This shouldn't happen if resolveMany worked correctly
+      throw new Error(
+        `Internal error: resolved value not found for secret "${secretRef.provider}:${secretRef.ref}"`,
+      );
+    }
+
+    setAtPath(resolvedPlan, path, value);
+  }
+
+  return resolvedPlan;
+}
+
+/**
+ * Check if a plan contains any secret references.
+ * Useful for short-circuiting resolution when no secrets are present.
+ */
+export function planHasSecrets(plan: TestPlanV1): boolean {
+  for (const node of plan.nodes) {
+    if (node.type !== NodeType.ENDPOINT) {
+      continue;
+    }
+
+    // Check headers
+    if (node.headers) {
+      for (const headerValue of Object.values(node.headers)) {
+        if (isSecretRef(headerValue)) {
+          return true;
+        }
+      }
+    }
+
+    // Check body (recursive check)
+    if (node.body !== undefined && containsSecretRef(node.body)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Recursively check if a value contains any secret references.
+ */
+function containsSecretRef(value: unknown): boolean {
+  if (value === null || value === undefined) {
+    return false;
+  }
+
+  if (isSecretRef(value)) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.some(containsSecretRef);
+  }
+
+  if (typeof value === "object") {
+    return Object.values(value).some(containsSecretRef);
+  }
+
+  return false;
+}