@velum-labs/routekit-tool-claude 0.18.0 → 0.18.2

package/dist/install.d.ts

@@ -9,6 +9,11 @@ export type ClaudeInstallInput = {
     gatewayUrl: string;
     /** Canonical RouteKit catalog ids permitted by the current model policy. */
     models: readonly string[];
+    /**
+     * Command Claude Code invokes when it needs the gateway bearer token. The
+     * helper output is never persisted in settings.json.
+     */
+    apiKeyHelper?: string;
     owner: ClaudeInstallOwner;
     claudeConfigDir?: string;
 };

package/dist/install.js

@@ -109,7 +109,8 @@ function isInstalledManifest(value) {
         (value.managedPickerModels === undefined || isStringArray(value.managedPickerModels)) &&
         (value.managedAvailableModels === undefined || value.managedAvailableModels === true) &&
         (value.managedEnforceAvailableModels === undefined ||
-            value.managedEnforceAvailableModels === true));
+            value.managedEnforceAvailableModels === true) &&
+        (value.managedApiKeyHelper === undefined || typeof value.managedApiKeyHelper === "string"));
 }
 function parseManifest(content, manifestPath) {
     let parsed;
@@ -449,6 +450,23 @@ export async function installClaudeIntegration(input) {
         const settings = parseSettings(beforeSettings.content ?? "{}\n", configPath);
         const env = { ...(settings.env ?? {}) };
         const nextManaged = managedEnv(input);
+        if (settings.apiKeyHelper !== undefined &&
+            typeof settings.apiKeyHelper !== "string") {
+            throw new Error(`the "apiKeyHelper" field in your Claude settings (${configPath}) must be a string`);
+        }
+        const currentApiKeyHelper = settings.apiKeyHelper;
+        const previousApiKeyHelper = previousManifest?.managedApiKeyHelper;
+        if (previousApiKeyHelper !== undefined &&
+            currentApiKeyHelper !== previousApiKeyHelper) {
+            throw new Error(`your Claude settings changed RouteKit-managed apiKeyHelper in ${configPath}; ` +
+                "restore that value before rerunning the install command");
+        }
+        if (previousManifest === undefined &&
+            input.apiKeyHelper !== undefined &&
+            currentApiKeyHelper !== undefined) {
+            throw new Error(`your Claude settings already define apiKeyHelper in ${configPath}; ` +
+                `remove it before rerunning \`${input.owner.installCommand}\``);
+        }
         const desiredPickerModels = pickerModels(input);
         if (desiredPickerModels.length === 0) {
             throw new Error("RouteKit's Claude picker catalog cannot be empty");
@@ -490,10 +508,16 @@ export async function installClaudeIntegration(input) {
             ...settings,
             env,
             availableModels: nextPickerModels,
+            ...(input.apiKeyHelper !== undefined
+                ? { apiKeyHelper: input.apiKeyHelper }
+                : {}),
             ...(nextManagedEnforceAvailableModels === true
                 ? { enforceAvailableModels: true }
                 : {})
         };
+        if (input.apiKeyHelper === undefined && previousApiKeyHelper !== undefined) {
+            delete nextSettings.apiKeyHelper;
+        }
         const nextContent = serialize(nextSettings);
         const targetSettings = snapshot(nextContent, 0o600);
         const exactRestoreEligible = previousManifest === undefined
@@ -514,6 +538,9 @@ export async function installClaudeIntegration(input) {
                 : {}),
             ...(nextManagedEnforceAvailableModels === true
                 ? { managedEnforceAvailableModels: true }
+                : {}),
+            ...(input.apiKeyHelper !== undefined
+                ? { managedApiKeyHelper: input.apiKeyHelper }
                 : {})
         };
         const pendingManifest = {
@@ -543,6 +570,7 @@ export async function installClaudeIntegration(input) {
             action: previousManifest === undefined ? "installed" : "updated",
             managedKeys: [
                 ...Object.keys(nextManaged),
+                ...(input.apiKeyHelper !== undefined ? ["apiKeyHelper"] : []),
                 "availableModels",
                 ...(nextManagedEnforceAvailableModels === true ? ["enforceAvailableModels"] : [])
             ]
@@ -595,6 +623,10 @@ export async function uninstallClaudeIntegration(input) {
                     delete env[key];
             }
             const next = { ...settings };
+            if (installed.managedApiKeyHelper !== undefined &&
+                settings.apiKeyHelper === installed.managedApiKeyHelper) {
+                delete next.apiKeyHelper;
+            }
             if (Object.keys(env).length === 0)
                 delete next.env;
             else

package/dist/test/install.test.js

@@ -67,6 +67,52 @@ test("Claude managed install updates and restores the exact original settings",
         rmSync(configDirectory, { recursive: true, force: true });
     }
 });
+test("Claude install owns a pull-based apiKeyHelper without storing its output", async () => {
+    const configDirectory = mkdtempSync(join(tmpdir(), "routekit-claude-helper-"));
+    const configPath = join(configDirectory, "settings.json");
+    const original = '{"theme":"dark"}\n';
+    writeFileSync(configPath, original);
+    try {
+        const helper = "'/opt/routekit/node' '/opt/routekit/index.js' credential get";
+        const installed = await installClaudeIntegration({
+            gatewayUrl: "http://127.0.0.1:9999",
+            models: ["openai/mock-model"],
+            apiKeyHelper: helper,
+            owner: OWNER,
+            claudeConfigDir: configDirectory
+        });
+        assert.ok(installed.managedKeys.includes("apiKeyHelper"));
+        assert.equal(JSON.parse(readFileSync(configPath, "utf8")).apiKeyHelper, helper);
+        const settings = JSON.parse(readFileSync(configPath, "utf8"));
+        settings.theme = "light";
+        writeFileSync(configPath, `${JSON.stringify(settings, null, 2)}\n`);
+        await uninstallClaudeIntegration({
+            ownerId: OWNER.id,
+            claudeConfigDir: configDirectory
+        });
+        assert.equal(JSON.parse(readFileSync(configPath, "utf8")).apiKeyHelper, undefined);
+        assert.equal(JSON.parse(readFileSync(configPath, "utf8")).theme, "light");
+    }
+    finally {
+        rmSync(configDirectory, { recursive: true, force: true });
+    }
+});
+test("Claude install refuses to overwrite a user apiKeyHelper", async () => {
+    const configDirectory = mkdtempSync(join(tmpdir(), "routekit-claude-helper-conflict-"));
+    writeFileSync(join(configDirectory, "settings.json"), '{"apiKeyHelper":"/usr/local/bin/user-helper"}\n');
+    try {
+        await assert.rejects(installClaudeIntegration({
+            gatewayUrl: "http://127.0.0.1:9999",
+            models: ["openai/mock-model"],
+            apiKeyHelper: "/usr/local/bin/routekit-helper",
+            owner: OWNER,
+            claudeConfigDir: configDirectory
+        }), /already define apiKeyHelper/);
+    }
+    finally {
+        rmSync(configDirectory, { recursive: true, force: true });
+    }
+});
 test("Claude uninstall preserves user edits made after install", async () => {
     const configDirectory = mkdtempSync(join(tmpdir(), "routekit-claude-edits-"));
     const configPath = join(configDirectory, "settings.json");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@velum-labs/routekit-tool-claude",
   "private": false,
-  "version": "0.18.0",
+  "version": "0.18.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/velum-labs/routekit.git",
@@ -30,11 +30,11 @@
     "@anthropic-ai/sdk": "0.115.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "zod": "4.4.3",
-    "@velum-labs/routekit-contracts": "0.18.0",
-    "@velum-labs/routekit-harness-core": "0.18.0",
-    "@velum-labs/routekit-registry": "0.18.0",
-    "@velum-labs/routekit-runtime": "0.18.0",
-    "@velum-labs/routekit-tools": "0.18.0"
+    "@velum-labs/routekit-contracts": "0.18.2",
+    "@velum-labs/routekit-harness-core": "0.18.2",
+    "@velum-labs/routekit-registry": "0.18.2",
+    "@velum-labs/routekit-runtime": "0.18.2",
+    "@velum-labs/routekit-tools": "0.18.2"
   },
   "keywords": [
     "llm",