@ricsam/r5d-browser 0.0.137 → 0.0.138

package/dist/mjs/runtime/isolated-root.mjs

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { RuntimeId, canonicalJson } from "@ricsam/r5d-api/runtime-protocol";
+import { assertPrivatePath, makePrivateDirectory, readPrivateFile } from "./private-paths.mjs";
+import { BrowserKeeperError } from "./protocol.mjs";
+function isolatedBrowserRoot(root, installationId, userId) {
+  RuntimeId.parse(installationId);
+  RuntimeId.parse(userId);
+  assertPrivatePath(root, "directory");
+  if (Buffer.byteLength(root) > 48) throw new BrowserKeeperError("browser_root_path_too_long");
+  const marker = path.join(root, "browser-keeper-root.json");
+  const identity = canonicalJson({ version: 1, purpose: "isolated-chromium-keeper", installationId, userId });
+  if (!fs.existsSync(marker)) {
+    if (fs.readdirSync(root).length !== 0) throw new BrowserKeeperError("root_not_empty");
+    const fd = fs.openSync(marker, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 256);
+    try {
+      fs.writeFileSync(fd, identity);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    const parent = fs.openSync(root, fs.constants.O_RDONLY);
+    try {
+      fs.fsyncSync(parent);
+    } finally {
+      fs.closeSync(parent);
+    }
+  }
+  if (readPrivateFile(marker, 2048, true).toString("utf8") !== identity) throw new BrowserKeeperError("wrong_root_identity");
+  const ledger = path.join(root, "ledger");
+  const runs = path.join(root, "runs");
+  makePrivateDirectory(ledger);
+  makePrivateDirectory(runs);
+  return { ledger, runs };
+}
+function freshBrowserRun(runs) {
+  assertPrivatePath(runs, "directory");
+  if (fs.readdirSync(runs).length >= 32) throw new BrowserKeeperError("browser_run_capacity");
+  const id = randomUUID();
+  const directory = path.join(runs, id);
+  fs.mkdirSync(directory, { mode: 448 });
+  const profile = path.join(directory, "profile");
+  const downloads = path.join(directory, "downloads");
+  const uploads = path.join(directory, "uploads");
+  const home = path.join(directory, "home");
+  for (const child of [profile, downloads, uploads, home]) fs.mkdirSync(child, { mode: 448 });
+  return { id, directory, profile, downloads, uploads, home };
+}
+export {
+  freshBrowserRun,
+  isolatedBrowserRoot
+};

package/dist/mjs/runtime/keeper.mjs

@@ -0,0 +1,169 @@
+import {
+  canonicalJson,
+  negotiateProtocol,
+  operationPayloadHash,
+  RuntimeHello,
+  RUNTIME_PROTOCOL
+} from "@ricsam/r5d-api/runtime-protocol";
+import { BrowserLedger } from "./ledger.mjs";
+import { BROWSER_KEEPER_CAPABILITY, BrowserKeeperError, BrowserKeeperMessage, BrowserOperation } from "./protocol.mjs";
+class BrowserKeeper {
+  hello;
+  ledger;
+  executor;
+  inFlight = /* @__PURE__ */ new Map();
+  queues = /* @__PURE__ */ new Map();
+  maxInFlight;
+  maxPayloadBytes;
+  pruneTimer;
+  closing = false;
+  closePromise;
+  storageFailed = false;
+  constructor(options) {
+    this.hello = RuntimeHello.parse({
+      installationId: options.installationId,
+      instanceId: options.instanceId,
+      releaseId: options.releaseId,
+      role: "keeper",
+      protocol: { min: RUNTIME_PROTOCOL, max: RUNTIME_PROTOCOL },
+      capabilities: [BROWSER_KEEPER_CAPABILITY]
+    });
+    this.maxInFlight = options.maxInFlight ?? 128;
+    this.maxPayloadBytes = options.maxPayloadBytes ?? 2 * 1024 * 1024;
+    if (![this.maxInFlight, this.maxPayloadBytes].every((value) => Number.isSafeInteger(value) && value > 0)) {
+      throw new BrowserKeeperError("invalid_limits");
+    }
+    this.ledger = new BrowserLedger(options);
+    this.executor = options.executor;
+    this.pruneTimer = setInterval(
+      () => {
+        try {
+          this.ledger.prune();
+        } catch {
+          this.storageFailed = true;
+        }
+      },
+      Math.min(options.retentionMs ?? 6e4, 6e4)
+    );
+    this.pruneTimer.unref();
+  }
+  /** Callable versioned boundary. Transport disconnect is deliberately not an AbortSignal. */
+  async handle(input, principal) {
+    try {
+      return await this.handleRequest(input, principal);
+    } catch (error) {
+      if (error instanceof BrowserKeeperError) throw error;
+      this.storageFailed = true;
+      throw new BrowserKeeperError("storage_unavailable");
+    }
+  }
+  async handleRequest(input, principal) {
+    if (this.closing) throw new BrowserKeeperError("keeper_draining");
+    if (this.storageFailed) throw new BrowserKeeperError("storage_unavailable");
+    const parsed = BrowserKeeperMessage.safeParse(input);
+    if (!parsed.success) throw new BrowserKeeperError("invalid_request");
+    const { hello, request } = parsed.data;
+    this.ledger.assertIdentity(principal.installationId, principal.userId);
+    if (hello.instanceId !== principal.ownerId || hello.role !== "browser-adapter") throw new BrowserKeeperError("unauthorized_peer");
+    try {
+      negotiateProtocol(this.hello, hello, [BROWSER_KEEPER_CAPABILITY]);
+    } catch {
+      throw new BrowserKeeperError("incompatible_peer");
+    }
+    const operation = "operation" in request ? request.operation : null;
+    const fence = operation?.fence ?? ("fence" in request ? request.fence : null);
+    if (!fence) throw new BrowserKeeperError("invalid_request");
+    this.ledger.assertIdentity(fence.installationId, operation?.userId ?? ("userId" in request ? request.userId : ""));
+    if (fence.ownerId !== principal.ownerId) throw new BrowserKeeperError("unauthorized_owner");
+    if (fence.resourceType === "browser-user" && fence.resourceId !== principal.userId) throw new BrowserKeeperError("wrong_identity");
+    this.ledger.prune();
+    if (request.method === "claim" || request.method === "renew") {
+      this.ledger.claim(fence, request.expiresAt, request.method === "renew");
+      return { ok: true };
+    }
+    if (request.method === "release") {
+      this.ledger.release(fence);
+      return { ok: true };
+    }
+    if (!operation) throw new BrowserKeeperError("invalid_request");
+    let frozen;
+    try {
+      const json = canonicalJson(operation);
+      if (Buffer.byteLength(json) > this.maxPayloadBytes) throw new BrowserKeeperError("payload_too_large");
+      frozen = BrowserOperation.parse(JSON.parse(json));
+    } catch (error) {
+      if (error instanceof BrowserKeeperError) throw error;
+      throw new BrowserKeeperError("invalid_payload");
+    }
+    const hash = await operationPayloadHash(frozen);
+    if (this.closing || this.storageFailed) throw new BrowserKeeperError("keeper_unavailable");
+    this.ledger.assertFence(frozen.fence);
+    const existing = this.ledger.find(frozen, hash);
+    if (request.method === "inspect") return existing;
+    if (existing) {
+      const pending2 = this.inFlight.get(frozen.operationId);
+      return pending2 ? structuredClone(await pending2) : existing;
+    }
+    if (this.inFlight.size >= this.maxInFlight) throw new BrowserKeeperError("keeper_capacity");
+    this.ledger.admit(frozen, hash);
+    const queueKey = `${frozen.fence.resourceType}:${frozen.fence.resourceId}`;
+    const previous = this.queues.get(queueKey) ?? Promise.resolve();
+    const pending = previous.then(() => this.perform(frozen, hash));
+    this.inFlight.set(frozen.operationId, pending);
+    const tail = pending.then(
+      () => void 0,
+      () => void 0
+    ).then(() => {
+      this.inFlight.delete(frozen.operationId);
+      if (this.queues.get(queueKey) === tail) this.queues.delete(queueKey);
+    });
+    this.queues.set(queueKey, tail);
+    return structuredClone(await pending);
+  }
+  async perform(operation, hash) {
+    try {
+      if (this.storageFailed) throw new BrowserKeeperError("storage_unavailable");
+      try {
+        this.ledger.assertFence(operation.fence);
+      } catch {
+        this.ledger.finish(operation.operationId, "cancelled", null, "stale_before_start");
+        return this.ledger.find(operation, hash);
+      }
+      this.ledger.running(operation.operationId);
+      let resultJson = null;
+      let uncertain = false;
+      try {
+        resultJson = canonicalJson(await this.executor.execute(operation));
+      } catch {
+        uncertain = true;
+      }
+      this.ledger.finish(
+        operation.operationId,
+        uncertain ? "unknown" : "completed",
+        resultJson,
+        uncertain ? "executor_uncertain" : void 0
+      );
+      return this.ledger.find(operation, hash);
+    } catch {
+      this.storageFailed = true;
+      throw new BrowserKeeperError("storage_unavailable");
+    }
+  }
+  /** Maintenance only: adapter disconnection must NOT invoke close or executor disposal. */
+  close() {
+    if (this.closePromise) return this.closePromise;
+    this.closing = true;
+    clearInterval(this.pruneTimer);
+    return this.closePromise = (async () => {
+      await Promise.allSettled(this.inFlight.values());
+      try {
+        await this.executor.dispose?.();
+      } finally {
+        this.ledger.close();
+      }
+    })();
+  }
+}
+export {
+  BrowserKeeper
+};

package/dist/mjs/runtime/ledger.mjs

@@ -0,0 +1,193 @@
+import { Database } from "bun:sqlite";
+import fs from "node:fs";
+import path from "node:path";
+import { RuntimeId } from "@ricsam/r5d-api/runtime-protocol";
+import { BrowserKeeperError } from "./protocol.mjs";
+class BrowserLedger {
+  db;
+  now;
+  installationId;
+  userId;
+  retentionMs;
+  maxReceiptBytes;
+  maxTotalReceiptBytes;
+  maxOperations;
+  maxClaims;
+  maxLeaseMs;
+  constructor(options) {
+    this.installationId = RuntimeId.parse(options.installationId);
+    this.userId = RuntimeId.parse(options.userId);
+    this.now = options.now ?? Date.now;
+    const positive = (value) => {
+      if (!Number.isSafeInteger(value) || value < 1) throw new BrowserKeeperError("invalid_limits");
+      return value;
+    };
+    this.retentionMs = positive(options.retentionMs ?? 24 * 60 * 60 * 1e3);
+    this.maxReceiptBytes = positive(options.maxReceiptBytes ?? 16 * 1024 * 1024);
+    this.maxTotalReceiptBytes = positive(options.maxTotalReceiptBytes ?? 64 * 1024 * 1024);
+    this.maxOperations = positive(options.maxOperations ?? 1e5);
+    this.maxClaims = positive(options.maxClaims ?? 4096);
+    this.maxLeaseMs = positive(options.maxLeaseMs ?? 5 * 60 * 1e3);
+    fs.mkdirSync(options.directory, { recursive: true, mode: 448 });
+    const directory = fs.lstatSync(options.directory);
+    if (!directory.isDirectory() || directory.isSymbolicLink() || (directory.mode & 63) !== 0 || directory.uid !== process.getuid?.()) {
+      throw new BrowserKeeperError("unsafe_state_directory");
+    }
+    const filename = path.join(options.directory, "operations.sqlite");
+    try {
+      const fd = fs.openSync(filename, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW, 384);
+      fs.closeSync(fd);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    for (const file of [filename, `${filename}-journal`, `${filename}-wal`, `${filename}-shm`]) {
+      if (!fs.existsSync(file)) {
+        try {
+          if (fs.lstatSync(file).isSymbolicLink()) throw new BrowserKeeperError("unsafe_ledger_file");
+        } catch (error) {
+          if (error.code !== "ENOENT") throw error;
+        }
+        continue;
+      }
+      const stats = fs.lstatSync(file);
+      if (!stats.isFile() || stats.isSymbolicLink() || stats.nlink !== 1 || (stats.mode & 63) !== 0 || stats.uid !== directory.uid) {
+        throw new BrowserKeeperError("unsafe_ledger_file");
+      }
+    }
+    this.db = new Database(filename, { strict: true });
+    try {
+      this.db.exec(
+        "PRAGMA busy_timeout=0; PRAGMA locking_mode=EXCLUSIVE; PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL; PRAGMA secure_delete=ON;"
+      );
+      this.db.exec("BEGIN EXCLUSIVE; COMMIT;");
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS identity (singleton INTEGER PRIMARY KEY CHECK(singleton=1), installation_id TEXT NOT NULL, user_id TEXT NOT NULL, version INTEGER NOT NULL);
+        CREATE TABLE IF NOT EXISTS claims (
+          resource_type TEXT NOT NULL, resource_id TEXT NOT NULL, owner_id TEXT NOT NULL,
+          epoch INTEGER NOT NULL, expires_at INTEGER NOT NULL, released INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY(resource_type, resource_id)
+        );
+        CREATE TABLE IF NOT EXISTS operations (
+          operation_id TEXT PRIMARY KEY, payload_hash TEXT NOT NULL, resource_type TEXT NOT NULL,
+          resource_id TEXT NOT NULL, owner_id TEXT NOT NULL, epoch INTEGER NOT NULL, state TEXT NOT NULL,
+          result_json TEXT, result_bytes INTEGER NOT NULL DEFAULT 0, reason TEXT, accepted_at INTEGER NOT NULL, finished_at INTEGER
+        );
+      `);
+      this.db.query("INSERT OR IGNORE INTO identity VALUES (1, ?, ?, 1)").run(this.installationId, this.userId);
+      const identity = this.db.query("SELECT * FROM identity WHERE singleton=1").get();
+      if (identity.installation_id !== this.installationId || identity.user_id !== this.userId || identity.version !== 1) {
+        throw new BrowserKeeperError("wrong_ledger_identity");
+      }
+      this.db.query("UPDATE operations SET state='unknown', reason='keeper_restarted', finished_at=? WHERE state IN ('accepted','running')").run(this.now());
+      this.prune();
+    } catch (error) {
+      this.db.close();
+      throw error;
+    }
+  }
+  assertIdentity(installationId, userId) {
+    if (installationId !== this.installationId || userId !== this.userId) throw new BrowserKeeperError("wrong_identity");
+  }
+  claimRow(fence) {
+    return this.db.query("SELECT owner_id, epoch, expires_at, released FROM claims WHERE resource_type=? AND resource_id=?").get(fence.resourceType, fence.resourceId);
+  }
+  assertFence(fence) {
+    if (fence.installationId !== this.installationId) throw new BrowserKeeperError("wrong_identity");
+    const claim = this.claimRow(fence);
+    if (!claim || claim.released || claim.owner_id !== fence.ownerId || claim.epoch !== fence.epoch || claim.expires_at <= this.now()) {
+      throw new BrowserKeeperError("stale_fence");
+    }
+  }
+  claim(fence, expiresAt, renew = false) {
+    const now = this.now();
+    if (expiresAt <= now || expiresAt - now > this.maxLeaseMs) throw new BrowserKeeperError("invalid_lease");
+    const previous = this.claimRow(fence);
+    if (renew) this.assertFence(fence);
+    else if (previous && (fence.epoch < previous.epoch || fence.epoch === previous.epoch && (previous.owner_id !== fence.ownerId || previous.released || previous.expires_at <= now)))
+      throw new BrowserKeeperError("stale_fence");
+    if (previous && fence.epoch === previous.epoch && expiresAt < previous.expires_at) throw new BrowserKeeperError("lease_regression");
+    if (!previous && this.count("claims") >= this.maxClaims) throw new BrowserKeeperError("claim_capacity");
+    this.db.query(
+      `INSERT INTO claims VALUES (?, ?, ?, ?, ?, 0)
+      ON CONFLICT(resource_type, resource_id) DO UPDATE SET owner_id=excluded.owner_id, epoch=excluded.epoch, expires_at=excluded.expires_at, released=0`
+    ).run(fence.resourceType, fence.resourceId, fence.ownerId, fence.epoch, expiresAt);
+  }
+  release(fence) {
+    this.assertFence(fence);
+    this.db.query("UPDATE claims SET released=1 WHERE resource_type=? AND resource_id=?").run(fence.resourceType, fence.resourceId);
+  }
+  count(table) {
+    return this.db.query(`SELECT COUNT(*) AS count FROM ${table}`).get().count;
+  }
+  find(operation, hash) {
+    const row = this.db.query("SELECT * FROM operations WHERE operation_id=?").get(operation.operationId);
+    if (!row) return null;
+    if (row.payload_hash !== hash || row.resource_type !== operation.fence.resourceType || row.resource_id !== operation.fence.resourceId) {
+      throw new BrowserKeeperError("operation_conflict");
+    }
+    return this.receipt(row);
+  }
+  admit(operation, hash) {
+    if (this.count("operations") >= this.maxOperations) throw new BrowserKeeperError("operation_capacity");
+    this.db.query(
+      `INSERT INTO operations (operation_id, payload_hash, resource_type, resource_id, owner_id, epoch, state, accepted_at)
+      VALUES (?, ?, ?, ?, ?, ?, 'accepted', ?)`
+    ).run(
+      operation.operationId,
+      hash,
+      operation.fence.resourceType,
+      operation.fence.resourceId,
+      operation.fence.ownerId,
+      operation.fence.epoch,
+      this.now()
+    );
+  }
+  running(operationId) {
+    this.db.query("UPDATE operations SET state='running' WHERE operation_id=? AND state='accepted'").run(operationId);
+  }
+  finish(operationId, state, resultJson, reason) {
+    const bytes = resultJson === null ? 0 : Buffer.byteLength(resultJson);
+    if (bytes > this.maxReceiptBytes || bytes > this.maxTotalReceiptBytes) {
+      resultJson = null;
+      reason = "receipt_too_large";
+    }
+    this.db.query(
+      "UPDATE operations SET state=?, result_json=?, result_bytes=?, reason=?, finished_at=? WHERE operation_id=? AND state IN ('accepted','running')"
+    ).run(state, resultJson, resultJson === null ? 0 : bytes, reason ?? null, this.now(), operationId);
+    this.prune();
+  }
+  prune() {
+    this.db.query("UPDATE operations SET result_json=NULL, result_bytes=0 WHERE result_json IS NOT NULL AND finished_at<=?").run(this.now() - this.retentionMs);
+    let total = this.db.query("SELECT COALESCE(SUM(result_bytes), 0) AS total FROM operations").get().total;
+    if (total > this.maxTotalReceiptBytes) {
+      const rows = this.db.query("SELECT operation_id, result_bytes FROM operations WHERE result_bytes>0 ORDER BY finished_at, rowid").all();
+      const clear = this.db.query("UPDATE operations SET result_json=NULL, result_bytes=0 WHERE operation_id=?");
+      this.db.transaction(() => {
+        for (const row of rows) {
+          if (total <= this.maxTotalReceiptBytes) break;
+          clear.run(row.operation_id);
+          total -= row.result_bytes;
+        }
+      })();
+    }
+  }
+  receipt(row) {
+    return {
+      protocol: 1,
+      installationId: this.installationId,
+      userId: this.userId,
+      operationId: row.operation_id,
+      payloadHash: row.payload_hash,
+      state: row.state,
+      resultAvailable: row.result_json !== null,
+      ...row.result_json !== null ? { result: JSON.parse(row.result_json) } : {},
+      ...row.reason ? { reason: row.reason } : {}
+    };
+  }
+  close() {
+    this.db.close();
+  }
+}
+export {
+  BrowserLedger
+};

package/dist/mjs/runtime/main.mjs

@@ -0,0 +1,105 @@
+import path from "node:path";
+import fs from "node:fs";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import { RuntimeId } from "@ricsam/r5d-api/runtime-protocol";
+import { BrowserKeeper } from "./keeper.mjs";
+import { serveBrowserKeeper } from "./ipc.mjs";
+import { BrowserKeeperError } from "./protocol.mjs";
+import { readPrivateFile } from "./private-paths.mjs";
+import { isolatedBrowserRoot } from "./isolated-root.mjs";
+import { createIsolatedChromiumRuntime, loadApprovedChromiumFactory } from "./chromium-factory.mjs";
+const BrowserKeeperConfig = z.object({
+  installationId: RuntimeId,
+  userId: RuntimeId,
+  instanceId: RuntimeId,
+  releaseId: RuntimeId,
+  root: z.string().refine(path.isAbsolute),
+  factory: z.object({ approvalPath: z.string().refine(path.isAbsolute), sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict(),
+  adapters: z.array(z.object({ ownerId: RuntimeId, token: z.string().min(32).max(4096) }).strict()).min(1).max(16)
+}).strict();
+async function startConfiguredBrowserKeeper(configPath) {
+  const parsed = BrowserKeeperConfig.safeParse(JSON.parse(readPrivateFile(configPath, 128 * 1024).toString("utf8")));
+  if (!parsed.success) throw new BrowserKeeperError("invalid_keeper_config");
+  const config = parsed.data;
+  const approval = loadApprovedChromiumFactory(config.factory.approvalPath, config.factory.sha256);
+  const adapters = config.adapters.map((adapter) => ({
+    ownerId: adapter.ownerId,
+    hash: createHash("sha256").update(adapter.token).digest()
+  }));
+  if (new Set(adapters.map((adapter) => adapter.ownerId)).size !== adapters.length || new Set(adapters.map((adapter) => adapter.hash.toString("hex"))).size !== adapters.length)
+    throw new BrowserKeeperError("duplicate_adapter_identity");
+  const root = isolatedBrowserRoot(config.root, config.installationId, config.userId);
+  let runtime;
+  const keeper = new BrowserKeeper({
+    directory: root.ledger,
+    installationId: config.installationId,
+    userId: config.userId,
+    instanceId: config.instanceId,
+    releaseId: config.releaseId,
+    executor: {
+      execute: (operation) => {
+        if (!runtime) throw new BrowserKeeperError("runtime_unavailable");
+        return runtime.executor.execute(operation);
+      },
+      dispose: async () => {
+        await runtime?.executor.dispose?.();
+      }
+    }
+  });
+  const socketPath = path.join(root.ledger, "keeper.sock");
+  try {
+    try {
+      const socket = fs.lstatSync(socketPath);
+      if (!socket.isSocket() || socket.uid !== process.getuid?.()) throw new BrowserKeeperError("unsafe_socket_path");
+      fs.unlinkSync(socketPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    runtime = await createIsolatedChromiumRuntime({ runs: root.runs, approval });
+    const ipc = await serveBrowserKeeper({
+      keeper,
+      socketPath,
+      authenticate: (token) => {
+        const hash = createHash("sha256").update(token).digest();
+        const adapter = adapters.find((candidate) => timingSafeEqual(hash, candidate.hash));
+        return adapter ? { installationId: config.installationId, userId: config.userId, ownerId: adapter.ownerId } : null;
+      }
+    });
+    let closePromise;
+    return {
+      socketPath,
+      identity: runtime.identity,
+      close() {
+        return closePromise ??= (async () => {
+          await ipc.close();
+          await keeper.close();
+        })();
+      }
+    };
+  } catch (error) {
+    await keeper.close();
+    throw error;
+  }
+}
+if (import.meta.main) {
+  try {
+    if (process.argv.length !== 4 || process.argv[2] !== "--config") throw new BrowserKeeperError("invalid_arguments");
+    const service = await startConfiguredBrowserKeeper(process.argv[3]);
+    const stop = () => {
+      void service.close().then(
+        () => process.exit(0),
+        () => process.exit(1)
+      );
+    };
+    process.once("SIGTERM", stop);
+    process.once("SIGINT", stop);
+  } catch {
+    process.stderr.write("Browser keeper startup failed; check private approval/configuration and exclusive state ownership.\n");
+    process.exitCode = 1;
+  }
+}
+export {
+  BrowserKeeperConfig,
+  startConfiguredBrowserKeeper
+};

package/dist/mjs/runtime/private-paths.mjs

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import path from "node:path";
+import { BrowserKeeperError } from "./protocol.mjs";
+function assertPrivatePath(filename, kind, immutable = false) {
+  if (!path.isAbsolute(filename) || path.normalize(filename) !== filename) throw new BrowserKeeperError("noncanonical_private_path");
+  const components = filename.split(path.sep).filter(Boolean);
+  if (components.length === 0) throw new BrowserKeeperError("unsafe_private_path");
+  let current = path.parse(filename).root;
+  for (let i = 0; i < components.length; i++) {
+    current = path.join(current, components[i]);
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink()) throw new BrowserKeeperError("linked_private_path");
+    const leaf = i === components.length - 1;
+    if (!leaf) {
+      if (!stat.isDirectory() || stat.uid !== 0 && stat.uid !== process.getuid?.() || (stat.mode & 18) !== 0 && (stat.mode & 512) === 0)
+        throw new BrowserKeeperError("unsafe_private_ancestor");
+    } else if (stat.uid !== process.getuid?.() || (stat.mode & 63) !== 0 || (kind === "directory" ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1) || immutable && (stat.mode & 146) !== 0) {
+      throw new BrowserKeeperError("unsafe_private_path");
+    }
+  }
+}
+function readPrivateFile(filename, maximumBytes, immutable = false) {
+  assertPrivatePath(filename, "file", immutable);
+  const fd = fs.openSync(filename, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  try {
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid?.() || (stat.mode & 63) !== 0 || stat.size > maximumBytes || immutable && (stat.mode & 146) !== 0)
+      throw new BrowserKeeperError("unsafe_private_file");
+    const bytes = fs.readFileSync(fd);
+    if (bytes.byteLength > maximumBytes) throw new BrowserKeeperError("private_file_too_large");
+    return bytes;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function makePrivateDirectory(directory) {
+  try {
+    fs.mkdirSync(directory, { mode: 448 });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  }
+  assertPrivatePath(directory, "directory");
+}
+export {
+  assertPrivatePath,
+  makePrivateDirectory,
+  readPrivateFile
+};

package/dist/mjs/runtime/protocol.mjs

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { OperationEnvelope, OwnershipFence, RuntimeHello, RuntimeId, RUNTIME_PROTOCOL } from "@ricsam/r5d-api/runtime-protocol";
+const BROWSER_KEEPER_CAPABILITY = "browser-operations.v1";
+const BrowserAction = z.enum([
+  "list_tabs",
+  "list_downloads",
+  "get_download",
+  "open_tab",
+  "close_tab",
+  "navigate",
+  "set_viewport",
+  "read_page",
+  "screenshot",
+  "move_mouse",
+  "mouse_click",
+  "scroll",
+  "wait_for",
+  "form_input",
+  "keyboard",
+  "keyboard_type",
+  "run_js",
+  "upload_begin",
+  "upload_chunk",
+  "upload_attach",
+  "upload_abort"
+]);
+const userActions = /* @__PURE__ */ new Set(["list_tabs", "list_downloads", "get_download", "open_tab"]);
+const BrowserFence = OwnershipFence.refine(
+  (fence) => fence.resourceType === "browser-tab" || fence.resourceType === "browser-user",
+  "Not a browser resource"
+);
+const BrowserOperation = OperationEnvelope.superRefine((operation, context) => {
+  if (!BrowserAction.safeParse(operation.kind).success) context.addIssue({ code: "custom", message: "Unsupported browser action" });
+  const payload = operation.payload;
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    context.addIssue({ code: "custom", message: "Browser input must be an object" });
+    return;
+  }
+  if (userActions.has(operation.kind)) {
+    if (operation.fence.resourceType !== "browser-user" || operation.fence.resourceId !== operation.userId || "tabId" in payload) {
+      context.addIssue({ code: "custom", message: "User action requires its user resource fence, without a tab target" });
+    }
+  } else if (operation.fence.resourceType !== "browser-tab" || !("tabId" in payload) || payload.tabId !== operation.fence.resourceId) {
+    context.addIssue({ code: "custom", message: "Tab target must match its fence" });
+  }
+});
+const lease = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const BrowserKeeperRequest = z.discriminatedUnion("method", [
+  z.object({ method: z.literal("claim"), userId: RuntimeId, fence: BrowserFence, expiresAt: lease }).strict(),
+  z.object({ method: z.literal("renew"), userId: RuntimeId, fence: BrowserFence, expiresAt: lease }).strict(),
+  z.object({ method: z.literal("release"), userId: RuntimeId, fence: BrowserFence }).strict(),
+  z.object({ method: z.literal("execute"), operation: BrowserOperation }).strict(),
+  z.object({ method: z.literal("inspect"), operation: BrowserOperation }).strict()
+]);
+const BrowserKeeperMessage = z.object({ hello: RuntimeHello, request: BrowserKeeperRequest }).strict();
+class BrowserKeeperError extends Error {
+  constructor(code) {
+    super(code);
+    this.code = code;
+    this.name = "BrowserKeeperError";
+  }
+  code;
+}
+export {
+  BROWSER_KEEPER_CAPABILITY,
+  BrowserAction,
+  BrowserFence,
+  BrowserKeeperError,
+  BrowserKeeperMessage,
+  BrowserKeeperRequest,
+  BrowserOperation
+};

package/dist/types/browser-input.d.ts

@@ -108,4 +108,8 @@ export type BrowserViewport = {
 };
 export declare function parseViewportInput(input: Readonly<Record<string, unknown>>): BrowserViewport | null;
 export declare function normalizeBrowserInput(action: BrowserInputAction, input: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/** Only checks arguments whose validity is independent of browser state. Run
+ * before durable dispatch: a model may correct these errors without an effect
+ * having been admitted. Click/navigation failures after dispatch stay unknown. */
+export declare function preflightBrowserInput(action: BrowserInputAction, raw: Readonly<Record<string, unknown>>): Record<string, unknown>;
 export {};

package/dist/types/cli-options.d.ts

@@ -4,6 +4,7 @@ export type BrowserCliOptions = {
     apiKey?: string;
     configPath: string;
     profilePath?: string;
+    rootPath?: string;
     chromePath?: string;
     help: boolean;
     version: boolean;

package/dist/types/personal-diagnostics.d.ts

@@ -0,0 +1,13 @@
+export type PersonalBrowserDiagnostic = {
+    phase: "accepted" | "received" | "request" | "response" | "failure" | "closed" | "action-error";
+    method?: "connect" | "write" | "read" | "close";
+    bytes?: number;
+    status?: number;
+    code?: string;
+    action?: string;
+    category?: "timeout" | "disconnected" | "invalid-input" | "other";
+};
+export type PersonalBrowserObserver = (event: PersonalBrowserDiagnostic) => void;
+export declare function browserErrorCategory(error: unknown): PersonalBrowserDiagnostic["category"];
+/** Opt-in diagnostics contain counts/categories only, never requests or error text. */
+export declare function personalBrowserDiagnosticObserver(enabled: boolean, write?: (line: string) => unknown): PersonalBrowserObserver;