@desplega.ai/agent-swarm 1.66.0 → 1.67.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.66.0",
+    "version": "1.67.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -1038,7 +1038,7 @@
         }
       },
       "delete": {
-        "summary": "Delete a config entry",
+        "summary": "Delete a config entry by ID (including legacy reserved rows for cleanup)",
         "tags": [
           "Config"
         ],
@@ -1115,7 +1115,7 @@
         }
       },
       "put": {
-        "summary": "Create or update a config entry",
+        "summary": "Create or update a config entry (reserved env-only keys are rejected)",
         "tags": [
           "Config"
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.66.0",
+  "version": "1.67.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -102,9 +102,9 @@
     "@desplega.ai/localtunnel": "^2.2.0",
     "@inkjs/ui": "^2.0.0",
     "@linear/sdk": "^77.0.0",
-    "@mariozechner/pi-agent-core": "^0.57.1",
-    "@mariozechner/pi-ai": "^0.57.1",
-    "@mariozechner/pi-coding-agent": "^0.57.1",
+    "@mariozechner/pi-agent-core": "^0.67.2",
+    "@mariozechner/pi-ai": "^0.67.2",
+    "@mariozechner/pi-coding-agent": "^0.67.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@openai/codex-sdk": "^0.118.0",
     "@openfort/openfort-node": "^0.9.1",

package/src/be/crypto/index.ts

@@ -0,0 +1,12 @@
+export {
+  __resetEncryptionKeyForTests,
+  getEncryptionKey,
+  resolveEncryptionKey,
+} from "./key-bootstrap";
+export {
+  AES_KEY_BYTES,
+  decryptSecret,
+  encryptSecret,
+  IV_BYTES,
+  TAG_BYTES,
+} from "./secrets-cipher";

package/src/be/crypto/key-bootstrap.ts

@@ -0,0 +1,147 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { AES_KEY_BYTES } from "./secrets-cipher";
+
+/**
+ * Encryption key bootstrap.
+ *
+ * Resolution order (first match wins):
+ *   1. `SECRETS_ENCRYPTION_KEY` env var   — base64 string, must decode to 32 bytes
+ *   2. `SECRETS_ENCRYPTION_KEY_FILE` env var — path to file containing base64
+ *   3. `<dirname(dbPath)>/.encryption-key` — on-disk file
+ *   4. Auto-generate 32 random bytes, write to path from step 3 with mode 0600
+ *      only when generation is allowed for the current DB state
+ *
+ * Special cases:
+ *   - `dbPath === ":memory:"`: steps 3-4 are skipped; an explicit env-var key is required.
+ *   - Malformed key at any source: throw immediately (do NOT fall through to
+ *     auto-generation, which would silently clobber a broken-but-present key).
+ *   - Callers can disable auto-generation for existing DBs via `allowGenerate=false`.
+ */
+
+let cachedKey: Buffer | null = null;
+
+const ENV_KEY = "SECRETS_ENCRYPTION_KEY";
+const ENV_KEY_FILE = "SECRETS_ENCRYPTION_KEY_FILE";
+const KEY_FILENAME = ".encryption-key";
+
+function decodeAndValidate(source: string, content: string): Buffer {
+  const trimmed = content.trim();
+  let decoded: Buffer;
+  try {
+    decoded = Buffer.from(trimmed, "base64");
+  } catch (err) {
+    throw new Error(
+      `Invalid encryption key at ${source}: base64 decode failed: ${(err as Error).message}`,
+    );
+  }
+  if (decoded.length !== AES_KEY_BYTES) {
+    throw new Error(
+      `Invalid encryption key at ${source}: expected ${AES_KEY_BYTES} bytes after base64 decode, got ${decoded.length} bytes`,
+    );
+  }
+  return decoded;
+}
+
+type ResolveEncryptionKeyOptions = {
+  allowGenerate?: boolean;
+};
+
+/**
+ * Resolve the encryption key according to the order documented above. Idempotent:
+ * the first successful call caches the key, and subsequent calls return it without
+ * re-reading env vars or disk.
+ */
+export function resolveEncryptionKey(
+  dbPath: string,
+  options: ResolveEncryptionKeyOptions = {},
+): Buffer {
+  if (cachedKey) return cachedKey;
+
+  const allowGenerate = options.allowGenerate ?? true;
+
+  // 1. SECRETS_ENCRYPTION_KEY env var
+  const envKey = process.env[ENV_KEY];
+  if (envKey && envKey.length > 0) {
+    cachedKey = decodeAndValidate(`env:${ENV_KEY}`, envKey);
+    return cachedKey;
+  }
+
+  // 2. SECRETS_ENCRYPTION_KEY_FILE env var
+  const envKeyFile = process.env[ENV_KEY_FILE];
+  if (envKeyFile && envKeyFile.length > 0) {
+    if (!existsSync(envKeyFile)) {
+      throw new Error(
+        `Invalid encryption key at env:${ENV_KEY_FILE} (${envKeyFile}): file does not exist`,
+      );
+    }
+    const content = readFileSync(envKeyFile, "utf8");
+    cachedKey = decodeAndValidate(`env:${ENV_KEY_FILE} (${envKeyFile})`, content);
+    return cachedKey;
+  }
+
+  // In-memory databases must not auto-generate a key in CWD — fail fast.
+  if (dbPath === ":memory:") {
+    throw new Error(
+      `In-memory database requires ${ENV_KEY} or ${ENV_KEY_FILE} to be set explicitly`,
+    );
+  }
+
+  const keyFilePath = path.join(path.dirname(dbPath), KEY_FILENAME);
+
+  // 3. On-disk .encryption-key file
+  if (existsSync(keyFilePath)) {
+    const content = readFileSync(keyFilePath, "utf8");
+    cachedKey = decodeAndValidate(`file:${keyFilePath}`, content);
+    return cachedKey;
+  }
+
+  if (!allowGenerate) {
+    throw new Error(
+      `Refusing to auto-generate ${KEY_FILENAME} for an existing database with encrypted secret rows. Restore ${ENV_KEY}, ${ENV_KEY_FILE}, or ${keyFilePath} before booting.`,
+    );
+  }
+
+  // 4. Auto-generate. Use `wx` flag for TOCTOU safety — fail if file reappeared
+  // between existsSync and write (another process won the race).
+  const generated = randomBytes(AES_KEY_BYTES);
+  const encoded = generated.toString("base64");
+  try {
+    writeFileSync(keyFilePath, encoded, { flag: "wx", mode: 0o600 });
+    console.warn(
+      `[secrets] Generated new encryption key at ${keyFilePath}. BACK THIS FILE UP. Losing it means losing all encrypted secrets.`,
+    );
+    cachedKey = generated;
+    return cachedKey;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "EEXIST") {
+      // Another process won the race — re-read its file.
+      const content = readFileSync(keyFilePath, "utf8");
+      cachedKey = decodeAndValidate(`file:${keyFilePath}`, content);
+      return cachedKey;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Return the cached encryption key. Throws if `resolveEncryptionKey` has not
+ * been called yet (or has been reset via the test hook).
+ */
+export function getEncryptionKey(): Buffer {
+  if (!cachedKey) {
+    throw new Error("Encryption key not resolved yet — call resolveEncryptionKey(dbPath) first");
+  }
+  return cachedKey;
+}
+
+/**
+ * Test-only: clear the module-level cache so the next `resolveEncryptionKey`
+ * call re-reads env vars / disk. Used by integration tests that simulate
+ * rotation, missing-key, or wrong-key scenarios.
+ */
+export function __resetEncryptionKeyForTests(): void {
+  cachedKey = null;
+}

package/src/be/crypto/secrets-cipher.ts

@@ -0,0 +1,90 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+
+/**
+ * AES-256-GCM secrets cipher.
+ *
+ * Encrypted payload layout (before base64):
+ *   [ iv (12 bytes) || ciphertext (variable) || auth tag (16 bytes) ]
+ *
+ * A fresh random IV is generated per `encryptSecret` call, so encrypting the
+ * same plaintext twice produces different ciphertexts. Decryption verifies the
+ * auth tag and throws on any tampering.
+ */
+
+export const AES_KEY_BYTES = 32;
+export const IV_BYTES = 12;
+export const TAG_BYTES = 16;
+
+const ALGORITHM = "aes-256-gcm" as const;
+
+function assertKey(key: Buffer): void {
+  if (!Buffer.isBuffer(key) || key.length !== AES_KEY_BYTES) {
+    const got = Buffer.isBuffer(key) ? `${key.length} bytes` : typeof key;
+    throw new Error(`Invalid encryption key: expected ${AES_KEY_BYTES} bytes, got ${got}`);
+  }
+}
+
+/**
+ * Encrypt a UTF-8 plaintext string with AES-256-GCM.
+ *
+ * @param plaintext - Any UTF-8 string (empty allowed).
+ * @param key - 32-byte key buffer.
+ * @returns base64-encoded `iv || ciphertext || authTag`.
+ */
+export function encryptSecret(plaintext: string, key: Buffer): string {
+  assertKey(key);
+  if (typeof plaintext !== "string") {
+    throw new Error(`encryptSecret: plaintext must be a string, got ${typeof plaintext}`);
+  }
+
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  if (authTag.length !== TAG_BYTES) {
+    // Should never happen with aes-256-gcm, but guard anyway.
+    throw new Error(`encryptSecret: unexpected auth tag length ${authTag.length}`);
+  }
+
+  return Buffer.concat([iv, ciphertext, authTag]).toString("base64");
+}
+
+/**
+ * Decrypt a payload produced by `encryptSecret`. Throws on any tampering
+ * (invalid length, corrupted ciphertext/iv, or bad auth tag).
+ */
+export function decryptSecret(encoded: string, key: Buffer): string {
+  assertKey(key);
+  if (typeof encoded !== "string") {
+    throw new Error(`decryptSecret: encoded payload must be a string, got ${typeof encoded}`);
+  }
+
+  let buf: Buffer;
+  try {
+    buf = Buffer.from(encoded, "base64");
+  } catch (err) {
+    throw new Error(`decryptSecret: invalid base64 payload: ${(err as Error).message}`);
+  }
+
+  if (buf.length < IV_BYTES + TAG_BYTES) {
+    throw new Error(
+      `decryptSecret: payload too short (${buf.length} bytes, need at least ${IV_BYTES + TAG_BYTES})`,
+    );
+  }
+
+  const iv = buf.subarray(0, IV_BYTES);
+  const authTag = buf.subarray(buf.length - TAG_BYTES);
+  const ciphertext = buf.subarray(IV_BYTES, buf.length - TAG_BYTES);
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+
+  try {
+    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return plaintext.toString("utf8");
+  } catch (err) {
+    throw new Error(
+      `decryptSecret: auth tag verification failed or payload corrupted: ${(err as Error).message}`,
+    );
+  }
+}

package/src/be/db.ts

@@ -57,9 +57,11 @@ import type {
   WorkflowVersion,
 } from "../types";
 import { deriveProviderFromKeyType } from "../utils/credentials";
+import { decryptSecret, encryptSecret, getEncryptionKey, resolveEncryptionKey } from "./crypto";
 import { normalizeDate, normalizeDateRequired } from "./date-utils";
 import { runMigrations } from "./migrations/runner";
 import { seedDefaultTemplates } from "./seed";
+import { isReservedConfigKey, reservedKeyError } from "./swarm-config-guard";
 
 let db: Database | null = null;
 let sqliteVecAvailable = false;
@@ -76,11 +78,18 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   // Fast path for tests: restore from pre-built template that already has
   // migrations, seeds, and all post-init work baked in. Only the per-connection
   // PRAGMA and the in-memory resolver function need to be set.
-  const templateBytes = (globalThis as any).__testMigrationTemplate as Uint8Array | undefined;
+  const templateGlobals = globalThis as typeof globalThis & {
+    __testMigrationTemplate?: Uint8Array;
+  };
+  const templateBytes = templateGlobals.__testMigrationTemplate;
   if (templateBytes) {
     db = Database.deserialize(templateBytes);
     db.run("PRAGMA foreign_keys = ON;");
     configureDbResolver(resolvePromptTemplate);
+    // Ensure the encryption key is resolved even when restoring from the test
+    // template. The cache may have been cleared via __resetEncryptionKeyForTests
+    // between test suites; this call is a no-op if the cache is already warm.
+    resolveEncryptionKey(dbPath);
     return db;
   }
 
@@ -234,6 +243,37 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   // Seed default prompt templates from the in-memory code registry
   seedDefaultTemplates();
 
+  const hasExistingEncryptedSecrets =
+    (database
+      .prepare<{ present: number }, []>(
+        "SELECT EXISTS(SELECT 1 FROM swarm_config WHERE isSecret = 1 AND encrypted = 1) as present",
+      )
+      .get()?.present ?? 0) === 1;
+
+  // Track whether user provided the key (for backup decision)
+  const userProvidedKey = !!(
+    process.env.SECRETS_ENCRYPTION_KEY?.length || process.env.SECRETS_ENCRYPTION_KEY_FILE?.length
+  );
+
+  // Resolve the secrets encryption key after migrations so we can tell whether
+  // this DB already contains encrypted secret rows (must reuse an explicit or
+  // on-disk key) or is still plaintext-only (safe to generate a new key before
+  // auto-migrating legacy plaintext rows).
+  resolveEncryptionKey(dbPath, { allowGenerate: !hasExistingEncryptedSecrets });
+
+  // Auto-encrypt any legacy plaintext secrets that predate the encryption
+  // feature. Runs after all compatibility guards; failures are fatal because
+  // continuing would leave secrets at rest in plaintext — the opposite of the
+  // guarantee this feature provides.
+  try {
+    autoEncryptLegacyPlaintextSecrets(database, dbPath, { createBackup: !userProvidedKey });
+  } catch (err) {
+    console.error(
+      `[secrets] FATAL: failed to auto-encrypt legacy secrets: ${(err as Error).message}`,
+    );
+    throw err;
+  }
+
   return db;
 }
 
@@ -4315,23 +4355,128 @@ type SwarmConfigRow = {
   description: string | null;
   createdAt: string;
   lastUpdatedAt: string;
+  encrypted: number; // SQLite boolean: 0 = plaintext, 1 = AES-256-GCM ciphertext
 };
 
+type SwarmConfigLookupRow = {
+  id: string;
+  scope: string;
+  scopeId: string | null;
+  key: string;
+  isSecret: number;
+  encrypted: number;
+};
+
+const RESERVED_CONFIG_PLACEHOLDER = "[reserved key stored in swarm_config; delete this row]";
+
 function rowToSwarmConfig(row: SwarmConfigRow): SwarmConfig {
+  const isEncrypted = row.encrypted === 1;
+  if (isReservedConfigKey(row.key)) {
+    return {
+      id: row.id,
+      scope: row.scope as "global" | "agent" | "repo",
+      scopeId: row.scopeId ?? null,
+      key: row.key,
+      value: RESERVED_CONFIG_PLACEHOLDER,
+      isSecret: row.isSecret === 1,
+      envPath: row.envPath ?? null,
+      description: row.description ?? null,
+      createdAt: row.createdAt,
+      lastUpdatedAt: row.lastUpdatedAt,
+      encrypted: isEncrypted,
+    };
+  }
+
+  let value = row.value;
+  if (isEncrypted) {
+    try {
+      value = decryptSecret(row.value, getEncryptionKey());
+    } catch (err) {
+      throw new Error(
+        `Failed to decrypt config '${row.key}' (id=${row.id}): check SECRETS_ENCRYPTION_KEY matches the key used at encryption time`,
+        { cause: err },
+      );
+    }
+  }
   return {
     id: row.id,
     scope: row.scope as "global" | "agent" | "repo",
     scopeId: row.scopeId ?? null,
     key: row.key,
-    value: row.value,
+    value,
     isSecret: row.isSecret === 1,
     envPath: row.envPath ?? null,
     description: row.description ?? null,
     createdAt: row.createdAt,
     lastUpdatedAt: row.lastUpdatedAt,
+    encrypted: isEncrypted,
   };
 }
 
+/**
+ * Scan swarm_config for any rows flagged `isSecret = 1` whose `encrypted`
+ * column is still 0 (plaintext), encrypt them in a single transaction, and
+ * flip the flag. Called exactly once during `initDb` on the main path — never
+ * on the test template fast-path.
+ *
+ * Exported for tests so they can simulate a pre-existing legacy row without
+ * needing to replay a full boot.
+ */
+export function autoEncryptLegacyPlaintextSecrets(
+  database: Database,
+  dbPath: string,
+  options: { createBackup?: boolean } = {},
+): void {
+  const rows = database
+    .prepare<{ id: string; key: string; value: string }, []>(
+      "SELECT id, key, value FROM swarm_config WHERE isSecret = 1 AND encrypted = 0",
+    )
+    .all();
+  if (rows.length === 0) return;
+
+  const key = getEncryptionKey();
+
+  // Create plaintext backup if key was auto-generated (not user-provided)
+  if (options.createBackup) {
+    const { writeFileSync } = require("node:fs");
+    const backupPath = `${dbPath}.backup.secrets-${new Date().toISOString().split("T")[0]}.env`;
+    const backupLines = [
+      "# PLAINTEXT SECRET BACKUP - CREATED DURING AUTO-ENCRYPTION MIGRATION",
+      "# This file was created because you did not provide SECRETS_ENCRYPTION_KEY",
+      "# DELETE THIS FILE after verifying your encryption key is safely backed up",
+      "#",
+      "# Encryption key location:",
+      "#   - Check: <data-dir>/.encryption-key",
+      "#   - Or set: SECRETS_ENCRYPTION_KEY=<base64-key>",
+      "",
+      ...rows.map((r) => `${r.key}=${r.value}`),
+      "",
+    ].join("\n");
+
+    try {
+      writeFileSync(backupPath, backupLines, { mode: 0o600 });
+      console.warn(`[secrets] Created plaintext backup: ${backupPath}`);
+      console.warn(`[secrets] DELETE THIS FILE after verifying your encryption key is backed up!`);
+    } catch (err) {
+      console.error(`[secrets] Failed to create backup file: ${(err as Error).message}`);
+      // Continue with encryption even if backup fails - the secrets are still in DB
+    }
+  }
+
+  console.log(`[secrets] Encrypting ${rows.length} legacy plaintext secret(s)...`);
+
+  const txn = database.transaction((items: { id: string; value: string }[]) => {
+    const stmt = database.prepare<unknown, [string, string]>(
+      "UPDATE swarm_config SET value = ?, encrypted = 1 WHERE id = ?",
+    );
+    for (const r of items) {
+      stmt.run(encryptSecret(r.value, key), r.id);
+    }
+  });
+  txn(rows);
+  console.log(`[secrets] Auto-migrated ${rows.length} secret(s) to encrypted storage.`);
+}
+
 /**
  * Mask secret values in config entries for API responses.
  */
@@ -4412,6 +4557,23 @@ export function getSwarmConfigs(filters?: {
     .map(rowToSwarmConfig);
 }
 
+/**
+ * Global configs that are allowed to flow into process.env.
+ * Reserved env-only keys are filtered in SQL before decryption so a corrupted
+ * legacy reserved row cannot block startup or reload.
+ */
+export function getInjectableGlobalConfigs(): SwarmConfig[] {
+  return getDb()
+    .prepare<SwarmConfigRow, []>(
+      `SELECT * FROM swarm_config
+       WHERE scope = 'global'
+         AND UPPER(key) NOT IN ('API_KEY', 'SECRETS_ENCRYPTION_KEY')
+       ORDER BY key ASC`,
+    )
+    .all()
+    .map(rowToSwarmConfig);
+}
+
 /**
  * Get a single config entry by ID.
  */
@@ -4422,6 +4584,34 @@ export function getSwarmConfigById(id: string): SwarmConfig | null {
   return row ? rowToSwarmConfig(row) : null;
 }
 
+/**
+ * Get config metadata by ID without decrypting the value. Used by cleanup
+ * paths so unreadable secret rows can still be inspected and removed.
+ */
+export function getSwarmConfigLookupById(id: string): {
+  id: string;
+  scope: "global" | "agent" | "repo";
+  scopeId: string | null;
+  key: string;
+  isSecret: boolean;
+  encrypted: boolean;
+} | null {
+  const row = getDb()
+    .prepare<SwarmConfigLookupRow, [string]>(
+      "SELECT id, scope, scopeId, key, isSecret, encrypted FROM swarm_config WHERE id = ?",
+    )
+    .get(id);
+  if (!row) return null;
+  return {
+    id: row.id,
+    scope: row.scope as "global" | "agent" | "repo",
+    scopeId: row.scopeId ?? null,
+    key: row.key,
+    isSecret: row.isSecret === 1,
+    encrypted: row.encrypted === 1,
+  };
+}
+
 /**
  * Upsert a config entry. Inserts or updates by (scope, scopeId, key) unique constraint.
  */
@@ -4434,12 +4624,21 @@ export function upsertSwarmConfig(data: {
   envPath?: string | null;
   description?: string | null;
 }): SwarmConfig {
+  if (isReservedConfigKey(data.key)) {
+    throw reservedKeyError(data.key);
+  }
+
   const now = new Date().toISOString();
   const scopeId = data.scope === "global" ? null : (data.scopeId ?? null);
   const isSecret = data.isSecret ? 1 : 0;
   const envPath = data.envPath ?? null;
   const description = data.description ?? null;
 
+  // Encrypt secret values at rest. Non-secret values are stored verbatim so
+  // they remain queryable and diffable. rowToSwarmConfig reverses this on read.
+  const storedValue = data.isSecret ? encryptSecret(data.value, getEncryptionKey()) : data.value;
+  const encryptedFlag: number = data.isSecret ? 1 : 0;
+
   // Manual check for existing entry because SQLite's UNIQUE constraint
   // treats NULL != NULL, so ON CONFLICT never fires when scopeId is NULL (global scope).
   const existing =
@@ -4459,11 +4658,14 @@ export function upsertSwarmConfig(data: {
 
   if (existing) {
     row = getDb()
-      .prepare<SwarmConfigRow, [string, number, string | null, string | null, string, string]>(
-        `UPDATE swarm_config SET value = ?, isSecret = ?, envPath = ?, description = ?, lastUpdatedAt = ?
+      .prepare<
+        SwarmConfigRow,
+        [string, number, string | null, string | null, number, string, string]
+      >(
+        `UPDATE swarm_config SET value = ?, isSecret = ?, envPath = ?, description = ?, encrypted = ?, lastUpdatedAt = ?
          WHERE id = ? RETURNING *`,
       )
-      .get(data.value, isSecret, envPath, description, now, existing.id);
+      .get(storedValue, isSecret, envPath, description, encryptedFlag, now, existing.id);
   } else {
     const id = crypto.randomUUID();
     row = getDb()
@@ -4480,16 +4682,31 @@ export function upsertSwarmConfig(data: {
           string | null,
           string,
           string,
+          number,
         ]
       >(
-        `INSERT INTO swarm_config (id, scope, scopeId, key, value, isSecret, envPath, description, createdAt, lastUpdatedAt)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+        `INSERT INTO swarm_config (id, scope, scopeId, key, value, isSecret, envPath, description, createdAt, lastUpdatedAt, encrypted)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
       )
-      .get(id, data.scope, scopeId, data.key, data.value, isSecret, envPath, description, now, now);
+      .get(
+        id,
+        data.scope,
+        scopeId,
+        data.key,
+        storedValue,
+        isSecret,
+        envPath,
+        description,
+        now,
+        now,
+        encryptedFlag,
+      );
   }
 
   if (!row) throw new Error("Failed to upsert swarm config");
 
+  // rowToSwarmConfig transparently decrypts `storedValue` back to plaintext so
+  // the returned object (and downstream writeEnvFile) sees the original value.
   const config = rowToSwarmConfig(row);
 
   // Write to envPath if set
@@ -4506,6 +4723,9 @@ export function upsertSwarmConfig(data: {
 
 /**
  * Delete a config entry by ID.
+ *
+ * Intentionally does not decrypt or block reserved keys. Legacy rows that
+ * predate hardening must remain removable through remediation paths.
  */
 export function deleteSwarmConfig(id: string): boolean {
   const result = getDb().run("DELETE FROM swarm_config WHERE id = ?", [id]);

package/src/be/migrations/038_encrypted_secrets.sql

@@ -0,0 +1,10 @@
+-- Add encryption flag to swarm_config
+-- Values with encrypted=1 are stored as base64(iv || ciphertext || authTag) AES-256-GCM.
+-- Legacy plaintext rows default to encrypted=0 and will be auto-migrated on next boot
+-- by initDb() before normal config reads occur.
+
+ALTER TABLE swarm_config ADD COLUMN encrypted INTEGER NOT NULL DEFAULT 0;
+
+-- The column defaults to 0 so pre-existing rows altered by this migration stay
+-- marked as plaintext until initDb() auto-encrypts legacy isSecret=1 rows.
+-- From then on, the write path will set encrypted=1 explicitly for isSecret=1 rows.

package/src/be/swarm-config-guard.ts

@@ -0,0 +1,25 @@
+/**
+ * Guards against storing reserved keys in the swarm_config table.
+ *
+ * `API_KEY` and `SECRETS_ENCRYPTION_KEY` must live only in the process
+ * environment (or a .env file) — persisting them in swarm_config would
+ * create a chicken-and-egg problem:
+ *   - `API_KEY` controls access to the HTTP API that reads swarm_config.
+ *   - `SECRETS_ENCRYPTION_KEY` is required to decrypt secrets stored in
+ *     swarm_config, so it cannot itself be stored encrypted there.
+ *
+ * Matching is case-insensitive so `api_key`, `Api_Key`, etc. are all
+ * rejected at every write path (DB helpers, HTTP routes, MCP tools).
+ */
+const RESERVED_KEYS = new Set(["API_KEY", "SECRETS_ENCRYPTION_KEY"]);
+
+export function isReservedConfigKey(key: string): boolean {
+  return RESERVED_KEYS.has(key.toUpperCase());
+}
+
+export function reservedKeyError(key: string): Error {
+  return new Error(
+    `Key '${key}' is reserved and cannot be stored in swarm_config. ` +
+      `Set it as an environment variable instead.`,
+  );
+}