@enspirit/emb 0.14.1 → 0.17.0

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>;

package/dist/src/secrets/providers/VaultOidcHelper.js

@@ -0,0 +1,226 @@
+/* eslint-disable n/no-unsupported-features/node-builtins -- fetch is stable in Node 20+ */
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { URL, URLSearchParams } from 'node:url';
+import { VaultError } from './VaultProvider.js';
+/**
+ * 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 async function performOidcLogin(options) {
+    const { vaultAddress, role, namespace, timeout = 120_000 } = options;
+    const port = options.port ?? 8250;
+    const callbackUrl = `http://localhost:${port}/oidc/callback`;
+    // Generate a random state and nonce for security
+    const state = randomBytes(16).toString('hex');
+    const nonce = randomBytes(16).toString('hex');
+    return new Promise((resolve, reject) => {
+        let timeoutId;
+        let server;
+        const cleanup = () => {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = undefined;
+            }
+            if (server) {
+                server.close();
+                server = undefined;
+            }
+        };
+        // Set up timeout
+        timeoutId = setTimeout(() => {
+            cleanup();
+            reject(new VaultError('OIDC login timed out. Please try again.', 'VAULT_AUTH_ERROR'));
+        }, timeout);
+        // Create the callback server
+        server = createServer(async (req, res) => {
+            const url = new URL(req.url || '/', `http://localhost:${port}`);
+            if (url.pathname === '/oidc/callback') {
+                // Check for errors in callback
+                const error = url.searchParams.get('error');
+                const errorDescription = url.searchParams.get('error_description');
+                if (error) {
+                    sendHtmlResponse(res, 'Login Failed', `<p>Error: ${error}</p><p>${errorDescription || ''}</p>`);
+                    cleanup();
+                    reject(new VaultError(`OIDC login failed: ${error} - ${errorDescription || 'Unknown error'}`, 'VAULT_AUTH_ERROR'));
+                    return;
+                }
+                // Extract the code from the callback
+                const code = url.searchParams.get('code');
+                const returnedState = url.searchParams.get('state');
+                if (!code) {
+                    sendHtmlResponse(res, 'Login Failed', '<p>No authorization code received.</p>');
+                    cleanup();
+                    reject(new VaultError('OIDC login failed: No authorization code received', 'VAULT_AUTH_ERROR'));
+                    return;
+                }
+                // Note: We don't validate state client-side because Vault generates
+                // its own state (prefixed with 'st_') regardless of what we send.
+                // Vault validates the state internally when we call the callback endpoint.
+                try {
+                    // Exchange the code for a Vault token
+                    // Pass the returned state/nonce from Keycloak (which are Vault's values)
+                    const returnedNonce = url.searchParams.get('nonce') || nonce;
+                    const result = await exchangeCodeForToken({
+                        vaultAddress,
+                        role,
+                        namespace,
+                        code,
+                        state: returnedState || state,
+                        nonce: returnedNonce,
+                    });
+                    sendHtmlResponse(res, 'Login Successful', '<p>You have been authenticated. You may close this window.</p>');
+                    cleanup();
+                    resolve(result);
+                }
+                catch (error_) {
+                    const errorMessage = error_ instanceof Error ? error_.message : 'Unknown error';
+                    sendHtmlResponse(res, 'Login Failed', `<p>Failed to complete authentication: ${errorMessage}</p>`);
+                    cleanup();
+                    reject(error_);
+                }
+            }
+            else {
+                res.writeHead(404);
+                res.end('Not Found');
+            }
+        });
+        server.on('error', (err) => {
+            cleanup();
+            reject(new VaultError(`Failed to start callback server: ${err.message}`, 'VAULT_AUTH_ERROR'));
+        });
+        server.listen(port, 'localhost', async () => {
+            try {
+                // Get the OIDC auth URL from Vault
+                const authUrl = await getOidcAuthUrl({
+                    vaultAddress,
+                    role,
+                    namespace,
+                    redirectUri: callbackUrl,
+                    state,
+                    nonce,
+                });
+                // Open the browser
+                const open = (await import('open')).default;
+                await open(authUrl);
+                console.log('Opening browser for authentication...');
+                console.log(`If the browser doesn't open, navigate to:\n${authUrl}`);
+            }
+            catch (error) {
+                cleanup();
+                reject(error);
+            }
+        });
+    });
+}
+/**
+ * Get the OIDC auth URL from Vault.
+ */
+async function getOidcAuthUrl(options) {
+    const { vaultAddress, role, namespace, redirectUri, state, nonce } = options;
+    const url = new URL('/v1/auth/oidc/oidc/auth_url', vaultAddress);
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (namespace) {
+        headers['X-Vault-Namespace'] = namespace;
+    }
+    // Build the request body
+    // Vault API uses snake_case for these parameters
+    /* eslint-disable camelcase */
+    const body = {
+        redirect_uri: redirectUri,
+        state,
+        nonce,
+    };
+    if (role) {
+        body.role = role;
+    }
+    /* eslint-enable camelcase */
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const data = (await response.json().catch(() => ({})));
+        const errorMessage = data.errors?.join(', ') || `HTTP ${response.status}`;
+        throw new VaultError(`Failed to get OIDC auth URL: ${errorMessage}`, 'VAULT_AUTH_ERROR', response.status);
+    }
+    const data = (await response.json());
+    const authUrl = data.data?.auth_url;
+    if (!authUrl) {
+        throw new VaultError('Vault did not return an OIDC auth URL', 'VAULT_AUTH_ERROR');
+    }
+    return authUrl;
+}
+/**
+ * Exchange the authorization code for a Vault token.
+ */
+async function exchangeCodeForToken(options) {
+    const { vaultAddress, role, namespace, code, state, nonce } = options;
+    const url = new URL('/v1/auth/oidc/oidc/callback', vaultAddress);
+    const params = new URLSearchParams({
+        code,
+        state,
+        nonce,
+    });
+    if (role) {
+        params.set('role', role);
+    }
+    const headers = {
+        'Content-Type': 'application/json',
+    };
+    if (namespace) {
+        headers['X-Vault-Namespace'] = namespace;
+    }
+    const response = await fetch(`${url.toString()}?${params.toString()}`, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        const data = (await response.json().catch(() => ({})));
+        const errorMessage = data.errors?.join(', ') || `HTTP ${response.status}`;
+        throw new VaultError(`Failed to exchange code for token: ${errorMessage}`, 'VAULT_AUTH_ERROR', response.status);
+    }
+    const data = (await response.json());
+    const token = data.auth?.client_token;
+    if (!token) {
+        throw new VaultError('Vault did not return a client token', 'VAULT_AUTH_ERROR');
+    }
+    return {
+        token,
+        ttlSeconds: data.auth?.lease_duration || 3600,
+    };
+}
+/**
+ * Send an HTML response to the browser.
+ */
+function sendHtmlResponse(res, title, body) {
+    const html = `<!DOCTYPE html>
+<html>
+<head>
+  <title>${title}</title>
+  <style>
+    body { font-family: sans-serif; padding: 40px; text-align: center; }
+    h1 { color: #333; }
+  </style>
+</head>
+<body>
+  <h1>${title}</h1>
+  ${body}
+</body>
+</html>`;
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(html);
+}

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

@@ -0,0 +1,74 @@
+import { AbstractSecretProvider, SecretReference } from '../SecretProvider.js';
+/**
+ * Authentication configuration for HashiCorp Vault.
+ */
+export type VaultAuthConfig = {
+    method: 'approle';
+    roleId: string;
+    secretId: string;
+} | {
+    method: 'jwt';
+    role: string;
+    jwt: string;
+} | {
+    method: 'kubernetes';
+    role: string;
+} | {
+    method: 'oidc';
+    role?: string;
+    port?: number;
+} | {
+    method: 'token';
+    token: string;
+};
+/**
+ * Configuration for the Vault provider.
+ */
+export interface VaultProviderConfig {
+    /** Vault server address (defaults to VAULT_ADDR env var) */
+    address: string;
+    /** Authentication configuration */
+    auth: VaultAuthConfig;
+    /** Vault namespace (optional, defaults to VAULT_NAMESPACE env var) */
+    namespace?: string;
+}
+/**
+ * Error class for Vault-specific errors.
+ */
+export declare class VaultError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+/**
+ * HashiCorp Vault secret provider.
+ * Supports KV v2 secrets engine.
+ */
+export declare class VaultProvider extends AbstractSecretProvider<VaultProviderConfig> {
+    private token;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    fetchSecret(ref: SecretReference): Promise<Record<string, unknown>>;
+    /**
+     * Normalize a path for the appropriate secrets engine.
+     * - KV v2: Insert '/data/' after the mount point
+     * - 1Password Connect: Use path as-is (contains /vaults/ and /items/)
+     * - Other engines: Use path as-is
+     */
+    private normalizeKvPath;
+    private buildHeaders;
+    private loginAppRole;
+    private loginKubernetes;
+    /**
+     * Authenticate using JWT (non-interactive).
+     * Suitable for CI/CD pipelines where a JWT is provided externally.
+     */
+    private loginJwt;
+    /**
+     * Authenticate using OIDC (interactive browser flow).
+     * Opens a browser for the user to authenticate with Keycloak/OIDC provider.
+     */
+    private loginOidc;
+    private verifyToken;
+    private parseErrorResponse;
+}