@batalabs/virlow-mcp-core 3.80.0 → 3.81.1

package/dist/cjs/api.d.ts

@@ -80,6 +80,35 @@ export interface ApiFolder {
     /** Encrypted v2 blob of the folder's property and view definitions. */
     encryptedSchema: string | null;
 }
+/** One attachment's metadata. The filename is only ever in encryptedTitle. */
+export interface ApiFile {
+    id: string;
+    noteId: string;
+    filename: string;
+    /** Legacy plaintext filename; null for anything a current client uploaded. */
+    originalName: string | null;
+    encryptedTitle: string;
+    iv: string;
+    salt: string;
+    mimeType: string;
+    size: number;
+    uploadedAt: string;
+    /** Set while the file is in the note's Recently deleted. */
+    deletedAt: string | null;
+}
+export interface ApiFileWithData extends ApiFile {
+    /** "v2:<iv>:<ciphertext>"; anything else is legacy v1. */
+    encryptedData: string;
+    noteSalt: string | null;
+}
+export interface FileUpload {
+    encryptedTitle: string;
+    encryptedData: string;
+    iv: string;
+    salt: string;
+    mimeType: string;
+    size: number;
+}
 export declare class VirlowApi {
     private readonly baseUrl;
     private tokens;
@@ -171,4 +200,21 @@ export declare class VirlowApi {
         mcpEnabled?: boolean;
         encryptedSchema?: string | null;
     }): Promise<ApiFolder>;
+    listFiles(noteId: string, opts?: {
+        trashed?: boolean;
+    }): Promise<ApiFile[]>;
+    /** The full row, ciphertext included. Trashed files are served too. */
+    getFile(id: string): Promise<ApiFileWithData>;
+    /** Metadata only: what an exposure check needs, without up to 50 MB of ciphertext. */
+    getFileMeta(id: string): Promise<ApiFile>;
+    uploadFile(noteId: string, body: FileUpload): Promise<ApiFile>;
+    patchFile(id: string, body: {
+        encryptedTitle?: string;
+        iv?: string;
+        noteId?: string;
+    }): Promise<ApiFile>;
+    /** Moves the file to the note's Recently deleted. There is deliberately no
+     * way to hard-delete from here: Claude's deletes can always be undone. */
+    deleteFile(id: string): Promise<void>;
+    restoreFile(id: string): Promise<ApiFile>;
 }

package/dist/cjs/api.js

@@ -222,5 +222,31 @@ class VirlowApi {
     updateFolder(id, body) {
         return this.request('PUT', `/api/folders/${id}`, body);
     }
+    listFiles(noteId, opts = {}) {
+        const qs = opts.trashed ? '?trashed=true' : '';
+        return this.request('GET', `/api/notes/${encodeURIComponent(noteId)}/files${qs}`);
+    }
+    /** The full row, ciphertext included. Trashed files are served too. */
+    getFile(id) {
+        return this.request('GET', `/api/files/${encodeURIComponent(id)}`);
+    }
+    /** Metadata only: what an exposure check needs, without up to 50 MB of ciphertext. */
+    getFileMeta(id) {
+        return this.request('GET', `/api/files/${encodeURIComponent(id)}?metadata=true`);
+    }
+    uploadFile(noteId, body) {
+        return this.request('POST', `/api/notes/${encodeURIComponent(noteId)}/files`, body);
+    }
+    patchFile(id, body) {
+        return this.request('PATCH', `/api/files/${encodeURIComponent(id)}`, body);
+    }
+    /** Moves the file to the note's Recently deleted. There is deliberately no
+     * way to hard-delete from here: Claude's deletes can always be undone. */
+    deleteFile(id) {
+        return this.request('DELETE', `/api/files/${encodeURIComponent(id)}`);
+    }
+    restoreFile(id) {
+        return this.request('POST', `/api/files/${encodeURIComponent(id)}/restore`);
+    }
 }
 exports.VirlowApi = VirlowApi;

package/dist/cjs/attachment-format.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure helpers for the attachment tools: names, types, sizes and how a file
+ * is shown to a model. No I/O, so every rule here is tested directly.
+ */
+export declare const FILENAME_MAX = 255;
+/** `text` and `content_base64`: what fits comfortably in one MCP message. */
+export declare const INLINE_MAX_BYTES: number;
+/** `path`: under the API's effective ceiling (~38 MB raw after the double base64). */
+export declare const PATH_MAX_BYTES: number;
+/** Largest non-text file read_attachment returns inline as base64. */
+export declare const BINARY_INLINE_MAX_BYTES: number;
+export declare const TEXT_MAX_CHARS = 200000;
+/**
+ * The name shown and stored (encrypted). Basename only, so a model passing a
+ * full path does not leak the user's directory layout into the note; control
+ * characters out; capped at 255 with the extension kept.
+ */
+export declare function sanitizeFilename(name: string): string;
+export declare function inferMimeType(filename: string): string;
+export declare function isTextLike(mimeType: string, filename: string): boolean;
+export declare function formatSize(bytes: number): string;
+/**
+ * atob accepts sloppy input on some runtimes; this does not. Bounded before
+ * anything is decoded: four characters carry three bytes, so input longer than
+ * ceil(max * 4 / 3) plus one padded group cannot fit in `max` and is refused
+ * without allocating its decoded form.
+ */
+export declare function decodeBase64Strict(input: string, max?: number): Uint8Array;
+/** Size gate shared by every add_attachment source. Returns the bytes so it can wrap a source inline. */
+export declare function checkSize(bytes: Uint8Array, max: number, label: string): Uint8Array;
+/**
+ * What read_attachment returns for a file it does not save: text as text,
+ * small binaries as base64 under a one-line header, and a clear refusal for
+ * anything bigger.
+ */
+export declare function renderAttachment(info: {
+    filename: string;
+    mimeType: string;
+}, bytes: Uint8Array, opts: {
+    canSave: boolean;
+}): string;

package/dist/cjs/attachment-format.js

@@ -0,0 +1,214 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEXT_MAX_CHARS = exports.BINARY_INLINE_MAX_BYTES = exports.PATH_MAX_BYTES = exports.INLINE_MAX_BYTES = exports.FILENAME_MAX = void 0;
+exports.sanitizeFilename = sanitizeFilename;
+exports.inferMimeType = inferMimeType;
+exports.isTextLike = isTextLike;
+exports.formatSize = formatSize;
+exports.decodeBase64Strict = decodeBase64Strict;
+exports.checkSize = checkSize;
+exports.renderAttachment = renderAttachment;
+const virlow_crypto_1 = require("@batalabs/virlow-crypto");
+/**
+ * Pure helpers for the attachment tools: names, types, sizes and how a file
+ * is shown to a model. No I/O, so every rule here is tested directly.
+ */
+exports.FILENAME_MAX = 255;
+/** `text` and `content_base64`: what fits comfortably in one MCP message. */
+exports.INLINE_MAX_BYTES = 2 * 1024 * 1024;
+/** `path`: under the API's effective ceiling (~38 MB raw after the double base64). */
+exports.PATH_MAX_BYTES = 35 * 1024 * 1024;
+/** Largest non-text file read_attachment returns inline as base64. */
+exports.BINARY_INLINE_MAX_BYTES = 2 * 1024 * 1024;
+exports.TEXT_MAX_CHARS = 200_000;
+const FALLBACK_NAME = 'attachment';
+const FORMAT_CONTROL = /\p{Cf}/u;
+/**
+ * The name shown and stored (encrypted). Basename only, so a model passing a
+ * full path does not leak the user's directory layout into the note; control
+ * characters out; capped at 255 with the extension kept.
+ */
+function sanitizeFilename(name) {
+    const base = name.split(/[\\/]/).pop() ?? '';
+    const cleaned = Array.from(base)
+        .filter((ch) => {
+        const c = ch.codePointAt(0) ?? 0;
+        if (c < 0x20 || c === 0x7f || (c >= 0x80 && c <= 0x9f))
+            return false;
+        // Line and paragraph separators break lines like a newline does; format
+        // controls (bidi overrides, zero-width characters, BOM) make a name
+        // read differently from what it is.
+        return c !== 0x2028 && c !== 0x2029 && !FORMAT_CONTROL.test(ch);
+    })
+        .join('')
+        .trim();
+    if (!cleaned || cleaned === '.' || cleaned === '..')
+        return FALLBACK_NAME;
+    if (cleaned.length <= exports.FILENAME_MAX)
+        return cleaned;
+    const dot = cleaned.lastIndexOf('.');
+    const ext = dot > 0 && cleaned.length - dot <= 16 ? cleaned.slice(dot) : '';
+    return cleaned.slice(0, exports.FILENAME_MAX - ext.length) + ext;
+}
+/** Every value here is on the API's MIME allowlist (virlow-api src/lib/validation.ts). */
+const MIME_BY_EXT = {
+    txt: 'text/plain',
+    log: 'text/plain',
+    md: 'text/markdown',
+    markdown: 'text/markdown',
+    csv: 'text/csv',
+    json: 'application/json',
+    xml: 'application/xml',
+    html: 'text/html',
+    htm: 'text/html',
+    rtf: 'application/rtf',
+    pdf: 'application/pdf',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    bmp: 'image/bmp',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+    avif: 'image/avif',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    ico: 'image/x-icon',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    pages: 'application/vnd.apple.pages',
+    numbers: 'application/vnd.apple.numbers',
+    zip: 'application/zip',
+    gz: 'application/gzip',
+    tar: 'application/x-tar',
+    '7z': 'application/x-7z-compressed',
+    rar: 'application/vnd.rar',
+    mp3: 'audio/mpeg',
+    m4a: 'audio/x-m4a',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    aac: 'audio/aac',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    avi: 'video/x-msvideo',
+    woff: 'font/woff',
+    woff2: 'font/woff2',
+    ttf: 'font/ttf',
+    otf: 'font/otf',
+    wasm: 'application/wasm',
+};
+/**
+ * Source code. Stored as text/plain, because text/javascript and friends are
+ * not on the API allowlist; read back as text by extension.
+ */
+const CODE_EXTENSIONS = new Set([
+    'js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'py', 'rb', 'go', 'rs', 'java', 'kt', 'swift',
+    'c', 'h', 'cpp', 'hpp', 'cs', 'php', 'sh', 'bash', 'zsh', 'ps1', 'sql', 'yaml', 'yml',
+    'toml', 'ini', 'conf', 'env', 'css', 'scss', 'less', 'vue', 'svelte', 'lua', 'r', 'dart',
+    'scala', 'gradle', 'dockerfile', 'makefile',
+]);
+const TEXT_MIME = new Set([
+    'application/json',
+    'application/xml',
+    'application/javascript',
+    'application/x-javascript',
+    'application/x-ndjson',
+    'application/yaml',
+    'application/x-yaml',
+]);
+/** Lowercased extension, or the whole lowercased name when there is no dot (Dockerfile). */
+function extOf(filename) {
+    const lower = filename.toLowerCase();
+    const dot = lower.lastIndexOf('.');
+    return dot === -1 ? lower : lower.slice(dot + 1);
+}
+function inferMimeType(filename) {
+    const ext = extOf(filename);
+    if (MIME_BY_EXT[ext])
+        return MIME_BY_EXT[ext];
+    if (CODE_EXTENSIONS.has(ext))
+        return 'text/plain';
+    return 'application/octet-stream';
+}
+function isTextLike(mimeType, filename) {
+    const mime = mimeType.split(';')[0].trim().toLowerCase();
+    if (mime.startsWith('text/') || TEXT_MIME.has(mime))
+        return true;
+    if (mime.endsWith('+json') || mime.endsWith('+xml'))
+        return true;
+    const ext = extOf(filename);
+    if (CODE_EXTENSIONS.has(ext))
+        return true;
+    const byExt = MIME_BY_EXT[ext];
+    return byExt !== undefined && (byExt.startsWith('text/') || TEXT_MIME.has(byExt));
+}
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * atob accepts sloppy input on some runtimes; this does not. Bounded before
+ * anything is decoded: four characters carry three bytes, so input longer than
+ * ceil(max * 4 / 3) plus one padded group cannot fit in `max` and is refused
+ * without allocating its decoded form.
+ */
+function decodeBase64Strict(input, max = exports.INLINE_MAX_BYTES) {
+    const compact = input.replace(/\s+/g, '');
+    if (compact.length > Math.ceil((max * 4) / 3) + 4) {
+        throw new Error(`content_base64 is about ${formatSize(Math.floor((compact.length * 3) / 4))}; the limit for inline content is ${formatSize(max)}.`);
+    }
+    if (compact.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(compact)) {
+        throw new Error('content_base64 is not valid base64.');
+    }
+    return (0, virlow_crypto_1.base64ToBytes)(compact);
+}
+/** Size gate shared by every add_attachment source. Returns the bytes so it can wrap a source inline. */
+function checkSize(bytes, max, label) {
+    if (bytes.byteLength === 0) {
+        throw new Error(`${label} is empty. There is nothing to attach.`);
+    }
+    if (bytes.byteLength > max) {
+        const where = max === exports.INLINE_MAX_BYTES
+            ? 'the limit for inline content is'
+            : 'the limit for attaching from disk is';
+        const hint = max === exports.INLINE_MAX_BYTES
+            ? ' Attach larger files from disk with path, using a local Virlow MCP server.'
+            : '';
+        throw new Error(`${label} is ${formatSize(bytes.byteLength)}; ${where} ${formatSize(max)}.${hint}`);
+    }
+    return bytes;
+}
+/**
+ * What read_attachment returns for a file it does not save: text as text,
+ * small binaries as base64 under a one-line header, and a clear refusal for
+ * anything bigger.
+ */
+function renderAttachment(info, bytes, opts) {
+    // The name is the one part of the header a file's author controls, so it is
+    // cleaned here too: a newline in it must not start a line of its own.
+    const filename = sanitizeFilename(info.filename);
+    if (isTextLike(info.mimeType, filename)) {
+        const text = new TextDecoder('utf-8').decode(bytes);
+        if (text.length <= exports.TEXT_MAX_CHARS)
+            return text;
+        return (`${text.slice(0, exports.TEXT_MAX_CHARS)}\n\n` +
+            `[truncated: showing the first ${exports.TEXT_MAX_CHARS} of ${text.length} characters]`);
+    }
+    if (bytes.byteLength <= exports.BINARY_INLINE_MAX_BYTES) {
+        return `${filename} · ${info.mimeType} · ${formatSize(bytes.byteLength)} · base64\n${(0, virlow_crypto_1.bytesToBase64)(bytes)}`;
+    }
+    const size = `${filename} is ${formatSize(bytes.byteLength)}, larger than the ${formatSize(exports.BINARY_INLINE_MAX_BYTES)} that can be returned inline.`;
+    throw new Error(opts.canSave
+        ? `${size} Pass save_to with an absolute path to write it to disk.`
+        : `${size} Open it in the Virlow app, or read it through a local Virlow MCP server, which can save it to disk.`);
+}

package/dist/cjs/attachments.d.ts

@@ -0,0 +1,38 @@
+import { type VirlowApi } from './api.js';
+import type { Vault } from './vault.js';
+export interface AttachmentInfo {
+    id: string;
+    noteId: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+    uploadedAt: string;
+    deletedAt: string | null;
+}
+export declare class AttachmentsService {
+    private readonly api;
+    private readonly vault;
+    constructor(api: VirlowApi, vault: Vault);
+    list(noteId: string, includeTrashed: boolean): Promise<AttachmentInfo[]>;
+    add(input: {
+        noteId: string;
+        filename: string;
+        mimeType?: string;
+        /** The bytes came from `text`: a name with no known extension is then text, not binary. */
+        fromText?: boolean;
+        bytes: Uint8Array;
+    }): Promise<AttachmentInfo>;
+    read(id: string): Promise<{
+        info: AttachmentInfo;
+        bytes: Uint8Array;
+    }>;
+    rename(id: string, newFilename: string): Promise<AttachmentInfo>;
+    move(id: string, toNoteId: string): Promise<AttachmentInfo>;
+    trash(id: string): Promise<void>;
+    restore(id: string): Promise<AttachmentInfo>;
+    /** Metadata with the filename decrypted. A legacy row's placeholder title
+     * does not decrypt; it falls back to its plaintext name, then a generic one. */
+    private describe;
+    private requireExposed;
+    private requireSession;
+}

package/dist/cjs/attachments.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentsService = void 0;
+const virlow_crypto_1 = require("@batalabs/virlow-crypto");
+const exposure_js_1 = require("./exposure.js");
+const api_js_1 = require("./api.js");
+const attachment_format_js_1 = require("./attachment-format.js");
+/** A file this vault's key cannot open: encrypted before the account had a
+ * master password, under the web app's old per-device key. */
+const WRONG_KEY_MESSAGE = 'Could not decrypt this file with your vault key. Open it in the Virlow app.';
+/**
+ * The API's 409 for renaming a v1 file (virlow-api src/routes/files/crud.ts):
+ * its content shares the column IV with the filename, so the name cannot be
+ * re-encrypted on its own. Matched on the text, because the other 409 on that
+ * route ("Restore this file before changing it") must pass through as it is.
+ */
+const API_LEGACY_RENAME_PREFIX = 'This file uses an older format.';
+function renameFailure(err) {
+    if (err instanceof api_js_1.ApiError && err.status === 409 && err.message.startsWith(API_LEGACY_RENAME_PREFIX)) {
+        return new virlow_crypto_1.LegacyAttachmentError();
+    }
+    return err;
+}
+function decryptFailure(err) {
+    if (err instanceof virlow_crypto_1.LegacyAttachmentError)
+        return err;
+    if (err instanceof Error && err.name === 'OperationError')
+        return new Error(WRONG_KEY_MESSAGE);
+    return err instanceof Error ? err : new Error(String(err));
+}
+/**
+ * Attachments as the MCP tools see them. Holds no state of its own (no
+ * caches, no lock hook), so buildServer can make one per server without
+ * touching the shared ServerServices shape that virlow-api builds by hand.
+ *
+ * Every method checks exposure for every note it touches, the same rule as
+ * NotesService.requireExposed: knowing a file's id is not consent to reach
+ * into a folder the user has not opened to AI.
+ */
+function inferredMimeType(filename, fromText) {
+    const inferred = (0, attachment_format_js_1.inferMimeType)(filename);
+    return fromText && inferred === 'application/octet-stream' ? 'text/plain' : inferred;
+}
+class AttachmentsService {
+    api;
+    vault;
+    constructor(api, vault) {
+        this.api = api;
+        this.vault = vault;
+    }
+    async list(noteId, includeTrashed) {
+        const key = this.requireSession();
+        await this.requireExposed(noteId);
+        const live = await this.api.listFiles(noteId);
+        const trashed = includeTrashed ? await this.api.listFiles(noteId, { trashed: true }) : [];
+        return Promise.all([...live, ...trashed].map((file) => this.describe(key, file)));
+    }
+    async add(input) {
+        // A backstop under the tools' own per-source caps, so no caller can encrypt
+        // and send nothing, or more than the API could ever accept.
+        if (input.bytes.byteLength === 0)
+            throw new Error('The file is empty. There is nothing to attach.');
+        if (input.bytes.byteLength > attachment_format_js_1.PATH_MAX_BYTES) {
+            throw new Error(`The file is ${(0, attachment_format_js_1.formatSize)(input.bytes.byteLength)}; the most that can be attached is ${(0, attachment_format_js_1.formatSize)(attachment_format_js_1.PATH_MAX_BYTES)}.`);
+        }
+        const key = this.requireSession();
+        await this.requireExposed(input.noteId);
+        const filename = (0, attachment_format_js_1.sanitizeFilename)(input.filename);
+        const encrypted = await (0, virlow_crypto_1.encryptAttachment)(key, filename, input.bytes);
+        const row = await this.api.uploadFile(input.noteId, {
+            ...encrypted,
+            // Stored for the web app's legacy per-salt key; unused under a master key.
+            salt: (0, virlow_crypto_1.bytesToBase64)(crypto.getRandomValues(new Uint8Array(32))),
+            mimeType: input.mimeType ?? inferredMimeType(filename, input.fromText === true),
+            size: input.bytes.byteLength,
+        });
+        return { ...infoOf(row), filename };
+    }
+    async read(id) {
+        const key = this.requireSession();
+        // Metadata first, so a file in a closed folder is never downloaded at all.
+        const meta = await this.api.getFileMeta(id);
+        await this.requireExposed(meta.noteId);
+        const file = await this.api.getFile(id);
+        // Moved between the two calls: check where it is now, too.
+        if (file.noteId !== meta.noteId)
+            await this.requireExposed(file.noteId);
+        try {
+            const { filename, bytes } = await (0, virlow_crypto_1.decryptAttachment)(key, file);
+            return { info: { ...infoOf(file), filename: (0, attachment_format_js_1.sanitizeFilename)(filename) }, bytes };
+        }
+        catch (err) {
+            throw decryptFailure(err);
+        }
+    }
+    async rename(id, newFilename) {
+        const key = this.requireSession();
+        const file = await this.api.getFileMeta(id);
+        await this.requireExposed(file.noteId);
+        const filename = (0, attachment_format_js_1.sanitizeFilename)(newFilename);
+        const row = await this.api
+            .patchFile(id, await (0, virlow_crypto_1.encryptAttachmentName)(key, filename))
+            .catch((err) => {
+            throw renameFailure(err);
+        });
+        return { ...infoOf(row), filename };
+    }
+    async move(id, toNoteId) {
+        const key = this.requireSession();
+        const file = await this.api.getFileMeta(id);
+        // Both ends: out of a closed folder would reveal it, into one would hide
+        // a file where the user cannot expect Claude to have put it.
+        await this.requireExposed(file.noteId, toNoteId);
+        return this.describe(key, await this.api.patchFile(id, { noteId: toNoteId }));
+    }
+    async trash(id) {
+        this.requireSession();
+        const file = await this.api.getFileMeta(id);
+        await this.requireExposed(file.noteId);
+        await this.api.deleteFile(id);
+    }
+    async restore(id) {
+        const key = this.requireSession();
+        const file = await this.api.getFileMeta(id);
+        await this.requireExposed(file.noteId);
+        return this.describe(key, await this.api.restoreFile(id));
+    }
+    /** Metadata with the filename decrypted. A legacy row's placeholder title
+     * does not decrypt; it falls back to its plaintext name, then a generic one. */
+    async describe(key, file) {
+        try {
+            const filename = await (0, virlow_crypto_1.decryptTitleField)(key, file.encryptedTitle, file.iv);
+            // Names reach the model; one with a newline in it must not add a line.
+            return { ...infoOf(file), filename: (0, attachment_format_js_1.sanitizeFilename)(filename) };
+        }
+        catch {
+            return infoOf(file);
+        }
+    }
+    async requireExposed(...noteIds) {
+        const [{ folders }, ...rows] = await Promise.all([
+            this.api.listFolders(),
+            ...noteIds.map((id) => this.api.getNote(id)),
+        ]);
+        const exposure = (0, exposure_js_1.computeExposure)(folders);
+        for (const row of rows) {
+            if (!exposure.allows(row.folderId)) {
+                throw new Error(`Note ${row.id} is in a folder that is not exposed to MCP. Turn on "Expose to MCP" in that folder's settings in the Virlow app to access it here.`);
+            }
+        }
+    }
+    requireSession() {
+        const key = this.vault.session.key;
+        this.vault.touch();
+        return key;
+    }
+}
+exports.AttachmentsService = AttachmentsService;
+function infoOf(file) {
+    return {
+        id: file.id,
+        noteId: file.noteId,
+        filename: (0, attachment_format_js_1.sanitizeFilename)(file.originalName ?? 'attachment'),
+        mimeType: file.mimeType,
+        size: file.size,
+        uploadedAt: file.uploadedAt,
+        deletedAt: file.deletedAt ?? null,
+    };
+}

package/dist/cjs/index.d.ts

@@ -1,8 +1,10 @@
 export { ApiError, VirlowApi } from './api.js';
-export type { ApiFolder, ApiNote, AuthTokens, LoginResult, NoteWrite, RefreshBody } from './api.js';
+export type { ApiFile, ApiFileWithData, ApiFolder, ApiNote, FileUpload, AuthTokens, LoginResult, NoteWrite, RefreshBody } from './api.js';
 export { LockedError, Vault } from './vault.js';
 export type { UnlockedSession } from './vault.js';
 export { NotesService, SEARCH_SCAN_CAP } from './notes.js';
+export { AttachmentsService } from './attachments.js';
+export type { AttachmentInfo } from './attachments.js';
 export { MemoryStore, SYNC_PAGE_LIMIT } from './memories.js';
 export type { CachedMemory, SimilarMemory, SyncResult } from './memories.js';
 export { MEMORY_NOTE_TYPE, mergeMeta, parseMemoryNote, serializeMemoryBody, toCodeEnvelope, } from './memory-note.js';

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.htmlToText = exports.extractLinkIds = exports.buildTitleMatcher = exports.withTags = exports.updateProp = exports.tagsFromAttrs = exports.sortedProps = exports.reorderProps = exports.removeProp = exports.newPropId = exports.encodeSchema = exports.encodeAttrs = exports.emptySchema = exports.emptyAttrs = exports.defineProp = exports.decodeSchema = exports.decodeAttrs = exports.TAGS_PROP = exports.ATTRS_MAX_BYTES = exports.memoriesAllowed = exports.MEMORIES_DISABLED_MESSAGE = exports.EmbeddingCache = exports.filteredNotice = exports.computeExposure = exports.resolveMemoryTree = exports.ensureNamespace = exports.MEMORIES_ROOT_NAME = exports.toCodeEnvelope = exports.serializeMemoryBody = exports.parseMemoryNote = exports.mergeMeta = exports.MEMORY_NOTE_TYPE = exports.SYNC_PAGE_LIMIT = exports.MemoryStore = exports.SEARCH_SCAN_CAP = exports.NotesService = exports.Vault = exports.LockedError = exports.VirlowApi = exports.ApiError = void 0;
+exports.htmlToText = exports.extractLinkIds = exports.buildTitleMatcher = exports.withTags = exports.updateProp = exports.tagsFromAttrs = exports.sortedProps = exports.reorderProps = exports.removeProp = exports.newPropId = exports.encodeSchema = exports.encodeAttrs = exports.emptySchema = exports.emptyAttrs = exports.defineProp = exports.decodeSchema = exports.decodeAttrs = exports.TAGS_PROP = exports.ATTRS_MAX_BYTES = exports.memoriesAllowed = exports.MEMORIES_DISABLED_MESSAGE = exports.EmbeddingCache = exports.filteredNotice = exports.computeExposure = exports.resolveMemoryTree = exports.ensureNamespace = exports.MEMORIES_ROOT_NAME = exports.toCodeEnvelope = exports.serializeMemoryBody = exports.parseMemoryNote = exports.mergeMeta = exports.MEMORY_NOTE_TYPE = exports.SYNC_PAGE_LIMIT = exports.MemoryStore = exports.AttachmentsService = exports.SEARCH_SCAN_CAP = exports.NotesService = exports.Vault = exports.LockedError = exports.VirlowApi = exports.ApiError = void 0;
 var api_js_1 = require("./api.js");
 Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return api_js_1.ApiError; } });
 Object.defineProperty(exports, "VirlowApi", { enumerable: true, get: function () { return api_js_1.VirlowApi; } });
@@ -10,6 +10,8 @@ Object.defineProperty(exports, "Vault", { enumerable: true, get: function () { r
 var notes_js_1 = require("./notes.js");
 Object.defineProperty(exports, "NotesService", { enumerable: true, get: function () { return notes_js_1.NotesService; } });
 Object.defineProperty(exports, "SEARCH_SCAN_CAP", { enumerable: true, get: function () { return notes_js_1.SEARCH_SCAN_CAP; } });
+var attachments_js_1 = require("./attachments.js");
+Object.defineProperty(exports, "AttachmentsService", { enumerable: true, get: function () { return attachments_js_1.AttachmentsService; } });
 var memories_js_1 = require("./memories.js");
 Object.defineProperty(exports, "MemoryStore", { enumerable: true, get: function () { return memories_js_1.MemoryStore; } });
 Object.defineProperty(exports, "SYNC_PAGE_LIMIT", { enumerable: true, get: function () { return memories_js_1.SYNC_PAGE_LIMIT; } });

package/dist/cjs/local-paths.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one gate for every disk path a model hands the attachment tools
+ * (`path` on add_attachment, `save_to` on read_attachment).
+ *
+ * "Absolute" is not enough on Windows. path.win32.isAbsolute accepts
+ * \\server\share\x, //server/share/x, \\?\UNC\..., \\.\pipe\x and a bare /x.
+ * Touching a UNC path makes Windows try SMB to that host, which hands it the
+ * user's NTLM hash; writing to one sends decrypted vault files off the
+ * machine; device paths reach pipes and drivers rather than files. A
+ * prompt-injected model can ask for any of these, so only a plain drive path
+ * is accepted.
+ */
+export type PathPlatform = 'win32' | 'posix';
+/**
+ * Returns the path to use, or throws a message the model can act on.
+ *
+ * Windows: only `X:\...` (either slash). `\\?\X:\...` is accepted and
+ * normalised to `X:\...`; every other `\\` or `//` form (UNC, `\\?\UNC\`,
+ * `\\.\` devices), a rooted path with no drive, a drive-relative path,
+ * alternate data streams and reserved device names are refused.
+ * POSIX: a leading `/`, but not `//`, which POSIX leaves
+ * implementation-defined and some systems treat as a network root.
+ *
+ * `platform` defaults to this process's; tests pass it to cover both.
+ */
+export declare function requireLocalAbsolutePath(p: string, label: string, platform?: PathPlatform): string;

package/dist/cjs/local-paths.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * The one gate for every disk path a model hands the attachment tools
+ * (`path` on add_attachment, `save_to` on read_attachment).
+ *
+ * "Absolute" is not enough on Windows. path.win32.isAbsolute accepts
+ * \\server\share\x, //server/share/x, \\?\UNC\..., \\.\pipe\x and a bare /x.
+ * Touching a UNC path makes Windows try SMB to that host, which hands it the
+ * user's NTLM hash; writing to one sends decrypted vault files off the
+ * machine; device paths reach pipes and drivers rather than files. A
+ * prompt-injected model can ask for any of these, so only a plain drive path
+ * is accepted.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireLocalAbsolutePath = requireLocalAbsolutePath;
+const currentPlatform = () => (process.platform === 'win32' ? 'win32' : 'posix');
+/** Names Windows maps to devices in any folder, with or without an extension. */
+const WIN_RESERVED = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)(\..*)?$/i;
+function isLocalWindowsPath(p) {
+    if (!/^[A-Za-z]:[\\/]/.test(p))
+        return false;
+    // A colon past the drive is an alternate data stream (file.txt:stream).
+    if (p.indexOf(':', 2) !== -1)
+        return false;
+    return !p
+        .slice(3)
+        .split(/[\\/]/)
+        .some((segment) => WIN_RESERVED.test(segment.replace(/[ .]+$/, '')));
+}
+/**
+ * Returns the path to use, or throws a message the model can act on.
+ *
+ * Windows: only `X:\...` (either slash). `\\?\X:\...` is accepted and
+ * normalised to `X:\...`; every other `\\` or `//` form (UNC, `\\?\UNC\`,
+ * `\\.\` devices), a rooted path with no drive, a drive-relative path,
+ * alternate data streams and reserved device names are refused.
+ * POSIX: a leading `/`, but not `//`, which POSIX leaves
+ * implementation-defined and some systems treat as a network root.
+ *
+ * `platform` defaults to this process's; tests pass it to cover both.
+ */
+function requireLocalAbsolutePath(p, label, platform = currentPlatform()) {
+    if (platform === 'win32') {
+        const candidate = /^\\\\\?\\[A-Za-z]:\\/.test(p) ? p.slice(4) : p;
+        if (isLocalWindowsPath(candidate))
+            return candidate;
+        throw new Error(`${label} must be a full local path like C:\\Users\\you\\file.pdf, got "${p}". ` +
+            'Network and device paths are not allowed.');
+    }
+    if (p.startsWith('/') && !p.startsWith('//'))
+        return p;
+    throw new Error(`${label} must be an absolute path like /home/you/file.pdf, got "${p}".`);
+}