@batalabs/virlow-mcp-core 3.116.0 → 3.117.0

package/dist/cjs/api.d.ts

@@ -48,6 +48,15 @@ export interface ApiNote {
     updatedAt: string;
     /** Encrypted v2 blob of the note's structured attrs (props, links, mentions). */
     encryptedAttrs: string | null;
+    /** Set on a note in a shared workspace: the version of that workspace's
+     * key its ciphertext (title, content, attrs) is under. Null or absent means
+     * the account key. See keyring.ts. */
+    keyVersion?: number | null;
+    /** List and get send the note's folder along; its workspaceId says which
+     * shared workspace (if any) the note is in. Absent from older servers. */
+    folder?: {
+        workspaceId?: string | null;
+    } | null;
 }
 export interface NoteWrite {
     title: string;
@@ -63,6 +72,11 @@ export interface NoteWrite {
     archived?: boolean;
     deleted?: boolean;
     encryptedAttrs?: string | null;
+    /** In a shared workspace: the workspace key version every ciphertext in
+     *  this write is under. The API requires it, equal to the workspace's
+     *  current version, on any write that carries ciphertext there, and
+     *  refuses it on a personal note. Never set for the account key. */
+    keyVersion?: number;
     /** The version the write is based on; the API answers 409 NOTE_CONFLICT
      *  when the note has moved on since. */
     expectedUpdatedAt?: string;
@@ -82,6 +96,58 @@ export interface ApiFolder {
     memoryPaused?: boolean;
     /** Encrypted v2 blob of the folder's property and view definitions. */
     encryptedSchema: string | null;
+    /** The account the row belongs to: in a shared workspace, its owner. */
+    userId?: string | null;
+    /** In a shared workspace this account does not own: whether this member
+     *  opened it to AI tools. Only this, never `mcpEnabled` (one value every
+     *  editor can set), opens such a folder; absent means closed. */
+    mcpEnabledForMember?: boolean;
+    /** The shared workspace this folder belongs to; null or absent = personal. */
+    workspaceId?: string | null;
+    /** In a shared workspace: the name, under the workspace key (`name` is "[ENCRYPTED]"). */
+    encryptedName?: string | null;
+    /** The workspace key version of encryptedName and encryptedSchema; null = the account key. */
+    keyVersion?: number | null;
+}
+/** An account's sharing keys as the API stores them (GET /api/users/me/identity). */
+export interface ApiIdentity {
+    box: string;
+    sign: string;
+    /** "v2:" blob of the private halves, under the account key. */
+    sealedPrivate: string;
+}
+/** One shared workspace this account belongs to (GET /api/workspaces). */
+export interface ApiWorkspaceSummary {
+    id: string;
+    rootFolderId: string;
+    role: 'owner' | 'editor' | 'viewer';
+    ownerId: string;
+    /** The current key version: every new ciphertext in the workspace uses it. */
+    keyVersion: number;
+    state: 'sharing' | 'shared';
+}
+/** One of this account's grants in a workspace, as GET /api/workspaces/:id sends it. */
+export interface ApiWorkspaceGrant {
+    keyVersion: number;
+    sealed: string;
+    signature: string;
+    granterId: string;
+    /** The granter's signing key as the server has it now; null if they have none. */
+    granterSign: string | null;
+}
+/** One person in a workspace, as GET /api/workspaces/:id sends them. */
+export interface ApiWorkspaceMember {
+    userId: string;
+    role: 'owner' | 'editor' | 'viewer';
+    identity: {
+        box: string;
+        sign: string;
+    } | null;
+}
+export interface ApiWorkspaceDetail {
+    workspace: ApiWorkspaceSummary;
+    members: ApiWorkspaceMember[];
+    grants: ApiWorkspaceGrant[];
 }
 /** A reminder on a note, sent to its owner by email or Slack. */
 export interface ApiReminder {
@@ -111,6 +177,8 @@ export interface ApiFile {
     /** Set for a large file, whose content is in object storage in encrypted
      *  chunks rather than in the row. Absent or null for every other file. */
     chunkSize?: number | null;
+    /** The workspace key version the name and content use; null = the account key. */
+    keyVersion?: number | null;
 }
 export interface ApiFileWithData extends ApiFile {
     /** "v2:<iv>:<ciphertext>"; anything else is legacy v1. */
@@ -124,6 +192,8 @@ export interface FileUpload {
     salt: string;
     mimeType: string;
     size: number;
+    /** In a shared workspace: the workspace key version it is encrypted under. */
+    keyVersion?: number;
 }
 export declare class VirlowApi {
     private readonly baseUrl;
@@ -209,7 +279,13 @@ export declare class VirlowApi {
     listFolders(): Promise<{
         folders: ApiFolder[];
     }>;
-    createFolder(name: string, parentId?: string | null, kind?: 'memories'): Promise<ApiFolder>;
+    createFolder(name: string, parentId?: string | null, kind?: 'memories', 
+    /** In a shared workspace: the name under the workspace key, and that key's
+     *  version. `name` is then the "[ENCRYPTED]" placeholder. */
+    sealed?: {
+        encryptedName: string;
+        keyVersion: number;
+    }): Promise<ApiFolder>;
     /** Partial update of a folder. Only `encryptedSchema` is used from here so
      * far, and it is forwarded as an already-encrypted blob: nothing in this
      * client encrypts, and nothing on the server can read it. */
@@ -218,6 +294,11 @@ export declare class VirlowApi {
         parentId?: string | null;
         mcpEnabled?: boolean;
         encryptedSchema?: string | null;
+        /** In a shared workspace: the name re-encrypted with the schema, when
+         *  the folder's ciphertext was under an older key version. */
+        encryptedName?: string;
+        /** In a shared workspace: the key version of the ciphertext sent. */
+        keyVersion?: number;
     }): Promise<ApiFolder>;
     listFiles(noteId: string, opts?: {
         trashed?: boolean;
@@ -231,11 +312,22 @@ export declare class VirlowApi {
         encryptedTitle?: string;
         iv?: string;
         noteId?: string;
+        /** A re-key: the content (or a large file's "v3:" header) under another key. */
+        encryptedData?: string;
+        /** In a shared workspace: the key version of the ciphertext sent. */
+        keyVersion?: number;
     }): 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>;
+    /** This account's sharing identity: public keys and the sealed private
+     *  halves. Null until some device of this account has published one. */
+    getIdentity(): Promise<ApiIdentity | null>;
+    /** The shared workspaces this account belongs to. */
+    listWorkspaces(): Promise<ApiWorkspaceSummary[]>;
+    /** One shared workspace, with this account's grants (every key version it was given). */
+    getWorkspace(id: string): Promise<ApiWorkspaceDetail>;
     /** This person's reminders on one note (a to-do is a note): pending ones
      *  and those from the last week. */
     listReminders(noteId: string): Promise<ApiReminder[]>;

package/dist/cjs/api.js

@@ -207,7 +207,10 @@ class VirlowApi {
         }
         return { folders };
     }
-    createFolder(name, parentId, kind) {
+    createFolder(name, parentId, kind, 
+    /** In a shared workspace: the name under the workspace key, and that key's
+     *  version. `name` is then the "[ENCRYPTED]" placeholder. */
+    sealed) {
         // `kind` is omitted rather than sent as null: the API rejects unknown kinds
         // and a namespace subfolder is an ordinary folder.
         const body = {
@@ -216,6 +219,10 @@ class VirlowApi {
         };
         if (kind !== undefined)
             body.kind = kind;
+        if (sealed !== undefined) {
+            body.encryptedName = sealed.encryptedName;
+            body.keyVersion = sealed.keyVersion;
+        }
         return this.request('POST', '/api/folders', body);
     }
     /** Partial update of a folder. Only `encryptedSchema` is used from here so
@@ -250,6 +257,21 @@ class VirlowApi {
     restoreFile(id) {
         return this.request('POST', `/api/files/${encodeURIComponent(id)}/restore`);
     }
+    /** This account's sharing identity: public keys and the sealed private
+     *  halves. Null until some device of this account has published one. */
+    async getIdentity() {
+        const body = await this.request('GET', '/api/users/me/identity');
+        return body.identity ?? null;
+    }
+    /** The shared workspaces this account belongs to. */
+    async listWorkspaces() {
+        const body = await this.request('GET', '/api/workspaces');
+        return body.workspaces;
+    }
+    /** One shared workspace, with this account's grants (every key version it was given). */
+    getWorkspace(id) {
+        return this.request('GET', `/api/workspaces/${encodeURIComponent(id)}`);
+    }
     /** This person's reminders on one note (a to-do is a note): pending ones
      *  and those from the last week. */
     async listReminders(noteId) {

package/dist/cjs/attachments.d.ts

@@ -1,5 +1,6 @@
 import { type VirlowApi } from './api.js';
-import type { Vault } from './vault.js';
+import { type Vault } from './vault.js';
+import { WorkspaceKeyring } from './keyring.js';
 export interface AttachmentInfo {
     id: string;
     noteId: string;
@@ -13,7 +14,15 @@ export declare function largeFileMessage(size: number): string;
 export declare class AttachmentsService {
     private readonly api;
     private readonly vault;
-    constructor(api: VirlowApi, vault: Vault);
+    private readonly 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
+     * sent encrypted under a key from a session that has since locked. */
+    private epoch;
+    constructor(api: VirlowApi, vault: Vault, 
+    /** Shared with NotesService (its `keyring`) so keys open once per unlock. */
+    keyring?: WorkspaceKeyring);
+    private requireSameSession;
     list(noteId: string, includeTrashed: boolean): Promise<AttachmentInfo[]>;
     add(input: {
         noteId: string;
@@ -34,6 +43,15 @@ export declare class AttachmentsService {
     /** 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 requirePlace;
+    /** Every note must be exposed. Returns where each one is, in order. */
     private requireExposed;
+    /** The key a file is under: its own version (null = the account key) in its note's workspace. */
+    private readKey;
+    /** The key a new file, name or content in this note goes under. Never the
+     * account key in a shared workspace; a key that does not open is refused. */
+    private writeKey;
+    /** A file's content (inline) or file key (large file header) under `toKey`. */
+    private rekeyContent;
     private requireSession;
 }

package/dist/cjs/attachments.js

@@ -4,7 +4,10 @@ exports.AttachmentsService = void 0;
 exports.largeFileMessage = largeFileMessage;
 const virlow_crypto_1 = require("@batalabs/virlow-crypto");
 const exposure_js_1 = require("./exposure.js");
+const keyring_js_1 = require("./keyring.js");
 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");
 /** 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. */
@@ -48,16 +51,32 @@ function inferredMimeType(filename, fromText) {
 class AttachmentsService {
     api;
     vault;
-    constructor(api, vault) {
+    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
+     * sent encrypted under a key from a session that has since locked. */
+    epoch = 0;
+    constructor(api, vault, 
+    /** Shared with NotesService (its `keyring`) so keys open once per unlock. */
+    keyring) {
         this.api = api;
         this.vault = vault;
+        this.keyring = keyring ?? new keyring_js_2.WorkspaceKeyring(api, vault);
+        this.vault.onLock = () => {
+            this.epoch++;
+        };
+    }
+    requireSameSession(startEpoch) {
+        if (this.epoch !== startEpoch) {
+            throw new vault_js_1.LockedError('Vault is locked. Call this server\'s unlock tool and ask the user to finish unlocking their Virlow vault.');
+        }
     }
     async list(noteId, includeTrashed) {
         const key = this.requireSession();
-        await this.requireExposed(noteId);
+        const place = await this.requirePlace(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)));
+        return Promise.all([...live, ...trashed].map((file) => this.describe(key, file, place)));
     }
     async add(input) {
         // A backstop under the tools' own per-source caps, so no caller can encrypt
@@ -68,15 +87,21 @@ class AttachmentsService {
             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 startEpoch = this.epoch;
+        const place = await this.requirePlace(input.noteId);
         const filename = (0, attachment_format_js_1.sanitizeFilename)(input.filename);
-        const encrypted = await (0, virlow_crypto_1.encryptAttachment)(key, filename, input.bytes);
+        // In a shared workspace, under its current key, sent with that version;
+        // never older than the version the note itself is under.
+        const choice = await this.writeKey(key, place, place.row.keyVersion ?? null);
+        const encrypted = await (0, virlow_crypto_1.encryptAttachment)(choice.key, filename, input.bytes);
+        this.requireSameSession(startEpoch);
         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,
+            ...(choice.keyVersion !== null ? { keyVersion: choice.keyVersion } : {}),
         });
         return { ...infoOf(row), filename };
     }
@@ -84,7 +109,7 @@ class AttachmentsService {
         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);
+        let place = await this.requirePlace(meta.noteId);
         // A large file lives in object storage in chunks, far past what a tool
         // result can carry. Say so before fetching anything.
         if (meta.chunkSize)
@@ -92,9 +117,10 @@ class AttachmentsService {
         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);
+            place = await this.requirePlace(file.noteId);
+        const fileKey = await this.readKey(key, file, place);
         try {
-            const { filename, bytes } = await (0, virlow_crypto_1.decryptAttachment)(key, file);
+            const { filename, bytes } = await (0, virlow_crypto_1.decryptAttachment)(fileKey, file);
             return { info: { ...infoOf(file), filename: (0, attachment_format_js_1.sanitizeFilename)(filename) }, bytes };
         }
         catch (err) {
@@ -103,12 +129,30 @@ class AttachmentsService {
     }
     async rename(id, newFilename) {
         const key = this.requireSession();
+        const startEpoch = this.epoch;
         const file = await this.api.getFileMeta(id);
-        await this.requireExposed(file.noteId);
+        const place = await this.requirePlace(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) => {
+        const choice = await this.writeKey(key, place, file.keyVersion ?? null);
+        let patch = await (0, virlow_crypto_1.encryptAttachmentName)(choice.key, filename);
+        if (choice.keyVersion !== null) {
+            patch.keyVersion = choice.keyVersion;
+            // The row has one key version for its name and its content, and the
+            // API sets it from this write. A file still under an older version of
+            // the workspace key has its content (or, for a large file, the file key
+            // in its header) re-encrypted in the same request.
+            if ((file.keyVersion ?? null) !== choice.keyVersion) {
+                // From the account key into a workspace's is the owner's sharing run,
+                // never this (see NotesService.requireOwnedForRekey).
+                if ((file.keyVersion ?? null) === null && choice.ownerId !== this.vault.session.userId) {
+                    throw new Error('This file is still under your own key but the server places it in a shared workspace you do not ' +
+                        'own, so it was not re-encrypted. Open it in the Virlow app.');
+                }
+                patch = { ...patch, encryptedData: await this.rekeyContent(key, id, place, choice.key) };
+            }
+        }
+        this.requireSameSession(startEpoch);
+        const row = await this.api.patchFile(id, patch).catch((err) => {
             throw renameFailure(err);
         });
         return { ...infoOf(row), filename };
@@ -118,8 +162,13 @@ class AttachmentsService {
         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 }));
+        const [from, to] = await this.requireExposed(file.noteId, toNoteId);
+        // A file's key belongs to its workspace; the API refuses a move across.
+        if (from && to && from.workspaceId !== to.workspaceId) {
+            throw new Error('This file cannot be moved in or out of a shared workspace: that changes its encryption. ' +
+                'Download it and attach it again instead.');
+        }
+        return this.describe(key, await this.api.patchFile(id, { noteId: toNoteId }), to);
     }
     async trash(id) {
         this.requireSession();
@@ -130,13 +179,14 @@ class AttachmentsService {
     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));
+        const place = await this.requirePlace(file.noteId);
+        return this.describe(key, await this.api.restoreFile(id), place);
     }
     /** 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) {
+    async describe(accountKey, file, place) {
         try {
+            const key = await this.readKey(accountKey, file, place);
             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) };
@@ -145,16 +195,81 @@ class AttachmentsService {
             return infoOf(file);
         }
     }
+    async requirePlace(noteId) {
+        const [place] = await this.requireExposed(noteId);
+        if (!place)
+            throw new Error(`Note ${noteId} was not found.`);
+        return place;
+    }
+    /** Every note must be exposed. Returns where each one is, in order. */
     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) {
+        // Same rule as NotesService: a folder in a workspace someone else owns is
+        // open only by this member's own switch (exposure.ts, isForeignFolder).
+        const exposure = (0, exposure_js_1.computeExposure)(folders, {
+            viewerId: this.vault.session.userId,
+            workspaceOwners: await this.keyring.workspaceOwners(folders),
+        });
+        const workspaces = new Map(folders.map((f) => [f.id, f.workspaceId ?? null]));
+        return rows.map((row) => {
             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.`);
             }
+            const listed = row.folderId === null ? null : (workspaces.get(row.folderId) ?? null);
+            const sent = row.folder?.workspaceId;
+            // The two must agree, as in NotesService.workspaceOfRow.
+            if (sent !== undefined && row.folderId !== null && workspaces.has(row.folderId) && (sent ?? null) !== listed) {
+                throw new Error(`Note ${row.id}: the server gave two different workspaces for it, so it was not opened. ` +
+                    'Open it in the Virlow app.');
+            }
+            const workspaceId = sent ?? listed;
+            if ((0, exposure_js_1.isSharedNote)(row) && !workspaceId) {
+                throw (0, exposure_js_1.sharedNoteError)(row.id, new keyring_js_1.NoWorkspaceKeyError());
+            }
+            return { row, workspaceId };
+        });
+    }
+    /** The key a file is under: its own version (null = the account key) in its note's workspace. */
+    async readKey(accountKey, file, place) {
+        if (file.keyVersion === null || file.keyVersion === undefined)
+            return accountKey;
+        try {
+            return await this.keyring.forRead(accountKey, file.keyVersion, place?.workspaceId);
+        }
+        catch (err) {
+            if (err instanceof vault_js_1.LockedError)
+                throw err;
+            throw (0, exposure_js_1.sharedNoteError)(file.noteId, err);
+        }
+    }
+    /** The key a new file, name or content in this note goes under. Never the
+     * account key in a shared workspace; a key that does not open is refused. */
+    async writeKey(accountKey, place, atLeast) {
+        try {
+            return await this.keyring.forWrite(accountKey, place?.workspaceId ?? null, { atLeast });
+        }
+        catch (err) {
+            // Only fixed text reaches the caller (see describeKeyFailure).
+            if (err instanceof vault_js_1.LockedError || err instanceof keyring_js_1.WriteRefusedError || !place?.workspaceId)
+                throw err;
+            throw (0, exposure_js_1.sharedNoteError)(place.row.id, err);
+        }
+    }
+    /** A file's content (inline) or file key (large file header) under `toKey`. */
+    async rekeyContent(accountKey, id, place, toKey) {
+        const full = await this.api.getFile(id);
+        const fromKey = await this.readKey(accountKey, full, place);
+        try {
+            if ((0, virlow_crypto_1.isV3Attachment)(full.encryptedData))
+                return await (0, virlow_crypto_1.rewrapFileKey)(fromKey, toKey, full.encryptedData);
+            const { filename, bytes } = await (0, virlow_crypto_1.decryptAttachment)(fromKey, full);
+            return (await (0, virlow_crypto_1.encryptAttachment)(toKey, filename, bytes)).encryptedData;
+        }
+        catch (err) {
+            throw decryptFailure(err);
         }
     }
     requireSession() {

package/dist/cjs/exposure.d.ts

@@ -1,4 +1,15 @@
-import type { ApiFolder } from './api.js';
+import type { ApiFolder, ApiNote } from './api.js';
+/**
+ * A note in a shared workspace is encrypted under that workspace's key at the
+ * note's version, not the account key. The keyring (keyring.ts) opens that key
+ * from this account's grant; when it cannot (no grant yet, a grant that fails
+ * its checks, a granter whose keys changed) the note is skipped in every scan
+ * and refused by id, never opened or written with the account key.
+ */
+export declare function isSharedNote(row: Pick<ApiNote, 'keyVersion'>): boolean;
+/** The reason is one of a fixed set (keyring.ts, describeKeyFailure), never
+ * the cause's own message, which can be server text or decrypted bytes. */
+export declare function sharedNoteError(id: string, cause?: unknown): Error;
 /**
  * Which folders the user has actually opened to AI tools.
  *
@@ -28,7 +39,29 @@ export interface ExposureOptions {
      * tools, so requiring the user to opt it in would be asking them to
      * authorise a folder they never made for a purpose it already has. */
     memoriesRootId?: string | null;
+    /**
+     * The unlocked account. When given, a folder that belongs to someone else's
+     * shared workspace (its row is not this account's, or its workspace's owner
+     * is someone else) is judged by `mcpEnabledForMember` alone: the row's own
+     * `mcpEnabled` is one value every editor of the workspace can set, so it is
+     * not this member's consent. See `isForeignFolder`.
+     */
+    viewerId?: string;
+    /** Workspace id to its owner, for the folders that carry a workspaceId.
+     * A workspace missing here counts as someone else's. */
+    workspaceOwners?: ReadonlyMap<string, string>;
 }
+/**
+ * Whether a folder is in a shared workspace this account does not own.
+ *
+ * Such a folder is closed to this account's AI tools unless the server reports
+ * it open for this member (`mcpEnabledForMember`). The hosted connector's
+ * folder list carries that per-member value. The local CLI has no per-member
+ * switch yet, so there a workspace shared with this account stays closed to
+ * AI tools; the workspaces this account owns follow their own switch as
+ * before.
+ */
+export declare function isForeignFolder(folder: Pick<ApiFolder, 'userId' | 'workspaceId'>, viewerId: string, workspaceOwners?: ReadonlyMap<string, string>): boolean;
 export declare function computeExposure(folders: ReadonlyArray<ApiFolder>, opts?: ExposureOptions): Exposure;
 /**
  * The sentence appended to any result that was filtered. Never omitted when
@@ -38,4 +71,5 @@ export declare function computeExposure(folders: ReadonlyArray<ApiFolder>, opts?
 export declare function filteredNotice(hidden: {
     inClosedFolders: number;
     unfiled: number;
+    shared?: number;
 }, exposure: Exposure): string;

package/dist/cjs/exposure.js

@@ -1,10 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSharedNote = isSharedNote;
+exports.sharedNoteError = sharedNoteError;
+exports.isForeignFolder = isForeignFolder;
 exports.computeExposure = computeExposure;
 exports.filteredNotice = filteredNotice;
+const keyring_js_1 = require("./keyring.js");
+/**
+ * A note in a shared workspace is encrypted under that workspace's key at the
+ * note's version, not the account key. The keyring (keyring.ts) opens that key
+ * from this account's grant; when it cannot (no grant yet, a grant that fails
+ * its checks, a granter whose keys changed) the note is skipped in every scan
+ * and refused by id, never opened or written with the account key.
+ */
+function isSharedNote(row) {
+    return row.keyVersion !== undefined && row.keyVersion !== null;
+}
+/** The reason is one of a fixed set (keyring.ts, describeKeyFailure), never
+ * the cause's own message, which can be server text or decrypted bytes. */
+function sharedNoteError(id, cause) {
+    return new Error(`Note ${id} is in a shared workspace whose key could not be opened here (${(0, keyring_js_1.describeKeyFailure)(cause)}). ` +
+        'Open it in the Virlow app instead.');
+}
+/**
+ * Whether a folder is in a shared workspace this account does not own.
+ *
+ * Such a folder is closed to this account's AI tools unless the server reports
+ * it open for this member (`mcpEnabledForMember`). The hosted connector's
+ * folder list carries that per-member value. The local CLI has no per-member
+ * switch yet, so there a workspace shared with this account stays closed to
+ * AI tools; the workspaces this account owns follow their own switch as
+ * before.
+ */
+function isForeignFolder(folder, viewerId, workspaceOwners = new Map()) {
+    if (folder.userId !== undefined && folder.userId !== null && folder.userId !== viewerId)
+        return true;
+    if (folder.workspaceId)
+        return workspaceOwners.get(folder.workspaceId) !== viewerId;
+    return false;
+}
 function computeExposure(folders, opts = {}) {
     const byId = new Map(folders.map((f) => [f.id, f]));
-    const memoriesRootId = opts.memoriesRootId ?? folders.find((f) => f.kind === 'memories')?.id ?? null;
+    const viewerId = opts.viewerId;
+    const foreign = (folder) => viewerId !== undefined && isForeignFolder(folder, viewerId, opts.workspaceOwners);
+    // Memories are never shared: a "memories" folder in someone else's
+    // workspace is not this account's memories root, whatever its kind says.
+    const candidateRootId = opts.memoriesRootId ?? folders.find((f) => f.kind === 'memories' && !foreign(f))?.id ?? null;
+    const candidateRoot = candidateRootId === null ? undefined : byId.get(candidateRootId);
+    const memoriesRootId = candidateRoot !== undefined && foreign(candidateRoot) ? null : candidateRootId;
     const resolved = new Map();
     const isExposed = (folderId) => {
         const cached = resolved.get(folderId);
@@ -17,13 +60,22 @@ function computeExposure(folders, opts = {}) {
         const seen = new Set();
         let current = folderId;
         let exposed = false;
+        const start = byId.get(folderId);
+        const startForeign = start !== undefined && foreign(start);
         while (current !== null && !seen.has(current)) {
             seen.add(current);
             const folder = byId.get(current);
             if (folder === undefined)
                 break;
+            // A shared workspace is a top-level tree, so a walk never legitimately
+            // crosses between this account's folders and someone else's. One that
+            // would (a parent the server put there) stops, closed, so neither side's
+            // switch can open the other.
+            if (foreign(folder) !== startForeign)
+                break;
             chain.push(folder.id);
-            if (folder.mcpEnabled === true || folder.id === memoriesRootId) {
+            const switchedOn = startForeign ? folder.mcpEnabledForMember === true : folder.mcpEnabled === true;
+            if (switchedOn || folder.id === memoriesRootId) {
                 exposed = true;
                 break;
             }
@@ -73,5 +125,10 @@ function filteredNotice(hidden, exposure) {
             `${n === 1 ? 'it' : 'them'} into a folder that is exposed to MCP to include ` +
             `${n === 1 ? 'it' : 'them'}.`);
     }
+    if (hidden.shared && hidden.shared > 0) {
+        const n = hidden.shared;
+        parts.push(`${n} note${n === 1 ? '' : 's'} in shared workspaces left out: the workspace key did not ` +
+            'open or did not check out here. Open the workspace in the Virlow app to see them.');
+    }
     return parts.length === 0 ? '' : `\n\n(${parts.join(' ')})`;
 }

package/dist/cjs/index.d.ts

@@ -1,9 +1,12 @@
 export { ApiError, VirlowApi } from './api.js';
-export type { ApiFile, ApiFileWithData, ApiFolder, ApiNote, FileUpload, AuthTokens, LoginResult, NoteWrite, RefreshBody } from './api.js';
+export type { ApiFile, ApiFileWithData, ApiFolder, ApiIdentity, ApiNote, ApiWorkspaceDetail, ApiWorkspaceGrant, ApiWorkspaceSummary, 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 { KeyChangedError, NoWorkspaceKeyError, WorkspaceKeyring, memorySignerMemory } from './keyring.js';
+export type { KeyChoice, SignerMemory } from './keyring.js';
+export { fileSignerMemory } from './signer-file.js';
 export type { AttachmentInfo } from './attachments.js';
 export { MemoryStore, SYNC_PAGE_LIMIT } from './memories.js';
 export type { CachedMemory, SimilarMemory, SyncResult } from './memories.js';