botversion-sdk 2.2.3 → 2.3.0

package/undo/lib/tagger.js

@@ -0,0 +1,333 @@
+// lib/tagger.js
+"use strict";
+// REQUEST TAGGER
+// Marks a request as "AI action" and carries that mark through everything the
+// request does (including after `await`), using Node's AsyncLocalStorage.
+//
+// How it hooks in without the host changing anything: it wraps the 'request'
+// event of Node's built-in HTTP servers. Express, Fastify, Koa, NestJS, Next.js
+// and plain Node servers all sit on top of these, so no framework-specific code.
+//
+// A request counts as an AI request only if it carries the marker header with an id
+// signed by BotVersion's server (checked against the host's API key in buildStore()).
+
+const { AsyncLocalStorage } = require("async_hooks");
+const log = require("./log");
+const actionId = require("./action-id");
+const undoRoute = require("./undo-route");
+const requester = require("./requester");
+
+const als = new AsyncLocalStorage();
+const PATCHED = Symbol.for("botversion.undoExp.emitPatched");
+const VISUAL_HEADER = "x-botversion-visual"; // sent by the visual agent: "record" or "confirm"
+
+let headerName = "x-botversion-action-id";
+let counter = 0;
+let signingKey = null; // derived from the host's API key; the raw key is never kept
+let lastIgnoredLog = 0;
+
+function setApiKey(key) {
+  try {
+    signingKey = actionId.deriveSigningKey(key);
+  } catch (_) {
+    signingKey = null;
+  }
+}
+
+function hasApiKey() {
+  return !!signingKey;
+}
+
+// Explains why a marked request was ignored, at most once a minute so forged requests cannot flood the log.
+function noteIgnored(message) {
+  const now = Date.now();
+  if (now - lastIgnoredLog < 60000) return;
+  lastIgnoredLog = now;
+}
+
+function setHeaderName(name) {
+  if (typeof name === "string" && name.trim())
+    headerName = name.trim().toLowerCase();
+}
+
+function getHeaderName() {
+  return headerName;
+}
+
+// The current AI-request info, or null if this code is not running inside one.
+function getCurrent() {
+  try {
+    return als.getStore() || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---- Decides whether a request is an AI request, and builds its info. ----
+function buildStore(req, res) {
+  const headers = req && req.headers;
+  if (!headers) return null;
+  const raw = headers[headerName];
+  const first = Array.isArray(raw) ? raw[0] : raw;
+  // Only a plain id shape is accepted, so odd or hostile values never reach logs or later storage.
+  if (typeof first !== "string" || !/^[A-Za-z0-9_-]{8,64}$/.test(first))
+    return null;
+  // Only ids issued by BotVersion's server and signed with the host's API key count as AI requests.
+  if (!signingKey) {
+    noteIgnored(
+      "a request carried the AI marker header but no API key was given to init(), so it is treated as a normal request",
+    );
+    return null;
+  }
+  if (!actionId.isValidActionId(first, signingKey)) {
+    noteIgnored(
+      "a request carried the AI marker header with an invalid signature, so it is treated as a normal request",
+    );
+    return null;
+  }
+  const value = first;
+
+  // Visual-agent mode: "record" or "confirm". Missing or unknown = handled as before.
+  const visualRaw = headers[VISUAL_HEADER];
+  const visualVal = Array.isArray(visualRaw) ? visualRaw[0] : visualRaw;
+  const visual =
+    visualVal === "record" || visualVal === "confirm" ? visualVal : null;
+  const requesterHash = requester.fromHeaders(headers); // hash of the browser-session secret, or null
+  // Without the session secret Undo could never be allowed later, so such a request is not treated as an AI request.
+  if (visual && !requesterHash) {
+    noteIgnored(
+      "a visual-agent request had no valid requester secret, so it is treated as a normal request",
+    );
+    return null;
+  }
+
+  // Path only, query string dropped (a query string could contain private data).
+  let path = "";
+  try {
+    path = String(req.url || "")
+      .split("?")[0]
+      .slice(0, 200);
+  } catch (_) {
+    /* ignore */
+  }
+
+  const store = {
+    actionId: value,
+    requesterHash, // hash of the browser-session secret (read above)
+    res: res || null, // the confirm gate answers the request through this
+    // true when the user clicked "yes", or when a record-only visual request must never be blocked
+    confirmed:
+      headers["x-botversion-confirmed"] === value || visual === "record",
+    visual, // null, "record" or "confirm"
+    blocked: null,
+    requestNo: ++counter,
+    method: String(req.method || "?"),
+    path,
+    startedAt: Date.now(),
+    savedIds: [], // snapshot ids saved by this request (lets a visual run roll back only this request)
+    queries: 0, // every database query the hook saw during this request
+    writes: 0, // how many of them were writes
+    unsaved: false, // true when a write of this request ran without a saved snapshot
+  };
+
+  // When the response is finished, print a summary. This is how we prove at
+  // runtime whether the hook actually saw anything (plan section 15, step 4).
+  try {
+    if (res && typeof res.once === "function") {
+      res.once("close", () => {
+        try {
+          const ms = Date.now() - store.startedAt;
+        } catch (_) {
+          /* never break the host */
+        }
+      });
+    }
+  } catch (_) {
+    /* never break the host */
+  }
+
+  return store;
+}
+// ---------------------------------------------------------------------------
+
+// ---- Lets the browser's permission check (preflight) accept our headers, without ever widening the host's own rules. ----
+const OUR_HEADERS = [
+  "x-botversion-action-id",
+  "x-botversion-requester",
+  "x-botversion-visual",
+  "x-botversion-confirmed",
+];
+
+// Returns the writeHead arguments, with our header names added to the host's allowed list only when the host already allows this origin.
+function withOurHeaders(res, origin, args) {
+  const last = args[args.length - 1];
+  const bag =
+    last && typeof last === "object" && !Array.isArray(last)
+      ? Object.assign({}, last)
+      : null;
+  const find = (name) =>
+    bag ? Object.keys(bag).find((k) => k.toLowerCase() === name) : undefined;
+  const read = (name) => {
+    const k = find(name);
+    if (k !== undefined) return String(bag[k]);
+    const v = res.getHeader(name);
+    return v === undefined || v === null ? "" : String(v);
+  };
+  const allowOrigin = read("access-control-allow-origin");
+  if (allowOrigin !== origin && allowOrigin !== "*") return args; // host did not allow this site: never widen
+  const current = read("access-control-allow-headers");
+  const have = current
+    .toLowerCase()
+    .split(",")
+    .map((s) => s.trim());
+  const credentialed =
+    read("access-control-allow-credentials").toLowerCase() === "true";
+  if (have.includes("*") && !credentialed) return args; // "*" already covers us
+  const missing = OUR_HEADERS.filter((n) => have.indexOf(n) === -1);
+  if (!missing.length) return args;
+  const value = (current ? current + ", " : "") + missing.join(", ");
+  const k = find("access-control-allow-headers");
+  if (bag && k !== undefined) {
+    bag[k] = value;
+    args[args.length - 1] = bag;
+  } else {
+    res.setHeader("Access-Control-Allow-Headers", value);
+  }
+  return args;
+}
+
+// Watches only preflight requests that ask for our headers. Any problem inside leaves the host's answer untouched.
+function guardPreflight(req, res) {
+  try {
+    if (!req || !res || String(req.method).toUpperCase() !== "OPTIONS") return;
+    const h = req.headers || {};
+    const origin = h.origin;
+    const asked = String(
+      h["access-control-request-headers"] || "",
+    ).toLowerCase();
+    if (!origin || asked.indexOf("x-botversion-") === -1) return;
+    if (typeof res.writeHead !== "function" || res.__bvPreflight) return;
+    res.__bvPreflight = true;
+    const original = res.writeHead;
+    res.writeHead = function () {
+      let args = Array.prototype.slice.call(arguments);
+      try {
+        args = withOurHeaders(res, origin, args);
+      } catch (_) {
+        args = Array.prototype.slice.call(arguments);
+      }
+      return original.apply(this, args);
+    };
+  } catch (_) {
+    /* never break the host */
+  }
+}
+
+// Tells the widget, through a response header, that a write of this visual request ran without a saved snapshot.
+function guardUnsavedHeader(store, res) {
+  try {
+    if (!store || !store.visual || !res || typeof res.writeHead !== "function")
+      return;
+    const original = res.writeHead;
+    res.writeHead = function () {
+      try {
+        if (store.unsaved && !res.headersSent) {
+          res.setHeader("x-botversion-unsaved", "1");
+          const prev = String(
+            res.getHeader("access-control-expose-headers") || "",
+          );
+          if (!prev.includes("*") && !/x-botversion-unsaved/i.test(prev))
+            res.setHeader(
+              "Access-Control-Expose-Headers",
+              prev ? prev + ", x-botversion-unsaved" : "x-botversion-unsaved",
+            );
+        }
+      } catch (_) {
+        /* never break the host */
+      }
+      return original.apply(this, arguments);
+    };
+  } catch (_) {
+    /* never break the host */
+  }
+}
+
+function wrapEmit(proto) {
+  if (!proto || typeof proto.emit !== "function") return false;
+  if (proto.emit[PATCHED]) return false; // already wrapped (safe to call init twice)
+
+  const original = proto.emit;
+  const wrapper = function emit(event, req, res) {
+    let store = null;
+    if (event === "request") {
+      try {
+        // The Undo route is answered here, before the host's framework sees the request.
+        if (
+          undoRoute.handle(req, res, (id) =>
+            actionId.isValidActionId(id, signingKey),
+          )
+        )
+          return true;
+      } catch (_) {
+        /* never break the host */
+      }
+      guardPreflight(req, res); // never throws; only touches preflight requests that ask for our headers
+      try {
+        store = buildStore(req, res);
+      } catch (_) {
+        store = null; // tagging problems must never affect the host
+      }
+      guardUnsavedHeader(store, res); // never throws; only acts on visual requests
+    }
+    if (!store) return original.apply(this, arguments);
+    const args = arguments;
+    return als.run(store, () => original.apply(this, args));
+  };
+  Object.defineProperty(wrapper, PATCHED, { value: true });
+  proto.emit = wrapper;
+  return true;
+}
+
+// Wraps every built-in server type that exists in this Node version.
+function install() {
+  const wrapped = [];
+  const targets = [
+    ["http", (m) => m.Server && m.Server.prototype],
+    ["https", (m) => m.Server && m.Server.prototype],
+    [
+      "http2",
+      (m) => [
+        m.Http2Server && m.Http2Server.prototype,
+        m.Http2SecureServer && m.Http2SecureServer.prototype,
+      ],
+    ],
+  ];
+  // http2 exposes its server classes only through createServer(); read the prototypes from an instance.
+  for (const [name, getProto] of targets) {
+    try {
+      const mod = require(name);
+      let protos;
+      if (name === "http2") {
+        protos = [
+          Object.getPrototypeOf(mod.createServer()),
+          Object.getPrototypeOf(mod.createSecureServer()),
+        ];
+      } else {
+        protos = [getProto(mod)];
+      }
+      for (const proto of protos) {
+        if (wrapEmit(proto) && !wrapped.includes(name)) wrapped.push(name);
+      }
+    } catch (e) {}
+  }
+  return wrapped;
+}
+
+module.exports = {
+  install,
+  getCurrent,
+  setHeaderName,
+  getHeaderName,
+  setApiKey,
+  hasApiKey,
+};

package/undo/lib/undo-mongo.js

@@ -0,0 +1,248 @@
+// lib/undo-mongo.js
+"use strict";
+// UNDO (MongoDB): restores the documents saved for one AI action.
+// Uses the host's own database object (remembered by the mongodb hook). Logs: counts only.
+// MongoDB has no transaction on every setup, so Undo checks EVERY document first and only then restores:
+// if any document was changed after the AI action, nothing is touched.
+
+const log = require("./log");
+const snapshotCrypto = require("./snapshot-crypto");
+const mstore = require("./snapshot-store-mongo");
+const { TABLE } = require("./snapshot-store");
+const requester = require("./requester");
+const guard = require("./capture-guard");
+const { Refuse } = require("./undo-prisma");
+
+const dbs = new Map(); // database name -> the host's own Db object
+
+function remember(db) {
+  try {
+    if (db && typeof db.collection === "function" && db.databaseName) {
+      dbs.set(db.databaseName, db);
+    }
+  } catch (_) {
+    /* never break the host */
+  }
+}
+
+const live = (r) =>
+  r.expires_at instanceof Date && r.expires_at.getTime() > Date.now();
+const decode = (v) =>
+  v == null ? null : mstore.fromText(snapshotCrypto.decrypt(v));
+
+// Every saved row of one action, from every database this app has written to.
+async function gather(actionId) {
+  const rows = [];
+  for (const db of dbs.values()) {
+    const found = await db
+      .collection(TABLE)
+      .find({ action_id: actionId })
+      .toArray();
+    for (const r of found) {
+      r._db = db;
+      rows.push(r);
+    }
+  }
+  return rows;
+}
+
+async function setStatus(actionId, from, to) {
+  for (const db of dbs.values())
+    await db
+      .collection(TABLE)
+      .updateMany(
+        { action_id: actionId, status: from },
+        { $set: { status: to } },
+      );
+}
+
+async function undoAction(actionId, requesterHash, opts) {
+  if (dbs.size === 0) {
+    throw new Refuse(
+      "no-client",
+      "Undo is not ready yet: the app has not used a MongoDB database in this process. Open any page of the app and try again.",
+    );
+  }
+  if (!snapshotCrypto.hasKey())
+    throw new Refuse("no-key", "Undo is off: no API key was given to the SDK.");
+  if (!mstore.hasEJSON())
+    throw new Refuse(
+      "unsupported",
+      "Undo needs the BSON library of the MongoDB driver, and it was not found.",
+    );
+
+  // Our own queries must never be captured again.
+  return guard.runUnhooked(async () => {
+    let claimed = false;
+    try {
+      let rows = await gather(actionId);
+      // Visual runs undo only the documents of one request (onlyIds); otherwise the whole action.
+      const onlyIds = opts && opts.onlyIds ? opts.onlyIds : null;
+      if (onlyIds) {
+        const s = new Set(onlyIds);
+        rows = rows.filter((r) => s.has(r._id));
+      }
+      if (!rows.length)
+        throw new Refuse(
+          "not-found",
+          "Nothing to undo for this action (it may have expired or saved nothing).",
+        );
+      if (!rows.every((r) => requester.same(r.requester_hash, requesterHash))) {
+        throw new Refuse(
+          "forbidden",
+          "Undo refused: this request is not from the browser session that ran the AI action.",
+        );
+      }
+      if (rows.some((r) => r.status === "undone" || r.status === "undoing"))
+        throw new Refuse(
+          "already-undone",
+          "This action was already undone (or is being undone right now).",
+        );
+      if (rows.some((r) => !live(r)))
+        throw new Refuse(
+          "expired",
+          "Undo is no longer available: the 30 minute window has passed.",
+        );
+      // Order by real save time first: seq restarts for each request, so it cannot order rows across requests.
+      rows.sort((a, b) => b.created_at - a.created_at || b.seq - a.seq); // last write first
+
+      // 1. Group the saved rows by document (newest first inside each group).
+      const groups = new Map();
+      for (const r of rows) {
+        if (!["insert", "update", "delete"].includes(r.operation))
+          throw new Refuse(
+            "unsupported",
+            "This kind of change cannot be undone yet. Nothing was changed.",
+          );
+        if (!r.has_after)
+          throw new Refuse(
+            "conflict",
+            `Cannot verify "${r.collection_name}": its after-state was not saved. Nothing was changed.`,
+          );
+        const pkText = snapshotCrypto.decrypt(r.primary_key);
+        const key =
+          r.db_name + "\u0002" + r.collection_name + "\u0002" + pkText;
+        if (!groups.has(key)) groups.set(key, []);
+        groups.get(key).push({
+          r,
+          id: mstore.fromText(pkText)._id,
+          before: decode(r.before_data),
+          after: decode(r.after_data),
+        });
+      }
+
+      // 2. Check EVERY document before touching any.
+      for (const items of groups.values()) {
+        const top = items[0];
+        const col = top.r._db.collection(top.r.collection_name);
+        const cur = await col.findOne({ _id: top.id });
+        let ok = mstore.canonOf(cur) === mstore.canonOf(top.after);
+        // Several writes to the same document must follow each other without a gap.
+        for (let i = 1; ok && i < items.length; i++)
+          ok =
+            mstore.canonOf(items[i - 1].before) ===
+            mstore.canonOf(items[i].after);
+        if (!ok)
+          throw new Refuse(
+            "conflict",
+            `Not undone: a document in "${top.r.collection_name}" was changed after the AI action. Nothing was changed.`,
+          );
+      }
+
+      // 3. Claim the rows, so two Undo clicks at the same moment cannot both run.
+      let claimedCount = 0;
+      for (const db of dbs.values()) {
+        const res = await db.collection(TABLE).updateMany(
+          Object.assign(
+            {
+              action_id: actionId,
+              status: { $in: ["captured", "conflict"] },
+            },
+            onlyIds ? { _id: { $in: onlyIds } } : {},
+          ),
+          { $set: { status: "undoing" } },
+        );
+        claimedCount += (res && res.modifiedCount) || 0;
+      }
+      claimed = claimedCount > 0;
+      if (claimedCount !== rows.length)
+        throw new Refuse(
+          "already-undone",
+          "This action was already undone (or is being undone right now).",
+        );
+
+      // 4. Restore: each document goes back to how it looked before the FIRST write of this action.
+      try {
+        for (const items of groups.values()) {
+          const first = items[items.length - 1];
+          const col = first.r._db.collection(first.r.collection_name);
+          if (first.before === null) await col.deleteOne({ _id: first.id });
+          else
+            await col.replaceOne({ _id: first.id }, first.before, {
+              upsert: true,
+            });
+        }
+      } catch (e) {
+        throw new Refuse(
+          "partial",
+          "Undo stopped part-way because of a database error. Some documents may be restored and the rest are not.",
+        );
+      }
+
+      // discard = rolled back by the confirm gate: remove the rows so the action can run again with the same id
+      for (const db of dbs.values()) {
+        const c = db.collection(TABLE);
+        if (opts && opts.discard)
+          await c.deleteMany(
+            onlyIds
+              ? { _id: { $in: rows.map((r) => r._id) } }
+              : { action_id: actionId },
+          );
+        else
+          await c.updateMany(
+            { action_id: actionId },
+            { $set: { status: "undone" } },
+          );
+      }
+      claimed = false;
+      return {
+        undone: rows.length,
+        hadDelete: rows.some((r) => r.operation === "delete"),
+      };
+    } catch (e) {
+      try {
+        if (claimed)
+          await setStatus(
+            actionId,
+            "undoing",
+            e instanceof Refuse && e.code !== "partial"
+              ? "captured"
+              : "conflict",
+          );
+        else if (e instanceof Refuse && e.code === "conflict")
+          await setStatus(actionId, "captured", "conflict");
+      } catch (_) {
+        /* ignore */
+      }
+      throw e;
+    }
+  });
+}
+
+// Is there anything to undo for this action, for this browser session? Answers true/false only.
+// Throws Refuse("no-client") when the app has not used MongoDB yet.
+async function statusAction(actionId, requesterHash) {
+  if (dbs.size === 0) throw new Refuse("no-client", "MongoDB not ready.");
+  const rows = await gather(actionId);
+  return (
+    rows.length > 0 &&
+    rows.every(
+      (r) =>
+        requester.same(r.requester_hash, requesterHash) &&
+        r.status === "captured" &&
+        live(r),
+    )
+  );
+}
+
+module.exports = { remember, undoAction, statusAction };