vpsnet-mcp 2.1.0 → 2.3.2

package/build/api-path.js

@@ -0,0 +1,26 @@
+/** Reject URL normalization and delimiter tricks before credentials or transport. */
+export function validateApiPath(path) {
+    if (typeof path !== "string" ||
+        path.length > 8192 ||
+        !path.startsWith("/") ||
+        path.startsWith("//") ||
+        /[\\#\s\x00-\x1f\x7f]/u.test(path)) {
+        throw new Error("Invalid VPSnet API route.");
+    }
+    const pathname = path.split("?", 1)[0];
+    for (const segment of pathname.slice(1).split("/")) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch {
+            throw new Error("Invalid VPSnet API route encoding.");
+        }
+        if (!decoded ||
+            decoded === "." ||
+            decoded === ".." ||
+            /[/%\\?#\s\x00-\x1f\x7f]/u.test(decoded)) {
+            throw new Error("Invalid VPSnet API route segment.");
+        }
+    }
+}

package/build/api.js

@@ -1,5 +1,8 @@
+import { RemoteAuthError } from './remote-auth-error.js';
+import { apiAuthorization, authorizationContext } from "./request-context.js";
 import { annotateAuthFailure } from "./auth-failure.js";
 import { createApiConfiguration } from "./api-configuration.js";
+import { validateApiPath } from "./api-path.js";
 const DEFAULT_API_TIMEOUT_MS = 45_000;
 const configuration = createApiConfiguration(process.env, process.cwd());
 const { keyFile: SIDECAR_KEY_FILE, mcpJson: PROJECT_MCP_JSON } = configuration.paths;
@@ -32,7 +35,7 @@ function isLoopbackHost(hostname) {
     }
     return octets[0] === 127;
 }
-function resolveApiBase() {
+export function resolveApiBase() {
     const raw = (process.env.VPSNET_API_URL || "").trim() || sidecarApiUrl() || "https://api.vpsnet.com";
     let url;
     try {
@@ -58,15 +61,17 @@ function resolveApiBase() {
     }
     return url.origin;
 }
-const startupKey = resolveApiKeyWithSource();
-if (!startupKey.key) {
-    console.error("No VPSnet API key found. Provide one of: the VPSNET_API_KEY environment variable, " +
-        `a key file at ${SIDECAR_KEY_FILE}, or mcpServers.vpsnet.env.VPSNET_API_KEY in ${PROJECT_MCP_JSON}.`);
-    process.exit(1);
+export function initializeStdioApi() {
+    const startupKey = resolveApiKeyWithSource();
+    if (!startupKey.key) {
+        console.error("No VPSnet API key found. Provide one of: the VPSNET_API_KEY environment variable, " +
+            `a key file at ${SIDECAR_KEY_FILE}, or mcpServers.vpsnet.env.VPSNET_API_KEY in ${PROJECT_MCP_JSON}.`);
+        throw new Error("No VPSnet API key found.");
+    }
+    // Say out loud where the key came from; key provenance must never be silent.
+    console.error(`VPSnet MCP: API key loaded from ${startupKey.source}.`);
+    console.error(`VPSnet MCP: API base resolved to ${resolveApiBase()}.`);
 }
-// Say out loud where the key came from; key provenance must never be silent.
-console.error(`VPSnet MCP: API key loaded from ${startupKey.source}.`);
-console.error(`VPSnet MCP: API base resolved to ${resolveApiBase()}.`);
 function resolveApiTimeoutMs() {
     const raw = Number.parseInt(process.env.VPSNET_API_TIMEOUT_MS || "", 10);
     if (Number.isFinite(raw) === false || raw <= 0) {
@@ -75,15 +80,20 @@ function resolveApiTimeoutMs() {
     return raw;
 }
 export async function apiRequest(method, path, body, extraHeaders, 
-// Explicitly annotate reviewed POST reads; other non-read methods fail closed.
+// Explicitly annotate reviewed POST reads and consuming GETs; other non-read methods fail closed.
 semantics) {
+    if (!["GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH", "DELETE"].includes(method)) {
+        throw new Error("Invalid VPSnet API request method.");
+    }
+    validateApiPath(path);
     const url = `${resolveApiBase()}${path}`;
     const headers = {
-        "X-API-KEY": resolveApiKey(),
         Accept: "application/json",
         ...(extraHeaders || {}),
+        ...apiAuthorization(resolveApiKey),
     };
-    const init = { method, headers };
+    // Credentials must never follow a redirect to a different endpoint.
+    const init = { method, headers, redirect: "error" };
     if (body) {
         headers["Content-Type"] = "application/json";
         init.body = JSON.stringify(body);
@@ -116,6 +126,15 @@ semantics) {
     catch {
         data = { error: text || res.statusText };
     }
+    if (authorizationContext()) {
+        if (res.status === 401)
+            throw new RemoteAuthError('invalid_token');
+        const failure = data;
+        if (res.status === 403 && failure?.error === 'insufficient_scope') {
+            const scope = typeof failure.required_scope === 'string' && /^[a-z_]+(?::[a-z_]+){1,2}$/.test(failure.required_scope) ? failure.required_scope : undefined;
+            throw new RemoteAuthError('insufficient_scope', scope);
+        }
+    }
     if (res.ok === false) {
         if (parsed === false || (text.trim() === "" && [502, 503, 504].includes(res.status))) {
             // Not an API answer at all: an HTML or plain-text page from the web
@@ -124,7 +143,20 @@ semantics) {
             // the API speaking; say what happened, with the status, in one line.
             return {
                 status: res.status,
-                data: describeNonApiResponse(res.status, res.headers.get("content-type"), text, new URL(url).host, semantics?.readOnly === true || ["GET", "HEAD", "OPTIONS"].includes(method.toUpperCase())),
+                data: describeNonApiResponse(res.status, res.headers.get("content-type"), text, new URL(url).host, semantics?.readOnly ?? ["GET", "HEAD", "OPTIONS"].includes(method.toUpperCase())),
+            };
+        }
+        if (res.status === 503 && method === "POST"
+            && /^\/account\/firecracker\/functions\/\d+\/invoke$/.test(path)
+            && data !== null && typeof data === "object" && !Array.isArray(data)
+            && data.noActiveServer === true) {
+            data = {
+                ...data,
+                code: "function_execution_unavailable",
+                message: "VPSnet Functions cannot currently accept this code execution. "
+                    + "This response describes the Functions service, not the status of a persistent Firecracker VPS.",
+                next_action: "Try again when Functions is available, using the same invocation idempotency key and input, "
+                    + "or contact VPSnet support. No server restart, new VPS or permission change is required by this error.",
             };
         }
         data = withHttpStatus(res.status, data, res.headers.get("retry-after"));
@@ -132,7 +164,7 @@ semantics) {
     // The account API signals auth problems with a bare status plus a message.
     // Explain them here, at the single choke point, so every tool reports the
     // real cause instead of an unactionable "Unauthorized".
-    return { status: res.status, data: annotateAuthFailure(res.status, data) };
+    return { status: res.status, data: authorizationContext() ? data : annotateAuthFailure(res.status, data) };
 }
 /**
  * Structured tool error for a non-2xx answer whose body is not JSON.

package/build/application-contract.js

@@ -72,6 +72,23 @@ const externalHttpsUrlSchema = z.string().max(500).refine((value) => {
         return false;
     }
 }, "External access must be a credential-free HTTPS URL without a query or fragment");
+/**
+ * An additional address of a managed_https endpoint: another name in one of the
+ * customer's own VPSnet DNS zones that leads to the same application. An empty
+ * name or "@" is the zone's bare domain (for example `example.com` next to
+ * `www.example.com`). `redirect` answers 301 to the main address and keeps the
+ * path and query; `serve` opens the same application. Wire shape: design
+ * app-additional-addresses-design-1005 section 2.3.
+ */
+export const applicationAdditionalAddressSchema = z.object({
+    zone_id: z.number().int().min(1),
+    name: z
+        .string()
+        .max(190)
+        .regex(/^(?:@|(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*)?)$/),
+    action: z.enum(["redirect", "serve"]).default("redirect"),
+    approve_dns: z.literal(true),
+}).strict();
 export const applicationSingleAccessSchema = z.discriminatedUnion("mode", [
     z.object({ mode: z.literal("platform_https") }).strict(),
     z.object({ mode: z.literal("private") }).strict(),
@@ -85,6 +102,10 @@ export const applicationSingleAccessSchema = z.discriminatedUnion("mode", [
             .max(190)
             .regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/),
         approve_dns: z.literal(true),
+        additional_addresses: z
+            .array(applicationAdditionalAddressSchema)
+            .max(4)
+            .optional(),
     }).strict(),
 ]);
 const applicationAccessEndpointSchema = z.object({

package/build/certificate-contract.js

@@ -7,16 +7,19 @@ export const certificateProductIdSchema = z
     .number()
     .int()
     .positive()
+    .max(Number.MAX_SAFE_INTEGER)
     .describe("Published product ID returned by list_certificate_catalog");
 export const certificateOfferIdSchema = z
     .number()
     .int()
     .positive()
+    .max(Number.MAX_SAFE_INTEGER)
     .describe("Published EUR offer ID returned by the selected catalog product");
 export const certificateOfferGenerationSchema = z
     .number()
     .int()
     .positive()
+    .max(Number.MAX_SAFE_INTEGER)
     .describe("Exact offer generation returned by the catalog; stale generations are rejected");
 export const certificateSubscriptionIdSchema = z
     .string()
@@ -172,6 +175,7 @@ const freeCertificateTargetOrderIdSchema = z
     .number()
     .int()
     .positive()
+    .max(Number.MAX_SAFE_INTEGER)
     .nullable()
     .optional()
     .describe("Optional owned VPS or Cloud VPS order ID returned by service tools");
@@ -263,16 +267,19 @@ export const certificateOrderInputShape = {
         .number()
         .int()
         .positive()
+        .max(Number.MAX_SAFE_INTEGER)
         .describe("Owned administrator contact ID selected in the VPSnet certificate order form"),
     technical_contact_id: z
         .number()
         .int()
         .positive()
+        .max(Number.MAX_SAFE_INTEGER)
         .describe("Owned technical contact ID selected in the VPSnet certificate order form"),
     organization_contact_id: z
         .number()
         .int()
         .positive()
+        .max(Number.MAX_SAFE_INTEGER)
         .nullable()
         .optional()
         .describe("Owned organization contact ID when required for OV or EV validation"),

package/build/file-restore-contract.js

@@ -18,6 +18,7 @@ export const fileBrowsePointIdSchema = z
     .number()
     .int()
     .positive()
+    .max(Number.MAX_SAFE_INTEGER)
     .describe("Backup point ID returned by list_restore_file_points");
 export const fileBrowseIdSchema = z
     .string()

package/build/http-server.js

@@ -0,0 +1,123 @@
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createVpsnetServer } from "./index.js";
+import { resolveApiBase } from "./api.js";
+import { requireRequestAuthorization, withAuthorization } from "./request-context.js";
+import { supportedScopes, orderScopes } from "./remote-policy.js";
+function publicUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash)
+        throw new Error("MCP public URLs must use HTTPS without credentials, query or fragment.");
+    return url;
+}
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    res.end(JSON.stringify(body));
+}
+export function createRemoteServer(options) {
+    requireRequestAuthorization();
+    const resource = publicUrl(options.resource);
+    const issuer = publicUrl(options.issuer).href.replace(/\/$/, "");
+    if (resource.pathname !== "/mcp")
+        throw new Error("The MCP resource path must be /mcp.");
+    const allowedScopes = options.ordersEnabled ? [...supportedScopes, ...orderScopes] : supportedScopes;
+    const apiBase = resolveApiBase();
+    const origins = new Set(options.allowedOrigins ?? []);
+    for (const origin of origins)
+        if (publicUrl(origin).origin !== origin)
+            throw new Error("Allowed origins must be HTTPS origins.");
+    async function authenticate(req) {
+        const match = /^Bearer (vpsnet_[A-Za-z0-9_-]{43})$/.exec(req.headers.authorization ?? "");
+        if (!match)
+            return null;
+        const response = await fetch(`${apiBase}/oauth/mcp/introspect`, {
+            method: "POST", headers: { Authorization: `Bearer ${match[1]}`, Accept: "application/json" },
+            redirect: "error", signal: AbortSignal.timeout(10_000),
+        });
+        if (response.status === 401 || response.status === 403)
+            return null;
+        if (!response.ok)
+            throw new Error("VPSnet authorization is unavailable.");
+        const value = await response.json();
+        if (value.active !== true || value.aud !== resource.href || value.iss !== issuer
+            || typeof value.exp !== "number" || value.exp <= Date.now() / 1000
+            || typeof value.sub !== "string" || typeof value.grant_id !== "string" || typeof value.scope !== "string"
+            || !Array.isArray(value.services) || !value.services.every(x => typeof x === "string"))
+            return null;
+        return { accessToken: match[1], subject: value.sub, grantId: value.grant_id,
+            expiresAt: value.exp, ordersAvailable: options.ordersEnabled === true && value.orders_available === true, scopes: value.scope.split(" ").filter(x => (allowedScopes.includes(x) || x === "vm:files")), services: value.services };
+    }
+    const http = createServer(async (req, res) => {
+        // TLS terminates at the supplied reverse proxy, which must preserve Host.
+        if (req.headers.host !== resource.host)
+            return json(res, 421, { error: "invalid_host" });
+        if (req.headers.origin && !origins.has(req.headers.origin))
+            return json(res, 403, { error: "invalid_origin" });
+        if (req.headers.origin) {
+            res.setHeader("Access-Control-Allow-Origin", req.headers.origin);
+            res.setHeader("Vary", "Origin");
+            res.setHeader("Access-Control-Expose-Headers", "WWW-Authenticate, MCP-Protocol-Version");
+        }
+        if (req.method === "OPTIONS") {
+            res.setHeader("Access-Control-Allow-Methods", "POST, GET, OPTIONS");
+            res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type, MCP-Protocol-Version, Last-Event-ID");
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === 'GET' && ['/.well-known/oauth-protected-resource', '/.well-known/oauth-protected-resource/mcp'].includes(req.url ?? '')) {
+            return json(res, 200, { resource: resource.href, authorization_servers: [issuer], scopes_supported: allowedScopes, bearer_methods_supported: ['header'], resource_name: 'VPSnet' });
+        }
+        if (req.url !== '/mcp')
+            return json(res, 404, { error: 'not_found' });
+        try {
+            const context = await authenticate(req);
+            if (!context) {
+                res.setHeader("WWW-Authenticate", `Bearer resource_metadata="${resource.origin}/.well-known/oauth-protected-resource${resource.pathname}"`);
+                return json(res, 401, { error: "invalid_token" });
+            }
+            if (req.method !== "POST") {
+                res.setHeader("Allow", "POST");
+                return json(res, 405, { error: "method_not_allowed" });
+            }
+            if (req.headers["mcp-session-id"])
+                return json(res, 400, { error: "stateless_transport" });
+            if (!req.headers["content-type"]?.split(";")[0].trim().match(/^application\/json$/i))
+                return json(res, 415, { error: "unsupported_media_type" });
+            let size = 0;
+            const chunks = [];
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > 1024 * 1024)
+                    return json(res, 413, { error: "request_too_large" });
+                chunks.push(chunk);
+            }
+            let body;
+            try {
+                body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+            }
+            catch {
+                return json(res, 400, { error: "invalid_json" });
+            }
+            if (Array.isArray(body))
+                return json(res, 400, { error: "batch_not_supported" });
+            await withAuthorization(context, async () => {
+                const server = createVpsnetServer({ remoteScopes: context.scopes, remoteProfile: context.ordersAvailable ? 'orders' : 'directory' });
+                const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+                res.once("close", () => { void transport.close(); void server.close(); });
+                await server.connect(transport);
+                await transport.handleRequest(req, res, body);
+            });
+        }
+        catch {
+            // Never emit upstream exceptions, tokens or request arguments into logs.
+            if (!res.headersSent)
+                json(res, 503, { error: "temporarily_unavailable" });
+            else
+                res.end();
+        }
+    });
+    http.requestTimeout = 30_000;
+    http.headersTimeout = 10_000;
+    return http;
+}