@enspirit/emb 0.15.0 → 0.17.5

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

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