deadbyte-mcp 0.8.7

package/src/path-policy.mjs

@@ -0,0 +1,91 @@
+import { lstat, mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+const WINDOWS_DEVICE_BASENAME = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/i;
+
+export function validatePortableRelativePath(relativePath) {
+  if (typeof relativePath !== 'string' || relativePath.length === 0) {
+    throw new Error('path must be a non-empty relative path');
+  }
+  if (relativePath.includes('\0')) throw new Error('NUL path bytes are denied');
+  if (path.isAbsolute(relativePath) || /^[A-Za-z]:/.test(relativePath) || /^[\\/]/.test(relativePath)) {
+    throw new Error('absolute paths are denied');
+  }
+
+  const segments = relativePath.split(/[\\/]/);
+  for (const segment of segments) {
+    if (segment === '' || segment === '.') throw new Error('ambiguous path segments are denied');
+    if (segment === '..') throw new Error('path escapes workspace');
+    if (segment.includes(':')) throw new Error('Windows alternate data streams are denied');
+    if (/[ .]$/.test(segment)) throw new Error('Windows trailing-dot/space aliases are denied');
+    const deviceStem = segment.split('.')[0].replace(/[ ]+$/g, '');
+    if (WINDOWS_DEVICE_BASENAME.test(deviceStem)) throw new Error('Windows device paths are denied');
+  }
+  return relativePath;
+}
+
+export function isInside(root, candidate) {
+  const rel = path.relative(root, candidate);
+  return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+async function nearestExistingParent(candidate) {
+  let cursor = candidate;
+  while (true) {
+    try {
+      await lstat(cursor);
+      return cursor;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      const parent = path.dirname(cursor);
+      if (parent === cursor) throw error;
+      cursor = parent;
+    }
+  }
+}
+
+export async function resolveWorkspace(workspacePath) {
+  const absolute = path.resolve(workspacePath);
+  await mkdir(absolute, { recursive: true });
+  return realpath(absolute);
+}
+
+export async function resolveExistingInside(rootReal, relativePath) {
+  validatePortableRelativePath(relativePath);
+  const lexical = path.resolve(rootReal, relativePath);
+  if (!isInside(rootReal, lexical)) throw new Error('path escapes workspace');
+
+  const resolved = await realpath(lexical);
+  if (!isInside(rootReal, resolved)) throw new Error('symlink escapes workspace');
+  return resolved;
+}
+
+export async function resolveWritableInside(rootReal, relativePath) {
+  validatePortableRelativePath(relativePath);
+  const lexical = path.resolve(rootReal, relativePath);
+  if (!isInside(rootReal, lexical)) throw new Error('path escapes workspace');
+
+  const parent = path.dirname(lexical);
+  const existing = await nearestExistingParent(parent);
+  const realExisting = await realpath(existing);
+  if (!isInside(rootReal, realExisting)) throw new Error('parent symlink escapes workspace');
+
+  await mkdir(parent, { recursive: true });
+  const realParent = await realpath(parent);
+  if (!isInside(rootReal, realParent)) throw new Error('parent resolves outside workspace');
+
+  try {
+    const existingTarget = await realpath(lexical);
+    if (!isInside(rootReal, existingTarget)) throw new Error('target symlink escapes workspace');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+
+  return lexical;
+}
+
+export function relativeFromRoot(rootReal, absolutePath) {
+  const rel = path.relative(rootReal, absolutePath);
+  if (!isInside(rootReal, absolutePath)) throw new Error('path escapes workspace');
+  return rel.split(path.sep).join('/');
+}

package/src/process-mcp-tools.mjs

@@ -0,0 +1,72 @@
+import * as z from 'zod/v4';
+import {
+  processActionOutputSchema,
+  processListOutputSchema,
+  processReadOutputSchema,
+  processStartOutputSchema,
+  processStatusOutputSchema,
+  processTerminateOutputSchema,
+  processStructuredResult
+} from './process-output-contracts.mjs';
+
+const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
+const id = z.string().regex(/^[A-Za-z0-9._-]{1,64}$/);
+const ok = (schema, value) => processStructuredResult(schema, value, false);
+const fail = (schema, status, error) => processStructuredResult(schema, { status, error: String(error) }, true);
+
+export function registerProcessTools(server, { runtime }) {
+  if (!server || !runtime) throw new Error('process tool registration requires server/runtime');
+
+  server.registerTool('process_session_start', {
+    description: 'Start one locally registered process profile inside an approved root. Executable identity comes only from local policy.',
+    inputSchema: z.strictObject({
+      profile_id: id, root_id: id, cwd: z.string().min(1).max(1024).default('.'),
+      args: z.array(z.string().max(8192)).max(64).default([])
+    }), outputSchema: processStartOutputSchema
+  }, async ({ profile_id, root_id, cwd, args }) => {
+    try { return ok(processStartOutputSchema, { status: 'ok', session: await runtime.start({ profileId: profile_id, rootId: root_id, cwd, args }) }); }
+    catch (error) { return fail(processStartOutputSchema, 'denied', error); }
+  });
+  server.registerTool('process_session_read', {
+    description: 'Read a bounded byte range from one DEADBYTE-owned process session using ordered stream offsets.',
+    inputSchema: z.strictObject({
+      session_id: hex64, offset: z.number().int().nonnegative().default(0),
+      max_bytes: z.number().int().min(1).max(262144).default(65536)
+    }), outputSchema: processReadOutputSchema
+  }, async ({ session_id, offset, max_bytes }) => {
+    try { return ok(processReadOutputSchema, { status: 'ok', ...(await runtime.read({ sessionId: session_id, offset, maxBytes: max_bytes })) }); }
+    catch (error) { return fail(processReadOutputSchema, 'denied', error); }
+  });
+
+  server.registerTool('process_session_status', {
+    description: 'Read the verified state of one DEADBYTE-owned process session by session identity.',
+    inputSchema: z.strictObject({ session_id: hex64 }), outputSchema: processStatusOutputSchema
+  }, async ({ session_id }) => {
+    try { return ok(processStatusOutputSchema, { status: 'ok', session: await runtime.status({ sessionId: session_id }) }); }
+    catch (error) { return fail(processStatusOutputSchema, 'denied', error); }
+  });
+
+  server.registerTool('process_session_list', {
+    description: 'List process sessions owned by this DEADBYTE runtime. This does not enumerate unrelated operating-system processes.',
+    inputSchema: z.strictObject({}), outputSchema: processListOutputSchema
+  }, async () => {
+    try { return ok(processListOutputSchema, { status: 'ok', ...(await runtime.list()) }); }
+    catch (error) { return fail(processListOutputSchema, 'failed', error); }
+  });
+  server.registerTool('process_session_terminate', {
+    description: 'Terminate one DEADBYTE-owned process session through its owned host boundary. Numeric PID is never an input.',
+    inputSchema: z.strictObject({ session_id: hex64 }), outputSchema: processTerminateOutputSchema
+  }, async ({ session_id }) => {
+    try { return ok(processTerminateOutputSchema, { status: 'ok', session: await runtime.terminate({ sessionId: session_id }) }); }
+    catch (error) { return fail(processTerminateOutputSchema, 'denied', error); }
+  });
+
+  server.registerTool('process_session_action', {
+    description: 'Execute one fixed policy-defined action in a running DEADBYTE-owned pipe session. Raw input and process identifiers are never accepted.',
+    inputSchema: z.strictObject({ session_id: hex64, action_id: id }),
+    outputSchema: processActionOutputSchema
+  }, async ({ session_id, action_id }) => {
+    try { return ok(processActionOutputSchema, { status: 'ok', ...(await runtime.action({ sessionId: session_id, actionId: action_id })) }); }
+    catch (error) { return fail(processActionOutputSchema, 'denied', error); }
+  });
+}

package/src/process-output-contracts.mjs

@@ -0,0 +1,79 @@
+import * as z from 'zod/v4';
+import { structuredToolResult } from './output-contracts.mjs';
+
+const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
+const digits = z.string().regex(/^[0-9]+$/);
+const processState = z.enum(['running','exited','terminated']);
+
+export const processSessionRecordSchema = z.strictObject({
+  session_id: hex64,
+  profile_id: z.string().min(1).max(64),
+  root_id: z.string().min(1).max(64),
+  cwd: z.string().min(1).max(1024),
+  child_pid: z.number().int().positive(),
+  creation_filetime: digits,
+  state: processState,
+  exit_code: z.number().int().nullable(),
+  earliest_offset: z.number().int().nonnegative(),
+  stream_head: z.number().int().nonnegative(),
+  stream_sha256: hex64,
+  journal_head_sha256: hex64
+});
+
+function resultWithSession(okStatus = 'ok') {
+  return z.strictObject({
+    status: z.enum([okStatus, 'denied', 'failed']),
+    error: z.string().min(1).max(4096).optional(),
+    session: processSessionRecordSchema.optional()
+  }).superRefine((value, ctx) => {
+    if (value.status === okStatus && !value.session) ctx.addIssue({ code: 'custom', path: ['session'], message: 'session required' });
+    if (value.status !== okStatus && !value.error) ctx.addIssue({ code: 'custom', path: ['error'], message: 'error required' });
+  });
+}
+export const processStartOutputSchema = resultWithSession('ok');
+export const processStatusOutputSchema = resultWithSession('ok');
+export const processTerminateOutputSchema = resultWithSession('ok');
+
+export const processActionOutputSchema = z.strictObject({
+  status: z.enum(['ok','denied','failed']),
+  error: z.string().min(1).max(4096).optional(),
+  action_id: z.string().regex(/^[A-Za-z0-9._-]{1,64}$/).optional(),
+  logical_bytes: z.number().int().nonnegative().optional(),
+  logical_sha256: hex64.optional(),
+  session: processSessionRecordSchema.optional()
+}).superRefine((value, ctx) => {
+  if (value.status !== 'ok') {
+    if (!value.error) ctx.addIssue({ code: 'custom', path: ['error'], message: 'error required' });
+    return;
+  }
+  for (const key of ['action_id','logical_bytes','logical_sha256','session']) {
+    if (value[key] === undefined) ctx.addIssue({ code: 'custom', path: [key], message: `${key} required` });
+  }
+});
+
+export const processListOutputSchema = z.strictObject({
+  status: z.enum(['ok','failed']),
+  error: z.string().min(1).max(4096).optional(),
+  sessions: z.array(processSessionRecordSchema).max(256).optional()
+}).superRefine((value, ctx) => {
+  if (value.status === 'ok' && !value.sessions) ctx.addIssue({ code: 'custom', path: ['sessions'], message: 'sessions required' });
+  if (value.status === 'failed' && !value.error) ctx.addIssue({ code: 'custom', path: ['error'], message: 'error required' });
+});
+
+export const processReadOutputSchema = z.strictObject({
+  status: z.enum(['ok','denied','failed']), error: z.string().min(1).max(4096).optional(),
+  session_id: hex64.optional(), offset: z.number().int().nonnegative().optional(),
+  next_offset: z.number().int().nonnegative().optional(), earliest_offset: z.number().int().nonnegative().optional(),
+  stream_head: z.number().int().nonnegative().optional(), stream_sha256: hex64.optional(),
+  truncated: z.boolean().optional(), data_base64: z.string().max(400000).optional(),
+  state: processState.optional(), exit_code: z.number().int().nullable().optional()
+}).superRefine((value, ctx) => {
+  if (value.status !== 'ok') { if (!value.error) ctx.addIssue({ code: 'custom', path: ['error'], message: 'error required' }); return; }
+  for (const key of ['session_id','offset','next_offset','earliest_offset','stream_head','stream_sha256','truncated','data_base64','state','exit_code']) {
+    if (value[key] === undefined) ctx.addIssue({ code: 'custom', path: [key], message: `${key} required` });
+  }
+});
+
+export function processStructuredResult(schema, value, isError = false) {
+  return structuredToolResult(schema, value, isError);
+}

package/src/process-policy.mjs

@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { decodeUtf8Strict } from './text-policy.mjs';
+
+export const PROCESS_POLICY_SCHEMA = 'deadbyte.process-policy.v1';
+export const PROCESS_GRANT_SCHEMA = 'deadbyte.process-grant.v1';
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+
+function sha256Bytes(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+async function sha256File(file) {
+  return sha256Bytes(await readFile(file));
+}
+
+function finiteInteger(value, name, min, max, fallback) {
+  if (value === undefined || value === null) return fallback;
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`${name} must be an integer in [${min}, ${max}]`);
+  }
+  return value;
+}function normalizeStringArray(value, name, maxItems = 64, maxLength = 2048) {
+  if (!Array.isArray(value) || value.length > maxItems ||
+      value.some(item => typeof item !== 'string' || item.length > maxLength || item.includes('\0'))) {
+    throw new Error(`${name} invalid`);
+  }
+  return [...value];
+}
+
+function normalizePolicyObject(raw, policyPath) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('process policy must be an object');
+  if (raw.schema !== PROCESS_POLICY_SCHEMA || raw.enabled !== true) throw new Error('process policy schema/enabled mismatch');
+  if (typeof raw.grant_file !== 'string' || !path.isAbsolute(raw.grant_file)) throw new Error('process policy grant_file must be absolute');
+  if (typeof raw.state_dir !== 'string' || !path.isAbsolute(raw.state_dir)) throw new Error('process policy state_dir must be absolute');
+  if (!raw.native_host || typeof raw.native_host !== 'object' || Array.isArray(raw.native_host)) throw new Error('process policy native_host missing');
+  if (typeof raw.native_host.path !== 'string' || !path.isAbsolute(raw.native_host.path)) throw new Error('process native_host path must be absolute');
+  const nativeHostSha = String(raw.native_host.sha256 ?? '').toLowerCase();
+  if (!SHA256_RE.test(nativeHostSha)) throw new Error('process native_host sha256 invalid');
+  if (!raw.roots || typeof raw.roots !== 'object' || Array.isArray(raw.roots)) throw new Error('process policy roots missing');
+  if (!raw.profiles || typeof raw.profiles !== 'object' || Array.isArray(raw.profiles)) throw new Error('process policy profiles missing');
+
+  const roots = {};
+  for (const [id, value] of Object.entries(raw.roots)) {
+    if (!ID_RE.test(id)) throw new Error(`invalid process root id '${id}'`);
+    if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.path !== 'string' || !path.isAbsolute(value.path)) {
+      throw new Error(`process root '${id}' malformed`);
+    }
+    roots[id] = { path: path.resolve(value.path), deny_paths: normalizeStringArray(value.deny_paths ?? [], `roots.${id}.deny_paths`, 128, 512) };
+  }
+  if (Object.keys(roots).length === 0) throw new Error('process policy requires at least one root');  const profiles = {};
+  for (const [id, value] of Object.entries(raw.profiles)) {
+    if (!ID_RE.test(id)) throw new Error(`invalid process profile id '${id}'`);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`process profile '${id}' malformed`);
+    if (typeof value.executable !== 'string' || !path.isAbsolute(value.executable)) throw new Error(`process profile '${id}' executable must be absolute`);
+    const executableSha = String(value.executable_sha256 ?? '').toLowerCase();
+    if (!SHA256_RE.test(executableSha)) throw new Error(`process profile '${id}' executable_sha256 invalid`);
+    const rootIds = normalizeStringArray(value.root_ids, `profiles.${id}.root_ids`, 64, 64);
+    if (rootIds.length === 0 || rootIds.some(rootId => !ID_RE.test(rootId) || !roots[rootId])) throw new Error(`process profile '${id}' root_ids invalid`);
+    const envAllow = normalizeStringArray(value.env_allow ?? [], `profiles.${id}.env_allow`, 64, 128);
+    if (envAllow.some(name => !/^[A-Za-z_][A-Za-z0-9_()]*$/.test(name))) throw new Error(`process profile '${id}' env_allow invalid`);
+    const transport = value.transport ?? 'conpty';
+    if (transport !== 'conpty' && transport !== 'pipe') throw new Error(`process profile '${id}' transport invalid`);
+    const inputActions = {};
+    if (value.input_actions !== undefined) {
+      if (!value.input_actions || typeof value.input_actions !== 'object' || Array.isArray(value.input_actions)) throw new Error(`process profile '${id}' input_actions invalid`);
+      for (const [actionId, actionText] of Object.entries(value.input_actions)) {
+        if (!ID_RE.test(actionId) || typeof actionText !== 'string' || actionText.includes('\0')) throw new Error(`process profile '${id}' input_actions invalid`);
+        if (Buffer.byteLength(actionText, 'utf8') > finiteInteger(value.max_input_bytes, `profiles.${id}.max_input_bytes`, 1, 1024 * 1024, 64 * 1024)) throw new Error(`process profile '${id}' input action too large`);
+        inputActions[actionId] = actionText;
+      }
+    }
+    profiles[id] = {
+      executable: path.resolve(value.executable), executable_sha256: executableSha,
+      root_ids: [...new Set(rootIds)], prefix_args: normalizeStringArray(value.prefix_args ?? [], `profiles.${id}.prefix_args`, 64, 2048),
+      max_args: finiteInteger(value.max_args, `profiles.${id}.max_args`, 0, 64, 16),
+      max_arg_bytes: finiteInteger(value.max_arg_bytes, `profiles.${id}.max_arg_bytes`, 1, 8192, 2048),
+      max_sessions: finiteInteger(value.max_sessions, `profiles.${id}.max_sessions`, 1, 32, 4),
+      max_input_bytes: finiteInteger(value.max_input_bytes, `profiles.${id}.max_input_bytes`, 1, 1024 * 1024, 64 * 1024),
+      max_retained_output_bytes: finiteInteger(value.max_retained_output_bytes, `profiles.${id}.max_retained_output_bytes`, 4096, 16 * 1024 * 1024, 1024 * 1024),
+      transport, env_allow: [...new Set(envAllow)], input_actions: inputActions
+    };
+  }
+  if (Object.keys(profiles).length === 0) throw new Error('process policy requires at least one profile');
+  return {
+    schema: PROCESS_POLICY_SCHEMA, enabled: true, policy_path: path.resolve(policyPath),
+    grant_file: path.resolve(raw.grant_file), state_dir: path.resolve(raw.state_dir),
+    native_host: { path: path.resolve(raw.native_host.path), sha256: nativeHostSha }, roots, profiles
+  };
+}async function assertRegularPinnedFile(file, expectedSha256, label) {
+  const info = await lstat(file);
+  if (info.isSymbolicLink() || !info.isFile()) throw new Error(`${label} must be a regular non-symlink file`);
+  const actual = await sha256File(file);
+  if (actual !== expectedSha256) throw new Error(`${label} executable hash mismatch: expected ${expectedSha256}, found ${actual}`);
+}
+
+export async function loadProcessPolicy(policyPath) {
+  if (!policyPath) throw new Error('missing DEADBYTE process policy path');
+  const absolute = path.resolve(policyPath);
+  const bytes = await readFile(absolute);
+  const policy = normalizePolicyObject(JSON.parse(decodeUtf8Strict(bytes)), absolute);
+  policy.policy_sha256 = sha256Bytes(bytes);
+  await assertRegularPinnedFile(policy.native_host.path, policy.native_host.sha256, 'process native_host');
+  await mkdir(policy.state_dir, { recursive: true });
+  for (const [id, root] of Object.entries(policy.roots)) {
+    const info = await lstat(root.path);
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error(`process root '${id}' must be a regular directory`);
+    root.real_path = await realpath(root.path);
+  }
+  for (const [id, profile] of Object.entries(policy.profiles)) {
+    await assertRegularPinnedFile(profile.executable, profile.executable_sha256, `process profile '${id}'`);
+  }
+  return policy;
+}
+
+function configuredStatus(policy, reason) {
+  return {
+    configured: true, armed: false, reason, expires_at_utc: null,
+    root_ids: Object.keys(policy.roots).sort(), profile_ids: Object.keys(policy.profiles).sort(),
+    policy_sha256: policy.policy_sha256
+  };
+}export async function processSessionStatus(policy) {
+  let grant;
+  try { grant = JSON.parse(decodeUtf8Strict(await readFile(policy.grant_file))); }
+  catch (error) { return configuredStatus(policy, error?.code === 'ENOENT' ? 'disarmed' : 'invalid-grant'); }
+  if (!grant || grant.schema !== PROCESS_GRANT_SCHEMA) return configuredStatus(policy, 'grant-schema');
+  if (grant.policy_sha256 !== policy.policy_sha256) return configuredStatus(policy, 'policy-digest');
+  if (typeof grant.instance_nonce !== 'string' || !SHA256_RE.test(grant.instance_nonce)) return configuredStatus(policy, 'nonce-invalid');
+  if (!Array.isArray(grant.profile_ids) || grant.profile_ids.length === 0 ||
+      grant.profile_ids.some(id => !ID_RE.test(id) || !policy.profiles[id])) return configuredStatus(policy, 'profiles-invalid');
+  if (!Array.isArray(grant.root_ids) || grant.root_ids.length === 0 ||
+      grant.root_ids.some(id => !ID_RE.test(id) || !policy.roots[id])) return configuredStatus(policy, 'roots-invalid');
+  const profileIds = [...new Set(grant.profile_ids)].sort();
+  const rootIds = [...new Set(grant.root_ids)].sort();
+  return {
+    configured: true, armed: true, reason: 'standing-grant', expires_at_utc: null,
+    root_ids: rootIds, profile_ids: profileIds, policy_sha256: policy.policy_sha256,
+    instance_nonce: grant.instance_nonce, standing: true
+  };
+}
+
+export async function assertProcessArmed(policy, profileId = null, rootId = null) {
+  const status = await processSessionStatus(policy);
+  if (!status.armed) throw new Error(`process plane is disarmed: ${status.reason}`);
+  if (profileId !== null && !status.profile_ids.includes(profileId)) throw new Error(`process profile '${profileId}' is not included in the active grant`);
+  if (rootId !== null && !status.root_ids.includes(rootId)) throw new Error(`process root '${rootId}' is not included in the active grant`);
+  return status;
+}