feat(kiloclaw): add generic patchSecrets endpoint with catalog-driven validation (#947)

<!-- PR title format: type(scope): description — e.g., feat(auth): add
SSO login -->
<!-- Keep the title under 72 characters, use imperative mood, no
trailing period. -->

## Summary

feat(kiloclaw): add generic patchSecrets endpoint with catalog-driven
validation

<!-- What changed and why? Keep this brief and outcome-focused. -->
<!-- Include any architectural changes and enough context for a reviewer
unfamiliar with this code area. -->

Adds patchSecrets tRPC mutation and PATCH /api/platform/secrets worker
endpoint
alongside existing patchChannels. Uses secret catalog for key
validation,
pattern matching, maxLength enforcement, and allFieldsRequired
enforcement.
                                                            
Makes updateChannels delegate to updateSecrets internally so both
storage fields
(channels + encryptedSecrets) stay in sync regardless of which endpoint
is
  called. Eliminates interleave drift risk.

  Key design decisions:
- Key remapping at storage boundary: encryptedSecrets stores env var
names
(e.g., TELEGRAM_BOT_TOKEN) so the existing
buildEnvVars/mergeEnvVarsWithSecrets
pipeline works unchanged. A reverse map (ENV_VAR_TO_FIELD_KEY) converts
back to
  field keys when reading into the working set.
- allFieldsRequired enforced at DO level: The DO validates post-merge
state
  (existing secrets + patch), not just the incoming patch. This allows
single-field rotations (e.g., rotating slackBotToken when slackAppToken
is
  already stored) while still rejecting invalid partial clears.
- secretCount excludes channel env vars: Channel tokens are dual-written
into
encryptedSecrets but excluded from secretCount (via CHANNEL_ENV_VARS
filter)
  since they're already counted by channelCount. Applied in getStatus(),
  getDebugState(), and /api/kiloclaw/config.
- Validation errors return 400: DO validation errors carry status: 400
and an
Invalid secret patch: prefix so the route handler returns the actual
message
  instead of a generic 500.


## Verification
- Catalog package tests pass (37 tests) — includes new allFieldsRequired
contract, maxLength contract, and unknown key rejection tests
- DO updateSecrets tests pass (8 tests) — set, remove, merge, legacy
migration, Slack dual-token set/clear, channel-only filtering
- DO updateChannels tests pass (8 tests) — all 6 existing tests pass
through delegation path, plus 2 new interleave consistency tests
- updateChannels delegation produces identical boolean return shape as
original implementation
- Worker builds without errors (wrangler types + wrangler deploy
--dry-run)
- Integration: provision instance via patchChannels, update via
patchSecrets, verify both endpoints see consistent state

## Visual Changes
N/A

## Reviewer Notes

- Dual-write strategy: updateSecrets writes to both channels (legacy,
field-keyed) and encryptedSecrets (new, env-var-keyed). Channel-category
keys go to both; future non-channel secrets (tools, providers) only go
to encryptedSecrets.
- updateChannels delegation: The old method now delegates to
updateSecrets. This is the fix for the interleave drift edge case;
there's now a single write path. Existing updateChannels callers see no
behavior change.
- tRPC defers allFieldsRequired to DO: The tRPC layer validates key
membership, patterns, and maxLength, but does not check
allFieldsRequired — only the DO can see existing state to validate
post-merge correctness.
- configured response filtered: The configured array returned by
updateSecrets is filtered to ALL_SECRET_FIELD_KEYS only, preventing
non-catalog env var names from leaking into the response.
- Rate limiting: Not yet applied to patchSecrets. Should match whatever
strategy patchChannels uses. Can be added as a follow-up.
- tRPC-level integration tests: Validation logic is tested via catalog
contract tests and DO-level tests rather than full tRPC caller tests,
since the router test infrastructure requires real DB + user setup +
worker client mocking.
- Depends on: PR #857 (@kilocode/kiloclaw-secret-catalog package)

Author: St0rmz1

kiloclaw/packages/secret-catalog/src/__tests__/catalog.test.ts

@@ -4,6 +4,7 @@ import {
   SECRET_CATALOG_MAP,
   ALL_SECRET_FIELD_KEYS,
   FIELD_KEY_TO_ENV_VAR,
+  ENV_VAR_TO_FIELD_KEY,
   FIELD_KEY_TO_ENTRY,
   getEntriesByCategory,
 } from '../catalog.js';
@@ -119,6 +120,20 @@ describe('Secret Catalog', () => {
       expect(FIELD_KEY_TO_ENV_VAR.get('slackBotToken')).toBe('SLACK_BOT_TOKEN');
       expect(FIELD_KEY_TO_ENV_VAR.get('slackAppToken')).toBe('SLACK_APP_TOKEN');
     });
+
+    it('ENV_VAR_TO_FIELD_KEY is the exact reverse of FIELD_KEY_TO_ENV_VAR', () => {
+      expect(ENV_VAR_TO_FIELD_KEY.size).toBe(FIELD_KEY_TO_ENV_VAR.size);
+      for (const [fieldKey, envVar] of FIELD_KEY_TO_ENV_VAR) {
+        expect(ENV_VAR_TO_FIELD_KEY.get(envVar)).toBe(fieldKey);
+      }
+    });
+
+    it('ENV_VAR_TO_FIELD_KEY has correct reverse mappings', () => {
+      expect(ENV_VAR_TO_FIELD_KEY.get('TELEGRAM_BOT_TOKEN')).toBe('telegramBotToken');
+      expect(ENV_VAR_TO_FIELD_KEY.get('DISCORD_BOT_TOKEN')).toBe('discordBotToken');
+      expect(ENV_VAR_TO_FIELD_KEY.get('SLACK_BOT_TOKEN')).toBe('slackBotToken');
+      expect(ENV_VAR_TO_FIELD_KEY.get('SLACK_APP_TOKEN')).toBe('slackAppToken');
+    });
   });
 
   describe('Lookup helpers', () => {
@@ -264,4 +279,57 @@ describe('Secret Catalog', () => {
       );
     });
   });
+
+  describe('allFieldsRequired contract', () => {
+    it('slack entry has allFieldsRequired set', () => {
+      const slack = SECRET_CATALOG_MAP.get('slack');
+      expect(slack?.allFieldsRequired).toBe(true);
+    });
+
+    it('slack entry has exactly 2 fields', () => {
+      const slack = SECRET_CATALOG_MAP.get('slack');
+      expect(slack?.fields.length).toBe(2);
+      expect(slack?.fields.map(f => f.key)).toEqual(['slackBotToken', 'slackAppToken']);
+    });
+
+    it('telegram and discord do not have allFieldsRequired', () => {
+      expect(SECRET_CATALOG_MAP.get('telegram')?.allFieldsRequired).toBeFalsy();
+      expect(SECRET_CATALOG_MAP.get('discord')?.allFieldsRequired).toBeFalsy();
+    });
+
+    it('ALL_SECRET_FIELD_KEYS rejects unknown keys', () => {
+      expect(ALL_SECRET_FIELD_KEYS.has('telegramBotToken')).toBe(true);
+      expect(ALL_SECRET_FIELD_KEYS.has('unknownKey')).toBe(false);
+      expect(ALL_SECRET_FIELD_KEYS.has('')).toBe(false);
+    });
+
+    it('FIELD_KEY_TO_ENTRY maps both slack fields to the same entry', () => {
+      const botEntry = FIELD_KEY_TO_ENTRY.get('slackBotToken');
+      const appEntry = FIELD_KEY_TO_ENTRY.get('slackAppToken');
+      expect(botEntry).toBeDefined();
+      expect(botEntry).toBe(appEntry);
+      expect(botEntry?.allFieldsRequired).toBe(true);
+    });
+  });
+
+  describe('maxLength contract', () => {
+    it('all maxLength values are within the global 500 ceiling', () => {
+      for (const entry of SECRET_CATALOG) {
+        for (const field of entry.fields) {
+          expect(field.maxLength).toBeLessThanOrEqual(500);
+        }
+      }
+    });
+
+    it('field-specific maxLength values are set correctly', () => {
+      const telegram = FIELD_KEY_TO_ENTRY.get('telegramBotToken');
+      const discord = FIELD_KEY_TO_ENTRY.get('discordBotToken');
+      const slackBot = FIELD_KEY_TO_ENTRY.get('slackBotToken');
+
+      expect(telegram?.fields[0].maxLength).toBe(100);
+      expect(discord?.fields[0].maxLength).toBe(200);
+      expect(slackBot?.fields.find(f => f.key === 'slackBotToken')?.maxLength).toBe(300);
+      expect(slackBot?.fields.find(f => f.key === 'slackAppToken')?.maxLength).toBe(300);
+    });
+  });
 });

kiloclaw/packages/secret-catalog/src/catalog.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import type { SecretCatalogEntry, SecretCategory } from './types.js';
-import { SecretCatalogEntrySchema } from './types.js';
+import type { SecretCatalogEntry, SecretCategory } from './types';
+import { SecretCatalogEntrySchema } from './types';
 
 /**
  * Secret Catalog — declarative registry of all secret types.
@@ -104,6 +104,9 @@ export const SECRET_CATALOG_MAP: ReadonlyMap<string, SecretCatalogEntry> = new M
   SECRET_CATALOG.map(entry => [entry.id, entry])
 );
 
+/** Union type of all secret field keys in the catalog */
+export type SecretFieldKey = (typeof SECRET_CATALOG_RAW)[number]['fields'][number]['key'];
+
 /** Set of all field keys across all entries */
 export const ALL_SECRET_FIELD_KEYS: ReadonlySet<string> = new Set(
   SECRET_CATALOG.flatMap(entry => entry.fields.map(field => field.key))
@@ -114,6 +117,11 @@ export const FIELD_KEY_TO_ENV_VAR: ReadonlyMap<string, string> = new Map(
   SECRET_CATALOG.flatMap(entry => entry.fields.map(field => [field.key, field.envVar]))
 );
 
+/** Reverse map: env var name → field key (for reading encryptedSecrets back to working set) */
+export const ENV_VAR_TO_FIELD_KEY: ReadonlyMap<string, string> = new Map(
+  SECRET_CATALOG.flatMap(entry => entry.fields.map(field => [field.envVar, field.key]))
+);
+
 /** Map of field key → owning entry (used for allFieldsRequired checks) */
 export const FIELD_KEY_TO_ENTRY: ReadonlyMap<string, SecretCatalogEntry> = new Map(
   SECRET_CATALOG.flatMap(entry => entry.fields.map(field => [field.key, entry]))

kiloclaw/packages/secret-catalog/src/index.ts

@@ -5,7 +5,7 @@ export {
   InjectionMethodSchema,
   SecretFieldDefinitionSchema,
   SecretCatalogEntrySchema,
-} from './types.js';
+} from './types';
 
 // Types
 export type {
@@ -14,20 +14,23 @@ export type {
   InjectionMethod,
   SecretFieldDefinition,
   SecretCatalogEntry,
-} from './types.js';
+} from './types';
 
-export { DEFAULT_INJECTION_METHOD, getInjectionMethod } from './types.js';
+export { DEFAULT_INJECTION_METHOD, getInjectionMethod } from './types';
 
 // Catalog and lookup helpers
 export {
   SECRET_CATALOG,
   SECRET_CATALOG_MAP,
   ALL_SECRET_FIELD_KEYS,
   FIELD_KEY_TO_ENV_VAR,
+  ENV_VAR_TO_FIELD_KEY,
   FIELD_KEY_TO_ENTRY,
   ALL_SECRET_ENV_VARS,
   getEntriesByCategory,
-} from './catalog.js';
+} from './catalog';
+
+export type { SecretFieldKey } from './catalog';
 
 // Validation
-export { validateFieldValue } from './validation.js';
+export { validateFieldValue } from './validation';

kiloclaw/src/durable-objects/kiloclaw-instance.test.ts

@@ -1412,6 +1412,230 @@ describe('updateChannels', () => {
     expect(result.telegram).toBe(true);
     expect(result.discord).toBe(true);
   });
+
+  it('updateChannels dual-writes to encryptedSecrets (no interleave drift)', async () => {
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage);
+
+    // Write via legacy path
+    await instance.updateChannels({ telegramBotToken: fakeEnvelope });
+
+    // channels uses field keys, encryptedSecrets uses env var names
+    const channels = storage._store.get('channels') as Record<string, unknown>;
+    const secrets = storage._store.get('encryptedSecrets') as Record<string, unknown>;
+    expect(channels.telegramBotToken).toEqual(fakeEnvelope);
+    expect(secrets.TELEGRAM_BOT_TOKEN).toEqual(fakeEnvelope);
+  });
+
+  it('interleaving updateChannels and updateSecrets keeps storage in sync', async () => {
+    const discordEnvelope = { ...fakeEnvelope, encryptedData: 'discord-data' };
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage);
+
+    // Step 1: set telegram via updateSecrets (new path)
+    await instance.updateSecrets({ telegramBotToken: fakeEnvelope });
+
+    // Step 2: set discord via updateChannels (legacy path, delegates to updateSecrets)
+    const result = await instance.updateChannels({ discordBotToken: discordEnvelope });
+
+    // Both should be present via legacy response
+    expect(result.telegram).toBe(true);
+    expect(result.discord).toBe(true);
+
+    // channels uses field keys, encryptedSecrets uses env var names
+    const channels = storage._store.get('channels') as Record<string, unknown>;
+    const secrets = storage._store.get('encryptedSecrets') as Record<string, unknown>;
+    expect(channels.telegramBotToken).toEqual(fakeEnvelope);
+    expect(channels.discordBotToken).toEqual(discordEnvelope);
+    expect(secrets.TELEGRAM_BOT_TOKEN).toEqual(fakeEnvelope);
+    expect(secrets.DISCORD_BOT_TOKEN).toEqual(discordEnvelope);
+  });
+});
+
+// ============================================================================
+// updateSecrets
+// ============================================================================
+
+describe('updateSecrets', () => {
+  const fakeEnvelope = {
+    encryptedData: 'data',
+    encryptedDEK: 'dek',
+    algorithm: 'rsa-aes-256-gcm' as const,
+    version: 1 as const,
+  };
+
+  it('stores env var names in encryptedSecrets but field keys in channels', async () => {
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage);
+
+    const result = await instance.updateSecrets({ telegramBotToken: fakeEnvelope });
+
+    expect(result.configured).toContain('telegramBotToken');
+    // channels uses field keys (for decryptChannelTokens backward compat)
+    const channels = storage._store.get('channels') as Record<string, unknown>;
+    expect(channels.telegramBotToken).toEqual(fakeEnvelope);
+    // encryptedSecrets uses env var names (for buildEnvVars/mergeEnvVarsWithSecrets)
+    const secrets = storage._store.get('encryptedSecrets') as Record<string, unknown>;
+    expect(secrets.TELEGRAM_BOT_TOKEN).toEqual(fakeEnvelope);
+    expect(secrets.telegramBotToken).toBeUndefined();
+  });
+
+  it('removes a secret when null is passed', async () => {
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage, {
+      channels: { telegramBotToken: fakeEnvelope },
+      encryptedSecrets: { TELEGRAM_BOT_TOKEN: fakeEnvelope },
+    });
+
+    const result = await instance.updateSecrets({ telegramBotToken: null });
+
+    expect(result.configured).not.toContain('telegramBotToken');
+    expect(storage._store.get('channels')).toBeNull();
+    expect(storage._store.get('encryptedSecrets')).toBeNull();
+  });
+
+  it('merges with existing secrets — setting telegram preserves discord', async () => {
+    const discordEnvelope = { ...fakeEnvelope, encryptedData: 'discord-data' };
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage, {
+      channels: { discordBotToken: discordEnvelope },
+      encryptedSecrets: { DISCORD_BOT_TOKEN: discordEnvelope },
+    });
+
+    const result = await instance.updateSecrets({ telegramBotToken: fakeEnvelope });
+
+    expect(result.configured).toContain('telegramBotToken');
+    expect(result.configured).toContain('discordBotToken');
+    const channels = storage._store.get('channels') as Record<string, unknown>;
+    expect(channels.telegramBotToken).toEqual(fakeEnvelope);
+    expect(channels.discordBotToken).toEqual(discordEnvelope);
+    const secrets = storage._store.get('encryptedSecrets') as Record<string, unknown>;
+    expect(secrets.TELEGRAM_BOT_TOKEN).toEqual(fakeEnvelope);
+    expect(secrets.DISCORD_BOT_TOKEN).toEqual(discordEnvelope);
+  });
+
+  it('reads from legacy channels field when encryptedSecrets is empty', async () => {
+    const { instance, storage } = createInstance();
+    // Simulate legacy state: only channels field, no encryptedSecrets
+    await seedProvisioned(storage, {
+      channels: { telegramBotToken: fakeEnvelope },
+    });
+
+    const discordEnvelope = { ...fakeEnvelope, encryptedData: 'discord-data' };
+    const result = await instance.updateSecrets({ discordBotToken: discordEnvelope });
+
+    // Should see both: legacy telegram + new discord
+    expect(result.configured).toContain('telegramBotToken');
+    expect(result.configured).toContain('discordBotToken');
+  });
+
+  it('removing all secrets sets both storage fields to null', async () => {
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage, {
+      channels: { telegramBotToken: fakeEnvelope },
+      encryptedSecrets: { TELEGRAM_BOT_TOKEN: fakeEnvelope },
+    });
+
+    const result = await instance.updateSecrets({ telegramBotToken: null });
+
+    expect(result.configured).toEqual([]);
+    expect(storage._store.get('channels')).toBeNull();
+    expect(storage._store.get('encryptedSecrets')).toBeNull();
+  });
+
+  it('sets both slack tokens and dual-writes to channels', async () => {
+    const slackBotEnvelope = { ...fakeEnvelope, encryptedData: 'slack-bot' };
+    const slackAppEnvelope = { ...fakeEnvelope, encryptedData: 'slack-app' };
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage);
+
+    const result = await instance.updateSecrets({
+      slackBotToken: slackBotEnvelope,
+      slackAppToken: slackAppEnvelope,
+    });
+
+    expect(result.configured).toContain('slackBotToken');
+    expect(result.configured).toContain('slackAppToken');
+    const channels = storage._store.get('channels') as Record<string, unknown>;
+    expect(channels.slackBotToken).toEqual(slackBotEnvelope);
+    expect(channels.slackAppToken).toEqual(slackAppEnvelope);
+    const secrets = storage._store.get('encryptedSecrets') as Record<string, unknown>;
+    expect(secrets.SLACK_BOT_TOKEN).toEqual(slackBotEnvelope);
+    expect(secrets.SLACK_APP_TOKEN).toEqual(slackAppEnvelope);
+  });
+
+  it('clears both slack tokens simultaneously', async () => {
+    const slackBotEnvelope = { ...fakeEnvelope, encryptedData: 'slack-bot' };
+    const slackAppEnvelope = { ...fakeEnvelope, encryptedData: 'slack-app' };
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage, {
+      channels: { slackBotToken: slackBotEnvelope, slackAppToken: slackAppEnvelope },
+      encryptedSecrets: { SLACK_BOT_TOKEN: slackBotEnvelope, SLACK_APP_TOKEN: slackAppEnvelope },
+    });
+
+    const result = await instance.updateSecrets({
+      slackBotToken: null,
+      slackAppToken: null,
+    });
+
+    expect(result.configured).not.toContain('slackBotToken');
+    expect(result.configured).not.toContain('slackAppToken');
+    expect(storage._store.get('channels')).toBeNull();
+    expect(storage._store.get('encryptedSecrets')).toBeNull();
+  });
+
+  it('second updateSecrets call does not accumulate phantom entries', async () => {
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage);
+
+    // First call: set telegram
+    await instance.updateSecrets({ telegramBotToken: fakeEnvelope });
+
+    // Second call: set discord — telegram should persist, no phantom keys
+    const discordEnvelope = { ...fakeEnvelope, encryptedData: 'discord-data' };
+    const result = await instance.updateSecrets({ discordBotToken: discordEnvelope });
+
+    expect(result.configured).toEqual(
+      expect.arrayContaining(['telegramBotToken', 'discordBotToken'])
+    );
+    expect(result.configured).toHaveLength(2);
+
+    // encryptedSecrets should have exactly 2 env var keys, no field key duplicates
+    const secrets = storage._store.get('encryptedSecrets') as Record<string, unknown>;
+    const secretKeys = Object.keys(secrets).sort();
+    expect(secretKeys).toEqual(['DISCORD_BOT_TOKEN', 'TELEGRAM_BOT_TOKEN']);
+
+    // channels should have exactly 2 field keys
+    const channels = storage._store.get('channels') as Record<string, unknown>;
+    const channelKeys = Object.keys(channels).sort();
+    expect(channelKeys).toEqual(['discordBotToken', 'telegramBotToken']);
+  });
+
+  it('configured return uses field keys not env var names', async () => {
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage);
+
+    const result = await instance.updateSecrets({ telegramBotToken: fakeEnvelope });
+
+    // Should return field keys, not env var names
+    expect(result.configured).toContain('telegramBotToken');
+    expect(result.configured).not.toContain('TELEGRAM_BOT_TOKEN');
+  });
+
+  it('rejects partial clear of allFieldsRequired entry', async () => {
+    const slackBotEnvelope = { ...fakeEnvelope, encryptedData: 'slack-bot' };
+    const slackAppEnvelope = { ...fakeEnvelope, encryptedData: 'slack-app' };
+    const { instance, storage } = createInstance();
+    await seedProvisioned(storage, {
+      channels: { slackBotToken: slackBotEnvelope, slackAppToken: slackAppEnvelope },
+      encryptedSecrets: { SLACK_BOT_TOKEN: slackBotEnvelope, SLACK_APP_TOKEN: slackAppEnvelope },
+    });
+
+    // Removing only one Slack token should fail — allFieldsRequired
+    await expect(instance.updateSecrets({ slackBotToken: null })).rejects.toThrow(
+      'Invalid secret patch: Slack requires all fields to be set together'
+    );
+  });
 });
 
 // ============================================================================