@atlassian-dc-mcp/common 0.26.0 → 0.28.0

package/src/attachment-download.ts

@@ -0,0 +1,154 @@
+import { writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+
+/**
+ * How the downloaded bytes should be returned to the caller inline, in addition
+ * to (or instead of) being written to disk.
+ * - `none`: do not embed the bytes in the response (default)
+ * - `base64`: embed base64-encoded bytes (suitable for binary files)
+ * - `text`: embed the bytes decoded as UTF-8 text (suitable for text files)
+ */
+export type AttachmentContentEncoding = 'none' | 'base64' | 'text';
+
+/** Default cap for inline content so responses do not balloon. 1 MiB. */
+export const DEFAULT_MAX_INLINE_BYTES = 1_048_576;
+
+export interface AttachmentDownloadOptions {
+  /**
+   * Absolute, already-validated destination path to write the bytes to. Resolving
+   * and sandboxing this path is the caller's responsibility (see the attachment
+   * gateway); the file is written with an exclusive flag and never overwrites an
+   * existing file. When omitted, nothing is written to disk.
+   */
+  destination?: string;
+  /** Whether and how to embed the bytes in the response. Defaults to `none`. */
+  returnContent?: AttachmentContentEncoding;
+  /** Maximum bytes to embed inline when returnContent is not `none`. */
+  maxInlineBytes?: number;
+  /** Hard cap on the number of downloaded bytes. Exceeding it aborts the download. */
+  maxDownloadBytes?: number;
+}
+
+export interface AttachmentDownloadResult {
+  filename: string;
+  mediaType?: string;
+  /** Number of bytes downloaded. */
+  size: number;
+  /** Absolute path the file was written to, when saving was requested. */
+  savedPath?: string;
+  /** Inline content, when returnContent is `base64` or `text`. */
+  content?: string;
+  encoding?: 'base64' | 'text';
+  /** Set when inline content was requested but omitted (e.g. over the size cap). */
+  contentOmittedReason?: string;
+}
+
+async function resolveToken(token: string | (() => string | undefined)): Promise<string> {
+  const resolved = typeof token === 'function' ? token() : token;
+  if (!resolved) {
+    throw new Error('Missing API token for attachment download');
+  }
+  return resolved;
+}
+
+/**
+ * Reads the response body, enforcing `cap` (when set) without buffering more than
+ * the limit. Streams chunk-by-chunk when a web ReadableStream is available and
+ * falls back to a buffered read with a post-check otherwise.
+ */
+async function readBodyWithCap(response: Response, cap: number | undefined, filename: string): Promise<Buffer> {
+  const body = response.body as ReadableStream<Uint8Array> | null;
+  if (cap !== undefined && body && typeof body.getReader === 'function') {
+    const reader = body.getReader();
+    const chunks: Buffer[] = [];
+    let total = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      total += value.byteLength;
+      if (total > cap) {
+        await reader.cancel();
+        throw new Error(`Attachment "${filename}" exceeds the configured download limit of ${cap} bytes`);
+      }
+      chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (cap !== undefined && buffer.length > cap) {
+    throw new Error(
+      `Attachment "${filename}" size ${buffer.length} bytes exceeds the configured download limit of ${cap} bytes`,
+    );
+  }
+  return buffer;
+}
+
+/**
+ * Downloads a file from an authenticated Atlassian Data Center URL using a
+ * Bearer token, optionally writing it to a pre-validated destination and/or
+ * returning its bytes inline.
+ *
+ * Writing uses an exclusive flag, so an existing file (including a symlink) is
+ * never overwritten.
+ */
+export async function downloadAttachment(params: {
+  url: string;
+  token: string | (() => string | undefined);
+  filename: string;
+  mediaType?: string;
+  options?: AttachmentDownloadOptions;
+}): Promise<AttachmentDownloadResult> {
+  const { url, filename, mediaType } = params;
+  const options = params.options ?? {};
+  const token = await resolveToken(params.token);
+
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      // Attachment download endpoints are XSRF-protected; nocheck bypasses it.
+      'X-Atlassian-Token': 'nocheck',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to download attachment "${filename}": ${response.status} ${response.statusText}`);
+  }
+
+  const cap = options.maxDownloadBytes;
+  const declaredLength = Number(response.headers.get('content-length'));
+  if (cap !== undefined && Number.isFinite(declaredLength) && declaredLength > cap) {
+    throw new Error(
+      `Attachment "${filename}" size ${declaredLength} bytes exceeds the configured download limit of ${cap} bytes`,
+    );
+  }
+
+  const buffer = await readBodyWithCap(response, cap, filename);
+  const resolvedMediaType = mediaType ?? response.headers.get('content-type') ?? undefined;
+
+  const result: AttachmentDownloadResult = {
+    filename: basename(filename),
+    mediaType: resolvedMediaType,
+    size: buffer.length,
+  };
+
+  if (options.destination) {
+    await writeFile(options.destination, buffer, { flag: 'wx' });
+    result.savedPath = options.destination;
+  }
+
+  const returnContent = options.returnContent ?? 'none';
+  if (returnContent !== 'none') {
+    const inlineCap = options.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
+    if (buffer.length > inlineCap) {
+      result.contentOmittedReason = `File size ${buffer.length} bytes exceeds inline cap of ${inlineCap} bytes`;
+    } else {
+      result.content = returnContent === 'base64' ? buffer.toString('base64') : buffer.toString('utf-8');
+      result.encoding = returnContent;
+    }
+  }
+
+  return result;
+}

package/src/attachment-gateway.ts

@@ -0,0 +1,255 @@
+import { realpathSync } from 'node:fs';
+import { lstat, realpath } from 'node:fs/promises';
+import { basename, delimiter, dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import type { ProductDefinition } from './config/source.js';
+
+/**
+ * Operator-controlled gateway that lets the attachment tools read from / write to
+ * the local filesystem. It is disabled by default: filesystem access must be
+ * explicitly enabled and confined to canonical root directories that the model
+ * cannot choose. Configured entirely through environment variables named after
+ * the product (e.g. JIRA_ATTACHMENTS_*).
+ */
+export const DEFAULT_MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024; // 25 MiB
+
+export interface AttachmentGatewaySide {
+  /** Whether this direction (upload/download) is enabled with a valid root. */
+  enabled: boolean;
+  /** Canonical (realpath-resolved) absolute root directories. */
+  roots: string[];
+  /** Hard byte limit for a single file in this direction. */
+  maxBytes: number;
+}
+
+export interface AttachmentGateway {
+  upload: AttachmentGatewaySide;
+  download: AttachmentGatewaySide;
+}
+
+type Env = Record<string, string | undefined>;
+type Warn = (message: string) => void;
+
+function envPrefix(product: ProductDefinition): string {
+  return product.id.toUpperCase();
+}
+
+function readBool(env: Env, name: string): boolean {
+  const value = env[name]?.trim().toLowerCase();
+  return value === 'true' || value === '1' || value === 'yes';
+}
+
+function readBytes(env: Env, name: string): number | undefined {
+  const raw = env[name]?.trim();
+  if (!raw || !/^\d+$/.test(raw)) {
+    return undefined;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  return parsed > 0 ? parsed : undefined;
+}
+
+function readRoots(env: Env, names: string[]): string[] {
+  const roots: string[] = [];
+  for (const name of names) {
+    const raw = env[name];
+    if (!raw) {
+      continue;
+    }
+    for (const part of raw.split(delimiter)) {
+      const trimmed = part.trim();
+      if (trimmed) {
+        roots.push(trimmed);
+      }
+    }
+  }
+  return roots;
+}
+
+function canonicalizeRoots(rawRoots: string[], warn: Warn): string[] {
+  const canonical: string[] = [];
+  for (const root of rawRoots) {
+    if (!isAbsolute(root)) {
+      warn(`Ignoring attachment root that is not an absolute path: "${root}"`);
+      continue;
+    }
+    try {
+      const real = realpathSync(root);
+      if (!canonical.includes(real)) {
+        canonical.push(real);
+      }
+    } catch {
+      warn(`Ignoring attachment root that does not exist or cannot be resolved: "${root}"`);
+    }
+  }
+  return canonical;
+}
+
+function resolveSide(args: {
+  enabledFlag: boolean;
+  rawRoots: string[];
+  maxBytes: number;
+  label: string;
+  rootEnvHint: string;
+  warn: Warn;
+}): AttachmentGatewaySide {
+  if (!args.enabledFlag) {
+    return { enabled: false, roots: [], maxBytes: args.maxBytes };
+  }
+  const roots = canonicalizeRoots(args.rawRoots, args.warn);
+  if (roots.length === 0) {
+    args.warn(
+      `${args.label} attachments were enabled but no valid directory is configured ` +
+        `(set ${args.rootEnvHint}); the ${args.label} tool will stay disabled.`,
+    );
+    return { enabled: false, roots: [], maxBytes: args.maxBytes };
+  }
+  return { enabled: true, roots, maxBytes: args.maxBytes };
+}
+
+/**
+ * Reads the attachment gateway configuration for a product from the environment.
+ * Roots are canonicalized once here; a direction is only reported as enabled when
+ * its flag is set and at least one valid root resolves.
+ */
+export function resolveAttachmentGateway(
+  product: ProductDefinition,
+  options?: { env?: Env; warn?: Warn },
+): AttachmentGateway {
+  const env = options?.env ?? process.env;
+  const warn = options?.warn ?? ((message: string) => console.error(`[attachment-gateway] ${message}`));
+  const p = envPrefix(product);
+
+  const exchangeDir = env[`${p}_ATTACHMENTS_DIR`]?.trim();
+  const dirRoots = exchangeDir ? [exchangeDir] : [];
+
+  const upload = resolveSide({
+    enabledFlag: readBool(env, `${p}_ATTACHMENTS_UPLOAD_ENABLED`),
+    rawRoots: [...readRoots(env, [`${p}_ATTACHMENTS_UPLOAD_ROOTS`]), ...dirRoots],
+    maxBytes: readBytes(env, `${p}_ATTACHMENTS_MAX_UPLOAD_BYTES`) ?? DEFAULT_MAX_ATTACHMENT_BYTES,
+    label: 'upload',
+    rootEnvHint: `${p}_ATTACHMENTS_UPLOAD_ROOTS or ${p}_ATTACHMENTS_DIR`,
+    warn,
+  });
+
+  const download = resolveSide({
+    enabledFlag: readBool(env, `${p}_ATTACHMENTS_DOWNLOAD_ENABLED`),
+    rawRoots: [...readRoots(env, [`${p}_ATTACHMENTS_DOWNLOAD_ROOTS`]), ...dirRoots],
+    maxBytes: readBytes(env, `${p}_ATTACHMENTS_MAX_DOWNLOAD_BYTES`) ?? DEFAULT_MAX_ATTACHMENT_BYTES,
+    label: 'download',
+    rootEnvHint: `${p}_ATTACHMENTS_DOWNLOAD_ROOTS or ${p}_ATTACHMENTS_DIR`,
+    warn,
+  });
+
+  return { upload, download };
+}
+
+function normalizeRelative(requested: string): string {
+  if (!requested || !requested.trim()) {
+    throw new Error('A file path is required');
+  }
+  if (isAbsolute(requested)) {
+    throw new Error(`Path must be relative to a configured attachment root, not absolute: "${requested}"`);
+  }
+  const norm = normalize(requested);
+  if (norm === '.' || norm === '..' || norm === '' || norm.startsWith(`..${sep}`) || norm.startsWith('../')) {
+    throw new Error(`Path must stay within the configured attachment root: "${requested}"`);
+  }
+  return norm;
+}
+
+function withinRoot(candidate: string, root: string): boolean {
+  return candidate === root || candidate.startsWith(root + sep);
+}
+
+/**
+ * Canonicalizes the deepest existing ancestor of `target` (resolving symlinked
+ * directories) and re-attaches the not-yet-existing tail. Used to confirm a path
+ * cannot escape a root through a symlinked parent directory.
+ */
+async function canonicalizeDeepestExisting(target: string): Promise<string> {
+  let current = target;
+  while (true) {
+    try {
+      const real = await realpath(current);
+      const tail = relative(current, target);
+      return tail ? join(real, tail) : real;
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) {
+        throw new Error(`Cannot resolve path: "${target}"`);
+      }
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Resolves `requested` (relative) against the allowed roots, returning an absolute
+ * path whose parent directory is canonically inside a root. The final path
+ * component is NOT symlink-resolved, so callers can still detect a symlinked leaf.
+ */
+async function resolveLeafWithinRoots(requested: string, roots: string[]): Promise<string> {
+  const norm = normalizeRelative(requested);
+  for (const root of roots) {
+    const lexical = resolve(root, norm);
+    if (!withinRoot(lexical, root)) {
+      continue;
+    }
+    const parentReal = await canonicalizeDeepestExisting(dirname(lexical));
+    if (withinRoot(parentReal, root)) {
+      return join(parentReal, basename(lexical));
+    }
+  }
+  throw new Error(`Path resolves outside the configured attachment root(s): "${requested}"`);
+}
+
+/**
+ * Resolves and validates a file to upload: it must live inside an allowed upload
+ * root, be a regular file (never a symlink or special file), and be within the
+ * size limit. Returns the absolute path to read.
+ */
+export async function resolveUploadSource(params: {
+  requestedPath: string;
+  side: AttachmentGatewaySide;
+}): Promise<{ absolutePath: string; size: number }> {
+  if (!params.side.enabled) {
+    throw new Error('Attachment upload from the local filesystem is disabled on this server');
+  }
+  const absolutePath = await resolveLeafWithinRoots(params.requestedPath, params.side.roots);
+  const info = await lstat(absolutePath);
+  if (info.isSymbolicLink()) {
+    throw new Error(`Refusing to upload a symlink: "${params.requestedPath}"`);
+  }
+  if (!info.isFile()) {
+    throw new Error(`Refusing to upload a non-regular file: "${params.requestedPath}"`);
+  }
+  if (info.size > params.side.maxBytes) {
+    throw new Error(
+      `File size ${info.size} bytes exceeds the configured upload limit of ${params.side.maxBytes} bytes`,
+    );
+  }
+  return { absolutePath, size: info.size };
+}
+
+/**
+ * Resolves a destination path to save a downloaded attachment into. The file is
+ * placed in the first configured download root; the caller writes with an
+ * exclusive flag so existing files (including symlinks) are never overwritten.
+ */
+export async function resolveDownloadDestination(params: {
+  requestedName: string;
+  side: AttachmentGatewaySide;
+}): Promise<string> {
+  if (!params.side.enabled) {
+    throw new Error('Saving attachments to the local filesystem is disabled on this server');
+  }
+  const safeName = basename(params.requestedName);
+  if (!safeName || safeName === '.' || safeName === '..') {
+    throw new Error(`Invalid attachment file name: "${params.requestedName}"`);
+  }
+  return resolveLeafWithinRoots(safeName, [params.side.roots[0]]);
+}
+
+/** Resolves a path within roots, throwing if it escapes. Exported for verification/tests. */
+export async function assertWithinRoots(requested: string, roots: string[]): Promise<string> {
+  return resolveLeafWithinRoots(requested, roots);
+}

package/src/index.ts

@@ -2,6 +2,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 export * from './api-error-handler.js'
+export * from './attachment-download.js'
+export * from './attachment-gateway.js'
 export * from './config/index.js';
 export { runSetup, runSetupCli } from './setup-cli.js';
 export { describeValidationError } from './setup/describe-error.js';