@simonsbs/keylore 1.0.0-rc5 → 1.0.0

package/dist/http/server.js

@@ -1,6 +1,12 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { randomUUID } from "node:crypto";
 import http from "node:http";
 import { URL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod/v4";
@@ -8,6 +14,13 @@ import { accessRequestInputSchema, backupInspectOutputSchema, breakGlassRequestI
 import { renderAdminPage } from "./admin-ui.js";
 import { createKeyLoreMcpServer } from "../mcp/create-server.js";
 import { authContextFromToken } from "../services/auth-context.js";
+const execFileAsync = promisify(execFile);
+const applyToolConfigInputSchema = z.object({
+    tool: z.enum(["codex", "gemini", "claude"]),
+});
+const replaceLocalSecretInputSchema = z.object({
+    secretValue: z.string().min(1),
+});
 function respondJson(res, statusCode, payload) {
     res.writeHead(statusCode, { "content-type": "application/json; charset=utf-8" });
     res.end(`${JSON.stringify(payload, null, 2)}\n`);
@@ -24,6 +37,124 @@ function respondRedirect(res, location) {
     res.writeHead(302, { location });
     res.end();
 }
+function userHomeDirectory() {
+    return process.env.HOME || os.homedir();
+}
+function resolveLocalStdioEntryPath() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const packageRoot = path.resolve(moduleDir, "..", "..");
+    const builtEntry = path.join(packageRoot, "dist", "index.js");
+    return builtEntry;
+}
+async function ensureParentDirectory(filePath) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+}
+async function readTextFileIfExists(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function codexManagedBlock(stdioEntryPath) {
+    const escapedPath = JSON.stringify(stdioEntryPath.replace(/\\/g, "\\\\"));
+    return [
+        "# >>> keylore managed start",
+        "[mcp_servers.keylore_stdio]",
+        'command = "node"',
+        `args = [${escapedPath}, "--transport", "stdio"]`,
+        "# <<< keylore managed end",
+    ].join("\n");
+}
+function replaceManagedTomlBlock(content, tableName, managedBlock) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    const managedStart = "# >>> keylore managed start";
+    const managedEnd = "# <<< keylore managed end";
+    const managedPattern = new RegExp(`${managedStart.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${managedEnd.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\n?`, "m");
+    if (managedPattern.test(normalized)) {
+        const next = normalized.replace(managedPattern, `${managedBlock}\n`);
+        return { next, changed: next !== normalized };
+    }
+    const lines = normalized.split("\n");
+    const tableHeader = `[${tableName}]`;
+    const startIndex = lines.findIndex((line) => line.trim() === tableHeader);
+    if (startIndex >= 0) {
+        let endIndex = lines.length;
+        for (let index = startIndex + 1; index < lines.length; index += 1) {
+            const candidate = lines[index];
+            if (candidate && candidate.trim().startsWith("[") && candidate.trim() !== tableHeader) {
+                endIndex = index;
+                break;
+            }
+        }
+        const before = lines.slice(0, startIndex).join("\n");
+        const after = lines.slice(endIndex).join("\n");
+        const next = `${before}${before ? "\n" : ""}${managedBlock}${after ? `\n${after}` : ""}`.replace(/\n{3,}/g, "\n\n");
+        return { next, changed: next !== normalized };
+    }
+    const next = `${normalized.trimEnd()}${normalized.trimEnd() ? "\n\n" : ""}${managedBlock}\n`;
+    return { next, changed: next !== normalized };
+}
+async function applyCodexLocalConfig(stdioEntryPath) {
+    const filePath = path.join(userHomeDirectory(), ".codex", "config.toml");
+    const existing = (await readTextFileIfExists(filePath)) ?? "";
+    const managedBlock = codexManagedBlock(stdioEntryPath);
+    const { next, changed } = replaceManagedTomlBlock(existing, "mcp_servers.keylore_stdio", managedBlock);
+    await ensureParentDirectory(filePath);
+    if (changed || existing.length === 0) {
+        await writeFile(filePath, next, "utf8");
+    }
+    return {
+        path: filePath,
+        action: existing.length === 0 ? "created" : changed ? "updated" : "unchanged",
+    };
+}
+async function applyGeminiLocalConfig(stdioEntryPath) {
+    const filePath = path.join(userHomeDirectory(), ".gemini", "settings.json");
+    const existing = (await readTextFileIfExists(filePath)) ?? "";
+    let parsed = {};
+    if (existing.trim().length > 0) {
+        parsed = JSON.parse(existing);
+    }
+    const currentServers = parsed.mcpServers && typeof parsed.mcpServers === "object" && !Array.isArray(parsed.mcpServers)
+        ? { ...parsed.mcpServers }
+        : {};
+    currentServers.keylore_stdio = {
+        command: "node",
+        args: [stdioEntryPath, "--transport", "stdio"],
+    };
+    parsed.mcpServers = currentServers;
+    const next = `${JSON.stringify(parsed, null, 2)}\n`;
+    await ensureParentDirectory(filePath);
+    if (next !== existing) {
+        await writeFile(filePath, next, "utf8");
+    }
+    return {
+        path: filePath,
+        action: existing.length === 0 ? "created" : next !== existing ? "updated" : "unchanged",
+    };
+}
+async function applyClaudeLocalConfig(stdioEntryPath) {
+    const commandJson = JSON.stringify({
+        command: "node",
+        args: [stdioEntryPath, "--transport", "stdio"],
+    });
+    try {
+        await execFileAsync("claude", ["mcp", "remove", "-s", "user", "keylore_stdio"]);
+    }
+    catch {
+        // Ignore missing existing config entries.
+    }
+    await execFileAsync("claude", ["mcp", "add-json", "-s", "user", "keylore_stdio", commandJson]);
+    return {
+        path: path.join(userHomeDirectory(), ".claude", "settings.json"),
+        action: "updated",
+    };
+}
 async function readBody(req, maxBytes) {
     const contentLengthHeader = req.headers["content-length"];
     const contentLength = typeof contentLengthHeader === "string" ? Number.parseInt(contentLengthHeader, 10) : undefined;
@@ -480,6 +611,36 @@ async function handleApiRequest(app, req, res, url) {
         });
         return;
     }
+    if (url.pathname === "/v1/core/tooling/apply" && req.method === "POST") {
+        const context = await authenticateRequest(app, req, res, ["catalog:write"], "api", `${app.config.publicBaseUrl}/v1`);
+        if (!context) {
+            return;
+        }
+        app.auth.requireRoles(context, ["admin", "operator"]);
+        if (!isLoopbackRequest(req) || app.config.environment === "production") {
+            respondJson(res, 403, { error: "Local tool setup is only available from loopback development instances." });
+            return;
+        }
+        const body = applyToolConfigInputSchema.parse(await readJsonBody(req, app.config.maxRequestBytes));
+        let result;
+        if (body.tool === "codex") {
+            result = await applyCodexLocalConfig(resolveLocalStdioEntryPath());
+        }
+        else if (body.tool === "gemini") {
+            result = await applyGeminiLocalConfig(resolveLocalStdioEntryPath());
+        }
+        else {
+            result = await applyClaudeLocalConfig(resolveLocalStdioEntryPath());
+        }
+        respondJson(res, 200, {
+            ok: true,
+            tool: body.tool,
+            path: result.path,
+            action: result.action,
+            connection: "local_stdio",
+        });
+        return;
+    }
     if (url.pathname === "/v1/catalog/credentials" && req.method === "GET") {
         const context = await authenticateRequest(app, req, res, ["catalog:read"], "api", `${app.config.publicBaseUrl}/v1`);
         if (!context) {
@@ -539,6 +700,18 @@ async function handleApiRequest(app, req, res, url) {
         respondJson(res, 200, { credential });
         return;
     }
+    if (coreCredentialContextId && url.pathname.endsWith("/local-secret") && req.method === "POST") {
+        const context = await authenticateRequest(app, req, res, ["catalog:write"], "api", `${app.config.publicBaseUrl}/v1`);
+        if (!context) {
+            return;
+        }
+        app.auth.requireRoles(context, ["admin", "operator"]);
+        const credentialId = coreCredentialContextId.replace(/\/local-secret$/, "");
+        const body = replaceLocalSecretInputSchema.parse(await readJsonBody(req, app.config.maxRequestBytes));
+        const credential = await app.coreMode.replaceLocalSecret(context, credentialId, body.secretValue);
+        respondJson(res, 200, { credential, updatedSecret: true });
+        return;
+    }
     if (coreCredentialContextId && !url.pathname.endsWith("/context") && req.method === "DELETE") {
         const context = await authenticateRequest(app, req, res, ["catalog:write"], "api", `${app.config.publicBaseUrl}/v1`);
         if (!context) {

package/dist/mcp/create-server.js

@@ -28,7 +28,7 @@ export function createKeyLoreMcpServer(app) {
         version: app.config.version,
     });
     server.registerTool("catalog_search", {
-        description: "Search credential metadata without exposing secret values. Use this before attempting access.",
+        description: "Search credential metadata without exposing secret values. Use this first to find the best credential by purpose, service, domain, permitted operation, tags, and LLM/user context. Do not assume the requested token name matches the credential ID.",
         inputSchema: {
             query: z.string().optional(),
             service: z.string().optional(),
@@ -54,7 +54,7 @@ export function createKeyLoreMcpServer(app) {
         };
     });
     server.registerTool("catalog_get", {
-        description: "Return one credential metadata record by identifier, still without secrets.",
+        description: "Return one credential metadata record by identifier, still without secrets. Use this after search when you need to inspect one candidate more closely before choosing it for access.",
         inputSchema: {
             credentialId: z.string().min(1),
         },
@@ -94,7 +94,7 @@ export function createKeyLoreMcpServer(app) {
         };
     });
     server.registerTool("access_request", {
-        description: "Evaluate policy and, if allowed, execute a constrained authenticated proxy request without returning secret material.",
+        description: "Evaluate policy and, if allowed, execute a constrained authenticated proxy request without returning secret material. Use the credential selected from metadata context, domains, and allowed operations, not just because its name looks similar to the request.",
         inputSchema: {
             credentialId: z.string().min(1),
             operation: operationSchema,
@@ -115,7 +115,7 @@ export function createKeyLoreMcpServer(app) {
         };
     });
     server.registerTool("policy_simulate", {
-        description: "Evaluate policy for a proposed access request without executing the outbound call or creating approval side effects.",
+        description: "Evaluate policy for a proposed access request without executing the outbound call or creating approval side effects. Use this to compare likely credentials and confirm the context-matched choice before making a live request.",
         inputSchema: {
             credentialId: z.string().min(1),
             operation: operationSchema,

package/dist/repositories/credential-repository.js

@@ -4,6 +4,23 @@ import { readTextFile, writeTextFile } from "./json-file.js";
 function normalizeText(value) {
     return value.trim().toLowerCase();
 }
+function normalizedLlmContext(credential) {
+    return credential.llmContext?.trim() || credential.selectionNotes;
+}
+function normalizedUserContext(credential) {
+    return credential.userContext?.trim() || normalizedLlmContext(credential);
+}
+function normalizedUpdateContexts(current, patch) {
+    const llmContext = patch.llmContext?.trim() ??
+        patch.selectionNotes?.trim() ??
+        current.llmContext?.trim() ??
+        current.selectionNotes;
+    return {
+        selectionNotes: llmContext,
+        llmContext,
+        userContext: patch.userContext?.trim() ?? current.userContext?.trim() ?? llmContext,
+    };
+}
 function matchesQuery(credential, query) {
     if (!query) {
         return true;
@@ -13,6 +30,8 @@ function matchesQuery(credential, query) {
         credential.displayName,
         credential.service,
         credential.owner,
+        credential.userContext ?? "",
+        credential.llmContext ?? "",
         credential.selectionNotes,
         ...credential.tags,
     ]
@@ -56,13 +75,19 @@ export class JsonCredentialRepository {
     }
     async create(record) {
         const parsed = createCredentialInputSchema.parse(record);
+        const normalized = {
+            ...parsed,
+            userContext: normalizedUserContext(parsed),
+            llmContext: normalizedLlmContext(parsed),
+            selectionNotes: normalizedLlmContext(parsed),
+        };
         const catalog = await this.readCatalog();
-        if (catalog.credentials.some((credential) => credential.id === parsed.id)) {
-            throw new Error(`Credential ${parsed.id} already exists.`);
+        if (catalog.credentials.some((credential) => credential.id === normalized.id)) {
+            throw new Error(`Credential ${normalized.id} already exists.`);
         }
-        catalog.credentials.push(parsed);
+        catalog.credentials.push(normalized);
         await this.writeCatalog(catalog);
-        return parsed;
+        return normalized;
     }
     async createWithDefaults(record) {
         return this.create({
@@ -77,14 +102,19 @@ export class JsonCredentialRepository {
         if (index === -1) {
             throw new Error(`Credential ${id} was not found.`);
         }
+        const current = catalog.credentials[index];
         const merged = createCredentialInputSchema.parse({
-            ...catalog.credentials[index],
+            ...current,
             ...parsedPatch,
             id,
         });
-        catalog.credentials[index] = merged;
+        const normalized = {
+            ...merged,
+            ...normalizedUpdateContexts(current, parsedPatch),
+        };
+        catalog.credentials[index] = normalized;
         await this.writeCatalog(catalog);
-        return merged;
+        return normalized;
     }
     async delete(id) {
         const catalog = await this.readCatalog();

package/dist/repositories/pg-credential-repository.js

@@ -1,5 +1,7 @@
 import { createCredentialInputSchema, credentialRecordSchema, updateCredentialInputSchema, } from "../domain/types.js";
 function mapRow(row) {
+    const llmContext = row.llm_context?.trim() || row.selection_notes;
+    const userContext = row.user_context?.trim() || llmContext;
     return credentialRecordSchema.parse({
         id: row.id,
         tenantId: row.tenant_id,
@@ -15,7 +17,9 @@ function mapRow(row) {
         lastValidatedAt: row.last_validated_at instanceof Date
             ? row.last_validated_at.toISOString()
             : row.last_validated_at,
-        selectionNotes: row.selection_notes,
+        selectionNotes: llmContext,
+        userContext,
+        llmContext,
         binding: row.binding,
         tags: row.tags,
         status: row.status,
@@ -31,7 +35,7 @@ function makeSearchClauses(input) {
     if (input.query) {
         params.push(input.query);
         const placeholder = `$${params.length}`;
-        conditions.push(`(id ILIKE '%' || ${placeholder} || '%' OR display_name ILIKE '%' || ${placeholder} || '%' OR service ILIKE '%' || ${placeholder} || '%' OR owner ILIKE '%' || ${placeholder} || '%' OR selection_notes ILIKE '%' || ${placeholder} || '%')`);
+        conditions.push(`(id ILIKE '%' || ${placeholder} || '%' OR display_name ILIKE '%' || ${placeholder} || '%' OR service ILIKE '%' || ${placeholder} || '%' OR owner ILIKE '%' || ${placeholder} || '%' OR selection_notes ILIKE '%' || ${placeholder} || '%' OR COALESCE(user_context, '') ILIKE '%' || ${placeholder} || '%' OR COALESCE(llm_context, '') ILIKE '%' || ${placeholder} || '%')`);
     }
     if (input.service) {
         push("service = $?", input.service);
@@ -54,6 +58,23 @@ function makeSearchClauses(input) {
     const clause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
     return { clause, params };
 }
+function normalizedCreateContexts(record) {
+    const llmContext = record.llmContext?.trim() || record.selectionNotes;
+    return {
+        llmContext,
+        userContext: record.userContext?.trim() || llmContext,
+    };
+}
+function normalizedUpdateContexts(current, patch) {
+    const llmContext = patch.llmContext?.trim() ??
+        patch.selectionNotes?.trim() ??
+        current.llmContext?.trim() ??
+        current.selectionNotes;
+    return {
+        llmContext,
+        userContext: patch.userContext?.trim() ?? current.userContext?.trim() ?? llmContext,
+    };
+}
 export class PgCredentialRepository {
     database;
     constructor(database) {
@@ -82,14 +103,15 @@ export class PgCredentialRepository {
     }
     async create(record) {
         const parsed = createCredentialInputSchema.parse(record);
+        const { llmContext, userContext } = normalizedCreateContexts(parsed);
         await this.database.query(`INSERT INTO credentials (
         id, tenant_id, display_name, service, owner, scope_tier, sensitivity,
         allowed_domains, permitted_operations, expires_at, rotation_policy,
-        last_validated_at, selection_notes, binding, tags, status
+        last_validated_at, selection_notes, user_context, llm_context, binding, tags, status
       ) VALUES (
         $1, $2, $3, $4, $5, $6, $7,
         $8, $9, $10, $11,
-        $12, $13, $14::jsonb, $15, $16
+        $12, $13, $14, $15, $16::jsonb, $17, $18
       )`, [
             parsed.id,
             parsed.tenantId,
@@ -103,12 +125,19 @@ export class PgCredentialRepository {
             parsed.expiresAt,
             parsed.rotationPolicy,
             parsed.lastValidatedAt,
-            parsed.selectionNotes,
+            llmContext,
+            userContext,
+            llmContext,
             JSON.stringify(parsed.binding),
             parsed.tags,
             parsed.status,
         ]);
-        return parsed;
+        return credentialRecordSchema.parse({
+            ...parsed,
+            selectionNotes: llmContext,
+            userContext,
+            llmContext,
+        });
     }
     async update(id, patch) {
         const parsedPatch = updateCredentialInputSchema.parse(patch);
@@ -121,6 +150,7 @@ export class PgCredentialRepository {
             ...parsedPatch,
             id,
         });
+        const { llmContext, userContext } = normalizedUpdateContexts(current, parsedPatch);
         await this.database.query(`UPDATE credentials SET
         display_name = $2,
         service = $3,
@@ -133,9 +163,11 @@ export class PgCredentialRepository {
         rotation_policy = $10,
         last_validated_at = $11,
         selection_notes = $12,
-        binding = $13::jsonb,
-        tags = $14,
-        status = $15,
+        user_context = $13,
+        llm_context = $14,
+        binding = $15::jsonb,
+        tags = $16,
+        status = $17,
         updated_at = NOW()
       WHERE id = $1`, [
             merged.id,
@@ -149,12 +181,19 @@ export class PgCredentialRepository {
             merged.expiresAt,
             merged.rotationPolicy,
             merged.lastValidatedAt,
-            merged.selectionNotes,
+            llmContext,
+            userContext,
+            llmContext,
             JSON.stringify(merged.binding),
             merged.tags,
             merged.status,
         ]);
-        return merged;
+        return credentialRecordSchema.parse({
+            ...merged,
+            selectionNotes: llmContext,
+            userContext,
+            llmContext,
+        });
     }
     async delete(id) {
         const result = await this.database.query("DELETE FROM credentials WHERE id = $1", [id]);

package/dist/services/backup-service.js

@@ -154,7 +154,9 @@ export class BackupService {
                 expiresAt: toIso(row.expires_at),
                 rotationPolicy: row.rotation_policy,
                 lastValidatedAt: toIso(row.last_validated_at),
-                selectionNotes: row.selection_notes,
+                selectionNotes: row.llm_context?.trim() || row.selection_notes,
+                userContext: row.user_context?.trim() || row.llm_context?.trim() || row.selection_notes,
+                llmContext: row.llm_context?.trim() || row.selection_notes,
                 binding: row.binding,
                 tags: row.tags,
                 status: row.status,
@@ -362,14 +364,16 @@ export class BackupService {
                 ]);
             }
             for (const credential of backup.credentials) {
+                const llmContext = credential.llmContext?.trim() || credential.selectionNotes;
+                const userContext = credential.userContext?.trim() || llmContext;
                 await client.query(`INSERT INTO credentials (
              id, tenant_id, display_name, service, owner, scope_tier, sensitivity,
              allowed_domains, permitted_operations, expires_at, rotation_policy,
-             last_validated_at, selection_notes, binding, tags, status
+             last_validated_at, selection_notes, user_context, llm_context, binding, tags, status
            ) VALUES (
              $1, $2, $3, $4, $5, $6, $7,
              $8, $9, $10, $11,
-             $12, $13, $14, $15, $16
+             $12, $13, $14, $15, $16, $17, $18
            )`, [
                     credential.id,
                     credential.tenantId,
@@ -383,7 +387,9 @@ export class BackupService {
                     credential.expiresAt,
                     credential.rotationPolicy,
                     credential.lastValidatedAt,
-                    credential.selectionNotes,
+                    llmContext,
+                    userContext,
+                    llmContext,
                     credential.binding,
                     credential.tags,
                     credential.status,

package/dist/services/core-mode-service.js

@@ -99,7 +99,12 @@ export class CoreModeService {
             expiresAt: parsed.expiresAt,
             rotationPolicy: parsed.rotationPolicy,
             lastValidatedAt: null,
-            selectionNotes: parsed.selectionNotes,
+            selectionNotes: parsed.llmContext?.trim() || parsed.selectionNotes?.trim() || "",
+            userContext: parsed.userContext?.trim() ||
+                parsed.llmContext?.trim() ||
+                parsed.selectionNotes?.trim() ||
+                "",
+            llmContext: parsed.llmContext?.trim() || parsed.selectionNotes?.trim() || "",
             binding,
             tags: parsed.tags,
             status: parsed.status,
@@ -138,6 +143,17 @@ export class CoreModeService {
         await this.syncCoreAllowRule(updated);
         return updated;
     }
+    async replaceLocalSecret(context, credentialId, secretValue) {
+        const existing = await this.broker.getCredential(context, credentialId);
+        if (!existing) {
+            throw new Error(`Credential ${credentialId} not found.`);
+        }
+        if (existing.owner !== "local") {
+            throw new Error("Only locally stored tokens can be replaced through the admin UI.");
+        }
+        await this.localSecrets.put(`local:${existing.tenantId}:${existing.id}`, secretValue);
+        return existing;
+    }
     async deleteCredential(context, credentialId) {
         const existing = await this.broker.getCredential(context, credentialId);
         if (!existing) {

package/migrations/009_v1_context_split.sql

@@ -0,0 +1,30 @@
+ALTER TABLE credentials
+  ADD COLUMN IF NOT EXISTS user_context TEXT;
+
+ALTER TABLE credentials
+  ADD COLUMN IF NOT EXISTS llm_context TEXT;
+
+UPDATE credentials
+SET
+  llm_context = CASE
+    WHEN llm_context IS NULL OR llm_context = '' THEN selection_notes
+    ELSE llm_context
+  END,
+  user_context = CASE
+    WHEN user_context IS NULL OR user_context = '' THEN
+      CASE
+        WHEN llm_context IS NULL OR llm_context = '' THEN selection_notes
+        ELSE llm_context
+      END
+    ELSE user_context
+  END
+WHERE llm_context IS NULL
+   OR llm_context = ''
+   OR user_context IS NULL
+   OR user_context = '';
+
+ALTER TABLE credentials
+  ALTER COLUMN llm_context SET NOT NULL;
+
+ALTER TABLE credentials
+  ALTER COLUMN user_context SET NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simonsbs/keylore",
-  "version": "1.0.0-rc5",
+  "version": "1.0.0",
   "description": "MCP credential broker and searchable credential catalogue for LLM coding tools.",
   "type": "module",
   "main": "dist/index.js",