@batalabs/virlow-mcp-core 3.116.0 → 3.117.0

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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.AttachmentsService = exports.SEARCH_SCAN_CAP = exports.NotesService = exports.Vault = exports.LockedError = exports.VirlowApi = exports.ApiError = void 0;
-exports.TodoService = exports.htmlToText = exports.extractLinkIds = void 0;
+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;
 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,13 @@ 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; } });
+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; } });
+Object.defineProperty(exports, "WorkspaceKeyring", { enumerable: true, get: function () { return keyring_js_1.WorkspaceKeyring; } });
+Object.defineProperty(exports, "memorySignerMemory", { enumerable: true, get: function () { return keyring_js_1.memorySignerMemory; } });
+var signer_file_js_1 = require("./signer-file.js");
+Object.defineProperty(exports, "fileSignerMemory", { enumerable: true, get: function () { return signer_file_js_1.fileSignerMemory; } });
 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/keyring.d.ts

@@ -0,0 +1,155 @@
+import type { ApiFolder, ApiWorkspaceSummary, VirlowApi } from './api.js';
+import { type Vault } from './vault.js';
+/**
+ * Which key a row in a shared workspace is encrypted under, and the key
+ * itself: the connector's side of the web app's keyring
+ * (src/lib/sharing/keyring.ts in the app, KeyBook.kt on Android;
+ * docs/superpowers/specs/2026-10-14-shared-workspaces-design.md).
+ *
+ * A personal row (no key version) uses the account key. A row in a shared
+ * workspace uses that workspace's key at the row's version, opened from this
+ * account's grant. Before a key is used:
+ *
+ * - the grant must open with this account's identity (whose private halves
+ *   are sealed under the account key), bound to this workspace, version and
+ *   person;
+ * - the granter must be allowed to grant: the workspace's owner, or an owner
+ *   or editor in its member list; a grant this account made itself must carry
+ *   this account's own signing key;
+ * - the signature must check out against the signing key this connector
+ *   first saw for the granter. A key that changed since is refused, because
+ *   that is what a server swapping keys would look like.
+ *
+ * Writes never go under a key version older than one this account has
+ * already seen for the workspace, so a server cannot roll a workspace back to
+ * a key a removed member still holds.
+ *
+ * Everything opened is held for one unlock and dropped when the vault locks,
+ * with the same epoch guard NotesService uses, so a fetch still in flight at
+ * the lock never seeds the next session. The remembered signing keys are
+ * public and are kept across locks (they are what makes trust-on-first-use
+ * mean anything); a host can persist them with `signers`.
+ *
+ * Where the pins live: the local CLI keeps them in a file (signer-file.ts),
+ * so they survive restarts. The hosted connector keeps them in memory, per
+ * process: a restart or another machine starts trusting afresh. That host
+ * already holds the account key in memory, so its pins defend against
+ * nothing it could not do anyway; they are kept for parity, not as a
+ * boundary.
+ */
+/** Signing keys seen for each person, first one wins: the web's `virlow.knownSigners`. */
+export interface SignerMemory {
+    get(userId: string): string | null;
+    /**
+     * Remember `sign` for `userId` unless a key is already remembered. Must be
+     * a compare-and-set: throws KeyChangedError when a different key got there
+     * first, never overwrites it.
+     */
+    remember(userId: string, sign: string): void;
+}
+/** Remembered for as long as the process lives. The default, and what the
+ * hosted connector uses: pins there are per process (see above). */
+export declare function memorySignerMemory(): SignerMemory;
+/**
+ * Why a workspace key did not open, as one of a fixed set. The text an AI
+ * tool sees comes only from here, never from an error's own message: those
+ * can carry server-chosen text, or (a JSON parse error) decrypted bytes.
+ */
+export type KeyFailureReason = 'no-grant' | 'key-changed' | 'signature-rejected' | 'not-authorized' | 'locked';
+export declare class SharedKeyError extends Error {
+    readonly reason: KeyFailureReason;
+    constructor(reason: KeyFailureReason);
+}
+/** Someone's signing key is not the one first seen for them. */
+export declare class KeyChangedError extends SharedKeyError {
+    readonly userId: string;
+    constructor(userId: string);
+}
+/** No key for this workspace and version opens here. */
+export declare class NoWorkspaceKeyError extends SharedKeyError {
+    constructor();
+}
+/** The grant came from someone the workspace does not let grant. */
+export declare class GranterNotAuthorizedError extends SharedKeyError {
+    constructor();
+}
+/** A write refused for a reason this module states itself (a viewer, a
+ * rollback). Its message is fixed text, safe to show as it is. */
+export declare class WriteRefusedError extends Error {
+    constructor(message: string);
+}
+export declare function keyFailureReason(err: unknown): KeyFailureReason;
+/** The fixed sentence for a failure; see KeyFailureReason. */
+export declare function describeKeyFailure(err: unknown): string;
+export interface KeyChoice {
+    key: CryptoKey;
+    /** The version sent with the ciphertext; null = the account key. */
+    keyVersion: number | null;
+    /** The workspace's owner; null for the account key. */
+    ownerId: string | null;
+}
+export declare class WorkspaceKeyring {
+    private readonly api;
+    private readonly vault;
+    /** Where the remembered signing keys live, per account. In memory by default. */
+    private readonly signers;
+    private epoch;
+    private identityPending;
+    private readonly details;
+    private readonly keys;
+    private readonly signerMemories;
+    /** `userId:workspaceId` to the highest key version this account has seen
+     * granted there. Kept across locks: versions only ever go up. */
+    private readonly highestSeen;
+    constructor(api: VirlowApi, vault: Vault, 
+    /** Where the remembered signing keys live, per account. In memory by default. */
+    signers?: (userId: string) => SignerMemory);
+    private handleLock;
+    /** The key to read a row with, from the version it was written under. */
+    forRead(accountKey: CryptoKey, keyVersion: number | null | undefined, workspaceId: string | null | undefined): Promise<CryptoKey>;
+    /**
+     * The key to write into a workspace with: its current version, as the API
+     * requires of every new ciphertext there. Never the account key: a null
+     * workspace is the only way to get that, and it is the caller's to ask.
+     * Asks the server for the current version every time, since a removal
+     * rotates the key and the connector hears no change signal.
+     *
+     * Refuses a version older than `atLeast` (the version the row being
+     * rewritten is already under) or than any this account has been granted
+     * for the workspace: writing under an older key would hand the new text to
+     * whoever a rotation meant to shut out.
+     */
+    forWrite(accountKey: CryptoKey, workspaceId: string | null | undefined, opts?: {
+        atLeast?: number | null;
+    }): Promise<KeyChoice>;
+    /** This account's role and the current key version of one workspace. Not cached. */
+    summary(workspaceId: string): Promise<ApiWorkspaceSummary>;
+    /**
+     * Who owns each workspace these folders belong to, for the exposure rule
+     * (exposure.ts, isForeignFolder). No request when none of them is shared.
+     */
+    workspaceOwners(folders: ReadonlyArray<ApiFolder>): Promise<Map<string, string>>;
+    /** A workspace key version, opened and checked. Kept until the vault locks. */
+    workspaceKey(workspaceId: string, keyVersion: number): Promise<CryptoKey>;
+    private versionKey;
+    private highestVersion;
+    private noteVersion;
+    private openKey;
+    /**
+     * The granter must be allowed to grant (the owner, or an owner or editor in
+     * the member list), and a grant this account made must carry its own
+     * signing key: one the server substituted would otherwise be pinned for
+     * this account itself on first use.
+     */
+    private requireAuthorizedGranter;
+    private detail;
+    /**
+     * This account's identity, opened with the unlocked account key. Never made
+     * here: an account without one has been sealed no workspace keys, and the
+     * app makes it on the next unlock there. Any failure to open it is reported
+     * as "no grant", without its cause: a parse error would quote the bytes it
+     * choked on, and those are decrypted.
+     */
+    private identity;
+    private signerMemory;
+}

package/dist/cjs/keyring.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkspaceKeyring = exports.WriteRefusedError = exports.GranterNotAuthorizedError = exports.NoWorkspaceKeyError = exports.KeyChangedError = exports.SharedKeyError = void 0;
+exports.memorySignerMemory = memorySignerMemory;
+exports.keyFailureReason = keyFailureReason;
+exports.describeKeyFailure = describeKeyFailure;
+const virlow_crypto_1 = require("@batalabs/virlow-crypto");
+const vault_js_1 = require("./vault.js");
+/** Remembered for as long as the process lives. The default, and what the
+ * hosted connector uses: pins there are per process (see above). */
+function memorySignerMemory() {
+    const seen = new Map();
+    return {
+        get: (id) => seen.get(id) ?? null,
+        remember: (id, sign) => {
+            const known = seen.get(id);
+            if (known !== undefined && known !== sign)
+                throw new KeyChangedError(id);
+            seen.set(id, sign);
+        },
+    };
+}
+const REASON_TEXT = {
+    'no-grant': 'no usable key for it was shared with you',
+    'key-changed': 'the keys of the person who shared it changed since this connector first saw them',
+    'signature-rejected': 'its key did not carry a valid signature from the person who shared it',
+    'not-authorized': 'its key was shared by someone not allowed to share it',
+    locked: 'the vault locked',
+};
+class SharedKeyError extends Error {
+    reason;
+    constructor(reason) {
+        super(REASON_TEXT[reason]);
+        this.reason = reason;
+        this.name = 'SharedKeyError';
+    }
+}
+exports.SharedKeyError = SharedKeyError;
+/** Someone's signing key is not the one first seen for them. */
+class KeyChangedError extends SharedKeyError {
+    userId;
+    constructor(userId) {
+        super('key-changed');
+        this.name = 'KeyChangedError';
+        this.userId = userId;
+    }
+}
+exports.KeyChangedError = KeyChangedError;
+/** No key for this workspace and version opens here. */
+class NoWorkspaceKeyError extends SharedKeyError {
+    constructor() {
+        super('no-grant');
+        this.name = 'NoWorkspaceKeyError';
+    }
+}
+exports.NoWorkspaceKeyError = NoWorkspaceKeyError;
+/** The grant came from someone the workspace does not let grant. */
+class GranterNotAuthorizedError extends SharedKeyError {
+    constructor() {
+        super('not-authorized');
+        this.name = 'GranterNotAuthorizedError';
+    }
+}
+exports.GranterNotAuthorizedError = GranterNotAuthorizedError;
+/** A write refused for a reason this module states itself (a viewer, a
+ * rollback). Its message is fixed text, safe to show as it is. */
+class WriteRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WriteRefusedError';
+    }
+}
+exports.WriteRefusedError = WriteRefusedError;
+function keyFailureReason(err) {
+    if (err instanceof vault_js_1.LockedError)
+        return 'locked';
+    if (err instanceof SharedKeyError)
+        return err.reason;
+    if (err instanceof virlow_crypto_1.GrantRejectedError)
+        return 'signature-rejected';
+    return 'no-grant';
+}
+/** The fixed sentence for a failure; see KeyFailureReason. */
+function describeKeyFailure(err) {
+    return REASON_TEXT[keyFailureReason(err)];
+}
+function lockedError() {
+    return new vault_js_1.LockedError('Vault is locked. Call this server\'s unlock tool and ask the user to finish unlocking their Virlow vault.');
+}
+const SELF_CHECK = new TextEncoder().encode('virlow-self-grant-check-v1');
+class WorkspaceKeyring {
+    api;
+    vault;
+    signers;
+    epoch = 0;
+    identityPending = null;
+    details = new Map();
+    keys = new Map();
+    signerMemories = new Map();
+    /** `userId:workspaceId` to the highest key version this account has seen
+     * granted there. Kept across locks: versions only ever go up. */
+    highestSeen = new Map();
+    constructor(api, vault, 
+    /** Where the remembered signing keys live, per account. In memory by default. */
+    signers = () => memorySignerMemory()) {
+        this.api = api;
+        this.vault = vault;
+        this.signers = signers;
+        // The setter adds a listener (see Vault.onLock); it never replaces one.
+        this.vault.onLock = () => this.handleLock();
+    }
+    handleLock() {
+        this.identityPending = null;
+        this.details.clear();
+        this.keys.clear();
+        this.epoch++;
+    }
+    /** The key to read a row with, from the version it was written under. */
+    async forRead(accountKey, keyVersion, workspaceId) {
+        if (keyVersion === null || keyVersion === undefined)
+            return accountKey;
+        if (!workspaceId)
+            throw new NoWorkspaceKeyError();
+        return this.workspaceKey(workspaceId, keyVersion);
+    }
+    /**
+     * The key to write into a workspace with: its current version, as the API
+     * requires of every new ciphertext there. Never the account key: a null
+     * workspace is the only way to get that, and it is the caller's to ask.
+     * Asks the server for the current version every time, since a removal
+     * rotates the key and the connector hears no change signal.
+     *
+     * Refuses a version older than `atLeast` (the version the row being
+     * rewritten is already under) or than any this account has been granted
+     * for the workspace: writing under an older key would hand the new text to
+     * whoever a rotation meant to shut out.
+     */
+    async forWrite(accountKey, workspaceId, opts = {}) {
+        if (!workspaceId)
+            return { key: accountKey, keyVersion: null, ownerId: null };
+        const startEpoch = this.epoch;
+        const summary = await this.summary(workspaceId);
+        if (this.epoch !== startEpoch)
+            throw lockedError();
+        if (summary.role === 'viewer') {
+            throw new WriteRefusedError('You can view this shared workspace but not change it. Ask its owner to make you an editor.');
+        }
+        const detail = await this.detail(workspaceId);
+        if (this.epoch !== startEpoch)
+            throw lockedError();
+        const granted = Math.max(0, ...detail.grants.map((g) => g.keyVersion));
+        this.noteVersion(workspaceId, granted);
+        const floor = Math.max(this.highestVersion(workspaceId), opts.atLeast ?? 0);
+        if (summary.keyVersion < floor) {
+            throw new WriteRefusedError('The server offered an older key for this shared workspace than this account already holds, ' +
+                'so nothing was written. Open the workspace in the Virlow app.');
+        }
+        const key = await this.workspaceKey(workspaceId, summary.keyVersion);
+        return { key, keyVersion: summary.keyVersion, ownerId: summary.ownerId };
+    }
+    /** This account's role and the current key version of one workspace. Not cached. */
+    async summary(workspaceId) {
+        const summaries = await this.api.listWorkspaces();
+        const summary = summaries.find((s) => s.id === workspaceId);
+        if (!summary)
+            throw new NoWorkspaceKeyError();
+        return summary;
+    }
+    /**
+     * Who owns each workspace these folders belong to, for the exposure rule
+     * (exposure.ts, isForeignFolder). No request when none of them is shared.
+     */
+    async workspaceOwners(folders) {
+        if (!folders.some((f) => f.workspaceId))
+            return new Map();
+        const summaries = await this.api.listWorkspaces();
+        return new Map(summaries.map((s) => [s.id, s.ownerId]));
+    }
+    /** A workspace key version, opened and checked. Kept until the vault locks. */
+    workspaceKey(workspaceId, keyVersion) {
+        const id = `${workspaceId}:${keyVersion}`;
+        let pending = this.keys.get(id);
+        if (!pending) {
+            const startEpoch = this.epoch;
+            pending = this.openKey(workspaceId, keyVersion, startEpoch);
+            // A failure is retried on the next call, not remembered: the grant may
+            // simply not have been sealed yet.
+            pending.catch(() => {
+                if (this.keys.get(id) === pending)
+                    this.keys.delete(id);
+            });
+            this.keys.set(id, pending);
+        }
+        return pending;
+    }
+    versionKey(workspaceId) {
+        return `${this.vault.session.userId}:${workspaceId}`;
+    }
+    highestVersion(workspaceId) {
+        return this.highestSeen.get(this.versionKey(workspaceId)) ?? 0;
+    }
+    noteVersion(workspaceId, keyVersion) {
+        const id = this.versionKey(workspaceId);
+        if (keyVersion > (this.highestSeen.get(id) ?? 0))
+            this.highestSeen.set(id, keyVersion);
+    }
+    async openKey(workspaceId, keyVersion, startEpoch) {
+        const { userId } = this.vault.session;
+        let detail = await this.detail(workspaceId);
+        let grant = detail.grants.find((g) => g.keyVersion === keyVersion);
+        if (!grant) {
+            // A rotation since the detail was fetched: ask once more.
+            this.details.delete(workspaceId);
+            detail = await this.detail(workspaceId);
+            grant = detail.grants.find((g) => g.keyVersion === keyVersion);
+        }
+        if (!grant || !grant.granterSign)
+            throw new NoWorkspaceKeyError();
+        const granterSign = grant.granterSign;
+        const identity = await this.identity();
+        if (this.epoch !== startEpoch)
+            throw lockedError();
+        await this.requireAuthorizedGranter(detail, grant, granterSign, identity, userId);
+        // Checked against the signing key first seen for the granter, and
+        // remembered only once the grant opens and verifies under it, so a grant
+        // that fails never pins the key it came with.
+        const signers = this.signerMemory(userId);
+        const known = signers.get(grant.granterId);
+        if (known !== null && known !== granterSign)
+            throw new KeyChangedError(grant.granterId);
+        const { key } = await (0, virlow_crypto_1.openGrant)(identity, { sealed: grant.sealed, signature: grant.signature }, { workspaceId, keyVersion, recipientUserId: userId }, granterSign);
+        if (this.epoch !== startEpoch)
+            throw lockedError();
+        // Read again: another open (or another process sharing the pin file) may
+        // have pinned a different key for this granter while this one was
+        // verifying. remember() is a compare-and-set as well.
+        const now = signers.get(grant.granterId);
+        if (now !== null && now !== granterSign)
+            throw new KeyChangedError(grant.granterId);
+        if (now === null)
+            signers.remember(grant.granterId, granterSign);
+        this.noteVersion(workspaceId, keyVersion);
+        return key;
+    }
+    /**
+     * The granter must be allowed to grant (the owner, or an owner or editor in
+     * the member list), and a grant this account made must carry its own
+     * signing key: one the server substituted would otherwise be pinned for
+     * this account itself on first use.
+     */
+    async requireAuthorizedGranter(detail, grant, granterSign, identity, userId) {
+        const member = (detail.members ?? []).find((m) => m.userId === grant.granterId);
+        const allowed = grant.granterId === detail.workspace.ownerId || member?.role === 'owner' || member?.role === 'editor';
+        if (!allowed)
+            throw new GranterNotAuthorizedError();
+        if (grant.granterId !== userId)
+            return;
+        if (granterSign !== identity.public.sign)
+            throw new KeyChangedError(userId);
+        // The public half the server stores is not bound to the sealed private
+        // one, so prove they are a pair: sign with the private key, verify with
+        // the key the grant names.
+        const signature = await crypto.subtle.sign('Ed25519', identity.signPrivate, SELF_CHECK);
+        const publicKey = await crypto.subtle.importKey('raw', (0, virlow_crypto_1.base64ToBytes)(granterSign), { name: 'Ed25519' }, false, ['verify']);
+        if (!(await crypto.subtle.verify('Ed25519', publicKey, signature, SELF_CHECK))) {
+            throw new KeyChangedError(userId);
+        }
+    }
+    detail(workspaceId) {
+        let pending = this.details.get(workspaceId);
+        if (!pending) {
+            pending = this.api.getWorkspace(workspaceId);
+            pending.catch(() => {
+                if (this.details.get(workspaceId) === pending)
+                    this.details.delete(workspaceId);
+            });
+            this.details.set(workspaceId, pending);
+        }
+        return pending;
+    }
+    /**
+     * This account's identity, opened with the unlocked account key. Never made
+     * here: an account without one has been sealed no workspace keys, and the
+     * app makes it on the next unlock there. Any failure to open it is reported
+     * as "no grant", without its cause: a parse error would quote the bytes it
+     * choked on, and those are decrypted.
+     */
+    identity() {
+        if (!this.identityPending) {
+            const accountKey = this.vault.session.key;
+            const pending = (async () => {
+                const stored = await this.api.getIdentity();
+                if (!stored)
+                    throw new NoWorkspaceKeyError();
+                try {
+                    return await (0, virlow_crypto_1.openIdentity)(accountKey, stored.sealedPrivate, { box: stored.box, sign: stored.sign });
+                }
+                catch {
+                    throw new NoWorkspaceKeyError();
+                }
+            })();
+            pending.catch(() => {
+                if (this.identityPending === pending)
+                    this.identityPending = null;
+            });
+            this.identityPending = pending;
+        }
+        return this.identityPending;
+    }
+    signerMemory(userId) {
+        let memory = this.signerMemories.get(userId);
+        if (!memory) {
+            memory = this.signers(userId);
+            this.signerMemories.set(userId, memory);
+        }
+        return memory;
+    }
+}
+exports.WorkspaceKeyring = WorkspaceKeyring;

package/dist/cjs/memories.d.ts

@@ -158,7 +158,7 @@ export declare class MemoryStore {
      *  the facts behind them. Null when no memory names it. */
     recallEntity(name: string, namespace?: string): Promise<{
         name: string;
-        kind: "project" | "person" | "organization" | "tool" | "place" | "event" | "topic" | "product" | "media" | "pet" | "group" | "goal" | "other";
+        kind: "place" | "project" | "person" | "organization" | "tool" | "event" | "topic" | "product" | "media" | "pet" | "group" | "goal" | "other";
         /** Whether the kind is stored (set by a person or an AI) or guessed. */
         kindStored: boolean;
         aliases: string[];
@@ -193,7 +193,7 @@ export declare class MemoryStore {
             note?: string | undefined;
             name: string;
             facts: number;
-            kind: "project" | "person" | "organization" | "tool" | "place" | "event" | "topic" | "product" | "media" | "pet" | "group" | "goal" | "other";
+            kind: "place" | "project" | "person" | "organization" | "tool" | "event" | "topic" | "product" | "media" | "pet" | "group" | "goal" | "other";
         }[];
         facts: CachedMemory[];
     }>;

package/dist/cjs/notes.d.ts

@@ -2,6 +2,7 @@ import { type Exposure } from './exposure.js';
 import { type HomeWidget, type NoteAttrsV1, type PropDefinition, type PropType, type PropValue } from './attrs.js';
 import type { VirlowApi } from './api.js';
 import { type Vault } from './vault.js';
+import { WorkspaceKeyring } from './keyring.js';
 /** Hard ceiling on how many notes searchNotes() will decrypt+scan in a
  * single call. Keeps a single search bounded even for very large accounts;
  * `truncated` tells the caller when the account holds more than this. Also
@@ -61,7 +62,10 @@ export declare class NotesService {
      * the same pre-edit row and the second write would silently clobber the
      * first's change. Mirrors MemoryStore's enqueue()/mutationChain pattern. */
     private mutationChain;
-    constructor(api: VirlowApi, vault: Vault);
+    /** 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);
     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
@@ -93,6 +97,7 @@ export declare class NotesService {
         withheld: {
             inClosedFolders: number;
             unfiled: number;
+            shared?: number;
         };
         exposure: Exposure;
     }>;
@@ -135,6 +140,7 @@ export declare class NotesService {
         };
         withheld: {
             inClosedFolders: number;
+            shared?: number;
         };
         sortedBy: PropDefinition | null;
     }>;
@@ -255,6 +261,8 @@ export declare class NotesService {
      * flip the switch in the app at any moment and the next tool call must
      * respect it. */
     private exposure;
+    /** Who is unlocked: the account whose consent the exposure rule asks for. */
+    private viewerId;
     /** The same computation for a caller that already has the folder list and
      * needs a folder out of it as well as the exposure (the property tools do:
      * a folder's schema and its exposure come from the same row). */
@@ -266,6 +274,50 @@ export declare class NotesService {
     createFolder(name: string, parentId?: string | null): Promise<{
         id: string;
     }>;
+    /** A folder's name as the person sees it: a shared folder's is under the
+     * workspace key (its `name` column only says "[ENCRYPTED]"). One that does
+     * not open is called what the app calls it. */
+    private folderName;
+    /** The shared workspace a note is in: from its own folder field when the
+     * server sent one, else from the folder list. Null for a personal note. */
+    private workspaceOfRow;
+    /** The key a note's ciphertext is under: the account key for a personal
+     * note, the workspace key at the note's version for a shared one. Throws
+     * when a shared note's key does not open; never falls back. */
+    private keyForRowOrThrow;
+    /** The same, as null instead of a throw, for scans that skip what they
+     * cannot open. A lock is not a note that cannot be opened: it propagates,
+     * so a scan cut short by one fails rather than reporting skipped notes. */
+    private keyForRowOrNull;
+    /** The key a folder's name and schema are under. */
+    private keyForFolder;
+    /**
+     * The ciphertext half of a note write: attrs, plus title and content when
+     * they changed, all under the key the note's place uses now (a shared
+     * workspace's current version, with that version sent along) and never the
+     * account key for a note in a shared workspace.
+     *
+     * The row has one key version for all of its ciphertext, and the API sets it
+     * from the write. So when the version changes (a rotation since the note was
+     * last saved, or a note the owner's sharing run has not reached yet), the
+     * unchanged title and content are re-encrypted as well; sending only the
+     * attrs would leave them under a key the row no longer names.
+     */
+    private sealNoteWrite;
+    /**
+     * Moving ciphertext from the account key to a workspace key is what the
+     * owner's sharing run does. For anyone else, a server that says a personal
+     * row is now in a workspace could otherwise have it re-encrypted under a key
+     * that server handed out, so it is refused unless this account owns the
+     * workspace.
+     */
+    private requireOwnedForRekey;
+    /**
+     * Writes a folder's schema under the key its place uses now. In a shared
+     * workspace the folder's name shares the row's key version, so a folder
+     * still under an older version has its name re-encrypted in the same write.
+     */
+    private writeSchema;
     /** Decrypt (with per-unlock caching) or pass through a legacy plaintext
      * row. Legacy rows (no encryptedTitle) carry their real content directly
      * in the plaintext title/content columns. */