@thalovant/mcp-server 0.1.10 → 0.1.11

package/.env.example

@@ -54,6 +54,22 @@ MCP_HTTP_AUTH_TOKEN=
 # deployment where a model drives the tools with a long-lived token.
 # THALOVANT_ENABLE_DESTRUCTIVE_TOOLS=false
 
+# Non-catalog skill sources (e.g. thalovant_install_runtime_group_skill with
+# sourceType "git" and an arbitrary sourceRef) can pull unvetted code into a
+# production runtime. They are refused unless this is explicitly enabled. Leave
+# it unset whenever a model drives the tools with a long-lived token.
+# THALOVANT_ENABLE_GIT_SKILL_SOURCES=false
+
+# Directory that thalovant_create_client_identity may write identity files into.
+# savePath is confined to this directory; absolute paths outside it and ".."
+# traversal are rejected. Defaults to <config-dir>/thalovant/identities.
+# THALOVANT_MCP_IDENTITY_DIR=/var/lib/thalovant-mcp/identities
+
+# Read-only mode: register ONLY tools annotated readOnlyHint:true, so a model
+# cannot mutate control-plane or runtime state. Safer default for observe-only
+# agents than hand-writing a denylist.
+# THALOVANT_MCP_READONLY=false
+
 # Optional policy and audit controls.
 # MCP_TOOL_ALLOWLIST=thalovant_*
 # MCP_TOOL_DENYLIST=thalovant_delete_memory_item

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+### Security
+
+- `thalovant_install_runtime_group_skill` now refuses non-catalog install sources by default. A `sourceType` other than `catalog` (notably `git` with an arbitrary `sourceRef`) can pull unvetted code into a production runtime, and the control-plane validator is format-only with no host allowlist, so it is rejected before any control-plane request unless the operator sets `THALOVANT_ENABLE_GIT_SKILL_SOURCES` (accepting `1`/`true`/`yes`/`on`), mirroring the `THALOVANT_ENABLE_DESTRUCTIVE_TOOLS` gate. `sourceType` is trimmed and case-folded before it is both checked and forwarded, so a variant such as `" Catalog "` or `"CATALOG"` cannot pass the local gate yet reach the control plane — which special-cases only the exact string `"catalog"` — as an unrecognized non-catalog source. The tool is now annotated `destructiveHint: true`, and `thalovant_config_status` reports `gitSkillSourcesEnabled`.
+- `thalovant_create_client_identity` now confines the optional `savePath` to a configurable identity directory (`THALOVANT_MCP_IDENTITY_DIR`, default `<config-dir>/thalovant/identities`). Absolute paths outside the directory and `..` traversal are rejected, and the destination is validated before the identity is created in the control plane, so a model can no longer drop a `0600` credential file into a git working tree or synced folder. `thalovant_config_status` reports `identityDir`.
+- `thalovant_healthcheck` output is now passed through `redactSecrets`, matching every other tool output.
+- `thalovant_get_analytics_overview` no longer advertises the `admin` and (admin-only) `ownerId` arguments to the model, so it no longer teaches an admin mode that only ever 403s for non-admin callers; only the plain overview call remains. Injected `admin`/`ownerId` values are stripped and never reach the control plane.
+- Extended output redaction to additional secret-ish keys: `device_code`, `user_code`, `psk`, `cert`, and `jwt`.
+- Added an opt-in read-only mode (`THALOVANT_MCP_READONLY`): only tools annotated `readOnlyHint: true` are registered, so an observe-only agent needs no hand-written denylist. `thalovant_config_status` reports `readOnly`.
+
 ## 0.1.10
 
 - Added hub-provisioning and skill-discovery tools so an agent can discover skills and provision hubs conversationally, all delegating to `@thalovant/sdk` (now `^0.2.28`).

package/README.md

@@ -353,7 +353,7 @@ Destructive, **not registered unless explicitly enabled** (see [Destructive Tool
 - `thalovant_delete_hub`
 - `thalovant_delete_runtime_group`
 
-Tool outputs redact credential-shaped fields. `thalovant_create_client_identity` does not return secret identity material; pass `savePath` when you want the full identity written to a local file with mode `0600`.
+Tool outputs redact credential-shaped fields. `thalovant_create_client_identity` does not return secret identity material; pass `savePath` when you want the full identity written to a local file with mode `0600`. `savePath` is confined to the server's identity directory (`THALOVANT_MCP_IDENTITY_DIR`, default `<config-dir>/thalovant/identities`): pass a plain filename, since absolute paths outside that directory and `..` traversal are rejected, so a model cannot drop a credential file into a git working tree or synced folder. `thalovant_config_status` reports the active `identityDir`.
 
 ## Destructive Tools
 
@@ -379,6 +379,20 @@ with the trusted principal's credential file granting them back via `allowedTool
 
 Deleting a hub still requires a current etag (`412` otherwise), and deleting a runtime group fails with `409` while it is the workspace default or still has hubs attached.
 
+## Non-Catalog Skill Sources
+
+`thalovant_install_runtime_group_skill` installs from the vetted marketplace catalog by default. Any other source — notably `sourceType: "git"` with an arbitrary `sourceRef` repository URL — pulls code the marketplace never reviewed straight into a production runtime, and the control-plane validator is format-only with no host allowlist. Because the tools are driven by a model holding a long-lived token, non-catalog sources are refused unless an operator opts in:
+
+```bash
+export THALOVANT_ENABLE_GIT_SKILL_SOURCES="true"
+```
+
+With the flag unset, a call with any `sourceType` other than `catalog` fails before any control-plane request is made. Accepted true values are `1`, `true`, `yes`, and `on`. `thalovant_config_status` reports the state as `gitSkillSourcesEnabled`. The tool is annotated `destructiveHint: true`.
+
+## Read-Only Mode
+
+Set `THALOVANT_MCP_READONLY=1` to register only tools annotated `readOnlyHint: true`. Write and destructive tools are then never registered and never appear in `tools/list`, so an operator can run an observe-only agent without hand-writing a denylist. Like the other registration-time gates it is read when a server instance is created; `thalovant_config_status` reports the state as `readOnly`.
+
 ## Development
 
 ```bash

package/dist/index.js

@@ -9,7 +9,8 @@ import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import { realpathSync } from "node:fs";
 import { appendFile, readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
 import { mkdir } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createRemoteJWKSet, jwtVerify } from "jose";
@@ -42,9 +43,16 @@ const SECRET_KEYS = [
     "privateKey",
     "refresh_token",
     "refreshToken",
+    "device_code",
+    "deviceCode",
+    "user_code",
+    "userCode",
     "authToken",
     "authorization",
     "bearer",
+    "jwt",
+    "psk",
+    "cert",
     "token",
     "secret",
 ];
@@ -128,6 +136,38 @@ const DESTRUCTIVE_TOOLS = ["thalovant_delete_hub", "thalovant_delete_runtime_gro
 function destructiveToolsEnabled() {
     return parseBool(process.env.THALOVANT_ENABLE_DESTRUCTIVE_TOOLS, false);
 }
+/**
+ * Non-catalog skill sources are opt-in.
+ *
+ * thalovant_install_runtime_group_skill can install a skill from a source other
+ * than the vetted marketplace catalog — notably `sourceType: "git"` with an
+ * arbitrary `sourceRef` repository URL. The control-plane validator is
+ * format-only with no host allowlist, so any non-catalog source is effectively
+ * an arbitrary-code-into-the-runtime primitive. Because this server hands its
+ * tools to an LLM holding a long-lived token, that primitive is refused by
+ * default and only enabled when an operator opts in with this flag, mirroring
+ * the THALOVANT_ENABLE_DESTRUCTIVE_TOOLS gate. Installing from the catalog (the
+ * default source) is always allowed.
+ */
+function gitSkillSourcesEnabled() {
+    return parseBool(process.env.THALOVANT_ENABLE_GIT_SKILL_SOURCES, false);
+}
+/** The default install source is the vetted marketplace catalog. */
+function isCatalogSource(sourceType) {
+    return !sourceType || sourceType.trim().toLowerCase() === "catalog";
+}
+/**
+ * Read-only mode.
+ *
+ * When THALOVANT_MCP_READONLY is set, only tools annotated readOnlyHint: true
+ * are registered, so an operator can run a safe agent without hand-writing a
+ * tool denylist. Non-read-only tools are never registered and so never appear
+ * in tools/list. This complements, and is independent of, the per-principal
+ * allow/deny policy in authorizeTool().
+ */
+function readOnlyModeEnabled() {
+    return parseBool(process.env.THALOVANT_MCP_READONLY, false);
+}
 const capacityProfileSchema = z
     .enum(["standard", "autoscaling"])
     .describe('Hub capacity profile. Only "standard" (the API default, 1 replica) and "autoscaling" (2-32 replicas) are accepted. Omit the key entirely rather than sending null — an explicit null fails 422 INVALID_HUB_CAPACITY_PROFILE. "autoscaling" is plan-gated: 403 HUB_AUTOSCALING_NOT_INCLUDED when the plan has no autoscaling, 409 AUTOSCALING_HUB_LIMIT_REACHED when its autoscaling slots are already used.');
@@ -467,6 +507,13 @@ async function auditLog(event) {
     }
 }
 function registerThalovantTool(server, name, config, handler) {
+    if (readOnlyModeEnabled()) {
+        const annotations = (config.annotations ?? {});
+        if (annotations.readOnlyHint !== true) {
+            // Read-only mode: do not register write/destructive tools at all.
+            return;
+        }
+    }
     server.registerTool(name, config, async (args, extra) => {
         const principal = principalFromExtra(extra);
         const start = Date.now();
@@ -619,8 +666,53 @@ function summarizeReply(reply) {
         failureEvent: reply.failureEvent ? redactSecrets(reply.failureEvent.asObject()) : undefined,
     };
 }
-async function saveIdentity(path, identity) {
-    const resolvedPath = resolve(path);
+/**
+ * Base directory that saved client-identity files are confined to.
+ *
+ * thalovant_create_client_identity takes an LLM-chosen savePath. The file is
+ * written 0600, but without a base directory the model controls WHERE the
+ * secret lands and could drop a credential file into a git working tree or a
+ * synced folder. Files are therefore confined to THALOVANT_MCP_IDENTITY_DIR,
+ * defaulting to an `identities` folder under the Thalovant SDK config dir
+ * ($XDG_CONFIG_HOME/thalovant, %APPDATA%/Thalovant on Windows, else
+ * ~/.config/thalovant), matching the SDK's own convention.
+ */
+function identityBaseDir() {
+    const override = process.env.THALOVANT_MCP_IDENTITY_DIR?.trim();
+    if (override)
+        return resolve(override);
+    if (process.env.XDG_CONFIG_HOME)
+        return join(process.env.XDG_CONFIG_HOME, "thalovant", "identities");
+    if (process.platform === "win32" && process.env.APPDATA)
+        return join(process.env.APPDATA, "Thalovant", "identities");
+    return join(homedir(), ".config", "thalovant", "identities");
+}
+/**
+ * Resolve an LLM-supplied savePath against the identity base directory and
+ * refuse anything that escapes it. Relative paths resolve inside the base dir;
+ * absolute paths and `..` traversal that land outside it are rejected. The base
+ * dir is realpath'd so a symlinked base still validates correctly.
+ */
+function resolveIdentityPath(savePath) {
+    const baseDir = identityBaseDir();
+    let canonicalBase = resolve(baseDir);
+    try {
+        canonicalBase = realpathSync(canonicalBase);
+    }
+    catch {
+        // Base dir does not exist yet; writeIdentityFile creates it. Use the resolved
+        // (non-canonical) path for containment — nothing is symlinked yet.
+    }
+    const candidate = resolve(canonicalBase, savePath);
+    const rel = relative(canonicalBase, candidate);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error(`savePath must resolve to a location inside the identity directory (${canonicalBase}). ` +
+            `Absolute paths outside it and ".." traversal are rejected; pass a plain filename such as "my-hub.json". ` +
+            `Set THALOVANT_MCP_IDENTITY_DIR to change the identity directory.`);
+    }
+    return candidate;
+}
+async function writeIdentityFile(resolvedPath, identity) {
     await mkdir(dirname(resolvedPath), { recursive: true, mode: 0o700 });
     await writeFile(resolvedPath, `${stableStringify(identity.asObject(true))}\n`, { mode: 0o600 });
     return resolvedPath;
@@ -1017,7 +1109,10 @@ export function createServer() {
         defaultProtocol: "wss",
         destructiveToolsEnabled: destructiveToolsEnabled(),
         destructiveTools: destructiveToolsEnabled() ? [...DESTRUCTIVE_TOOLS] : [],
-        secretHandling: "Secrets are redacted in tool output. Identity files are only written when savePath is provided.",
+        gitSkillSourcesEnabled: gitSkillSourcesEnabled(),
+        readOnly: readOnlyModeEnabled(),
+        identityDir: identityBaseDir(),
+        secretHandling: "Secrets are redacted in tool output. Identity files are only written when savePath is provided, and only inside identityDir.",
     }));
     registerThalovantTool(server, "thalovant_list_public_hubs", {
         title: "List Public Hubs",
@@ -1107,7 +1202,7 @@ export function createServer() {
                 .string()
                 .min(1)
                 .optional()
-                .describe("Optional local file path for the full secret identity JSON. File mode is set to 0600."),
+                .describe("Optional filename for the full secret identity JSON, written 0600 inside the server's identity directory (see identityDir in thalovant_config_status). Pass a plain filename like \"my-hub.json\"; absolute paths outside the identity directory and \"..\" traversal are rejected."),
         },
         annotations: {
             readOnlyHint: false,
@@ -1116,6 +1211,10 @@ export function createServer() {
             openWorldHint: true,
         },
     }, async ({ hubId, name, siteId, ownerId, active, preferredProtocols, idempotencyKey, spec, savePath, ...auth }) => {
+        // Validate the destination BEFORE creating a cloud identity, so a path
+        // that escapes the identity directory is refused without leaving an
+        // orphaned credential behind in the control plane.
+        const targetIdentityPath = savePath ? resolveIdentityPath(savePath) : undefined;
         const api = await createControlPlane(auth);
         ensureAuthenticated(api);
         const result = await api.createClientIdentity(hubId, {
@@ -1128,7 +1227,7 @@ export function createServer() {
             spec,
         });
         const selectedEndpoint = api.requireRuntimeProtocol(result, preferredProtocols[0]);
-        const savedIdentityPath = savePath ? await saveIdentity(savePath, result.identity) : undefined;
+        const savedIdentityPath = targetIdentityPath ? await writeIdentityFile(targetIdentityPath, result.identity) : undefined;
         return jsonContent({
             result: redactSecrets(result.asObject({ includeSecrets: false })),
             selectedEndpoint,
@@ -1180,7 +1279,7 @@ export function createServer() {
         const client = await createRuntimeClient(runtime);
         try {
             await client.connect(clampTimeout(timeoutMs));
-            return jsonContent(client.healthcheck());
+            return jsonContent(redactSecrets(client.healthcheck()));
         }
         finally {
             await client.close();
@@ -1355,10 +1454,8 @@ export function createServer() {
         description: "Read authenticated Thalovant analytics overview data.",
         inputSchema: {
             ...controlPlaneSchema,
-            admin: z.boolean().optional(),
             range: z.string().min(1).optional(),
             bucket: z.string().min(1).optional(),
-            ownerId: z.string().min(1).optional(),
             hubId: z.string().min(1).optional(),
             clientId: z.string().min(1).optional(),
             country: z.string().min(1).optional(),
@@ -1886,7 +1983,7 @@ export function createServer() {
     });
     registerThalovantTool(server, "thalovant_install_runtime_group_skill", {
         title: "Install Runtime Group Skill",
-        description: "Install (or re-install) a skill in a Thalovant runtime group. Installing a skill that is already present updates the existing entry rather than failing. Discover skillId with thalovant_list_marketplace_skills, then confirm installable/purchase_required with thalovant_list_runtime_group_marketplace before calling this. Requires the hubs:write scope and a paid plan (402 'API access requires a paid plan'); a paid marketplace skill ALSO needs marketplace access on the tenant plan, which fails with a second, distinct 402 about paid marketplace access.",
+        description: "Install (or re-install) a skill in a Thalovant runtime group from the marketplace catalog. Installing a skill that is already present updates the existing entry rather than failing. Discover skillId with thalovant_list_marketplace_skills, then confirm installable/purchase_required with thalovant_list_runtime_group_marketplace before calling this. Requires the hubs:write scope and a paid plan (402 'API access requires a paid plan'); a paid marketplace skill ALSO needs marketplace access on the tenant plan, which fails with a second, distinct 402 about paid marketplace access. Only catalog sources are allowed by default: installing from a non-catalog source such as sourceType \"git\" runs code the marketplace never vetted and is refused unless the operator sets THALOVANT_ENABLE_GIT_SKILL_SOURCES.",
         inputSchema: {
             ...controlPlaneSchema,
             runtimeGroupId: z.string().min(1).describe("Runtime group UUID."),
@@ -1901,8 +1998,8 @@ export function createServer() {
                 .min(1)
                 .max(32)
                 .optional()
-                .describe('Install source, 1-32 characters, defaulting to "catalog". The API accepts any string here rather than a fixed enum, but only "catalog" (requires the skill to exist in the marketplace catalog) and "git" (requires sourceRef) get special handling.'),
-            sourceRef: z.string().min(1).max(255).optional().describe("Max 255 characters. Required for git installs — a git install without a valid repository URL fails 422."),
+                .describe('Install source, 1-32 characters, defaulting to "catalog". The API accepts any string here rather than a fixed enum, but only "catalog" (requires the skill to exist in the marketplace catalog) and "git" (requires sourceRef) get special handling. The value is trimmed and lower-cased before it is both checked and forwarded, so "Catalog" and " catalog " are treated exactly as "catalog". Any value that is not "catalog" is refused unless the operator sets THALOVANT_ENABLE_GIT_SKILL_SOURCES, because a non-catalog source can pull unvetted code into the runtime.'),
+            sourceRef: z.string().min(1).max(255).optional().describe("Max 255 characters. Required for git installs — a git install without a valid repository URL fails 422. Only usable when THALOVANT_ENABLE_GIT_SKILL_SOURCES is set."),
             versionPin: z.string().min(1).max(64).optional().describe("Pin the skill to an exact version. Max 64 characters."),
             active: z
                 .boolean()
@@ -1911,11 +2008,23 @@ export function createServer() {
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: false,
+            destructiveHint: true,
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ runtimeGroupId, skillId, marketplaceSkillId, sourceType, sourceRef, versionPin, active, ...auth }) => {
+    }, async ({ runtimeGroupId, skillId, marketplaceSkillId, sourceType: rawSourceType, sourceRef, versionPin, active, ...auth }) => {
+        // Normalize once (trim + case-fold) and forward the SAME value the gate
+        // validates. Otherwise a whitespace/case variant such as " Catalog " or
+        // "CATALOG" passes the local catalog check while the control plane, which
+        // special-cases only the exact string "catalog", treats it as a
+        // non-catalog source — bypassing the gate for the case it exists to block.
+        // A blank/omitted value defaults to the catalog source server-side.
+        const trimmedSource = typeof rawSourceType === "string" ? rawSourceType.trim() : "";
+        const sourceType = trimmedSource ? trimmedSource.toLowerCase() : undefined;
+        if (!isCatalogSource(sourceType) && !gitSkillSourcesEnabled()) {
+            throw new Error(`Refusing to install a skill from non-catalog source "${rawSourceType}". A non-catalog source (for example sourceType "git" with an arbitrary sourceRef) can pull unvetted code into the runtime and is disabled by default. ` +
+                "Set THALOVANT_ENABLE_GIT_SKILL_SOURCES=1 to allow non-catalog skill sources, or install from the marketplace catalog by omitting sourceType (or setting it to \"catalog\").");
+        }
         const api = await createControlPlane(auth);
         ensureAuthenticated(api);
         const options = { marketplaceSkillId, sourceType, sourceRef, versionPin, active };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thalovant/mcp-server",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Stdio and Streamable HTTP MCP server for Thalovant control-plane and hub runtime APIs.",
   "license": "MIT",
   "type": "module",