@batalabs/virlow-mcp-core 3.119.4 → 3.121.0

package/dist/cjs/attachments.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AttachmentsService = void 0;
+exports.AttachmentsService = exports.SMALL_FILE_BYTES = void 0;
 exports.largeFileMessage = largeFileMessage;
 const virlow_crypto_1 = require("@batalabs/virlow-crypto");
 const exposure_js_1 = require("./exposure.js");
@@ -9,6 +9,11 @@ const api_js_1 = require("./api.js");
 const vault_js_1 = require("./vault.js");
 const keyring_js_2 = require("./keyring.js");
 const attachment_format_js_1 = require("./attachment-format.js");
+const large_files_js_1 = require("./large-files.js");
+/** Above this a file goes as a large upload, in chunks. The web app's limit too. */
+exports.SMALL_FILE_BYTES = 10 * 1024 * 1024;
+/** How much of a small file's plaintext one `readRange` write carries. */
+const SMALL_FILE_WRITE_BYTES = 1024 * 1024;
 /** 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.';
@@ -51,6 +56,7 @@ function inferredMimeType(filename, fromText) {
 class AttachmentsService {
     api;
     vault;
+    options;
     keyring;
     /** Bumped when the vault locks. add() and rename() capture it before their
      * first await and check it right before the upload or patch, so nothing is
@@ -58,9 +64,14 @@ class AttachmentsService {
     epoch = 0;
     constructor(api, vault, 
     /** Shared with NotesService (its `keyring`) so keys open once per unlock. */
-    keyring) {
+    keyring, 
+    /** For the account holder's own surfaces (the desktop drive), where "Expose
+     * to MCP" does not apply: that switch is consent for AI tools, and no AI
+     * tool is the caller. Never set this for anything serving tools. */
+    options = {}) {
         this.api = api;
         this.vault = vault;
+        this.options = options;
         this.keyring = keyring ?? new keyring_js_2.WorkspaceKeyring(api, vault);
         this.vault.onLock = () => {
             this.epoch++;
@@ -127,6 +138,93 @@ class AttachmentsService {
             throw decryptFailure(err);
         }
     }
+    /**
+     * A file's plaintext for bytes [start, end), written as it arrives, so a large
+     * file never sits in memory whole. May write more than was asked, from an
+     * earlier offset and on to the end of what it had to decrypt anyway: a small
+     * file is one ciphertext, a large one opens by the chunk. Offsets given to
+     * `write` are always chunk or 1 MiB boundaries.
+     */
+    async readRange(id, input) {
+        const key = this.requireSession();
+        const startEpoch = this.epoch;
+        const meta = await this.api.getFileMeta(id);
+        let place = await this.requirePlace(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)
+            place = await this.requirePlace(file.noteId);
+        const fileKey = await this.readKey(key, file, place);
+        this.requireSameSession(startEpoch);
+        const write = async (bytes, offset) => {
+            this.requireSameSession(startEpoch);
+            await input.write(bytes, offset);
+        };
+        try {
+            if (file.chunkSize) {
+                if (!file.download)
+                    throw new Error('The file has no stored content to read');
+                await (0, large_files_js_1.downloadLargeFile)(this.api.largeFileTransport(), {
+                    size: file.size,
+                    chunkSize: file.chunkSize,
+                    header: file.encryptedData,
+                    url: file.download.url,
+                    masterKey: fileKey,
+                    refreshUrl: async () => {
+                        const fresh = await this.api.getFile(id);
+                        if (!fresh.download)
+                            throw new Error('The file has no stored content to read');
+                        return fresh.download.url;
+                    },
+                    range: { start: input.start, end: input.end },
+                    write,
+                    ...(input.signal ? { signal: input.signal } : {}),
+                });
+                return;
+            }
+            const { bytes } = await (0, virlow_crypto_1.decryptAttachment)(fileKey, file);
+            const from = Math.floor(input.start / SMALL_FILE_WRITE_BYTES) * SMALL_FILE_WRITE_BYTES;
+            for (let at = from; at < bytes.byteLength; at += SMALL_FILE_WRITE_BYTES) {
+                if (input.signal?.aborted)
+                    throw new DOMException('Download cancelled', 'AbortError');
+                await write(bytes.subarray(at, Math.min(at + SMALL_FILE_WRITE_BYTES, bytes.byteLength)), at);
+            }
+        }
+        catch (err) {
+            throw err?.name === 'AbortError' || err instanceof vault_js_1.LockedError ? err : decryptFailure(err);
+        }
+    }
+    /** A file of any size from a Blob: one request when small, chunks when not. */
+    async addBlob(input) {
+        const { file } = input;
+        if (file.size <= exports.SMALL_FILE_BYTES) {
+            return this.add({
+                noteId: input.noteId,
+                filename: input.filename,
+                bytes: new Uint8Array(await file.arrayBuffer()),
+                ...(input.mimeType ? { mimeType: input.mimeType } : {}),
+            });
+        }
+        const key = this.requireSession();
+        const startEpoch = this.epoch;
+        const place = await this.requirePlace(input.noteId);
+        const filename = (0, attachment_format_js_1.sanitizeFilename)(input.filename);
+        const choice = await this.writeKey(key, place, place.row.keyVersion ?? null);
+        const name = await (0, virlow_crypto_1.encryptAttachmentName)(choice.key, filename);
+        this.requireSameSession(startEpoch);
+        const row = await (0, large_files_js_1.uploadLargeFile)(this.api.largeFileTransport(), {
+            noteId: input.noteId,
+            file,
+            mimeType: input.mimeType ?? inferredMimeType(filename, false),
+            masterKey: choice.key,
+            keyVersion: choice.keyVersion,
+            encryptedTitle: name.encryptedTitle,
+            iv: name.iv,
+            salt: (0, virlow_crypto_1.bytesToBase64)(crypto.getRandomValues(new Uint8Array(32))),
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+        return { ...infoOf(row), filename };
+    }
     async rename(id, newFilename) {
         const key = this.requireSession();
         const startEpoch = this.epoch;
@@ -215,7 +313,7 @@ class AttachmentsService {
         });
         const workspaces = new Map(folders.map((f) => [f.id, f.workspaceId ?? null]));
         return rows.map((row) => {
-            if (!exposure.allows(row.folderId)) {
+            if (this.options.allFolders !== true && !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.`);
             }
             const listed = row.folderId === null ? null : (workspaces.get(row.folderId) ?? null);

package/dist/cjs/index.d.ts

@@ -3,7 +3,7 @@ export type { ApiFile, ApiFileWithData, ApiFolder, ApiIdentity, ApiNote, ApiWork
 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 { AttachmentsService, SMALL_FILE_BYTES } from './attachments.js';
 export { KeyChangedError, NoWorkspaceKeyError, WorkspaceKeyring, memorySignerMemory } from './keyring.js';
 export type { KeyChoice, SignerMemory } from './keyring.js';
 export { fileSignerMemory } from './signer-file.js';

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.serializeRegistry = exports.registryKeyFor = exports.parseRegistry = exports.mergeRegistries = exports.emptyRegistry = exports.describedEntities = exports.describeInRegistry = exports.canWriteRegistry = exports.ENTITY_REGISTRY_VERSION = exports.ENTITY_REGISTRY_TITLE = exports.ENTITY_REGISTRY_NOTE_TYPE = exports.toCodeEnvelope = exports.serializeMemoryBody = exports.parseMemoryNote = exports.mergeMeta = exports.MEMORY_NOTE_TYPE = exports.SYNC_PAGE_LIMIT = exports.MemoryStore = exports.fileSignerMemory = exports.memorySignerMemory = exports.WorkspaceKeyring = exports.NoWorkspaceKeyError = exports.KeyChangedError = exports.AttachmentsService = exports.SEARCH_SCAN_CAP = exports.NotesService = exports.Vault = exports.LockedError = exports.VirlowApi = exports.ApiError = void 0;
-exports.TodoService = exports.htmlToText = exports.extractLinkIds = exports.buildTitleMatcher = exports.withTags = exports.updateProp = exports.tagsFromAttrs = exports.sortedProps = void 0;
+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.serializeRegistry = exports.registryKeyFor = exports.parseRegistry = exports.mergeRegistries = exports.emptyRegistry = exports.describedEntities = exports.describeInRegistry = exports.canWriteRegistry = exports.ENTITY_REGISTRY_VERSION = exports.ENTITY_REGISTRY_TITLE = exports.ENTITY_REGISTRY_NOTE_TYPE = exports.toCodeEnvelope = exports.serializeMemoryBody = exports.parseMemoryNote = exports.mergeMeta = exports.MEMORY_NOTE_TYPE = exports.SYNC_PAGE_LIMIT = exports.MemoryStore = exports.fileSignerMemory = exports.memorySignerMemory = exports.WorkspaceKeyring = exports.NoWorkspaceKeyError = exports.KeyChangedError = exports.SMALL_FILE_BYTES = exports.AttachmentsService = exports.SEARCH_SCAN_CAP = exports.NotesService = exports.Vault = exports.LockedError = exports.VirlowApi = exports.ApiError = void 0;
+exports.TodoService = exports.htmlToText = exports.extractLinkIds = exports.buildTitleMatcher = exports.withTags = exports.updateProp = exports.tagsFromAttrs = exports.sortedProps = exports.reorderProps = 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; } });
@@ -13,6 +13,7 @@ Object.defineProperty(exports, "NotesService", { enumerable: true, get: function
 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; } });
+Object.defineProperty(exports, "SMALL_FILE_BYTES", { enumerable: true, get: function () { return attachments_js_1.SMALL_FILE_BYTES; } });
 var keyring_js_1 = require("./keyring.js");
 Object.defineProperty(exports, "KeyChangedError", { enumerable: true, get: function () { return keyring_js_1.KeyChangedError; } });
 Object.defineProperty(exports, "NoWorkspaceKeyError", { enumerable: true, get: function () { return keyring_js_1.NoWorkspaceKeyError; } });

package/dist/cjs/large-files.d.ts

@@ -0,0 +1,72 @@
+export interface Transport {
+    /** A JSON call to the API with the session's auth. `path` starts with "/". */
+    api: <T>(path: string, init?: {
+        method?: string;
+        body?: unknown;
+    }) => Promise<T>;
+    /** PUT bytes to a signed URL, reporting bytes sent. Resolves with the HTTP status. */
+    put: (url: string, body: Uint8Array, onSent: (sent: number) => void, signal?: AbortSignal) => Promise<number>;
+    /** GET a byte range [start, end) of a signed URL. */
+    getRange: (url: string, start: number, end: number, signal?: AbortSignal) => Promise<Response>;
+    /** Wait before a retry. Replaced in tests. */
+    wait?: (ms: number) => Promise<void>;
+}
+/** The API's answer was a refusal it worded for a person. */
+export interface ApiRefusalBody {
+    error?: string;
+    code?: string;
+    feature?: string;
+    missing?: number[];
+}
+export declare class ApiRefusal extends Error {
+    readonly status: number;
+    readonly body: ApiRefusalBody;
+    constructor(status: number, body: ApiRefusalBody);
+}
+export interface LargeUploadInput {
+    noteId: string;
+    file: Blob;
+    mimeType: string;
+    /** The key that wraps the file's own key: the account key, or a shared workspace's. */
+    masterKey: CryptoKey;
+    /** The workspace key version `masterKey` is, in a shared workspace. */
+    keyVersion?: number | null;
+    encryptedTitle: string;
+    iv: string;
+    salt: string;
+    onProgress?: (sentBytes: number) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Sends `file` as a large upload and returns the attachment the API recorded.
+ * If anything fails, the upload is abandoned on the server so the space it
+ * reserved is released straight away rather than a day later.
+ */
+export declare function uploadLargeFile<Row>(transport: Transport, input: LargeUploadInput): Promise<Row>;
+export interface LargeDownloadInput {
+    /** The row from GET /files/:id. */
+    size: number;
+    chunkSize: number;
+    header: string;
+    url: string;
+    masterKey: CryptoKey;
+    /** Asked for a new signed URL when the one in hand stops working. */
+    refreshUrl: () => Promise<string>;
+    /** Only the chunks covering these plaintext bytes [start, end); the whole
+     *  file when absent. A reader asked for one part of a file pays for that part. */
+    range?: {
+        start: number;
+        end: number;
+    };
+    /** Called with each chunk's plaintext and where it starts, in file order. */
+    write: (chunk: Uint8Array, offset: number) => Promise<void> | void;
+    onProgress?: (receivedBytes: number) => void;
+    signal?: AbortSignal;
+}
+/**
+ * Reads a large file back: fetches the sealed chunks by range, a few at a
+ * time, opens each and hands them to `write` in order. A chunk that is not
+ * the one stored at that place in that file fails its tag and the download
+ * with it, so what reaches `write` is the file or nothing.
+ */
+export declare function downloadLargeFile(transport: Transport, input: LargeDownloadInput): Promise<void>;

package/dist/cjs/large-files.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiRefusal = void 0;
+exports.uploadLargeFile = uploadLargeFile;
+exports.downloadLargeFile = downloadLargeFile;
+const virlow_crypto_1 = require("@batalabs/virlow-crypto");
+/**
+ * Files too large to send as one request. The file is cut into chunks, each
+ * encrypted here under a key made for this file alone, and each sent straight
+ * to object storage at a URL the API signs. The API never carries the bytes,
+ * and neither end ever holds the whole file in memory.
+ *
+ * This module is the transfer only. Who may upload what, and which format a
+ * file takes, is fileService's decision.
+ */
+/** Chunks in flight at once. Each holds a chunk and its ciphertext in memory. */
+const CONCURRENCY = 3;
+/** Tries per chunk before the transfer fails. */
+const ATTEMPTS = 4;
+/** Part URLs asked for at a time; the API signs at most 100. */
+const URL_BATCH = 50;
+class ApiRefusal extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(body.error ?? `Request failed: ${status}`);
+        this.name = 'ApiRefusal';
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.ApiRefusal = ApiRefusal;
+const defaultWait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function aborted(signal) {
+    return signal?.aborted === true;
+}
+/** Runs `job` over `items`, `limit` at a time, stopping at the first failure. */
+async function pool(items, limit, job) {
+    let next = 0;
+    let failure;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && next < items.length) {
+            const item = items[next++];
+            try {
+                await job(item);
+            }
+            catch (error) {
+                if (!failed) {
+                    failed = true;
+                    failure = error;
+                }
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    if (failed)
+        throw failure;
+}
+/**
+ * Sends `file` as a large upload and returns the attachment the API recorded.
+ * If anything fails, the upload is abandoned on the server so the space it
+ * reserved is released straight away rather than a day later.
+ */
+async function uploadLargeFile(transport, input) {
+    const { file, signal } = input;
+    const wait = transport.wait ?? defaultWait;
+    const { header, fileKey } = await (0, virlow_crypto_1.createFileKey)(input.masterKey);
+    const upload = await transport.api(`/notes/${input.noteId}/files/uploads`, {
+        method: 'POST',
+        body: {
+            mimeType: input.mimeType,
+            size: file.size,
+            encryptedData: header,
+            encryptedTitle: input.encryptedTitle,
+            iv: input.iv,
+            salt: input.salt,
+            ...(input.keyVersion !== null && input.keyVersion !== undefined && { keyVersion: input.keyVersion }),
+        },
+    });
+    try {
+        const sentByPart = new Map();
+        const report = (partNumber, sent) => {
+            sentByPart.set(partNumber, sent);
+            if (!input.onProgress)
+                return;
+            let total = 0;
+            for (const value of sentByPart.values())
+                total += value;
+            input.onProgress(Math.min(total, file.size));
+        };
+        // Signed URLs, fetched a batch ahead of the parts that need them. A URL
+        // that has expired by the time its part is sent is signed again.
+        const urls = new Map();
+        let signing = Promise.resolve();
+        const urlFor = (partNumber, pending, fresh = false) => {
+            const ask = signing.then(async () => {
+                if (!fresh && urls.has(partNumber))
+                    return;
+                // This part and whichever others still need one, so the batches do
+                // not depend on which worker happens to ask first.
+                const wanted = fresh
+                    ? [partNumber]
+                    : [partNumber, ...pending.filter((n) => n !== partNumber && !urls.has(n))].slice(0, URL_BATCH);
+                const signed = await transport.api(`/files/uploads/${upload.id}/parts`, { method: 'POST', body: { partNumbers: wanted } });
+                for (const entry of signed.urls)
+                    urls.set(entry.partNumber, entry.url);
+            });
+            // One signing call at a time, and a failed one does not poison the next.
+            signing = ask.catch(() => { });
+            return ask.then(() => {
+                const url = urls.get(partNumber);
+                if (!url)
+                    throw new Error(`No upload URL for part ${partNumber}`);
+                return url;
+            });
+        };
+        const sendPart = async (partNumber, pending) => {
+            const index = partNumber - 1;
+            const plain = new Uint8Array(await file.slice(index * upload.chunkSize, (index + 1) * upload.chunkSize).arrayBuffer());
+            const sealed = await (0, virlow_crypto_1.encryptFileChunk)(fileKey, index, partNumber === upload.partCount, plain);
+            for (let attempt = 1;; attempt++) {
+                if (aborted(signal))
+                    throw new DOMException('Upload cancelled', 'AbortError');
+                let status = 0;
+                try {
+                    const url = await urlFor(partNumber, pending, attempt > 1);
+                    status = await transport.put(url, sealed, (sent) => report(partNumber, Math.min(sent, plain.byteLength)), signal);
+                }
+                catch (error) {
+                    if (aborted(signal) || attempt >= ATTEMPTS)
+                        throw error;
+                }
+                if (status >= 200 && status < 300) {
+                    report(partNumber, plain.byteLength);
+                    return;
+                }
+                if (attempt >= ATTEMPTS)
+                    throw new Error(`Uploading part ${partNumber} failed (${status})`);
+                report(partNumber, 0);
+                await wait(500 * 2 ** (attempt - 1));
+            }
+        };
+        const all = Array.from({ length: upload.partCount }, (_, i) => i + 1);
+        await pool(all, CONCURRENCY, (partNumber) => sendPart(partNumber, all));
+        // The API checks what the store holds. If it says parts are missing (a
+        // PUT that reported success and was lost), send those and ask once more.
+        for (let round = 1;; round++) {
+            try {
+                return await transport.api(`/files/uploads/${upload.id}/complete`, { method: 'POST' });
+            }
+            catch (error) {
+                const missing = error instanceof ApiRefusal && error.body.code === 'UPLOAD_INCOMPLETE'
+                    ? (error.body.missing ?? [])
+                    : [];
+                if (missing.length === 0 || round >= 2)
+                    throw error;
+                await pool(missing, CONCURRENCY, (partNumber) => sendPart(partNumber, missing));
+            }
+        }
+    }
+    catch (error) {
+        await transport.api(`/files/uploads/${upload.id}`, { method: 'DELETE' }).catch(() => { });
+        throw error;
+    }
+}
+/**
+ * Reads a large file back: fetches the sealed chunks by range, a few at a
+ * time, opens each and hands them to `write` in order. A chunk that is not
+ * the one stored at that place in that file fails its tag and the download
+ * with it, so what reaches `write` is the file or nothing.
+ */
+async function downloadLargeFile(transport, input) {
+    const { size, chunkSize, signal } = input;
+    const wait = transport.wait ?? defaultWait;
+    const fileKey = await (0, virlow_crypto_1.openFileKey)(input.masterKey, input.header);
+    const count = (0, virlow_crypto_1.fileChunkCount)(size, chunkSize);
+    let url = input.url;
+    let refreshing = null;
+    const refresh = () => {
+        refreshing ??= input
+            .refreshUrl()
+            .then((fresh) => {
+            url = fresh;
+        })
+            .finally(() => {
+            refreshing = null;
+        });
+        return refreshing;
+    };
+    const fetchChunk = async (index) => {
+        const { start, end } = (0, virlow_crypto_1.sealedChunkRange)(size, chunkSize, index);
+        for (let attempt = 1;; attempt++) {
+            if (aborted(signal))
+                throw new DOMException('Download cancelled', 'AbortError');
+            try {
+                const response = await transport.getRange(url, start, end, signal);
+                if (response.ok) {
+                    const sealed = new Uint8Array(await response.arrayBuffer());
+                    if (sealed.byteLength !== end - start)
+                        throw new Error('The stored file is incomplete');
+                    return await (0, virlow_crypto_1.decryptFileChunk)(fileKey, index, index === count - 1, sealed);
+                }
+                if (attempt >= ATTEMPTS)
+                    throw new Error(`Download failed (${response.status})`);
+                // A signed URL past its hour answers 403.
+                if (response.status === 403)
+                    await refresh();
+            }
+            catch (error) {
+                // A chunk that fails its tag will fail it every time.
+                if (aborted(signal) || attempt >= ATTEMPTS || error?.name === 'OperationError') {
+                    throw error;
+                }
+            }
+            await wait(500 * 2 ** (attempt - 1));
+        }
+    };
+    // A window of chunks is fetched together and written in order, so memory
+    // holds a few chunks however large the file is.
+    const first = input.range ? Math.floor(input.range.start / chunkSize) : 0;
+    const stop = input.range ? Math.min(count, Math.ceil(input.range.end / chunkSize)) : count;
+    let received = 0;
+    for (let from = first; from < stop; from += CONCURRENCY) {
+        const window = Array.from({ length: Math.min(CONCURRENCY, stop - from) }, (_, i) => from + i);
+        const chunks = await Promise.all(window.map(fetchChunk));
+        for (const [i, chunk] of chunks.entries()) {
+            await input.write(chunk, (from + i) * chunkSize);
+            received += chunk.byteLength;
+            input.onProgress?.(received);
+        }
+    }
+    if (!input.range && received !== size)
+        throw new Error('The stored file is incomplete');
+}

package/dist/cjs/notes.d.ts

@@ -20,6 +20,8 @@ export interface AppliedProp {
 export declare class NotesService {
     private readonly api;
     private readonly vault;
+    /** See AttachmentsService: for the account holder's own surfaces only. */
+    private readonly options;
     /** Per-unlock cache of decrypted (title, content) keyed by `id:updatedAt`
      * so re-reading/re-scanning the same note twice in one unlock doesn't
      * re-run AES-GCM decryption. Cleared whenever the vault locks. */
@@ -65,7 +67,11 @@ export declare class NotesService {
     /** Opens shared workspaces' keys for this unlock. Public so the attachment
      * service built next to this one shares it rather than opening them twice. */
     readonly keyring: WorkspaceKeyring;
-    constructor(api: VirlowApi, vault: Vault, keyring?: WorkspaceKeyring);
+    constructor(api: VirlowApi, vault: Vault, keyring?: WorkspaceKeyring, 
+    /** See AttachmentsService: for the account holder's own surfaces only. */
+    options?: {
+        allFolders?: boolean;
+    });
     private handleLock;
     /** Drops the paged row list after anything that could change which rows
      * exist, where they live, or what they are called. Called after the write
@@ -257,6 +263,33 @@ export declare class NotesService {
         }>;
         withheld: number;
     }>;
+    /**
+     * Every folder and every storage item (a note of type `file`), decrypted, for
+     * a surface that shows the account's own tree (the desktop drive). Refused
+     * unless this service was built with `allFolders`, so no tool path can reach it.
+     *
+     * Only storage items: files attached to an ordinary note belong to that note
+     * and stay out of the drive. An empty storage item is listed, so files can be
+     * dropped into it. The memories tree is left out: the MCP server makes it for
+     * AI tools and it holds no files. `attachmentStamp` changes when a note's attachments do, so
+     * a caller lists a note's files only when it has to. A note whose key does
+     * not open here is left out and counted, never opened with the account key.
+     */
+    listDriveCatalog(): Promise<{
+        folders: Array<{
+            id: string;
+            name: string;
+            parentId: string | null;
+        }>;
+        notes: Array<{
+            id: string;
+            title: string;
+            folderId: string | null;
+            updatedAt: string;
+            attachmentStamp: string;
+        }>;
+        withheld: number;
+    }>;
     /** Folder exposure for this request. Not cached across calls: the user can
      * flip the switch in the app at any moment and the next tool call must
      * respect it. */

package/dist/cjs/notes.js

@@ -181,6 +181,7 @@ function resolveValues(defs, values, createOption) {
 class NotesService {
     api;
     vault;
+    options;
     /** Per-unlock cache of decrypted (title, content) keyed by `id:updatedAt`
      * so re-reading/re-scanning the same note twice in one unlock doesn't
      * re-run AES-GCM decryption. Cleared whenever the vault locks. */
@@ -226,9 +227,12 @@ class NotesService {
     /** Opens shared workspaces' keys for this unlock. Public so the attachment
      * service built next to this one shares it rather than opening them twice. */
     keyring;
-    constructor(api, vault, keyring) {
+    constructor(api, vault, keyring, 
+    /** See AttachmentsService: for the account holder's own surfaces only. */
+    options = {}) {
         this.api = api;
         this.vault = vault;
+        this.options = options;
         this.vault.onLock = () => this.handleLock();
         this.keyring = keyring ?? new keyring_js_1.WorkspaceKeyring(api, vault);
     }
@@ -781,6 +785,70 @@ class NotesService {
             withheld: folders.length - visible.length,
         };
     }
+    /**
+     * Every folder and every storage item (a note of type `file`), decrypted, for
+     * a surface that shows the account's own tree (the desktop drive). Refused
+     * unless this service was built with `allFolders`, so no tool path can reach it.
+     *
+     * Only storage items: files attached to an ordinary note belong to that note
+     * and stay out of the drive. An empty storage item is listed, so files can be
+     * dropped into it. The memories tree is left out: the MCP server makes it for
+     * AI tools and it holds no files. `attachmentStamp` changes when a note's attachments do, so
+     * a caller lists a note's files only when it has to. A note whose key does
+     * not open here is left out and counted, never opened with the account key.
+     */
+    async listDriveCatalog() {
+        if (this.options.allFolders !== true)
+            throw new Error('The drive catalog is not available here.');
+        const key = this.requireSession();
+        const { folders: rows } = await this.api.listFolders();
+        const exposure = await this.exposureOf(rows);
+        const byId = new Map(rows.map((f) => [f.id, f]));
+        const inMemories = (folder) => {
+            const seen = new Set();
+            let current = folder;
+            while (current && !seen.has(current.id)) {
+                if (current.kind === 'memories')
+                    return true;
+                seen.add(current.id);
+                current = current.parentId === null ? undefined : byId.get(current.parentId);
+            }
+            return false;
+        };
+        const shown = rows.filter((f) => !inMemories(f));
+        const shownIds = new Set(shown.map((f) => f.id));
+        const folders = await Promise.all(shown.map(async (f) => ({ id: f.id, name: await this.folderName(key, f), parentId: f.parentId })));
+        const notes = [];
+        let withheld = 0;
+        for (let page = 1, pages = 1; page <= pages; page += 1) {
+            const result = await this.api.listNotes({ page, limit: 50, deleted: false, archived: false });
+            pages = result.pagination.pages;
+            const storage = result.notes.filter((row) => row.type === 'file' &&
+                row.hidden !== true &&
+                !isSystemNote(row) &&
+                (row.folderId === null || shownIds.has(row.folderId)));
+            const decrypted = await Promise.all(storage.map(async (row) => {
+                const rowKey = await this.keyForRowOrNull(key, row, exposure);
+                if (rowKey === null)
+                    return null;
+                const title = await this.decryptRow(rowKey, row).then((fields) => fields.title, () => null);
+                if (title === null)
+                    return null;
+                const stamp = [...(row.attachments ?? [])]
+                    .map((a) => `${a.id}:${a.iv}:${a.encryptedTitle}`)
+                    .sort()
+                    .join('|');
+                return { id: row.id, title, folderId: row.folderId, updatedAt: row.updatedAt, attachmentStamp: stamp };
+            }));
+            for (const entry of decrypted) {
+                if (entry === null)
+                    withheld += 1;
+                else
+                    notes.push(entry);
+            }
+        }
+        return { folders, notes, withheld };
+    }
     /** Folder exposure for this request. Not cached across calls: the user can
      * flip the switch in the app at any moment and the next tool call must
      * respect it. */
@@ -812,8 +880,10 @@ class NotesService {
             `/${f.userId ?? ''}/${f.workspaceId ?? ''}/${f.workspaceId ? (workspaceOwners.get(f.workspaceId) ?? '') : ''}`)
             .join('|');
         const workspaces = new Map(folders.map((f) => [f.id, f.workspaceId ?? null]));
+        const computed = (0, exposure_js_1.computeExposure)(folders, { viewerId, workspaceOwners });
         return {
-            ...(0, exposure_js_1.computeExposure)(folders, { viewerId, workspaceOwners }),
+            ...computed,
+            ...(this.options.allFolders === true ? { allows: () => true, hiddenFolderCount: 0, allHidden: false } : {}),
             key: `${viewerId}#${key}`,
             workspaceOf: (folderId) => (folderId === null ? null : (workspaces.get(folderId) ?? null)),
             hasFolder: (folderId) => workspaces.has(folderId),

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { ApiFile, ApiFileWithData, ApiFolder, ApiIdentity, ApiNote, ApiWork
 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 { AttachmentsService, SMALL_FILE_BYTES } from './attachments.js';
 export { KeyChangedError, NoWorkspaceKeyError, WorkspaceKeyring, memorySignerMemory } from './keyring.js';
 export type { KeyChoice, SignerMemory } from './keyring.js';
 export { fileSignerMemory } from './signer-file.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EACV,OAAO,EACP,eAAe,EACf,SAAS,EACT,WAAW,EACX,OAAO,EACP,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,UAAU,EACV,WAAW,EACX,SAAS,EACT,WAAW,GACZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC1G,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,EACb,cAAc,EACd,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAChE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EACL,eAAe,EACf,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,UAAU,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EACV,YAAY,EACZ,WAAW,EACX,aAAa,EACb,UAAU,EACV,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC1H,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnF,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjG;;;;;;;;;;GAUG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}