@enspirit/emb 0.14.1 → 0.17.0

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

@@ -0,0 +1,266 @@
+/* eslint-disable n/no-unsupported-features/node-builtins -- fetch is stable in Node 20+ */
+import { AbstractSecretProvider } from '../SecretProvider.js';
+import { cacheToken, clearCachedToken, getCachedToken, } from './VaultTokenCache.js';
+/**
+ * Error class for Vault-specific errors.
+ */
+export class VaultError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.name = 'VaultError';
+    }
+}
+/**
+ * HashiCorp Vault secret provider.
+ * Supports KV v2 secrets engine.
+ */
+export class VaultProvider extends AbstractSecretProvider {
+    token = null;
+    async connect() {
+        const { auth, address, namespace } = this.config;
+        // Try to use cached token first (for methods that benefit from caching)
+        if (auth.method === 'oidc') {
+            const cached = await getCachedToken(address, namespace);
+            if (cached) {
+                this.token = cached.token;
+                try {
+                    await this.verifyToken();
+                    // Cached token is still valid
+                    return;
+                }
+                catch {
+                    // Cached token is invalid, clear it and proceed with fresh auth
+                    await clearCachedToken(address, namespace);
+                    this.token = null;
+                }
+            }
+        }
+        let authResult;
+        switch (auth.method) {
+            case 'approle': {
+                authResult = await this.loginAppRole(auth.roleId, auth.secretId);
+                break;
+            }
+            case 'jwt': {
+                authResult = await this.loginJwt(auth.role, auth.jwt);
+                break;
+            }
+            case 'kubernetes': {
+                authResult = await this.loginKubernetes(auth.role);
+                break;
+            }
+            case 'oidc': {
+                authResult = await this.loginOidc(auth.role, auth.port);
+                break;
+            }
+            case 'token': {
+                // For explicit tokens, we don't know the TTL - use a default
+                authResult = { token: auth.token, ttlSeconds: 3600 };
+                break;
+            }
+            default: {
+                throw new VaultError(`Unsupported auth method: ${auth.method}`, 'VAULT_AUTH_ERROR');
+            }
+        }
+        this.token = authResult.token;
+        // Verify the token works by looking it up
+        await this.verifyToken();
+        // Cache the token for methods that benefit from caching
+        if (auth.method === 'oidc' && authResult.ttlSeconds > 0) {
+            await cacheToken(address, authResult.token, authResult.ttlSeconds, namespace);
+        }
+    }
+    async disconnect() {
+        this.token = null;
+        this.clearCache();
+    }
+    async fetchSecret(ref) {
+        if (!this.token) {
+            throw new VaultError('Not connected to Vault', 'VAULT_NOT_CONNECTED');
+        }
+        // For KV v2, the path needs 'data' inserted after the mount point
+        // e.g., "secret/myapp" becomes "secret/data/myapp"
+        const path = this.normalizeKvPath(ref.path);
+        const url = new URL(`/v1/${path}`, this.config.address);
+        if (ref.version) {
+            url.searchParams.set('version', ref.version);
+        }
+        const response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: this.buildHeaders(),
+        });
+        if (!response.ok) {
+            const error = await this.parseErrorResponse(response);
+            const namespace = this.config.namespace
+                ? ` (namespace: ${this.config.namespace})`
+                : '';
+            throw new VaultError(`Failed to read secret at '${ref.path}'${namespace}: ${error.message}`, 'VAULT_READ_ERROR', response.status);
+        }
+        const data = await response.json();
+        // KV v2 wraps the data in a 'data' field
+        return (data.data?.data ||
+            data.data ||
+            {});
+    }
+    /**
+     * 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
+     */
+    normalizeKvPath(path) {
+        // If path already contains '/data/', assume it's correctly formatted for KV v2
+        if (path.includes('/data/')) {
+            return path;
+        }
+        // 1Password Connect paths contain /vaults/ and /items/ - don't modify
+        if (path.includes('/vaults/') || path.includes('/items/')) {
+            return path;
+        }
+        // For KV v2, insert /data/ after the mount point
+        // Split by first '/' to get mount and rest of path
+        const firstSlash = path.indexOf('/');
+        if (firstSlash === -1) {
+            // Just a mount, no sub-path
+            return `${path}/data`;
+        }
+        const mount = path.slice(0, Math.max(0, firstSlash));
+        const subPath = path.slice(Math.max(0, firstSlash + 1));
+        return `${mount}/data/${subPath}`;
+    }
+    buildHeaders() {
+        const headers = {
+            'X-Vault-Token': this.token,
+            'Content-Type': 'application/json',
+        };
+        if (this.config.namespace) {
+            headers['X-Vault-Namespace'] = this.config.namespace;
+        }
+        return headers;
+    }
+    async loginAppRole(roleId, secretId) {
+        const url = new URL('/v1/auth/approle/login', this.config.address);
+        const response = await fetch(url.toString(), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(this.config.namespace && {
+                    'X-Vault-Namespace': this.config.namespace,
+                }),
+            },
+            // Vault API uses snake_case for these properties
+            // eslint-disable-next-line camelcase
+            body: JSON.stringify({ role_id: roleId, secret_id: secretId }),
+        });
+        if (!response.ok) {
+            const error = await this.parseErrorResponse(response);
+            throw new VaultError(`AppRole login failed: ${error.message}`, 'VAULT_AUTH_ERROR', response.status);
+        }
+        const data = (await response.json());
+        return {
+            token: data.auth?.client_token || '',
+            ttlSeconds: data.auth?.lease_duration || 3600,
+        };
+    }
+    async loginKubernetes(role) {
+        // Read the service account token from the mounted file
+        const fs = await import('node:fs/promises');
+        const tokenPath = '/var/run/secrets/kubernetes.io/serviceaccount/token';
+        let jwt;
+        try {
+            jwt = await fs.readFile(tokenPath, 'utf8');
+        }
+        catch {
+            throw new VaultError(`Could not read Kubernetes service account token from ${tokenPath}`, 'VAULT_AUTH_ERROR');
+        }
+        const url = new URL('/v1/auth/kubernetes/login', this.config.address);
+        const response = await fetch(url.toString(), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(this.config.namespace && {
+                    'X-Vault-Namespace': this.config.namespace,
+                }),
+            },
+            body: JSON.stringify({ role, jwt }),
+        });
+        if (!response.ok) {
+            const error = await this.parseErrorResponse(response);
+            throw new VaultError(`Kubernetes login failed: ${error.message}`, 'VAULT_AUTH_ERROR', response.status);
+        }
+        const data = (await response.json());
+        return {
+            token: data.auth?.client_token || '',
+            ttlSeconds: data.auth?.lease_duration || 3600,
+        };
+    }
+    /**
+     * Authenticate using JWT (non-interactive).
+     * Suitable for CI/CD pipelines where a JWT is provided externally.
+     */
+    async loginJwt(role, jwt) {
+        const url = new URL('/v1/auth/jwt/login', this.config.address);
+        const response = await fetch(url.toString(), {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(this.config.namespace && {
+                    'X-Vault-Namespace': this.config.namespace,
+                }),
+            },
+            body: JSON.stringify({ role, jwt }),
+        });
+        if (!response.ok) {
+            const error = await this.parseErrorResponse(response);
+            throw new VaultError(`JWT login failed: ${error.message}`, 'VAULT_AUTH_ERROR', response.status);
+        }
+        const data = (await response.json());
+        return {
+            token: data.auth?.client_token || '',
+            ttlSeconds: data.auth?.lease_duration || 3600,
+        };
+    }
+    /**
+     * Authenticate using OIDC (interactive browser flow).
+     * Opens a browser for the user to authenticate with Keycloak/OIDC provider.
+     */
+    async loginOidc(role, port) {
+        const { performOidcLogin } = await import('./VaultOidcHelper.js');
+        const result = await performOidcLogin({
+            vaultAddress: this.config.address,
+            role,
+            port: port ?? 8250,
+            namespace: this.config.namespace,
+        });
+        return {
+            token: result.token,
+            ttlSeconds: result.ttlSeconds,
+        };
+    }
+    async verifyToken() {
+        const url = new URL('/v1/auth/token/lookup-self', this.config.address);
+        const response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: this.buildHeaders(),
+        });
+        if (!response.ok) {
+            const error = await this.parseErrorResponse(response);
+            throw new VaultError(`Token verification failed: ${error.message}`, 'VAULT_AUTH_ERROR', response.status);
+        }
+    }
+    async parseErrorResponse(response) {
+        try {
+            const data = (await response.json());
+            return {
+                message: data.errors?.join(', ') || `HTTP ${response.status}`,
+            };
+        }
+        catch {
+            return { message: `HTTP ${response.status}: ${response.statusText}` };
+        }
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Cached token metadata stored on disk.
+ */
+export interface CachedToken {
+    /** Unix timestamp (ms) when the token was cached */
+    createdAt: number;
+    /** Unix timestamp (ms) when the token expires */
+    expiresAt: number;
+    /** Vault namespace (if any) */
+    namespace?: string;
+    /** The Vault client token */
+    token: string;
+    /** Vault address this token is for */
+    vaultAddress: string;
+}
+/**
+ * Options for token caching.
+ */
+export interface TokenCacheOptions {
+    /** Custom cache directory (default: ~/.emb/vault-tokens) */
+    cacheDir?: string;
+    /** Buffer time in ms before expiry to consider token invalid (default: 5 minutes) */
+    expiryBuffer?: number;
+}
+/**
+ * Retrieve a cached token if it exists and is still valid.
+ *
+ * @param vaultAddress - The Vault server address
+ * @param namespace - Optional Vault namespace
+ * @param options - Cache options
+ * @returns The cached token or null if not found/expired
+ */
+export declare function getCachedToken(vaultAddress: string, namespace?: string, options?: TokenCacheOptions): Promise<CachedToken | null>;
+/**
+ * Cache a Vault token to disk (encrypted).
+ *
+ * @param vaultAddress - The Vault server address
+ * @param token - The Vault client token
+ * @param ttlSeconds - Token TTL in seconds (from Vault's lease_duration)
+ * @param namespace - Optional Vault namespace
+ * @param options - Cache options
+ */
+export declare function cacheToken(vaultAddress: string, token: string, ttlSeconds: number, namespace?: string, options?: TokenCacheOptions): Promise<void>;
+/**
+ * Clear a cached token.
+ *
+ * @param vaultAddress - The Vault server address
+ * @param namespace - Optional Vault namespace
+ * @param options - Cache options
+ */
+export declare function clearCachedToken(vaultAddress: string, namespace?: string, options?: TokenCacheOptions): Promise<void>;
+/**
+ * Check if a cached token exists and is valid (without returning the token).
+ *
+ * @param vaultAddress - The Vault server address
+ * @param namespace - Optional Vault namespace
+ * @param options - Cache options
+ * @returns True if a valid cached token exists
+ */
+export declare function hasCachedToken(vaultAddress: string, namespace?: string, options?: TokenCacheOptions): Promise<boolean>;

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

@@ -0,0 +1,188 @@
+import { createCipheriv, createDecipheriv, createHash, pbkdf2Sync, randomBytes, } from 'node:crypto';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir, hostname, userInfo } from 'node:os';
+import { join } from 'node:path';
+const DEFAULT_EXPIRY_BUFFER = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_CACHE_DIR = join(homedir(), '.emb', 'vault-tokens');
+// Encryption constants
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 16;
+const _AUTH_TAG_LENGTH = 16;
+const SALT_LENGTH = 32;
+const KEY_LENGTH = 32;
+const PBKDF2_ITERATIONS = 100_000;
+/**
+ * Derive an encryption key from machine-specific data.
+ * The key is derived from hostname + username + a static pepper,
+ * making the cache file unusable if copied to another machine or user.
+ */
+function deriveKey(salt) {
+    const machineId = `${hostname()}:${userInfo().username}:emb-vault-cache`;
+    return pbkdf2Sync(machineId, salt, PBKDF2_ITERATIONS, KEY_LENGTH, 'sha256');
+}
+/**
+ * Encrypt data using AES-256-GCM.
+ */
+function encrypt(data) {
+    const salt = randomBytes(SALT_LENGTH);
+    const key = deriveKey(salt);
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, key, iv);
+    const encrypted = Buffer.concat([
+        cipher.update(data, 'utf8'),
+        cipher.final(),
+    ]);
+    const authTag = cipher.getAuthTag();
+    return {
+        version: 1,
+        salt: salt.toString('hex'),
+        iv: iv.toString('hex'),
+        authTag: authTag.toString('hex'),
+        encrypted: encrypted.toString('hex'),
+    };
+}
+/**
+ * Decrypt data using AES-256-GCM.
+ * Returns null if decryption fails (wrong machine, corrupted data, etc.)
+ */
+function decrypt(file) {
+    try {
+        if (file.version !== 1) {
+            return null;
+        }
+        const salt = Buffer.from(file.salt, 'hex');
+        const key = deriveKey(salt);
+        const iv = Buffer.from(file.iv, 'hex');
+        const authTag = Buffer.from(file.authTag, 'hex');
+        const encrypted = Buffer.from(file.encrypted, 'hex');
+        const decipher = createDecipheriv(ALGORITHM, key, iv);
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([
+            decipher.update(encrypted),
+            decipher.final(),
+        ]);
+        return decrypted.toString('utf8');
+    }
+    catch {
+        // Decryption failed - wrong key (different machine/user) or corrupted data
+        return null;
+    }
+}
+/**
+ * Generate a cache key for a Vault address and namespace combination.
+ * Uses a hash to create safe filenames.
+ */
+function getCacheKey(vaultAddress, namespace) {
+    const input = namespace ? `${vaultAddress}::${namespace}` : vaultAddress;
+    return createHash('sha256').update(input).digest('hex').slice(0, 16);
+}
+/**
+ * Get the path to the cache file for a given Vault address.
+ */
+function getCachePath(vaultAddress, namespace, cacheDir = DEFAULT_CACHE_DIR) {
+    const key = getCacheKey(vaultAddress, namespace);
+    return join(cacheDir, `${key}.json`);
+}
+/**
+ * Retrieve a cached token if it exists and is still valid.
+ *
+ * @param vaultAddress - The Vault server address
+ * @param namespace - Optional Vault namespace
+ * @param options - Cache options
+ * @returns The cached token or null if not found/expired
+ */
+export async function getCachedToken(vaultAddress, namespace, options = {}) {
+    const { expiryBuffer = DEFAULT_EXPIRY_BUFFER, cacheDir } = options;
+    const cachePath = getCachePath(vaultAddress, namespace, cacheDir);
+    try {
+        const content = await readFile(cachePath, 'utf8');
+        const encryptedFile = JSON.parse(content);
+        // Decrypt the cached data
+        const decrypted = decrypt(encryptedFile);
+        if (!decrypted) {
+            // Decryption failed - likely different machine/user or corrupted
+            await clearCachedToken(vaultAddress, namespace, options);
+            return null;
+        }
+        const cached = JSON.parse(decrypted);
+        // Verify the cached token matches the requested address/namespace
+        if (cached.vaultAddress !== vaultAddress ||
+            cached.namespace !== namespace) {
+            return null;
+        }
+        // Check if token is expired or close to expiry
+        const now = Date.now();
+        if (cached.expiresAt - expiryBuffer <= now) {
+            // Token is expired or about to expire, clear it
+            await clearCachedToken(vaultAddress, namespace, options);
+            return null;
+        }
+        return cached;
+    }
+    catch {
+        // File doesn't exist or is invalid
+        return null;
+    }
+}
+/**
+ * Cache a Vault token to disk (encrypted).
+ *
+ * @param vaultAddress - The Vault server address
+ * @param token - The Vault client token
+ * @param ttlSeconds - Token TTL in seconds (from Vault's lease_duration)
+ * @param namespace - Optional Vault namespace
+ * @param options - Cache options
+ */
+// eslint-disable-next-line max-params
+export async function cacheToken(vaultAddress, token, ttlSeconds, namespace, options = {}) {
+    const { cacheDir = DEFAULT_CACHE_DIR } = options;
+    const cachePath = getCachePath(vaultAddress, namespace, cacheDir);
+    const now = Date.now();
+    const cached = {
+        token,
+        expiresAt: now + ttlSeconds * 1000,
+        createdAt: now,
+        namespace,
+        vaultAddress,
+    };
+    // Encrypt the token data
+    const encryptedFile = encrypt(JSON.stringify(cached));
+    // Ensure cache directory exists
+    await mkdir(cacheDir, { recursive: true, mode: 0o700 });
+    // Write the encrypted cache file with restricted permissions
+    await writeFile(cachePath, JSON.stringify(encryptedFile, null, 2), {
+        mode: 0o600,
+        encoding: 'utf8',
+    });
+    // Ensure permissions are correct (writeFile mode may not work on all platforms)
+    await chmod(cachePath, 0o600);
+}
+/**
+ * Clear a cached token.
+ *
+ * @param vaultAddress - The Vault server address
+ * @param namespace - Optional Vault namespace
+ * @param options - Cache options
+ */
+export async function clearCachedToken(vaultAddress, namespace, options = {}) {
+    const { cacheDir } = options;
+    const cachePath = getCachePath(vaultAddress, namespace, cacheDir);
+    try {
+        await rm(cachePath);
+    }
+    catch {
+        // Ignore errors if file doesn't exist
+    }
+}
+/**
+ * Check if a cached token exists and is valid (without returning the token).
+ *
+ * @param vaultAddress - The Vault server address
+ * @param namespace - Optional Vault namespace
+ * @param options - Cache options
+ * @returns True if a valid cached token exists
+ */
+export async function hasCachedToken(vaultAddress, namespace, options = {}) {
+    const cached = await getCachedToken(vaultAddress, namespace, options);
+    return cached !== null;
+}

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

@@ -0,0 +1,2 @@
+export * from './VaultProvider.js';
+export * from './VaultTokenCache.js';

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

@@ -0,0 +1,2 @@
+export * from './VaultProvider.js';
+export * from './VaultTokenCache.js';

package/dist/src/types.d.ts

@@ -1,6 +1,7 @@
 import type Docker from 'dockerode';
 import { AppsV1Api, CoreV1Api, KubeConfig } from '@kubernetes/client-node';
 import { Monorepo } from './monorepo/index.js';
+import { SecretManager } from './secrets/index.js';
 import { DockerComposeClient } from './docker/index.js';
 /**
  * The context is meant to be what all plugins can decorate
@@ -18,4 +19,5 @@ export interface EmbContext {
         core: CoreV1Api;
     };
     monorepo: Monorepo;
+    secrets: SecretManager;
 }

package/dist/src/utils/TemplateExpander.d.ts

@@ -1,6 +1,18 @@
+/**
+ * An async source is a function that returns a promise resolving to the value.
+ */
+type AsyncSource = (key: string) => Promise<unknown>;
+/**
+ * A static source is a simple key-value record.
+ */
+type StaticSource = Record<string, unknown>;
+/**
+ * A source can be either static or async.
+ */
+type Source = AsyncSource | StaticSource;
 type ExpandOptions = {
     default?: string;
-    sources?: Record<string, Record<string, unknown>>;
+    sources?: Record<string, Source>;
 };
 export type ExpansionHistory = {
     source: string;

package/dist/src/utils/TemplateExpander.js

@@ -1,31 +1,84 @@
-const TPL_REGEX = /(?<!\\)\${(?:(\w+):)?(\w+)(?::-(.*?))?}/g;
+// Matches ${source:key} or ${key} patterns
+// - Source name: word characters only (e.g., "vault", "env")
+// - Key: word characters, slashes, hashes, dots, with hyphens allowed between segments
+//   (e.g., "secret/path#field", "MY_VAR", "secret/my-app#key")
+// - Optional fallback: :-value
+// The key pattern uses (?:-[\w/#.]+)* to allow hyphens only between valid segments,
+// preventing the key from consuming the :- fallback delimiter.
+const TPL_REGEX = /(?<!\\)\${(?:(\w+):)?([\w/#.]+(?:-[\w/#.]+)*)(?::-(.*?))?}/g;
+/**
+ * Check if a source is async (a function).
+ */
+function isAsyncSource(source) {
+    return typeof source === 'function';
+}
 export class TemplateExpander {
     expansions = [];
     get expansionCount() {
         return this.expansions.length;
     }
     async expand(str, options = {}) {
-        return (str || '')
-            .toString()
-            .replaceAll(TPL_REGEX, (match, source, key, fallback) => {
-            const src = source ?? options.default ?? '';
-            const provider = options.sources?.[src];
-            if (!provider) {
+        const input = (str || '').toString();
+        // Collect all matches with their positions
+        const matches = [...input.matchAll(TPL_REGEX)];
+        if (matches.length === 0) {
+            return input.replaceAll('\\${', '${');
+        }
+        // Resolve all values (async for function sources, sync for objects)
+        const resolutions = await Promise.all(matches.map(async (match) => {
+            const [fullMatch, sourceName, key, fallback] = match;
+            const src = sourceName ?? options.default ?? '';
+            const source = options.sources?.[src];
+            // No source found
+            if (!source) {
                 if (fallback !== undefined) {
-                    return this.track(src, key, fallback);
+                    return {
+                        match: fullMatch,
+                        value: this.track(src, key, fallback),
+                    };
+                }
+                throw new Error(`Invalid expand provider '${sourceName}' ('${fullMatch}')`);
+            }
+            // Resolve value based on source type
+            let val;
+            if (isAsyncSource(source)) {
+                try {
+                    val = await source(key);
                 }
-                throw new Error(`Invalid expand provider '${source}' ('${match}')`);
+                catch (error) {
+                    if (fallback !== undefined) {
+                        return {
+                            match: fullMatch,
+                            value: this.track(src, key, fallback),
+                        };
+                    }
+                    throw error;
+                }
+            }
+            else {
+                val = source[key];
             }
-            const val = provider[key];
+            // Handle missing values
             if (!val && fallback === undefined) {
-                throw new Error(`Could not expand '${match}' and no default value provided`);
+                throw new Error(`Could not expand '${fullMatch}' and no default value provided`);
             }
             if (val !== undefined && val !== null) {
-                return this.track(src, key, val);
+                return {
+                    match: fullMatch,
+                    value: this.track(src, key, val),
+                };
             }
-            return this.track(src, key, fallback ?? '');
-        })
-            .replaceAll('\\${', '${');
+            return {
+                match: fullMatch,
+                value: this.track(src, key, fallback ?? ''),
+            };
+        }));
+        // Build result string by replacing matches with resolved values
+        let result = input;
+        for (const { match, value } of resolutions) {
+            result = result.replace(match, value);
+        }
+        return result.replaceAll('\\${', '${');
     }
     async expandRecord(record, options) {
         if (typeof record === 'string') {