@griffin-app/griffin-executor 0.1.0

package/src/index.ts

@@ -0,0 +1,81 @@
+export { executeMonitorV1 } from "./executor.js";
+export type {
+  ExecutionOptions,
+  ExecutionResult,
+  NodeResult,
+  HttpClientAdapter,
+  HttpRequest,
+  HttpResponse,
+  RunStatusUpdate,
+  StatusCallbacks,
+} from "./types.js";
+export type {
+  TestMonitor,
+  HttpRequest as HttpRequestNode,
+  WaitNode,
+  AssertionNode,
+  Edge,
+} from "./test-monitor-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,
+  MonitorStartEvent,
+  MonitorEndEvent,
+  NodeStartEvent,
+  NodeEndEvent,
+  HttpRequestEvent,
+  HttpResponseEvent,
+  HttpRetryEvent,
+  AssertionResultEvent,
+  WaitStartEvent,
+  NodeStreamEvent,
+  ErrorEvent,
+} from "./events/types.js";
+export {
+  // Event bus adapters
+  KinesisAdapter,
+  type KinesisAdapterOptions,
+  InMemoryAdapter,
+} from "./events/adapters/index.js";
+
+// Export secrets system
+export {
+  // Core types and utilities
+  type SecretProvider,
+  type SecretRef,
+  type SecretRefData,
+  type SecretResolveOptions,
+  SecretResolutionError,
+  isSecretRef,
+  // Resolution utilities
+  resolveSecretsInMonitor,
+  collectSecretsFromMonitor,
+  planHasSecrets,
+  // Providers
+  EnvSecretProvider,
+  type EnvSecretProviderOptions,
+  AwsSecretsManagerProvider,
+  type AwsSecretsManagerProviderOptions,
+  type AwsSecretsManagerClient,
+  VaultProvider,
+  type VaultProviderOptions,
+  type VaultHttpClient,
+  // Factory functions
+  createSecretProvider,
+  type SecretProviderConfig,
+  type EnvProviderConfig,
+  type AwsProviderConfig,
+  type VaultProviderConfig,
+} from "./secrets/index.js";

package/src/secrets/factory.ts

@@ -0,0 +1,248 @@
+/**
+ * Factory for creating SecretProvider instances from configuration.
+ * 
+ * This module provides pure factory functions that construct providers
+ * from config objects. Callers (hub, CLI, agents) are responsible for
+ * sourcing the configuration from their environment.
+ */
+
+import type { SecretProvider } from "./types.js";
+import { EnvSecretProvider } from "./providers/env.js";
+import { AwsSecretsManagerProvider, type AwsSecretsManagerClient } from "./providers/aws.js";
+import { VaultProvider, type VaultHttpClient } from "./providers/vault.js";
+import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";
+import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";
+
+
+/**
+ * Configuration for environment variable provider.
+ */
+export interface EnvProviderConfig {
+  provider: "env";
+  /**
+   * Optional prefix to prepend to secret refs.
+   * For example, prefix="APP_" means secret("env:API_KEY") looks for "APP_API_KEY".
+   */
+  prefix?: string;
+  /**
+   * Custom environment object to read from.
+   * If not provided, caller should pass process.env.
+   */
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * Configuration for AWS Secrets Manager provider.
+ */
+export interface AwsProviderConfig {
+  provider: "aws";
+  /**
+   * AWS region for Secrets Manager.
+   */
+  region: string;
+  /**
+   * Optional prefix for secret names.
+   * For example, prefix="myapp/" means secret("aws:api-key") looks for "myapp/api-key".
+   */
+  prefix?: string;
+  /**
+   * Optional IAM role to assume.
+   */
+  roleArn?: string;
+  /**
+   * Optional external ID for role assumption.
+   */
+  externalId?: string;
+  /**
+   * AWS credentials. If not provided, uses ambient credentials (IAM role, environment, etc).
+   */
+  credentials?: {
+    accessKeyId: string;
+    secretAccessKey: string;
+  };
+}
+
+/**
+ * Configuration for HashiCorp Vault provider.
+ */
+export interface VaultProviderConfig {
+  provider: "vault";
+  /**
+   * Vault server address (e.g., "https://vault.example.com").
+   */
+  address: string;
+  /**
+   * Vault authentication token.
+   */
+  token: string;
+  /**
+   * Optional Vault namespace.
+   */
+  namespace?: string;
+  /**
+   * KV secrets engine version (1 or 2). Defaults to 2.
+   */
+  kvVersion?: 1 | 2;
+  /**
+   * Optional prefix for secret paths.
+   */
+  prefix?: string;
+}
+
+/**
+ * Union type for all provider configurations.
+ */
+export type SecretProviderConfig =
+  | EnvProviderConfig
+  | AwsProviderConfig
+  | VaultProviderConfig;
+
+/**
+ * Create a SecretProvider from configuration.
+ * 
+ * This is a pure factory function - it does not access environment variables
+ * or external state. All configuration must be provided by the caller.
+ * 
+ * @example
+ * // Environment provider
+ * const envProvider = await createSecretProvider({
+ *   provider: "env",
+ *   prefix: "APP_",
+ *   env: process.env,
+ * });
+ * 
+ * @example
+ * // AWS provider with credentials
+ * const awsProvider = await createSecretProvider({
+ *   provider: "aws",
+ *   region: "us-east-1",
+ *   prefix: "myapp/",
+ *   credentials: {
+ *     accessKeyId: "...",
+ *     secretAccessKey: "...",
+ *   },
+ * });
+ * 
+ * @example
+ * // Vault provider
+ * const vaultProvider = await createSecretProvider({
+ *   provider: "vault",
+ *   address: "https://vault.example.com",
+ *   token: "...",
+ *   kvVersion: 2,
+ * });
+ */
+export async function createSecretProvider(
+  config: SecretProviderConfig,
+): Promise<SecretProvider> {
+  switch (config.provider) {
+    case "env":
+      return new EnvSecretProvider({
+        prefix: config.prefix,
+        env: config.env,
+      });
+
+    case "aws":
+      return createAwsProvider(config);
+
+    case "vault":
+      return createVaultProvider(config);
+
+    default:
+      const exhaustive: never = config;
+      throw new Error(`Unknown provider type: ${(exhaustive as any).provider}`);
+  }
+}
+
+/**
+ * Create AWS Secrets Manager provider with SDK client.
+ */
+async function createAwsProvider(
+  config: AwsProviderConfig,
+): Promise<AwsSecretsManagerProvider> {
+
+
+  const clientConfig: {
+    region: string;
+    credentials?: {
+      accessKeyId: string;
+      secretAccessKey: string;
+      sessionToken?: string;
+    };
+  } = { region: config.region };
+
+  // Handle role assumption if roleArn is provided
+  if (config.roleArn) {
+    const stsClient = new STSClient({ region: config.region });
+    const assumeRoleResponse = await stsClient.send(
+      new AssumeRoleCommand({
+        RoleArn: config.roleArn,
+        RoleSessionName: "griffin-executor",
+        ExternalId: config.externalId,
+      }),
+    );
+
+    if (assumeRoleResponse.Credentials) {
+      clientConfig.credentials = {
+        accessKeyId: assumeRoleResponse.Credentials.AccessKeyId ?? "",
+        secretAccessKey: assumeRoleResponse.Credentials.SecretAccessKey ?? "",
+        sessionToken: assumeRoleResponse.Credentials.SessionToken,
+      };
+    }
+  } else if (config.credentials) {
+    clientConfig.credentials = config.credentials;
+  }
+  // Otherwise uses ambient AWS credentials (IAM role, environment variables, etc)
+
+  const smClient = new SecretsManagerClient(clientConfig);
+
+  // Wrap SDK client with the interface expected by AwsSecretsManagerProvider
+  const client: AwsSecretsManagerClient = {
+    async getSecretValue(params: { SecretId: string; VersionStage?: string }) {
+      const command = new GetSecretValueCommand({
+        SecretId: params.SecretId,
+        VersionStage: params.VersionStage,
+      });
+      const response = await smClient.send(command);
+      return {
+        SecretString: response.SecretString,
+        SecretBinary: response.SecretBinary,
+      };
+    },
+  };
+
+  return new AwsSecretsManagerProvider({
+    client,
+    prefix: config.prefix,
+  });
+}
+
+/**
+ * Create Vault provider with HTTP client.
+ */
+function createVaultProvider(config: VaultProviderConfig): VaultProvider {
+  // Create HTTP client for Vault API calls
+  const httpClient: VaultHttpClient = {
+    async get(url: string, options: { headers: Record<string, string> }) {
+      // Import axios dynamically to avoid bundling it when not needed
+      const axios = await import("axios");
+      const response = await axios.default.get(url, {
+        headers: options.headers,
+        validateStatus: () => true, // Don't throw on non-2xx
+      });
+      return {
+        status: response.status,
+        data: response.data,
+      };
+    },
+  };
+
+  return new VaultProvider({
+    address: config.address,
+    token: config.token,
+    httpClient,
+    namespace: config.namespace,
+    kvVersion: config.kvVersion ?? 2,
+    prefix: config.prefix,
+  });
+}

package/src/secrets/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Secret management for griffin monitor executor.
+ *
+ * This module provides:
+ * - SecretProvider interface for implementing custom providers
+ * - Secret resolution utilities for test monitors
+ * - Built-in providers: env, aws, vault
+ * - Factory functions for creating providers from configuration
+ */
+
+// Core types
+export {
+  type SecretProvider,
+  type SecretRef,
+  type SecretRefData,
+  type SecretResolveOptions,
+  SecretResolutionError,
+  isSecretRef,
+  isStringLiteral,
+} from "./types.js";
+
+// Resolution utilities
+export {
+  resolveSecretsInMonitor,
+  collectSecretsFromMonitor,
+  planHasSecrets,
+} from "./resolver.js";
+
+// Providers
+export {
+  EnvSecretProvider,
+  type EnvSecretProviderOptions,
+  AwsSecretsManagerProvider,
+  type AwsSecretsManagerProviderOptions,
+  type AwsSecretsManagerClient,
+  VaultProvider,
+  type VaultProviderOptions,
+  type VaultHttpClient,
+} from "./providers/index.js";
+
+// Factory functions
+export {
+  createSecretProvider,
+  type SecretProviderConfig,
+  type EnvProviderConfig,
+  type AwsProviderConfig,
+  type VaultProviderConfig,
+} from "./factory.js";

package/src/secrets/providers/aws.ts

@@ -0,0 +1,178 @@
+/**
+ * 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)`,
+          { 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, {
+        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}"`,
+          { ref },
+        );
+      }
+
+      const value = parsed[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);
+    } 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)
+        }`,
+        { 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`,
+        { 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";