@griffin-app/griffin-plan-executor 0.1.0

package/src/index.ts

@@ -0,0 +1,69 @@
+export { executePlanV1 } from "./executor.js";
+export type {
+  ExecutionOptions,
+  ExecutionResult,
+  NodeResult,
+  HttpClientAdapter,
+  HttpRequest,
+  HttpResponse,
+} from "./types.js";
+export type {
+  TestPlan,
+  Endpoint,
+  WaitNode,
+  AssertionNode,
+  Edge,
+} from "./test-plan-types.js";
+export {
+  AxiosAdapter,
+  StubAdapter,
+  type StubResponse,
+} from "./adapters/index.js";
+
+export {
+  LocalEventEmitter,
+  DurableEventEmitter,
+  type ExecutionEventEmitter,
+  type DurableEventBusAdapter,
+} from "./events/emitter.js";
+export type {
+  ExecutionEvent,
+  BaseEvent,
+  PlanStartEvent,
+  PlanEndEvent,
+  NodeStartEvent,
+  NodeEndEvent,
+  HttpRequestEvent,
+  HttpResponseEvent,
+  HttpRetryEvent,
+  AssertionResultEvent,
+  WaitStartEvent,
+  NodeStreamEvent,
+  ErrorEvent,
+} from "./events/types.js";
+
+// Export secrets system
+export {
+  // Core types and utilities
+  type SecretProvider,
+  type SecretRef,
+  type SecretRefData,
+  type SecretResolveOptions,
+  SecretResolutionError,
+  isSecretRef,
+  // Registry
+  SecretProviderRegistry,
+  // Resolution utilities
+  resolveSecretsInPlan,
+  collectSecretsFromPlan,
+  planHasSecrets,
+  // Providers
+  EnvSecretProvider,
+  type EnvSecretProviderOptions,
+  AwsSecretsManagerProvider,
+  type AwsSecretsManagerProviderOptions,
+  type AwsSecretsManagerClient,
+  VaultProvider,
+  type VaultProviderOptions,
+  type VaultHttpClient,
+} from "./secrets/index.js";

package/src/secrets/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Secret management for griffin plan executor.
+ *
+ * This module provides:
+ * - SecretProvider interface for implementing custom providers
+ * - SecretProviderRegistry for managing multiple providers
+ * - Secret resolution utilities for test plans
+ * - Built-in providers: env, aws, vault
+ */
+
+// Core types
+export {
+  type SecretProvider,
+  type SecretRef,
+  type SecretRefData,
+  type SecretResolveOptions,
+  SecretResolutionError,
+  isSecretRef,
+} from "./types.js";
+
+// Registry
+export { SecretProviderRegistry } from "./registry.js";
+
+// Resolution utilities
+export {
+  resolveSecretsInPlan,
+  collectSecretsFromPlan,
+  planHasSecrets,
+} from "./resolver.js";
+
+// Providers
+export {
+  EnvSecretProvider,
+  type EnvSecretProviderOptions,
+  AwsSecretsManagerProvider,
+  type AwsSecretsManagerProviderOptions,
+  type AwsSecretsManagerClient,
+  VaultProvider,
+  type VaultProviderOptions,
+  type VaultHttpClient,
+} from "./providers/index.js";

package/src/secrets/providers/aws.ts

@@ -0,0 +1,179 @@
+/**
+ * AWS Secrets Manager secret provider.
+ *
+ * Reads secrets from AWS Secrets Manager. Supports JSON secrets
+ * with field extraction and version staging.
+ *
+ * Usage in DSL:
+ *   secret("aws:my-secret")
+ *   secret("aws:prod/api-keys", { field: "stripe" })
+ *   secret("aws:my-secret", { version: "AWSPREVIOUS" })
+ */
+
+import type { SecretProvider, SecretResolveOptions } from "../types.js";
+import { SecretResolutionError } from "../types.js";
+
+/**
+ * Interface for AWS Secrets Manager client.
+ * This allows dependency injection of the actual AWS SDK client.
+ */
+export interface AwsSecretsManagerClient {
+  getSecretValue(params: { SecretId: string; VersionStage?: string }): Promise<{
+    SecretString?: string;
+    SecretBinary?: Uint8Array;
+  }>;
+}
+
+export interface AwsSecretsManagerProviderOptions {
+  /**
+   * AWS Secrets Manager client instance.
+   * Should be pre-configured with region and credentials.
+   */
+  client: AwsSecretsManagerClient;
+
+  /**
+   * Optional prefix for secret names.
+   * For example, if prefix is "myapp/", then secret("aws:api-key")
+   * will look for "myapp/api-key" in Secrets Manager.
+   */
+  prefix?: string;
+
+  /**
+   * Default version stage to use if not specified.
+   * Defaults to "AWSCURRENT".
+   */
+  defaultVersionStage?: string;
+}
+
+export class AwsSecretsManagerProvider implements SecretProvider {
+  readonly name = "aws";
+  private readonly client: AwsSecretsManagerClient;
+  private readonly prefix: string;
+  private readonly defaultVersionStage: string;
+
+  // Simple in-memory cache with TTL
+  private cache = new Map<string, { value: string; expires: number }>();
+  private readonly cacheTtlMs = 5 * 60 * 1000; // 5 minutes
+
+  constructor(options: AwsSecretsManagerProviderOptions) {
+    this.client = options.client;
+    this.prefix = options.prefix ?? "";
+    this.defaultVersionStage = options.defaultVersionStage ?? "AWSCURRENT";
+  }
+
+  async resolve(ref: string, options?: SecretResolveOptions): Promise<string> {
+    const secretId = this.prefix + ref;
+    const versionStage = options?.version ?? this.defaultVersionStage;
+    const cacheKey = `${secretId}:${versionStage}`;
+
+    // Check cache
+    const cached = this.cache.get(cacheKey);
+    if (cached && cached.expires > Date.now()) {
+      return this.extractField(cached.value, options?.field, ref);
+    }
+
+    try {
+      const response = await this.client.getSecretValue({
+        SecretId: secretId,
+        VersionStage: versionStage,
+      });
+
+      if (!response.SecretString) {
+        throw new SecretResolutionError(
+          `Secret "${secretId}" does not contain a string value (binary secrets are not supported)`,
+          { provider: this.name, ref },
+        );
+      }
+
+      // Cache the raw value
+      this.cache.set(cacheKey, {
+        value: response.SecretString,
+        expires: Date.now() + this.cacheTtlMs,
+      });
+
+      return this.extractField(response.SecretString, options?.field, ref);
+    } catch (error) {
+      if (error instanceof SecretResolutionError) {
+        throw error;
+      }
+
+      // Handle common AWS errors
+      const awsError = error as { name?: string; message?: string };
+      let message = `Failed to retrieve secret "${secretId}"`;
+
+      if (awsError.name === "ResourceNotFoundException") {
+        message = `Secret "${secretId}" not found in AWS Secrets Manager`;
+      } else if (awsError.name === "AccessDeniedException") {
+        message = `Access denied to secret "${secretId}". Check IAM permissions.`;
+      } else if (awsError.message) {
+        message = `${message}: ${awsError.message}`;
+      }
+
+      throw new SecretResolutionError(message, {
+        provider: this.name,
+        ref,
+        cause: error,
+      });
+    }
+  }
+
+  /**
+   * Extract a field from a JSON secret string.
+   */
+  private extractField(
+    secretValue: string,
+    field: string | undefined,
+    ref: string,
+  ): string {
+    if (!field) {
+      return secretValue;
+    }
+
+    try {
+      const parsed = JSON.parse(secretValue);
+
+      if (typeof parsed !== "object" || parsed === null) {
+        throw new SecretResolutionError(
+          `Secret "${ref}" is not a JSON object, cannot extract field "${field}"`,
+          { provider: this.name, ref },
+        );
+      }
+
+      const value = parsed[field];
+
+      if (value === undefined) {
+        throw new SecretResolutionError(
+          `Field "${field}" not found in secret "${ref}"`,
+          { provider: this.name, ref },
+        );
+      }
+
+      // Convert to string if not already
+      return typeof value === "string" ? value : JSON.stringify(value);
+    } catch (error) {
+      if (error instanceof SecretResolutionError) {
+        throw error;
+      }
+
+      throw new SecretResolutionError(
+        `Failed to parse secret "${ref}" as JSON for field extraction: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        { provider: this.name, ref, cause: error },
+      );
+    }
+  }
+
+  async validate(): Promise<void> {
+    // Try a simple operation to verify credentials
+    // This is a no-op if the client is properly configured
+    // The actual validation happens on first secret access
+  }
+
+  /**
+   * Clear the cache. Useful for testing or forced refresh.
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+}

package/src/secrets/providers/env.ts

@@ -0,0 +1,66 @@
+/**
+ * Environment variable secret provider.
+ *
+ * Reads secrets from process.env. Useful for local development
+ * and simple deployments where secrets are injected as environment variables.
+ *
+ * Usage in DSL:
+ *   secret("env:MY_API_KEY")
+ *   secret("env:DATABASE_URL")
+ */
+
+import type { SecretProvider, SecretResolveOptions } from "../types.js";
+import { SecretResolutionError } from "../types.js";
+
+export interface EnvSecretProviderOptions {
+  /**
+   * Custom environment object to read from.
+   * Defaults to process.env.
+   */
+  env?: Record<string, string | undefined>;
+
+  /**
+   * Prefix to strip from secret refs.
+   * For example, if prefix is "APP_", then secret("env:API_KEY")
+   * will look for "APP_API_KEY" in the environment.
+   */
+  prefix?: string;
+}
+
+export class EnvSecretProvider implements SecretProvider {
+  readonly name = "env";
+  private readonly env: Record<string, string | undefined>;
+  private readonly prefix: string;
+
+  constructor(options: EnvSecretProviderOptions = {}) {
+    this.env = options.env ?? process.env;
+    this.prefix = options.prefix ?? "";
+  }
+
+  async resolve(ref: string, _options?: SecretResolveOptions): Promise<string> {
+    const envKey = this.prefix + ref;
+    const value = this.env[envKey];
+
+    if (value === undefined) {
+      throw new SecretResolutionError(
+        `Environment variable "${envKey}" is not set`,
+        { provider: this.name, ref },
+      );
+    }
+
+    return value;
+  }
+
+  async resolveMany(
+    refs: Array<{ ref: string; options?: SecretResolveOptions }>,
+  ): Promise<Map<string, string>> {
+    const results = new Map<string, string>();
+
+    for (const { ref } of refs) {
+      const value = await this.resolve(ref);
+      results.set(ref, value);
+    }
+
+    return results;
+  }
+}

package/src/secrets/providers/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Secret provider implementations.
+ */
+
+export { EnvSecretProvider, type EnvSecretProviderOptions } from "./env.js";
+export {
+  AwsSecretsManagerProvider,
+  type AwsSecretsManagerProviderOptions,
+  type AwsSecretsManagerClient,
+} from "./aws.js";
+export {
+  VaultProvider,
+  type VaultProviderOptions,
+  type VaultHttpClient,
+} from "./vault.js";

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`,
+          { provider: this.name, ref },
+        );
+      }
+
+      if (response.status === 403) {
+        throw new SecretResolutionError(
+          `Access denied to secret "${secretPath}". Check Vault policies.`,
+          { provider: this.name, ref },
+        );
+      }
+
+      if (response.status !== 200) {
+        throw new SecretResolutionError(
+          `Vault returned status ${response.status} for secret "${secretPath}"`,
+          { provider: this.name, 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}"`,
+            { provider: this.name, 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}"`,
+            { provider: this.name, 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)
+        }`,
+        { provider: this.name, 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}"`,
+        { provider: this.name, 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();
+  }
+}