feat(kiloclaw): add 1Password integration via op CLI (#1333)

<!-- 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
- Add 1Password as a password manager integration in KiloClaw, following
the catalog driven pattern
- Users configure a Service Account Token (ops_...) in Settings; the op
CLI (already installed in the Dockerfile at v2.33.0) reads
OP_SERVICE_ACCOUNT_TOKEN from the environment automatically
- Bootstrap writes a TOOLS.md section so the agent knows op is available
and how to use it
- Fix: replace hardcoded .max(500) Zod cap in patchSecrets with
MAX_SECRET_FIELD_LENGTH derived from the catalog (1Password tokens are
~850 chars)
- Add upgrade_required as a new changelog deploy hint type (purple
badge), distinct from redeploy_required


## Verification
- pnpm run typecheck — passes
- pnpm run format:check — passes
- pnpm run test — 2721 passed, 175 suites
- vitest run bootstrap.test.ts — 44 passed (includes 5 new tests for
TOOLS.md 1Password section)
- Manually tested token validation against 3 real 1Password service
account tokens (848-852 chars)
- Verified regex matches via new RegExp() in Node to ensure the catalog
pattern works at runtime

<img width="523" height="151" alt="Screenshot 2026-03-20 at 2 40 59 PM"
src="https://github.com/user-attachments/assets/86a2e969-2c9f-4bf2-b14e-4eac1787b82d"
/>



## Visual Changes
- New Password Managers section in Settings tab (between Payments and
Productivity)
- 1Password entry with Lock icon, collapsible accordion, and "Setup
Guide" dialog with security warning
- New purple Upgrade Required badge in changelog (alongside existing
blue/red badges)
<img width="839" height="311" alt="Screenshot 2026-03-20 at 2 44 06 PM"
src="https://github.com/user-attachments/assets/c68ad38f-9618-4561-825c-23d23e95dd8d"
/>


## Reviewer Notes

- No Dockerfile changes — op CLI is already installed. The controller
bootstrap change requires a new image build (CI triggers on controller
source change) and users must Upgrade to latest (not just Redeploy) to
get the TOOLS.md section
- The token save + env injection works immediately on Redeploy; the
agent awareness via TOOLS.md only activates after Upgrade. This is a
known gap — the version/upgrade system doesn't currently surface
controller-only changes as "update available"
- MAX_SECRET_FIELD_LENGTH is currently 2000 (driven by AgentCard JWT
maxLength). This raises the blanket Zod cap from 500 → 2000, which is
well within CF Workers/Next.js payload limits
- Service Accounts are available on all 1Password plans (Individual,
Family, Teams, Business) with different rate limits. No plan restriction
needed
- The validationPattern uses \\- in the character class — harmless,
matches the style of other catalog patterns (e.g., Discord)

Author: St0rmz1

kiloclaw/controller/src/bootstrap.test.ts

@@ -7,6 +7,7 @@ import {
   generateHooksToken,
   configureGitHub,
   runOnboardOrDoctor,
+  updateToolsMd1PasswordSection,
   buildGatewayArgs,
   bootstrap,
 } from './bootstrap';
@@ -567,6 +568,79 @@ describe('runOnboardOrDoctor', () => {
   });
 });
 
+// ---- updateToolsMd1PasswordSection ----
+
+describe('updateToolsMd1PasswordSection', () => {
+  it('adds 1Password section when OP_SERVICE_ACCOUNT_TOKEN is set', () => {
+    const harness = fakeDeps();
+    (harness.deps.readFileSync as ReturnType<typeof vi.fn>).mockReturnValue('# TOOLS\n');
+
+    const env: Record<string, string | undefined> = {
+      OP_SERVICE_ACCOUNT_TOKEN: 'ops_test123',
+    };
+
+    updateToolsMd1PasswordSection(env, harness.deps);
+
+    expect(harness.writeCalls).toHaveLength(1);
+    expect(harness.writeCalls[0]!.data).toContain('<!-- BEGIN:1password -->');
+    expect(harness.writeCalls[0]!.data).toContain('op vault list');
+    expect(harness.writeCalls[0]!.data).toContain('<!-- END:1password -->');
+  });
+
+  it('skips adding when section already present', () => {
+    const harness = fakeDeps();
+    (harness.deps.readFileSync as ReturnType<typeof vi.fn>).mockReturnValue(
+      '# TOOLS\n<!-- BEGIN:1password -->\nexisting\n<!-- END:1password -->'
+    );
+
+    const env: Record<string, string | undefined> = {
+      OP_SERVICE_ACCOUNT_TOKEN: 'ops_test123',
+    };
+
+    updateToolsMd1PasswordSection(env, harness.deps);
+
+    expect(harness.writeCalls).toHaveLength(0);
+  });
+
+  it('removes stale section when token is absent', () => {
+    const harness = fakeDeps();
+    (harness.deps.readFileSync as ReturnType<typeof vi.fn>).mockReturnValue(
+      '# TOOLS\n<!-- BEGIN:1password -->\nold section\n<!-- END:1password -->\n'
+    );
+
+    const env: Record<string, string | undefined> = {};
+
+    updateToolsMd1PasswordSection(env, harness.deps);
+
+    expect(harness.writeCalls).toHaveLength(1);
+    expect(harness.writeCalls[0]!.data).not.toContain('<!-- BEGIN:1password -->');
+  });
+
+  it('no-ops when TOOLS.md does not exist', () => {
+    const harness = fakeDeps();
+    (harness.deps.existsSync as ReturnType<typeof vi.fn>).mockReturnValue(false);
+
+    const env: Record<string, string | undefined> = {
+      OP_SERVICE_ACCOUNT_TOKEN: 'ops_test123',
+    };
+
+    updateToolsMd1PasswordSection(env, harness.deps);
+
+    expect(harness.writeCalls).toHaveLength(0);
+  });
+
+  it('no-ops when token absent and no stale section exists', () => {
+    const harness = fakeDeps();
+    (harness.deps.readFileSync as ReturnType<typeof vi.fn>).mockReturnValue('# TOOLS\n');
+
+    const env: Record<string, string | undefined> = {};
+
+    updateToolsMd1PasswordSection(env, harness.deps);
+
+    expect(harness.writeCalls).toHaveLength(0);
+  });
+});
+
 // ---- buildGatewayArgs ----
 
 describe('buildGatewayArgs', () => {

kiloclaw/controller/src/bootstrap.ts

@@ -442,7 +442,67 @@ export function updateToolsMdGoogleSection(env: EnvLike, deps: BootstrapDeps): v
   }
 }
 
-// ---- Step 8: Gateway args ----
+// ---- Step 8: TOOLS.md 1Password section ----
+
+const OP_MARKER_BEGIN = '<!-- BEGIN:1password -->';
+const OP_MARKER_END = '<!-- END:1password -->';
+
+const OP_TOOLS_SECTION = `
+${OP_MARKER_BEGIN}
+## 1Password
+
+The \`op\` CLI is configured with a 1Password service account. Use it to look up credentials, generate passwords, and manage vault items.
+
+- List vaults: \`op vault list\`
+- Search items: \`op item list --vault <vault-name>\`
+- Get a credential: \`op item get "<item-name>" --vault <vault-name>\`
+- Get specific field: \`op item get "<item-name>" --fields password --vault <vault-name>\`
+- Generate password: \`op item create --category login --title "New Login" --generate-password\`
+- Run \`op --help\` for all available commands.
+
+**Security note:** Only access credentials the user has explicitly requested. Do not list or expose vault contents unnecessarily.
+${OP_MARKER_END}`;
+
+/**
+ * Manage the 1Password section in TOOLS.md.
+ *
+ * When OP_SERVICE_ACCOUNT_TOKEN is present, append a bounded section so the
+ * agent knows the op CLI is available. When absent, remove any stale section.
+ * Idempotent: skips if the marker is already present.
+ */
+export function updateToolsMd1PasswordSection(env: EnvLike, deps: BootstrapDeps): void {
+  if (!deps.existsSync(TOOLS_MD_DEST)) return;
+
+  const content = deps.readFileSync(TOOLS_MD_DEST, 'utf8');
+
+  if (env.OP_SERVICE_ACCOUNT_TOKEN) {
+    // 1Password configured — add section if not already present
+    if (!content.includes(OP_MARKER_BEGIN)) {
+      deps.writeFileSync(TOOLS_MD_DEST, content + OP_TOOLS_SECTION);
+      console.log('TOOLS.md: added 1Password section');
+    } else {
+      console.log('TOOLS.md: 1Password section already present');
+    }
+  } else {
+    // 1Password not configured — remove stale section if present
+    if (content.includes(OP_MARKER_BEGIN)) {
+      const beginIdx = content.indexOf(OP_MARKER_BEGIN);
+      const endIdx = content.indexOf(OP_MARKER_END);
+      if (beginIdx !== -1 && endIdx !== -1) {
+        const before = content.slice(0, beginIdx).replace(/\n+$/, '\n');
+        const after = content.slice(endIdx + OP_MARKER_END.length).replace(/^\n+/, '');
+        deps.writeFileSync(TOOLS_MD_DEST, before + after);
+        console.log('TOOLS.md: removed stale 1Password section');
+      } else {
+        console.warn(
+          'TOOLS.md: 1Password BEGIN marker found but END marker missing, skipping removal'
+        );
+      }
+    }
+  }
+}
+
+// ---- Step 9: Gateway args ----
 
 /**
  * Build the gateway CLI arguments array.
@@ -497,6 +557,7 @@ export async function bootstrap(
   await yieldToEventLoop();
 
   updateToolsMdGoogleSection(env, deps);
+  updateToolsMd1PasswordSection(env, deps);
 
   // Write mcporter config for MCP servers (AgentCard, etc.)
   writeMcporterConfig(env);

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

@@ -44,6 +44,7 @@ describe('Secret Catalog', () => {
         'key',
         'github',
         'credit-card',
+        'lock',
       ]);
       for (const entry of SECRET_CATALOG) {
         expect(validIcons.has(entry.icon)).toBe(true);
@@ -193,9 +194,10 @@ describe('Secret Catalog', () => {
 
     it('returns all tool entries sorted by order', () => {
       const tools = getEntriesByCategory('tool');
-      expect(tools.length).toBe(2);
+      expect(tools.length).toBe(3);
       expect(tools[0].id).toBe('github');
       expect(tools[1].id).toBe('agentcard');
+      expect(tools[2].id).toBe('onepassword');
     });
 
     it('returns empty array for categories with no entries', () => {
@@ -220,7 +222,8 @@ describe('Secret Catalog', () => {
       expect(keys).toContain('githubUsername');
       expect(keys).toContain('githubEmail');
       expect(keys).toContain('agentcardApiKey');
-      expect(keys.size).toBe(4);
+      expect(keys).toContain('onepasswordServiceAccountToken');
+      expect(keys.size).toBe(5);
     });
 
     it('returns empty set for categories with no entries', () => {

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

@@ -154,6 +154,28 @@ const SECRET_CATALOG_RAW = [
     helpText: 'Virtual debit cards for autonomous agent spending. See setup guide for details.',
     helpUrl: 'https://agentcard.sh',
   },
+  {
+    id: 'onepassword',
+    label: '1Password',
+    category: 'tool',
+    icon: 'lock',
+    order: 3,
+    fields: [
+      {
+        key: 'onepasswordServiceAccountToken',
+        label: 'Service Account Token',
+        placeholder: 'ops_...',
+        placeholderConfigured: 'Enter new token to replace',
+        envVar: 'OP_SERVICE_ACCOUNT_TOKEN',
+        validationPattern: '^ops_[A-Za-z0-9_\\-]{50,1500}$',
+        validationMessage:
+          '1Password service account tokens start with ops_ followed by a long base64-encoded string.',
+        maxLength: 2000,
+      },
+    ],
+    helpText: 'Create a service account at 1password.com with access to a dedicated vault.',
+    helpUrl: 'https://developer.1password.com/docs/service-accounts/get-started/',
+  },
 ] as const satisfies readonly SecretCatalogEntry[];
 
 // Runtime validation — fails fast at module load if catalog data is malformed
@@ -192,6 +214,11 @@ export const FIELD_KEY_TO_ENTRY: ReadonlyMap<string, SecretCatalogEntry> = new M
   SECRET_CATALOG.flatMap(entry => entry.fields.map(field => [field.key, entry]))
 );
 
+/** Largest maxLength across all catalog fields (for blanket Zod schema caps) */
+export const MAX_SECRET_FIELD_LENGTH: number = Math.max(
+  ...SECRET_CATALOG.flatMap(entry => entry.fields.map(field => field.maxLength))
+);
+
 /** Set of all env var names from catalog entries (for SENSITIVE_KEYS classification) */
 export const ALL_SECRET_ENV_VARS: ReadonlySet<string> = new Set(
   SECRET_CATALOG.flatMap(entry => entry.fields.map(field => field.envVar))

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

@@ -27,6 +27,7 @@ export {
   ENV_VAR_TO_FIELD_KEY,
   FIELD_KEY_TO_ENTRY,
   ALL_SECRET_ENV_VARS,
+  MAX_SECRET_FIELD_LENGTH,
   INTERNAL_SENSITIVE_ENV_VARS,
   getEntriesByCategory,
   getFieldKeysByCategory,

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

@@ -11,6 +11,7 @@ export const SecretIconKeySchema = z.enum([
   'key',
   'github',
   'credit-card',
+  'lock',
 ]);
 
 /**

kiloclaw/src/routes/kiloclaw.test.ts

@@ -17,6 +17,7 @@ describe('buildConfiguredSecrets', () => {
       slack: false,
       github: false,
       agentcard: false,
+      onepassword: false,
     });
   });
 
@@ -36,7 +37,10 @@ describe('buildConfiguredSecrets', () => {
     expect(partial.slack).toBe(false);
 
     const full = buildConfiguredSecrets({
-      encryptedSecrets: { SLACK_BOT_TOKEN: envelope, SLACK_APP_TOKEN: envelope },
+      encryptedSecrets: {
+        SLACK_BOT_TOKEN: envelope,
+        SLACK_APP_TOKEN: envelope,
+      },
     });
     expect(full.slack).toBe(true);
   });
@@ -107,12 +111,15 @@ describe('buildConfiguredSecrets', () => {
     expect(keys).toContain('telegram');
     expect(keys).toContain('discord');
     expect(keys).toContain('slack');
-    expect(keys).toHaveLength(5);
+    expect(keys).toContain('onepassword');
+    expect(keys).toHaveLength(6);
   });
 
   it('treats null values as not configured', () => {
     const result = buildConfiguredSecrets({
-      encryptedSecrets: { TELEGRAM_BOT_TOKEN: null as unknown as Record<string, unknown> },
+      encryptedSecrets: {
+        TELEGRAM_BOT_TOKEN: null as unknown as Record<string, unknown>,
+      },
     });
     expect(result.telegram).toBe(false);
   });

src/app/(app)/claw/components/ChangelogCard.tsx

@@ -24,6 +24,10 @@ const DEPLOY_HINT_STYLES = {
     label: 'Redeploy Required',
     className: 'border-red-500/30 bg-red-500/15 text-red-400',
   },
+  upgrade_required: {
+    label: 'Upgrade Required',
+    className: 'border-purple-500/30 bg-purple-500/15 text-purple-400',
+  },
 } as const;
 
 function ChangelogRow({ entry }: { entry: ChangelogEntry }) {

src/app/(app)/claw/components/ChangelogTab.tsx

@@ -23,6 +23,10 @@ const DEPLOY_HINT_STYLES = {
     label: 'Redeploy Required',
     className: 'border-red-500/30 bg-red-500/15 text-red-400',
   },
+  upgrade_required: {
+    label: 'Upgrade Required',
+    className: 'border-purple-500/30 bg-purple-500/15 text-purple-400',
+  },
 } as const;
 
 function ChangelogRow({ entry }: { entry: ChangelogEntry }) {