frinus-mcp 3.1.0 → 3.2.0

package/README.md

@@ -307,6 +307,47 @@ Reusable behaviours assigned to agents.
 | `skill_remove` | Detach a skill from an agent. |
 | `skill_agent_list` | List the skills owned by a given agent. |
 
+### Credential Vault (5) — `credential_exec` broker
+
+Encrypted credentials stored in the Control Plane, referenced from memories via
+`credential_ref`.
+
+| Tool | Description |
+|------|-------------|
+| `credential_store` | Store an encrypted credential under a ref (e.g. `mysql_x`). |
+| `credential_get` | Inspect **non-secret metadata only** (host/user/db/port + the env vars `credential_exec` will inject). Never returns the value. |
+| `credential_exec` | **Run a command with the credential injected into the child process ENV.** Returns only stdout/stderr/exit_code — the secret never reaches the model, screen, or disk. |
+| `credential_list` | List stored credential refs (no secret data). |
+| `credential_delete` | Delete a stored credential. |
+
+**Secret-handling principle — server-side broker, never by value.** The model
+never receives a secret value: no plaintext, no temp files, no shell snippets that
+carry the secret. To *use* a credential you call **`credential_exec`**. The MCP
+server (already running locally via `npx -y frinus-mcp@latest`) fetches the
+credential from the vault, injects its fields into the **environment** of a child
+process — never into argv, never into any text the model sees — runs the command
+with `shell:false` (no shell injection), and returns only the output.
+
+```jsonc
+// MYSQL_PWD / MYSQL_USER / MYSQL_HOST are pre-injected → standard clients just work
+credential_exec(ref="mysql_prod", argv=["mysql", "-e", "SELECT 1"])
+credential_exec(ref="pg_prod",    argv=["psql",  "-c", "SELECT 1"])
+
+// For anything else, read the injected vars inside an explicit shell:
+credential_exec(ref="jira_x", argv=["sh","-c",
+  "curl -sS -H \"Authorization: Bearer $CRED_TOKEN\" \"$CRED_BASE_URL/whoami\""])
+```
+
+Injected env vars (when present in the credential): password/secret/token →
+`MYSQL_PWD`, `PGPASSWORD`, `CRED_PASSWORD`; `user`/`username` → `CRED_USER`,
+`MYSQL_USER`, `PGUSER`; `host` → `CRED_HOST`, `MYSQL_HOST`, `PGHOST`; `port` →
+`CRED_PORT`, `MYSQL_TCP_PORT`, `PGPORT`; `database` → `CRED_DATABASE`,
+`PGDATABASE`; any other scalar → `CRED_<UPPER_SNAKE>` (e.g. `base_url` →
+`CRED_BASE_URL`). `argv` must be an array of strings (no shell command string;
+use `["sh","-c","..."]` if you really need a shell). 30s timeout, 256 KiB output
+cap. Everything ships in the npm package — **the user installs nothing, edits no
+PATH, and runs no extra command**; an up-to-date MCP is all that's required.
+
 ## Memory Types
 
 | Type | Use Case | Example |

package/dist/tools/definitions.js

@@ -1499,24 +1499,84 @@ to link a memory to this credential.`,
     },
     {
         name: "credential_get",
-        description: `Retrieve a decrypted credential from the vault.
+        description: `Inspect a credential's NON-SECRET metadata — never its value.
 
-Returns the decrypted credential data for the given reference.
-Only the credential owner (authenticated user) can access their credentials.
+This tool returns ONLY non-secret metadata (host/user/db/port), the names of the
+secret fields, and the names of the environment variables that 'credential_exec'
+will inject. The secret VALUE is NEVER returned, so it can never be echoed inline
+into a shell command and leaked on a screen share.
 
-Use this when a memory has a credential_ref and you need the actual
-credentials to perform an action (e.g., connect to a database, call an API).`,
+To actually USE the credential (connect to a DB, call an API), do NOT request the
+value — call 'credential_exec'. It fetches the secret on the server side, injects
+it into the child process environment, runs your command, and returns only the
+output. The secret never reaches you, the screen, or disk.
+
+Only the credential owner (authenticated API key) can access their credentials.`,
         inputSchema: {
             type: "object",
             properties: {
                 ref: {
                     type: "string",
-                    description: "Credential reference to retrieve (e.g., 'jira_muza')",
+                    description: "Credential reference to inspect (e.g., 'jira_muza')",
                 },
             },
             required: ["ref"],
         },
     },
+    {
+        name: "credential_exec",
+        description: `Run a command with a vault credential injected into its environment — the secret NEVER reaches you.
+
+This is the secure way to USE a stored credential. The MCP server (running locally
+via npx) fetches the credential from the vault, injects its fields into the
+ENVIRONMENT of a child process (never into argv, never into any text you see),
+runs your command with shell:false (no shell injection), and returns ONLY
+stdout, stderr, and exit_code. The secret value is never returned to you, never
+printed on screen, never logged, and never written to disk.
+
+Injected environment variables (when present in the credential):
+  - password/secret/token field -> MYSQL_PWD, PGPASSWORD, CRED_PASSWORD
+  - user / username             -> CRED_USER, MYSQL_USER, PGUSER
+  - host / hostname             -> CRED_HOST, MYSQL_HOST, PGHOST
+  - port                        -> CRED_PORT, MYSQL_TCP_PORT, PGPORT
+  - database / db / dbname      -> CRED_DATABASE, PGDATABASE
+  - any other scalar field      -> CRED_<UPPER_SNAKE_NAME> (e.g. base_url -> CRED_BASE_URL)
+
+Because MYSQL_PWD / PGPASSWORD etc. are standard, common clients pick them up
+with no flags:
+  credential_exec(ref="mysql_prod", argv=["mysql", "-e", "SELECT 1"])
+  credential_exec(ref="pg_prod",    argv=["psql", "-c", "SELECT 1"])
+
+For anything else, read the injected vars inside an explicit shell — the secret
+is expanded inside the child, never in text you author:
+  credential_exec(ref="jira_x", argv=["sh", "-c",
+    "curl -sS -H \\"Authorization: Bearer $CRED_TOKEN\\" \\"$CRED_BASE_URL/whoami\\""])
+
+RULES:
+  - 'argv' MUST be an array of strings (program first, then args). A shell command
+    string is NOT accepted; pass ["sh","-c","..."] only when you genuinely need a shell.
+  - NEVER put a secret value in argv or ask for the value — there is no path to it.
+  - 30s timeout; output capped at 256 KiB per stream.`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                ref: {
+                    type: "string",
+                    description: "Credential reference to use (e.g., 'mysql_centerpag', 'jira_muza').",
+                },
+                argv: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Command as an array: program first, then each argument as a separate string. E.g. [\"mysql\", \"-e\", \"SELECT 1\"]. NOT a shell string.",
+                },
+                stdin: {
+                    type: "string",
+                    description: "Optional data to pipe to the command's stdin (e.g. a SQL script).",
+                },
+            },
+            required: ["ref", "argv"],
+        },
+    },
     {
         name: "credential_list",
         description: `List all stored credentials for the current user.

package/dist/tools/handlers.js

@@ -5,8 +5,166 @@
  * and return formatted MCP tool results.
  */
 import axios from "axios";
+import { spawn } from "node:child_process";
 import { getResolvedTenantOrgId } from "../client/memory-client.js";
 // ---------------------------------------------------------------------------
+// Credential delivery — server-side broker, never by value
+// ---------------------------------------------------------------------------
+// SECURITY: agents running in Claude Code render the full bash command string
+// on screen. If a secret value ever enters the agent's text context, the agent
+// can (and historically did) splice it inline into a command like
+// `export MYSQL_PWD='...'`, leaking it in plaintext during screen sharing.
+//
+// The structural fix is to NEVER return the secret value to the model at all,
+// and — going one step further — to never even require the agent to hold the
+// secret as a shell-side reference. The MCP server already runs locally (via
+// `npx -y frinus-mcp@latest`) and already fetches the credential from the
+// Control Plane vault. So the broker lives INSIDE this process as a native
+// tool: `credential_exec`.
+//
+// `credential_exec` fetches the credential, injects the fields into the ENV of
+// a child process (never into argv, never into the model's text), spawns the
+// command with shell:false, and returns ONLY stdout/stderr/exit_code. The
+// secret never enters the tool result, is never logged, and never touches disk.
+// Everything ships in the npm package — the user installs nothing, edits no
+// PATH, and runs no extra command.
+//
+// `credential_get` no longer surfaces any secret-bearing snippet: it returns
+// non-sensitive metadata only and points the agent at `credential_exec`.
+/** Keys (case-insensitive) treated as sensitive when surfacing metadata. */
+const SECRET_KEY_RE = /pass(word|wd)?|secret|token|api[_-]?key|private[_-]?key|credential/i;
+function looksLikePassword(key) {
+    return SECRET_KEY_RE.test(key);
+}
+// ---------------------------------------------------------------------------
+// credential_exec internals
+// ---------------------------------------------------------------------------
+const CRED_EXEC_TIMEOUT_MS = 30_000;
+const CRED_EXEC_MAX_OUTPUT = 256 * 1024; // 256 KiB cap per stream
+/**
+ * Map credential fields onto environment variables for the child process.
+ * The secret value flows ONLY into this env map — never into argv, never into
+ * any returned/ logged text.
+ *
+ *  - Password-like field  -> MYSQL_PWD, PGPASSWORD, CRED_PASSWORD
+ *  - user/username        -> CRED_USER (+ MYSQL_USER, PGUSER)
+ *  - host/hostname        -> CRED_HOST (+ MYSQL_HOST, PGHOST)
+ *  - port                 -> CRED_PORT (+ MYSQL_TCP_PORT, PGPORT)
+ *  - database/db/dbname   -> CRED_DATABASE (+ PGDATABASE)
+ *  - any other scalar     -> CRED_<UPPER_SNAKE> (e.g. base_url -> CRED_BASE_URL)
+ */
+function buildCredentialEnv(data) {
+    const env = {};
+    const isScalar = (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+    let passwordSet = false;
+    let userSet = false;
+    let hostSet = false;
+    let portSet = false;
+    let dbSet = false;
+    for (const [k, v] of Object.entries(data)) {
+        if (!isScalar(v))
+            continue;
+        const val = String(v);
+        const lk = k.toLowerCase();
+        // Generic CRED_<NAME> for every scalar field (raw key, upper-snaked).
+        const credKey = "CRED_" + k.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+        env[credKey] = val;
+        if (!passwordSet && looksLikePassword(k)) {
+            env.CRED_PASSWORD = val;
+            env.MYSQL_PWD = val;
+            env.PGPASSWORD = val;
+            passwordSet = true;
+        }
+        else if (!userSet && (lk === "user" || lk === "username")) {
+            env.CRED_USER = val;
+            env.MYSQL_USER = val;
+            env.PGUSER = val;
+            userSet = true;
+        }
+        else if (!hostSet && (lk === "host" || lk === "hostname")) {
+            env.CRED_HOST = val;
+            env.MYSQL_HOST = val;
+            env.PGHOST = val;
+            hostSet = true;
+        }
+        else if (!portSet && lk === "port") {
+            env.CRED_PORT = val;
+            env.MYSQL_TCP_PORT = val;
+            env.PGPORT = val;
+            portSet = true;
+        }
+        else if (!dbSet && (lk === "database" || lk === "db" || lk === "dbname")) {
+            env.CRED_DATABASE = val;
+            env.PGDATABASE = val;
+            dbSet = true;
+        }
+    }
+    return env;
+}
+/**
+ * Spawn `argv` (program + args, shell:false) with the credential env injected
+ * on top of a minimal copy of the current env. Captures stdout/stderr with a
+ * size cap and a hard timeout. Never throws on a non-zero exit; throws only on
+ * spawn failure (e.g. command not found).
+ */
+function runWithCredEnv(argv, credEnv, stdin) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(argv[0], argv.slice(1), {
+            shell: false,
+            env: { ...process.env, ...credEnv },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let truncated = false;
+        let timedOut = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, CRED_EXEC_TIMEOUT_MS);
+        const append = (buf, chunk) => {
+            if (buf.length >= CRED_EXEC_MAX_OUTPUT) {
+                truncated = true;
+                return buf;
+            }
+            const next = buf + chunk.toString("utf8");
+            if (next.length > CRED_EXEC_MAX_OUTPUT) {
+                truncated = true;
+                return next.slice(0, CRED_EXEC_MAX_OUTPUT);
+            }
+            return next;
+        };
+        child.stdout.on("data", (c) => { stdout = append(stdout, c); });
+        child.stderr.on("data", (c) => { stderr = append(stderr, c); });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({
+                stdout,
+                stderr,
+                exit_code: code,
+                signal: signal ?? null,
+                timed_out: timedOut,
+                truncated,
+            });
+        });
+        if (typeof stdin === "string") {
+            child.stdin.write(stdin);
+        }
+        child.stdin.end();
+    });
+}
+// ---------------------------------------------------------------------------
 // Helper: 401/403 error handling
 // ---------------------------------------------------------------------------
 export function handleApiError(error) {
@@ -1472,11 +1630,57 @@ const handlers = {
         try {
             const ref = args.ref;
             const result = await cpClient.getCredential(ref);
+            const data = (result ?? {});
+            // SERVER-SIDE BROKER MODEL: we never return any secret value here, and we
+            // no longer emit shell snippets that handle the secret either. We surface
+            // ONLY non-sensitive metadata (host/user/db/port) plus the names of the
+            // secret fields and the env vars they will populate, and we instruct the
+            // agent to run the command through `credential_exec`, which injects the
+            // secret into the child process env on the server side — the value never
+            // reaches the agent, the screen, or disk.
+            const nonSecret = {};
+            const secretFields = [];
+            const credEnvKeys = Object.keys(buildCredentialEnv(data)).sort();
+            for (const [k, v] of Object.entries(data)) {
+                if (typeof v === "object" && v !== null)
+                    continue;
+                if (looksLikePassword(k))
+                    secretFields.push(k);
+                else
+                    nonSecret[k] = v;
+            }
+            const hasUser = "user" in data || "username" in data;
+            const isDbLike = hasUser && secretFields.length > 0;
+            const lines = [];
+            lines.push(`Credential '${ref}' resolved (metadata only — NO secret value is ever returned).`);
+            lines.push("To USE this credential, call the `credential_exec` tool. It fetches the " +
+                "secret on the server side, injects it into the child process environment, " +
+                "runs your command, and returns ONLY stdout/stderr/exit_code. The secret " +
+                "never enters this text, your context, the screen, or disk.");
+            lines.push("");
+            if (Object.keys(nonSecret).length > 0) {
+                lines.push("Non-secret metadata: " + JSON.stringify(nonSecret));
+            }
+            if (secretFields.length > 0) {
+                lines.push(`Secret fields (handled server-side only): ${secretFields.join(", ")}`);
+            }
+            lines.push(`Env vars injected into the child by credential_exec: ${credEnvKeys.join(", ")}`);
+            lines.push("");
+            lines.push("DO NOT request, print, or inline the secret value. Use credential_exec:");
+            lines.push("");
+            if (isDbLike) {
+                lines.push("# MySQL (MYSQL_PWD / MYSQL_USER / MYSQL_HOST are pre-injected):");
+                lines.push(`credential_exec(ref="${ref}", argv=["mysql", "-e", "SELECT 1"])`);
+                lines.push("");
+                lines.push("# Postgres (PGPASSWORD / PGUSER / PGHOST / PGDATABASE are pre-injected):");
+                lines.push(`credential_exec(ref="${ref}", argv=["psql", "-c", "SELECT 1"])`);
+            }
+            else {
+                lines.push("# Read an injected field inside the command (here CRED_API_KEY, etc.):");
+                lines.push(`credential_exec(ref="${ref}", argv=["sh", "-c", "curl -sS -H \\"Authorization: Bearer $CRED_TOKEN\\" \\"$CRED_BASE_URL/whoami\\""])`);
+            }
             return {
-                content: [{
-                        type: "text",
-                        text: JSON.stringify(result, null, 2),
-                    }],
+                content: [{ type: "text", text: lines.join("\n") }],
             };
         }
         catch (error) {
@@ -1494,6 +1698,90 @@ const handlers = {
             throw error;
         }
     },
+    // credential_exec — server-side broker. Runs a command with the credential
+    // injected into the child process ENV. Returns ONLY stdout/stderr/exit_code.
+    // The secret value never enters the returned text and is never logged.
+    async credential_exec(args, { cpClient }) {
+        const ref = args.ref;
+        const argv = args.argv;
+        const stdin = args.stdin;
+        // Validate argv: must be a non-empty array of strings (program + args).
+        // We deliberately do NOT accept a shell command string — spawn runs with
+        // shell:false to avoid shell injection. The caller can still opt into a
+        // shell explicitly with argv ["sh","-c","..."], which is their choice.
+        if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === "string")) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "argv must be a non-empty array of strings (program + args), e.g. [\"mysql\", \"-e\", \"SELECT 1\"]. A shell command string is not accepted (use [\"sh\", \"-c\", \"...\"] if you really need a shell).",
+                    }],
+                isError: true,
+            };
+        }
+        if (stdin !== undefined && typeof stdin !== "string") {
+            return {
+                content: [{ type: "text", text: "stdin, if provided, must be a string." }],
+                isError: true,
+            };
+        }
+        let credData;
+        try {
+            const result = await cpClient.getCredential(ref);
+            credData = (result ?? {});
+        }
+        catch (error) {
+            if (error?.response?.status === 404) {
+                return {
+                    content: [{ type: "text", text: `No credential found for ref '${ref}'` }],
+                    isError: true,
+                };
+            }
+            const apiErr = handleApiError(error);
+            if (apiErr)
+                return apiErr;
+            throw error;
+        }
+        if (Object.keys(credData).length === 0) {
+            return {
+                content: [{ type: "text", text: `Credential '${ref}' has no fields to inject.` }],
+                isError: true,
+            };
+        }
+        const credEnv = buildCredentialEnv(credData);
+        let res;
+        try {
+            res = await runWithCredEnv(argv, credEnv, stdin);
+        }
+        catch (err) {
+            // Spawn failure (e.g. ENOENT command not found). The error message is
+            // about the program/argv, which the caller already provided — no secret.
+            return {
+                content: [{
+                        type: "text",
+                        text: `Failed to execute command: ${err?.code ? err.code + " " : ""}${err?.message ?? String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+        // Return ONLY non-secret execution results. The credential value lived only
+        // in the child's env; it is not part of stdout/stderr unless the invoked
+        // command itself chose to print it (the caller's responsibility).
+        const summary = [
+            `exit_code: ${res.exit_code}`,
+            res.signal ? `signal: ${res.signal}` : null,
+            res.timed_out ? "timed_out: true (killed after 30s)" : null,
+            res.truncated ? "truncated: true (output capped at 256 KiB)" : null,
+            "",
+            "--- stdout ---",
+            res.stdout.length ? res.stdout : "(empty)",
+            "--- stderr ---",
+            res.stderr.length ? res.stderr : "(empty)",
+        ].filter((l) => l !== null).join("\n");
+        return {
+            content: [{ type: "text", text: summary }],
+            isError: res.exit_code !== 0,
+        };
+    },
     async credential_list(_args, { cpClient }) {
         try {
             const result = await cpClient.listCredentials();

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "manifest_version": "0.2",
+  "manifest_version": "0.3",
   "name": "frinus",
   "display_name": "Frinus — Memória Cognitiva",
   "version": "3.1.0",
@@ -12,7 +12,6 @@
   "homepage": "https://frinus.rdxsec.com.br",
   "documentation": "https://github.com/frinus-ai/frinus-mcp",
   "support": "https://github.com/frinus-ai/frinus-mcp/issues",
-  "icon": "icon.png",
   "server": {
     "type": "node",
     "entry_point": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frinus-mcp",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Frinus - MCP Server for Cognitive Memory (φρήν + νοῦς). Long-term memory, sessions, agents and knowledge for Claude and any MCP client.",
   "type": "module",
   "main": "dist/index.js",