fix(kiloclaw): preserve manual Composio provenance until cleanup

Author: pandemicsyn

.specs/kiloclaw-composio.md

@@ -55,15 +55,16 @@ Kilo previously shipped a managed Composio onboarding experiment that created Ki
 15. Retired managed Composio identities MUST NOT be reused for new instances or configuration updates.
 16. After managed creation paths are disabled, the system MUST verify whether an active instance associated with retired managed identity state retains managed Composio credentials, including a possible partial-write case where runtime injection succeeded before a tracking marker was persisted.
 17. Any confirmed managed credential material in a live instance MUST be cleared before obsolete stored managed identity state is deleted. Verification and clearing MUST NOT remove manually configured Composio credentials.
-18. If no live managed runtime credential remains, obsolete managed identity rows, encrypted credential residue, connected-account identifiers, and destroyed-instance tracking markers MAY be removed by dropping the retired managed-state schema.
-19. Obsolete managed-state database structures MUST NOT be dropped until managed creation is disabled and live runtime residue has been ruled out or cleared.
+18. Until obsolete managed-state schema is dropped, an instance that receives user-provided Composio credentials through provision or Settings MUST be recorded as manually configured, and an instance that clears both Composio fields MUST clear that provenance marker. This marker retention is cleanup safety metadata only and MUST NOT restore managed onboarding behavior.
+19. If no live managed runtime credential remains, obsolete managed identity rows, encrypted credential residue, connected-account identifiers, and destroyed-instance tracking markers MAY be removed by dropping the retired managed-state schema.
+20. Obsolete managed-state database structures MUST NOT be dropped until managed creation is disabled and live runtime residue has been ruled out or cleared.
 
 ### Credential Boundary and Data Protection
 
-20. Kilo central or retired managed Composio credentials MUST NOT be injected into a user or organization OpenClaw instance.
-21. Logs, analytics, audit records, Sentry events, command output, and user-facing errors MUST NOT include raw Composio credentials, OAuth tokens, Connect Links containing secret material, or decrypted stored identity data.
-22. User-provided Composio secrets MUST continue to follow the normal KiloClaw secret encryption, transport, and deletion rules.
-23. Retired managed rows containing encrypted credentials or user-linked provider identifiers MUST be deleted after the required live-runtime verification or otherwise scrubbed in accordance with account-deletion requirements.
+21. Kilo central or retired managed Composio credentials MUST NOT be injected into a user or organization OpenClaw instance.
+22. Logs, analytics, audit records, Sentry events, command output, and user-facing errors MUST NOT include raw Composio credentials, OAuth tokens, Connect Links containing secret material, or decrypted stored identity data.
+23. User-provided Composio secrets MUST continue to follow the normal KiloClaw secret encryption, transport, and deletion rules.
+24. Retired managed rows containing encrypted credentials or user-linked provider identifiers MUST be deleted after the required live-runtime verification or otherwise scrubbed in accordance with account-deletion requirements.
 
 ## Error Handling
 
@@ -78,7 +79,7 @@ Kilo previously shipped a managed Composio onboarding experiment that created Ki
 
 - Removed managed identity provisioning, managed Connect Link onboarding, and managed callback injection from supported product behavior.
 - Retained explicit user-provided Composio credentials through Settings and the encrypted secret pipeline.
-- Added post-deploy live-runtime verification and subsequent stored-state removal requirements for managed credentials created or injected while the experiment was shipped.
+- Added post-deploy live-runtime verification, temporary manual provenance tracking, and subsequent stored-state removal requirements for managed credentials created or injected while the experiment was shipped.
 
 ### 2026-05-20 -- Managed onboarding experiment
 

apps/web/src/lib/kiloclaw/instance-registry.ts

@@ -196,6 +196,22 @@ export async function restoreDestroyedInstance(instanceId: string): Promise<void
     .where(eq(kiloclaw_instances.id, instanceId));
 }
 
+// Retained until retired managed Composio state is verified and its schema is dropped.
+// Manual provenance prevents follow-up cleanup from removing user-owned secrets.
+export async function markComposioInstanceConfigManual(instanceId: string): Promise<void> {
+  await db
+    .update(kiloclaw_instances)
+    .set({ composio_config_source: 'manual' })
+    .where(eq(kiloclaw_instances.id, instanceId));
+}
+
+export async function clearComposioInstanceConfigSource(instanceId: string): Promise<void> {
+  await db
+    .update(kiloclaw_instances)
+    .set({ composio_config_source: null })
+    .where(eq(kiloclaw_instances.id, instanceId));
+}
+
 /**
  * Fetch the user's active personal KiloClaw instance (read-only, no upsert).
  *

apps/web/src/lib/kiloclaw/provision-secrets.test.ts

@@ -2,7 +2,11 @@ jest.mock('@/lib/kiloclaw/encryption', () => ({
   encryptKiloClawSecret: jest.fn((value: string) => `encrypted:${value}`),
 }));
 
-import { encryptProvisionSecretsForWorker } from './provision-secrets';
+import {
+  encryptProvisionSecretsForWorker,
+  getComposioSecretsPatchSource,
+  hasComposioProvisionSecrets,
+} from './provision-secrets';
 
 describe('encryptProvisionSecretsForWorker', () => {
   it('maps valid manual Composio secret keys to worker env var names before encrypting', () => {
@@ -27,4 +31,40 @@ describe('encryptProvisionSecretsForWorker', () => {
       })
     ).toThrow('Composio user API keys start with uak_');
   });
+
+  const partialComposioCredentialPairs: Array<Record<string, string>> = [
+    { composioUserApiKey: 'uak_manual_credential_123' },
+    { composioOrg: 'org-1' },
+  ];
+
+  it.each(partialComposioCredentialPairs)(
+    'rejects a partial manual Composio credential pair during provision',
+    secrets => {
+      expect(() => encryptProvisionSecretsForWorker(secrets)).toThrow(
+        'Composio requires all fields to be set together'
+      );
+    }
+  );
+});
+
+describe('Composio manual source tracking', () => {
+  it('identifies provision inputs that require a manual source marker', () => {
+    expect(
+      hasComposioProvisionSecrets({
+        composioUserApiKey: 'uak_manual_credential_123',
+        composioOrg: 'org-1',
+      })
+    ).toBe(true);
+    expect(hasComposioProvisionSecrets({ CUSTOM_SECRET: 'kept' })).toBe(false);
+  });
+
+  it('marks manual patch updates and clears source only when both fields are removed', () => {
+    expect(getComposioSecretsPatchSource({ composioUserApiKey: 'new-value' })).toBe(
+      'upsert_manual'
+    );
+    expect(getComposioSecretsPatchSource({ composioUserApiKey: null, composioOrg: null })).toBe(
+      'clear'
+    );
+    expect(getComposioSecretsPatchSource({ CUSTOM_SECRET: null })).toBe('none');
+  });
 });

apps/web/src/lib/kiloclaw/provision-secrets.ts

@@ -8,7 +8,31 @@ import { encryptKiloClawSecret } from '@/lib/kiloclaw/encryption';
 
 const COMPOSIO_SECRET_FIELD_KEYS = ['composioUserApiKey', 'composioOrg'] as const;
 
+export function hasComposioProvisionSecrets(secrets: Record<string, string> | undefined): boolean {
+  return COMPOSIO_SECRET_FIELD_KEYS.some(key => secrets?.[key] !== undefined);
+}
+
+export function getComposioSecretsPatchSource(
+  secrets: Record<string, string | null>
+): 'upsert_manual' | 'clear' | 'none' {
+  const touchedValues = COMPOSIO_SECRET_FIELD_KEYS.filter(key => secrets[key] !== undefined).map(
+    key => secrets[key]
+  );
+  if (touchedValues.length === 0) return 'none';
+  if (touchedValues.every(value => value === null)) return 'clear';
+  return 'upsert_manual';
+}
+
 function validateComposioProvisionSecrets(secrets: Record<string, string>): void {
+  if (!hasComposioProvisionSecrets(secrets)) return;
+  const hasAllFields = COMPOSIO_SECRET_FIELD_KEYS.every(key => secrets[key] !== undefined);
+  if (!hasAllFields) {
+    throw new TRPCError({
+      code: 'BAD_REQUEST',
+      message: 'Composio requires all fields to be set together',
+    });
+  }
+
   for (const key of COMPOSIO_SECRET_FIELD_KEYS) {
     const value = secrets[key];
     if (value === undefined) continue;

apps/web/src/routers/kiloclaw-router.ts

@@ -64,9 +64,11 @@ import {
   getInboundEmailAddressForInstance,
 } from '@/lib/kiloclaw/inbound-email-alias';
 import {
+  clearComposioInstanceConfigSource,
   getActiveInstance,
   listAllActiveInstances,
   markActiveInstanceDestroyed,
+  markComposioInstanceConfigManual,
   renameInstance,
   restoreDestroyedInstance,
   workerInstanceId,
@@ -76,7 +78,11 @@ import {
   getPersonalProvisionLockKey,
   withKiloclawProvisionContextLock,
 } from '@/lib/kiloclaw/provision-lock';
-import { encryptProvisionSecretsForWorker } from '@/lib/kiloclaw/provision-secrets';
+import {
+  encryptProvisionSecretsForWorker,
+  getComposioSecretsPatchSource,
+  hasComposioProvisionSecrets,
+} from '@/lib/kiloclaw/provision-secrets';
 import {
   clearSubscriptionLifecycleAfterInstanceDestroy,
   clearTrialInactivityStopAfterStart,
@@ -1133,6 +1139,10 @@ async function provisionInstance(
       : undefined
   );
 
+  if (hasComposioProvisionSecrets(input.secrets)) {
+    await markComposioInstanceConfigManual(result.instanceId);
+  }
+
   return result;
 }
 
@@ -3453,11 +3463,18 @@ export const kiloclawRouter = createTRPCRouter({
       const instance = await getActiveInstance(ctx.user.id);
       const client = new KiloClawInternalClient();
       try {
-        return await client.patchSecrets(
+        const result = await client.patchSecrets(
           ctx.user.id,
           { secrets: encryptedPatch, meta: input.meta },
           workerInstanceId(instance)
         );
+        const composioSourceAction = getComposioSecretsPatchSource(secrets);
+        if (instance && composioSourceAction === 'upsert_manual') {
+          await markComposioInstanceConfigManual(instance.id);
+        } else if (instance && composioSourceAction === 'clear') {
+          await clearComposioInstanceConfigSource(instance.id);
+        }
+        return result;
       } catch (err) {
         if (err instanceof KiloClawApiError && err.statusCode >= 400 && err.statusCode < 500) {
           // Extract message from worker response body (JSON or plain text)

apps/web/src/routers/organizations/organization-kiloclaw-router.ts

@@ -39,8 +39,10 @@ import {
   getInboundEmailAddressForInstance,
 } from '@/lib/kiloclaw/inbound-email-alias';
 import {
+  clearComposioInstanceConfigSource,
   getActiveOrgInstance,
   markActiveInstanceDestroyed,
+  markComposioInstanceConfigManual,
   renameOrgInstance,
   restoreDestroyedInstance,
   workerInstanceId,
@@ -50,7 +52,11 @@ import {
   getOrganizationProvisionLockKey,
   withKiloclawProvisionContextLock,
 } from '@/lib/kiloclaw/provision-lock';
-import { encryptProvisionSecretsForWorker } from '@/lib/kiloclaw/provision-secrets';
+import {
+  encryptProvisionSecretsForWorker,
+  getComposioSecretsPatchSource,
+  hasComposioProvisionSecrets,
+} from '@/lib/kiloclaw/provision-secrets';
 import {
   organizationMemberProcedure,
   organizationMemberMutationProcedure,
@@ -481,6 +487,10 @@ export const organizationKiloclawRouter = createTRPCRouter({
             { orgId: input.organizationId }
           );
 
+          if (hasComposioProvisionSecrets(input.secrets)) {
+            await markComposioInstanceConfigManual(result.instanceId);
+          }
+
           PostHogClient().capture({
             distinctId: ctx.user.google_user_email,
             event: 'claw_org_instance_provisioned',
@@ -534,6 +544,10 @@ export const organizationKiloclawRouter = createTRPCRouter({
         { instanceId: instance.id, orgId: input.organizationId }
       );
 
+      if (hasComposioProvisionSecrets(input.secrets)) {
+        await markComposioInstanceConfigManual(result.instanceId);
+      }
+
       return result;
     }),
 
@@ -737,11 +751,18 @@ export const organizationKiloclawRouter = createTRPCRouter({
       const instance = await requireOrgInstance(ctx.user.id, input.organizationId);
       const client = new KiloClawInternalClient();
       try {
-        return await client.patchSecrets(
+        const result = await client.patchSecrets(
           ctx.user.id,
           { secrets: encryptedPatch, meta: input.meta },
           workerInstanceId(instance)
         );
+        const composioSourceAction = getComposioSecretsPatchSource(input.secrets);
+        if (composioSourceAction === 'upsert_manual') {
+          await markComposioInstanceConfigManual(instance.id);
+        } else if (composioSourceAction === 'clear') {
+          await clearComposioInstanceConfigSource(instance.id);
+        }
+        return result;
       } catch (err) {
         if (err instanceof KiloClawApiError && err.statusCode >= 400 && err.statusCode < 500) {
           let message = `Secret patch failed (${err.statusCode})`;