@griffin-app/griffin-executor 0.1.0

package/src/secrets/providers/vault.ts

@@ -0,0 +1,257 @@
+/**
+ * HashiCorp Vault secret provider.
+ *
+ * Reads secrets from HashiCorp Vault KV secrets engine (v1 and v2).
+ * Supports field extraction from JSON secrets.
+ *
+ * Usage in DSL:
+ *   secret("vault:secret/data/myapp/config")
+ *   secret("vault:secret/data/myapp/config", { field: "api_key" })
+ *   secret("vault:secret/data/myapp/config", { version: "2" })
+ */
+
+import type { SecretProvider, SecretResolveOptions } from "../types.js";
+import { SecretResolutionError } from "../types.js";
+
+/**
+ * HTTP client interface for Vault API calls.
+ * This allows dependency injection without requiring a specific HTTP library.
+ */
+export interface VaultHttpClient {
+  get(
+    url: string,
+    options: { headers: Record<string, string> },
+  ): Promise<{
+    status: number;
+    data: unknown;
+  }>;
+}
+
+export interface VaultProviderOptions {
+  /**
+   * Vault server address (e.g., "https://vault.example.com:8200").
+   */
+  address: string;
+
+  /**
+   * Authentication token.
+   */
+  token: string;
+
+  /**
+   * HTTP client for making requests to Vault.
+   */
+  httpClient: VaultHttpClient;
+
+  /**
+   * Optional namespace for Vault Enterprise.
+   */
+  namespace?: string;
+
+  /**
+   * KV secrets engine version (1 or 2).
+   * Defaults to 2.
+   */
+  kvVersion?: 1 | 2;
+
+  /**
+   * Optional prefix for secret paths.
+   */
+  prefix?: string;
+}
+
+export class VaultProvider implements SecretProvider {
+  readonly name = "vault";
+  private readonly address: string;
+  private readonly token: string;
+  private readonly httpClient: VaultHttpClient;
+  private readonly namespace?: string;
+  private readonly kvVersion: 1 | 2;
+  private readonly prefix: string;
+
+  // Simple in-memory cache with TTL
+  private cache = new Map<
+    string,
+    { value: Record<string, unknown>; expires: number }
+  >();
+  private readonly cacheTtlMs = 5 * 60 * 1000; // 5 minutes
+
+  constructor(options: VaultProviderOptions) {
+    this.address = options.address.replace(/\/$/, ""); // Remove trailing slash
+    this.token = options.token;
+    this.httpClient = options.httpClient;
+    this.namespace = options.namespace;
+    this.kvVersion = options.kvVersion ?? 2;
+    this.prefix = options.prefix ?? "";
+  }
+
+  async resolve(ref: string, options?: SecretResolveOptions): Promise<string> {
+    const secretPath = this.prefix + ref;
+    const version = options?.version;
+    const cacheKey = `${secretPath}:${version ?? "latest"}`;
+
+    // Check cache
+    const cached = this.cache.get(cacheKey);
+    if (cached && cached.expires > Date.now()) {
+      return this.extractField(cached.value, options?.field, ref);
+    }
+
+    try {
+      // Build request URL
+      let url = `${this.address}/v1/${secretPath}`;
+      if (this.kvVersion === 2 && version) {
+        url += `?version=${version}`;
+      }
+
+      // Build headers
+      const headers: Record<string, string> = {
+        "X-Vault-Token": this.token,
+      };
+      if (this.namespace) {
+        headers["X-Vault-Namespace"] = this.namespace;
+      }
+
+      const response = await this.httpClient.get(url, { headers });
+
+      if (response.status === 404) {
+        throw new SecretResolutionError(
+          `Secret "${secretPath}" not found in Vault`,
+          { ref },
+        );
+      }
+
+      if (response.status === 403) {
+        throw new SecretResolutionError(
+          `Access denied to secret "${secretPath}". Check Vault policies.`,
+          { ref },
+        );
+      }
+
+      if (response.status !== 200) {
+        throw new SecretResolutionError(
+          `Vault returned status ${response.status} for secret "${secretPath}"`,
+          { ref },
+        );
+      }
+
+      // Parse response based on KV version
+      const data = response.data as {
+        data?: Record<string, unknown> | { data?: Record<string, unknown> };
+      };
+
+      let secretData: Record<string, unknown>;
+
+      if (this.kvVersion === 2) {
+        // KV v2 wraps data in an extra "data" object
+        const kvData = data?.data as
+          | { data?: Record<string, unknown> }
+          | undefined;
+        if (!kvData?.data) {
+          throw new SecretResolutionError(
+            `Invalid KV v2 response structure for secret "${secretPath}"`,
+            { ref },
+          );
+        }
+        secretData = kvData.data;
+      } else {
+        // KV v1 has data directly
+        if (!data?.data || typeof data.data !== "object") {
+          throw new SecretResolutionError(
+            `Invalid KV v1 response structure for secret "${secretPath}"`,
+            { ref },
+          );
+        }
+        secretData = data.data as Record<string, unknown>;
+      }
+
+      // Cache the secret data
+      this.cache.set(cacheKey, {
+        value: secretData,
+        expires: Date.now() + this.cacheTtlMs,
+      });
+
+      return this.extractField(secretData, options?.field, ref);
+    } catch (error) {
+      if (error instanceof SecretResolutionError) {
+        throw error;
+      }
+
+      throw new SecretResolutionError(
+        `Failed to retrieve secret "${secretPath}" from Vault: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        { ref, cause: error },
+      );
+    }
+  }
+
+  /**
+   * Extract a field from the secret data.
+   * If no field is specified, returns the entire data as JSON string.
+   */
+  private extractField(
+    secretData: Record<string, unknown>,
+    field: string | undefined,
+    ref: string,
+  ): string {
+    if (!field) {
+      // Return entire secret as JSON if no field specified
+      return JSON.stringify(secretData);
+    }
+
+    const value = secretData[field];
+
+    if (value === undefined) {
+      throw new SecretResolutionError(
+        `Field "${field}" not found in secret "${ref}"`,
+        { ref },
+      );
+    }
+
+    // Convert to string if not already
+    return typeof value === "string" ? value : JSON.stringify(value);
+  }
+
+  async validate(): Promise<void> {
+    // Verify we can authenticate with Vault
+    try {
+      const headers: Record<string, string> = {
+        "X-Vault-Token": this.token,
+      };
+      if (this.namespace) {
+        headers["X-Vault-Namespace"] = this.namespace;
+      }
+
+      const response = await this.httpClient.get(
+        `${this.address}/v1/auth/token/lookup-self`,
+        { headers },
+      );
+
+      if (response.status === 403) {
+        throw new Error("Invalid or expired Vault token");
+      }
+
+      if (response.status !== 200) {
+        throw new Error(
+          `Vault authentication check failed with status ${response.status}`,
+        );
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("Vault")) {
+        throw error;
+      }
+      throw new Error(
+        `Failed to connect to Vault at ${this.address}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  /**
+   * Clear the cache. Useful for testing or forced refresh.
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+}

package/src/secrets/resolver.ts

@@ -0,0 +1,269 @@
+/**
+ * Secret resolution utilities for test monitors.
+ */
+import { type MonitorV1 } from "@griffin-app/griffin-hub-sdk";
+import type { SecretProvider } from "./types.js";
+import type { SecretRef, SecretRefData } from "./types.js";
+import { isSecretRef, isStringLiteral, SecretResolutionError } from "./types.js";
+
+/**
+ * Collected secret references and literals from a monitor.
+ */
+interface CollectedSecrets {
+  /** All unique secret references found */
+  refs: SecretRefData[];
+  /** Paths where secrets were found (for substitution) */
+  paths: Array<{
+    path: (string | number)[];
+    secretRef: SecretRefData;
+  }>;
+  /** Paths where string literals were found (for unwrapping) */
+  literalPaths: Array<{
+    path: (string | number)[];
+    value: string;
+  }>;
+}
+
+/**
+ * Recursively collect all secret references and string literals from a value.
+ * @param value - The value to scan
+ * @param currentPath - Current path in the object tree
+ * @param collected - Accumulator for found secrets and literals
+ */
+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 (isStringLiteral(value)) {
+    collected.literalPaths.push({
+      path: [...currentPath],
+      value: value.$literal,
+    });
+    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 and string literals from a test monitor.
+ * Scans endpoint headers and bodies for $secret markers and $literal wrappers.
+ */
+export function collectSecretsFromMonitor(
+  monitor: MonitorV1,
+): CollectedSecrets {
+  const collected: CollectedSecrets = {
+    refs: [],
+    paths: [],
+    literalPaths: [],
+  };
+
+  for (let nodeIndex = 0; nodeIndex < monitor.nodes.length; nodeIndex++) {
+    const node = monitor.nodes[nodeIndex];
+
+    // Only endpoints can have secrets (in headers and body)
+    if (node.type !== "HTTP_REQUEST") {
+      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.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 and unwrap string literals in a monitor and return a new monitor with substituted values.
+ * The original monitor is not modified.
+ *
+ * @param monitor - The test monitor containing secret references and string literals
+ * @param provider - The secret provider (required when monitor contains secret refs)
+ * @returns A new monitor with all secrets resolved to their values and literals unwrapped
+ * @throws SecretResolutionError if any secret cannot be resolved (fail-fast)
+ */
+export async function resolveSecretsInMonitor(
+  monitor: MonitorV1,
+  provider: SecretProvider | null,
+): Promise<MonitorV1> {
+  // Collect all secret references and string literals
+  const collected = collectSecretsFromMonitor(monitor);
+
+  if (collected.refs.length === 0 && collected.literalPaths.length === 0) {
+    // No secrets or literals to resolve
+    return monitor;
+  }
+
+  // Resolve secrets when we have refs (provider required)
+  if (collected.refs.length > 0 && !provider) {
+    throw new SecretResolutionError(
+      "Monitor contains secret references but no secret provider was provided",
+      { ref: "unknown" },
+    );
+  }
+
+  // Clone the monitor for modification
+  const resolvedMonitor = deepClone(monitor);
+
+  // Substitute resolved secret values at each path
+  if (provider) {
+    for (const { path, secretRef } of collected.paths) {
+      const value = await provider.resolve(secretRef.ref, {
+        version: secretRef.version,
+        field: secretRef.field,
+      });
+      setAtPath(resolvedMonitor, path, value);
+    }
+  }
+
+  // Unwrap string literals at each path
+  for (const { path, value } of collected.literalPaths) {
+    setAtPath(resolvedMonitor, path, value);
+  }
+
+  return resolvedMonitor;
+}
+
+/**
+ * Check if a monitor contains any secret references or string literals that need resolution.
+ * Useful for short-circuiting resolution when no secrets or literals are present.
+ */
+export function planHasSecrets(monitor: MonitorV1): boolean {
+  for (const node of monitor.nodes) {
+    if (node.type !== "HTTP_REQUEST") {
+      continue;
+    }
+
+    // Check headers
+    if (node.headers) {
+      for (const headerValue of Object.values(node.headers)) {
+        if (isSecretRef(headerValue) || isStringLiteral(headerValue)) {
+          return true;
+        }
+      }
+    }
+
+    // Check body (recursive check)
+    if (node.body !== undefined && containsSecretOrLiteral(node.body)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Recursively check if a value contains any secret references or string literals.
+ */
+function containsSecretOrLiteral(value: unknown): boolean {
+  if (value === null || value === undefined) {
+    return false;
+  }
+
+  if (isSecretRef(value) || isStringLiteral(value)) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.some(containsSecretOrLiteral);
+  }
+
+  if (typeof value === "object") {
+    return Object.values(value).some(containsSecretOrLiteral);
+  }
+
+  return false;
+}