Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
/**
* Owner-supplied files arriving over HTTP.
*
* The runtime reads attachments from disk (`src/core/attachments.ts`), the same
* contract channels use for a WhatsApp photo: `{ kind, path, mime, name }`. A web
* or API client has bytes, not a path, so this module is the missing half — it
* validates what arrived and writes it under `<mercury home>/uploads/<yyyy-mm>/`,
* owned by Mercury and readable only by its user.
*
* Only bytes are accepted, never a server path: a client must not be able to make
* Mercury read a file it could not otherwise reach.
*/
import { existsSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
import { randomUUID } from 'node:crypto';
import { basename, dirname, extname, join, sep } from 'node:path';
import { getMercuryHome } from '../../utils/config.js';
import type { ChannelAttachment } from '../../types/channel.js';
import { decodeTextAttachment, MAX_TEXT_BYTES, textAttachmentMime, textPrefix } from '../../core/text-attachments.js';
/** Same caps as the runtime applies when it hands files to the model. */
export const MAX_FILES = 4;
export const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
export const MAX_PDF_BYTES = 15 * 1024 * 1024;
export { MAX_TEXT_BYTES };
export interface InlineAttachment {
/** Display name; only its basename is kept. */
name?: string;
/** Optional hint — the bytes decide. */
mime?: string;
/** Base64. A `data:` URL prefix is tolerated and stripped. */
data: string;
}
export type UploadResult =
| { ok: true; attachments: ChannelAttachment[] }
| { ok: false; error: string };
const IMAGE_EXTENSIONS = new Map([
['image/jpeg', '.jpg'],
['image/png', '.png'],
['image/webp', '.webp'],
['image/gif', '.gif'],
]);
const PDF_MIME = 'application/pdf';
/** `<mercury home>/uploads/<yyyy-mm>/` — created on demand. */
export function uploadsDir(now: Date = new Date()): string {
const month = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}`;
return join(getMercuryHome(), 'uploads', month);
}
/** Recognises the formats the model can take, from the bytes rather than the label. */
function sniff(bytes: Buffer): { mime: string; kind: 'image' | 'document' } | null {
if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
return { mime: 'image/png', kind: 'image' };
}
if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
return { mime: 'image/jpeg', kind: 'image' };
}
if (bytes.length >= 6 && bytes.subarray(0, 6).toString('latin1').match(/^GIF8[79]a$/)) {
return { mime: 'image/gif', kind: 'image' };
}
if (
bytes.length >= 12 &&
bytes.subarray(0, 4).toString('latin1') === 'RIFF' &&
bytes.subarray(8, 12).toString('latin1') === 'WEBP'
) {
return { mime: 'image/webp', kind: 'image' };
}
if (bytes.length >= 5 && bytes.subarray(0, 5).toString('latin1') === '%PDF-') {
return { mime: PDF_MIME, kind: 'document' };
}
return null;
}
/** Keeps the basename, drops traversal and control characters, forces an extension. */
function safeFileName(name: string | undefined, extension: string, text = false): string {
const base = (name ?? '').split(/[\\/]/).pop() ?? '';
const cleaned = base
// eslint-disable-next-line no-control-regex
.replace(/[\u0000-\u001f<>:"|?*]+/g, '')
.replace(/\s+/g, ' ')
.trim();
if (text) {
// Keep the type-bearing extension when shortening long names: the runtime
// and download route must still recognize this file after it is stored.
const supplied = extname(cleaned);
const suffix = /^\.(txt|md|markdown)$/i.test(supplied) ? supplied : extension;
const stem = textPrefix(cleaned.slice(0, cleaned.length - supplied.length), 80 - suffix.length) || `upload-${randomUUID().slice(0, 8)}`;
return `${stem}${suffix}`.replace(/^\.+/, '_');
}
const shortened = cleaned.slice(0, 80);
const useful = shortened && extname(shortened).toLowerCase() !== '' ? shortened : `upload-${randomUUID().slice(0, 8)}${extension}`;
return useful.replace(/^\.+/, '_');
}
function decode(data: string): Buffer | null {
const payload = data.startsWith('data:') ? data.replace(/^data:[^,]*;base64,/, '') : data;
// Text has no magic bytes to catch permissive base64 decoding. Require the
// standard encoding, including padding, before interpreting any UTF-8.
if (payload.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(payload)) return null;
return Buffer.from(payload, 'base64');
}
/**
* Validates and persists the attachments of one request.
*
* A rejected attachment rejects the whole request: silently dropping the photo
* and sending the text alone is the behaviour that makes an owner think the
* model ignored them.
*/
export function storeInlineAttachments(input: unknown, now: Date = new Date()): UploadResult {
if (input === undefined || input === null) return { ok: true, attachments: [] };
if (!Array.isArray(input)) return { ok: false, error: 'attachments must be an array' };
if (input.length === 0) return { ok: true, attachments: [] };
if (input.length > MAX_FILES) return { ok: false, error: `at most ${MAX_FILES} attachments per message` };
const stored: Array<{ attachment: ChannelAttachment; bytes: Buffer }> = [];
for (const [index, raw] of input.entries()) {
const item = raw as Partial<InlineAttachment> | null;
if (!item || typeof item !== 'object' || typeof item.data !== 'string') {
return { ok: false, error: `attachment ${index + 1} needs base64 "data"` };
}
if ((item.name !== undefined && typeof item.name !== 'string') || (item.mime !== undefined && typeof item.mime !== 'string')) {
return { ok: false, error: `attachment ${index + 1} name and mime must be strings` };
}
if (item.data.length > Math.ceil(MAX_PDF_BYTES / 3) * 4 + 1024) {
return { ok: false, error: `attachment ${index + 1} exceeds the maximum upload size (15 MB)` };
}
const bytes = decode(item.data);
if (!bytes) return { ok: false, error: `attachment ${index + 1} is not valid base64` };
const textMime = textAttachmentMime(item.name, item.mime);
const sniffed = sniff(bytes) ?? (textMime ? { mime: textMime, kind: 'document' as const } : null);
if (!sniffed) {
return { ok: false, error: `attachment ${index + 1} is not a supported image (png, jpeg, webp, gif), PDF, TXT or Markdown file` };
}
const isText = sniffed.mime.startsWith('text/');
const limit = isText ? MAX_TEXT_BYTES : sniffed.kind === 'image' ? MAX_IMAGE_BYTES : MAX_PDF_BYTES;
if (bytes.length > limit) {
return {
ok: false,
error: isText ? `attachment ${index + 1} exceeds the text limit of 256 KiB` : `attachment ${index + 1} is ${Math.round(bytes.length / 1048576)} MB; the limit is ${Math.round(limit / 1048576)} MB`,
};
}
if (isText && decodeTextAttachment(bytes) === null) {
return { ok: false, error: `attachment ${index + 1} must be UTF-8 text without binary control characters` };
}
stored.push({
attachment: {
kind: sniffed.kind,
path: '',
mime: sniffed.mime,
name: safeFileName(item.name, isText ? (sniffed.mime === 'text/markdown' ? '.md' : '.txt') : IMAGE_EXTENSIONS.get(sniffed.mime) ?? '.pdf', isText),
},
bytes,
});
}
const dir = uploadsDir(now);
mkdirSync(dir, { recursive: true, mode: 0o700 });
return {
ok: true,
attachments: stored.map(({ attachment, bytes }) => {
const path = join(dir, `${randomUUID()}-${attachment.name}`);
writeFileSync(path, bytes, { mode: 0o600 });
return { ...attachment, path };
}),
};
}
// ── Serving stored uploads back to the owner ─────────────────────────────
//
// A sent file is recorded on its message as a REF: "<yyyy-mm>/<file>",
// relative to the uploads root, never an absolute path. Clients fetch it
// through GET /api/chat/uploads/:month/:file (authenticated like every API
// route). Both parts are validated by shape and the resolved file must sit
// directly in that month's folder, so a ref can never reach anything else.
const MONTH_RE = /^\d{4}-\d{2}$/;
const FILE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-[^/\\]{1,200}$/i;
export interface AttachmentRef {
name: string;
kind: 'image' | 'document';
mime?: string;
ref: string;
}
/** The ref of a stored upload path, or null when the path is not one. */
export function uploadRef(path: string): string | null {
const file = basename(path);
const month = basename(dirname(path));
if (!MONTH_RE.test(month) || !FILE_RE.test(file)) return null;
if (dirname(dirname(path)) !== join(getMercuryHome(), 'uploads')) return null;
return `${month}/${file}`;
}
/** Message metadata for the attachments of one turn (only real uploads). */
export function attachmentRefs(attachments: unknown): AttachmentRef[] {
if (!Array.isArray(attachments)) return [];
const out: AttachmentRef[] = [];
for (const a of attachments as ChannelAttachment[]) {
if (!a || typeof a.path !== 'string') continue;
const ref = uploadRef(a.path);
if (!ref) continue;
out.push({ name: a.name ?? basename(a.path), kind: a.kind, ...(a.mime ? { mime: a.mime } : {}), ref });
}
return out;
}
/** Resolve a ref from a request to the file on disk, or null. */
export function resolveUploadRef(month: string, file: string): string | null {
if (!MONTH_RE.test(month) || !FILE_RE.test(file)) return null;
const root = join(getMercuryHome(), 'uploads', month);
const path = join(root, file);
if (!existsSync(path)) return null;
try {
const real = realpathSync(path);
const realRoot = realpathSync(root);
if (dirname(real) !== realRoot || real.includes(`..${sep}`)) return null;
return real;
} catch {
return null;
}
}
/** The served type of a stored upload, from its bytes; null for anything else. */
export function uploadMime(bytes: Buffer, name?: string): string | null {
// Markdown is served as inert text, never interpreted as HTML in this origin.
return sniff(bytes)?.mime ?? (textAttachmentMime(name) && decodeTextAttachment(bytes) !== null ? 'text/plain; charset=utf-8' : null);
}