@openpalm/lib 0.9.8 → 0.10.1

package/src/control-plane/secret-backend.test.ts

@@ -0,0 +1,359 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  detectSecretBackend,
+  type ControlPlaneState,
+  ensureSecrets,
+  validatePassEntryName,
+} from '../index.js';
+import { PlaintextBackend, PassBackend } from './secret-backend.js';
+import { generateRedactSchema } from './redact-schema.js';
+import { getCoreSecretMappings } from './secret-mappings.js';
+import { writeSecretProviderConfig } from './provider-config.js';
+
+let rootDir = '';
+
+function createState(): ControlPlaneState {
+  const vaultDir = join(rootDir, 'vault');
+  const dataDir = join(rootDir, 'data');
+  const configDir = join(rootDir, 'config');
+  const logsDir = join(rootDir, 'logs');
+  const cacheDir = join(rootDir, 'cache');
+  mkdirSync(vaultDir, { recursive: true });
+  mkdirSync(dataDir, { recursive: true });
+  mkdirSync(configDir, { recursive: true });
+  mkdirSync(logsDir, { recursive: true });
+  mkdirSync(cacheDir, { recursive: true });
+
+  return {
+    adminToken: 'admin-token',
+    assistantToken: '',
+    setupToken: 'setup-token',
+    homeDir: rootDir,
+    configDir,
+    vaultDir,
+    dataDir,
+    logsDir,
+    cacheDir,
+    services: {},
+    artifacts: { compose: '' },
+    artifactMeta: [],
+    audit: [],
+  };
+}
+
+beforeEach(() => {
+  rootDir = mkdtempSync(join(tmpdir(), 'openpalm-secret-backend-'));
+});
+
+afterEach(() => {
+  rmSync(rootDir, { recursive: true, force: true });
+});
+
+describe('secret backend', () => {
+  test('ensureSecrets repairs auth.json when Docker created it as a directory', () => {
+    const state = createState();
+    mkdirSync(join(state.vaultDir, 'stack', 'auth.json'), { recursive: true });
+
+    ensureSecrets(state);
+
+    const authJsonPath = join(state.vaultDir, 'stack', 'auth.json');
+    expect(lstatSync(authJsonPath).isFile()).toBe(true);
+    expect(readFileSync(authJsonPath, 'utf-8')).toBe('{}\n');
+  });
+
+  test('detectSecretBackend defaults to plaintext and routes custom secrets into vault env files', async () => {
+    const state = createState();
+    ensureSecrets(state);
+    const backend = detectSecretBackend(state);
+
+    expect(backend.provider).toBe('plaintext');
+
+    const entry = await backend.write('openpalm/custom/example', 'very-secret');
+    expect(entry.provider).toBe('plaintext');
+    expect(entry.scope).toBe('user');
+    expect(await backend.exists('openpalm/custom/example')).toBe(true);
+
+    // Custom secrets are now written to stack.env (all secrets consolidated there)
+    const stackEnv = readFileSync(join(state.vaultDir, 'stack', 'stack.env'), 'utf-8');
+    expect(stackEnv).toContain('very-secret');
+  });
+
+  test('validatePassEntryName rejects traversal and invalid characters', () => {
+    expect(() => validatePassEntryName('../bad')).toThrow();
+    expect(() => validatePassEntryName('openpalm/Bad Key')).toThrow();
+    expect(validatePassEntryName('openpalm/custom/good-key')).toBe('openpalm/custom/good-key');
+  });
+
+  test('validatePassEntryName rejects empty after trim', () => {
+    expect(() => validatePassEntryName('')).toThrow('must not be empty');
+    expect(() => validatePassEntryName('   ')).toThrow('must not be empty');
+    expect(() => validatePassEntryName('///')).toThrow('must not be empty');
+  });
+
+  test('validatePassEntryName rejects uppercase characters', () => {
+    expect(() => validatePassEntryName('openpalm/MyKey')).toThrow('invalid characters');
+    expect(() => validatePassEntryName('OPENPALM/key')).toThrow('invalid characters');
+  });
+
+  test('validatePassEntryName handles multiple slashes and dots', () => {
+    expect(validatePassEntryName('openpalm/a/b/c')).toBe('openpalm/a/b/c');
+    expect(validatePassEntryName('openpalm/my.key')).toBe('openpalm/my.key');
+    expect(validatePassEntryName('openpalm/my_key')).toBe('openpalm/my_key');
+  });
+
+  test('validatePassEntryName strips leading/trailing slashes', () => {
+    expect(validatePassEntryName('/openpalm/key/')).toBe('openpalm/key');
+  });
+});
+
+describe('PlaintextBackend', () => {
+  test('remove clears value for non-core secrets', async () => {
+    const state = createState();
+    ensureSecrets(state);
+    const backend = new PlaintextBackend(state);
+
+    await backend.write('openpalm/custom/temp', 'temp-value');
+    expect(await backend.exists('openpalm/custom/temp')).toBe(true);
+
+    await backend.remove('openpalm/custom/temp');
+    expect(await backend.exists('openpalm/custom/temp')).toBe(false);
+
+    // Value is cleared — entry shows present: false
+    const entries = await backend.list('openpalm/custom/');
+    const found = entries.find((e) => e.key === 'openpalm/custom/temp');
+    if (found) {
+      expect(found.present).toBe(false);
+    }
+  });
+
+  test('remove clears value but keeps index for core secrets', async () => {
+    const state = createState();
+    ensureSecrets(state);
+    const backend = new PlaintextBackend(state);
+
+    // Write a core secret
+    await backend.write('openpalm/admin-token', 'my-token');
+    expect(await backend.exists('openpalm/admin-token')).toBe(true);
+
+    await backend.remove('openpalm/admin-token');
+    expect(await backend.exists('openpalm/admin-token')).toBe(false);
+
+    // Core secrets still appear in list (as present: false)
+    const entries = await backend.list('openpalm/');
+    const found = entries.find((e) => e.key === 'openpalm/admin-token');
+    expect(found).toBeDefined();
+  });
+
+  test('list includes both core and indexed entries', async () => {
+    const state = createState();
+    ensureSecrets(state);
+    const backend = new PlaintextBackend(state);
+
+    await backend.write('openpalm/custom/my-key', 'value');
+
+    const entries = await backend.list();
+    const coreKeys = entries.filter((e) => e.kind === 'core');
+    const customKeys = entries.filter((e) => e.kind === 'custom');
+
+    expect(coreKeys.length).toBeGreaterThan(0);
+    expect(customKeys.length).toBeGreaterThan(0);
+    expect(customKeys.find((e) => e.key === 'openpalm/custom/my-key')).toBeDefined();
+  });
+
+  test('generate creates a secret with random value', async () => {
+    const state = createState();
+    ensureSecrets(state);
+    const backend = new PlaintextBackend(state);
+
+    const entry = await backend.generate('openpalm/custom/generated', 64);
+    expect(entry.present).toBe(true);
+    expect(await backend.exists('openpalm/custom/generated')).toBe(true);
+  });
+});
+
+describe('PassBackend', () => {
+  test('constructor reads passPrefix from provider config', () => {
+    const state = createState();
+    writeSecretProviderConfig(state, {
+      provider: 'pass',
+      passwordStoreDir: '/tmp/test-pass-store',
+      passPrefix: 'myprefix',
+    });
+
+    const backend = new PassBackend(state);
+    expect(backend.provider).toBe('pass');
+    // Verify it doesn't throw with valid config
+    expect(backend.capabilities.generate).toBe(true);
+  });
+
+  test('constructor uses default store dir when no config', () => {
+    const state = createState();
+    const backend = new PassBackend(state);
+    expect(backend.provider).toBe('pass');
+  });
+
+  test('exists returns false for non-existent entries', async () => {
+    const state = createState();
+    const storeDir = join(rootDir, 'data', 'secrets', 'pass-store');
+    mkdirSync(storeDir, { recursive: true });
+
+    const backend = new PassBackend(state);
+    expect(await backend.exists('openpalm/nonexistent')).toBe(false);
+  });
+
+  test('list returns empty array for empty store', async () => {
+    const state = createState();
+    const storeDir = join(rootDir, 'data', 'secrets', 'pass-store');
+    mkdirSync(storeDir, { recursive: true });
+
+    const backend = new PassBackend(state);
+    const entries = await backend.list();
+    expect(entries).toEqual([]);
+  });
+
+  test('list scopes to passPrefix subdirectory', async () => {
+    const state = createState();
+    const storeDir = join(rootDir, 'data', 'secrets', 'pass-store');
+
+    // Create fake .gpg files under the prefix subdirectory
+    const prefixDir = join(storeDir, 'myprefix', 'openpalm');
+    mkdirSync(prefixDir, { recursive: true });
+    writeFileSync(join(prefixDir, 'admin-token.gpg'), 'fake-gpg-data');
+    writeFileSync(join(prefixDir, 'assistant-token.gpg'), 'fake-gpg-data');
+
+    // Create a file outside the prefix (should not appear)
+    mkdirSync(join(storeDir, 'other'), { recursive: true });
+    writeFileSync(join(storeDir, 'other', 'secret.gpg'), 'fake');
+
+    writeSecretProviderConfig(state, {
+      provider: 'pass',
+      passwordStoreDir: storeDir,
+      passPrefix: 'myprefix',
+    });
+
+    const backend = new PassBackend(state);
+    const entries = await backend.list();
+
+    expect(entries).toHaveLength(2);
+    // Keys should be canonical (without prefix)
+    expect(entries[0]?.key).toBe('openpalm/admin-token');
+    expect(entries[1]?.key).toBe('openpalm/assistant-token');
+  });
+
+  test('exists checks prefixed path in store', async () => {
+    const state = createState();
+    const storeDir = join(rootDir, 'data', 'secrets', 'pass-store');
+    const prefixDir = join(storeDir, 'myprefix');
+    mkdirSync(join(prefixDir, 'openpalm'), { recursive: true });
+    writeFileSync(join(prefixDir, 'openpalm', 'admin-token.gpg'), 'fake');
+
+    writeSecretProviderConfig(state, {
+      provider: 'pass',
+      passwordStoreDir: storeDir,
+      passPrefix: 'myprefix',
+    });
+
+    const backend = new PassBackend(state);
+    expect(await backend.exists('openpalm/admin-token')).toBe(true);
+    expect(await backend.exists('openpalm/nonexistent')).toBe(false);
+  });
+});
+
+describe('detectSecretBackend', () => {
+  test('returns PlaintextBackend by default', () => {
+    const state = createState();
+    const backend = detectSecretBackend(state);
+    expect(backend.provider).toBe('plaintext');
+    expect(backend).toBeInstanceOf(PlaintextBackend);
+  });
+
+  test('returns PassBackend when provider.json has provider: pass', () => {
+    const state = createState();
+    writeSecretProviderConfig(state, {
+      provider: 'pass',
+      passwordStoreDir: '/tmp/test',
+    });
+
+    const backend = detectSecretBackend(state);
+    expect(backend.provider).toBe('pass');
+    expect(backend).toBeInstanceOf(PassBackend);
+  });
+
+  test('returns PassBackend when schema contains @varlock/pass-plugin', () => {
+    const state = createState();
+    mkdirSync(join(state.vaultDir, 'user'), { recursive: true });
+    writeFileSync(
+      join(state.vaultDir, 'user', 'user.env.schema'),
+      '# @plugin(@varlock/pass-plugin)\nOPENAI_API_KEY=pass("openpalm/openai/api-key")\n',
+    );
+
+    const backend = detectSecretBackend(state);
+    expect(backend.provider).toBe('pass');
+    expect(backend).toBeInstanceOf(PassBackend);
+  });
+
+  test('returns PlaintextBackend when provider.json has provider: plaintext', () => {
+    const state = createState();
+    writeSecretProviderConfig(state, { provider: 'plaintext' });
+
+    const backend = detectSecretBackend(state);
+    expect(backend.provider).toBe('plaintext');
+    expect(backend).toBeInstanceOf(PlaintextBackend);
+  });
+});
+
+describe('generateRedactSchema', () => {
+  test('output includes all mapped env keys', () => {
+    const systemEnv: Record<string, string> = {};
+    const schema = generateRedactSchema(systemEnv);
+
+    // All static core mappings should be present
+    expect(schema).toContain('OP_ADMIN_TOKEN=');
+    expect(schema).toContain('OP_ASSISTANT_TOKEN=');
+    expect(schema).toContain('OP_MEMORY_TOKEN=');
+    expect(schema).toContain('OPENAI_API_KEY=');
+    expect(schema).toContain('ANTHROPIC_API_KEY=');
+    expect(schema).toContain('GROQ_API_KEY=');
+    expect(schema).toContain('MISTRAL_API_KEY=');
+    expect(schema).toContain('GOOGLE_API_KEY=');
+    expect(schema).toContain('MCP_API_KEY=');
+    expect(schema).toContain('EMBEDDING_API_KEY=');
+  });
+
+  test('includes legacy aliases', () => {
+    const schema = generateRedactSchema({});
+    expect(schema).toContain('ADMIN_TOKEN=');
+    expect(schema).toContain('OP_OPENCODE_PASSWORD=');
+  });
+
+  test('includes dynamic channel secrets', () => {
+    const systemEnv = {
+      CHANNEL_DISCORD_SECRET: 'abc123',
+      CHANNEL_SLACK_SECRET: 'def456',
+    };
+    const schema = generateRedactSchema(systemEnv);
+    expect(schema).toContain('CHANNEL_DISCORD_SECRET=');
+    expect(schema).toContain('CHANNEL_SLACK_SECRET=');
+  });
+
+  test('has correct header format', () => {
+    const schema = generateRedactSchema({});
+    expect(schema).toContain('@defaultSensitive=true');
+    expect(schema).toContain('@defaultRequired=false');
+  });
+
+  test('entries are sorted', () => {
+    const schema = generateRedactSchema({});
+    const lines = schema
+      .split('\n')
+      .filter((l) => l.match(/^[A-Z]/))
+      .map((l) => l.replace(/=.*$/, ''));
+
+    const sorted = [...lines].sort();
+    expect(lines).toEqual(sorted);
+  });
+});
+

package/src/control-plane/secret-backend.ts

@@ -0,0 +1,322 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { execFile as execFileCb, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { join, normalize, resolve } from 'node:path';
+import type { ControlPlaneState } from './types.js';
+import {
+  classifySecretKey,
+  classifySecretScope,
+  ensurePlaintextSecretEntry,
+  findCoreSecretByKey,
+  getCoreSecretMappings,
+  readPlaintextSecretIndex,
+  removePlaintextSecretEntry,
+  type SecretEntryMetadata,
+  type SecretScope,
+} from './secret-mappings.js';
+import { readSecretProviderConfig } from './provider-config.js';
+import {
+  readStackEnv,
+  updateSecretsEnv,
+  updateSystemSecretsEnv,
+} from './secrets.js';
+
+const execFile = promisify(execFileCb);
+
+/** Run a command with stdin input, returning a promise. */
+function execWithInput(
+  cmd: string,
+  args: string[],
+  input: string,
+  env: NodeJS.ProcessEnv,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { env, stdio: ['pipe', 'pipe', 'pipe'] });
+    let stderr = '';
+    child.stderr?.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} exited with code ${code}: ${stderr}`));
+    });
+    child.stdin?.end(input);
+  });
+}
+
+type ResolvedSecretTarget = {
+  key: string;
+  scope: SecretScope;
+  envKey?: string;
+};
+
+export type SecretBackendCapabilities = {
+  generate: boolean;
+  remove: boolean;
+  rename: boolean;
+};
+
+export interface SecretBackend {
+  readonly provider: 'plaintext' | 'pass';
+  readonly capabilities: SecretBackendCapabilities;
+  list(prefix?: string): Promise<SecretEntryMetadata[]>;
+  write(key: string, value: string): Promise<SecretEntryMetadata>;
+  generate(key: string, length?: number): Promise<SecretEntryMetadata>;
+  remove(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+}
+
+function generateSecretValue(length = 32): string {
+  // Hex encoding produces two output characters per byte. Clamp to at least
+  // 16 bytes (32 hex chars) so generated secrets stay comfortably strong.
+  return randomBytes(Math.max(16, Math.ceil(length / 2))).toString('hex').slice(0, length);
+}
+
+function resolvePlaintextTarget(state: ControlPlaneState, key: string): ResolvedSecretTarget {
+  const systemEnv = readStackEnv(state.vaultDir);
+  const coreMapping = findCoreSecretByKey(key, systemEnv);
+  if (coreMapping) {
+    return { key, scope: coreMapping.scope, envKey: coreMapping.envKey };
+  }
+
+  const indexed = ensurePlaintextSecretEntry(state, key);
+  return { key, scope: indexed.scope, envKey: indexed.envKey };
+}
+
+function currentValueForTarget(state: ControlPlaneState, target: ResolvedSecretTarget): string {
+  if (!target.envKey) return '';
+  const env = target.scope === 'system'
+    ? readStackEnv(state.vaultDir)
+    : readStackEnv(state.vaultDir);
+  return env[target.envKey] ?? '';
+}
+
+export class PlaintextBackend implements SecretBackend {
+  readonly provider = 'plaintext' as const;
+  readonly capabilities = { generate: true, remove: true, rename: false } as const;
+
+  constructor(private readonly state: ControlPlaneState) {}
+
+  async list(prefix = 'openpalm/'): Promise<SecretEntryMetadata[]> {
+    const userEnv = readStackEnv(this.state.vaultDir);
+    const systemEnv = readStackEnv(this.state.vaultDir);
+    const index = readPlaintextSecretIndex(this.state);
+    const entries: SecretEntryMetadata[] = [];
+
+    for (const mapping of getCoreSecretMappings(systemEnv)) {
+      if (!mapping.secretKey.startsWith(prefix)) continue;
+      const env = mapping.scope === 'system' ? systemEnv : userEnv;
+      entries.push({
+        key: mapping.secretKey,
+        scope: mapping.scope,
+        kind: 'core',
+        provider: this.provider,
+        present: Boolean(env[mapping.envKey]),
+        envKey: mapping.envKey,
+      });
+    }
+
+    for (const [key, entry] of Object.entries(index.entries)) {
+      if (!key.startsWith(prefix)) continue;
+      const env = entry.scope === 'system' ? systemEnv : userEnv;
+      entries.push({
+        key,
+        scope: entry.scope,
+        kind: entry.kind,
+        provider: this.provider,
+        present: Boolean(env[entry.envKey]),
+        envKey: entry.envKey,
+        updatedAt: entry.updatedAt,
+      });
+    }
+
+    entries.sort((a, b) => a.key.localeCompare(b.key));
+    return entries;
+  }
+
+  async write(key: string, value: string): Promise<SecretEntryMetadata> {
+    const target = resolvePlaintextTarget(this.state, key);
+    if (!target.envKey) {
+      throw new Error(`Unable to resolve env key for secret ${key}`);
+    }
+
+    if (target.scope === 'system') {
+      updateSystemSecretsEnv(this.state, { [target.envKey]: value });
+    } else {
+      updateSecretsEnv(this.state, { [target.envKey]: value });
+    }
+
+    return {
+      key,
+      scope: target.scope,
+      kind: key.startsWith('openpalm/component/') ? 'component' : key.startsWith('openpalm/custom/') ? 'custom' : 'core',
+      provider: this.provider,
+      present: true,
+      envKey: target.envKey,
+    };
+  }
+
+  async generate(key: string, length = 32): Promise<SecretEntryMetadata> {
+    return this.write(key, generateSecretValue(length));
+  }
+
+  async remove(key: string): Promise<void> {
+    const target = resolvePlaintextTarget(this.state, key);
+    if (target.envKey) {
+      if (target.scope === 'system') {
+        updateSystemSecretsEnv(this.state, { [target.envKey]: '' });
+      } else {
+        updateSecretsEnv(this.state, { [target.envKey]: '' });
+      }
+    }
+    if (!findCoreSecretByKey(key, readStackEnv(this.state.vaultDir))) {
+      removePlaintextSecretEntry(this.state, key);
+    }
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const target = resolvePlaintextTarget(this.state, key);
+    return currentValueForTarget(this.state, target).length > 0;
+  }
+}
+
+export function validatePassEntryName(entry: string): string {
+  const trimmed = entry.trim().replace(/^\/+|\/+$/g, '');
+  if (!trimmed) {
+    throw new Error('Secret key must not be empty');
+  }
+  if (trimmed.includes('..')) {
+    throw new Error('Secret key must not contain path traversal');
+  }
+  if (!/^[a-z0-9._/-]+$/.test(trimmed)) {
+    throw new Error('Secret key contains invalid characters');
+  }
+  return trimmed;
+}
+
+function walkPassStore(dir: string, prefix = ''): string[] {
+  if (!existsSync(dir)) return [];
+  const entries: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+    if (stat.isDirectory()) {
+      entries.push(...walkPassStore(fullPath, prefix ? `${prefix}/${entry}` : entry));
+      continue;
+    }
+    if (!entry.endsWith('.gpg')) continue;
+    const name = entry.replace(/\.gpg$/, '');
+    entries.push(prefix ? `${prefix}/${name}` : name);
+  }
+  return entries;
+}
+
+export class PassBackend implements SecretBackend {
+  readonly provider = 'pass' as const;
+  readonly capabilities = { generate: true, remove: true, rename: false } as const;
+  private readonly passwordStoreDir: string;
+  private readonly passPrefix: string;
+
+  constructor(private readonly state: ControlPlaneState) {
+    const config = readSecretProviderConfig(state);
+    this.passwordStoreDir = config?.passwordStoreDir ?? `${state.dataDir}/secrets/pass-store`;
+    this.passPrefix = config?.passPrefix ?? '';
+  }
+
+  private env(): NodeJS.ProcessEnv {
+    return {
+      ...process.env,
+      PASSWORD_STORE_DIR: this.passwordStoreDir,
+    };
+  }
+
+  /** Prepend passPrefix to a canonical key for pass store operations. */
+  private prefixedEntry(canonicalKey: string): string {
+    const entry = validatePassEntryName(canonicalKey);
+    return this.passPrefix ? `${this.passPrefix}/${entry}` : entry;
+  }
+
+  private keyPath(key: string): string {
+    const prefixed = this.prefixedEntry(key);
+    const normalizedEntry = normalize(prefixed);
+    const resolvedPath = resolve(this.passwordStoreDir, `${normalizedEntry}.gpg`);
+    const resolvedStore = resolve(this.passwordStoreDir);
+    if (!resolvedPath.startsWith(`${resolvedStore}/`)) {
+      throw new Error('Secret key resolves outside the password store');
+    }
+    return resolvedPath;
+  }
+
+  async list(prefix = 'openpalm/'): Promise<SecretEntryMetadata[]> {
+    // Scope walk to the passPrefix subdirectory
+    const walkDir = this.passPrefix
+      ? join(this.passwordStoreDir, this.passPrefix)
+      : this.passwordStoreDir;
+    return walkPassStore(walkDir)
+      .filter((entry) => entry.startsWith(prefix))
+      .sort((a, b) => a.localeCompare(b))
+      .map((key) => ({
+        key,
+        scope: classifySecretScope(key),
+        kind: classifySecretKey(key),
+        provider: this.provider,
+        present: true,
+      }));
+  }
+
+  async write(key: string, value: string): Promise<SecretEntryMetadata> {
+    const canonicalKey = validatePassEntryName(key);
+    const storeEntry = this.prefixedEntry(canonicalKey);
+    await execWithInput('pass', ['insert', '-m', '-f', storeEntry], `${value}\n`, this.env());
+    return {
+      key: canonicalKey,
+      scope: classifySecretScope(canonicalKey),
+      kind: classifySecretKey(canonicalKey),
+      provider: this.provider,
+      present: true,
+    };
+  }
+
+  async generate(key: string, length = 32): Promise<SecretEntryMetadata> {
+    const canonicalKey = validatePassEntryName(key);
+    const storeEntry = this.prefixedEntry(canonicalKey);
+    await execFile('pass', ['generate', '-n', '-f', storeEntry, String(length)], {
+      env: this.env(),
+    });
+    return {
+      key: canonicalKey,
+      scope: classifySecretScope(canonicalKey),
+      kind: classifySecretKey(canonicalKey),
+      provider: this.provider,
+      present: true,
+    };
+  }
+
+  async remove(key: string): Promise<void> {
+    const storeEntry = this.prefixedEntry(key);
+    await execFile('pass', ['rm', '-f', storeEntry], {
+      env: this.env(),
+    });
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return existsSync(this.keyPath(key));
+  }
+}
+
+export function detectSecretBackend(state: ControlPlaneState): SecretBackend {
+  const providerConfig = readSecretProviderConfig(state);
+  if (providerConfig?.provider === 'pass') {
+    return new PassBackend(state);
+  }
+
+  for (const schemaPath of [`${state.vaultDir}/user/user.env.schema`, `${state.vaultDir}/stack/stack.env.schema`]) {
+    if (!existsSync(schemaPath)) continue;
+    const content = readFileSync(schemaPath, 'utf-8');
+    if (content.includes('@varlock/pass-plugin')) {
+      return new PassBackend(state);
+    }
+  }
+
+  return new PlaintextBackend(state);
+}