/** * Type Definitions for v0.7.0 Configuration Architecture * * BREAKING CHANGE: Complete rewrite with NO backward compatibility. * This module defines the new unified configuration system for multi-environment deployments. * * @module types/config * @version 0.7.0 */ /** * CloudFormation Parameter Names * * These constants define the parameter names used in CloudFormation stacks. * Centralizing these prevents magic string duplication across the codebase. */ export declare const CFN_PARAMS: { /** * BenchlingWebhook parameter in Quilt CloudFormation stack * Controls whether the Quilt stack processes Benchling webhook events * Valid values: "Enabled" | "Disabled" */ readonly BENCHLING_WEBHOOK: "BenchlingWebhook"; }; /** * Configuration profile identifier * Profiles allow multiple named configurations (e.g., "default", "dev", "prod") * * @example "default" * @example "dev" * @example "prod" */ export type ProfileName = string; /** * Profile Configuration (Single Source of Truth) * * This is the primary configuration interface for v0.7.0, replacing the previous * three-tier system (user/derived/deploy). All configuration is now unified in * a single structured format. * * @example * ```json * { * "quilt": { * "catalog": "https://quilt.example.com", * "bucket": "my-quilt-bucket", * "database": "quilt_catalog", * "queueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/quilt-queue", * "region": "us-east-1" * }, * "benchling": { * "tenant": "my-tenant", * "clientId": "client_123", * "secretArn": "arn:aws:secretsmanager:...", * "appDefinitionId": "app_456" * }, * "packages": { * "bucket": "benchling-packages", * "prefix": "benchling", * "metadataKey": "experiment_id" * }, * "deployment": { * "region": "us-east-1", * "imageTag": "latest" * }, * "integratedStack": true, * "_metadata": { * "version": "0.9.0", * "createdAt": "2025-11-04T10:00:00Z", * "updatedAt": "2025-11-04T10:00:00Z", * "source": "wizard" * } * } * ``` */ export interface ProfileConfig { /** * Quilt catalog and infrastructure configuration */ quilt: QuiltConfig; /** * Benchling tenant and OAuth configuration */ benchling: BenchlingConfig; /** * Package storage and metadata configuration */ packages: PackageConfig; /** * AWS deployment configuration (CDK) */ deployment: DeploymentConfig; /** * Deployment mode flag * * - `true`: Integrated mode - uses existing BenchlingSecret in Quilt stack * - `false` or undefined: Standalone mode - creates dedicated secret * * @default false */ integratedStack?: boolean; /** * Optional logging configuration */ logging?: LoggingConfig; /** * Optional security configuration (webhook verification, IP allowlist) */ security?: SecurityConfig; /** * Configuration metadata (provenance, versioning, timestamps) */ _metadata: ConfigMetadata; /** * Optional profile inheritance (for profile hierarchies) * * When present, this profile inherits configuration from the specified base profile. * Values in this profile override inherited values via deep merge. * * @example "_inherits": "default" */ _inherits?: string; } /** * Quilt Catalog Configuration * * Configuration for Quilt data catalog integration, including service endpoints * and SQS queue for package creation. * * **Breaking Change (v0.9.0)**: `stackArn` is used at deployment time only to resolve services. * Services are passed as explicit environment variables to the container. * No runtime CloudFormation API calls are made. * * **Usage**: * - **Deployment time**: `stackArn` used to resolve service endpoints from stack outputs * - **Runtime**: Explicit environment variables are used (no CloudFormation API calls) */ export interface QuiltConfig { /** * Quilt CloudFormation stack ARN (optional) * * Used at deployment time to resolve service endpoints from stack outputs. * The resolved services are then passed as explicit environment variables to the container. * * **Deployment usage only** - not passed to container runtime. * **Breaking Change (v0.9.0)**: No longer passed as environment variable or CloudFormation parameter. * * @example "arn:aws:cloudformation:us-east-1:123456789012:stack/quilt-stack/..." */ stackArn?: string; /** * Quilt catalog domain (without protocol) * * Resolved from stack outputs at deployment time: * - Priority 1: `Catalog` output * - Priority 2: `CatalogDomain` output * - Priority 3: Extract from `ApiGatewayEndpoint` output * * Passed to container as `QUILT_WEB_HOST` environment variable. * * @example "quilt.example.com" */ catalog: string; /** * Athena/Glue database name for catalog metadata * * Resolved from stack output `UserAthenaDatabaseName` at deployment time. * Passed to container as `ATHENA_USER_DATABASE` environment variable. * * @example "quilt_catalog" */ database: string; /** * SQS queue URL for package creation jobs * * Resolved from stack output `PackagerQueueUrl` at deployment time. * Passed to container as `PACKAGER_SQS_URL` environment variable. * * @example "https://sqs.us-east-1.amazonaws.com/123456789012/quilt-package-queue" */ queueUrl: string; /** * AWS region for Quilt resources * * @example "us-east-1" */ region: string; /** * Athena workgroup for user queries (non-managed role) * * Resolved from BenchlingAthenaWorkgroup stack resource * This is a RESOURCE (not an output) - requires DescribeStackResources API * * @example "quilt-user-workgroup-prod" */ athenaUserWorkgroup?: string; /** * IAM policy for Athena user workgroup (non-managed role) * * Resolved from UserAthenaNonManagedRolePolicy stack resource * This is a RESOURCE (not an output) - requires DescribeStackResources API * * @example "quilt-prod-UserAthenaNonManagedRolePolicy-ABC123" */ athenaUserPolicy?: string; /** * IAM managed policy ARN for S3 bucket write access (from BucketWritePolicy) * * This policy grants read-write permissions to all Quilt S3 buckets. * Attached directly to the ECS task role, eliminating the need for role assumption. * Discovered from CloudFormation stack resources during setup. * * Resolved from BucketWritePolicy stack resource (AWS::IAM::ManagedPolicy) * This is a RESOURCE (not an output) - requires DescribeStackResources API * * @example "arn:aws:iam::123456789012:policy/quilt-staging-BucketWritePolicy-XXXXX" */ bucketWritePolicyArn?: string; /** * IAM managed policy ARN for Athena query access (from UserAthenaNonManagedRolePolicy) * * This policy grants permissions to execute Athena queries, access Glue catalog, * and write query results to the Athena results bucket. * Attached directly to the ECS task role. * Discovered from CloudFormation stack resources during setup. * * Resolved from UserAthenaNonManagedRolePolicy stack resource (AWS::IAM::ManagedPolicy) * This is a RESOURCE (not an output) - requires DescribeStackResources API * * @example "arn:aws:iam::123456789012:policy/quilt-staging-UserAthenaNonManagedRolePolicy-XXXXX" */ athenaUserPolicyArn?: string; /** * Iceberg Glue database for single-query bucketless search (optional) * * When set, bucketless PackageQuery searches Iceberg manifest tables instead * of fanning out concurrent Athena queries. Passed to container as * QUILT_ICEBERG_DATABASE. * * @example "icebergdatabase-v9cxuqnwjj5a" */ icebergDatabase?: string; } /** * Benchling Configuration * * OAuth credentials and tenant information for Benchling API integration. */ export interface BenchlingConfig { /** * Benchling tenant identifier (subdomain) * * @example "my-company" */ tenant: string; /** * OAuth client ID * * @example "client_abc123" */ clientId: string; /** * OAuth client secret (optional, for local dev only) * * For production, use `secretArn` instead to reference AWS Secrets Manager. * * @example "secret_xyz789" */ clientSecret?: string; /** * AWS Secrets Manager ARN for OAuth credentials (production) * * @example "arn:aws:secretsmanager:us-east-1:123456789012:secret:benchling-..." */ secretArn?: string; /** * Benchling app definition ID * * @example "app_def_456" */ appDefinitionId: string; /** * Test entry ID for validation (optional) * * @example "etr_abc123" */ testEntryId?: string; } /** * Package Configuration * * S3 storage and metadata settings for Benchling packages. */ export interface PackageConfig { /** * S3 bucket for package storage. * * When omitted, the webhook runs in bucketless mode: it does not create * default packages for unlinked entries and linked-package lookup is not * scoped to a single configured bucket. * * @example "benchling-packages" */ bucket?: string; /** * S3 key prefix for packages * * @example "benchling" * @default "benchling" */ prefix: string; /** * Metadata key for package organization * * @example "experiment_id" * @default "experiment_id" */ metadataKey: string; /** * Optional Quilt workflow name for package creation. * * Empty/undefined uses the Quilt default workflow. * * @example "alpha" */ workflow?: string; /** * Package entries automatically on entry and Canvas events. * * When false, an entry is packaged only when a user clicks Update Package * on its Canvas. Synced to the secret as `auto_packaging`. * * @default true */ autoPackaging?: boolean; } /** * Deployment Configuration * * AWS infrastructure settings for CDK deployment. */ export interface DeploymentConfig { /** * AWS region for deployment * * @example "us-east-1" */ region: string; /** * AWS account ID (optional, auto-detected if not provided) * * @example "123456789012" */ account?: string; /** * ECR repository name (optional, default: "benchling-webhook") * * @example "my-custom-repo" */ ecrRepository?: string; /** * Docker image tag * * @example "latest" * @example "0.7.0" * @default "latest" */ imageTag?: string; /** * CloudFormation stack name (optional) * * If not specified, stack name is auto-generated based on profile: * - "default" profile → "BenchlingWebhookStack" (backwards compatible) * - Other profiles → "BenchlingWebhookStack-{profile}" * * This enables multiple webhook stacks per AWS account/region. * * @example "BenchlingWebhookStack-sales" * @example "BenchlingWebhookStack-customer-acme" * @default Auto-generated based on profile name * @since 0.9.8 */ stackName?: string; /** * VPC configuration for ECS deployment * If not specified, a new VPC will be created with private subnets and NAT Gateway * * @example { vpcId: "vpc-0123456789abcdef0" } */ vpc?: VpcConfig; } /** * VPC Configuration * * Configures VPC for ECS deployment. Supports both existing VPC (by ID) and auto-creation. */ export interface VpcConfig { /** * Existing VPC ID to use (optional) * * If specified, the VPC must have: * - Private subnets with NAT Gateway for outbound internet access * - Proper routing for ECS tasks * * If not specified, a new VPC will be created matching the Quilt production architecture: * - 2 Availability Zones * - Public subnets (for NAT Gateways) * - Private subnets with NAT Gateway (for ECS tasks) * * @example "vpc-0123456789abcdef0" */ vpcId?: string; /** * Private subnet IDs for ECS tasks and NLB * Required when vpcId is specified * Must have ≥2 subnets in different AZs * * Discovered by scripts/discover-vpc.ts during setup wizard. * Subnets are classified as private by analyzing route tables * for NAT Gateway routes (not IGW routes). * * @example ["subnet-0aaa", "subnet-0bbb"] */ privateSubnetIds?: string[]; /** * Public subnet IDs (optional) * Only needed if creating resources that require public subnets * @example ["subnet-0ccc", "subnet-0ddd"] */ publicSubnetIds?: string[]; /** * Availability zones for the subnets * Must match the order and count of privateSubnetIds * @example ["us-east-1a", "us-east-1b"] */ availabilityZones?: string[]; /** * VPC CIDR block * Required when vpcId is specified for CDK synthesis * Discovered by scripts/discover-vpc.ts during setup wizard * @example "10.0.0.0/16" */ vpcCidrBlock?: string; /** * Whether to create a new VPC if vpcId is not specified * * @default true */ createIfMissing?: boolean; } /** * Logging Configuration * * Python logging level for FastAPI application. */ export interface LoggingConfig { /** * Python logging level * * @default "INFO" */ level: "DEBUG" | "INFO" | "WARNING" | "ERROR"; } /** * Security Configuration * * Webhook security settings including IP allowlist and signature verification. */ export interface SecurityConfig { /** * Comma-separated list of allowed IP addresses/CIDR blocks for webhook endpoints * * v1.0.0+: Enforced via REST API Gateway resource policy (free). * Empty string means no IP filtering (all IPs allowed). * Health endpoints are always accessible from any IP. * * @example "192.168.1.0/24,10.0.0.0/8" * @default "" */ webhookAllowList?: string; /** * Enable webhook signature verification in FastAPI application * * @default true */ enableVerification?: boolean; } /** * Configuration Metadata * * Provenance tracking for configuration files. */ export interface ConfigMetadata { /** * Configuration schema version * * @example "0.7.0" */ version: string; /** * ISO 8601 timestamp when configuration was created * * @example "2025-11-04T10:00:00Z" */ createdAt: string; /** * ISO 8601 timestamp when configuration was last updated * * @example "2025-11-04T15:30:00Z" */ updatedAt: string; /** * Source of configuration * * - "wizard": Created via interactive setup wizard * - "manual": Hand-edited by user * - "cli": Created via CLI command */ source: "wizard" | "manual" | "cli"; /** * Additional metadata fields (extensible) */ [key: string]: string | undefined; } /** * Deployment History * * Tracks all deployments for a profile with one active deployment pointer. */ export interface DeploymentHistory { /** * The currently active deployment for this profile, or null if none. */ active: DeploymentRecord | null; /** * Complete deployment history (newest first) * * All past deployments for this profile, ordered by timestamp descending. */ history: DeploymentRecord[]; } /** * Deployment Record * * A single deployment event with full metadata for debugging and rollback. */ export interface DeploymentRecord { /** * ISO 8601 deployment timestamp * * @example "2025-11-04T10:30:00Z" */ timestamp: string; /** * Docker image tag deployed * * @example "latest" * @example "0.7.0" */ imageTag: string; /** * Deployed webhook endpoint URL * * @example "https://abc123.execute-api.us-east-1.amazonaws.com/dev" */ endpoint: string; /** * CloudFormation stack name * * @example "BenchlingWebhookStack" */ stackName: string; /** * AWS region * * @example "us-east-1" */ region: string; /** * User who triggered deployment (optional) * * @example "ernest@example.com" */ deployedBy?: string; /** * Git commit hash (optional) * * @example "abc123f" */ commit?: string; /** * ARN of the Lambda authorizer function (v0.9.1+) */ authorizerArn?: string; /** * CloudWatch log group for Lambda authorizer (v0.9.1+) */ authorizerLogGroup?: string; /** * Additional metadata (extensible) */ [key: string]: string | undefined; } /** * Configuration Validation Result * * Result of configuration validation operations. */ export interface ValidationResult { /** * Whether the configuration is valid */ isValid: boolean; /** * Validation errors (fatal issues that prevent deployment) */ errors: string[]; /** * Validation warnings (non-fatal issues) */ warnings?: string[]; /** * Additional validation details */ details?: Record; } /** * Migration Report * * Result of migrating from legacy configuration format. */ export interface MigrationReport { /** * Whether migration completed successfully */ success: boolean; /** * Profiles that were successfully migrated */ profilesMigrated: string[]; /** * Migration errors */ errors: string[]; /** * Migration warnings (non-fatal issues) */ warnings?: string[]; /** * Additional migration details */ details?: Record; } /** * Profile Management Options */ export interface ProfileOptions { /** * Base configuration directory (defaults to ~/.config/benchling-webhook) */ baseDir?: string; /** * Profile name to use */ profile?: ProfileName; /** * Create profile if it doesn't exist */ createIfMissing?: boolean; } /** * JSON Schema for ProfileConfig validation * * This schema can be used with ajv or other JSON Schema validators. */ export declare const ProfileConfigSchema: { readonly $schema: "http://json-schema.org/draft-07/schema#"; readonly title: "ProfileConfig"; readonly description: "Benchling Webhook Profile Configuration"; readonly type: "object"; readonly required: readonly ["quilt", "benchling", "packages", "deployment", "_metadata"]; readonly properties: { readonly quilt: { readonly type: "object"; readonly required: readonly ["catalog", "database", "queueUrl", "region"]; readonly properties: { readonly stackArn: { readonly type: "string"; readonly pattern: "^arn:aws:cloudformation:"; }; readonly catalog: { readonly type: "string"; readonly minLength: 1; }; readonly database: { readonly type: "string"; readonly minLength: 1; }; readonly queueUrl: { readonly type: "string"; readonly pattern: "^https://sqs\\.[a-z0-9-]+\\.amazonaws\\.com/\\d{12}/.+"; }; readonly region: { readonly type: "string"; readonly pattern: "^[a-z]{2}-[a-z]+-[0-9]$"; }; readonly athenaUserWorkgroup: { readonly type: "string"; readonly minLength: 1; }; readonly bucketWritePolicyArn: { readonly type: "string"; readonly pattern: "^arn:aws:iam::\\d{12}:policy/.+"; }; readonly athenaUserPolicyArn: { readonly type: "string"; readonly pattern: "^arn:aws:iam::\\d{12}:policy/.+"; }; readonly icebergDatabase: { readonly type: "string"; readonly minLength: 1; }; }; }; readonly benchling: { readonly type: "object"; readonly required: readonly ["tenant", "clientId", "appDefinitionId"]; readonly properties: { readonly tenant: { readonly type: "string"; readonly minLength: 1; }; readonly clientId: { readonly type: "string"; readonly minLength: 1; }; readonly clientSecret: { readonly type: "string"; }; readonly secretArn: { readonly type: "string"; readonly pattern: "^arn:aws:secretsmanager:"; }; readonly appDefinitionId: { readonly type: "string"; readonly minLength: 1; }; readonly testEntryId: { readonly type: "string"; }; }; }; readonly packages: { readonly type: "object"; readonly required: readonly ["prefix", "metadataKey"]; readonly properties: { readonly bucket: { readonly type: "string"; readonly minLength: 3; }; readonly prefix: { readonly type: "string"; readonly minLength: 1; }; readonly metadataKey: { readonly type: "string"; readonly minLength: 1; }; readonly workflow: { readonly type: "string"; readonly minLength: 1; }; readonly autoPackaging: { readonly type: "boolean"; }; }; }; readonly deployment: { readonly type: "object"; readonly required: readonly ["region"]; readonly properties: { readonly region: { readonly type: "string"; readonly pattern: "^[a-z]{2}-[a-z]+-[0-9]$"; }; readonly account: { readonly type: "string"; readonly pattern: "^[0-9]{12}$"; }; readonly ecrRepository: { readonly type: "string"; }; readonly imageTag: { readonly type: "string"; }; readonly stackName: { readonly type: "string"; readonly minLength: 1; readonly maxLength: 128; }; }; }; readonly integratedStack: { readonly type: "boolean"; }; readonly logging: { readonly type: "object"; readonly properties: { readonly level: { readonly type: "string"; readonly enum: readonly ["DEBUG", "INFO", "WARNING", "ERROR"]; }; }; }; readonly security: { readonly type: "object"; readonly properties: { readonly webhookAllowList: { readonly type: "string"; }; readonly enableVerification: { readonly type: "boolean"; }; }; }; readonly _metadata: { readonly type: "object"; readonly required: readonly ["version", "createdAt", "updatedAt", "source"]; readonly properties: { readonly version: { readonly type: "string"; }; readonly createdAt: { readonly type: "string"; readonly format: "date-time"; }; readonly updatedAt: { readonly type: "string"; readonly format: "date-time"; }; readonly source: { readonly type: "string"; readonly enum: readonly ["wizard", "manual", "cli"]; }; }; }; readonly _inherits: { readonly type: "string"; }; }; readonly additionalProperties: true; }; export declare const DeploymentHistorySchema: { readonly $schema: "http://json-schema.org/draft-07/schema#"; readonly title: "DeploymentHistory"; readonly description: "Deployment tracking for a profile"; readonly type: "object"; readonly required: readonly ["active", "history"]; readonly properties: { readonly active: { readonly oneOf: readonly [{ readonly type: "object"; readonly required: readonly ["timestamp", "imageTag", "endpoint", "stackName", "region"]; readonly properties: { readonly timestamp: { readonly type: "string"; readonly format: "date-time"; }; readonly imageTag: { readonly type: "string"; }; readonly endpoint: { readonly type: "string"; readonly format: "uri"; }; readonly stackName: { readonly type: "string"; }; readonly region: { readonly type: "string"; }; readonly deployedBy: { readonly type: "string"; }; readonly commit: { readonly type: "string"; }; }; readonly additionalProperties: true; }, { readonly type: "null"; }]; }; readonly history: { readonly type: "array"; readonly items: { readonly type: "object"; readonly required: readonly ["timestamp", "imageTag", "endpoint", "stackName", "region"]; readonly properties: { readonly timestamp: { readonly type: "string"; readonly format: "date-time"; }; readonly imageTag: { readonly type: "string"; }; readonly endpoint: { readonly type: "string"; readonly format: "uri"; }; readonly stackName: { readonly type: "string"; }; readonly region: { readonly type: "string"; }; readonly deployedBy: { readonly type: "string"; }; readonly commit: { readonly type: "string"; }; }; readonly additionalProperties: true; }; }; }; readonly additionalProperties: false; }; /** * Get CloudFormation stack name for a profile * * Implements profile-based naming strategy with backwards compatibility: * - "default" profile → "BenchlingWebhookStack" (legacy name) * - Other profiles → "BenchlingWebhookStack-{profile}" * - Custom name in config → Use as-is * * @param profile - Profile name * @param customName - Optional custom stack name from deployment config * @returns CloudFormation stack name * * @example * getStackName("default") // "BenchlingWebhookStack" * getStackName("sales") // "BenchlingWebhookStack-sales" * getStackName("dev", "MyCustomStack") // "MyCustomStack" * * @since 0.9.8 */ export declare function getStackName(profile: string, customName?: string): string; //# sourceMappingURL=config.d.ts.map