@agentvalet/mcp-server 1.15.0 → 1.17.0

package/dist/index.js

@@ -180,6 +180,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             scope: args.scope,
             data: bodyArg,
             ...(typeof args.connection_id === "string" ? { connection_id: args.connection_id } : {}),
+            ...(args.caller && typeof args.caller === "object" ? { caller: args.caller } : {}),
             ...(typeof args.reason === "string" ? { reason: args.reason } : {}),
         }, progressToken);
     }
@@ -213,6 +214,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             // No `data` alias on the new tools: new surface, no legacy.
             ...(args.body !== undefined ? { data: args.body } : {}),
             ...(typeof args.connection_id === "string" ? { connection_id: args.connection_id } : {}),
+            ...(args.caller && typeof args.caller === "object" ? { caller: args.caller } : {}),
             ...(typeof args.reason === "string" ? { reason: args.reason } : {}),
         }, progressToken);
     }

package/dist/registration-keys.js

@@ -0,0 +1,88 @@
+// apps/mcp-server/src/registration-keys.ts
+//
+// Local key custody for the agent_register -> owner approval -> agent_status
+// flow (Claude Desktop / MCPB self-registration).
+//
+// agent_register generates the RSA keypair HERE and sends only the public key
+// (POST /v1/register public_key_pem). The private key waits on disk, keyed by
+// the registration token, until agent_status sees the approval and installs it
+// as the agent's key. The private key never leaves this machine, never reaches
+// the dashboard, and is never put in a tool result the model can see.
+//
+// Layout (under ~/.agentvalet, dir 0700, key files 0600):
+//   pending/<registration_token>.key   private key awaiting approval
+//   agents/<agent_id>.key              installed key for an approved agent
+//   agent.key + agent.json             the DEFAULT identity config.ts boots
+//                                      from — written ONLY when neither file
+//                                      exists, so a registration never clobbers
+//                                      an identity another agent already owns
+//                                      (see invariant_register_clobbers_existing_agent_key).
+import { generateKeyPairSync } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentvaletDir, getIdentityPath, getKeyPath, persistBindArtifacts } from "./bind.js";
+const SAFE_SEGMENT = /^[A-Za-z0-9_-]{1,128}$/;
+export function generateRegistrationKeypair() {
+    return generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+}
+function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+export function pendingKeyPath(token) {
+    if (!SAFE_SEGMENT.test(token))
+        return null;
+    return join(getAgentvaletDir(), "pending", `${token}.key`);
+}
+export function savePendingKey(token, privateKeyPem) {
+    const path = pendingKeyPath(token);
+    if (!path)
+        throw new Error("Unexpected registration token format; refusing to use it as a file name");
+    ensureDir(join(getAgentvaletDir(), "pending"));
+    writeFileSync(path, privateKeyPem, { mode: 0o600 });
+    return path;
+}
+export function readPendingKey(token) {
+    const path = pendingKeyPath(token);
+    if (!path || !existsSync(path))
+        return null;
+    try {
+        return readFileSync(path, "utf-8").trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function deletePendingKey(token) {
+    const path = pendingKeyPath(token);
+    if (path)
+        rmSync(path, { force: true });
+}
+/**
+ * Installs an approved agent's private key. Always writes
+ * agents/<agent_id>.key; additionally writes the default agent.key +
+ * agent.json when (and only when) no default identity exists yet, so the next
+ * server start picks it up with no env vars at all.
+ */
+export function installAgentKey(opts) {
+    if (!SAFE_SEGMENT.test(opts.agentId)) {
+        throw new Error("Unexpected agent_id format; refusing to use it as a file name");
+    }
+    const agentsDir = join(getAgentvaletDir(), "agents");
+    ensureDir(agentsDir);
+    const keyPath = join(agentsDir, `${opts.agentId}.key`);
+    writeFileSync(keyPath, opts.privateKeyPem, { mode: 0o600 });
+    const defaultTaken = existsSync(getKeyPath()) || existsSync(getIdentityPath());
+    if (!defaultTaken) {
+        persistBindArtifacts({
+            agent_id: opts.agentId,
+            owner_id: opts.ownerId,
+            proxy_url: opts.proxyUrl,
+            bound_at: new Date().toISOString(),
+        }, opts.privateKeyPem);
+    }
+    return { keyPath, becameDefault: !defaultTaken };
+}

package/dist/tools/handlers.js

@@ -8,6 +8,8 @@ import { errorContent, jsonContent, tryParseJson, safeJsonParse, sleep, diagnose
 import { requireCredentials, fetchWithAuth } from "../auth.js";
 import { recordPermissionsVersion } from "../permissions-watcher.js";
 import { parseConsentRefusal, elicitConsent, consentFallbackText, connectUrlFor } from "./consent.js";
+import { importPKCS8 } from "jose";
+import { generateRegistrationKeypair, savePendingKey, readPendingKey, deletePendingKey, installAgentKey, } from "../registration-keys.js";
 export async function handleListPlatforms(ctx) {
     const gate = await requireCredentials(ctx);
     if (gate)
@@ -99,6 +101,7 @@ consentRetried = false) {
         scope: params.scope,
         ...(params.data !== undefined && { data: params.data }),
         ...(params.connection_id ? { connection_id: params.connection_id } : {}),
+        ...(params.caller ? { caller: params.caller } : {}),
         // Agent-supplied justification. Forwarded verbatim; the proxy normalizes
         // and caps it before it reaches the approver's screen.
         ...(params.reason ? { reason: params.reason } : {}),
@@ -249,13 +252,34 @@ async function sendProgress(ctx, token, progress, total, message) {
         // Best-effort — never let a failed notification break the call.
     }
 }
+// Unwraps the proxy's { data, _meta } envelope when present.
+function unwrapData(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    if (obj.data && typeof obj.data === "object")
+        return obj.data;
+    return obj;
+}
+function structured(result) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent: result,
+    };
+}
+// agent_register: the keypair is generated HERE and only the public key is
+// sent, so the private key never leaves this machine (and never transits the
+// owner's dashboard). It waits on disk until agent_status sees the approval.
 export async function handleAgentRegister(ctx, args) {
+    const { publicKey, privateKey } = generateRegistrationKeypair();
     let response;
     try {
         response = await fetchWithTimeout(`${ctx.PROXY_URL}/v1/register`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(args),
+            // public_key_pem last so a model-supplied value can never override it —
+            // we would not hold the matching private key.
+            body: JSON.stringify({ ...args, public_key_pem: publicKey }),
         });
     }
     catch (err) {
@@ -264,7 +288,65 @@ export async function handleAgentRegister(ctx, args) {
     const body = await response.text();
     if (!response.ok)
         return errorContent(`Proxy error ${response.status}: ${body}`);
-    return jsonContent(body);
+    const data = unwrapData(tryParseJson(body));
+    const token = typeof data?.registration_token === "string" ? data.registration_token : null;
+    if (!data || !token)
+        return jsonContent(body);
+    // Only keep the private key if the proxy actually bound our public key. An
+    // older proxy ignores public_key_pem and issues its own keypair; agent_status
+    // then collects that one via claim-key instead.
+    let keyStoredLocally = false;
+    if (data.keypair_source === "client") {
+        try {
+            savePendingKey(token, privateKey);
+            keyStoredLocally = true;
+        }
+        catch (err) {
+            return errorContent(`Registration ${token} was submitted, but the private key could not be saved locally ` +
+                `(${err instanceof Error ? err.message : err}). Ask the owner to reject it and register again.`);
+        }
+    }
+    return structured({
+        ...data,
+        key_stored_locally: keyStoredLocally,
+        next_step: "Ask the owner to approve this agent in the AgentValet dashboard, then call agent_status with the registration_token. " +
+            "The private key stays on this machine; agent_status installs it once approved.",
+    });
+}
+async function claimServerIssuedKey(ctx, token) {
+    try {
+        const res = await fetchWithTimeout(`${ctx.PROXY_URL}/v1/register/claim-key/${encodeURIComponent(token)}`, {
+            method: "GET",
+            headers: { "Content-Type": "application/json" },
+        });
+        if (!res.ok)
+            return null;
+        const json = (await res.json());
+        return typeof json.private_key === "string" && json.private_key.includes("PRIVATE KEY")
+            ? json.private_key
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+// If this server booted with no usable key (state B/C), adopt the newly
+// approved identity in-process so platform tools work without a restart.
+async function activateInProcess(ctx, agentId, ownerId, pem) {
+    if (ctx.AGENT_PRIVATE_KEY_RAW !== null)
+        return false;
+    if (ctx.AGENT_ID && ctx.AGENT_ID !== agentId)
+        return false;
+    try {
+        ctx.privateKey = await importPKCS8(pem, "RS256");
+    }
+    catch {
+        return false;
+    }
+    ctx.AGENT_ID = agentId;
+    ctx.OWNER_ID = ownerId;
+    ctx.AGENT_PRIVATE_KEY_RAW = pem;
+    return true;
 }
 export async function handleAgentStatus(ctx, token) {
     let response;
@@ -280,7 +362,76 @@ export async function handleAgentStatus(ctx, token) {
     const body = await response.text();
     if (!response.ok)
         return errorContent(`Proxy error ${response.status}: ${body}`);
-    return jsonContent(body);
+    const data = unwrapData(tryParseJson(body));
+    if (!data || typeof data.status !== "string")
+        return jsonContent(body);
+    if (data.status === "rejected" || data.status === "expired") {
+        deletePendingKey(token);
+        return structured(data);
+    }
+    if (data.status !== "approved")
+        return structured(data);
+    const agentId = typeof data.agent_id === "string" ? data.agent_id : "";
+    const mcpEnv = (data.mcp_config
+        ?.mcpServers?.agentvalet?.env) ?? {};
+    const ownerId = typeof data.owner_id === "string" ? data.owner_id : (mcpEnv.OWNER_ID ?? "");
+    // Locate the private key: our own (client keypair) or, for a legacy
+    // server-issued keypair, the one-time claim-key pickup.
+    let pem = null;
+    let source = null;
+    if (data.keypair_source === "client") {
+        pem = readPendingKey(token);
+        source = "client";
+    }
+    else {
+        pem = await claimServerIssuedKey(ctx, token);
+        source = "server";
+    }
+    const result = {
+        status: "approved",
+        agent_id: agentId,
+        owner_id: ownerId,
+        keypair_source: source,
+    };
+    if (!pem || !agentId || !ownerId) {
+        result.key_installed = false;
+        result.next_step =
+            source === "client"
+                ? "Approved, but this machine does not hold the private key for this registration (it was generated by a different install, or already installed). " +
+                    "Check ~/.agentvalet/agents/, or register again from this machine."
+                : "Approved, but the one-time private key could not be collected (already claimed, or the 5-minute window after approval has passed). " +
+                    "Register again from this machine so the key is generated locally.";
+        return structured(result);
+    }
+    let installed;
+    try {
+        installed = installAgentKey({ agentId, ownerId, proxyUrl: ctx.PROXY_URL, privateKeyPem: pem });
+    }
+    catch (err) {
+        return errorContent(`Approved as ${agentId}, but the private key could not be saved: ${err instanceof Error ? err.message : err}`);
+    }
+    deletePendingKey(token);
+    const activated = await activateInProcess(ctx, agentId, ownerId, pem);
+    result.key_installed = true;
+    result.key_path = installed.keyPath;
+    result.default_identity = installed.becameDefault;
+    result.activated = activated;
+    // The config to use this agent elsewhere: a key PATH, never the key itself.
+    result.mcp_config = {
+        mcpServers: {
+            agentvalet: {
+                command: "npx",
+                args: ["-y", "@agentvalet/mcp-server"],
+                env: { AGENT_ID: agentId, OWNER_ID: ownerId, PROXY_URL: ctx.PROXY_URL, AGENT_PRIVATE_KEY_PATH: installed.keyPath },
+            },
+        },
+    };
+    result.next_step = activated
+        ? "Registered and active in this session. Call list_platforms to see what the owner granted."
+        : installed.becameDefault
+            ? "Registered. The key is installed as this machine's default AgentValet identity; restart the MCP server (or Claude Desktop) to use it."
+            : "Registered. Another AgentValet identity is already configured on this machine, so it was left untouched; use the mcp_config above (AGENT_PRIVATE_KEY_PATH) to run this agent.";
+    return structured(result);
 }
 export async function handleAuthzenEvaluate(ctx, platformId, scope) {
     const gate = await requireCredentials(ctx);

package/dist/tools/schemas.js

@@ -98,6 +98,11 @@ export const USE_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected (e.g. two GitHub orgs). Value is the connection id shown in the dashboard. Omit to use the default connection.",
             },
+            caller: {
+                type: "object",
+                description: "Optional. Who the human is that this call is for, when this agent serves many people: { assertion: '<JWT from an identity provider the org registered>' } (verified) or { source, id } (asserted; honoured only where the platform allows it). On a platform with per-person tokens, the person's own upstream token is used; if they have not authorized yet the call returns consent_required with a consent_url to give them.",
+                properties: { assertion: { type: "string" }, source: { type: "string" }, id: { type: "string" } },
+            },
             reason: {
                 type: "string",
                 description: "Optional but strongly encouraged. One sentence on WHY you are making this call. If the action requires owner approval, this is shown to the human who decides — without it their approval is a blind yes/no. Max 500 characters (longer is truncated). Plain text; markup is not rendered.",
@@ -125,6 +130,11 @@ export const READ_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected. Omit to use the default.",
             },
+            caller: {
+                type: "object",
+                description: "Optional. Who the human is that this call is for, when this agent serves many people: { assertion: '<JWT from an identity provider the org registered>' } (verified) or { source, id } (asserted; honoured only where the platform allows it). On a platform with per-person tokens, the person's own upstream token is used; if they have not authorized yet the call returns consent_required with a consent_url to give them.",
+                properties: { assertion: { type: "string" }, source: { type: "string" }, id: { type: "string" } },
+            },
             reason: {
                 type: "string",
                 description: "Optional but strongly encouraged. One sentence on WHY you are making this call. Shown to the human approver if the call is gated. Max 500 characters; plain text.",
@@ -156,6 +166,11 @@ export const WRITE_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected. Omit to use the default.",
             },
+            caller: {
+                type: "object",
+                description: "Optional. Who the human is that this call is for, when this agent serves many people: { assertion: '<JWT from an identity provider the org registered>' } (verified) or { source, id } (asserted; honoured only where the platform allows it). On a platform with per-person tokens, the person's own upstream token is used; if they have not authorized yet the call returns consent_required with a consent_url to give them.",
+                properties: { assertion: { type: "string" }, source: { type: "string" }, id: { type: "string" } },
+            },
             reason: {
                 type: "string",
                 description: "Optional but strongly encouraged. One sentence on WHY you are making this call. Shown to the human approver if the call is gated. Max 500 characters; plain text.",
@@ -181,6 +196,11 @@ export const DELETE_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected. Omit to use the default.",
             },
+            caller: {
+                type: "object",
+                description: "Optional. Who the human is that this call is for, when this agent serves many people: { assertion: '<JWT from an identity provider the org registered>' } (verified) or { source, id } (asserted; honoured only where the platform allows it). On a platform with per-person tokens, the person's own upstream token is used; if they have not authorized yet the call returns consent_required with a consent_url to give them.",
+                properties: { assertion: { type: "string" }, source: { type: "string" }, id: { type: "string" } },
+            },
             reason: {
                 type: "string",
                 description: "Optional but strongly encouraged. One sentence on WHY you are deleting this. Shown to the human approver if the call is gated. Max 500 characters; plain text.",
@@ -191,7 +211,7 @@ export const DELETE_PLATFORM_TOOL = {
 };
 export const AGENT_REGISTER_TOOL = {
     name: "agent_register",
-    description: "agent_register: Self-register this agent with an owner. No auth required.\nInput: owner_id (string), agent_name (string), requested_scopes (array of {platformId, scopes}).\nReturns: registration_token, poll_url, client_id, scope, expires_in.\nAuth: None.",
+    description: "agent_register: Self-register this agent with an owner. No auth required.\nInput: owner_id (string), agent_name (string), requested_scopes (array of {platformId, scopes}).\nThe agent's RSA keypair is generated on this machine; only the public key is sent and the private key stays here.\nReturns: registration_token, poll_url, client_id, scope, keypair_source, key_stored_locally.\nNext: once the owner approves in the dashboard, call agent_status with the registration_token to install the key.\nAuth: None.",
     inputSchema: {
         type: "object",
         properties: {
@@ -226,13 +246,15 @@ export const AGENT_REGISTER_TOOL = {
             client_id: { type: "string" },
             scope: { type: "string" },
             expires_in: { type: "number" },
+            keypair_source: { type: "string", enum: ["client", "server"] },
+            key_stored_locally: { type: "boolean" },
         },
         required: ["registration_token"],
     },
 };
 export const AGENT_STATUS_TOOL = {
     name: "agent_status",
-    description: "agent_status: Poll registration status using the token from agent_register.\nInput: token (string, required).\nReturns: status (\"pending_approval\"|\"approved\"|\"rejected\"), agent_id (if approved), mcp_config (if approved).\nAuth: None.",
+    description: "agent_status: Poll registration status using the token from agent_register.\nInput: token (string, required).\nOn approval it installs the agent's private key on this machine (~/.agentvalet/agents/<agent_id>.key, plus the default identity if none exists) and activates it for this session when the server had no identity yet. The private key is never returned in the result.\nReturns: status (\"pending\"|\"approved\"|\"rejected\"|\"expired\"), agent_id, key_installed, key_path, activated, mcp_config (if approved).\nAuth: None.",
     inputSchema: {
         type: "object",
         properties: {
@@ -246,8 +268,11 @@ export const AGENT_STATUS_TOOL = {
     outputSchema: {
         type: "object",
         properties: {
-            status: { type: "string", enum: ["pending_approval", "approved", "rejected"] },
+            status: { type: "string", enum: ["pending", "pending_approval", "approved", "rejected", "expired"] },
             agent_id: { type: "string" },
+            key_installed: { type: "boolean" },
+            key_path: { type: "string" },
+            activated: { type: "boolean" },
             mcp_config: { type: "object" },
         },
         required: ["status"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvalet/mcp-server",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "AgentValet MCP server — lets AI agents call approved platforms via the AgentValet proxy",
   "mcpName": "io.github.agentvalet/mcp-server",
   "type": "module",