fix(deploy): validate deployment id as 8-hex app_id, not UUID (#43)

The six deployment-by-id tools (get_deployment, get_deployment_events,
redeploy, delete_deployment, update_deploy_env, wake_deployment) applied
uuidSchema (canonical 8-4-4-4-12) to their `id` arg. But a deployment's
public id (app_id/token, returned as `deploy_id` by create_deploy) is
8-char lowercase hex — the api's generateAppID() is hex.EncodeToString of
4 random bytes (api/internal/handlers/deploy.go). zod therefore rejected
EVERY real call client-side (-32602) before it reached the api, killing
the entire manage-the-deploy loop through MCP.

Introduce deployIdSchema (/^[0-9a-f]{8}$/) and apply it to exactly those
six tools; resource-token tools keep uuidSchema (their tokens ARE UUIDs).

Why it shipped green: (a) test/mock-api.ts was edited to EMIT UUID-shaped
app_ids "like prod" — but prod does not, so fixtures never tripped the bad
schema; (b) the handler tests call .handler directly, bypassing the zod
inputSchema the real SDK dispatch applies. Revert the mock to emit 8-hex
app_ids and add a regression test that drives the registered inputSchema
(the dispatch path) for all six tools, iterating the registry (rule 18).

Also pin zod in dependencies (was an implicit SDK peer).

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: mastermanas805

package-lock.json

@@ -46,13 +46,14 @@
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "pretest": "tsc && tsc -p tsconfig.test.json",
-    "test": "node --test --experimental-test-coverage --test-coverage-exclude='dist-test/test/**' --test-coverage-exclude='dist/**' --test-coverage-exclude='node_modules/**' dist-test/test/integration.test.js dist-test/test/live-smoke.test.js dist-test/test/prod-cohort.test.js dist-test/test/client-unit.test.js dist-test/test/index-unit.test.js dist-test/test/tools-unit.test.js dist-test/test/operate-tools-unit.test.js dist-test/test/tool-coverage.test.js dist-test/test/tool-contract.test.js dist-test/test/env-regex-unit.test.js dist-test/test/input-hardening-unit.test.js",
-    "test:nocov": "node --test dist-test/test/integration.test.js dist-test/test/live-smoke.test.js dist-test/test/prod-cohort.test.js dist-test/test/client-unit.test.js dist-test/test/index-unit.test.js dist-test/test/tools-unit.test.js dist-test/test/operate-tools-unit.test.js dist-test/test/tool-coverage.test.js dist-test/test/tool-contract.test.js dist-test/test/env-regex-unit.test.js dist-test/test/input-hardening-unit.test.js",
+    "test": "node --test --experimental-test-coverage --test-coverage-exclude='dist-test/test/**' --test-coverage-exclude='dist/**' --test-coverage-exclude='node_modules/**' dist-test/test/integration.test.js dist-test/test/live-smoke.test.js dist-test/test/prod-cohort.test.js dist-test/test/client-unit.test.js dist-test/test/index-unit.test.js dist-test/test/tools-unit.test.js dist-test/test/operate-tools-unit.test.js dist-test/test/tool-coverage.test.js dist-test/test/tool-contract.test.js dist-test/test/env-regex-unit.test.js dist-test/test/input-hardening-unit.test.js dist-test/test/deploy-id-schema-unit.test.js",
+    "test:nocov": "node --test dist-test/test/integration.test.js dist-test/test/live-smoke.test.js dist-test/test/prod-cohort.test.js dist-test/test/client-unit.test.js dist-test/test/index-unit.test.js dist-test/test/tools-unit.test.js dist-test/test/operate-tools-unit.test.js dist-test/test/tool-coverage.test.js dist-test/test/tool-contract.test.js dist-test/test/env-regex-unit.test.js dist-test/test/input-hardening-unit.test.js dist-test/test/deploy-id-schema-unit.test.js",
     "test:smoke": "bash test.sh",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.29.0"
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.9.2",

package.json

@@ -280,6 +280,18 @@ const envSchema = z
 const UUID_REGEX =
   /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 
+// BUG-MCP-043: a deployment's public identifier (`app_id` / `token`, returned
+// as `deploy_id` by create_deploy) is NOT a UUID — the api's generateAppID()
+// (api/internal/handlers/deploy.go) is hex.EncodeToString of 4 random bytes =>
+// exactly 8 lowercase hex chars. The openapi route params for /deploy/{id},
+// /deploy/{id}/events, /deploy/{id}/wake, and /api/v1/deployments/{id} are bare
+// `{type: string}`. A canonical-UUID regex therefore REJECTS every real
+// deployment id client-side (zod -32602) before the request reaches the api,
+// breaking the entire manage-the-deploy loop (status/events/redeploy/delete/
+// env/wake) through MCP. This regex matches the real format so the validation
+// error message stays precise while accepting genuine ids.
+const APP_ID_REGEX = /^[0-9a-f]{8}$/;
+
 // BUG-MCP-022: client-side IP-or-CIDR validation for the `allowed_ips` field
 // on create_deploy. Accepts:
 //   - IPv4 address (e.g. "203.0.113.42")
@@ -324,6 +336,18 @@ const uuidSchema = z
     "must be a UUID in canonical 8-4-4-4-12 form (e.g. 8b1f3c9e-...-...)"
   );
 
+// deployIdSchema validates the 8-char hex `app_id`/`token` used to address a
+// deployment (see APP_ID_REGEX above). DISTINCT from uuidSchema: resource
+// tokens are real UUIDs, deployment ids are 8-hex. Used only by the six
+// deployment-by-id tools (get_deployment, get_deployment_events, redeploy,
+// delete_deployment, update_deploy_env, wake_deployment).
+export const deployIdSchema = z
+  .string()
+  .regex(
+    APP_ID_REGEX,
+    "must be an 8-character lowercase-hex deployment id (e.g. a3f91c0e), as returned by create_deploy"
+  );
+
 // Vault env / key shapes — mirror the api's validateEnv / validateKey
 // (api/internal/handlers/vault.go): env is 1-64 chars [A-Za-z0-9_-], key is
 // 1-256 chars [A-Za-z0-9_.-]. These are DISTINCT from the resource `env`
@@ -1499,8 +1523,8 @@ single record.
 
 Requires INSTANODE_TOKEN.`,
   {
-    // BUG-MCP-025: validate UUID client-side.
-    id: uuidSchema.describe("Deployment app id (returned as 'deploy_id' by create_deploy)."),
+    // BUG-MCP-043: app_id is 8-char hex, not a UUID. Validate client-side.
+    id: deployIdSchema.describe("Deployment app id (returned as 'deploy_id' by create_deploy)."),
   },
   async ({ id }) => {
     try {
@@ -1575,8 +1599,8 @@ If the deploy succeeded there may be no events (empty list) — that's normal.
 Requires INSTANODE_TOKEN. A deployment id that isn't on your team returns a
 clean "not found" (the api never confirms other teams' deployments).`,
   {
-    // BUG-MCP-025: validate UUID client-side, mirroring get_deployment.
-    id: uuidSchema.describe(
+    // BUG-MCP-043: app_id is 8-char hex, not a UUID. Mirrors get_deployment.
+    id: deployIdSchema.describe(
       "Deployment app id (returned as 'deploy_id' by create_deploy / 'app_id' by get_deployment)."
     ),
     // Optional cap on rows returned. api default is 50, clamped server-side.
@@ -1658,8 +1682,8 @@ to "running" (~30s typical).
 
 Requires INSTANODE_TOKEN.`,
   {
-    // BUG-MCP-025: validate UUID client-side.
-    id: uuidSchema.describe("Deployment app id (returned as 'deploy_id' by create_deploy)."),
+    // BUG-MCP-043: app_id is 8-char hex, not a UUID. Validate client-side.
+    id: deployIdSchema.describe("Deployment app id (returned as 'deploy_id' by create_deploy)."),
     // T-redeploy-fix: tarball is required. The api handler at
     // deploy.go:1245 returns 400 missing_tarball without it; the previous
     // tool schema omitted this field and the description lied about
@@ -1708,8 +1732,8 @@ deleted. Irreversible.
 
 Requires INSTANODE_TOKEN.`,
   {
-    // BUG-MCP-025: validate UUID client-side.
-    id: uuidSchema.describe("Deployment app id (returned as 'deploy_id' by create_deploy)."),
+    // BUG-MCP-043: app_id is 8-char hex, not a UUID. Validate client-side.
+    id: deployIdSchema.describe("Deployment app id (returned as 'deploy_id' by create_deploy)."),
   },
   async ({ id }) => {
     try {
@@ -1925,7 +1949,8 @@ Values can be plaintext or vault://env/KEY references (write the secret first
 with set_vault_key). Requires INSTANODE_TOKEN. A deployment id not on your
 team returns a clean 404 (the api never confirms other teams' deployments).`,
   {
-    id: uuidSchema.describe(
+    // BUG-MCP-043: app_id is 8-char hex, not a UUID. Validate client-side.
+    id: deployIdSchema.describe(
       "Deployment app id (returned as 'deploy_id' by create_deploy / 'app_id' by get_deployment)."
     ),
     env: z
@@ -2218,7 +2243,8 @@ always-on, so there's nothing to wake.
 
 Requires INSTANODE_TOKEN. A deployment id not on your team returns a clean 404.`,
   {
-    id: uuidSchema.describe(
+    // BUG-MCP-043: app_id is 8-char hex, not a UUID. Validate client-side.
+    id: deployIdSchema.describe(
       "Deployment app id (returned as 'deploy_id' by create_deploy / 'app_id' by get_deployment)."
     ),
   },

src/index.ts

@@ -0,0 +1,126 @@
+/**
+ * REGRESSION test for BUG-MCP-043 — the deploy-id schema.
+ *
+ * Symptom (live dogfood): the six deployment-by-id tools (get_deployment,
+ * get_deployment_events, redeploy, delete_deployment, update_deploy_env,
+ * wake_deployment) validated their `id` arg with `uuidSchema` (canonical
+ * 8-4-4-4-12 UUID). But a deployment's public id (`app_id`/`token`, returned as
+ * `deploy_id` by create_deploy) is 8-char lowercase hex — the api's
+ * generateAppID() is hex.EncodeToString of 4 random bytes
+ * (api/internal/handlers/deploy.go). So zod rejected EVERY real call CLIENT-SIDE
+ * (-32602) before it reached the api, killing the manage-the-deploy loop.
+ *
+ * Why it shipped green: (a) test/mock-api.ts was edited to EMIT UUID-shaped
+ * app_ids ("like prod" — but prod does NOT), so fixtures never tripped the bad
+ * schema; (b) the handler tests call the registered .handler directly, BYPASSING
+ * the zod inputSchema the real MCP-SDK dispatch applies. 161 tests passed while
+ * every real call was broken.
+ *
+ * This test closes both gaps. It drives the SCHEMA/DISPATCH path — the registered
+ * `inputSchema` the SDK validates against at the wire boundary — NOT the handler
+ * directly. And it iterates the live registry (reliability rule 18) rather than a
+ * hand-typed slice, so it cannot silently miss one of the six.
+ *
+ * Against the OLD schema this test reds on every one of the six tools: the bad
+ * `uuidSchema` would reject the real 8-hex id and accept the UUID — the exact
+ * inversion of correctness.
+ */
+
+import { strict as assert } from "node:assert";
+import { before, describe, it } from "node:test";
+
+// Keep the side-effecting `await server.connect(transport)` off when index.js
+// is imported (same flag every other in-process suite uses).
+process.env["INSTANODE_MCP_NO_LISTEN"] = "1";
+delete process.env["INSTANODE_TOKEN"];
+
+// The six deployment-by-id tools whose `id` arg is an 8-hex app_id, NOT a UUID.
+// Iterated as a registry (rule 18) so a future tool added to this class is
+// caught the moment it lands with the wrong schema.
+const DEPLOY_ID_TOOLS = [
+  "get_deployment",
+  "get_deployment_events",
+  "redeploy",
+  "delete_deployment",
+  "update_deploy_env",
+  "wake_deployment",
+] as const;
+
+// A real-shaped deployment id (8 lowercase hex) the api would actually mint.
+const REAL_APP_ID = "a3f91c0e";
+// A canonical UUID — what the BROKEN schema demanded, and what the api never
+// uses to address a deployment.
+const A_UUID = "00000000-0000-4000-8000-000000000000";
+// An obviously-bad value: not hex, wrong length.
+const BAD_ID = "not-an-id";
+
+let server: any;
+let deployIdSchema: any;
+
+before(async () => {
+  const mod: any = await import("../src/index.js");
+  server = mod.server;
+  deployIdSchema = mod.deployIdSchema;
+});
+
+// The mcp-sdk validates args against the registered inputSchema at the WIRE
+// boundary, not inside the handler. So we assert on the per-field zod schema's
+// safeParse — the same validation the real dispatch applies — NOT by invoking
+// the handler (which is exactly the bypass that hid this bug).
+function idSchemaOf(toolName: string): any {
+  const reg = (server as any)._registeredTools as Record<string, { inputSchema?: any }>;
+  const t = reg[toolName];
+  if (!t) throw new Error(`tool not registered: ${toolName}`);
+  return (t as any).inputSchema?.shape?.["id"] ?? null;
+}
+
+describe("BUG-MCP-043: deploy-id schema (registered inputSchema / dispatch path)", () => {
+  for (const tool of DEPLOY_ID_TOOLS) {
+    it(`${tool}.id ACCEPTS a real 8-hex app_id`, () => {
+      const schema = idSchemaOf(tool);
+      assert.ok(schema, `${tool}.id schema not located`);
+      assert.equal(
+        schema.safeParse(REAL_APP_ID).success,
+        true,
+        `${tool} rejected a real 8-hex deployment id — the manage-the-deploy loop is broken`
+      );
+    });
+
+    it(`${tool}.id REJECTS a UUID (the wrong, old schema's shape)`, () => {
+      const schema = idSchemaOf(tool);
+      assert.equal(
+        schema.safeParse(A_UUID).success,
+        false,
+        `${tool} accepted a UUID — it is still using uuidSchema, not deployIdSchema`
+      );
+    });
+
+    it(`${tool}.id REJECTS an obviously-bad value`, () => {
+      const schema = idSchemaOf(tool);
+      assert.equal(schema.safeParse(BAD_ID).success, false);
+    });
+  }
+});
+
+describe("BUG-MCP-043: deployIdSchema unit contract", () => {
+  it("parses a real 8-hex id", () => {
+    assert.equal(deployIdSchema.parse(REAL_APP_ID), REAL_APP_ID);
+  });
+
+  it("throws on a non-id value", () => {
+    assert.throws(() => deployIdSchema.parse(BAD_ID));
+  });
+
+  it("throws on a UUID (the deploy id is never a UUID)", () => {
+    assert.throws(() => deployIdSchema.parse(A_UUID));
+  });
+
+  it("throws on uppercase hex (api emits lowercase via hex.EncodeToString)", () => {
+    assert.throws(() => deployIdSchema.parse("A3F91C0E"));
+  });
+
+  it("throws on the wrong length (7 or 9 hex chars)", () => {
+    assert.throws(() => deployIdSchema.parse("a3f91c0"));
+    assert.throws(() => deployIdSchema.parse("a3f91c0ee"));
+  });
+});

test/deploy-id-schema-unit.test.ts

@@ -271,26 +271,55 @@ describe("BUG-MCP-021: create_deploy private+allowed_ips coupling (handler)", ()
   });
 });
 
-// ── BUG-MCP-024 / 025: UUID schemas ─────────────────────────────────────────
+// ── BUG-MCP-024: UUID schemas on RESOURCE-token fields ──────────────────────
+// Resource tokens ARE real UUIDs, so uuidSchema is correct for them.
 
-describe("BUG-MCP-024/025: UUID validation on token/id fields", () => {
+describe("BUG-MCP-024: UUID validation on resource-token fields", () => {
   const uuidSamples = {
     good: "8b1f3c9e-1234-4abc-9def-0123456789ab",
     bad: "not-a-uuid",
   };
+  for (const [tool, field] of [["delete_resource", "token"]] as const) {
+    it(`${tool}.${field} accepts a real UUID`, () => {
+      const s = schemaFor(tool, field);
+      assert.equal(s.safeParse(uuidSamples.good).success, true);
+    });
+    it(`${tool}.${field} rejects a non-UUID`, () => {
+      const s = schemaFor(tool, field);
+      assert.equal(s.safeParse(uuidSamples.bad).success, false);
+    });
+  }
+});
+
+// ── BUG-MCP-043: deploy-id fields are 8-hex app_ids, NOT UUIDs ───────────────
+// The original BUG-MCP-025 lumped these in with delete_resource and asserted
+// they accept a UUID — that assertion was wrong (it codified the very bug that
+// broke the manage-the-deploy loop). A deployment's id is the api's 8-char
+// lowercase-hex app_id. Asserted here against the registered schema (the SDK
+// dispatch path), so the inversion can never silently come back.
+
+describe("BUG-MCP-043: 8-hex deploy-id validation on deployment fields", () => {
+  const samples = {
+    goodAppId: "a3f91c0e",
+    aUuid: "8b1f3c9e-1234-4abc-9def-0123456789ab",
+    bad: "not-an-id",
+  };
   for (const [tool, field] of [
-    ["delete_resource", "token"],
     ["get_deployment", "id"],
     ["redeploy", "id"],
     ["delete_deployment", "id"],
   ] as const) {
-    it(`${tool}.${field} accepts a real UUID`, () => {
+    it(`${tool}.${field} accepts a real 8-hex app_id`, () => {
       const s = schemaFor(tool, field);
-      assert.equal(s.safeParse(uuidSamples.good).success, true);
+      assert.equal(s.safeParse(samples.goodAppId).success, true);
     });
-    it(`${tool}.${field} rejects a non-UUID`, () => {
+    it(`${tool}.${field} rejects a UUID (deploy ids are never UUIDs)`, () => {
       const s = schemaFor(tool, field);
-      assert.equal(s.safeParse(uuidSamples.bad).success, false);
+      assert.equal(s.safeParse(samples.aUuid).success, false);
+    });
+    it(`${tool}.${field} rejects a non-id`, () => {
+      const s = schemaFor(tool, field);
+      assert.equal(s.safeParse(samples.bad).success, false);
     });
   }
 });

test/input-hardening-unit.test.ts

@@ -732,11 +732,13 @@ describe("instanode-mcp integration suite", () => {
     it("get_deployment returns a not-found error for an unknown app id", async () => {
       const { client, close } = await connectClient(mock.url, "valid");
       try {
-        // BUG-MCP-025: id must be a real UUID — supply one the mock doesn't
-        // know about so the API still returns 404.
+        // BUG-MCP-043: id is an 8-char hex app_id (NOT a UUID). Supply one the
+        // mock never minted so the call passes the deployIdSchema at the SDK
+        // dispatch boundary and the API still returns 404. (A UUID here would be
+        // rejected client-side, never reaching the 404 path this test asserts.)
         const res = await client.callTool({
           name: "get_deployment",
-          arguments: { id: "00000000-0000-4000-8000-000000000404" },
+          arguments: { id: "deadbeef" },
         });
         assert.ok(/404|not found/i.test(resultText(res)), "get_deployment did not surface a 404");
       } finally {
@@ -747,12 +749,13 @@ describe("instanode-mcp integration suite", () => {
     it("redeploy returns a not-found error for an unknown app id", async () => {
       const { client, close } = await connectClient(mock.url, "valid");
       try {
-        // BUG-MCP-025: see above — UUID-shaped + unknown.
+        // BUG-MCP-043: see above — 8-hex app_id + unknown, so it clears the
+        // deployIdSchema dispatch gate and the API returns 404.
         // tarball_base64 is now required (real api: deploy.go:1245).
         const res = await client.callTool({
           name: "redeploy",
           arguments: {
-            id: "00000000-0000-4000-8000-000000000404",
+            id: "deadbeef",
             tarball_base64: fakeTarballBase64(),
           },
         });