@kustodian/plugin-doppler 1.0.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kustodian/plugin-doppler",
+  "version": "1.0.0",
+  "description": "Doppler secret provider plugin for Kustodian",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "bun run tsc --noEmit"
+  },
+  "keywords": [
+    "kustodian",
+    "plugin",
+    "doppler",
+    "secrets",
+    "kubernetes"
+  ],
+  "author": "Luca Silverentand <luca@onezero.company>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasilverentand/kustodian.git",
+    "directory": "plugins/doppler"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@kustodian/core": "workspace:*",
+    "@kustodian/plugins": "workspace:*",
+    "@kustodian/schema": "workspace:*"
+  },
+  "devDependencies": {}
+}

package/src/executor.ts

@@ -0,0 +1,228 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { Errors, type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+
+import { DEFAULT_TIMEOUT, type DopplerPluginOptionsType } from './types.js';
+
+const exec_file_async = promisify(execFile);
+
+/**
+ * Result of a command execution.
+ */
+export interface CommandResultType {
+  stdout: string;
+  stderr: string;
+  exit_code: number;
+}
+
+/**
+ * Options for command execution.
+ */
+export interface ExecOptionsType {
+  cwd?: string | undefined;
+  timeout?: number | undefined;
+  env?: Record<string, string> | undefined;
+}
+
+/**
+ * Executes a command and returns the result.
+ * Uses execFile for security (no shell invocation).
+ */
+export async function exec_command(
+  command: string,
+  args: string[] = [],
+  options: ExecOptionsType = {},
+): Promise<ResultType<CommandResultType, KustodianErrorType>> {
+  try {
+    const { stdout, stderr } = await exec_file_async(command, args, {
+      cwd: options.cwd,
+      timeout: options.timeout,
+      env: { ...process.env, ...options.env },
+    });
+
+    return success({
+      stdout,
+      stderr,
+      exit_code: 0,
+    });
+  } catch (error) {
+    if (is_exec_error(error)) {
+      return success({
+        stdout: error.stdout ?? '',
+        stderr: error.stderr ?? '',
+        exit_code: error.code ?? 1,
+      });
+    }
+
+    return failure(Errors.unknown(`Failed to execute command: ${command}`, error));
+  }
+}
+
+/**
+ * Type guard for exec errors.
+ */
+function is_exec_error(
+  error: unknown,
+): error is { stdout?: string; stderr?: string; code?: number } {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    ('stdout' in error || 'stderr' in error || 'code' in error)
+  );
+}
+
+/**
+ * Gets environment variables for Doppler CLI authentication.
+ */
+function get_doppler_auth_env(options: DopplerPluginOptionsType): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  const token = options.token ?? process.env['DOPPLER_TOKEN'];
+  if (token) {
+    env['DOPPLER_TOKEN'] = token;
+  }
+
+  return env;
+}
+
+/**
+ * Checks if doppler CLI is available in the system PATH.
+ */
+export async function check_doppler_available(): Promise<ResultType<string, KustodianErrorType>> {
+  const result = await exec_command('doppler', ['--version']);
+
+  if (!result.success) {
+    return result;
+  }
+
+  if (result.value.exit_code !== 0) {
+    return failure(Errors.secret_cli_not_found('Doppler', 'doppler'));
+  }
+
+  // Parse version from output (e.g., "v3.68.0")
+  const version = result.value.stdout.trim();
+  return success(version);
+}
+
+/**
+ * Fetches all secrets for a project/config combination.
+ * Returns a JSON object of all secrets.
+ */
+export async function doppler_secrets_download(
+  project: string,
+  config: string,
+  options: DopplerPluginOptionsType = {},
+): Promise<ResultType<Record<string, string>, KustodianErrorType>> {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const env = get_doppler_auth_env(options);
+
+  const result = await exec_command(
+    'doppler',
+    ['secrets', 'download', '--project', project, '--config', config, '--format', 'json', '--no-file'],
+    {
+      timeout,
+      env,
+    },
+  );
+
+  if (!result.success) {
+    return result;
+  }
+
+  const { stdout, stderr, exit_code } = result.value;
+
+  if (exit_code !== 0) {
+    // Parse specific error types from stderr
+    const stderr_lower = stderr.toLowerCase();
+
+    if (
+      stderr_lower.includes('not found') ||
+      stderr_lower.includes("doesn't exist") ||
+      stderr_lower.includes('no project') ||
+      stderr_lower.includes('no config')
+    ) {
+      return failure(Errors.secret_not_found('Doppler', `${project}/${config}`));
+    }
+
+    if (
+      stderr_lower.includes('unauthorized') ||
+      stderr_lower.includes('authentication') ||
+      stderr_lower.includes('invalid token') ||
+      stderr_lower.includes('access denied')
+    ) {
+      return failure(Errors.secret_auth_error('Doppler', stderr));
+    }
+
+    if (stderr_lower.includes('timeout')) {
+      return failure(Errors.secret_timeout('Doppler', timeout));
+    }
+
+    return failure(Errors.unknown(`Doppler error: ${stderr}`));
+  }
+
+  try {
+    const secrets = JSON.parse(stdout) as Record<string, string>;
+    return success(secrets);
+  } catch (error) {
+    return failure(Errors.unknown('Failed to parse Doppler secrets output', error));
+  }
+}
+
+/**
+ * Fetches a single secret value from Doppler.
+ */
+export async function doppler_secret_get(
+  project: string,
+  config: string,
+  secret_name: string,
+  options: DopplerPluginOptionsType = {},
+): Promise<ResultType<string, KustodianErrorType>> {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const env = get_doppler_auth_env(options);
+
+  const result = await exec_command(
+    'doppler',
+    ['secrets', 'get', secret_name, '--project', project, '--config', config, '--plain'],
+    {
+      timeout,
+      env,
+    },
+  );
+
+  if (!result.success) {
+    return result;
+  }
+
+  const { stdout, stderr, exit_code } = result.value;
+
+  if (exit_code !== 0) {
+    // Parse specific error types from stderr
+    const stderr_lower = stderr.toLowerCase();
+
+    if (
+      stderr_lower.includes('not found') ||
+      stderr_lower.includes("doesn't exist") ||
+      stderr_lower.includes('no secret')
+    ) {
+      return failure(Errors.secret_not_found('Doppler', `${project}/${config}/${secret_name}`));
+    }
+
+    if (
+      stderr_lower.includes('unauthorized') ||
+      stderr_lower.includes('authentication') ||
+      stderr_lower.includes('invalid token')
+    ) {
+      return failure(Errors.secret_auth_error('Doppler', stderr));
+    }
+
+    if (stderr_lower.includes('timeout')) {
+      return failure(Errors.secret_timeout('Doppler', timeout));
+    }
+
+    return failure(Errors.unknown(`Doppler error: ${stderr}`));
+  }
+
+  return success(stdout.trim());
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+// Plugin exports
+export { create_doppler_plugin, plugin } from './plugin.js';
+export { plugin as default } from './plugin.js';
+
+// Executor exports
+export {
+  check_doppler_available,
+  exec_command,
+  doppler_secret_get,
+  doppler_secrets_download,
+  type CommandResultType,
+  type ExecOptionsType,
+} from './executor.js';
+
+// Resolver exports
+export { resolve_doppler_substitutions } from './resolver.js';
+
+// Types
+export {
+  create_cache_key,
+  DEFAULT_TIMEOUT,
+  type DopplerCacheKeyType,
+  type DopplerPluginOptionsType,
+  type DopplerRefType,
+} from './types.js';

package/src/plugin.ts

@@ -0,0 +1,141 @@
+import { success } from '@kustodian/core';
+import type {
+  CommandType,
+  HookContextType,
+  HookEventType,
+  KustodianPluginType,
+  PluginCommandContributionType,
+  PluginHookContributionType,
+  PluginManifestType,
+} from '@kustodian/plugins';
+
+import { check_doppler_available, doppler_secret_get, doppler_secrets_download } from './executor.js';
+import type { DopplerPluginOptionsType } from './types.js';
+
+/**
+ * Doppler plugin manifest.
+ */
+const manifest: PluginManifestType = {
+  name: '@kustodian/plugin-doppler',
+  version: '0.1.0',
+  description: 'Doppler secret provider for Kustodian',
+  capabilities: ['commands', 'hooks'],
+};
+
+/**
+ * Creates the Doppler plugin.
+ */
+export function create_doppler_plugin(options: DopplerPluginOptionsType = {}): KustodianPluginType {
+  return {
+    manifest,
+
+    async activate() {
+      // Verify CLI availability on activation (warning only)
+      const check_result = await check_doppler_available();
+      if (!check_result.success) {
+        console.warn('Doppler CLI not found - secret resolution may fail');
+      }
+      return success(undefined);
+    },
+
+    async deactivate() {
+      return success(undefined);
+    },
+
+    get_commands(): PluginCommandContributionType[] {
+      const doppler_command: CommandType = {
+        name: 'doppler',
+        description: 'Doppler secret management commands',
+        subcommands: [
+          {
+            name: 'check',
+            description: 'Check Doppler CLI availability and authentication',
+            handler: async () => {
+              const result = await check_doppler_available();
+              if (result.success) {
+                console.log(`Doppler CLI version: ${result.value}`);
+                return success(undefined);
+              }
+              console.error('Doppler CLI not available');
+              return result;
+            },
+          },
+          {
+            name: 'test',
+            description: 'Test reading a secret from Doppler',
+            arguments: [
+              { name: 'project', description: 'Doppler project', required: true },
+              { name: 'config', description: 'Doppler config', required: true },
+              { name: 'secret', description: 'Secret name', required: true },
+            ],
+            handler: async (ctx) => {
+              const [project, config, secret] = ctx.args;
+              if (!project || !config || !secret) {
+                console.error('Missing required arguments: project, config, secret');
+                return success(undefined);
+              }
+
+              const result = await doppler_secret_get(project, config, secret, options);
+              if (result.success) {
+                console.log('Secret retrieved successfully (value hidden)');
+                console.log(`Length: ${result.value.length} characters`);
+                return success(undefined);
+              }
+
+              console.error(`Failed to read secret: ${result.error.message}`);
+              return result;
+            },
+          },
+          {
+            name: 'list-secrets',
+            description: 'List available secrets in a Doppler config',
+            arguments: [
+              { name: 'project', description: 'Doppler project', required: true },
+              { name: 'config', description: 'Doppler config', required: true },
+            ],
+            handler: async (ctx) => {
+              const [project, config] = ctx.args;
+              if (!project || !config) {
+                console.error('Missing required arguments: project, config');
+                return success(undefined);
+              }
+
+              const result = await doppler_secrets_download(project, config, options);
+              if (result.success) {
+                console.log('Available secrets:');
+                for (const key of Object.keys(result.value)) {
+                  console.log(`  - ${key}`);
+                }
+                return success(undefined);
+              }
+
+              console.error(`Failed to list secrets: ${result.error.message}`);
+              return result;
+            },
+          },
+        ],
+      };
+      return [{ command: doppler_command }];
+    },
+
+    get_hooks(): PluginHookContributionType[] {
+      return [
+        {
+          event: 'generator:after_resolve',
+          priority: 50, // Run before default (100) to inject secrets early
+          handler: async (_event: HookEventType, ctx: HookContextType) => {
+            // Hook for secret injection will be implemented in generator integration
+            return success(ctx);
+          },
+        },
+      ];
+    },
+  };
+}
+
+/**
+ * Default plugin export.
+ */
+export const plugin = create_doppler_plugin();
+
+export default plugin;

package/src/resolver.ts

@@ -0,0 +1,87 @@
+import { type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import type { DopplerSubstitutionType } from '@kustodian/schema';
+
+import { doppler_secrets_download } from './executor.js';
+import { create_cache_key, type DopplerCacheKeyType, type DopplerPluginOptionsType } from './types.js';
+
+/**
+ * Resolves Doppler substitutions to actual secret values.
+ * Groups by project/config to minimize API calls.
+ * Returns a map from substitution name to resolved value.
+ */
+export async function resolve_doppler_substitutions(
+  substitutions: DopplerSubstitutionType[],
+  options: DopplerPluginOptionsType = {},
+): Promise<ResultType<Record<string, string>, KustodianErrorType>> {
+  if (substitutions.length === 0) {
+    return success({});
+  }
+
+  // Group substitutions by project/config to minimize API calls
+  const groups = new Map<DopplerCacheKeyType, DopplerSubstitutionType[]>();
+
+  for (const sub of substitutions) {
+    const key = create_cache_key(sub.project, sub.config);
+    const group = groups.get(key) ?? [];
+    group.push(sub);
+    groups.set(key, group);
+  }
+
+  // Cache for downloaded secrets per project/config
+  const secrets_cache = new Map<DopplerCacheKeyType, Record<string, string>>();
+
+  const results: Record<string, string> = {};
+
+  // Fetch secrets for each group
+  for (const [key, subs] of groups) {
+    // Get project and config from the first substitution in the group
+    const first = subs[0]!;
+
+    // Check if we already have the secrets cached
+    let secrets = secrets_cache.get(key);
+
+    if (!secrets) {
+      const download_result = await doppler_secrets_download(first.project, first.config, options);
+
+      if (!download_result.success) {
+        // If we can't download secrets, try to use defaults
+        let all_have_defaults = true;
+        for (const sub of subs) {
+          if (sub.default !== undefined) {
+            results[sub.name] = sub.default;
+          } else if (options.fail_on_missing !== false) {
+            all_have_defaults = false;
+          }
+        }
+
+        if (!all_have_defaults) {
+          return failure(download_result.error);
+        }
+
+        continue;
+      }
+
+      secrets = download_result.value;
+      secrets_cache.set(key, secrets);
+    }
+
+    // Extract the requested secrets
+    for (const sub of subs) {
+      const value = secrets[sub.secret];
+
+      if (value !== undefined) {
+        results[sub.name] = value;
+      } else if (sub.default !== undefined) {
+        results[sub.name] = sub.default;
+      } else if (options.fail_on_missing !== false) {
+        return failure({
+          code: 'SECRET_NOT_FOUND',
+          message: `Secret not found in Doppler: ${sub.project}/${sub.config}/${sub.secret}`,
+        });
+      }
+    }
+  }
+
+  return success(results);
+}

package/src/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Options for the Doppler plugin.
+ */
+export interface DopplerPluginOptionsType {
+  /** Doppler service token (can also be set via DOPPLER_TOKEN env var) */
+  token?: string | undefined;
+  /** Timeout for CLI operations in milliseconds (default: 30000) */
+  timeout?: number | undefined;
+  /** Whether to fail on missing secrets (default: true) */
+  fail_on_missing?: boolean | undefined;
+}
+
+/**
+ * Parsed Doppler secret reference.
+ */
+export interface DopplerRefType {
+  project: string;
+  config: string;
+  secret: string;
+}
+
+/**
+ * Cache key for Doppler project/config combination.
+ */
+export type DopplerCacheKeyType = `${string}/${string}`;
+
+/**
+ * Default timeout for Doppler CLI operations.
+ */
+export const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * Creates a cache key for a Doppler project/config combination.
+ */
+export function create_cache_key(project: string, config: string): DopplerCacheKeyType {
+  return `${project}/${config}`;
+}