@atlassian-dc-mcp/common 0.27.0 → 0.28.0

package/build/attachment-gateway.js

@@ -0,0 +1,201 @@
+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';
+/**
+ * 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
+function envPrefix(product) {
+    return product.id.toUpperCase();
+}
+function readBool(env, name) {
+    const value = env[name]?.trim().toLowerCase();
+    return value === 'true' || value === '1' || value === 'yes';
+}
+function readBytes(env, name) {
+    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, names) {
+    const roots = [];
+    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, warn) {
+    const canonical = [];
+    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) {
+    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, options) {
+    const env = options?.env ?? process.env;
+    const warn = options?.warn ?? ((message) => 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) {
+    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, root) {
+    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) {
+    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, roots) {
+    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) {
+    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) {
+    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, roots) {
+    return resolveLeafWithinRoots(requested, roots);
+}
+//# sourceMappingURL=attachment-gateway.js.map

package/build/attachment-gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-gateway.js","sourceRoot":"","sources":["../src/attachment-gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAG9G;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,SAAS;AAmBvE,SAAS,SAAS,CAAC,OAA0B;IAC3C,OAAO,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED,SAAS,QAAQ,CAAC,GAAQ,EAAE,IAAY;IACtC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,OAAO,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,GAAG,IAAI,KAAK,KAAK,KAAK,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,GAAQ,EAAE,IAAY;IACvC,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACxC,OAAO,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACzC,CAAC;AAED,SAAS,SAAS,CAAC,GAAQ,EAAE,KAAe;IAC1C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,SAAS;QACX,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;YACxC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,iBAAiB,CAAC,QAAkB,EAAE,IAAU;IACvD,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACtB,IAAI,CAAC,2DAA2D,IAAI,GAAG,CAAC,CAAC;YACzE,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,wEAAwE,IAAI,GAAG,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,WAAW,CAAC,IAOpB;IACC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IAChE,CAAC;IACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,CACP,GAAG,IAAI,CAAC,KAAK,iEAAiE;YAC5E,QAAQ,IAAI,CAAC,WAAW,UAAU,IAAI,CAAC,KAAK,2BAA2B,CAC1E,CAAC;QACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA0B,EAC1B,OAAoC;IAEpC,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACxC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC,CAAC;IACtG,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAE7B,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,CAAC;IACxD,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAElD,MAAM,MAAM,GAAG,WAAW,CAAC;QACzB,WAAW,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,6BAA6B,CAAC;QAC7D,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC;QAC7E,QAAQ,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,+BAA+B,CAAC,IAAI,4BAA4B;QAC7F,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,GAAG,CAAC,gCAAgC,CAAC,kBAAkB;QACpE,IAAI;KACL,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,WAAW,CAAC;QAC3B,WAAW,EAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,+BAA+B,CAAC;QAC/D,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC,EAAE,GAAG,QAAQ,CAAC;QAC/E,QAAQ,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,iCAAiC,CAAC,IAAI,4BAA4B;QAC/F,KAAK,EAAE,UAAU;QACjB,WAAW,EAAE,GAAG,CAAC,kCAAkC,CAAC,kBAAkB;QACtE,IAAI;KACL,CAAC,CAAC;IAEH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,iBAAiB,CAAC,SAAiB;IAC1C,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,yEAAyE,SAAS,GAAG,CAAC,CAAC;IACzG,CAAC;IACD,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1G,MAAM,IAAI,KAAK,CAAC,0DAA0D,SAAS,GAAG,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,UAAU,CAAC,SAAiB,EAAE,IAAY;IACjD,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,2BAA2B,CAAC,MAAc;IACvD,IAAI,OAAO,GAAG,MAAM,CAAC;IACrB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;YACrC,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACvC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;YAChC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBACvB,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,GAAG,CAAC,CAAC;YACtD,CAAC;YACD,OAAO,GAAG,MAAM,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,sBAAsB,CAAC,SAAiB,EAAE,KAAe;IACtE,MAAM,IAAI,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;YAC/B,SAAS;QACX,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,2BAA2B,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QACvE,IAAI,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,CAAC;YACjC,OAAO,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,6DAA6D,SAAS,GAAG,CAAC,CAAC;AAC7F,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAGzC;IACC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,sBAAsB,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3F,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,CAAC,aAAa,GAAG,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,2CAA2C,MAAM,CAAC,aAAa,GAAG,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,aAAa,IAAI,CAAC,IAAI,iDAAiD,MAAM,CAAC,IAAI,CAAC,QAAQ,QAAQ,CACpG,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,MAGhD;IACC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAChD,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,CAAC,aAAa,GAAG,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,sBAAsB,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,SAAiB,EAAE,KAAe;IACxE,OAAO,sBAAsB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC"}

package/build/index.d.ts

@@ -1,5 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.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';

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,cAAc,wBAAwB,CAAA;AACtC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvG,eAAO,MAAM,kBAAkB,GAAI,QAAQ,OAAO;;;;;CAKhD,CAAC;AAGH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,UAGvC,CAAC;AAGF,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,aAKA;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,sBAkCpD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,cAAc,wBAAwB,CAAA;AACtC,cAAc,0BAA0B,CAAA;AACxC,cAAc,yBAAyB,CAAA;AACvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGvG,eAAO,MAAM,kBAAkB,GAAI,QAAQ,OAAO;;;;;CAKhD,CAAC;AAGH,eAAO,MAAM,WAAW,GAAI,OAAO,KAAK,UAGvC,CAAC;AAGF,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,aAKA;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,SAAS,sBAkCpD"}

package/build/index.js

@@ -1,6 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.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';

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,cAAc,wBAAwB,CAAA;AACtC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAwB,MAAM,iBAAiB,CAAC;AAEvG,2CAA2C;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAe,EAAE,EAAE,CAAC,CAAC;IACtD,OAAO,EAAE,CAAC;YACR,IAAI,EAAE,MAAe;YACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CAAC;CACH,CAAC,CAAC;AAEH,uBAAuB;AACvB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAE,EAAE;IAC1C,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;AAEF,sCAAsC;AACtC,MAAM,UAAU,eAAe,CAAC,OAG/B;IACC,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAiB;IACnD,0DAA0D;IAC1D,yBAAyB;IACzB,iDAAiD;IACjD,EAAE;IACF,wCAAwC;IACxC,0DAA0D;IAC1D,qCAAqC;IACrC,MAAM;IACN,EAAE;IACF,8CAA8C;IAC9C,kDAAkD;IAClD,MAAM;IACN,EAAE;IACF,mDAAmD;IACnD,sCAAsC;IACtC,2CAA2C;IAC3C,kDAAkD;IAClD,2CAA2C;IAC3C,4CAA4C;IAC5C,mBAAmB;IACnB,uBAAuB;IACvB,gBAAgB;IAChB,QAAQ;IACR,EAAE;IACF,uDAAuD;IACvD,qBAAqB;IACrB,QAAQ;IACR,MAAM;IAGN,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,cAAc,wBAAwB,CAAA;AACtC,cAAc,0BAA0B,CAAA;AACxC,cAAc,yBAAyB,CAAA;AACvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAwB,MAAM,iBAAiB,CAAC;AAEvG,2CAA2C;AAC3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAe,EAAE,EAAE,CAAC,CAAC;IACtD,OAAO,EAAE,CAAC;YACR,IAAI,EAAE,MAAe;YACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CAAC;CACH,CAAC,CAAC;AAEH,uBAAuB;AACvB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAY,EAAE,EAAE;IAC1C,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;AAEF,sCAAsC;AACtC,MAAM,UAAU,eAAe,CAAC,OAG/B;IACC,OAAO,IAAI,SAAS,CAAC;QACnB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAiB;IACnD,0DAA0D;IAC1D,yBAAyB;IACzB,iDAAiD;IACjD,EAAE;IACF,wCAAwC;IACxC,0DAA0D;IAC1D,qCAAqC;IACrC,MAAM;IACN,EAAE;IACF,8CAA8C;IAC9C,kDAAkD;IAClD,MAAM;IACN,EAAE;IACF,mDAAmD;IACnD,sCAAsC;IACtC,2CAA2C;IAC3C,kDAAkD;IAClD,2CAA2C;IAC3C,4CAA4C;IAC5C,mBAAmB;IACnB,uBAAuB;IACvB,gBAAgB;IAChB,QAAQ;IACR,EAAE;IACF,uDAAuD;IACvD,qBAAqB;IACrB,QAAQ;IACR,MAAM;IAGN,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlassian-dc-mcp/common",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "main": "build/index.js",
   "type": "module",
   "private": false,
@@ -39,5 +39,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8f0fb46e1faa03f3f6553b23d210773df37f0354"
+  "gitHead": "7f51cd1b0328ecc90785211511415e9609d09a25"
 }

package/src/__tests__/attachment-download.test.ts

@@ -0,0 +1,162 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { downloadAttachment } from '../attachment-download.js';
+
+function mockFetchOnce(
+  body: Buffer,
+  init?: { ok?: boolean; status?: number; statusText?: string; contentType?: string; contentLength?: string; stream?: boolean },
+) {
+  const ok = init?.ok ?? true;
+  const headers = new Map<string, string>();
+  if (init?.contentType) headers.set('content-type', init.contentType);
+  if (init?.contentLength) headers.set('content-length', init.contentLength);
+
+  const response: Record<string, unknown> = {
+    ok,
+    status: init?.status ?? (ok ? 200 : 500),
+    statusText: init?.statusText ?? (ok ? 'OK' : 'Error'),
+    headers: { get: (name: string) => headers.get(name.toLowerCase()) ?? null },
+    arrayBuffer: async () => body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength),
+  };
+
+  if (init?.stream) {
+    let sent = false;
+    response.body = {
+      getReader: () => ({
+        read: async () => (sent ? { done: true, value: undefined } : ((sent = true), { done: false, value: new Uint8Array(body) })),
+        cancel: async () => undefined,
+      }),
+    };
+  }
+
+  global.fetch = jest.fn().mockResolvedValue(response) as unknown as typeof fetch;
+}
+
+describe('downloadAttachment', () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dc-mcp-dl-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    jest.restoreAllMocks();
+  });
+
+  it('writes the file to the provided destination and reports metadata', async () => {
+    mockFetchOnce(Buffer.from('hello world'), { contentType: 'text/plain' });
+    const destination = path.join(tmpDir, 'note.txt');
+
+    const result = await downloadAttachment({
+      url: 'https://host/download/x',
+      token: 'tok',
+      filename: 'note.txt',
+      options: { destination },
+    });
+
+    expect(global.fetch).toHaveBeenCalledWith('https://host/download/x', {
+      headers: { Authorization: 'Bearer tok', 'X-Atlassian-Token': 'nocheck' },
+    });
+    expect(result.savedPath).toBe(destination);
+    expect(result.size).toBe(11);
+    expect(fs.readFileSync(destination, 'utf-8')).toBe('hello world');
+    expect(result.content).toBeUndefined();
+  });
+
+  it('refuses to overwrite an existing destination file', async () => {
+    mockFetchOnce(Buffer.from('new content'));
+    const destination = path.join(tmpDir, 'exists.txt');
+    fs.writeFileSync(destination, 'original');
+
+    await expect(
+      downloadAttachment({ url: 'https://host/x', token: 'tok', filename: 'exists.txt', options: { destination } }),
+    ).rejects.toThrow();
+    expect(fs.readFileSync(destination, 'utf-8')).toBe('original');
+  });
+
+  it('returns text content inline when requested', async () => {
+    mockFetchOnce(Buffer.from('inline text'));
+
+    const result = await downloadAttachment({
+      url: 'https://host/download/x',
+      token: () => 'tok',
+      filename: 'note.txt',
+      options: { returnContent: 'text' },
+    });
+
+    expect(result.content).toBe('inline text');
+    expect(result.encoding).toBe('text');
+    expect(result.savedPath).toBeUndefined();
+  });
+
+  it('returns base64 content inline when requested', async () => {
+    const bytes = Buffer.from([0x00, 0x01, 0x02, 0xff]);
+    mockFetchOnce(bytes);
+
+    const result = await downloadAttachment({
+      url: 'https://host/download/x',
+      token: 'tok',
+      filename: 'blob.bin',
+      options: { returnContent: 'base64' },
+    });
+
+    expect(result.content).toBe(bytes.toString('base64'));
+    expect(result.encoding).toBe('base64');
+  });
+
+  it('omits inline content when the file exceeds maxInlineBytes', async () => {
+    mockFetchOnce(Buffer.from('123456'));
+
+    const result = await downloadAttachment({
+      url: 'https://host/download/x',
+      token: 'tok',
+      filename: 'big.txt',
+      options: { returnContent: 'text', maxInlineBytes: 3 },
+    });
+
+    expect(result.content).toBeUndefined();
+    expect(result.contentOmittedReason).toContain('exceeds inline cap');
+  });
+
+  it('rejects early when content-length exceeds the download cap', async () => {
+    mockFetchOnce(Buffer.from('1234567890'), { contentLength: '10' });
+
+    await expect(
+      downloadAttachment({ url: 'https://host/x', token: 'tok', filename: 'big.bin', options: { maxDownloadBytes: 5 } }),
+    ).rejects.toThrow('exceeds the configured download limit');
+  });
+
+  it('aborts a streamed body that exceeds the download cap', async () => {
+    mockFetchOnce(Buffer.from('1234567890'), { stream: true });
+
+    await expect(
+      downloadAttachment({ url: 'https://host/x', token: 'tok', filename: 'big.bin', options: { maxDownloadBytes: 5 } }),
+    ).rejects.toThrow('exceeds the configured download limit');
+  });
+
+  it('enforces the cap on a buffered body without content-length', async () => {
+    mockFetchOnce(Buffer.from('1234567890'));
+
+    await expect(
+      downloadAttachment({ url: 'https://host/x', token: 'tok', filename: 'big.bin', options: { maxDownloadBytes: 5 } }),
+    ).rejects.toThrow('exceeds the configured download limit');
+  });
+
+  it('throws when the response is not ok', async () => {
+    mockFetchOnce(Buffer.from(''), { ok: false, status: 404, statusText: 'Not Found' });
+
+    await expect(
+      downloadAttachment({ url: 'https://host/x', token: 'tok', filename: 'f.txt' }),
+    ).rejects.toThrow('404 Not Found');
+  });
+
+  it('throws when no token is available', async () => {
+    mockFetchOnce(Buffer.from(''));
+
+    await expect(
+      downloadAttachment({ url: 'https://host/x', token: () => undefined, filename: 'f.txt' }),
+    ).rejects.toThrow('Missing API token');
+  });
+});

package/src/__tests__/attachment-gateway.test.ts

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  DEFAULT_MAX_ATTACHMENT_BYTES,
+  resolveAttachmentGateway,
+  resolveDownloadDestination,
+  resolveUploadSource,
+} from '../attachment-gateway.js';
+import type { ProductDefinition } from '../config/source.js';
+
+const PRODUCT: ProductDefinition = {
+  id: 'jira',
+  envVars: { host: 'JIRA_HOST', apiBasePath: 'JIRA_API_BASE_PATH', token: 'JIRA_API_TOKEN', defaultPageSize: 'JIRA_DEFAULT_PAGE_SIZE' },
+};
+
+const silentWarn = () => undefined;
+
+describe('resolveAttachmentGateway', () => {
+  let root: string;
+  let realRoot: string;
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'dc-mcp-gw-'));
+    realRoot = fs.realpathSync(root);
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('is disabled by default', () => {
+    const gw = resolveAttachmentGateway(PRODUCT, { env: {}, warn: silentWarn });
+    expect(gw.upload.enabled).toBe(false);
+    expect(gw.download.enabled).toBe(false);
+  });
+
+  it('stays disabled when enabled but no valid root is configured', () => {
+    const gw = resolveAttachmentGateway(PRODUCT, {
+      env: { JIRA_ATTACHMENTS_UPLOAD_ENABLED: 'true' },
+      warn: silentWarn,
+    });
+    expect(gw.upload.enabled).toBe(false);
+  });
+
+  it('enables upload with a canonical root and default size limit', () => {
+    const gw = resolveAttachmentGateway(PRODUCT, {
+      env: { JIRA_ATTACHMENTS_UPLOAD_ENABLED: 'true', JIRA_ATTACHMENTS_UPLOAD_ROOTS: root },
+      warn: silentWarn,
+    });
+    expect(gw.upload.enabled).toBe(true);
+    expect(gw.upload.roots).toEqual([realRoot]);
+    expect(gw.upload.maxBytes).toBe(DEFAULT_MAX_ATTACHMENT_BYTES);
+  });
+
+  it('uses JIRA_ATTACHMENTS_DIR as a shared exchange root and honours size overrides', () => {
+    const gw = resolveAttachmentGateway(PRODUCT, {
+      env: {
+        JIRA_ATTACHMENTS_UPLOAD_ENABLED: 'true',
+        JIRA_ATTACHMENTS_DOWNLOAD_ENABLED: '1',
+        JIRA_ATTACHMENTS_DIR: root,
+        JIRA_ATTACHMENTS_MAX_UPLOAD_BYTES: '1024',
+      },
+      warn: silentWarn,
+    });
+    expect(gw.upload.roots).toEqual([realRoot]);
+    expect(gw.download.roots).toEqual([realRoot]);
+    expect(gw.upload.maxBytes).toBe(1024);
+  });
+});
+
+describe('resolveUploadSource', () => {
+  let root: string;
+  const side = () => ({ enabled: true, roots: [fs.realpathSync(root)], maxBytes: 100 });
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'dc-mcp-up-'));
+  });
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('resolves a regular file inside the root', async () => {
+    fs.writeFileSync(path.join(root, 'a.txt'), 'hi');
+    const { absolutePath, size } = await resolveUploadSource({ requestedPath: 'a.txt', side: side() });
+    expect(absolutePath).toBe(path.join(fs.realpathSync(root), 'a.txt'));
+    expect(size).toBe(2);
+  });
+
+  it('rejects absolute paths', async () => {
+    await expect(resolveUploadSource({ requestedPath: '/etc/passwd', side: side() })).rejects.toThrow('not absolute');
+  });
+
+  it('rejects traversal outside the root', async () => {
+    await expect(resolveUploadSource({ requestedPath: '../secret', side: side() })).rejects.toThrow('within the configured');
+  });
+
+  it('rejects a symlink leaf', async () => {
+    const target = path.join(root, 'real.txt');
+    fs.writeFileSync(target, 'secret');
+    fs.symlinkSync(target, path.join(root, 'link.txt'));
+    await expect(resolveUploadSource({ requestedPath: 'link.txt', side: side() })).rejects.toThrow('symlink');
+  });
+
+  it('rejects a path that escapes via a symlinked directory', async () => {
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'dc-mcp-out-'));
+    fs.writeFileSync(path.join(outside, 'secret.txt'), 'x');
+    fs.symlinkSync(outside, path.join(root, 'escape'));
+    await expect(resolveUploadSource({ requestedPath: 'escape/secret.txt', side: side() })).rejects.toThrow('outside');
+    fs.rmSync(outside, { recursive: true, force: true });
+  });
+
+  it('rejects a non-regular file (directory)', async () => {
+    fs.mkdirSync(path.join(root, 'sub'));
+    await expect(resolveUploadSource({ requestedPath: 'sub', side: side() })).rejects.toThrow('non-regular');
+  });
+
+  it('rejects a file over the size limit', async () => {
+    fs.writeFileSync(path.join(root, 'big.txt'), 'x'.repeat(200));
+    await expect(resolveUploadSource({ requestedPath: 'big.txt', side: side() })).rejects.toThrow('exceeds the configured upload limit');
+  });
+
+  it('throws when upload is disabled', async () => {
+    await expect(
+      resolveUploadSource({ requestedPath: 'a.txt', side: { enabled: false, roots: [], maxBytes: 100 } }),
+    ).rejects.toThrow('disabled');
+  });
+});
+
+describe('resolveDownloadDestination', () => {
+  let root: string;
+  const side = () => ({ enabled: true, roots: [fs.realpathSync(root)], maxBytes: 100 });
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'dc-mcp-dd-'));
+  });
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('resolves a basename into the download root', async () => {
+    const dest = await resolveDownloadDestination({ requestedName: 'out.bin', side: side() });
+    expect(dest).toBe(path.join(fs.realpathSync(root), 'out.bin'));
+  });
+
+  it('strips directory components from the requested name', async () => {
+    const dest = await resolveDownloadDestination({ requestedName: '../../etc/passwd', side: side() });
+    expect(dest).toBe(path.join(fs.realpathSync(root), 'passwd'));
+  });
+
+  it('throws when saving is disabled', async () => {
+    await expect(
+      resolveDownloadDestination({ requestedName: 'out.bin', side: { enabled: false, roots: [], maxBytes: 100 } }),
+    ).rejects.toThrow('disabled');
+  });
+});