@enspirit/emb 0.15.0 → 0.17.5

package/dist/src/monorepo/plugins/VaultPlugin.js

@@ -0,0 +1,91 @@
+import { getContext } from '../../context.js';
+import { VaultProvider, } from '../../secrets/providers/VaultProvider.js';
+import { AbstractPlugin } from './plugin.js';
+/**
+ * Plugin that integrates HashiCorp Vault with EMB.
+ *
+ * Usage in .emb.yml:
+ * ```yaml
+ * plugins:
+ *   - name: vault
+ *     config:
+ *       address: ${env:VAULT_ADDR:-http://localhost:8200}
+ *       auth:
+ *         method: token
+ *         token: ${env:VAULT_TOKEN}
+ * ```
+ *
+ * Then use secrets in templates:
+ * ```yaml
+ * env:
+ *   DB_PASSWORD: ${vault:secret/myapp/db#password}
+ * ```
+ */
+export class VaultPlugin extends AbstractPlugin {
+    static name = 'vault';
+    provider = null;
+    async init() {
+        const resolvedConfig = this.resolveConfig();
+        this.provider = new VaultProvider(resolvedConfig);
+        await this.provider.connect();
+        // Register the provider with the global SecretManager
+        const context = getContext();
+        if (context?.secrets) {
+            context.secrets.register('vault', this.provider);
+        }
+    }
+    /**
+     * Resolve the plugin configuration, filling in defaults from env vars.
+     */
+    resolveConfig() {
+        const address = this.config.address || process.env.VAULT_ADDR;
+        if (!address) {
+            throw new Error('Vault address not configured. Set VAULT_ADDR environment variable or configure address in plugin config.');
+        }
+        const auth = this.resolveAuth();
+        return {
+            address,
+            namespace: this.config.namespace || process.env.VAULT_NAMESPACE,
+            auth,
+        };
+    }
+    /**
+     * Resolve authentication configuration.
+     */
+    resolveAuth() {
+        // If explicit auth config is provided, use it
+        if (this.config.auth) {
+            return this.config.auth;
+        }
+        // Try to infer from environment
+        const token = process.env.VAULT_TOKEN;
+        if (token) {
+            return { method: 'token', token };
+        }
+        const roleId = process.env.VAULT_ROLE_ID;
+        const secretId = process.env.VAULT_SECRET_ID;
+        if (roleId && secretId) {
+            return { method: 'approle', roleId, secretId };
+        }
+        const k8sRole = process.env.VAULT_K8S_ROLE;
+        if (k8sRole) {
+            return { method: 'kubernetes', role: k8sRole };
+        }
+        // JWT auth (non-interactive, for CI/CD)
+        const jwt = process.env.VAULT_JWT;
+        const jwtRole = process.env.VAULT_JWT_ROLE;
+        if (jwt && jwtRole) {
+            return { method: 'jwt', role: jwtRole, jwt };
+        }
+        // OIDC auth (interactive browser flow)
+        const oidcRole = process.env.VAULT_OIDC_ROLE;
+        if (oidcRole !== undefined) {
+            return { method: 'oidc', role: oidcRole || undefined };
+        }
+        throw new Error('Vault authentication not configured. ' +
+            'Set VAULT_TOKEN, or VAULT_ROLE_ID + VAULT_SECRET_ID, ' +
+            'or VAULT_K8S_ROLE, or VAULT_JWT + VAULT_JWT_ROLE, ' +
+            'or VAULT_OIDC_ROLE environment variable, ' +
+            'or configure auth in plugin config.');
+    }
+}

package/dist/src/monorepo/plugins/index.d.ts

@@ -2,6 +2,7 @@ import { AbstractPlugin } from './plugin.js';
 export * from './AutoDockerPlugin.js';
 export * from './DotEnvPlugin.js';
 export * from './EmbfileLoaderPlugin.js';
+export * from './VaultPlugin.js';
 import { Monorepo } from '../index.js';
 export type AbstractPluginConstructor = new <C, P extends AbstractPlugin<C>>(config: C, monorepo: Monorepo) => P;
 export declare const registerPlugin: (plugin: AbstractPluginConstructor) => void;

package/dist/src/monorepo/plugins/index.js

@@ -1,9 +1,11 @@
 export * from './AutoDockerPlugin.js';
 export * from './DotEnvPlugin.js';
 export * from './EmbfileLoaderPlugin.js';
+export * from './VaultPlugin.js';
 import { AutoDockerPlugin } from './AutoDockerPlugin.js';
 import { DotEnvPlugin } from './DotEnvPlugin.js';
 import { EmbfileLoaderPlugin } from './EmbfileLoaderPlugin.js';
+import { VaultPlugin } from './VaultPlugin.js';
 const PluginRegistry = new Map();
 export const registerPlugin = (plugin) => {
     if (PluginRegistry.has(plugin.name)) {
@@ -21,3 +23,4 @@ export const getPlugin = (name) => {
 registerPlugin(AutoDockerPlugin);
 registerPlugin(DotEnvPlugin);
 registerPlugin(EmbfileLoaderPlugin);
+registerPlugin(VaultPlugin);

package/dist/src/secrets/SecretDiscovery.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Location where a secret reference was found.
+ */
+export interface SecretLocation {
+    /** Component name (if applicable) */
+    component?: string;
+    /** Field path within the config (e.g., "env.DB_PASSWORD") */
+    field: string;
+    /** File path where the reference was found */
+    file?: string;
+}
+/**
+ * A discovered secret reference in the configuration.
+ */
+export interface DiscoveredSecret {
+    /** Key within the secret (e.g., "password") */
+    key?: string;
+    /** Where this reference was found */
+    location: SecretLocation;
+    /** Original template string (e.g., "${vault:secret/myapp#password}") */
+    original: string;
+    /** Path to the secret (e.g., "secret/myapp/db") */
+    path: string;
+    /** Provider name (e.g., "vault") */
+    provider: string;
+}
+/**
+ * Discover all secret references in a configuration object.
+ *
+ * @param config - The configuration object to scan
+ * @param location - Base location information
+ * @param secretProviders - Set of registered secret provider names to look for
+ * @returns Array of discovered secret references
+ */
+export declare function discoverSecrets(config: Record<string, unknown>, location?: Omit<SecretLocation, 'field'>, secretProviders?: Set<string>): DiscoveredSecret[];
+/**
+ * Deduplicate secret references by provider+path+key.
+ * Keeps track of all locations where each secret is used.
+ */
+export interface AggregatedSecret {
+    key?: string;
+    locations: SecretLocation[];
+    path: string;
+    provider: string;
+}
+export declare function aggregateSecrets(secrets: DiscoveredSecret[]): AggregatedSecret[];

package/dist/src/secrets/SecretDiscovery.js

@@ -0,0 +1,82 @@
+// Matches ${provider:path#key} patterns for secret providers
+// We're specifically looking for non-env providers (vault, aws, azure, etc.)
+const SECRET_REGEX = /\${(\w+):([\w/.]+(?:-[\w/.]+)*)(?:#([\w-]+))?(?::-[^}]*)?}/g;
+/**
+ * Recursively find all secret references in an object.
+ */
+// eslint-disable-next-line max-params
+function findSecretsInValue(value, fieldPath, location, secretProviders, results) {
+    if (typeof value === 'string') {
+        // Find all secret references in the string
+        let match;
+        SECRET_REGEX.lastIndex = 0; // Reset regex state
+        while ((match = SECRET_REGEX.exec(value)) !== null) {
+            const [original, provider, pathWithKey, explicitKey] = match;
+            // Only include registered secret providers
+            if (!secretProviders.has(provider)) {
+                continue;
+            }
+            // Parse path and key - key can be after # or part of path
+            let path = pathWithKey;
+            let key = explicitKey;
+            // If no explicit key via #, check if path contains #
+            if (!key && path.includes('#')) {
+                const hashIndex = path.indexOf('#');
+                key = path.slice(hashIndex + 1);
+                path = path.slice(0, hashIndex);
+            }
+            results.push({
+                provider,
+                path,
+                key,
+                original,
+                location: {
+                    ...location,
+                    field: fieldPath,
+                },
+            });
+        }
+    }
+    else if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            findSecretsInValue(item, `${fieldPath}[${index}]`, location, secretProviders, results);
+        });
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const [key, val] of Object.entries(value)) {
+            const newPath = fieldPath ? `${fieldPath}.${key}` : key;
+            findSecretsInValue(val, newPath, location, secretProviders, results);
+        }
+    }
+}
+/**
+ * Discover all secret references in a configuration object.
+ *
+ * @param config - The configuration object to scan
+ * @param location - Base location information
+ * @param secretProviders - Set of registered secret provider names to look for
+ * @returns Array of discovered secret references
+ */
+export function discoverSecrets(config, location = {}, secretProviders = new Set()) {
+    const results = [];
+    findSecretsInValue(config, '', location, secretProviders, results);
+    return results;
+}
+export function aggregateSecrets(secrets) {
+    const map = new Map();
+    for (const secret of secrets) {
+        const id = `${secret.provider}:${secret.path}#${secret.key || ''}`;
+        if (map.has(id)) {
+            map.get(id).locations.push(secret.location);
+        }
+        else {
+            map.set(id, {
+                provider: secret.provider,
+                path: secret.path,
+                key: secret.key,
+                locations: [secret.location],
+            });
+        }
+    }
+    return [...map.values()];
+}

package/dist/src/secrets/SecretManager.d.ts

@@ -0,0 +1,52 @@
+import { AbstractSecretProvider, SecretReference } from './SecretProvider.js';
+/**
+ * Type for async source functions compatible with TemplateExpander.
+ */
+export type AsyncSecretSource = (key: string) => Promise<unknown>;
+/**
+ * Manages secret providers and creates template sources for them.
+ */
+export declare class SecretManager {
+    private providers;
+    /**
+     * Register a secret provider.
+     * @param name Provider name (e.g., 'vault', 'op')
+     * @param provider The provider instance
+     */
+    register(name: string, provider: AbstractSecretProvider): void;
+    /**
+     * Get a registered provider by name.
+     * @param name Provider name
+     * @returns The provider instance or undefined if not found
+     */
+    get(name: string): AbstractSecretProvider | undefined;
+    /**
+     * Check if a provider is registered.
+     * @param name Provider name
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered provider names.
+     */
+    getProviderNames(): string[];
+    /**
+     * Connect all registered providers.
+     */
+    connectAll(): Promise<void>;
+    /**
+     * Disconnect all registered providers.
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Parse a secret reference string into a SecretReference object.
+     * Format: "path/to/secret#key" or "path/to/secret"
+     * @param refString The reference string to parse
+     */
+    parseReference(refString: string): SecretReference;
+    /**
+     * Create an async source function for use with TemplateExpander.
+     * @param providerName The name of the provider to use
+     * @returns An async function that resolves secrets
+     */
+    createSource(providerName: string): AsyncSecretSource;
+}

package/dist/src/secrets/SecretManager.js

@@ -0,0 +1,75 @@
+/**
+ * Manages secret providers and creates template sources for them.
+ */
+export class SecretManager {
+    providers = new Map();
+    /**
+     * Register a secret provider.
+     * @param name Provider name (e.g., 'vault', 'op')
+     * @param provider The provider instance
+     */
+    register(name, provider) {
+        if (this.providers.has(name)) {
+            throw new Error(`Secret provider '${name}' is already registered`);
+        }
+        this.providers.set(name, provider);
+    }
+    /**
+     * Get a registered provider by name.
+     * @param name Provider name
+     * @returns The provider instance or undefined if not found
+     */
+    get(name) {
+        return this.providers.get(name);
+    }
+    /**
+     * Check if a provider is registered.
+     * @param name Provider name
+     */
+    has(name) {
+        return this.providers.has(name);
+    }
+    /**
+     * Get all registered provider names.
+     */
+    getProviderNames() {
+        return [...this.providers.keys()];
+    }
+    /**
+     * Connect all registered providers.
+     */
+    async connectAll() {
+        await Promise.all([...this.providers.values()].map((p) => p.connect()));
+    }
+    /**
+     * Disconnect all registered providers.
+     */
+    async disconnectAll() {
+        await Promise.all([...this.providers.values()].map((p) => p.disconnect()));
+    }
+    /**
+     * Parse a secret reference string into a SecretReference object.
+     * Format: "path/to/secret#key" or "path/to/secret"
+     * @param refString The reference string to parse
+     */
+    parseReference(refString) {
+        const [path, key] = refString.split('#');
+        return { path, key };
+    }
+    /**
+     * Create an async source function for use with TemplateExpander.
+     * @param providerName The name of the provider to use
+     * @returns An async function that resolves secrets
+     */
+    createSource(providerName) {
+        return async (key) => {
+            const provider = this.get(providerName);
+            if (!provider) {
+                throw new Error(`Secret provider '${providerName}' not found. ` +
+                    `Available providers: ${this.getProviderNames().join(', ') || 'none'}`);
+            }
+            const ref = this.parseReference(key);
+            return provider.get(ref);
+        };
+    }
+}

package/dist/src/secrets/SecretProvider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Reference to a secret in a provider.
+ */
+export interface SecretReference {
+    /** Optional field within the secret */
+    key?: string;
+    /** Path to the secret, e.g., "secret/data/myapp/db" */
+    path: string;
+    /** Optional version of the secret */
+    version?: string;
+}
+/**
+ * Abstract base class for secret providers.
+ * Implementations should handle specific secret management systems
+ * (e.g., HashiCorp Vault, 1Password).
+ */
+export declare abstract class AbstractSecretProvider<C = unknown> {
+    protected config: C;
+    protected cache: Map<string, Record<string, unknown>>;
+    constructor(config: C);
+    /**
+     * Connect to the secret provider and authenticate.
+     */
+    abstract connect(): Promise<void>;
+    /**
+     * Disconnect from the secret provider and clean up resources.
+     */
+    abstract disconnect(): Promise<void>;
+    /**
+     * Fetch a secret from the provider.
+     * @param ref Reference to the secret
+     * @returns The secret data as a key-value record
+     */
+    abstract fetchSecret(ref: SecretReference): Promise<Record<string, unknown>>;
+    /**
+     * Get a secret value, using cache if available.
+     * @param ref Reference to the secret
+     * @returns The secret value (entire record if no key specified, or specific field value)
+     */
+    get(ref: SecretReference): Promise<unknown>;
+    /**
+     * Clear the cache.
+     */
+    clearCache(): void;
+}

package/dist/src/secrets/SecretProvider.js

@@ -0,0 +1,38 @@
+/**
+ * Abstract base class for secret providers.
+ * Implementations should handle specific secret management systems
+ * (e.g., HashiCorp Vault, 1Password).
+ */
+export class AbstractSecretProvider {
+    config;
+    cache = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Get a secret value, using cache if available.
+     * @param ref Reference to the secret
+     * @returns The secret value (entire record if no key specified, or specific field value)
+     */
+    async get(ref) {
+        const cacheKey = `${ref.path}:${ref.version || 'latest'}`;
+        if (!this.cache.has(cacheKey)) {
+            this.cache.set(cacheKey, await this.fetchSecret(ref));
+        }
+        const cached = this.cache.get(cacheKey);
+        if (ref.key) {
+            if (!(ref.key in cached)) {
+                const availableKeys = Object.keys(cached).join(', ') || 'none';
+                throw new Error(`Key '${ref.key}' not found in secret '${ref.path}'. Available keys: ${availableKeys}`);
+            }
+            return cached[ref.key];
+        }
+        return cached;
+    }
+    /**
+     * Clear the cache.
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+}

package/dist/src/secrets/index.d.ts

@@ -0,0 +1,3 @@
+export * from './SecretDiscovery.js';
+export * from './SecretManager.js';
+export * from './SecretProvider.js';

package/dist/src/secrets/index.js

@@ -0,0 +1,3 @@
+export * from './SecretDiscovery.js';
+export * from './SecretManager.js';
+export * from './SecretProvider.js';

package/dist/src/secrets/providers/VaultOidcHelper.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Options for the OIDC login flow.
+ */
+export interface OidcLoginOptions {
+    /** Vault namespace (optional) */
+    namespace?: string;
+    /** Local port for the callback server (default: 8250) */
+    port?: number;
+    /** OIDC role to authenticate as (optional, uses default role if omitted) */
+    role?: string;
+    /** Timeout in milliseconds for the login flow (default: 120000 = 2 minutes) */
+    timeout?: number;
+    /** Vault server address */
+    vaultAddress: string;
+}
+/**
+ * Result of an OIDC login.
+ */
+export interface OidcLoginResult {
+    /** The Vault client token */
+    token: string;
+    /** Token TTL in seconds */
+    ttlSeconds: number;
+}
+/**
+ * Perform an interactive OIDC login with Vault.
+ *
+ * This function:
+ * 1. Starts a local HTTP server to receive the callback
+ * 2. Requests an OIDC auth URL from Vault
+ * 3. Opens the user's browser to the auth URL
+ * 4. Waits for the callback with the Vault token
+ * 5. Returns the token and TTL
+ *
+ * @param options - OIDC login options
+ * @returns The Vault client token and TTL
+ * @throws VaultError if the login fails
+ */
+export declare function performOidcLogin(options: OidcLoginOptions): Promise<OidcLoginResult>;