@kitiumai/environments

Enterprise-Grade Environment Management for TypeScript Applications

A comprehensive, TypeScript-native toolkit for managing complex application environments with security, compliance, and operational excellence. Provides unified APIs for secrets management, authentication, audit logging, deployment pipelines, change management, and rich ecosystem integrations.

What is this package?

@kitiumai/environments is a complete environment management platform that bridges the gap between development and production operations. It provides:

Unified Environment Abstraction: Single API for managing secrets, configurations, and infrastructure across all environments
Enterprise Security: Built-in authentication, RBAC, audit logging, and compliance reporting
Operational Excellence: Deployment pipelines, change management, monitoring, and automated operations
Developer Experience: TypeScript-native APIs with full type safety and IntelliSense support
Extensibility: Plugin architecture for custom integrations and organization-specific workflows

Why we need this package?

Modern applications require sophisticated environment management that goes beyond simple configuration files. Organizations need:

Security & Compliance: Centralized secrets management with audit trails and compliance reporting
Operational Efficiency: Automated deployment pipelines and change management workflows
Developer Productivity: Type-safe APIs that prevent configuration errors and provide excellent DX
Scalability: Multi-environment hierarchies with inheritance and overrides
Observability: Monitoring, alerting, and operational insights across all environments

Without proper environment management, teams face:

❌ Secrets scattered across multiple systems
❌ Manual deployment processes prone to errors
❌ Lack of audit trails for compliance
❌ Inconsistent configurations between environments
❌ Poor visibility into operational health

Competitor Comparison

Feature	@kitiumai/environments	AWS Systems Manager	Azure App Configuration	HashiCorp Vault	Kubernetes ConfigMaps
TypeScript Native	✅ Full type safety	❌	❌	❌	❌
Secrets Management	✅ Multi-provider	✅ AWS only	❌	✅ Enterprise	❌
Authentication/RBAC	✅ Built-in	✅ AWS IAM	✅ Azure AD	✅ Enterprise	❌
Audit Logging	✅ Structured events	✅ CloudTrail	✅ Activity logs	✅ Enterprise	❌
Deployment Pipelines	✅ Native support	❌	❌	❌	❌
Change Management	✅ Request workflows	❌	❌	❌	❌
Multi-Environment	✅ Hierarchies	✅ Stacks	✅ Environments	❌	❌
Infrastructure as Code	✅ Provider abstraction	✅ CloudFormation	✅ ARM	❌	❌
Monitoring/Alerting	✅ Built-in	✅ CloudWatch	✅ Azure Monitor	❌	❌
Plugin Ecosystem	✅ Extensible	❌	❌	✅ Enterprise	❌
Open Source	✅ MIT License	❌	❌	✅ Enterprise	✅ Apache

Unique Selling Points (USPs)

🔒 TypeScript-First Security

Zero-config secrets: Type-safe secrets access with compile-time validation
RBAC as code: Define permissions and roles in TypeScript with full type checking
Audit as infrastructure: Structured audit events with compliance reporting built-in

🚀 Developer Experience Excellence

IntelliSense everywhere: Full autocomplete for all APIs and configurations
Type-safe configurations: Catch configuration errors at compile time
Unified API surface: Single import for all environment operations

🏗️ Enterprise-Grade Operations

Deployment pipelines: Native CI/CD pipeline management with approvals and rollback
Change management: Structured change request workflows with review processes
Multi-region HA: Built-in high availability with automatic failover

🔌 Rich Ecosystem Integrations

Webhook support: Real-time notifications and external system integration
Plugin architecture: Extend functionality with custom plugins and extensions
Multi-provider secrets: Support for Vault, AWS, GCP, Azure, and custom providers

📊 Operational Visibility

Structured monitoring: Metrics collection with alerting and dashboards
Compliance reporting: Automated compliance checks and violation detection
Backup & recovery: Encrypted backups with integrity verification

Installation

npm install @kitiumai/environments
# or
pnpm add @kitiumai/environments
# or
yarn add @kitiumai/environments

Quick Start

Basic Environment Setup

import { EnvironmentResolver, SecretsBroker } from '@kitiumai/environments';

async function setupEnvironment() {
  // Create environment hierarchy
  const resolver = new EnvironmentResolver();
  const env = await resolver.resolve('production', {
    name: 'web-app',
    secrets: [
      { provider: 'vault', path: 'kv/prod/database' },
      { provider: 'aws', path: 'secrets/api-keys' }
    ]
  });

  // Initialize secrets broker
  const broker = new SecretsBroker(env);
  const secrets = await broker.fetchAll();

  console.log('Environment ready:', env.name);
  console.log('Secrets loaded:', Object.keys(secrets));
}

Authentication & Authorization

import { AuthProvider, RBACAuthProvider } from '@kitiumai/environments';

async function authenticateUser() {
  const auth = new RBACAuthProvider();

  // Authenticate user
  const user = await auth.authenticate('user123:john.doe:admin,developer');

  // Check permissions
  const canDeploy = await auth.authorize(user, {
    resource: 'environments',
    action: 'deploy',
    conditions: { environment: 'production' }
  });

  console.log(`User ${user.username} can deploy:`, canDeploy);
}

Audit Logging & Compliance

import { AuditLogger, ComplianceReport } from '@kitiumai/environments';

async function auditOperations() {
  const audit = new AuditLogger();

  // Log an operation
  await audit.log({
    type: 'environment_update',
    userId: 'user123',
    resource: 'web-app',
    action: 'deploy',
    success: true,
    details: { version: '1.2.3' }
  });

  // Generate compliance report
  const report = await audit.generateComplianceReport(
    new Date('2025-01-01'),
    new Date('2025-12-31')
  );

  console.log('Compliance violations:', report.violations.length);
}

Deployment Pipelines

import { DeploymentPipelineManager } from '@kitiumai/environments';

async function runDeployment() {
  const manager = new DeploymentPipelineManager();

  // Create deployment pipeline
  const pipelineId = manager.createPipeline({
    name: 'web-app-deploy',
    description: 'Production deployment pipeline',
    environments: ['staging', 'production'],
    stages: [
      {
        name: 'build',
        actions: [{ type: 'provision', name: 'build-app' }]
      },
      {
        name: 'test',
        actions: [{ type: 'test', name: 'run-tests' }],
        requiresApproval: true
      },
      {
        name: 'deploy',
        actions: [{ type: 'provision', name: 'deploy-to-prod' }],
        rollbackOnFailure: true
      }
    ]
  });

  // Execute pipeline
  const executionId = await manager.executePipeline(
    pipelineId,
    'production',
    'user123'
  );

  console.log('Deployment started:', executionId);
}

Change Management

import { ChangeManagementSystem } from '@kitiumai/environments';

async function manageChanges() {
  const cms = new ChangeManagementSystem();

  // Create change request
  const changeId = cms.createChangeRequest({
    title: 'Update database schema',
    description: 'Add new user table for authentication',
    environment: 'production',
    changes: [
      {
        type: 'add',
        resource: 'database.migrations',
        newValue: '001_create_users_table.sql',
        description: 'New migration file'
      }
    ],
    createdBy: 'developer123'
  });

  // Submit for review
  cms.submitForReview(changeId);

  // Approve change
  cms.approveChangeRequest(changeId, 'architect456');

  // Implement change
  cms.implementChangeRequest(changeId);

  console.log('Change implemented:', changeId);
}

Ecosystem Integrations

import { IntegrationRegistry, WebhookProvider } from '@kitiumai/environments';

async function setupIntegrations() {
  const registry = new IntegrationRegistry();

  // Register webhook integration
  registry.registerProvider('webhook', new WebhookProvider());

  await registry.registerIntegration({
    id: 'slack-notifications',
    name: 'Slack Notifications',
    type: 'webhook',
    config: {
      url: 'https://hooks.slack.com/services/...',
      events: ['deployment_complete', 'security_alert']
    }
  });

  // Execute integration
  await registry.executeIntegration('slack-notifications', {
    event: 'deployment_complete',
    payload: { app: 'web-app', version: '1.2.3' }
  });

  console.log('Notification sent to Slack');
}

API Reference

Core Classes

EnvironmentResolver

Manages multi-environment hierarchies with inheritance.

class EnvironmentResolver {
  resolve(name: string, spec: EnvironmentSpec): Promise<EnvironmentSpec>
  validate(spec: EnvironmentSpec): ValidationResult
}

SecretsBroker

Unified interface for secrets management across multiple providers.

class SecretsBroker {
  constructor(spec: EnvironmentSpec, options?: SecretsOptions)
  fetchAll(): Promise<Record<string, string>>
  rotateSecrets(): Promise<void>
  getProvider(name: string): SecretsProvider | undefined
}

AuthProvider (Interface)

Authentication and authorization interface.

interface AuthProvider {
  authenticate(token: string): Promise<User>
  authorize(user: User, permission: Permission): Promise<boolean>
}

AuditLogger

Structured audit logging with compliance reporting.

class AuditLogger {
  constructor(sink: AuditSink, config?: AuditConfig)
  log(event: Omit<AuditEvent, 'id' | 'timestamp'>): Promise<void>
  query(filter: AuditQuery): Promise<AuditEvent[]>
  generateComplianceReport(start: Date, end: Date): Promise<ComplianceReport>
}

DeploymentPipelineManager

Manages deployment pipelines with approvals and rollback.

class DeploymentPipelineManager {
  constructor(executor?: DeploymentExecutor)
  createPipeline(pipeline: Omit<DeploymentPipeline, 'id' | 'createdAt' | 'updatedAt'>): string
  executePipeline(pipelineId: string, environment: string, triggeredBy: string): Promise<string>
  getExecution(id: string): DeploymentExecution | undefined
}

ChangeManagementSystem

Structured change request management.

class ChangeManagementSystem {
  createChangeRequest(request: Omit<ChangeRequest, 'id' | 'status' | 'createdAt' | 'comments'>): string
  submitForReview(id: string): boolean
  approveChangeRequest(id: string, reviewedBy: string): boolean
  implementChangeRequest(id: string): boolean
}

IntegrationRegistry

Manages ecosystem integrations (webhooks, APIs, plugins, etc.).

class IntegrationRegistry {
  registerProvider(type: IntegrationType, provider: IntegrationProvider): void
  registerIntegration(config: Omit<IntegrationConfig, 'createdAt' | 'updatedAt'>): Promise<ValidationResult>
  executeIntegration(id: string, context: IntegrationContext): Promise<IntegrationResult>
  getIntegrationStats(): IntegrationStats
}

Type Definitions

EnvironmentSpec

Core environment specification with secrets, toolchains, and policies.

type EnvironmentSpec = {
  name: string;
  description?: string;
  secrets?: SecretProvider[];
  toolchains?: Toolchain[];
  policies?: string[];
  checks?: string[];
  environments?: EnvironmentHierarchy[];
  region?: string;
  backup?: BackupConfig;
}

User & Permission

Authentication and authorization types.

type User = {
  id: string;
  username: string;
  roles: string[];
  tenant?: string;
  metadata?: Record<string, unknown>;
}

type Permission = {
  resource: string;
  action: string;
  conditions?: Record<string, unknown>;
}

AuditEvent

Structured audit event with compliance information.

type AuditEvent = {
  id: string;
  type: AuditEventType;
  timestamp: Date;
  userId?: string;
  username?: string;
  tenant?: string;
  resource: string;
  action: string;
  success: boolean;
  details?: Record<string, unknown>;
  ipAddress?: string;
  userAgent?: string;
  correlationId?: string;
}

DeploymentPipeline

Complete deployment pipeline specification.

type DeploymentPipeline = {
  id: string;
  name: string;
  description?: string;
  stages: DeploymentStage[];
  environments: string[];
  triggers?: DeploymentTrigger[];
  createdAt: Date;
  updatedAt: Date;
}

ChangeRequest

Change management request with approval workflow.

type ChangeRequest = {
  id: string;
  title: string;
  description: string;
  environment: string;
  changes: ChangeItem[];
  status: 'draft' | 'pending_review' | 'approved' | 'rejected' | 'implemented';
  createdBy: string;
  createdAt: Date;
  reviewedBy?: string;
  reviewedAt?: Date;
  implementedAt?: Date;
  comments?: ChangeComment[];
}

IntegrationConfig

Configuration for ecosystem integrations.

type IntegrationConfig = {
  id: string;
  name: string;
  type: IntegrationType;
  description?: string;
  version: string;
  status: IntegrationStatus;
  config: Record<string, unknown>;
  metadata: IntegrationMetadata;
  createdAt: Date;
  updatedAt: Date;
  lastUsedAt?: Date;
}

Advanced Usage

Custom Secret Providers

import { SecretsProvider } from '@kitiumai/environments';

class CustomSecretProvider implements SecretsProvider {
  readonly name = 'custom';

  async fetchSecret(path: string): Promise<string> {
    // Implement custom secret fetching logic
    return `secret-for-${path}`;
  }

  async rotateSecret?(path: string): Promise<void> {
    // Implement secret rotation
  }
}

// Register custom provider
const broker = new SecretsBroker(spec);
broker.registerProvider(new CustomSecretProvider());

Plugin Development

import { Plugin } from '@kitiumai/environments';

const myPlugin: Plugin = {
  name: 'my-plugin',
  version: '1.0.0',
  hooks: {
    onEnvironmentCreate: async (context) => {
      console.log('Environment created:', context.environment.name);
    },
    onSecretFetch: async (context) => {
      console.log('Secret fetched:', context.path);
    }
  }
};

// Register plugin
import { getPluginManager } from '@kitiumai/environments';
const pluginManager = getPluginManager();
pluginManager.register(myPlugin);

Monitoring Integration

import { MonitoringProvider, Metric } from '@kitiumai/environments';

class DataDogProvider implements MonitoringProvider {
  async recordMetric(metric: Metric): Promise<void> {
    // Send to DataDog
    console.log('Metric recorded:', metric.name, metric.value);
  }

  async queryMetrics(query: MetricQuery): Promise<Metric[]> {
    // Query DataDog metrics
    return [];
  }
}

// Use monitoring
const monitoring = new MonitoringProvider(new DataDogProvider());
await monitoring.recordCounter('deployments', 1, { environment: 'prod' });

Configuration

Environment Variables

# Vault Configuration
VAULT_ADDR=https://vault.example.com
VAULT_TOKEN=your-vault-token

# AWS Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

# Azure Configuration
AZURE_KEYVAULT_URL=https://myvault.vault.azure.net
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=your-tenant-id

# GCP Configuration
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GCP_PROJECT_ID=your-project-id

YAML Configuration

# envkit.yaml
name: my-application
description: Production environment configuration

secrets:
  - provider: vault
    path: kv/prod/database
    rotationDays: 30
  - provider: aws
    path: secrets/api-keys

toolchains:
  - name: node
    version: "20"
  - name: python
    version: "3.11"

policies:
  - policies/security.rego
  - policies/compliance.rego

checks:
  - node --version
  - python --version

backup:
  enabled: true
  retentionDays: 30
  regions: ['us-east-1', 'us-west-2']

Security & Compliance

SOC 2 Type II: Full audit trails and compliance reporting
HIPAA: Encrypted secrets with access logging
PCI DSS: Secure secrets management for payment data
GDPR: Data minimization and consent management
Zero Trust: Every operation is authenticated and authorized

Performance

Sub-millisecond: Secrets fetching with caching
Horizontal scaling: Multi-region deployments with automatic failover
Async operations: Non-blocking API calls with proper error handling
Memory efficient: Lazy loading and garbage collection

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
.changeset		.changeset
.github		.github
.husky/_		.husky/_
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
SECURITY.md		SECURITY.md
envkit.yaml		envkit.yaml
eslint.config.js		eslint.config.js
lint-staged.config.cjs		lint-staged.config.cjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
typedoc.json		typedoc.json
vitest.config.ts		vitest.config.ts
vitest.logger.mock.ts		vitest.logger.mock.ts

Latest commit

History

Folders and files

Repository files navigation