@tenkicloud/mcp 0.3.2-canary.1 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +42 -1
- package/README.md +88 -79
- package/SECURITY.md +2 -2
- package/dist/client.d.ts +16 -1
- package/dist/client.js +62 -16
- package/dist/env.d.ts +6 -0
- package/dist/env.js +25 -0
- package/dist/http.js +13 -10
- package/dist/index.js +9 -8
- package/dist/oauth.d.ts +7 -1
- package/dist/oauth.js +29 -9
- package/dist/server.d.ts +25 -5
- package/dist/server.js +88 -53
- package/dist/tools/artifacts.d.ts +3 -3
- package/dist/tools/artifacts.js +6 -6
- package/dist/tools/auth_status.d.ts +3 -3
- package/dist/tools/auth_status.js +8 -9
- package/dist/tools/common.d.ts +35 -0
- package/dist/tools/common.js +78 -0
- package/dist/tools/egress.d.ts +38 -0
- package/dist/tools/egress.js +153 -0
- package/dist/tools/exec.js +1 -1
- package/dist/tools/files.js +36 -3
- package/dist/tools/files_ops.js +9 -1
- package/dist/tools/git.d.ts +0 -1
- package/dist/tools/git.js +85 -23
- package/dist/tools/ports.d.ts +8 -1
- package/dist/tools/ports.js +24 -3
- package/dist/tools/previews.js +59 -22
- package/dist/tools/sandboxes.d.ts +1 -1
- package/dist/tools/sandboxes.js +342 -26
- package/dist/tools/sessions_admin.js +63 -23
- package/dist/tools/snapshots.js +41 -22
- package/dist/tools/ssh.d.ts +3 -3
- package/dist/tools/ssh.js +35 -9
- package/dist/tools/templates.d.ts +2 -1
- package/dist/tools/templates.js +36 -16
- package/dist/tools/titles.d.ts +8 -0
- package/dist/tools/titles.js +102 -0
- package/dist/tools/volumes.js +36 -11
- package/dist/tools/workspace.d.ts +9 -1
- package/dist/tools/workspace.js +29 -90
- package/package.json +12 -8
package/dist/env.d.ts
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/** Every `LUXORAI_<suffix>` is tried (in order) before any legacy `TENKI_<suffix>`. Empty or blank values fall through. */
|
|
2
|
+
export declare function readEnv(...suffixes: string[]): string | undefined;
|
|
3
|
+
/** The env var name {@link readEnv} resolved, for diagnostics. */
|
|
4
|
+
export declare function resolvedEnvName(env: NodeJS.ProcessEnv, ...suffixes: string[]): string | undefined;
|
|
5
|
+
/** API keys carry `lx_` (Luxor AI) or the legacy `tk_` prefix. */
|
|
6
|
+
export declare function isApiKey(token: string): boolean;
|
package/dist/env.js
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/** Every `LUXORAI_<suffix>` is tried (in order) before any legacy `TENKI_<suffix>`. Empty or blank values fall through. */
|
|
2
|
+
export function readEnv(...suffixes) {
|
|
3
|
+
for (const prefix of ["LUXORAI_", "TENKI_"]) {
|
|
4
|
+
for (const suffix of suffixes) {
|
|
5
|
+
const value = process.env[`${prefix}${suffix}`];
|
|
6
|
+
if (value?.trim())
|
|
7
|
+
return value;
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
return undefined;
|
|
11
|
+
}
|
|
12
|
+
/** The env var name {@link readEnv} resolved, for diagnostics. */
|
|
13
|
+
export function resolvedEnvName(env, ...suffixes) {
|
|
14
|
+
for (const prefix of ["LUXORAI_", "TENKI_"]) {
|
|
15
|
+
for (const suffix of suffixes) {
|
|
16
|
+
if (env[`${prefix}${suffix}`]?.trim())
|
|
17
|
+
return `${prefix}${suffix}`;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
return undefined;
|
|
21
|
+
}
|
|
22
|
+
/** API keys carry `lx_` (Luxor AI) or the legacy `tk_` prefix. */
|
|
23
|
+
export function isApiKey(token) {
|
|
24
|
+
return token.startsWith("lx_") || token.startsWith("tk_");
|
|
25
|
+
}
|
package/dist/http.js
CHANGED
|
@@ -17,8 +17,9 @@ import { randomUUID, timingSafeEqual } from "node:crypto";
|
|
|
17
17
|
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
|
|
18
18
|
import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
|
|
19
19
|
import { TenkiClient } from "./client.js";
|
|
20
|
-
import { OAuthResourceRoutes, OAuthTokenVerifier, authorizationBinding, bearerToken, loadOAuthConfig, } from "./oauth.js";
|
|
20
|
+
import { OAuthResourceRoutes, OAuthTokenVerifier, authorizationBinding, bearerToken, loadOAuthConfig, metadataUrlForHost, } from "./oauth.js";
|
|
21
21
|
import { createServer } from "./server.js";
|
|
22
|
+
import { readEnv } from "./env.js";
|
|
22
23
|
const MAX_BODY_BYTES = 1 << 20; // 1 MiB — reject larger POST bodies (memory-DoS guard)
|
|
23
24
|
const MAX_SESSIONS = 256; // cap concurrent sessions (init-flood DoS guard)
|
|
24
25
|
const SESSION_IDLE_MS = 30 * 60 * 1000; // reap sessions idle longer than this
|
|
@@ -109,16 +110,18 @@ function authOk(header, expected) {
|
|
|
109
110
|
* an ephemeral `port: 0` bind still accepts its own address). Anything else —
|
|
110
111
|
* e.g. a rebound attacker domain — is rejected by the transport.
|
|
111
112
|
*/
|
|
112
|
-
function allowedHostsFor(server, host, port,
|
|
113
|
+
function allowedHostsFor(server, host, port, publicUrls = []) {
|
|
113
114
|
const addr = server.address();
|
|
114
115
|
const bound = addr && typeof addr === "object" ? addr.port : port;
|
|
115
116
|
const ports = Array.from(new Set([port, bound]));
|
|
116
117
|
const hosts = Array.from(new Set([host, "127.0.0.1", "localhost", "[::1]", "::1"]));
|
|
117
|
-
const configured = (
|
|
118
|
+
const configured = (readEnv("MCP_ALLOWED_HOSTS") || "")
|
|
118
119
|
.split(",")
|
|
119
120
|
.map((value) => value.trim())
|
|
120
121
|
.filter(Boolean);
|
|
121
|
-
|
|
122
|
+
for (const publicUrl of publicUrls) {
|
|
123
|
+
if (!URL.canParse(publicUrl))
|
|
124
|
+
continue;
|
|
122
125
|
const url = new URL(publicUrl);
|
|
123
126
|
configured.push(url.host, url.hostname);
|
|
124
127
|
}
|
|
@@ -134,8 +137,8 @@ function oauthUnauthorized(res, metadataUrl, scope) {
|
|
|
134
137
|
.end(JSON.stringify({ error: "unauthorized" }));
|
|
135
138
|
}
|
|
136
139
|
export function startHttp(client, port) {
|
|
137
|
-
const host =
|
|
138
|
-
const httpToken =
|
|
140
|
+
const host = readEnv("MCP_HTTP_HOST") || "127.0.0.1";
|
|
141
|
+
const httpToken = readEnv("MCP_HTTP_TOKEN") || "";
|
|
139
142
|
const isLoopback = host === "127.0.0.1" || host === "::1" || host === "localhost";
|
|
140
143
|
const oauthConfig = loadOAuthConfig();
|
|
141
144
|
const oauthVerifier = oauthConfig ? new OAuthTokenVerifier(oauthConfig) : null;
|
|
@@ -176,7 +179,7 @@ export function startHttp(client, port) {
|
|
|
176
179
|
const token = bearerToken(req.headers["authorization"]);
|
|
177
180
|
delegated = token ? await oauthVerifier.verify(token) : null;
|
|
178
181
|
if (!delegated) {
|
|
179
|
-
oauthUnauthorized(res, oauthConfig.
|
|
182
|
+
oauthUnauthorized(res, metadataUrlForHost(oauthConfig, req.headers.host), oauthConfig.scope);
|
|
180
183
|
return;
|
|
181
184
|
}
|
|
182
185
|
}
|
|
@@ -189,7 +192,7 @@ export function startHttp(client, port) {
|
|
|
189
192
|
if (existingEntry?.authorization &&
|
|
190
193
|
delegated &&
|
|
191
194
|
existingEntry.authorization.binding !== authorizationBinding(delegated)) {
|
|
192
|
-
oauthUnauthorized(res, oauthConfig.
|
|
195
|
+
oauthUnauthorized(res, metadataUrlForHost(oauthConfig, req.headers.host), oauthConfig.scope);
|
|
193
196
|
return;
|
|
194
197
|
}
|
|
195
198
|
if (existingEntry?.authorization && delegated) {
|
|
@@ -229,7 +232,7 @@ export function startHttp(client, port) {
|
|
|
229
232
|
// DNS-rebinding defense: only accept these Host headers, so a rebound
|
|
230
233
|
// attacker-domain request from a browser is rejected.
|
|
231
234
|
enableDnsRebindingProtection: true,
|
|
232
|
-
allowedHosts: allowedHostsFor(httpServer, host, port, oauthConfig
|
|
235
|
+
allowedHosts: allowedHostsFor(httpServer, host, port, oauthConfig ? [oauthConfig.publicUrl, ...oauthConfig.resources] : []),
|
|
233
236
|
onsessioninitialized: (id) => {
|
|
234
237
|
sessions.set(id, {
|
|
235
238
|
transport,
|
|
@@ -244,7 +247,7 @@ export function startHttp(client, port) {
|
|
|
244
247
|
sessions.delete(id);
|
|
245
248
|
};
|
|
246
249
|
const sessionClient = delegated
|
|
247
|
-
? new TenkiClient("",
|
|
250
|
+
? new TenkiClient("", readEnv("API_ENDPOINT", "API_URL") || undefined, {
|
|
248
251
|
workspaceId: delegated.workspaceId,
|
|
249
252
|
bearerTokenProvider: () => sessionAuthorization.apiDelegationToken,
|
|
250
253
|
})
|
package/dist/index.js
CHANGED
|
@@ -17,32 +17,33 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
|
|
|
17
17
|
import { TenkiClient } from "./client.js";
|
|
18
18
|
import { createServer } from "./server.js";
|
|
19
19
|
import { startHttp } from "./http.js";
|
|
20
|
+
import { readEnv } from "./env.js";
|
|
20
21
|
// A missing credential is NOT fatal: exiting here is reported by MCP clients as
|
|
21
22
|
// an opaque "server failed to start" with stderr usually swallowed, leaving the
|
|
22
23
|
// user with no idea a token is needed. Instead the server boots with only
|
|
23
24
|
// tenki_auth_status registered (see createServer), so an agent can ask what is
|
|
24
25
|
// wrong and relay the fix.
|
|
25
|
-
const token =
|
|
26
|
-
const oauthHttp = Boolean(
|
|
26
|
+
const token = readEnv("AUTH_TOKEN", "API_KEY");
|
|
27
|
+
const oauthHttp = Boolean(readEnv("MCP_OAUTH_ISSUER"));
|
|
27
28
|
if (!token && !oauthHttp) {
|
|
28
29
|
console.error("tenki-mcp: no credential — starting in unauthenticated mode (only tenki_auth_status is available). " +
|
|
29
30
|
"Set TENKI_API_KEY (tk_…) or TENKI_AUTH_TOKEN (ory_st_…) in the server's env and restart, " +
|
|
30
31
|
"e.g. claude mcp add tenki --env TENKI_API_KEY=tk_… -- npx -y @tenkicloud/mcp");
|
|
31
32
|
}
|
|
32
|
-
const baseUrl =
|
|
33
|
+
const baseUrl = readEnv("API_ENDPOINT", "API_URL") || undefined;
|
|
33
34
|
/** Positive integer from env, or undefined so the client keeps its own default. */
|
|
34
|
-
const envMs = (
|
|
35
|
-
const n = Number.parseInt(
|
|
35
|
+
const envMs = (suffix) => {
|
|
36
|
+
const n = Number.parseInt(readEnv(suffix) ?? "", 10);
|
|
36
37
|
return Number.isFinite(n) && n > 0 ? n : undefined;
|
|
37
38
|
};
|
|
38
39
|
const client = token
|
|
39
40
|
? new TenkiClient(token, baseUrl, {
|
|
40
|
-
timeoutMs: envMs("
|
|
41
|
-
slowTimeoutMs: envMs("
|
|
41
|
+
timeoutMs: envMs("MCP_TIMEOUT_MS"),
|
|
42
|
+
slowTimeoutMs: envMs("MCP_SLOW_TIMEOUT_MS"),
|
|
42
43
|
})
|
|
43
44
|
: null;
|
|
44
45
|
async function main() {
|
|
45
|
-
if ((
|
|
46
|
+
if ((readEnv("MCP_TRANSPORT") || "stdio").toLowerCase() === "http") {
|
|
46
47
|
const httpServer = startHttp(client, Number(process.env.PORT) || 3000);
|
|
47
48
|
for (const sig of ["SIGINT", "SIGTERM"]) {
|
|
48
49
|
process.on(sig, () => httpServer.close(() => process.exit(0)));
|
package/dist/oauth.d.ts
CHANGED
|
@@ -2,6 +2,8 @@ import type http from "node:http";
|
|
|
2
2
|
export interface OAuthConfig {
|
|
3
3
|
issuer: string;
|
|
4
4
|
resource: string;
|
|
5
|
+
/** Every accepted resource URI (first is `resource`), e.g. one per served domain. */
|
|
6
|
+
resources: string[];
|
|
5
7
|
publicUrl: string;
|
|
6
8
|
metadataUrl: string;
|
|
7
9
|
identityUrl: string;
|
|
@@ -27,7 +29,11 @@ export declare class OAuthTokenVerifier {
|
|
|
27
29
|
export declare class OAuthResourceRoutes {
|
|
28
30
|
private readonly config;
|
|
29
31
|
constructor(config: OAuthConfig);
|
|
30
|
-
handle(
|
|
32
|
+
handle(req: http.IncomingMessage, res: http.ServerResponse, url: URL): Promise<boolean>;
|
|
31
33
|
}
|
|
34
|
+
/** The configured resource whose host matches the request (RFC 9728 requires an exact match), else the first. */
|
|
35
|
+
export declare function resourceForHost(config: Pick<OAuthConfig, "resource" | "resources">, host: string | undefined): string;
|
|
36
|
+
/** Protected-resource metadata URL to advertise in a challenge, on the same host as the matched resource. */
|
|
37
|
+
export declare function metadataUrlForHost(config: Pick<OAuthConfig, "resources" | "publicUrl" | "metadataUrl">, host: string | undefined): string;
|
|
32
38
|
export declare function bearerToken(header: string | undefined): string | null;
|
|
33
39
|
export declare function authorizationBinding(authorization: DelegatedAuthorization): string;
|
package/dist/oauth.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
|
+
import { readEnv } from "./env.js";
|
|
2
3
|
const DEFAULT_SCOPE = "mcp";
|
|
3
4
|
const FETCH_TIMEOUT_MS = 8_000;
|
|
4
5
|
const TOKEN_CACHE_MS = 15_000;
|
|
@@ -7,24 +8,26 @@ function trimUrl(value) {
|
|
|
7
8
|
return value.trim().replace(/\/+$/, "");
|
|
8
9
|
}
|
|
9
10
|
export function loadOAuthConfig() {
|
|
10
|
-
const issuer = trimUrl(
|
|
11
|
-
const identityUrl = trimUrl(
|
|
12
|
-
const identityServiceToken = (
|
|
13
|
-
const publicUrl = trimUrl(
|
|
11
|
+
const issuer = trimUrl(readEnv("MCP_OAUTH_ISSUER") || "");
|
|
12
|
+
const identityUrl = trimUrl(readEnv("MCP_IDENTITY_URL") || "");
|
|
13
|
+
const identityServiceToken = (readEnv("MCP_IDENTITY_SERVICE_TOKEN") || "").trim();
|
|
14
|
+
const publicUrl = trimUrl(readEnv("MCP_PUBLIC_URL") || "");
|
|
14
15
|
if (!issuer && !identityUrl && !identityServiceToken && !publicUrl)
|
|
15
16
|
return null;
|
|
16
17
|
if (!issuer || !identityUrl || !identityServiceToken || !publicUrl) {
|
|
17
18
|
throw new Error("TENKI_MCP_OAUTH_ISSUER, TENKI_MCP_IDENTITY_URL, TENKI_MCP_IDENTITY_SERVICE_TOKEN, and TENKI_MCP_PUBLIC_URL must be set together.");
|
|
18
19
|
}
|
|
19
|
-
const
|
|
20
|
+
const configured = (readEnv("MCP_OAUTH_RESOURCE") || "").split(",").map(trimUrl).filter(Boolean);
|
|
21
|
+
const resources = configured.length ? Array.from(new Set(configured)) : [`${publicUrl}/mcp`];
|
|
20
22
|
return {
|
|
21
23
|
issuer,
|
|
22
|
-
resource,
|
|
24
|
+
resource: resources[0],
|
|
25
|
+
resources,
|
|
23
26
|
publicUrl,
|
|
24
27
|
metadataUrl: `${publicUrl}/.well-known/oauth-protected-resource/mcp`,
|
|
25
28
|
identityUrl,
|
|
26
29
|
identityServiceToken,
|
|
27
|
-
scope: (
|
|
30
|
+
scope: (readEnv("MCP_OAUTH_SCOPE") || DEFAULT_SCOPE).trim(),
|
|
28
31
|
};
|
|
29
32
|
}
|
|
30
33
|
function tokenDigest(token) {
|
|
@@ -117,10 +120,10 @@ export class OAuthResourceRoutes {
|
|
|
117
120
|
constructor(config) {
|
|
118
121
|
this.config = config;
|
|
119
122
|
}
|
|
120
|
-
async handle(
|
|
123
|
+
async handle(req, res, url) {
|
|
121
124
|
if (url.pathname === "/.well-known/oauth-protected-resource/mcp" || url.pathname === "/.well-known/oauth-protected-resource") {
|
|
122
125
|
json(res, 200, {
|
|
123
|
-
resource: this.config.
|
|
126
|
+
resource: resourceForHost(this.config, req.headers.host),
|
|
124
127
|
authorization_servers: [this.config.issuer],
|
|
125
128
|
scopes_supported: [this.config.scope, "offline_access"],
|
|
126
129
|
bearer_methods_supported: ["header"],
|
|
@@ -135,6 +138,23 @@ export class OAuthResourceRoutes {
|
|
|
135
138
|
return false;
|
|
136
139
|
}
|
|
137
140
|
}
|
|
141
|
+
/** The configured resource whose host matches the request (RFC 9728 requires an exact match), else the first. */
|
|
142
|
+
export function resourceForHost(config, host) {
|
|
143
|
+
const wanted = (host ?? "").toLowerCase();
|
|
144
|
+
return config.resources.find((resource) => urlHost(resource) === wanted) ?? config.resource;
|
|
145
|
+
}
|
|
146
|
+
/** Protected-resource metadata URL to advertise in a challenge, on the same host as the matched resource. */
|
|
147
|
+
export function metadataUrlForHost(config, host) {
|
|
148
|
+
const wanted = (host ?? "").toLowerCase();
|
|
149
|
+
const matched = config.resources.find((resource) => urlHost(resource) === wanted);
|
|
150
|
+
if (!matched || wanted === urlHost(config.publicUrl))
|
|
151
|
+
return config.metadataUrl;
|
|
152
|
+
return `${new URL(matched).origin}/.well-known/oauth-protected-resource/mcp`;
|
|
153
|
+
}
|
|
154
|
+
/** Lowercased host of a URL, or undefined when it does not parse (a resource may be any absolute URI). */
|
|
155
|
+
function urlHost(value) {
|
|
156
|
+
return URL.canParse(value) ? new URL(value).host.toLowerCase() : undefined;
|
|
157
|
+
}
|
|
138
158
|
export function bearerToken(header) {
|
|
139
159
|
const match = /^Bearer (.+)$/.exec(header ?? "");
|
|
140
160
|
return match?.[1]?.trim() || null;
|
package/dist/server.d.ts
CHANGED
|
@@ -4,8 +4,9 @@
|
|
|
4
4
|
*
|
|
5
5
|
* Security controls (see SECURITY.md; maps to CSA MCP Server Top-10 MCP-07
|
|
6
6
|
* "excessive permissions"). Every tool is registered through a guard that:
|
|
7
|
-
* 1.
|
|
8
|
-
* so clients can surface
|
|
7
|
+
* 1. gives it a human-readable title (tools/titles.ts) and MCP annotations
|
|
8
|
+
* (readOnlyHint / destructiveHint / openWorldHint) so clients can surface
|
|
9
|
+
* or gate dangerous tools;
|
|
9
10
|
* 2. enforces least-privilege via env:
|
|
10
11
|
* TENKI_MCP_READONLY=1 → register ONLY read tools (no create/run/delete/spend)
|
|
11
12
|
* TENKI_MCP_DISABLED_TOOLS=a,b → skip these named tools
|
|
@@ -14,9 +15,28 @@
|
|
|
14
15
|
*/
|
|
15
16
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
16
17
|
import type { TenkiClient } from "./client.js";
|
|
17
|
-
export declare const VERSION = "0.
|
|
18
|
-
|
|
18
|
+
export declare const VERSION = "0.4.1";
|
|
19
|
+
/**
|
|
20
|
+
* Tool classes, mapped to MCP annotations by annotationsFor():
|
|
21
|
+
* read → readOnlyHint: true. Pure inspection: no state change, no spend.
|
|
22
|
+
* additive → readOnlyHint: false, destructiveHint: false. Only creates new
|
|
23
|
+
* things or extends existing ones (a sandbox, a snapshot, more
|
|
24
|
+
* lifetime, a keep-alive); never changes or removes what exists.
|
|
25
|
+
* destructive → readOnlyHint: false, destructiveHint: true. May overwrite,
|
|
26
|
+
* modify, interrupt or delete existing state.
|
|
27
|
+
*
|
|
28
|
+
* Destructive is the DEFAULT for anything that is not a read: a non-read tool
|
|
29
|
+
* is additive only when it is listed in ADDITIVE. MCP defines
|
|
30
|
+
* `destructiveHint: false` as "performs only additive updates", and clients use
|
|
31
|
+
* it to decide whether to ask before a call, so an unlisted new tool must fail
|
|
32
|
+
* safe (prompt) rather than claim to be harmless.
|
|
33
|
+
*/
|
|
34
|
+
type Cls = "read" | "additive" | "destructive";
|
|
19
35
|
export declare function classifyTool(name: string): Cls;
|
|
36
|
+
/** Title for a tool: the TOOL_TITLES entry, else one derived from the name so
|
|
37
|
+
* a tool is never advertised without a title (the offline suite fails on a
|
|
38
|
+
* missing entry, so the fallback only guards production). */
|
|
39
|
+
export declare function titleFor(name: string): string;
|
|
20
40
|
/**
|
|
21
41
|
* Build a fresh MCP server instance with all tools registered against `client`.
|
|
22
42
|
*
|
|
@@ -24,7 +44,7 @@ export declare function classifyTool(name: string): Cls;
|
|
|
24
44
|
* start — which MCP clients report as an opaque "server failed to start" —
|
|
25
45
|
* the server boots with ONLY tenki_auth_status registered, so an agent can
|
|
26
46
|
* discover and explain the missing credential. Registering the other tools in
|
|
27
|
-
* that state would offer
|
|
47
|
+
* that state would offer 82 tools that can only fail.
|
|
28
48
|
*/
|
|
29
49
|
export declare function createServer(client: TenkiClient | null): McpServer;
|
|
30
50
|
export {};
|
package/dist/server.js
CHANGED
|
@@ -4,8 +4,9 @@
|
|
|
4
4
|
*
|
|
5
5
|
* Security controls (see SECURITY.md; maps to CSA MCP Server Top-10 MCP-07
|
|
6
6
|
* "excessive permissions"). Every tool is registered through a guard that:
|
|
7
|
-
* 1.
|
|
8
|
-
* so clients can surface
|
|
7
|
+
* 1. gives it a human-readable title (tools/titles.ts) and MCP annotations
|
|
8
|
+
* (readOnlyHint / destructiveHint / openWorldHint) so clients can surface
|
|
9
|
+
* or gate dangerous tools;
|
|
9
10
|
* 2. enforces least-privilege via env:
|
|
10
11
|
* TENKI_MCP_READONLY=1 → register ONLY read tools (no create/run/delete/spend)
|
|
11
12
|
* TENKI_MCP_DISABLED_TOOLS=a,b → skip these named tools
|
|
@@ -29,8 +30,11 @@ import { registerTemplates } from "./tools/templates.js";
|
|
|
29
30
|
import { registerWorkspace } from "./tools/workspace.js";
|
|
30
31
|
import { registerArtifacts } from "./tools/artifacts.js";
|
|
31
32
|
import { registerSsh } from "./tools/ssh.js";
|
|
33
|
+
import { registerEgress } from "./tools/egress.js";
|
|
32
34
|
import { registerAuthStatus } from "./tools/auth_status.js";
|
|
33
|
-
|
|
35
|
+
import { readEnv } from "./env.js";
|
|
36
|
+
import { TOOL_TITLES } from "./tools/titles.js";
|
|
37
|
+
export const VERSION = "0.4.1";
|
|
34
38
|
const modules = [
|
|
35
39
|
registerIdentity,
|
|
36
40
|
registerRun,
|
|
@@ -44,40 +48,75 @@ const modules = [
|
|
|
44
48
|
registerPreviews,
|
|
45
49
|
registerSnapshots,
|
|
46
50
|
registerVolumes,
|
|
51
|
+
registerEgress,
|
|
47
52
|
registerTemplates,
|
|
48
53
|
registerWorkspace,
|
|
49
54
|
registerArtifacts,
|
|
50
55
|
registerSsh,
|
|
51
56
|
];
|
|
52
|
-
// Destroys/removes/revokes a resource
|
|
57
|
+
// Destroys/removes/revokes a resource. Checked first, so a name with one of
|
|
58
|
+
// these prefixes is destructive even if it is mistakenly listed in ADDITIVE.
|
|
53
59
|
const DESTRUCTIVE = /^tenki_(terminate|delete|remove|unshare|revoke|detach|unexpose|unbind)/;
|
|
54
|
-
// Named exceptions that match the READ prefix below but actually grant a
|
|
55
|
-
// write/spend capability, so they must never be treated as read-only.
|
|
56
|
-
// tenki_get_upload_url returns a signed URL for an arbitrary PUT into the sandbox.
|
|
57
|
-
const WRITE_OVERRIDE = new Set(["tenki_get_upload_url"]);
|
|
58
|
-
// Named exceptions that are pure reads but don't match the READ prefix below.
|
|
59
|
-
// tenki_auth_status only inspects the ambient credential + probes WhoAmI, so it
|
|
60
|
-
// must stay available under TENKI_MCP_READONLY (it is how an operator diagnoses
|
|
61
|
-
// a credential problem in that posture).
|
|
62
|
-
const READ_OVERRIDE = new Set(["tenki_auth_status"]);
|
|
63
60
|
// Pure inspection, no state change / no spend → readOnlyHint.
|
|
64
61
|
const READ = /^tenki_(get|list|whoami|resolve|stat|read)/;
|
|
62
|
+
// Names that match the READ prefix but are not reads. tenki_get_upload_url
|
|
63
|
+
// returns a signed URL for an HTTP PUT that can overwrite a file in the sandbox.
|
|
64
|
+
const NOT_READ = new Set(["tenki_get_upload_url"]);
|
|
65
|
+
// Pure reads that don't match the READ prefix. tenki_auth_status only inspects
|
|
66
|
+
// the ambient credential + probes WhoAmI, so it must stay available under
|
|
67
|
+
// TENKI_MCP_READONLY (it is how an operator diagnoses a credential problem in
|
|
68
|
+
// that posture). git diff/log only read the repository.
|
|
69
|
+
const READ_OVERRIDE = new Set(["tenki_auth_status", "tenki_git_diff", "tenki_git_log"]);
|
|
70
|
+
// Non-read tools that only add. Everything else that is not a read is
|
|
71
|
+
// destructive — see the class comment above for why that is the default.
|
|
72
|
+
const ADDITIVE = new Set([
|
|
73
|
+
"tenki_run_code", // boots, uses and tears down its own throwaway sandbox
|
|
74
|
+
"tenki_create_sandbox",
|
|
75
|
+
"tenki_fork_sandbox", // the source keeps running; children are new sandboxes
|
|
76
|
+
"tenki_resume_sandbox",
|
|
77
|
+
"tenki_extend_sandbox",
|
|
78
|
+
"tenki_report_sandbox_activity", // keep-alive
|
|
79
|
+
"tenki_make_dir",
|
|
80
|
+
"tenki_git_clone", // git refuses a non-empty target directory
|
|
81
|
+
"tenki_expose_port",
|
|
82
|
+
"tenki_create_preview_url",
|
|
83
|
+
"tenki_touch_preview", // keep-alive
|
|
84
|
+
"tenki_create_snapshot",
|
|
85
|
+
"tenki_create_volume",
|
|
86
|
+
"tenki_attach_volume",
|
|
87
|
+
"tenki_create_egress_policy",
|
|
88
|
+
"tenki_create_template",
|
|
89
|
+
// Not tenki_build_template: a build with image_name publishes a new latest
|
|
90
|
+
// version, which changes what an existing `workspace/name` reference boots.
|
|
91
|
+
"tenki_issue_ssh_cert",
|
|
92
|
+
]);
|
|
65
93
|
export function classifyTool(name) {
|
|
66
94
|
if (DESTRUCTIVE.test(name))
|
|
67
95
|
return "destructive";
|
|
68
|
-
if (
|
|
69
|
-
return "write";
|
|
70
|
-
if (READ_OVERRIDE.has(name) || READ.test(name))
|
|
96
|
+
if (!NOT_READ.has(name) && (READ_OVERRIDE.has(name) || READ.test(name)))
|
|
71
97
|
return "read";
|
|
72
|
-
|
|
98
|
+
if (ADDITIVE.has(name))
|
|
99
|
+
return "additive";
|
|
100
|
+
return "destructive";
|
|
101
|
+
}
|
|
102
|
+
/** Title for a tool: the TOOL_TITLES entry, else one derived from the name so
|
|
103
|
+
* a tool is never advertised without a title (the offline suite fails on a
|
|
104
|
+
* missing entry, so the fallback only guards production). */
|
|
105
|
+
export function titleFor(name) {
|
|
106
|
+
return (TOOL_TITLES[name] ??
|
|
107
|
+
name
|
|
108
|
+
.replace(/^tenki_/, "")
|
|
109
|
+
.split("_")
|
|
110
|
+
.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
|
|
111
|
+
.join(" "));
|
|
73
112
|
}
|
|
74
113
|
function readGuardOpts() {
|
|
75
114
|
const truthy = (v) => v === "1" || (v ?? "").toLowerCase() === "true";
|
|
76
|
-
const disabled = new Set((
|
|
115
|
+
const disabled = new Set((readEnv("MCP_DISABLED_TOOLS") || "")
|
|
77
116
|
.split(",")
|
|
78
117
|
.map((s) => s.trim())
|
|
79
118
|
.filter(Boolean));
|
|
80
|
-
return { readonly: truthy(
|
|
119
|
+
return { readonly: truthy(readEnv("MCP_READONLY")), disabled, audit: truthy(readEnv("MCP_AUDIT")) };
|
|
81
120
|
}
|
|
82
121
|
/** Log a tool call's name + argument KEYS (never values/content/token) to stderr. */
|
|
83
122
|
function auditKeys(args) {
|
|
@@ -87,8 +126,9 @@ function auditKeys(args) {
|
|
|
87
126
|
return keys.length ? ` args=[${keys.join(",")}]` : "";
|
|
88
127
|
}
|
|
89
128
|
/** MCP annotations derived from a tool's classification. */
|
|
90
|
-
function annotationsFor(cls) {
|
|
129
|
+
function annotationsFor(name, cls) {
|
|
91
130
|
return {
|
|
131
|
+
title: titleFor(name),
|
|
92
132
|
readOnlyHint: cls === "read",
|
|
93
133
|
destructiveHint: cls === "destructive",
|
|
94
134
|
idempotentHint: cls === "read",
|
|
@@ -128,45 +168,40 @@ function noopToolHandle() {
|
|
|
128
168
|
};
|
|
129
169
|
}
|
|
130
170
|
/**
|
|
131
|
-
* Wrap a server so every tool registration from a module is annotated
|
|
132
|
-
* to the least-privilege env controls above. Both registration APIs
|
|
133
|
-
* the legacy `.tool(name, description, schema, handler)` form and
|
|
134
|
-
* `.registerTool(name, config, handler)` form (the only one that
|
|
135
|
-
* outputSchema) — so neither path can bypass
|
|
136
|
-
* the denylist.
|
|
171
|
+
* Wrap a server so every tool registration from a module is titled, annotated
|
|
172
|
+
* and subject to the least-privilege env controls above. Both registration APIs
|
|
173
|
+
* are guarded: the legacy `.tool(name, description, schema, handler)` form and
|
|
174
|
+
* the modern `.registerTool(name, config, handler)` form (the only one that
|
|
175
|
+
* accepts an outputSchema) — so neither path can bypass titles, annotations,
|
|
176
|
+
* read-only mode, or the denylist. Legacy calls are re-issued as registerTool,
|
|
177
|
+
* because the SDK's tool() overloads have no title parameter (MCP `Tool.title`
|
|
178
|
+
* would be undefined). Other access passes through to the real server unchanged.
|
|
137
179
|
*/
|
|
138
180
|
function guard(server, opts) {
|
|
181
|
+
const register = (target, name, config, handler) => {
|
|
182
|
+
const cls = classifyTool(name);
|
|
183
|
+
if (opts.disabled.has(name))
|
|
184
|
+
return noopToolHandle(); // explicit denylist
|
|
185
|
+
if (opts.readonly && cls !== "read")
|
|
186
|
+
return noopToolHandle(); // read-only posture: skip anything that mutates/spends
|
|
187
|
+
if (opts.registered)
|
|
188
|
+
opts.registered.count++;
|
|
189
|
+
// Name-derived classification and title stay authoritative so a module
|
|
190
|
+
// cannot soften the hints; other annotation fields pass through.
|
|
191
|
+
const annotations = {
|
|
192
|
+
...config.annotations,
|
|
193
|
+
...annotationsFor(name, cls),
|
|
194
|
+
};
|
|
195
|
+
return target.registerTool(name, { ...config, title: titleFor(name), annotations }, withAudit(name, handler, opts.audit));
|
|
196
|
+
};
|
|
139
197
|
return new Proxy(server, {
|
|
140
198
|
get(target, prop, receiver) {
|
|
141
199
|
if (prop === "tool") {
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
if (opts.disabled.has(name))
|
|
145
|
-
return noopToolHandle(); // explicit denylist
|
|
146
|
-
if (opts.readonly && cls !== "read")
|
|
147
|
-
return noopToolHandle(); // read-only posture: skip anything that mutates/spends
|
|
148
|
-
if (opts.registered)
|
|
149
|
-
opts.registered.count++;
|
|
150
|
-
return target.tool(name, description, schema, annotationsFor(cls), withAudit(name, handler, opts.audit));
|
|
151
|
-
};
|
|
200
|
+
// Every module uses the four-argument form; a schema-less tool passes {}.
|
|
201
|
+
return (name, description, schema, handler) => register(target, name, { description, inputSchema: schema }, handler);
|
|
152
202
|
}
|
|
153
203
|
if (prop === "registerTool") {
|
|
154
|
-
return (name, config, handler) =>
|
|
155
|
-
const cls = classifyTool(name);
|
|
156
|
-
if (opts.disabled.has(name))
|
|
157
|
-
return noopToolHandle(); // explicit denylist
|
|
158
|
-
if (opts.readonly && cls !== "read")
|
|
159
|
-
return noopToolHandle(); // read-only posture: skip anything that mutates/spends
|
|
160
|
-
// Name-derived classification stays authoritative for the four hints so
|
|
161
|
-
// a module cannot soften them; other annotation fields pass through.
|
|
162
|
-
if (opts.registered)
|
|
163
|
-
opts.registered.count++;
|
|
164
|
-
const annotations = {
|
|
165
|
-
...config.annotations,
|
|
166
|
-
...annotationsFor(cls),
|
|
167
|
-
};
|
|
168
|
-
return target.registerTool(name, { ...config, annotations }, withAudit(name, handler, opts.audit));
|
|
169
|
-
};
|
|
204
|
+
return (name, config, handler) => register(target, name, config, handler);
|
|
170
205
|
}
|
|
171
206
|
return Reflect.get(target, prop, receiver);
|
|
172
207
|
},
|
|
@@ -179,7 +214,7 @@ function guard(server, opts) {
|
|
|
179
214
|
* start — which MCP clients report as an opaque "server failed to start" —
|
|
180
215
|
* the server boots with ONLY tenki_auth_status registered, so an agent can
|
|
181
216
|
* discover and explain the missing credential. Registering the other tools in
|
|
182
|
-
* that state would offer
|
|
217
|
+
* that state would offer 82 tools that can only fail.
|
|
183
218
|
*/
|
|
184
219
|
export function createServer(client) {
|
|
185
220
|
const server = new McpServer({ name: "tenki", version: VERSION });
|
|
@@ -7,9 +7,9 @@
|
|
|
7
7
|
* GetArtifactDownloadUrl to GET one out. These tools return the signed URL; the
|
|
8
8
|
* caller performs the actual HTTP PUT/GET.
|
|
9
9
|
*
|
|
10
|
-
* GetArtifactUploadUrlRequest {
|
|
11
|
-
*
|
|
12
|
-
*
|
|
10
|
+
* GetArtifactUploadUrlRequest is { session_id, path, content_type }.
|
|
11
|
+
* GetArtifactDownloadUrlRequest is { artifact_id } ONLY — there is no session_id
|
|
12
|
+
* field (the API discards unknown fields silently), so the tool no longer requires one.
|
|
13
13
|
*/
|
|
14
14
|
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
15
15
|
import type { TenkiClient } from "../client.js";
|
package/dist/tools/artifacts.js
CHANGED
|
@@ -10,10 +10,10 @@ export function registerArtifacts(server, client) {
|
|
|
10
10
|
path,
|
|
11
11
|
...(content_type ? { contentType: content_type } : {}),
|
|
12
12
|
})));
|
|
13
|
-
server.tool("tenki_get_download_url", "Get a short-lived signed URL to download (HTTP GET)
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
async ({
|
|
13
|
+
server.tool("tenki_get_download_url", "Get a short-lived signed URL to download (HTTP GET) an artifact by its artifact id (e.g. the artifactId returned by tenki_get_upload_url, or a template build's buildLogArtifactId). The API supports download-by-artifact-id only, not download-by-path.", {
|
|
14
|
+
artifact_id: z.string().describe("Artifact id (UUID) to download."),
|
|
15
|
+
session_id: sessionIdSchema
|
|
16
|
+
.optional()
|
|
17
|
+
.describe("Ignored — kept for backwards compatibility; the API addresses artifacts by id alone."),
|
|
18
|
+
}, async ({ artifact_id }) => ok(await client.control("GetArtifactDownloadUrl", { artifactId: artifact_id })));
|
|
19
19
|
}
|
|
@@ -18,13 +18,13 @@ export type CredentialKind = "none" | "api_key" | "oauth_session_token" | "sessi
|
|
|
18
18
|
export interface CredentialInfo {
|
|
19
19
|
kind: CredentialKind;
|
|
20
20
|
/** Env var the token came from, or undefined when there is none. */
|
|
21
|
-
source?: "TENKI_AUTH_TOKEN" | "TENKI_API_KEY";
|
|
21
|
+
source?: "LUXORAI_AUTH_TOKEN" | "LUXORAI_API_KEY" | "TENKI_AUTH_TOKEN" | "TENKI_API_KEY";
|
|
22
22
|
}
|
|
23
23
|
/**
|
|
24
24
|
* Classify the ambient credential WITHOUT returning any of its material.
|
|
25
|
-
* Mirrors the header selection in client.ts (`tk_` → Bearer API key,
|
|
25
|
+
* Mirrors the header selection in client.ts (`lx_`/`tk_` → Bearer API key,
|
|
26
26
|
* `ory_st_` → OAuth/Ory session token, anything else → session cookie) and
|
|
27
|
-
* index.ts's precedence (
|
|
27
|
+
* index.ts's precedence (LUXORAI_AUTH_TOKEN, LUXORAI_API_KEY, TENKI_AUTH_TOKEN, TENKI_API_KEY).
|
|
28
28
|
*/
|
|
29
29
|
export declare function describeCredential(env?: NodeJS.ProcessEnv): CredentialInfo;
|
|
30
30
|
/**
|
|
@@ -1,20 +1,19 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
+
import { isApiKey, readEnv, resolvedEnvName } from "../env.js";
|
|
2
3
|
/**
|
|
3
4
|
* Classify the ambient credential WITHOUT returning any of its material.
|
|
4
|
-
* Mirrors the header selection in client.ts (`tk_` → Bearer API key,
|
|
5
|
+
* Mirrors the header selection in client.ts (`lx_`/`tk_` → Bearer API key,
|
|
5
6
|
* `ory_st_` → OAuth/Ory session token, anything else → session cookie) and
|
|
6
|
-
* index.ts's precedence (
|
|
7
|
+
* index.ts's precedence (LUXORAI_AUTH_TOKEN, LUXORAI_API_KEY, TENKI_AUTH_TOKEN, TENKI_API_KEY).
|
|
7
8
|
*/
|
|
8
9
|
export function describeCredential(env = process.env) {
|
|
9
|
-
const
|
|
10
|
-
const
|
|
11
|
-
|
|
12
|
-
if (!raw && env.TENKI_MCP_OAUTH_ISSUER?.trim())
|
|
10
|
+
const source = resolvedEnvName(env, "AUTH_TOKEN", "API_KEY");
|
|
11
|
+
const raw = source ? env[source].trim() : "";
|
|
12
|
+
if (!raw && resolvedEnvName(env, "MCP_OAUTH_ISSUER"))
|
|
13
13
|
return { kind: "hosted_oauth" };
|
|
14
14
|
if (!raw)
|
|
15
15
|
return { kind: "none" };
|
|
16
|
-
|
|
17
|
-
if (raw.startsWith("tk_"))
|
|
16
|
+
if (isApiKey(raw))
|
|
18
17
|
return { kind: "api_key", source };
|
|
19
18
|
if (raw.startsWith("ory_st_"))
|
|
20
19
|
return { kind: "oauth_session_token", source };
|
|
@@ -64,7 +63,7 @@ export function registerAuthStatus(server, client, toolsRegistered) {
|
|
|
64
63
|
outputSchema: authOutputSchema,
|
|
65
64
|
}, async () => {
|
|
66
65
|
const cred = describeCredential();
|
|
67
|
-
const endpoint =
|
|
66
|
+
const endpoint = readEnv("API_ENDPOINT", "API_URL") || "https://api.tenki.cloud";
|
|
68
67
|
const base = {
|
|
69
68
|
credential: cred.kind,
|
|
70
69
|
...(cred.source ? { source: cred.source } : {}),
|