@openpalm/lib 0.11.0-beta.8 → 0.11.0-rc.1

package/src/control-plane/rollback.ts

@@ -2,10 +2,10 @@
  * Snapshot-based rollback for the OpenPalm control plane.
  *
  * Before writing validated changes to live paths, the current state
- * is snapshotted to ~/.cache/openpalm/rollback/. On deploy failure
+ * is snapshotted to OP_HOME/data/rollback/. On deploy failure
  * (or manual `openpalm rollback`), the snapshot is restored.
  */
-import { mkdirSync, copyFileSync, existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import type { ControlPlaneState } from "./types.js";
 import { resolveRollbackDir } from "./home.js";
@@ -14,9 +14,11 @@ import { resolveRollbackDir } from "./home.js";
  *  Only config/ system files are included — user-editable config files
  *  are never overwritten by lifecycle operations. */
 const SNAPSHOT_FILES = [
-  "config/stack/stack.env",
-  "config/stack/guardian.env",
-  "config/auth.json",
+  "knowledge/env/stack.env",
+  "config/stack/services.compose.yml",
+  "config/stack/channels.compose.yml",
+  "config/stack/custom.compose.yml",
+  "knowledge/secrets/auth.json",
 ];
 
 /**
@@ -30,8 +32,7 @@ function safeCopy(src: string, dest: string): void {
 
 /**
  * Save the current live configuration files to the rollback directory.
- * Also snapshots stack/core.compose.yml and all addon compose.yml files
- * under stack/addons/.
+ * Also snapshots stack/core.compose.yml.
  */
 export function snapshotCurrentState(state: ControlPlaneState): void {
   const rollbackDir = resolveRollbackDir();
@@ -48,22 +49,6 @@ export function snapshotCurrentState(state: ControlPlaneState): void {
   const coreCompose = join(state.homeDir, "config/stack/core.compose.yml");
   safeCopy(coreCompose, join(rollbackDir, "config/stack/core.compose.yml"));
 
-  // Snapshot config/stack/addons/*/compose.yml
-  const addonsDir = join(state.homeDir, "config/stack/addons");
-  if (existsSync(addonsDir)) {
-    for (const entry of readdirSync(addonsDir, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        const addonCompose = join(addonsDir, entry.name, "compose.yml");
-        if (existsSync(addonCompose)) {
-          safeCopy(
-            addonCompose,
-            join(rollbackDir, "config/stack/addons", entry.name, "compose.yml"),
-          );
-        }
-      }
-    }
-  }
-
   // Write a timestamp marker
   writeFileSync(
     join(rollbackDir, ".snapshot-ts"),
@@ -94,21 +79,6 @@ export function restoreSnapshot(state: ControlPlaneState): void {
     safeCopy(srcCoreCompose, join(state.homeDir, "config/stack/core.compose.yml"));
   }
 
-  // Restore config/stack/addons/*/compose.yml
-  const srcAddons = join(rollbackDir, "config/stack/addons");
-  if (existsSync(srcAddons)) {
-    for (const entry of readdirSync(srcAddons, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        const srcAddonCompose = join(srcAddons, entry.name, "compose.yml");
-        if (existsSync(srcAddonCompose)) {
-          safeCopy(
-            srcAddonCompose,
-            join(state.homeDir, "config/stack/addons", entry.name, "compose.yml"),
-          );
-        }
-      }
-    }
-  }
 }
 
 /**

package/src/control-plane/scheduler.ts

@@ -1,7 +1,7 @@
 /**
  * Automation scheduler — types and akm CLI integration.
  *
- * Automations are AKM markdown task files at ${stashDir}/tasks/*.md.
+ * Automations are AKM task files at ${stashDir}/tasks/*.yml.
  * Scheduling is handled by the OS cron daemon (via `akm tasks sync`).
  * Execution is handled by `akm tasks run <id>`.
  */
@@ -10,6 +10,7 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createLogger } from "../logger.js";
 import { loadMarkdownTasks, taskToAutomationConfig } from "./markdown-task.js";
+import { assertAkmEnvComplete } from "./akm-user-env.js";
 
 const logger = createLogger("scheduler");
 
@@ -69,8 +70,9 @@ export async function executeAutomation(
   id: string,
   akmEnv: NodeJS.ProcessEnv,
 ): Promise<AutomationRunResult> {
-  // Strip .md suffix if caller passes the full filename
-  const taskId = id.replace(/\.md$/, "");
+  assertAkmEnvComplete(akmEnv); // I-6: never let akm fall back to the global config
+  // Strip file suffix if caller passes the full filename.
+  const taskId = id.replace(/\.(?:ya?ml|md)$/, "");
   return new Promise((resolve) => {
     execFile(
       "akm",
@@ -89,9 +91,10 @@ export async function executeAutomation(
   });
 }
 
-// ── Sync crontab with stash/tasks/*.md ───────────────────────────────────
+// ── Sync crontab with knowledge/tasks/*.yml ──────────────────────────────────
 
 export async function syncAutomations(akmEnv: NodeJS.ProcessEnv): Promise<void> {
+  assertAkmEnvComplete(akmEnv); // I-6: never let akm fall back to the global config
   return new Promise((resolve, reject) => {
     execFile(
       "akm",
@@ -112,11 +115,11 @@ export async function syncAutomations(akmEnv: NodeJS.ProcessEnv): Promise<void>
 
 export function readAutomationLogs(
   id: string,
-  cacheDir: string,
+  dataDir: string,
   limit: number = 50,
 ): string[] {
-  const taskId = id.replace(/\.md$/, "");
-  const logDir = join(cacheDir, "akm", "tasks", "logs", taskId);
+  const taskId = id.replace(/\.(?:ya?ml|md)$/, "");
+  const logDir = join(dataDir, "akm", "cache", "tasks", "logs", taskId);
   if (!existsSync(logDir)) return [];
 
   const logFiles = readdirSync(logDir, { withFileTypes: true })

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

@@ -0,0 +1,159 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  auditComposeSecrets,
+  auditFileBasedSecrets,
+  auditSecretFilesystem,
+  auditStackEnv,
+  isSecretLikeKey,
+} from './secret-audit.js';
+
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'secret-audit-test-'));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('isSecretLikeKey', () => {
+  it('detects secret-like keys but allows file indirection keys', () => {
+    expect(isSecretLikeKey('OPENAI_API_KEY')).toBe(true);
+    expect(isSecretLikeKey('OP_UI_LOGIN_PASSWORD')).toBe(true);
+    expect(isSecretLikeKey('CHANNEL_CHAT_SECRET')).toBe(true);
+    expect(isSecretLikeKey('OPENAI_API_KEY_FILE')).toBe(false);
+    expect(isSecretLikeKey('OP_IMAGE_TAG')).toBe(false);
+  });
+});
+
+describe('auditStackEnv', () => {
+  it('rejects secret-like keys in stack.env', () => {
+    const issues = auditStackEnv({
+      OP_HOME: '/home/me/.openpalm',
+      OP_IMAGE_TAG: 'latest',
+      OPENAI_API_KEY: 'sk-test',
+      OP_UI_LOGIN_PASSWORD: 'secret',
+    });
+
+    expect(issues.map((entry) => entry.code)).toEqual([
+      'stack-env-secret-key',
+      'stack-env-secret-key',
+    ]);
+  });
+
+  it('accepts non-secret runtime configuration', () => {
+    expect(auditStackEnv({
+      OP_HOME: '/home/me/.openpalm',
+      OP_UID: '1000',
+      OP_GID: '1000',
+      OP_ASSISTANT_PORT: '3800',
+      OPENAI_BASE_URL: 'http://localhost:11434/v1',
+    })).toEqual([]);
+  });
+});
+
+describe('auditComposeSecrets', () => {
+  it('rejects service env_file and direct secret-like environment values', () => {
+    const issues = auditComposeSecrets(`
+services:
+  guardian:
+    env_file:
+      - ./service.env
+    environment:
+      OPENCODE_SERVER_PASSWORD: secret
+`);
+
+    expect(issues.map((entry) => entry.code)).toEqual([
+      'compose-service-env-file',
+      'compose-secret-env-var',
+    ]);
+  });
+
+  it('accepts *_FILE environment variables and in-boundary secret grants', () => {
+    const issues = auditComposeSecrets({
+      services: {
+        assistant: {
+          environment: {
+            OPENAI_API_KEY_FILE: '/run/secrets/provider_openai_api_key',
+          },
+          secrets: ['provider_openai_api_key'],
+        },
+        guardian: {
+          environment: ['GUARDIAN_CHANNEL_SECRET_FILE=/run/secrets/guardian_channel_secret'],
+          secrets: [{ source: 'guardian_channel_secret' }, { source: 'channel_chat_hmac' }],
+        },
+        chat: {
+          image: 'openpalm/channel:latest',
+          secrets: ['channel_chat_hmac'],
+        },
+      },
+    });
+
+    expect(issues).toEqual([]);
+  });
+
+  it('rejects cross-boundary secret grants', () => {
+    const issues = auditComposeSecrets({
+      services: {
+        assistant: { secrets: ['guardian_channel_secret'] },
+        chat: { image: 'openpalm/channel:latest', secrets: ['channel_slack_hmac'] },
+        guardian: { secrets: ['admin_session_key'] },
+      },
+    });
+
+    expect(issues.map((entry) => entry.code)).toEqual([
+      'compose-secret-boundary',
+      'compose-secret-boundary',
+      'compose-secret-boundary',
+    ]);
+  });
+});
+
+describe('auditSecretFilesystem', () => {
+  it('requires a 0700 secrets directory and 0600 secret files', () => {
+    const secretsDir = join(tempDir, 'config', 'stack', 'secrets');
+    mkdirSync(secretsDir, { recursive: true, mode: 0o700 });
+    chmodSync(secretsDir, 0o700);
+    const secretPath = join(secretsDir, 'provider_openai_api_key');
+    writeFileSync(secretPath, 'sk-test\n', { mode: 0o600 });
+    chmodSync(secretPath, 0o600);
+
+    expect(auditSecretFilesystem(secretsDir)).toEqual([]);
+  });
+
+  it('reports unsafe directory and file permissions', () => {
+    const secretsDir = join(tempDir, 'secrets');
+    mkdirSync(secretsDir, { recursive: true, mode: 0o755 });
+    chmodSync(secretsDir, 0o755);
+    const secretPath = join(secretsDir, 'admin_session_key');
+    writeFileSync(secretPath, 'secret\n', { mode: 0o644 });
+    chmodSync(secretPath, 0o644);
+
+    expect(auditSecretFilesystem(secretsDir).map((entry) => entry.code)).toEqual([
+      'secrets-dir-mode',
+      'secret-file-mode',
+    ]);
+  });
+});
+
+describe('auditFileBasedSecrets', () => {
+  it('combines stack env, compose, and filesystem checks', () => {
+    const secretsDir = join(tempDir, 'secrets');
+    mkdirSync(secretsDir, { recursive: true, mode: 0o700 });
+    chmodSync(secretsDir, 0o700);
+    writeFileSync(join(secretsDir, 'provider_openai_api_key'), 'sk-test\n', { mode: 0o600 });
+
+    const result = auditFileBasedSecrets({
+      stackEnvContent: 'OP_HOME=/tmp/openpalm\nOPENAI_API_KEY=bad\n',
+      composeConfig: 'services:\n  assistant:\n    environment:\n      OPENAI_API_KEY_FILE: /run/secrets/provider_openai_api_key\n',
+      secretsDir,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.issues.map((entry) => entry.code)).toEqual(['stack-env-secret-key']);
+  });
+});

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

@@ -0,0 +1,255 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { parseEnvContent, parseEnvFile } from './env.js';
+
+export type SecretAuditSeverity = 'error' | 'warning';
+
+export type SecretAuditIssue = {
+  severity: SecretAuditSeverity;
+  code: string;
+  message: string;
+  path?: string;
+};
+
+export type SecretAuditResult = {
+  ok: boolean;
+  issues: SecretAuditIssue[];
+};
+
+export type SecretAuditOptions = {
+  stackEnvPath?: string;
+  stackEnvContent?: string;
+  composeConfig?: string | unknown;
+  secretsDir?: string;
+};
+
+type ComposeService = {
+  image?: unknown;
+  env_file?: unknown;
+  environment?: unknown;
+  secrets?: unknown;
+  networks?: unknown;
+};
+
+type ComposeConfig = {
+  services?: Record<string, ComposeService>;
+};
+
+const SECRET_FILE_MODE = 0o600;
+const SECRET_DIR_MODE = 0o700;
+
+const NON_SECRET_STACK_KEYS = new Set([
+  'COMPOSE_PROJECT_NAME',
+  'OP_PROJECT_NAME',
+  'OP_HOME',
+  'OP_UID',
+  'OP_GID',
+  'OP_IMAGE_NAMESPACE',
+  'OP_IMAGE_TAG',
+  'OP_SETUP_COMPLETE',
+  'OP_ASSISTANT_BIND_ADDRESS',
+  'OP_ASSISTANT_PORT',
+  'OP_ASSISTANT_SSH_BIND_ADDRESS',
+  'OP_ASSISTANT_SSH_PORT',
+  'OPENCODE_ENABLE_SSH',
+  'OP_CHAT_BIND_ADDRESS',
+  'OP_CHAT_PORT',
+  'OP_API_BIND_ADDRESS',
+  'OP_API_PORT',
+  'OP_VOICE_BIND_ADDRESS',
+  'OP_VOICE_PORT',
+  'OP_OLLAMA_BIND_ADDRESS',
+  'OP_VOICE_PROFILE',
+  'OP_OLLAMA_PROFILE',
+  'OP_HOST_UI_PORT',
+  'OP_OWNER_NAME',
+  'OP_OWNER_EMAIL',
+  'OPENAI_BASE_URL',
+]);
+
+function issue(code: string, message: string, path?: string): SecretAuditIssue {
+  return { severity: 'error', code, message, path };
+}
+
+export function isSecretLikeKey(key: string): boolean {
+  const normalized = key.toUpperCase();
+  if (normalized.endsWith('_FILE')) return false;
+  return /(^|_)(SECRET|TOKEN|PASSWORD|PASS|API_KEY|PRIVATE_KEY|CREDENTIAL|CREDENTIALS)(_|$)/.test(normalized);
+}
+
+function parseComposeConfig(input: string | unknown): ComposeConfig {
+  if (typeof input === 'string') {
+    const parsed = parseYaml(input) as unknown;
+    return isRecord(parsed) ? parsed as ComposeConfig : {};
+  }
+  return isRecord(input) ? input as ComposeConfig : {};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function environmentEntries(environment: unknown): Array<[string, unknown]> {
+  if (Array.isArray(environment)) {
+    return environment.flatMap((entry) => {
+      if (typeof entry !== 'string') return [];
+      const eq = entry.indexOf('=');
+      return eq > 0 ? [[entry.slice(0, eq), entry.slice(eq + 1)] as [string, string]] : [[entry, '']];
+    });
+  }
+  if (isRecord(environment)) return Object.entries(environment);
+  return [];
+}
+
+function serviceSecrets(secrets: unknown): string[] {
+  if (!Array.isArray(secrets)) return [];
+  return secrets.flatMap((entry) => {
+    if (typeof entry === 'string') return [entry];
+    if (!isRecord(entry)) return [];
+    const source = entry.source ?? entry.target;
+    return typeof source === 'string' ? [source] : [];
+  });
+}
+
+function serviceNetworks(networks: unknown): string[] {
+  if (Array.isArray(networks)) return networks.filter((entry): entry is string => typeof entry === 'string');
+  if (isRecord(networks)) return Object.keys(networks);
+  return [];
+}
+
+function normalizedSecretName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+
+function isChannelService(name: string, service: ComposeService): boolean {
+  const normalized = normalizedSecretName(name);
+  if (normalized.startsWith('channel_')) return true;
+  const image = typeof service.image === 'string' ? service.image.toLowerCase() : '';
+  if (image.includes('/channel') || image.endsWith(':channel') || image.includes('openpalm/channel')) return true;
+  return serviceNetworks(service.networks).includes('channel_lan') && name !== 'guardian';
+}
+
+function allowedSecretForService(serviceName: string, service: ComposeService, secretName: string): boolean {
+  const serviceId = normalizedSecretName(serviceName.replace(/^channel[-_]/i, ''));
+  const secretId = normalizedSecretName(secretName);
+
+  if (serviceName === 'assistant') {
+    return /^(assistant|opencode|provider|llm|embedding|akm|user)_/.test(secretId);
+  }
+  if (serviceName === 'guardian') {
+    return secretId.startsWith('guardian_') || secretId.startsWith('channel_');
+  }
+  if (serviceName === 'admin') {
+    return /^(admin|ui|openpalm)_/.test(secretId);
+  }
+  if (isChannelService(serviceName, service)) {
+    return secretId.startsWith(`channel_${serviceId}_`) || secretId.startsWith(`${serviceId}_`);
+  }
+  return secretId.startsWith(`${serviceId}_`);
+}
+
+export function auditStackEnv(env: Record<string, string>, label = 'stack.env'): SecretAuditIssue[] {
+  const issues: SecretAuditIssue[] = [];
+  for (const key of Object.keys(env)) {
+    if (NON_SECRET_STACK_KEYS.has(key)) continue;
+    if (isSecretLikeKey(key)) {
+      issues.push(issue(
+        'stack-env-secret-key',
+        `${label} must not contain secret-like key ${key}; store it as a file under knowledge/secrets and expose ${key}_FILE instead.`,
+        `${label}:${key}`,
+      ));
+    }
+  }
+  return issues;
+}
+
+export function auditComposeSecrets(composeConfig: string | unknown): SecretAuditIssue[] {
+  const compose = parseComposeConfig(composeConfig);
+  const issues: SecretAuditIssue[] = [];
+  for (const [serviceName, service] of Object.entries(compose.services ?? {})) {
+    if (service.env_file !== undefined) {
+      issues.push(issue(
+        'compose-service-env-file',
+        `service ${serviceName} must not use env_file; pass non-secrets explicitly and use Docker secrets for secret values.`,
+        `services.${serviceName}.env_file`,
+      ));
+    }
+
+    for (const [key] of environmentEntries(service.environment)) {
+      if (isSecretLikeKey(key)) {
+        issues.push(issue(
+          'compose-secret-env-var',
+          `service ${serviceName} environment key ${key} is secret-like; expose only ${key}_FILE.`,
+          `services.${serviceName}.environment.${key}`,
+        ));
+      }
+    }
+
+    for (const secretName of serviceSecrets(service.secrets)) {
+      if (!allowedSecretForService(serviceName, service, secretName)) {
+        issues.push(issue(
+          'compose-secret-boundary',
+          `service ${serviceName} is not allowed to mount secret ${secretName}.`,
+          `services.${serviceName}.secrets`,
+        ));
+      }
+    }
+  }
+  return issues;
+}
+
+export function auditSecretFilesystem(secretsDir: string): SecretAuditIssue[] {
+  const issues: SecretAuditIssue[] = [];
+  if (!existsSync(secretsDir)) {
+    issues.push(issue('secrets-dir-missing', `secrets directory does not exist: ${secretsDir}`, secretsDir));
+    return issues;
+  }
+
+  const dirStat = statSync(secretsDir);
+  if (!dirStat.isDirectory()) {
+    issues.push(issue('secrets-dir-not-directory', `secrets path is not a directory: ${secretsDir}`, secretsDir));
+    return issues;
+  }
+  if ((dirStat.mode & 0o777) !== SECRET_DIR_MODE) {
+    issues.push(issue('secrets-dir-mode', `secrets directory must be 0700, got ${formatMode(dirStat.mode)}.`, secretsDir));
+  }
+
+  for (const entry of readdirSync(secretsDir, { withFileTypes: true })) {
+    const path = join(secretsDir, entry.name);
+    if (entry.isDirectory()) {
+      issues.push(...auditSecretFilesystem(path));
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const fileStat = statSync(path);
+    if ((fileStat.mode & 0o777) !== SECRET_FILE_MODE) {
+      issues.push(issue('secret-file-mode', `secret file must be 0600, got ${formatMode(fileStat.mode)}.`, path));
+    }
+  }
+  return issues;
+}
+
+function formatMode(mode: number): string {
+  return `0${(mode & 0o777).toString(8)}`;
+}
+
+export function auditFileBasedSecrets(options: SecretAuditOptions): SecretAuditResult {
+  const issues: SecretAuditIssue[] = [];
+
+  if (options.stackEnvContent !== undefined) {
+    issues.push(...auditStackEnv(parseEnvContent(options.stackEnvContent), 'stack.env'));
+  } else if (options.stackEnvPath) {
+    issues.push(...auditStackEnv(parseEnvFile(options.stackEnvPath), options.stackEnvPath));
+  }
+
+  if (options.composeConfig !== undefined) {
+    issues.push(...auditComposeSecrets(options.composeConfig));
+  }
+
+  if (options.secretsDir) {
+    issues.push(...auditSecretFilesystem(options.secretsDir));
+  }
+
+  return { ok: issues.length === 0, issues };
+}

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

@@ -62,7 +62,7 @@ type SecretIndexFile = {
 };
 
 function secretIndexPath(state: ControlPlaneState): string {
-  return `${state.stateDir}/secrets/plaintext-index.json`;
+  return `${state.dataDir}/secrets/plaintext-index.json`;
 }
 
 function normalizeIndexedKey(key: string): string {
@@ -144,7 +144,7 @@ export function readPlaintextSecretIndex(state: ControlPlaneState): SecretIndexF
 }
 
 export function writePlaintextSecretIndex(state: ControlPlaneState, index: SecretIndexFile): void {
-  const dir = `${state.stateDir}/secrets`;
+  const dir = `${state.dataDir}/secrets`;
   mkdirSync(dir, { recursive: true });
   writeFileSync(secretIndexPath(state), JSON.stringify(index, null, 2) + '\n');
 }

package/src/control-plane/secrets-files.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'bun:test';
+import { mkdtempSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { buildEnvFiles } from './config-persistence.js';
+import { assertNoSecretLikeStackEnvKeys, patchSecretsEnvFile } from './secrets.js';
+import { listSecretNames, readSecret, resolveSecretsDir, secretPath, writeSecret, listSecretFiles, readSecretFile, writeSecretFile, removeSecretFile, assertSafeSecretFilename } from './secrets-files.js';
+import type { ControlPlaneState } from './types.js';
+
+function tempStackDir(): string {
+  return mkdtempSync(join(tmpdir(), 'openpalm-secrets-files-'));
+}
+
+describe('file-based control-plane secrets', () => {
+  it('creates the secrets directory and files with private permissions', () => {
+    const stackDir = tempStackDir();
+
+    writeSecret(stackDir, 'channel_chat_secret', 'value');
+
+    expect(resolveSecretsDir(stackDir)).toBe(join(stackDir, 'knowledge', 'secrets'));
+    expect(statSync(resolveSecretsDir(stackDir)).mode & 0o777).toBe(0o700);
+    expect(statSync(secretPath(stackDir, 'channel_chat_secret')).mode & 0o777).toBe(0o600);
+    expect(readSecret(stackDir, 'channel_chat_secret')).toBe('value');
+    expect(listSecretNames(stackDir)).toEqual(['channel_chat_secret']);
+  });
+
+  it('rejects invalid secret names', () => {
+    const stackDir = tempStackDir();
+
+    expect(() => writeSecret(stackDir, 'CHANNEL_CHAT_SECRET', 'value')).toThrow(/Invalid secret name/);
+    expect(() => writeSecret(stackDir, 'channel-chat-secret', 'value')).toThrow(/Invalid secret name/);
+  });
+
+  it('rejects secret-like stack.env keys', () => {
+    expect(() => assertNoSecretLikeStackEnvKeys({ OPENAI_API_KEY: 'sk-test' })).toThrow(/OPENAI_API_KEY/);
+    expect(() => assertNoSecretLikeStackEnvKeys({ OP_OWNER_NAME: 'Ada' })).not.toThrow();
+  });
+
+  it('does not include file-based secrets in compose env files', () => {
+    const stackDir = tempStackDir();
+    const stashDir = join(stackDir, 'knowledge');
+    const stackEnv = join(stashDir, 'env', 'stack.env');
+    mkdirSync(join(stashDir, 'env'), { recursive: true });
+    writeFileSync(stackEnv, 'OP_HOME=/tmp/openpalm\n');
+    writeSecret(stackDir, 'channel_chat_secret', 'value');
+    const state = { stackDir, stashDir } as ControlPlaneState;
+
+    expect(buildEnvFiles(state)).toEqual([stackEnv]);
+  });
+
+  it('routes secret patches to lower-case secret files instead of stack.env', () => {
+    const stackDir = tempStackDir();
+    writeFileSync(join(stackDir, 'stack.env'), 'OP_SETUP_COMPLETE=false\n');
+
+    patchSecretsEnvFile(stackDir, { OP_UI_LOGIN_PASSWORD: 'pw', OP_IMAGE_TAG: 'latest' });
+
+    expect(readSecret(stackDir, 'op_ui_login_password')).toBe('pw\n');
+    expect(listSecretNames(stackDir)).toContain('op_ui_login_password');
+  });
+});
+
+describe('secrets-dir file browser API (admin Secrets tab)', () => {
+  it('lists ALL files incl. dotted names like auth.json, with sizes', () => {
+    const stackDir = tempStackDir();
+    writeSecret(stackDir, 'channel_api_secret', 'abc');           // regex-valid secret
+    writeFileSync(join(resolveSecretsDir(stackDir), 'auth.json'), '{"k":1}'); // dotted file
+    const files = listSecretFiles(stackDir);
+    const names = files.map((f) => f.name);
+    expect(names).toContain('auth.json');           // included (strict listSecretNames would exclude it)
+    expect(names).toContain('channel_api_secret');
+    expect(files.find((f) => f.name === 'auth.json')!.size).toBe('{"k":1}'.length);
+    // strict API still excludes the dotted file
+    expect(listSecretNames(stackDir)).not.toContain('auth.json');
+  });
+
+  it('reads, writes (0600), and removes a dotted file by basename', () => {
+    const stackDir = tempStackDir();
+    writeSecretFile(stackDir, 'auth.json', '{"token":"x"}');
+    expect(statSync(join(resolveSecretsDir(stackDir), 'auth.json')).mode & 0o777).toBe(0o600);
+    expect(readSecretFile(stackDir, 'auth.json')).toBe('{"token":"x"}');
+    removeSecretFile(stackDir, 'auth.json');
+    expect(readSecretFile(stackDir, 'auth.json')).toBeNull();
+  });
+
+  it('rejects path traversal and unsafe names', () => {
+    expect(() => assertSafeSecretFilename('../escape')).toThrow();
+    expect(() => assertSafeSecretFilename('a/b')).toThrow();
+    expect(() => assertSafeSecretFilename('..')).toThrow();
+    expect(() => assertSafeSecretFilename('')).toThrow();
+    // valid names
+    expect(() => assertSafeSecretFilename('auth.json')).not.toThrow();
+    expect(() => assertSafeSecretFilename('op_ui_login_password')).not.toThrow();
+    expect(() => assertSafeSecretFilename('discord_bot_token')).not.toThrow();
+  });
+
+  it('readSecretFile returns null for a missing file', () => {
+    expect(readSecretFile(tempStackDir(), 'nope.txt')).toBeNull();
+  });
+});