@shieldfive/mcp 0.2.0

package/src/plans.mjs

@@ -0,0 +1,188 @@
+// Binding a confirmed call to the preview the user approved.
+//
+// Every mutating tool plans twice: once for the preview, and again when it is
+// called back with confirm: true. Until now the two plans were unrelated. The
+// user saw "12 files, 4.1 GB" in the preview, said yes, and the confirmed call
+// went out and planned again from scratch — against whatever the tree looked
+// like by then. If a directory had grown, or a destination had appeared, or the
+// file behind a path had been replaced, the call did something the user had
+// never been shown. The pre-publish review recorded this as D3, and README,
+// SECURITY.md and the CHANGELOG all said it was not covered.
+//
+// The fix is the usual two-phase shape. A preview registers a fingerprint of
+// what it planned and hands back an opaque `plan_token`. A confirmed call must
+// carry that token; the tool re-plans as before, fingerprints the result the
+// same way, and refuses if the two differ — naming what changed, so the model
+// can show the user a new plan rather than guess.
+//
+// Three properties matter:
+//
+//   1. The token is issued by the server and means nothing outside it. It is
+//      random, not a hash of the plan, so nothing a client can compute
+//      authorizes a change.
+//   2. It is single use. One approval performs one change; a token cannot be
+//      replayed against a tree that has moved on.
+//   3. It expires. An approval from an hour ago is not consent to act on a
+//      directory nobody has looked at since.
+//
+// What this does NOT do is close the time-of-check/time-of-use window: the
+// fingerprint is taken during the confirmed call, and the filesystem can still
+// change between that and the write itself. The per-tool checks immediately
+// before each write are what narrow that gap, and SECURITY.md states the limit.
+
+import { randomUUID } from 'node:crypto'
+
+import { quote } from './format.mjs'
+import { ToolError } from './roots.mjs'
+
+/** How long an approved plan stays good for. */
+export const PLAN_TTL_MS = 10 * 60 * 1000
+
+/** How many plans are remembered at once. Oldest first out. */
+export const PLAN_CAPACITY = 64
+
+/**
+ * The identity of a filesystem entry, as far as a plan is concerned.
+ *
+ * Device and inode say it is the same entry rather than the same path — a path
+ * swapped for another file between the preview and the confirmation is a
+ * different plan even when every visible field matches. Size and mtime catch a
+ * file rewritten in place, where the inode does not change.
+ */
+export function entryId(stats) {
+  if (!stats) return 'absent'
+  const kind = stats.isSymbolicLink()
+    ? 'symlink'
+    : stats.isDirectory()
+      ? 'directory'
+      : stats.isFile()
+        ? 'file'
+        : 'special'
+  return `${kind}:${stats.dev}:${stats.ino}:${stats.mtimeMs}:${stats.size}`
+}
+
+/** Stable JSON: object keys in a fixed order, so two equal plans stringify alike. */
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+      .join(',')}}`
+  }
+  return JSON.stringify(value ?? null)
+}
+
+/**
+ * A store of approved plans.
+ *
+ * In memory and per process on purpose: a plan is an approval inside one
+ * conversation, and a server that has restarted has no conversation to honour
+ * it in.
+ */
+export function createPlanStore({ now = () => Date.now(), ttlMs = PLAN_TTL_MS, capacity = PLAN_CAPACITY } = {}) {
+  const plans = new Map()
+
+  // Map iterates in insertion order, so the first key is always the oldest.
+  function sweep(at) {
+    for (const [token, plan] of plans) {
+      if (at - plan.issuedAt >= ttlMs) plans.delete(token)
+    }
+    while (plans.size > capacity) plans.delete(plans.keys().next().value)
+  }
+
+  return {
+    /** Register what a preview planned; returns the token that approves it. */
+    issue(fingerprint) {
+      const at = now()
+      const token = `plan_${randomUUID().replace(/-/g, '')}`
+      plans.set(token, { body: canonical(fingerprint), issuedAt: at })
+      sweep(at)
+      return token
+    },
+
+    /**
+     * Consume a token.
+     *
+     * Returns the approved body, or a reason it cannot be used. Consuming
+     * happens whether or not the body matches: a token that has been answered
+     * once is spent, and a mismatch means the caller has to look at a new plan
+     * anyway.
+     */
+    take(token) {
+      const plan = plans.get(token)
+      if (!plan) return { ok: false, reason: 'unknown' }
+      plans.delete(token)
+      if (now() - plan.issuedAt >= ttlMs) return { ok: false, reason: 'expired' }
+      return { ok: true, body: plan.body }
+    },
+
+    get size() {
+      return plans.size
+    },
+  }
+}
+
+/** Which fields differ between the plan that was approved and the one now. */
+function differences(approved, fresh) {
+  let a
+  try {
+    a = JSON.parse(approved)
+  } catch {
+    return ['the plan']
+  }
+  const b = JSON.parse(canonical(fresh))
+  const out = []
+  for (const key of new Set([...Object.keys(a), ...Object.keys(b)])) {
+    const before = canonical(a[key])
+    const after = canonical(b[key])
+    if (before !== after) out.push(key)
+  }
+  return out.length ? out : ['the plan']
+}
+
+/**
+ * Refuse a confirmed call that is not the plan the user approved.
+ *
+ * Called before anything is written, and after the tool has re-planned, so the
+ * comparison is between two plans built the same way from two readings of the
+ * filesystem.
+ */
+export function requireApprovedPlan(ctx, token, fingerprint) {
+  const store = ctx.plans
+  if (!store) {
+    throw new ToolError(
+      'plan_store_missing',
+      'Refused: this server has no plan store, so a confirmed call cannot be checked ' +
+        'against the plan it claims to perform. Nothing was changed.',
+    )
+  }
+  if (typeof token !== 'string' || !token) {
+    throw new ToolError(
+      'plan_token_required',
+      'Refused: confirm: true needs the plan_token from the preview of this exact call. ' +
+        'Call this tool without confirm, show the user what it reports, and pass the ' +
+        'plan_token it returns. Nothing was changed.',
+    )
+  }
+  const taken = store.take(token)
+  if (!taken.ok) {
+    throw new ToolError(
+      taken.reason === 'expired' ? 'plan_expired' : 'unknown_plan_token',
+      taken.reason === 'expired'
+        ? `Refused: plan ${quote(token)} is older than ${Math.round(PLAN_TTL_MS / 60000)} minutes. ` +
+          'Plan again and confirm the new plan. Nothing was changed.'
+        : `Refused: plan ${quote(token)} is not a plan this server issued, or it has already ` +
+          'been used. Each plan performs one change. Nothing was changed.',
+    )
+  }
+  const body = canonical(fingerprint)
+  if (body !== taken.body) {
+    throw new ToolError(
+      'plan_changed',
+      `Refused: ${differences(taken.body, fingerprint).join(', ')} changed between the plan and ` +
+        'this call, so performing it would not do what was approved. Nothing was changed; ' +
+        'call again without confirm to see the current plan.',
+    )
+  }
+}

package/src/roots.mjs

@@ -0,0 +1,336 @@
+// Path containment — the security core of this server.
+//
+// Every path that reaches the filesystem passes through here first. One rule:
+// a path is usable only if its real path, with every symlink resolved, sits
+// inside one of the roots the user configured at startup. Nothing else grants
+// access, and there is no override flag.
+//
+// Why realpath rather than string prefixing. A string check on the path the
+// caller supplied is defeated by `..`, and a check after `path.resolve` is still
+// defeated by a symlink: `/allowed/link -> /etc` resolves to a string under
+// /allowed while reading /etc. Resolving symlinks first is what closes that, and
+// it is why the directory walk in scan.mjs uses lstat and never follows a link.
+//
+// The boundary test is separator-aware. `/data/roots-evil` must not match the
+// root `/data/root` just because the string starts with it.
+
+import { realpath, lstat } from 'node:fs/promises'
+import { basename, delimiter, dirname, isAbsolute, join, resolve, sep } from 'node:path'
+
+import { quote } from './format.mjs'
+
+/** A refusal the model is meant to read and act on, not a crash. */
+export class ToolError extends Error {
+  constructor(code, message, detail = undefined) {
+    super(message)
+    this.name = 'ToolError'
+    this.code = code
+    if (detail !== undefined) this.detail = detail
+  }
+}
+
+/**
+ * The longest path argument accepted: PATH_MAX on Linux, and more than macOS
+ * accepts. The cap is not about the filesystem. Without it a 5 MB path argument
+ * was reflected verbatim into the error and into the model's context.
+ */
+export const MAX_PATH_CHARS = 4096
+
+export const NO_ROOTS_MESSAGE =
+  'No allowed roots are configured, so this server can read nothing. ' +
+  'Start it with one or more directories: `shieldfive-mcp /Users/you/Documents ' +
+  '/Volumes/Archive`, or set SHIELDFIVE_MCP_ROOTS to a ' +
+  `${JSON.stringify(delimiter)}-separated list. Roots are the only paths this ` +
+  'server may touch; it has no default and will not guess one.'
+
+/**
+ * Resolve configured roots to real paths.
+ *
+ * A root that does not exist, or is not a directory, is dropped with a reason
+ * rather than silently ignored — a typo in a client config should be visible,
+ * not just produce an empty file listing.
+ *
+ * Root candidates are trimmed, unlike tool arguments: they come from a config
+ * file or a shell variable a person typed, where stray whitespace around a
+ * separator is common, and every rejection is logged at startup.
+ */
+export async function resolveRoots(candidates) {
+  const roots = []
+  const rejected = []
+
+  for (const raw of candidates) {
+    const trimmed = String(raw).trim()
+    if (!trimmed) continue
+
+    if (!isAbsolute(trimmed)) {
+      rejected.push({ path: trimmed, reason: 'not an absolute path' })
+      continue
+    }
+
+    let real
+    try {
+      real = await realpath(trimmed)
+    } catch (err) {
+      rejected.push({
+        path: trimmed,
+        reason: err.code === 'ENOENT' ? 'does not exist' : `unreadable (${err.code})`,
+      })
+      continue
+    }
+
+    let stats
+    try {
+      stats = await lstat(real)
+    } catch (err) {
+      rejected.push({ path: trimmed, reason: `unreadable (${err.code})` })
+      continue
+    }
+    if (!stats.isDirectory()) {
+      rejected.push({ path: trimmed, reason: 'not a directory' })
+      continue
+    }
+
+    if (roots.some((r) => r.realPath === real)) continue
+    roots.push({ configured: trimmed, realPath: real })
+  }
+
+  // Drop a root nested inside another so a file is never reported twice and
+  // containment has a single answer.
+  const kept = roots.filter(
+    (r) => !roots.some((other) => other !== r && isInside(r.realPath, other.realPath)),
+  )
+  for (const r of roots) {
+    if (!kept.includes(r)) {
+      rejected.push({
+        path: r.configured,
+        reason: 'nested inside another configured root',
+      })
+    }
+  }
+
+  return { roots: kept, rejected }
+}
+
+/** True when `child` is `parent` itself or sits beneath it. Separator-aware. */
+export function isInside(child, parent) {
+  if (child === parent) return true
+  return child.startsWith(parent.endsWith(sep) ? parent : parent + sep)
+}
+
+/** Read root candidates from argv and the environment. */
+export function rootCandidatesFrom(argv, env) {
+  const fromArgs = argv.filter((a) => !a.startsWith('-'))
+  const fromEnv = (env.SHIELDFIVE_MCP_ROOTS ?? '').split(delimiter)
+  return [...fromArgs, ...fromEnv]
+}
+
+/**
+ * Resolve a caller-supplied path that must already exist, following links.
+ *
+ * Returns the REAL path. This is for what is read or walked; a path a tool is
+ * about to move, rename or trash goes through resolveEntry() instead, so the
+ * tool acts on the link it was given rather than on what the link points to.
+ */
+export async function resolveExisting(rootSet, input, { what = 'path' } = {}) {
+  assertRoots(rootSet)
+  const requested = requireAbsolute(input, what)
+
+  let real
+  try {
+    real = await realpath(requested)
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new ToolError('not_found', `No such ${what}: ${quote(requested)}`)
+    }
+    throw new ToolError('unreadable', `Cannot read ${what} ${quote(requested)} (${err.code})`)
+  }
+
+  return { realPath: real, root: requireContained(rootSet, real, requested, what) }
+}
+
+/**
+ * Resolve a path that may not exist yet — a move destination, a new folder.
+ *
+ * The nearest existing ancestor is realpath'd and the remaining segments are
+ * re-appended, so a destination under a symlinked parent is caught before the
+ * write rather than after it.
+ */
+export async function resolveTarget(rootSet, input, { what = 'destination' } = {}) {
+  assertRoots(rootSet)
+  const requested = requireAbsolute(input, what)
+  const { realPath, exists } = await resolveNearest(requested, what)
+  return { realPath, root: requireContained(rootSet, realPath, requested, what), exists }
+}
+
+/**
+ * Resolve a directory entry a tool is about to move, rename or trash.
+ *
+ * The parent is realpath'd and the last component is not: a symlink named here
+ * is the thing acted on, never its target. Following it made trash_local on a
+ * shortcut trash the folder behind it, and rename_local rename the file a link
+ * pointed to, leaving the link dangling. Containment is checked on the entry's
+ * own position, which is all the operation touches.
+ *
+ * `stats` is the entry's lstat.
+ */
+export async function resolveEntry(rootSet, input, { what = 'path' } = {}) {
+  assertRoots(rootSet)
+  const requested = requireAbsolute(input, what)
+  const parent = dirname(requested)
+  if (parent === requested) {
+    throw new ToolError('invalid_path', `${what} ${quote(requested)} is a filesystem root, not an entry.`)
+  }
+
+  let realParent
+  try {
+    realParent = await realpath(parent)
+  } catch (err) {
+    throw entryError(err, what, requested)
+  }
+  const realPath = join(realParent, basename(requested))
+
+  let stats
+  try {
+    stats = await lstat(realPath)
+  } catch (err) {
+    throw entryError(err, what, requested)
+  }
+  return { realPath, root: requireContained(rootSet, realPath, requested, what), stats }
+}
+
+/**
+ * Resolve where a move or a rename would put something.
+ *
+ * Like resolveTarget(), except that the last component is inspected without
+ * being followed and only its own position has to be inside a root. `stats` is
+ * the lstat of whatever is already there, or null. A symlink at the
+ * destination, dangling or not, is an existing entry to report and to refuse or
+ * displace, not a way through to its target: a dangling one used to read as a
+ * free name, and a copy then wrote through it to wherever it pointed.
+ */
+export async function resolveDestination(rootSet, input, { what = 'destination' } = {}) {
+  assertRoots(rootSet)
+  const requested = requireAbsolute(input, what)
+  const parent = dirname(requested)
+  if (parent === requested) {
+    throw new ToolError('invalid_path', `${what} ${quote(requested)} is a filesystem root, not an entry.`)
+  }
+
+  const nearest = await resolveNearest(parent, what)
+  const realPath = join(nearest.realPath, basename(requested))
+  let stats = null
+  if (nearest.exists) {
+    try {
+      stats = await lstat(realPath)
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw new ToolError('unreadable', `Cannot read ${what} ${quote(requested)} (${err.code})`)
+      }
+    }
+  }
+  return { realPath, root: requireContained(rootSet, realPath, requested, what), stats }
+}
+
+/**
+ * Realpath the nearest existing ancestor of `requested` and re-append the rest.
+ *
+ * A component that exists but does not resolve is a dangling symlink. realpath
+ * reports ENOENT for it exactly as for a missing path, and taking that at its
+ * word made the link look like a free, contained name that a write would then
+ * follow out of the root. It is refused.
+ */
+async function resolveNearest(requested, what) {
+  const trailing = []
+  let probe = requested
+  for (;;) {
+    let real
+    try {
+      real = await realpath(probe)
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        throw new ToolError('unreadable', `Cannot resolve ${what} ${quote(requested)} (${err.code})`)
+      }
+      if (await isSymlink(probe)) {
+        throw new ToolError(
+          'dangling_symlink',
+          `Refused: ${quote(probe)} is a symlink whose target does not exist. This server ` +
+            'does not write through links, and will not treat a broken one as a free name. ' +
+            'Remove or repair the link first.',
+        )
+      }
+      const parent = resolve(probe, '..')
+      if (parent === probe) {
+        throw new ToolError('not_found', `No existing ancestor for ${quote(requested)}`)
+      }
+      trailing.unshift(probe.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)))
+      probe = parent
+      continue
+    }
+    return { realPath: trailing.length ? join(real, ...trailing) : real, exists: trailing.length === 0 }
+  }
+}
+
+async function isSymlink(path) {
+  try {
+    return (await lstat(path)).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+function entryError(err, what, requested) {
+  if (err.code === 'ENOENT' || err.code === 'ENOTDIR') {
+    return new ToolError('not_found', `No such ${what}: ${quote(requested)}`)
+  }
+  return new ToolError('unreadable', `Cannot read ${what} ${quote(requested)} (${err.code})`)
+}
+
+function assertRoots(rootSet) {
+  if (!rootSet || rootSet.length === 0) {
+    throw new ToolError('no_roots', NO_ROOTS_MESSAGE)
+  }
+}
+
+/**
+ * A path argument, exactly as given.
+ *
+ * Nothing is trimmed. "report " and "report" are different files, and trimming
+ * made a request for the first act on the second.
+ */
+function requireAbsolute(input, what) {
+  if (typeof input !== 'string' || input === '') {
+    throw new ToolError('invalid_path', `A ${what} is required.`)
+  }
+  if (input.length > MAX_PATH_CHARS) {
+    throw new ToolError(
+      'invalid_path',
+      `${what} is ${input.length.toLocaleString('en-US')} characters long, more than any ` +
+        `filesystem accepts. It starts ${quote(input, 80)}.`,
+    )
+  }
+  if (input.includes('\0')) {
+    throw new ToolError('invalid_path', `${what} contains a NUL byte, which no path can: ${quote(input)}.`)
+  }
+  if (!isAbsolute(input)) {
+    throw new ToolError(
+      'invalid_path',
+      `${what} must be an absolute path; got ${quote(input)}. ` +
+        'This server resolves nothing against a working directory, because it has ' +
+        'no meaningful one.',
+    )
+  }
+  return resolve(input)
+}
+
+function requireContained(rootSet, real, requested, what) {
+  const root = rootSet.find((r) => isInside(real, r.realPath))
+  if (!root) {
+    throw new ToolError(
+      'outside_roots',
+      `Refused: ${what} ${quote(requested)} resolves to ${quote(real)}, which is outside ` +
+        `every configured root (${rootSet.map((r) => r.realPath).join(', ')}). ` +
+        'Add the directory at startup if this is intended; there is no override.',
+    )
+  }
+  return root
+}