@melaya/runner 1.1.60 → 1.1.62

package/dist/vaults.js

@@ -0,0 +1,1130 @@
+/**
+ * Obsidian vault host — the runner side of docs/plans/obsidian-vault-protocol.md.
+ *
+ * A "device vault" is a folder on THIS computer, registered by the server for
+ * this runner's stable install id (rnr_…). The runner:
+ *   - keeps the registrations in ~/.melaya-runner/vaults/registry.json (0600)
+ *     and re-opens them on start (incremental re-index);
+ *   - indexes and serves them through a long-lived Python host (localVault.py,
+ *     the pure-Python engine from the shared bundle), index outside the vault
+ *     at ~/.melaya-runner/vaults/<vault_id>/index.sqlite;
+ *   - verifies every vault capability ITSELF (Ed25519, keys pushed with
+ *     runner:vaultKeys): signature, exp, aud, grant selection, read/write,
+ *     route policy, pushed revocations, folder bounds. The server relay is
+ *     not trusted to bypass any of it;
+ *   - answers server requests on the socket (runner:vault-*) and local agent
+ *     requests on the local relay (POST /vaults/op), forwarding every vault it
+ *     does not hold to {server}/api/v1/vault-api/op.
+ *
+ * Never logged: capability tokens, note content, op arguments.
+ */
+import { createPublicKey, verify as cryptoVerify, randomBytes } from "crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, watch as fsWatch, writeFileSync, } from "fs";
+import { spawn } from "child_process";
+import { homedir, platform as osPlatform } from "os";
+import path from "path";
+import { Readable } from "stream";
+import { APP_DEV_OPS, APP_ONLY_OPS, APP_WRITE_OPS } from "./obsidianApp.js";
+import { VaultMirrorManager, mirrorApiBase } from "./vaultMirror.js";
+// ── Wire contract ─────────────────────────────────────────────────────────
+export const VAULT_HOST_CAPABILITY = "vault_host_v1";
+/** Engine methods that change the vault. Everything else is a read. A write
+ *  needs "write" in the grant's ops; an unknown name stays a read here and the
+ *  Python host still refuses names that are not public engine methods. The
+ *  host applies the engine's own proposal in the same request (localVault.py
+ *  cmd_op), so the list must match its WRITE_OPS. */
+export const VAULT_WRITE_OPS = new Set([
+    "create", "append", "prepend", "patch", "move", "rename", "copy", "delete",
+    "property_set", "property_remove", "task", "daily_append", "daily_prepend",
+    "unique", "template_insert", "bookmark", "canvas_write", "base_create",
+    "upload",
+]);
+/** Engine methods no caller may name: `apply` / `resume_recovery` take a
+ *  caller-supplied proposal (forged bytes), the rest are host lifecycle. */
+export const VAULT_DENIED_OPS = new Set([
+    "apply", "resume_recovery", "refresh", "close", "capabilities_list",
+]);
+export function vaultErr(code, message) {
+    return { ok: false, error: { code, message, retry_after: null } };
+}
+const VAULT_ID_RE = /^vlt_[A-Za-z0-9]{1,64}$/;
+const OP_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+// A capability lives at most 10 minutes (protocol §1); a token claiming more
+// was not minted by our issuer. Small leeway for runner clock drift.
+const MAX_CAP_LIFETIME_S = 600;
+const CLOCK_SKEW_S = 30;
+const MAX_RELAY_BODY = 8 * 1024 * 1024;
+// ── Capability verification (protocol §1, §2 enforcement step 1) ─────────
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+/** kid → Ed25519 public key, from runner:vaultKeys {keys:[{kid, publicKeyRawB64}]}. */
+export function parseVaultKeys(keys) {
+    const out = new Map();
+    if (!Array.isArray(keys))
+        return out;
+    for (const k of keys) {
+        const kid = typeof k?.kid === "string" ? k.kid : "";
+        const b64 = typeof k?.publicKeyRawB64 === "string" ? k.publicKeyRawB64 : "";
+        if (!kid || !b64)
+            continue;
+        try {
+            const raw = Buffer.from(b64, "base64");
+            if (raw.length !== 32)
+                continue;
+            out.set(kid, createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: "der", type: "spki" }));
+        }
+        catch { /* skip a bad key, keep the others */ }
+    }
+    return out;
+}
+/** Decode the payload WITHOUT verifying it. Only for routing a local relay
+ *  request (local vs forward); every served request is fully verified. */
+export function decodeVaultCapUnverified(token) {
+    const parts = String(token || "").split(".");
+    if (parts.length !== 3 || parts[0] !== "v1")
+        return null;
+    try {
+        const p = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+        return p && typeof p === "object" && Array.isArray(p.grants) ? p : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Run and turn capabilities live as long as the run (up to 12 h, server
+// CAP_MAX_TTL_SECONDS). The server hands them to this runner over the
+// authenticated socket (run dispatch payload, per-turn connector env); only
+// those exact tokens may exceed MAX_CAP_LIFETIME_S, and only on the local relay.
+// Signature, expiry, audience and revocations are still checked on every op.
+const RUN_CAP_MAX_LIFETIME_S = 12 * 3600;
+const _trustedRunCaps = new Map();
+/** Record a run or turn capability received from the server for a local agent. */
+export function trustRunVaultCapability(token) {
+    if (!token)
+        return;
+    const p = decodeVaultCapUnverified(token);
+    const exp = Number(p?.exp);
+    if (!Number.isFinite(exp))
+        return;
+    const now = Math.floor(Date.now() / 1000);
+    for (const [t, e] of _trustedRunCaps)
+        if (e + CLOCK_SKEW_S < now)
+            _trustedRunCaps.delete(t);
+    _trustedRunCaps.set(token, exp);
+}
+export function isTrustedRunVaultCapability(token) {
+    return _trustedRunCaps.has(token);
+}
+/** Signature, version, kid, lifetime and audience. `audiences` is any-of. `maxLifetimeS` is raised only for
+ *  run/turn capabilities the server handed to this runner (see above). */
+export function verifyVaultCapability(token, keys, audiences, nowSec = Math.floor(Date.now() / 1000), maxLifetimeS = MAX_CAP_LIFETIME_S) {
+    const parts = String(token || "").split(".");
+    if (parts.length !== 3 || parts[0] !== "v1")
+        return { ok: false, code: "forbidden", reason: "malformed" };
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    }
+    catch {
+        return { ok: false, code: "forbidden", reason: "malformed" };
+    }
+    if (!payload || typeof payload !== "object" || payload.v !== 1)
+        return { ok: false, code: "forbidden", reason: "malformed" };
+    const key = keys.get(String(payload.kid || ""));
+    if (!key)
+        return { ok: false, code: "forbidden", reason: keys.size ? "kid_unknown" : "keys_missing" };
+    let sigOk = false;
+    try {
+        sigOk = cryptoVerify(null, Buffer.from(`v1.${parts[1]}`), key, Buffer.from(parts[2], "base64url"));
+    }
+    catch {
+        sigOk = false;
+    }
+    if (!sigOk)
+        return { ok: false, code: "forbidden", reason: "bad_signature" };
+    const exp = Number(payload.exp);
+    const iat = Number(payload.iat);
+    if (!Number.isFinite(exp) || exp + CLOCK_SKEW_S < nowSec)
+        return { ok: false, code: "forbidden", reason: "expired" };
+    if (!Number.isFinite(iat) || iat - CLOCK_SKEW_S > nowSec || exp - iat > maxLifetimeS + CLOCK_SKEW_S) {
+        return { ok: false, code: "forbidden", reason: "lifetime_invalid" };
+    }
+    const aud = Array.isArray(payload.aud) ? payload.aud : [];
+    if (!audiences.some((a) => aud.includes(a)))
+        return { ok: false, code: "forbidden", reason: "aud_mismatch" };
+    if (!Array.isArray(payload.grants))
+        return { ok: false, code: "forbidden", reason: "malformed" };
+    return { ok: true, payload };
+}
+/** `vault` = a vlt_ id in grants, or the exact case-insensitive label of exactly
+ *  one grant. Empty = the grant marked default, or the only grant. */
+export function selectVaultGrant(payload, vault) {
+    const grants = Array.isArray(payload.grants) ? payload.grants : [];
+    const want = String(vault ?? "").trim();
+    if (!want) {
+        const defaults = grants.filter((g) => g.default === true);
+        if (defaults.length === 1)
+            return { ok: true, grant: defaults[0] };
+        if (grants.length === 1)
+            return { ok: true, grant: grants[0] };
+        if (!grants.length)
+            return { ok: false, error: vaultErr("not_selected", "No vault is selected for this run.") };
+        return { ok: false, error: vaultErr("ambiguous", "Several vaults are selected; pass vault= with one of their labels.") };
+    }
+    const byId = grants.find((g) => g.vault_id === want);
+    if (byId)
+        return { ok: true, grant: byId };
+    const lower = want.toLowerCase();
+    const byLabel = grants.filter((g) => typeof g.label === "string" && g.label.toLowerCase() === lower);
+    if (byLabel.length === 1)
+        return { ok: true, grant: byLabel[0] };
+    if (byLabel.length > 1)
+        return { ok: false, error: vaultErr("ambiguous", "Several selected vaults share that label; pass the vault id.") };
+    return { ok: false, error: vaultErr("not_selected", "That vault is not selected for this run.") };
+}
+export function isVaultWriteOp(op) {
+    return VAULT_WRITE_OPS.has(op) || APP_WRITE_OPS.has(op);
+}
+// ── Revocations (runner:vaultRevoke) ──────────────────────────────────────
+/** vaultId+grantId → the minimum revocation_version still valid. A grant whose
+ *  capability carries an older version fails the next call, whatever the
+ *  token's remaining lifetime. Process memory only: a restarted runner relies
+ *  on the short capability lifetime plus the server re-pushing. */
+export class VaultRevocations {
+    min = new Map();
+    revoke(vaultId, grantId, revocationVersion) {
+        if (!vaultId || !grantId || !Number.isFinite(revocationVersion))
+            return;
+        const k = `${vaultId}\u0000${grantId}`;
+        this.min.set(k, Math.max(this.min.get(k) ?? -Infinity, revocationVersion));
+    }
+    isRevoked(g) {
+        const m = this.min.get(`${g.vault_id}\u0000${g.grant_id}`);
+        return m !== undefined && !(Number(g.revocation_version) >= m);
+    }
+}
+/** Steps 2-5 of the enforcement order for one already-verified capability.
+ *  Returns the grant to serve, or the error envelope. */
+export function authorizeVaultOp(payload, input, ctx) {
+    const pick = selectVaultGrant(payload, input.vault);
+    if (!pick.ok)
+        return pick;
+    const g = pick.grant;
+    if (!OP_NAME_RE.test(input.op || ""))
+        return { ok: false, error: vaultErr("invalid", "Unknown vault operation.") };
+    if (VAULT_DENIED_OPS.has(input.op))
+        return { ok: false, error: vaultErr("forbidden", `${input.op} cannot be called directly.`) };
+    const ops = Array.isArray(g.ops) ? g.ops : [];
+    if (isVaultWriteOp(input.op)) {
+        if (!ops.includes("write"))
+            return { ok: false, error: vaultErr("forbidden", "This vault is read-only for this run.") };
+    }
+    else if (!ops.includes("read") && !ops.includes("write")) {
+        return { ok: false, error: vaultErr("forbidden", "This run has no access to that vault.") };
+    }
+    // Developer tools (eval, dev:*) only when the owner turned them on (policy dev_tools).
+    if (APP_DEV_OPS.has(input.op) && g.dev_tools !== true) {
+        return { ok: false, error: vaultErr("forbidden", "Developer tools are off for this vault. The owner can turn them on in the vault's settings.") };
+    }
+    if (ctx.via === "server" && g.relay !== true) {
+        return { ok: false, error: vaultErr("policy_route", "The owner does not allow this vault's notes to transit Melaya; run it on this computer with a local model.") };
+    }
+    const models = Array.isArray(payload.models) ? payload.models : [];
+    if (g.external_models === false && models.includes("external")) {
+        return { ok: false, error: vaultErr("policy_route", "The owner does not allow this vault's notes to reach external model providers.") };
+    }
+    if (ctx.revocations.isRevoked(g))
+        return { ok: false, error: vaultErr("forbidden", "Access to this vault was revoked.") };
+    return { ok: true, grant: g };
+}
+function pathApi(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+function caseFold(platform, p) {
+    // NTFS and APFS are case-insensitive by default: compare folded.
+    return platform === "win32" || platform === "darwin" ? p.toLowerCase() : p;
+}
+function samePath(platform, a, b) {
+    const P = pathApi(platform);
+    return caseFold(platform, P.resolve(a)) === caseFold(platform, P.resolve(b));
+}
+/** True iff `child` is `parent` or inside it. */
+export function isInsidePath(platform, child, parent) {
+    const P = pathApi(platform);
+    const rel = P.relative(caseFold(platform, P.resolve(parent)), caseFold(platform, P.resolve(child)));
+    return rel === "" || (!rel.startsWith("..") && !P.isAbsolute(rel));
+}
+function systemFolders(platform, home) {
+    const P = pathApi(platform);
+    if (platform === "win32") {
+        const sysDrive = (process.env.SystemDrive || "C:") + "\\";
+        const env = (k, d) => process.env[k] || d;
+        return {
+            tree: [
+                env("SystemRoot", P.join(sysDrive, "Windows")),
+                env("ProgramFiles", P.join(sysDrive, "Program Files")),
+                env("ProgramFiles(x86)", P.join(sysDrive, "Program Files (x86)")),
+                env("ProgramData", P.join(sysDrive, "ProgramData")),
+                P.join(sysDrive, "$Recycle.Bin"),
+                P.join(sysDrive, "System Volume Information"),
+                P.join(sysDrive, "Recovery"),
+                P.join(home, "AppData"),
+            ],
+            exact: [],
+        };
+    }
+    const tree = ["/System", "/Library", "/usr", "/etc", "/bin", "/sbin", "/var", "/private", "/dev", "/proc", "/sys", "/boot", "/lib", "/lib64", "/opt", "/root", "/snap", "/Applications", "/cores"];
+    const exact = ["/Volumes", "/mnt", "/media", "/tmp", "/home", "/Users"];
+    if (platform === "darwin") {
+        // ~/Library holds iCloud Drive vaults (Mobile Documents), so only the
+        // folder itself and its credential stores are refused.
+        exact.push(P.join(home, "Library"), P.join(home, "Library", "Mobile Documents"));
+        tree.push(P.join(home, "Library", "Keychains"), P.join(home, "Library", "Application Support"));
+    }
+    return { tree, exact };
+}
+/** Pure check of an already-resolved real path. */
+export function checkVaultFolderPolicy(real, opts = {}) {
+    const platform = opts.platform ?? osPlatform();
+    const P = pathApi(platform);
+    const home = opts.home ?? homedir();
+    const runnerDir = opts.runnerDir ?? P.join(home, ".melaya-runner");
+    if (!real || !P.isAbsolute(real))
+        return "forbidden_path";
+    if (platform === "win32" && (/^\\\\/.test(real) || /^\/\//.test(real)))
+        return "forbidden_path"; // UNC / device paths
+    if (samePath(platform, real, P.parse(P.resolve(real)).root))
+        return "forbidden_path"; // a filesystem root
+    // The home folder itself and anything that contains it (C:\Users, /home).
+    if (isInsidePath(platform, home, real))
+        return "forbidden_path";
+    // The runner's own config, venv, shared bundle and vault indexes.
+    if (isInsidePath(platform, real, runnerDir) || isInsidePath(platform, runnerDir, real))
+        return "forbidden_path";
+    // Dot-folders directly under home (~/.ssh, ~/.aws, ~/.config, ...).
+    if (isInsidePath(platform, real, home)) {
+        const first = P.relative(P.resolve(home), P.resolve(real)).split(/[\\/]/)[0] || "";
+        if (first.startsWith("."))
+            return "forbidden_path";
+    }
+    const sys = systemFolders(platform, home);
+    for (const t of [...sys.tree, ...(opts.extraForbidden ?? [])])
+        if (isInsidePath(platform, real, t))
+            return "forbidden_path";
+    for (const e of sys.exact)
+        if (samePath(platform, real, e))
+            return "forbidden_path";
+    return null;
+}
+/** Resolve a picked folder to the real path the engine will serve, refusing
+ *  symlink / junction roots, non-directories and protected locations. */
+export function resolveVaultFolder(input, opts = {}) {
+    const platform = opts.platform ?? osPlatform();
+    const P = pathApi(platform);
+    const raw = String(input || "").trim();
+    if (!raw || raw.includes("\u0000") || !P.isAbsolute(raw))
+        return { ok: false, error: "forbidden_path" };
+    if (platform === "win32" && /^(\\\\|\/\/)/.test(raw))
+        return { ok: false, error: "forbidden_path" };
+    const abs = P.resolve(raw);
+    let st;
+    try {
+        st = lstatSync(abs);
+    }
+    catch {
+        return { ok: false, error: "not_a_folder" };
+    }
+    // lstat reports Windows junctions and mount points as symbolic links too.
+    if (st.isSymbolicLink())
+        return { ok: false, error: "forbidden_path" };
+    if (!st.isDirectory())
+        return { ok: false, error: "not_a_folder" };
+    let real;
+    try {
+        real = realpathSync.native(abs);
+    }
+    catch {
+        return { ok: false, error: "not_a_folder" };
+    }
+    let realHome = opts.home ?? homedir();
+    try {
+        realHome = realpathSync.native(realHome);
+    }
+    catch { /* keep as given */ }
+    const policy = checkVaultFolderPolicy(real, { ...opts, platform, home: realHome, runnerDir: opts.runnerDir ?? P.join(realHome, ".melaya-runner") });
+    if (policy)
+        return { ok: false, error: policy };
+    return { ok: true, real };
+}
+// ── Registry (~/.melaya-runner/vaults/registry.json) ─────────────────────
+export function defaultVaultsDir() {
+    return path.join(homedir(), ".melaya-runner", "vaults");
+}
+function cleanGlobs(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === "string" && x.length > 0 && x.length <= 512 && !x.includes("\u0000")).slice(0, 200);
+}
+/** Validate a registration coming from the server. Path policy is separate. */
+export function normalizeRegistration(v) {
+    const o = (v ?? {});
+    const id = typeof o.id === "string" ? o.id : "";
+    if (!VAULT_ID_RE.test(id))
+        return null;
+    const p = typeof o.path === "string" ? o.path : "";
+    if (!p)
+        return null;
+    let cfg = typeof o.configDirName === "string" && o.configDirName.trim() ? o.configDirName.trim() : ".obsidian";
+    // One plain folder name inside the vault, never a path.
+    if (cfg.length > 64 || /[\\/:\u0000]/.test(cfg) || cfg === "." || cfg === "..")
+        cfg = ".obsidian";
+    return {
+        id,
+        label: typeof o.label === "string" ? o.label.slice(0, 200) : id,
+        path: p,
+        configDirName: cfg,
+        include: cleanGlobs(o.include),
+        exclude: cleanGlobs(o.exclude),
+    };
+}
+export class VaultRegistry {
+    dir;
+    file;
+    vaults = new Map();
+    constructor(dir = defaultVaultsDir()) {
+        this.dir = dir;
+        this.file = path.join(dir, "registry.json");
+    }
+    load() {
+        this.vaults.clear();
+        try {
+            if (!existsSync(this.file))
+                return;
+            const parsed = JSON.parse(readFileSync(this.file, "utf-8"));
+            for (const v of Array.isArray(parsed?.vaults) ? parsed.vaults : []) {
+                const reg = normalizeRegistration(v);
+                if (reg)
+                    this.vaults.set(reg.id, reg);
+            }
+        }
+        catch { /* a corrupt registry is rebuilt by the next server register */ }
+    }
+    list() { return Array.from(this.vaults.values()); }
+    get(id) { return this.vaults.get(id); }
+    upsert(reg) {
+        this.vaults.set(reg.id, reg);
+        this.save();
+    }
+    remove(id) {
+        const had = this.vaults.delete(id);
+        if (had)
+            this.save();
+        return had;
+    }
+    /** Index folder of one vault (outside the vault). */
+    indexDir(id) {
+        if (!VAULT_ID_RE.test(id))
+            throw new Error("bad vault id");
+        return path.join(this.dir, id);
+    }
+    save() {
+        mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify({ vaults: this.list() }, null, 2), { encoding: "utf-8", mode: 0o600 });
+        renameSync(tmp, this.file);
+        try {
+            chmodSync(this.file, 0o600);
+        }
+        catch { /* not supported on this FS */ }
+    }
+}
+/** Per-runner HMAC key for engine cursors (stable across host restarts). */
+function loadCursorKey(dir) {
+    const f = path.join(dir, "cursor.key");
+    try {
+        const v = readFileSync(f, "utf-8").trim();
+        if (/^[a-f0-9]{64}$/.test(v))
+            return v;
+    }
+    catch { /* create below */ }
+    const fresh = randomBytes(32).toString("hex");
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(f, fresh, { encoding: "utf-8", mode: 0o600 });
+    }
+    catch { /* in-memory for this process */ }
+    return fresh;
+}
+/** JSON-lines RPC to one long-lived `python -u localVault.py`, started lazily
+ *  and restarted with backoff when it dies while vaults are registered. */
+export class VaultHostProcess {
+    o;
+    proc = null;
+    starting = null;
+    seq = 0;
+    buf = "";
+    pending = new Map();
+    eventCbs = [];
+    restartCbs = [];
+    backoffMs = 1000;
+    stopped = false;
+    spawns = 0;
+    restartTimer = null;
+    stderrTail = [];
+    constructor(o) {
+        this.o = o;
+    }
+    onEvent(cb) { this.eventCbs.push(cb); }
+    onRestart(cb) { this.restartCbs.push(cb); }
+    async ensure() {
+        if (this.proc && this.proc.exitCode === null && !this.proc.killed)
+            return this.proc;
+        if (this.starting)
+            return this.starting;
+        this.starting = (async () => {
+            const l = await this.o.launch();
+            const p = spawn(l.pythonPath, ["-u", l.scriptPath], { env: l.env, cwd: l.cwd, stdio: ["pipe", "pipe", "pipe"] });
+            // EPIPE after a crash surfaces here; the exit handler does the cleanup.
+            p.stdin?.on("error", () => { });
+            p.stdout?.setEncoding("utf-8");
+            p.stdout?.on("data", (d) => this.onStdout(d));
+            p.stderr?.on("data", (d) => {
+                for (const line of d.toString("utf-8").split(/\r?\n/)) {
+                    if (!line.trim())
+                        continue;
+                    this.stderrTail.push(line.slice(0, 300));
+                    if (this.stderrTail.length > 20)
+                        this.stderrTail.shift();
+                    this.o.log?.(`host: ${line.slice(0, 300)}`);
+                }
+            });
+            p.on("error", (e) => this.onExit(p, `spawn failed: ${e.message}`));
+            p.on("exit", (code) => this.onExit(p, `exited ${code ?? "?"}`));
+            this.proc = p;
+            // A fresh process after a crash knows no vault: let the service
+            // re-register them (requests that race this are retried by the service).
+            if (++this.spawns > 1) {
+                setImmediate(() => { for (const cb of this.restartCbs) {
+                    try {
+                        cb();
+                    }
+                    catch { /* listener bug */ }
+                } });
+            }
+            return p;
+        })();
+        try {
+            return await this.starting;
+        }
+        finally {
+            this.starting = null;
+        }
+    }
+    onStdout(d) {
+        this.buf += d;
+        if (this.buf.length > 64 * 1024 * 1024)
+            this.buf = ""; // OOM backstop
+        let i;
+        while ((i = this.buf.indexOf("\n")) >= 0) {
+            const line = this.buf.slice(0, i).trim();
+            this.buf = this.buf.slice(i + 1);
+            if (!line.startsWith("{"))
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (msg?.event === "status" && typeof msg.vaultId === "string") {
+                const { event: _e, ...ev } = msg;
+                for (const cb of this.eventCbs) {
+                    try {
+                        cb(ev);
+                    }
+                    catch { /* listener bug */ }
+                }
+                continue;
+            }
+            if (msg?.event === "ready") {
+                this.backoffMs = 1000;
+                continue;
+            }
+            const entry = typeof msg?.id === "string" ? this.pending.get(msg.id) : undefined;
+            if (!entry)
+                continue;
+            this.pending.delete(msg.id);
+            clearTimeout(entry.timer);
+            if (msg.ok === true)
+                entry.resolve(msg.result);
+            else
+                entry.reject(new Error(String(msg.error || "host_error").slice(0, 300)));
+        }
+    }
+    onExit(p, why) {
+        if (this.proc !== p)
+            return;
+        this.proc = null;
+        this.buf = "";
+        for (const [id, e] of this.pending) {
+            clearTimeout(e.timer);
+            e.reject(new Error("vault_host_crashed"));
+            this.pending.delete(id);
+        }
+        if (this.stopped)
+            return;
+        this.o.log?.(`vault host ${why}`);
+        if (!this.o.wanted() || this.restartTimer)
+            return;
+        const delay = this.backoffMs;
+        this.backoffMs = Math.min(60_000, this.backoffMs * 2);
+        this.restartTimer = setTimeout(() => {
+            this.restartTimer = null;
+            if (this.stopped || !this.o.wanted())
+                return;
+            this.ensure().catch((e) => this.o.log?.(`vault host restart failed: ${e?.message || e}`));
+        }, delay);
+        this.restartTimer.unref?.();
+    }
+    async request(cmd, payload, timeoutMs = 60_000) {
+        const p = await this.ensure();
+        const id = `v${++this.seq}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error("vault_host_timeout"));
+            }, timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+            try {
+                p.stdin?.write(JSON.stringify({ id, cmd, ...payload }) + "\n");
+            }
+            catch (e) {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(new Error(`vault_host_write_failed: ${e?.message || e}`));
+            }
+        });
+    }
+    stop() {
+        this.stopped = true;
+        if (this.restartTimer)
+            clearTimeout(this.restartTimer);
+        try {
+            this.proc?.stdin?.end();
+        }
+        catch { /* gone */ }
+        const p = this.proc;
+        if (p)
+            setTimeout(() => { try {
+                p.kill();
+            }
+            catch { /* gone */ } }, 2000).unref?.();
+    }
+}
+const WATCH_DEBOUNCE_MS = 1500;
+const WATCH_MAX_PATHS = 2000;
+export class VaultService {
+    o;
+    keys = new Map();
+    revocations = new VaultRevocations();
+    cursorKey;
+    watchers = new Map();
+    lastStatus = new Map();
+    /** Cloud copy of `storage: mirror` vaults (vaultMirror.ts, plan §6.4 S4). */
+    mirror;
+    mirrorSink = null;
+    constructor(o) {
+        this.o = o;
+        this.cursorKey = loadCursorKey(o.registry.dir);
+        this.mirror = new VaultMirrorManager({
+            host: o.host,
+            isRegistered: (id) => !!o.registry.get(id),
+            apiBase: (id) => mirrorApiBase(o.serverHttpBase, id),
+            emit: (event, payload) => this.mirrorSink?.(event, payload),
+            log: o.log,
+            timers: o.watch !== false,
+        });
+        o.host.onEvent((ev) => {
+            if (!o.registry.get(ev.vaultId))
+                return; // a late event for an unregistered vault
+            this.lastStatus.set(ev.vaultId, ev);
+            o.emitStatus?.(ev);
+            this.mirror.onIndexStatus(ev);
+        });
+        o.host.onRestart(() => { void this.restore(); });
+    }
+    /** Where mirror renew requests and statuses go (the runner socket). */
+    setMirrorSink(sink) {
+        this.mirrorSink = sink;
+    }
+    get rnrId() { return this.o.rnrId; }
+    hasKeys() { return this.keys.size > 0; }
+    /** runner:vaultKeys — replaces the key set (the server sends all current kids). */
+    setKeys(keys) {
+        const parsed = parseVaultKeys(keys);
+        if (parsed.size)
+            this.keys = parsed;
+    }
+    /** runner:vaultRevoke */
+    revoke(p) {
+        this.revocations.revoke(String(p?.vaultId || ""), String(p?.grantId || ""), Number(p?.revocationVersion));
+    }
+    /** Statuses to re-send after a reconnect. */
+    latestStatuses() { return Array.from(this.lastStatus.values()); }
+    hostRegisterPayload(reg) {
+        const dir = this.o.registry.indexDir(reg.id);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        return {
+            vault: {
+                id: reg.id,
+                label: reg.label,
+                root: reg.path,
+                configDirName: reg.configDirName,
+                include: reg.include,
+                exclude: reg.exclude,
+                indexPath: path.join(dir, "index.sqlite"),
+            },
+            cursorKey: this.cursorKey,
+        };
+    }
+    /** runner:vault-register */
+    async register(input) {
+        const reg = normalizeRegistration(input);
+        if (!reg)
+            return { ok: false, error: "invalid" };
+        const folder = resolveVaultFolder(reg.path, this.o.folderPolicy);
+        if (!folder.ok)
+            return { ok: false, error: folder.error };
+        const resolved = { ...reg, path: folder.real };
+        let data;
+        try {
+            data = await this.o.host.request("register", this.hostRegisterPayload(resolved), 30 * 60_000);
+        }
+        catch (e) {
+            return { ok: false, error: String(e?.message || "vault_host_failed").slice(0, 300) };
+        }
+        this.o.registry.upsert(resolved);
+        this.startWatch(resolved);
+        const out = {
+            notes: Number(data?.notes) || 0,
+            bytes: Number(data?.bytes) || 0,
+            indexRev: Number(data?.indexRev) || 0,
+            capabilities: await this.withAppCapabilities(resolved, data?.capabilities),
+        };
+        this.lastStatus.set(reg.id, { vaultId: reg.id, status: "ready", ...out });
+        return { ok: true, data: out };
+    }
+    /** runner:vault-unregister — also deletes the derived index (it holds note text). */
+    async unregister(vaultId) {
+        const id = String(vaultId || "");
+        if (!VAULT_ID_RE.test(id))
+            return { ok: false, error: "invalid" };
+        this.stopWatch(id);
+        this.lastStatus.delete(id);
+        this.mirror.forget(id);
+        const had = this.o.registry.get(id);
+        this.o.registry.remove(id);
+        if (had) {
+            try {
+                await this.o.host.request("unregister", { vaultId: id }, 30_000);
+            }
+            catch { /* host gone: nothing open */ }
+        }
+        try {
+            const dir = this.o.registry.indexDir(id);
+            if (isInsidePath(process.platform, dir, this.o.registry.dir) && !samePath(process.platform, dir, this.o.registry.dir)) {
+                rmSync(dir, { recursive: true, force: true });
+            }
+        }
+        catch { /* best-effort */ }
+        return { ok: true, data: { removed: !!had } };
+    }
+    /** Re-open every registered vault (startup, host restart). */
+    async restore() {
+        for (const reg of this.o.registry.list()) {
+            const folder = resolveVaultFolder(reg.path, this.o.folderPolicy);
+            if (!folder.ok) {
+                const ev = { vaultId: reg.id, status: "error", error: folder.error };
+                this.lastStatus.set(reg.id, ev);
+                this.o.emitStatus?.(ev);
+                continue;
+            }
+            try {
+                const data = await this.o.host.request("register", this.hostRegisterPayload({ ...reg, path: folder.real }), 30 * 60_000);
+                const ev = { vaultId: reg.id, status: "ready", notes: Number(data?.notes) || 0, bytes: Number(data?.bytes) || 0, indexRev: Number(data?.indexRev) || 0, capabilities: await this.withAppCapabilities({ ...reg, path: folder.real }, data?.capabilities) };
+                this.lastStatus.set(reg.id, ev);
+                this.o.emitStatus?.(ev);
+                this.startWatch({ ...reg, path: folder.real });
+            }
+            catch (e) {
+                const ev = { vaultId: reg.id, status: "error", error: String(e?.message || "vault_host_failed").slice(0, 300) };
+                this.lastStatus.set(reg.id, ev);
+                this.o.emitStatus?.(ev);
+            }
+        }
+    }
+    /** Verify a capability and serve one op for a vault held on THIS runner. */
+    async op(input, via) {
+        const audiences = via === "server" ? [`runner:${this.o.rnrId}`, "vault-api"] : [`runner:${this.o.rnrId}`];
+        const token = String(input.capability || "");
+        const maxLife = via === "local" && isTrustedRunVaultCapability(token) ? RUN_CAP_MAX_LIFETIME_S : undefined;
+        const cap = verifyVaultCapability(token, this.keys, audiences, undefined, maxLife);
+        if (!cap.ok)
+            return vaultErr(cap.code, `The vault capability was refused (${cap.reason}).`);
+        const op = String(input.op || "");
+        const auth = authorizeVaultOp(cap.payload, { vault: input.vault, op }, { via, revocations: this.revocations });
+        if (!auth.ok)
+            return auth.error;
+        const g = auth.grant;
+        if (g.source !== "device" || g.rnr_id !== this.o.rnrId) {
+            return vaultErr("forbidden", "That vault is not held by this computer.");
+        }
+        if (!this.o.registry.get(g.vault_id)) {
+            return vaultErr("not_found", "That vault is not registered on this computer; reconnect it in Melaya.");
+        }
+        let args = (input.args && typeof input.args === "object" && !Array.isArray(input.args) ? input.args : {});
+        const idem = typeof input.idempotency_key === "string" ? input.idempotency_key.slice(0, 200) : null;
+        // App ops (obsidianApp.ts): through the user's running Obsidian, or back
+        // to the files engine for a Files+App op when the app is not reachable.
+        const reg = this.o.registry.get(g.vault_id);
+        const appGrant = { ops: g.ops, folders: Array.isArray(g.folders) ? g.folders : [], dev_tools: g.dev_tools === true };
+        if (this.o.app) {
+            const served = await this.o.app.serve({ reg, grant: appGrant, op, args, idempotencyKey: idem }).catch(() => null);
+            if (served?.kind === "env")
+                return served.env;
+            if (served?.kind === "files")
+                args = served.args;
+        }
+        else if (APP_ONLY_OPS.has(op)) {
+            return vaultErr("unsupported", "This runner cannot reach the Obsidian app; update the Melaya runner.");
+        }
+        const env = await this.hostOp(g, op, args, idem);
+        if (this.o.app && op === "base_query") {
+            const viaApp = await this.o.app.afterFiles({ reg, grant: appGrant, op, args }, env).catch(() => null);
+            if (viaApp)
+                return viaApp;
+        }
+        if (this.o.app && op === "capabilities" && env.ok) {
+            const st = await this.o.app.status(reg).catch(() => null);
+            if (st) {
+                const e = env;
+                if (Array.isArray(e.items))
+                    e.items = [...e.items, ...st.features];
+                e.app = { cli: st.cli, rest: st.rest, version: st.version, features: st.features };
+            }
+        }
+        return env;
+    }
+    /** One engine op on the Python host (re-registers once after a host restart). */
+    async hostOp(g, op, args, idem) {
+        const req = {
+            vaultId: g.vault_id,
+            op,
+            args,
+            folders: Array.isArray(g.folders) ? g.folders.filter((f) => typeof f === "string") : [],
+            write: isVaultWriteOp(op),
+            idempotency_key: idem,
+        };
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                const env = await this.o.host.request("op", req, 110_000);
+                if (env && typeof env === "object" && typeof env.ok === "boolean")
+                    return env;
+                return vaultErr("invalid", "The vault host returned an empty answer.");
+            }
+            catch (e) {
+                const m = String(e?.message || "");
+                // A host that restarted since registration does not know the vault
+                // yet: re-open it once and retry.
+                if (m === "unknown_vault" && attempt === 0) {
+                    const reg = this.o.registry.get(g.vault_id);
+                    const folder = reg ? resolveVaultFolder(reg.path, this.o.folderPolicy) : null;
+                    if (!reg || !folder?.ok)
+                        return vaultErr("not_found", "That vault's folder is no longer available on this computer.");
+                    try {
+                        await this.o.host.request("register", this.hostRegisterPayload({ ...reg, path: folder.real }), 30 * 60_000);
+                    }
+                    catch {
+                        return vaultErr("vault_offline", "The vault host on this computer could not reopen the vault.");
+                    }
+                    continue;
+                }
+                if (m === "vault_host_timeout")
+                    return vaultErr("vault_offline", "The vault host on this computer did not answer in time.");
+                return vaultErr("vault_offline", "The vault host on this computer is not running; it restarts automatically.");
+            }
+        }
+        return vaultErr("vault_offline", "The vault host on this computer could not serve the request.");
+    }
+    /** Merge the Obsidian app's availability into a vault's capability report
+     *  (stored by the server as agents.vaults.capabilities). */
+    async withAppCapabilities(reg, caps) {
+        const base = caps && typeof caps === "object" && !Array.isArray(caps) ? { ...caps } : {};
+        if (!this.o.app)
+            return base;
+        const st = await this.o.app.status(reg).catch(() => null);
+        if (!st)
+            return base;
+        return { ...base, app_bridge: st.features.length > 0, app: { cli: st.cli, rest: st.rest, version: st.version, features: st.features } };
+    }
+    /** runner:vault-app — the owner's vault settings asking about / connecting
+     *  the Obsidian app on this computer. The Local REST API key is read from
+     *  the plugin's own settings HERE and stays here: only states and a short
+     *  certificate fingerprint go back. */
+    async appControl(p) {
+        const id = String(p?.vaultId || "");
+        if (!VAULT_ID_RE.test(id))
+            return { ok: false, error: "invalid" };
+        const reg = this.o.registry.get(id);
+        if (!reg)
+            return { ok: false, error: "not_registered" };
+        if (!this.o.app)
+            return { ok: false, error: "app_bridge_unavailable" };
+        const action = String(p?.action || "status");
+        const pub = (s) => ({
+            cli: s.cli, rest: s.rest, version: s.version, features: s.features, restFingerprint: s.restFingerprint,
+        });
+        if (action === "status") {
+            this.o.app.invalidate();
+            return { ok: true, data: pub(await this.o.app.status(reg)) };
+        }
+        if (action === "connect_rest") {
+            const r = await this.o.app.connectRest(reg);
+            return r.ok ? { ok: true, data: pub(r.status) } : { ok: false, error: r.error };
+        }
+        if (action === "disconnect_rest") {
+            this.o.app.disconnectRest(id);
+            return { ok: true, data: pub(await this.o.app.status(reg)) };
+        }
+        return { ok: false, error: "invalid" };
+    }
+    /** True iff a relay request targets a device vault held by this runner. */
+    isLocalTarget(capability, vault) {
+        const p = decodeVaultCapUnverified(capability);
+        if (!p)
+            return false;
+        const pick = selectVaultGrant(p, typeof vault === "string" ? vault : "");
+        return pick.ok && pick.grant.source === "device" && pick.grant.rnr_id === this.o.rnrId;
+    }
+    /** POST /vaults/op on the local relay (127.0.0.1). */
+    async handleRelayHttp(req, res) {
+        const send = (status, body) => {
+            if (res.headersSent)
+                return;
+            res.writeHead(status, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(body));
+        };
+        const chunks = [];
+        let size = 0;
+        let tooBig = false;
+        try {
+            for await (const c of req) {
+                size += c.length;
+                if (size > MAX_RELAY_BODY) {
+                    tooBig = true;
+                    break;
+                }
+                chunks.push(c);
+            }
+        }
+        catch {
+            return send(400, { ok: false, error: "read_failed" });
+        }
+        if (tooBig)
+            return send(413, { ok: false, error: "too_large" });
+        const raw = Buffer.concat(chunks);
+        const h = String(req.headers.authorization || "");
+        const capability = h.startsWith("Vault ") ? h.slice(6).trim() : "";
+        if (!capability)
+            return send(401, { ok: false, error: "missing_capability" });
+        let body;
+        try {
+            body = JSON.parse(raw.toString("utf-8") || "{}");
+        }
+        catch {
+            return send(400, { ok: false, error: "invalid_json" });
+        }
+        if (!body || typeof body !== "object")
+            return send(400, { ok: false, error: "invalid_json" });
+        if (this.isLocalTarget(capability, body.vault)) {
+            const env = await this.op({ capability, op: body.op, vault: body.vault, args: body.args, idempotency_key: body.idempotency_key }, "local");
+            return send(200, env);
+        }
+        // Not ours: forward the identical request to the server's public Vault API.
+        const doFetch = this.o.fetchImpl ?? fetch;
+        try {
+            const r = await doFetch(`${this.o.serverHttpBase.replace(/\/+$/, "")}/api/v1/vault-api/op`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Vault ${capability}` },
+                body: raw,
+                signal: AbortSignal.timeout(125_000),
+            });
+            res.writeHead(r.status, { "Content-Type": r.headers.get("content-type") || "application/json" });
+            if (!r.body) {
+                res.end();
+                return;
+            }
+            await new Promise((resolve) => {
+                const s = Readable.fromWeb(r.body);
+                s.on("error", () => { try {
+                    res.end();
+                }
+                catch { /* closed */ } resolve(); });
+                s.on("end", () => resolve());
+                s.pipe(res);
+            });
+        }
+        catch (e) {
+            send(502, { ok: false, error: e?.name === "TimeoutError" ? "timeout" : "server_unreachable" });
+        }
+    }
+    // ── change detection (plan §6.4: fs.watch → debounced queue) ──────────
+    // The Python host also runs a periodic stat-only reconciliation (10 min),
+    // which covers watcher overflow, sleep and platforms without recursive
+    // fs.watch (Linux on Node < 20).
+    startWatch(reg) {
+        this.stopWatch(reg.id);
+        if (this.o.watch === false)
+            return;
+        const st = { w: null, paths: new Set(), full: false, timer: null };
+        this.watchers.set(reg.id, st);
+        const flush = () => {
+            st.timer = null;
+            const paths = st.full ? null : Array.from(st.paths);
+            st.paths.clear();
+            st.full = false;
+            this.o.host.request("changed", { vaultId: reg.id, paths }, 10 * 60_000).catch(() => { });
+        };
+        try {
+            st.w = fsWatch(reg.path, { recursive: true, persistent: false }, (_ev, filename) => {
+                const name = filename ? String(filename).replace(/\\/g, "/") : "";
+                // Dot entries (the config folder's workspace.json changes constantly,
+                // .git, .trash) are invisible to the engine anyway.
+                if (name && name.split("/").some((s) => s.startsWith(".")))
+                    return;
+                if (!name || st.paths.size >= WATCH_MAX_PATHS)
+                    st.full = true;
+                else
+                    st.paths.add(name);
+                if (!st.timer) {
+                    st.timer = setTimeout(flush, WATCH_DEBOUNCE_MS);
+                    st.timer.unref?.();
+                }
+            });
+            st.w.on("error", () => {
+                try {
+                    st.w?.close();
+                }
+                catch { /* closed */ }
+                st.w = null;
+                st.full = true;
+                if (!st.timer) {
+                    st.timer = setTimeout(flush, WATCH_DEBOUNCE_MS);
+                    st.timer.unref?.();
+                }
+            });
+        }
+        catch {
+            st.w = null; // no recursive watch here: the host's reconciliation covers it
+        }
+    }
+    stopWatch(id) {
+        const st = this.watchers.get(id);
+        if (!st)
+            return;
+        if (st.timer)
+            clearTimeout(st.timer);
+        try {
+            st.w?.close();
+        }
+        catch { /* closed */ }
+        this.watchers.delete(id);
+    }
+    stop() {
+        for (const id of Array.from(this.watchers.keys()))
+            this.stopWatch(id);
+        this.mirror.stop();
+        this.o.host.stop();
+    }
+}
+/** Wire the server → runner vault events. Every request is answered with
+ *  runner:vault-result {requestId, ok, data | envelope | error}. */
+export function attachVaultSocketHandlers(socket, service, pickFolder) {
+    const reply = (requestId, r) => {
+        if (typeof requestId !== "string" || !requestId)
+            return;
+        socket.emit("runner:vault-result", { requestId, ...r });
+    };
+    socket.on("runner:vaultKeys", (p) => service.setKeys(p?.keys));
+    socket.on("runner:vaultRevoke", (p) => service.revoke(p ?? {}));
+    // Cloud copy (storage: mirror): the server pushes a mirror capability per
+    // vault on enable and on every hello; renewals and statuses go back here.
+    service.setMirrorSink((event, payload) => { socket.emit(event, payload); });
+    socket.on("runner:vault-mirror", (p) => {
+        service.mirror.setGrant(p ?? {});
+    });
+    socket.on("runner:vault-register", async (p) => {
+        reply(p?.requestId, await service.register(p?.vault).catch((e) => ({ ok: false, error: String(e?.message || "register_failed").slice(0, 300) })));
+    });
+    socket.on("runner:vault-unregister", async (p) => {
+        reply(p?.requestId, await service.unregister(p?.vaultId).catch((e) => ({ ok: false, error: String(e?.message || "unregister_failed").slice(0, 300) })));
+    });
+    socket.on("runner:vault-op", async (p) => {
+        // The runner verifies the capability itself; the server is not trusted
+        // to bypass it. Refusals travel as an error envelope (ok:true transport).
+        const envelope = await service.op(p ?? {}, "server").catch(() => vaultErr("vault_offline", "The vault host failed."));
+        reply(p?.requestId, { ok: true, envelope });
+    });
+    socket.on("runner:vault-app", async (p) => {
+        reply(p?.requestId, await service.appControl(p ?? {}).catch((e) => ({ ok: false, error: String(e?.message || "app_failed").slice(0, 300) })));
+    });
+    socket.on("runner:vault-pick-folder", async (p) => {
+        try {
+            reply(p?.requestId, { ok: true, data: await pickFolder() });
+        }
+        catch (e) {
+            reply(p?.requestId, { ok: false, error: String(e?.message || "pick failed").slice(0, 300) });
+        }
+    });
+}
+// ── Tool env for runner-hosted agents ─────────────────────────────────────
+let _relayPort = 0;
+/** Called once the local relay is listening (connection.ts). */
+export function setVaultRelayPort(port) {
+    _relayPort = port;
+}
+/**
+ * Env a runner-hosted agent needs to call vault tools (protocol §5): the
+ * capability and the LOCAL relay URL, which serves this computer's vaults
+ * in-process and forwards every other vault to the server.
+ *
+ * Must be merged LAST into the subprocess env (after payload.credentials, so a
+ * credential named MEL_VAULT_* can never replace it) by:
+ *   - the pipeline spawn in connection.ts `runner:run` (the env object built
+ *     next to `PYTHONPATH: sharedDir` / MEL_STUDIO_URL), from the run payload's
+ *     capability;
+ *   - the assistant host, per turn, in `runner:assistant_turn` (the turn's
+ *     capability; the host is long-lived, so the value rides the turn frame,
+ *     not the boot env built by `buildAssistantEnv`).
+ * Returns {} when there is no capability or the relay is not up yet.
+ */
+export function vaultToolEnv(capability, relayPort = _relayPort) {
+    if (!capability || !relayPort)
+        return {};
+    return {
+        MEL_VAULT_CAP: capability,
+        MEL_VAULT_API_URL: `http://127.0.0.1:${relayPort}/vaults`,
+    };
+}
+/** Locate localVault.py next to the compiled module (dist/) or one level up (src tree). */
+export function findVaultHostScript(baseDir) {
+    for (const c of [path.join(baseDir, "localVault.py"), path.join(baseDir, "..", "localVault.py")]) {
+        try {
+            if (statSync(c).isFile())
+                return c;
+        }
+        catch { /* next */ }
+    }
+    return null;
+}