@batalabs/virlow-mcp-core 3.19.0 → 3.68.0

package/dist/cjs/memory-secrets.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Refuses memories that contain credentials, before anything is written.
+ *
+ * Memories are captured automatically, so the rule cannot depend on the AI
+ * remembering not to save a key: a memory is encrypted, but it is recalled
+ * into prompts and shown in the app, and a secret has no business in either.
+ * The check is on-device and returns a reason, so the AI can say what it
+ * left out instead of retrying with the secret reworded.
+ *
+ * Deliberately narrow: patterns that are credentials with near certainty,
+ * plus long high-entropy tokens. A false positive costs one memory; a false
+ * negative puts a live key into every future prompt that recalls it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretInMemoryError = void 0;
+exports.findSecret = findSecret;
+exports.assertNoSecret = assertNoSecret;
+const PATTERNS = [
+    { what: 'a private key', test: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+    { what: 'an AWS access key', test: /\b(AKIA|ASIA)[0-9A-Z]{16}\b/ },
+    { what: 'a GitHub token', test: /\b(ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/ },
+    { what: 'a Slack token', test: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/ },
+    { what: 'a Stripe key', test: /\b(sk|rk|pk)_(live|test)_[A-Za-z0-9]{16,}\b/ },
+    { what: 'a Stripe webhook secret', test: /\bwhsec_[A-Za-z0-9]{16,}\b/ },
+    { what: 'an API key', test: /\bsk-(ant-|proj-)?[A-Za-z0-9_-]{20,}\b/ },
+    { what: 'a Google API key', test: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    { what: 'a JSON web token', test: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/ },
+    {
+        what: 'a password',
+        test: /\b(password|passwd|pwd|passphrase|api[_ -]?key|secret|token)\s*[:=]\s*\S{6,}/i,
+    },
+    { what: 'a connection string with a password', test: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s@/]{3,}@/i },
+];
+/** Luhn-valid runs of 13 to 19 digits, spaces or dashes allowed. */
+function hasCardNumber(text) {
+    for (const match of text.matchAll(/\b(?:\d[ -]?){13,19}\b/g)) {
+        const digits = match[0].replace(/\D/g, '');
+        if (digits.length < 13 || digits.length > 19)
+            continue;
+        let sum = 0;
+        for (let i = 0; i < digits.length; i++) {
+            let d = Number(digits[digits.length - 1 - i]);
+            if (i % 2 === 1) {
+                d *= 2;
+                if (d > 9)
+                    d -= 9;
+            }
+            sum += d;
+        }
+        if (sum % 10 === 0)
+            return true;
+    }
+    return false;
+}
+/** Shannon entropy per character. */
+function entropy(token) {
+    const counts = new Map();
+    for (const ch of token)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let bits = 0;
+    for (const n of counts.values()) {
+        const p = n / token.length;
+        bits -= p * Math.log2(p);
+    }
+    return bits;
+}
+/** A long run of mixed letters and digits with no structure a person
+ *  writes: what an unlabelled key or token looks like. Ids like UUIDs and
+ *  hex hashes are common in notes and are left alone. */
+function hasHighEntropyToken(text) {
+    for (const [token] of text.matchAll(/[A-Za-z0-9+/_=-]{32,}/g)) {
+        if (/^[0-9a-f-]+$/i.test(token))
+            continue; // uuid or hex hash
+        if (!/[a-z]/.test(token) || !/[A-Z]/.test(token) || !/[0-9]/.test(token))
+            continue;
+        if (entropy(token) >= 4.2)
+            return true;
+    }
+    return false;
+}
+/** What secret the text holds, or null when it holds none. */
+function findSecret(text) {
+    for (const pattern of PATTERNS) {
+        if (pattern.test.test(text))
+            return pattern.what;
+    }
+    if (hasCardNumber(text))
+        return 'a card number';
+    if (hasHighEntropyToken(text))
+        return 'what looks like a key or token';
+    return null;
+}
+class SecretInMemoryError extends Error {
+    constructor(what) {
+        super(`Not saved: this memory contains ${what}. Memories are recalled into prompts, so credentials are never ` +
+            'stored. Save the fact without the secret (for example "the API key is in 1Password"), not the secret.');
+        this.name = 'SecretInMemoryError';
+    }
+}
+exports.SecretInMemoryError = SecretInMemoryError;
+function assertNoSecret(...texts) {
+    for (const text of texts) {
+        const what = findSecret(text);
+        if (what)
+            throw new SecretInMemoryError(what);
+    }
+}

package/dist/cjs/notes.d.ts

@@ -1,10 +1,21 @@
 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 { type Vault } from './vault.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. */
+ * `truncated` tells the caller when the account holds more than this. Also
+ * bounds listVisibleRows(), which backs mention-matching and backlinks(). */
 export declare const SEARCH_SCAN_CAP = 500;
+/** One property a setProperties() call actually changed, said the way the
+ * caller asked for it: the definition's name, and option names rather than
+ * the option ids stored in the note. A caller that had to read ids back to
+ * confirm its own write would be reading something it never wrote. */
+export interface AppliedProp {
+    name: string;
+    /** The stored value rendered for a human, or `removed` when it was cleared. */
+    value: string;
+}
 export declare class NotesService {
     private readonly api;
     private readonly vault;
@@ -12,6 +23,33 @@ export declare class NotesService {
      * so re-reading/re-scanning the same note twice in one unlock doesn't
      * re-run AES-GCM decryption. Cleared whenever the vault locks. */
     private readonly decryptCache;
+    /** Per-unlock cache of decoded attrs, keyed the same way as decryptCache.
+     * Stores `null` too (a note with no attrs), so `.has()` rather than a
+     * truthiness check distinguishes "decoded, no attrs" from "not cached
+     * yet". Cleared on lock alongside decryptCache. */
+    private readonly attrsCache;
+    /** Per-unlock cache of decrypted titles only (no content), used by
+     * mention-matching and backlinks() so neither has to pay for a full body
+     * decrypt just to learn a note's title. Cleared on lock alongside the
+     * other caches. */
+    private readonly titleCache;
+    /** Per-unlock cache of decoded folder schemas, keyed on the folder id and
+     * the ciphertext itself so a schema this service just rewrote is never
+     * served from a stale entry. Cleared on lock alongside the other caches. */
+    private readonly schemaCache;
+    /**
+     * The rows listVisibleRows() last paged, with the epoch and folder-exposure
+     * they were computed under. Without this, update_note paged the entire note
+     * list on every call just to build mention titles, so one edit cost as many
+     * round trips as the account has pages of notes.
+     *
+     * Keyed on the exposure as well as the epoch, so flipping a folder's
+     * "Expose to MCP" switch takes effect on the very next call rather than
+     * leaving a closed folder's titles in the mention set; dropped outright on
+     * every write, so a note this service just created, moved, trashed or
+     * retitled is never missing from (or stale in) the next scan.
+     */
+    private visibleRowsCache;
     /** Bumped every time the vault locks (see handleLock()). decryptRow()
      * captures this before its await on decryptNoteFields() and re-checks it
      * afterward, so a decrypt that was still in flight when the vault locked
@@ -25,6 +63,10 @@ export declare class NotesService {
     private mutationChain;
     constructor(api: VirlowApi, vault: Vault);
     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
+     * lands, so a failed write leaves the cache alone. */
+    private invalidateVisibleRows;
     listNotes(params: {
         folderId?: string;
         starred?: boolean;
@@ -54,11 +96,54 @@ export declare class NotesService {
         };
         exposure: Exposure;
     }>;
+    /**
+     * A folder the way a view shows it: every note in it, with the value it
+     * carries for each of the folder's property definitions.
+     *
+     * The program's AI-parity principle is that every capability the UI gains,
+     * the tools gain in the same epic. The app can now read a folder as a table,
+     * a board or a calendar; without this an assistant could read and write
+     * individual properties but never see the shape the user is looking at, so
+     * "which of these is still in review" meant reading every note in turn.
+     *
+     * Values come from the attrs blob already on each list row, so a folder of
+     * two thousand notes answers without fetching or decrypting a single body.
+     * That is the same constraint the views are built to, and it is why this
+     * reads rows rather than calling readNote per note.
+     *
+     * Hidden notes and unexposed folders are filtered exactly as listNotes does,
+     * and for the same reasons; the counts it withholds are reported here too so
+     * a filtered folder is never mistaken for a small one.
+     */
+    listFolderView(params: {
+        folderId: string;
+        sortBy?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<{
+        defs: PropDefinition[];
+        rows: Array<{
+            id: string;
+            title: string;
+            values: Record<string, string>;
+        }>;
+        pagination: {
+            page: number;
+            limit: number;
+            total: number;
+            pages: number;
+        };
+        withheld: {
+            inClosedFolders: number;
+        };
+        sortedBy: PropDefinition | null;
+    }>;
     readNote(id: string): Promise<{
         id: string;
         title: string;
         content: string;
         folderId: string | null;
+        attrs: NoteAttrsV1 | null;
     }>;
     createNote(title: string, content: string, folderId?: string | null, type?: string): Promise<{
         id: string;
@@ -66,7 +151,85 @@ export declare class NotesService {
     updateNote(id: string, changes: {
         title?: string;
         content?: string;
+        /** Merged into the existing props; a value of `null` deletes that key. */
+        props?: Record<string, PropValue | null>;
+        /** Replaces the existing aliases outright when provided. */
+        aliases?: string[];
     }): Promise<void>;
+    /**
+     * Notes that link to `id`, built entirely from attrs, never a body
+     * decrypt. Scans the same folder-visible, non-hidden rows as listNotes(),
+     * bounded by SEARCH_SCAN_CAP like searchNotes().
+     *
+     * Unlike readNote()/decryptRow(), which let an in-flight decrypt finish and
+     * simply skip the cache write if the vault locked mid-flight, this
+     * aggregates across every visible note in one call: a lock partway through
+     * means the result mixes attrs decoded under a session that's since been
+     * revoked, which is not safe to hand back. So the whole call rejects with
+     * LockedError instead.
+     */
+    backlinks(id: string): Promise<Array<{
+        id: string;
+        title: string;
+    }>>;
+    /** A folder's property definitions, in display order. Read-only, so no
+     * mutation queue and no epoch guard past the read itself. */
+    listProperties(folderId: string): Promise<PropDefinition[]>;
+    /** A folder's dashboard as it stands, with the blocks it will draw. */
+    readDashboard(folderId: string): Promise<{
+        widgets: HomeWidget[];
+        defs: PropDefinition[];
+        arranged: boolean;
+    }>;
+    /**
+     * Replaces a folder's dashboard arrangement.
+     *
+     * The previous arrangement is kept alongside the new one, so a person can
+     * put back what an assistant changed. That matters more here than for a
+     * note: a note edit is visible in the note, while a dashboard edit can
+     * remove a block and leave nothing behind to say what was there. One level,
+     * deliberately: this is an undo, not a history, and the schema travels
+     * inside every folder read.
+     */
+    setDashboard(folderId: string, widgets: HomeWidget[]): Promise<HomeWidget[]>;
+    /**
+     * Appends a property definition to a folder's schema.
+     *
+     * Refuses a name the folder already uses, rather than creating a second
+     * definition with it: setProperties() resolves a value's key by name, and a
+     * duplicate would make every later call ambiguous. The message names the
+     * existing id so the caller can just use it.
+     */
+    defineProperty(folderId: string, def: {
+        name: string;
+        type: PropType;
+        options?: {
+            name: string;
+        }[];
+        showInList?: boolean;
+    }): Promise<PropDefinition>;
+    /**
+     * Sets typed property values on one note, keyed by property name or id.
+     *
+     * Only `encryptedAttrs` is sent: the title and body keep the ciphertext,
+     * IV and salt they already had, so a property change can never damage a
+     * body nobody asked to change.
+     *
+     * When `createOption` invents an option for a select or multiSelect, the
+     * definition carrying it is written to the folder **before** the value that
+     * names it. Get that order wrong and a failure in between leaves a value
+     * pointing at an option id no definition carries, which reads as blank in
+     * the app and cannot be repaired from here. In this order the worst a
+     * failure between the two writes leaves behind is an option nobody uses
+     * yet, and repeating the same call finds that option by name, adds no
+     * duplicate, and writes the value.
+     */
+    setProperties(noteId: string, values: Record<string, unknown>, opts?: {
+        createOption?: boolean;
+    }): Promise<{
+        attrs: NoteAttrsV1;
+        applied: AppliedProp[];
+    }>;
     searchNotes(query: string, limit?: number): Promise<{
         results: Array<{
             id: string;
@@ -92,6 +255,10 @@ export declare class NotesService {
      * flip the switch in the app at any moment and the next tool call must
      * respect it. */
     private exposure;
+    /** 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). */
+    private exposureOf;
     /** Throws unless `folderId` is exposed to MCP. Every method that reads or
      * mutates a specific note (by id) must call this — knowing a note's id is
      * not consent to bypass the "Expose to MCP" folder switch. */
@@ -103,6 +270,45 @@ export declare class NotesService {
      * row. Legacy rows (no encryptedTitle) carry their real content directly
      * in the plaintext title/content columns. */
     private decryptRow;
+    /** Decode (with per-unlock caching) a note's attrs blob. Mirrors
+     * decryptRow()'s epoch guard: a decode still in flight when the vault
+     * locks resolves for its own caller but never lands in the cache. */
+    private decodeAttrsFor;
+    /** Decrypt (with per-unlock caching) just a note's title, without touching
+     * its body, the cheaper primitive backlinks() and mention-matching need. */
+    private decryptTitleFor;
+    /** The folder-visible, non-hidden rows a mention/backlink scan is allowed to
+     * see, same exposure rules as listNotes()/searchNotes(), bounded by
+     * SEARCH_SCAN_CAP for the same reason searchNotes() is. Accepts an
+     * already-computed `exposure` so a caller that has just checked it (as
+     * updateNote() has, for requireExposed()) does not pay for a second
+     * listFolders() round trip. */
+    private listVisibleRows;
+    /** Same guard as decryptRow(): a paging run that was still in flight when
+     * the vault locked must not seed the cache for the session that follows. */
+    private cacheVisibleRows;
+    /** Title entries for mention-matching against a note being saved: one entry
+     * per other folder-visible note's title, plus one more per alias in its
+     * attrs (an alias is another name mentions should recognize, same as the
+     * title). Titles come from decryptTitleFor() and aliases from
+     * decodeAttrsFor() (the same per-epoch caches backlinks() uses), so this
+     * costs no body decryption. */
+    private visibleTitles;
+    /** The folder a property tool was pointed at, refused unless it exists and
+     * the user has opened it to MCP. Knowing a folder id is no more consent
+     * than knowing a note id is (see requireExposed). */
+    private requireFolder;
+    /** Decode (with per-unlock caching) a folder's property definitions. A
+     * folder that has never had any decodes to an empty schema rather than
+     * null, so every caller can treat the two the same way. */
+    private decodeSchemaFor;
+    /** Encrypts a folder schema and enforces the server's size cap
+     * client-side, the way encodeAttrsChecked() does for a note's attrs. */
+    private encodeSchemaChecked;
+    /** Encrypts attrs and enforces the server's size cap client-side: an
+     * oversized blob is refused with a clear message rather than sent and
+     * bounced back as an HTTP 413 `ATTRS_TOO_LARGE`. */
+    private encodeAttrsChecked;
     private buildSnippet;
     private requireSession;
     /** Chains `fn` onto the mutation queue so overlapping calls run one at a