@atlassian-dc-mcp/common 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/b1ff/atlassian-dc-mcp/compare/v0.27.0...v0.28.0) (2026-07-22)
+
+
+### Features
+
+* **attachments:** sandbox local filesystem access behind an opt-in gateway ([2a22547](https://github.com/b1ff/atlassian-dc-mcp/commit/2a22547292a390a032642ad09bd09ede0808e9d7))
+* **jira:** add jira_downloadAttachment tool ([31cbeef](https://github.com/b1ff/atlassian-dc-mcp/commit/31cbeefd00fde37b1245efbe975ea4d63db46758))
+
+
+
+
+
 # [0.27.0](https://github.com/b1ff/atlassian-dc-mcp/compare/v0.26.0...v0.27.0) (2026-07-18)
 
 **Note:** Version bump only for package @atlassian-dc-mcp/common

package/build/__tests__/attachment-download.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attachment-download.test.d.ts.map

package/build/__tests__/attachment-download.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-download.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/attachment-download.test.ts"],"names":[],"mappings":""}

package/build/__tests__/attachment-download.test.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { downloadAttachment } from '../attachment-download.js';
+function mockFetchOnce(body, init) {
+    const ok = init?.ok ?? true;
+    const headers = new Map();
+    if (init?.contentType)
+        headers.set('content-type', init.contentType);
+    if (init?.contentLength)
+        headers.set('content-length', init.contentLength);
+    const response = {
+        ok,
+        status: init?.status ?? (ok ? 200 : 500),
+        statusText: init?.statusText ?? (ok ? 'OK' : 'Error'),
+        headers: { get: (name) => 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);
+}
+describe('downloadAttachment', () => {
+    let tmpDir;
+    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');
+    });
+});
+//# sourceMappingURL=attachment-download.test.js.map

package/build/__tests__/attachment-download.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-download.test.js","sourceRoot":"","sources":["../../src/__tests__/attachment-download.test.ts"],"names":[],"mappings":"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"}

package/build/__tests__/attachment-gateway.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attachment-gateway.test.d.ts.map

package/build/__tests__/attachment-gateway.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-gateway.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/attachment-gateway.test.ts"],"names":[],"mappings":""}

package/build/__tests__/attachment-gateway.test.js

@@ -0,0 +1,123 @@
+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';
+const PRODUCT = {
+    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;
+    let realRoot;
+    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;
+    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;
+    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');
+    });
+});
+//# sourceMappingURL=attachment-gateway.test.js.map

package/build/__tests__/attachment-gateway.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-gateway.test.js","sourceRoot":"","sources":["../../src/__tests__/attachment-gateway.test.ts"],"names":[],"mappings":"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"}

package/build/attachment-download.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 declare const DEFAULT_MAX_INLINE_BYTES = 1048576;
+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;
+}
+/**
+ * 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 declare function downloadAttachment(params: {
+    url: string;
+    token: string | (() => string | undefined);
+    filename: string;
+    mediaType?: string;
+    options?: AttachmentDownloadOptions;
+}): Promise<AttachmentDownloadResult>;
+//# sourceMappingURL=attachment-download.d.ts.map

package/build/attachment-download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-download.d.ts","sourceRoot":"","sources":["../src/attachment-download.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnE,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,UAAY,CAAC;AAElD,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC7B,kFAAkF;IAClF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AA6CD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,yBAAyB,CAAC;CACrC,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAmDpC"}

package/build/attachment-download.js

@@ -0,0 +1,94 @@
+import { writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+/** Default cap for inline content so responses do not balloon. 1 MiB. */
+export const DEFAULT_MAX_INLINE_BYTES = 1_048_576;
+async function resolveToken(token) {
+    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, cap, filename) {
+    const body = response.body;
+    if (cap !== undefined && body && typeof body.getReader === 'function') {
+        const reader = body.getReader();
+        const chunks = [];
+        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) {
+    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 = {
+        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;
+}
+//# sourceMappingURL=attachment-download.js.map

package/build/attachment-download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-download.js","sourceRoot":"","sources":["../src/attachment-download.ts"],"names":[],"mappings":"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"}

package/build/attachment-gateway.d.ts

@@ -0,0 +1,57 @@
+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 declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+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;
+/**
+ * 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 declare function resolveAttachmentGateway(product: ProductDefinition, options?: {
+    env?: Env;
+    warn?: Warn;
+}): AttachmentGateway;
+/**
+ * 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 declare function resolveUploadSource(params: {
+    requestedPath: string;
+    side: AttachmentGatewaySide;
+}): Promise<{
+    absolutePath: string;
+    size: number;
+}>;
+/**
+ * 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 declare function resolveDownloadDestination(params: {
+    requestedName: string;
+    side: AttachmentGatewaySide;
+}): Promise<string>;
+/** Resolves a path within roots, throwing if it escapes. Exported for verification/tests. */
+export declare function assertWithinRoots(requested: string, roots: string[]): Promise<string>;
+export {};
+//# sourceMappingURL=attachment-gateway.d.ts.map

package/build/attachment-gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-gateway.d.ts","sourceRoot":"","sources":["../src/attachment-gateway.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAE7D,MAAM,WAAW,qBAAqB;IACpC,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,EAAE,qBAAqB,CAAC;CACjC;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAC9C,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AA8EtC;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,GAAG,CAAC;IAAC,IAAI,CAAC,EAAE,IAAI,CAAA;CAAE,GACnC,iBAAiB,CA2BnB;AA8DD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,qBAAqB,CAAC;CAC7B,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBlD;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,qBAAqB,CAAC;CAC7B,GAAG,OAAO,CAAC,MAAM,CAAC,CASlB;AAED,6FAA6F;AAC7F,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAE3F"}