terminal-commands 0.1.1

package/src/device-auth.ts

@@ -0,0 +1,163 @@
+import { z } from "zod";
+
+export interface DeviceAuthConfig {
+  issuer: string;
+  clientId: string;
+  audience: string;
+  scope: string;
+}
+
+export interface StoredCredentials {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt: number;
+  scope?: string;
+  tokenType?: string;
+  issuer: string;
+  audience: string;
+}
+
+export type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+const deviceCodeSchema = z.object({
+  device_code: z.string().min(1),
+  user_code: z.string().min(1),
+  verification_uri: z.string().url(),
+  verification_uri_complete: z.string().url().optional(),
+  expires_in: z.number().int().positive(),
+  interval: z.number().int().positive().default(5),
+});
+
+const tokenSchema = z.object({
+  access_token: z.string().min(1),
+  refresh_token: z.string().min(1).optional(),
+  expires_in: z.number().int().positive(),
+  scope: z.string().optional(),
+  token_type: z.string().optional(),
+});
+
+function endpoint(issuer: string, path: string): string {
+  return new URL(path, issuer.endsWith("/") ? issuer : `${issuer}/`).toString();
+}
+
+async function postForm(
+  url: string,
+  values: Record<string, string>,
+  fetchImpl: FetchLike,
+): Promise<Response> {
+  return fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(values),
+  });
+}
+
+export async function requestDeviceCode(
+  config: DeviceAuthConfig,
+  fetchImpl: FetchLike = fetch,
+) {
+  const response = await postForm(
+    endpoint(config.issuer, "oauth/device/code"),
+    {
+      client_id: config.clientId,
+      audience: config.audience,
+      scope: config.scope,
+    },
+    fetchImpl,
+  );
+  if (!response.ok)
+    throw new Error(`Device login could not start (${response.status}).`);
+  return deviceCodeSchema.parse(await response.json());
+}
+
+export async function pollForDeviceToken(
+  config: DeviceAuthConfig,
+  deviceCode: string,
+  expiresInSeconds: number,
+  intervalSeconds: number,
+  signal?: AbortSignal,
+  fetchImpl: FetchLike = fetch,
+): Promise<StoredCredentials> {
+  const deadline = Date.now() + expiresInSeconds * 1_000;
+  let intervalMs = Math.max(intervalSeconds, 1) * 1_000;
+
+  while (Date.now() < deadline) {
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(resolve, intervalMs);
+      signal?.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          reject(new Error("Login cancelled."));
+        },
+        { once: true },
+      );
+    });
+
+    const response = await postForm(
+      endpoint(config.issuer, "oauth/token"),
+      {
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+        device_code: deviceCode,
+        client_id: config.clientId,
+      },
+      fetchImpl,
+    );
+    const body = (await response.json()) as Record<string, unknown>;
+    if (response.ok) {
+      const token = tokenSchema.parse(body);
+      return {
+        accessToken: token.access_token,
+        refreshToken: token.refresh_token,
+        expiresAt: Date.now() + token.expires_in * 1_000,
+        scope: token.scope,
+        tokenType: token.token_type,
+        issuer: config.issuer,
+        audience: config.audience,
+      };
+    }
+    if (body.error === "authorization_pending") continue;
+    if (body.error === "slow_down") {
+      intervalMs += 5_000;
+      continue;
+    }
+    if (body.error === "expired_token") break;
+    throw new Error(
+      `Device login failed: ${String(body.error_description ?? body.error ?? response.status)}`,
+    );
+  }
+  throw new Error("Device login expired. Run login again.");
+}
+
+export async function refreshDeviceToken(
+  config: DeviceAuthConfig,
+  refreshToken: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<StoredCredentials> {
+  const response = await postForm(
+    endpoint(config.issuer, "oauth/token"),
+    {
+      grant_type: "refresh_token",
+      client_id: config.clientId,
+      refresh_token: refreshToken,
+    },
+    fetchImpl,
+  );
+  if (!response.ok)
+    throw new Error(
+      "Saved login expired. Run `terminal-commands login` again.",
+    );
+  const token = tokenSchema.parse(await response.json());
+  return {
+    accessToken: token.access_token,
+    refreshToken: token.refresh_token ?? refreshToken,
+    expiresAt: Date.now() + token.expires_in * 1_000,
+    scope: token.scope,
+    tokenType: token.token_type,
+    issuer: config.issuer,
+    audience: config.audience,
+  };
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Request, Response } from "express";
+
+import { createServer } from "./server.js";
+
+const host = process.env.MACHINE_TERMINAL_HOST ?? "127.0.0.1";
+const port = Number.parseInt(process.env.MACHINE_TERMINAL_PORT ?? "3333", 10);
+const localHosts = new Set(["127.0.0.1", "::1", "localhost"]);
+
+if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+  throw new Error("MACHINE_TERMINAL_PORT must be a valid TCP port.");
+}
+if (
+  !localHosts.has(host) &&
+  process.env.MACHINE_TERMINAL_ALLOW_PUBLIC_BIND !== "1"
+) {
+  throw new Error(
+    "Refusing a non-loopback bind. Set MACHINE_TERMINAL_ALLOW_PUBLIC_BIND=1 only behind authenticated HTTPS.",
+  );
+}
+
+const app = createMcpExpressApp({ host });
+
+app.get("/health", (_request: Request, response: Response) => {
+  response.json({
+    status: "ok",
+    server: "terminal-commands",
+    version: "0.1.0",
+  });
+});
+
+app.post("/mcp", async (request: Request, response: Response) => {
+  const server = createServer();
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  });
+  response.on("close", () => {
+    void transport.close();
+    void server.close();
+  });
+
+  try {
+    await server.connect(transport);
+    await transport.handleRequest(request, response, request.body);
+  } catch (error) {
+    console.error("MCP request failed", error);
+    if (!response.headersSent) {
+      response.status(500).json({
+        jsonrpc: "2.0",
+        error: { code: -32603, message: "Internal server error" },
+        id: null,
+      });
+    }
+  }
+});
+
+for (const method of ["get", "delete"] as const) {
+  app[method]("/mcp", (_request: Request, response: Response) => {
+    response.status(405).json({
+      jsonrpc: "2.0",
+      error: { code: -32000, message: "Method not allowed" },
+      id: null,
+    });
+  });
+}
+
+const listener = app.listen(port, host, () => {
+  console.log(`Terminal Commands MCP listening at http://${host}:${port}/mcp`);
+});
+
+function shutdown(signal: string) {
+  console.log(`Received ${signal}; shutting down.`);
+  listener.close((error?: Error) => {
+    if (error) {
+      console.error(error);
+      process.exitCode = 1;
+    }
+  });
+}
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));

package/src/runner.ts

@@ -0,0 +1,55 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { assertProgramAllowed, safeEnvironment } from "./security.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface ProgramResult {
+  exitCode: number | null;
+  signal: string | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+export async function runProgram(options: {
+  program: string;
+  args: string[];
+  cwd: string;
+  timeoutMs: number;
+  maxOutputChars: number;
+}): Promise<ProgramResult> {
+  assertProgramAllowed(options.program);
+
+  try {
+    const { stdout, stderr } = await execFileAsync(
+      options.program,
+      options.args,
+      {
+        cwd: options.cwd,
+        env: safeEnvironment(),
+        encoding: "utf8",
+        maxBuffer: options.maxOutputChars,
+        timeout: options.timeoutMs,
+        windowsHide: true,
+      },
+    );
+    return { exitCode: 0, signal: null, stdout, stderr, timedOut: false };
+  } catch (error) {
+    const failure = error as NodeJS.ErrnoException & {
+      code?: number | string;
+      killed?: boolean;
+      signal?: string;
+      stdout?: string;
+      stderr?: string;
+    };
+    return {
+      exitCode: typeof failure.code === "number" ? failure.code : null,
+      signal: failure.signal ?? null,
+      stdout: failure.stdout ?? "",
+      stderr: failure.stderr ?? failure.message,
+      timedOut: failure.killed === true && failure.signal === "SIGTERM",
+    };
+  }
+}

package/src/security.ts

@@ -0,0 +1,112 @@
+import { constants } from "node:fs";
+import { access, lstat, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const DEFAULT_ENVIRONMENT_KEYS = [
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "PATH",
+  "SHELL",
+  "TERM",
+  "TMPDIR",
+  "USER",
+] as const;
+
+const DEFAULT_BLOCKED_PROGRAMS = new Set([
+  "bash",
+  "cmd",
+  "cmd.exe",
+  "fish",
+  "powershell",
+  "powershell.exe",
+  "pwsh",
+  "sh",
+  "sudo",
+  "su",
+  "zsh",
+]);
+
+export function configuredRoots(
+  raw = process.env.MACHINE_TERMINAL_ROOTS,
+): string[] {
+  const candidates = raw?.split(path.delimiter).filter(Boolean) ?? [
+    process.cwd(),
+  ];
+  return [...new Set(candidates.map((candidate) => path.resolve(candidate)))];
+}
+
+export function isWithinRoot(candidate: string, root: string): boolean {
+  const relative = path.relative(root, candidate);
+  return (
+    relative === "" ||
+    (!relative.startsWith(`..${path.sep}`) && relative !== "..")
+  );
+}
+
+export async function resolveReadablePath(
+  requestedPath: string,
+  roots: string[],
+  cwd = roots[0] ?? os.homedir(),
+): Promise<string> {
+  const resolvedRoots = await Promise.all(roots.map((root) => realpath(root)));
+  const candidate = await realpath(path.resolve(cwd, requestedPath));
+  if (!resolvedRoots.some((root) => isWithinRoot(candidate, root))) {
+    throw new Error("Path is outside MACHINE_TERMINAL_ROOTS.");
+  }
+  await access(candidate, constants.R_OK);
+  return candidate;
+}
+
+export async function resolveWritablePath(
+  requestedPath: string,
+  roots: string[],
+  cwd = roots[0] ?? os.homedir(),
+): Promise<string> {
+  const absolute = path.resolve(cwd, requestedPath);
+  const resolvedParent = await realpath(path.dirname(absolute));
+  const resolvedRoots = await Promise.all(roots.map((root) => realpath(root)));
+  const candidate = path.join(resolvedParent, path.basename(absolute));
+  if (!resolvedRoots.some((root) => isWithinRoot(candidate, root))) {
+    throw new Error("Path is outside MACHINE_TERMINAL_ROOTS.");
+  }
+  try {
+    const stats = await lstat(candidate);
+    if (stats.isSymbolicLink()) {
+      throw new Error("Writing through symbolic links is not allowed.");
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  return candidate;
+}
+
+export function safeEnvironment(
+  source: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return Object.fromEntries(
+    DEFAULT_ENVIRONMENT_KEYS.flatMap((key) =>
+      source[key] === undefined ? [] : [[key, source[key]]],
+    ),
+  );
+}
+
+export function assertProgramAllowed(program: string): void {
+  const name = path.basename(program).toLowerCase();
+  const allowShell = process.env.MACHINE_TERMINAL_ALLOW_SHELL === "1";
+  if (!allowShell && DEFAULT_BLOCKED_PROGRAMS.has(name)) {
+    throw new Error(
+      `Program '${name}' is blocked by default. Set MACHINE_TERMINAL_ALLOW_SHELL=1 to allow shells and privilege tools.`,
+    );
+  }
+
+  const allowlist = process.env.MACHINE_TERMINAL_ALLOWED_PROGRAMS?.split(",")
+    .map((value) => value.trim().toLowerCase())
+    .filter(Boolean);
+  if (allowlist?.length && !allowlist.includes(name)) {
+    throw new Error(
+      `Program '${name}' is not in MACHINE_TERMINAL_ALLOWED_PROGRAMS.`,
+    );
+  }
+}

package/src/server.ts

@@ -0,0 +1,217 @@
+import { readFile, readdir, writeFile } from "node:fs/promises";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { runProgram } from "./runner.js";
+import {
+  configuredRoots,
+  resolveReadablePath,
+  resolveWritablePath,
+} from "./security.js";
+
+const roots = configuredRoots();
+
+function textResult(value: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(value, null, 2) }],
+    structuredContent: value as Record<string, unknown>,
+  };
+}
+
+export function createServer(): McpServer {
+  const server = new McpServer(
+    { name: "terminal-commands", version: "0.1.0" },
+    {
+      instructions:
+        "This server controls the user's machine. Prefer dedicated file tools over commands. Every command and write can modify or expose local data and must receive user approval. Never request secrets or bypass configured roots and safety controls.",
+    },
+  );
+
+  server.registerTool(
+    "get_system_info",
+    {
+      title: "Get machine information",
+      description:
+        "Return basic platform information and the configured filesystem roots.",
+      inputSchema: {},
+      outputSchema: {
+        platform: z.string(),
+        architecture: z.string(),
+        nodeVersion: z.string(),
+        roots: z.array(z.string()),
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+      },
+    },
+    async () =>
+      textResult({
+        platform: process.platform,
+        architecture: process.arch,
+        nodeVersion: process.version,
+        roots,
+      }),
+  );
+
+  server.registerTool(
+    "list_directory",
+    {
+      title: "List a directory",
+      description:
+        "List immediate entries in a directory inside the configured roots.",
+      inputSchema: { path: z.string().min(1) },
+      outputSchema: {
+        path: z.string(),
+        entries: z.array(
+          z.object({
+            name: z.string(),
+            type: z.enum(["directory", "file", "other"]),
+          }),
+        ),
+        truncated: z.boolean(),
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+      },
+    },
+    async ({ path: requestedPath }) => {
+      const directory = await resolveReadablePath(requestedPath, roots);
+      const entries = await readdir(directory, { withFileTypes: true });
+      return textResult({
+        path: directory,
+        entries: entries.slice(0, 1000).map((entry) => ({
+          name: entry.name,
+          type: entry.isDirectory()
+            ? "directory"
+            : entry.isFile()
+              ? "file"
+              : "other",
+        })),
+        truncated: entries.length > 1000,
+      });
+    },
+  );
+
+  server.registerTool(
+    "read_text_file",
+    {
+      title: "Read a text file",
+      description:
+        "Read a UTF-8 text file inside the configured roots, with a bounded result size.",
+      inputSchema: {
+        path: z.string().min(1),
+        maxCharacters: z.number().int().min(1).max(200_000).default(50_000),
+      },
+      outputSchema: {
+        path: z.string(),
+        contents: z.string(),
+        truncated: z.boolean(),
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+      },
+    },
+    async ({ path: requestedPath, maxCharacters }) => {
+      const filename = await resolveReadablePath(requestedPath, roots);
+      const contents = await readFile(filename, "utf8");
+      return textResult({
+        path: filename,
+        contents: contents.slice(0, maxCharacters),
+        truncated: contents.length > maxCharacters,
+      });
+    },
+  );
+
+  server.registerTool(
+    "write_text_file",
+    {
+      title: "Write a text file",
+      description:
+        "Create or overwrite a UTF-8 text file inside the configured roots.",
+      inputSchema: {
+        path: z.string().min(1),
+        contents: z.string().max(500_000),
+        overwrite: z.boolean().default(false),
+      },
+      outputSchema: {
+        path: z.string(),
+        bytesWritten: z.number().int().nonnegative(),
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: false,
+      },
+    },
+    async ({ path: requestedPath, contents, overwrite }) => {
+      const filename = await resolveWritablePath(requestedPath, roots);
+      await writeFile(filename, contents, {
+        encoding: "utf8",
+        flag: overwrite ? "w" : "wx",
+      });
+      return textResult({
+        path: filename,
+        bytesWritten: Buffer.byteLength(contents),
+      });
+    },
+  );
+
+  server.registerTool(
+    "run_program",
+    {
+      title: "Run a local program",
+      description:
+        "Run one executable without a shell. Shells and privilege-elevation programs are blocked unless explicitly enabled by local configuration.",
+      inputSchema: {
+        program: z.string().min(1),
+        args: z.array(z.string()).max(100).default([]),
+        cwd: z.string().min(1).optional(),
+        timeoutMs: z.number().int().min(100).max(120_000).default(30_000),
+        maxOutputCharacters: z
+          .number()
+          .int()
+          .min(1_000)
+          .max(200_000)
+          .default(50_000),
+      },
+      outputSchema: {
+        program: z.string(),
+        args: z.array(z.string()),
+        cwd: z.string(),
+        exitCode: z.number().int().nullable(),
+        signal: z.string().nullable(),
+        stdout: z.string(),
+        stderr: z.string(),
+        timedOut: z.boolean(),
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: true,
+      },
+    },
+    async ({ program, args, cwd, timeoutMs, maxOutputCharacters }) => {
+      const workingDirectory = await resolveReadablePath(
+        cwd ?? roots[0]!,
+        roots,
+      );
+      const result = await runProgram({
+        program,
+        args,
+        cwd: workingDirectory,
+        timeoutMs,
+        maxOutputChars: maxOutputCharacters,
+      });
+      return textResult({ program, args, cwd: workingDirectory, ...result });
+    },
+  );
+
+  return server;
+}

package/src/stdio.ts

@@ -0,0 +1,16 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { createServer } from "./server.js";
+
+const server = createServer();
+const transport = new StdioServerTransport();
+
+await server.connect(transport);
+
+async function shutdown() {
+  await server.close();
+  process.exit(0);
+}
+
+process.on("SIGINT", () => void shutdown());
+process.on("SIGTERM", () => void shutdown());

package/test/agent-config.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { loadAgentConfig } from "../src/agent-config.js";
+
+const required = {
+  MACHINE_TERMINAL_DEVICE_TOKEN: "test-token",
+  MACHINE_TERMINAL_DEVICE_ID: "test-device",
+};
+
+test("accepts a secure gateway URL", () => {
+  const config = loadAgentConfig({
+    ...required,
+    MACHINE_TERMINAL_GATEWAY_URL: "wss://mcp.example.com/device/connect",
+  });
+  assert.equal(config.MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE, "0");
+});
+
+test("allows unencrypted WebSocket only on loopback", () => {
+  assert.doesNotThrow(() =>
+    loadAgentConfig({
+      ...required,
+      MACHINE_TERMINAL_GATEWAY_URL: "ws://127.0.0.1:3400/device/connect",
+    }),
+  );
+  assert.throws(() =>
+    loadAgentConfig({
+      ...required,
+      MACHINE_TERMINAL_GATEWAY_URL: "ws://mcp.example.com/device/connect",
+    }),
+  );
+});