botversion-sdk 2.2.3 → 2.3.0

package/undo/lib/action-id.js

@@ -0,0 +1,38 @@
+// lib/action-id.js
+"use strict";
+// Checks signed action ids issued by BotVersion's server (22 random characters + 22 signature characters).
+// The signing key is derived from the host's API key; the API key itself is never kept or logged.
+const crypto = require("crypto");
+
+const ID_LEN = 22;
+const SIG_LEN = 22;
+
+// Returns the derived signing key, or null when no usable API key was given.
+function deriveSigningKey(apiKey) {
+  if (typeof apiKey !== "string" || !apiKey.trim()) return null;
+  return crypto
+    .createHmac("sha256", apiKey)
+    .update("botversion-action-id-v1")
+    .digest();
+}
+
+function sign(random, signingKey) {
+  return crypto
+    .createHmac("sha256", signingKey)
+    .update(random)
+    .digest("base64url")
+    .slice(0, SIG_LEN);
+}
+
+// True only if this id was really issued with the matching API key.
+function isValidActionId(id, signingKey) {
+  if (!signingKey || typeof id !== "string") return false;
+  if (!/^[A-Za-z0-9_-]{44}$/.test(id)) return false;
+  const given = Buffer.from(id.slice(ID_LEN));
+  const expected = Buffer.from(sign(id.slice(0, ID_LEN), signingKey));
+  return (
+    given.length === expected.length && crypto.timingSafeEqual(given, expected)
+  );
+}
+
+module.exports = { deriveSigningKey, isValidActionId };

package/undo/lib/capture-guard.js

@@ -0,0 +1,8 @@
+// lib/capture-guard.js
+"use strict";
+const { AsyncLocalStorage } = require("async_hooks");
+const als = new AsyncLocalStorage();
+module.exports = {
+  runUnhooked: (fn) => als.run(true, fn),
+  isUnhooked: () => als.getStore() === true,
+};

package/undo/lib/capture-mongo.js

@@ -0,0 +1,341 @@
+// lib/capture-mongo.js
+"use strict";
+// MONGODB CAPTURE: saves before/after documents of tagged writes, on the host's own connection.
+// Handles insertOne/insertMany, updateOne/updateMany/replaceOne, deleteOne/deleteMany and
+// findOneAndUpdate/findOneAndReplace/findOneAndDelete (what Mongoose uses for save, create, findByIdAndUpdate...).
+// Anything else that writes (bulkWrite, drop, rename, upsert, inside a host transaction) is blocked until the user confirms.
+// MongoDB has no cross-document transaction on every setup, so snapshots are saved just before the write.
+// Never throws into the host. Logs: collection names, counts and reasons only.
+
+const log = require("./log");
+const tagger = require("./tagger");
+const store = require("./snapshot-store");
+const mstore = require("./snapshot-store-mongo");
+const guard = require("./capture-guard");
+const gate = require("./gate");
+const undoMongo = require("./undo-mongo");
+
+const WRITE_KIND = {
+  insertOne: "insert",
+  insertMany: "insert",
+  updateOne: "update",
+  updateMany: "update",
+  replaceOne: "update",
+  findOneAndUpdate: "update",
+  findOneAndReplace: "update",
+  deleteOne: "delete",
+  deleteMany: "delete",
+  findOneAndDelete: "delete",
+};
+// Writes this package can never save: blocked until the user confirms.
+const UNSAVABLE = new Set([
+  "bulkWrite",
+  "drop",
+  "rename",
+  "findAndModify",
+  "findAndRemove",
+  "insert",
+  "update",
+  "remove",
+  "save",
+]);
+const HOOKED_METHODS = Object.keys(WRITE_KIND).concat(Array.from(UNSAVABLE));
+const kindOf = (m) => WRITE_KIND[m] || (UNSAVABLE.has(m) ? "other" : null);
+
+const idKey = (id) => mstore.toText({ _id: id });
+
+// Splits the host's arguments into: the host's own arguments, its callback (older drivers), filter and options.
+function parseCall(method, args) {
+  const a = Array.prototype.slice.call(args);
+  let cb = null;
+  if (typeof a[a.length - 1] === "function") cb = a.pop();
+  const kind = WRITE_KIND[method];
+  // update-type calls are (filter, update, options); insert and delete calls are (document or filter, options).
+  const optIndex = kind === "update" ? 2 : 1;
+  const options = a[optIndex];
+  return {
+    hostArgs: a,
+    cb,
+    filter: a[0],
+    options: options && typeof options === "object" ? options : {},
+  };
+}
+
+// The documents an insert call hands to the driver, or null if the shape is not understood.
+function docsOf(ctx) {
+  const first = ctx.call.hostArgs[0];
+  const list = ctx.method === "insertMany" ? first : [first];
+  if (!Array.isArray(list) || list.some((d) => !d || typeof d !== "object"))
+    return null;
+  return list;
+}
+
+// Reading too many documents is safe, too few is not (same rule as the SQL hooks).
+async function readMatching(col, filter, options) {
+  const o = {};
+  if (options.sort) o.sort = options.sort;
+  if (options.collation) o.collation = options.collation;
+  return col
+    .find(filter, o)
+    .limit(store.ROW_LIMIT + 1)
+    .toArray();
+}
+
+async function readByIds(col, ids) {
+  if (!ids.length) return [];
+  return col.find({ _id: { $in: ids } }).toArray();
+}
+
+async function removeSaved(snapCol, before) {
+  if (before && before.saved && before.saved.length)
+    await mstore.deleteByIds(
+      snapCol,
+      before.saved.map((s) => s.id),
+    );
+}
+
+// ---- INSERT ----
+
+// Before an insert: can its new documents be saved? Remembers which ids already existed, so a failed insert never claims them.
+async function planInsert(ctx, notSaved) {
+  const docs = docsOf(ctx);
+  if (!docs) {
+    notSaved("this insert shape cannot be saved");
+    return null;
+  }
+  const c = store.checkCapturable({
+    rowCount: docs.length,
+    primaryKeyColumns: ["_id"],
+  });
+  if (!c.ok) {
+    notSaved(c.reason);
+    return null;
+  }
+  const explicit = docs
+    .filter((d) => d._id !== undefined && d._id !== null)
+    .map((d) => d._id);
+  const existing = explicit.length ? await readByIds(ctx.col, explicit) : [];
+  return { keys: new Set(existing.map((r) => idKey(r._id))) };
+}
+
+async function afterInsert(ctx, plan, result, notSaved) {
+  const { col, snapCol, st, label, dbName } = ctx;
+  let ids;
+  if (result && result.insertedId !== undefined && result.insertedId !== null)
+    ids = [result.insertedId];
+  else if (
+    result &&
+    result.insertedIds &&
+    typeof result.insertedIds === "object"
+  )
+    ids = Object.keys(result.insertedIds).map((k) => result.insertedIds[k]);
+  else
+    // The insert failed part-way: use the ids the driver put on the documents.
+    ids = (docsOf(ctx) || [])
+      .map((d) => d._id)
+      .filter((id) => id !== undefined && id !== null);
+  ids = ids.filter((id) => !plan.keys.has(idKey(id)));
+  if (!ids.length) {
+    return;
+  }
+  const rows = await readByIds(col, ids);
+  let n = 0;
+  for (const row of rows) {
+    const r = await mstore.saveSnapshot(snapCol, st, {
+      dbName,
+      collName: col.collectionName,
+      operation: "insert",
+      id: row._id,
+      before: null,
+      after: row,
+      hasAfter: true,
+    });
+    if (!r.ok) return notSaved(r.reason);
+    n++;
+  }
+}
+
+// ---- UPDATE / DELETE ----
+
+async function beforeChange(ctx, kind, notSaved) {
+  const { col, snapCol, call, st, dbName } = ctx;
+  const rows = await readMatching(col, call.filter, call.options);
+  const c = store.checkCapturable({
+    rowCount: rows.length,
+    primaryKeyColumns: ["_id"],
+  });
+  if (!c.ok) {
+    notSaved(c.reason);
+    return null;
+  }
+  const saved = [];
+  for (const row of rows) {
+    const r = await mstore.saveSnapshot(snapCol, st, {
+      dbName,
+      collName: col.collectionName,
+      operation: kind,
+      id: row._id,
+      before: row,
+      after: null,
+      hasAfter: kind === "delete", // a deleted document has no after-state
+    });
+    if (!r.ok) {
+      notSaved(r.reason);
+      return { saved }; // the caller removes what was saved so far
+    }
+    saved.push({ id: r.id, key: idKey(row._id), docId: row._id, doc: row });
+  }
+  return { saved };
+}
+
+// After the write: keep only the snapshots of documents this write really changed or removed.
+async function afterChange(ctx, kind, before) {
+  const { col, snapCol, st, label } = ctx;
+  const now = await readByIds(
+    col,
+    before.saved.map((s) => s.docId),
+  );
+  const byKey = new Map(now.map((r) => [idKey(r._id), r]));
+  const drop = [];
+  let kept = 0;
+  for (const s of before.saved) {
+    const cur = byKey.get(s.key);
+    if (kind === "delete") {
+      if (cur)
+        drop.push(s.id); // still there: this write did not delete it
+      else kept++;
+      continue;
+    }
+    if (!cur || mstore.canonOf(cur) === mstore.canonOf(s.doc)) {
+      drop.push(s.id); // unchanged (or gone): nothing of this write to undo
+      continue;
+    }
+    await mstore.saveAfter(snapCol, s.id, cur);
+    kept++;
+  }
+  await mstore.deleteByIds(snapCol, drop);
+}
+
+// ---- the whole job for one tagged write ----
+
+async function runCapture(ctx, hostCall) {
+  const { snapCol, method, st, label } = ctx;
+  const kind = WRITE_KIND[method];
+  let phase = "before"; // "before" = the write has not run yet, so it can still be blocked
+  let failedWhy = null;
+  const notSaved = (why) => {
+    if (phase === "before") failedWhy = failedWhy || why;
+    if (phase !== "before" || st.confirmed) st.unsaved = true; // the write runs (or already ran) without a saved snapshot
+  };
+
+  let before = null;
+  let plan = null;
+  try {
+    if (kind === "insert") plan = await planInsert(ctx, notSaved);
+    else before = await beforeChange(ctx, kind, notSaved);
+  } catch (e) {
+    notSaved("capture error " + ((e && e.code) || "unknown"));
+  }
+
+  // Cannot be saved: remove what was saved so far (a half-saved set could restore only part of the data), then block unless confirmed.
+  if (failedWhy) {
+    await removeSaved(snapCol, before);
+    before = null;
+    if (!st.confirmed) await gate.block(st, label, failedWhy);
+  }
+
+  phase = "after";
+  let result;
+  let hostErr = null;
+  try {
+    result = await hostCall();
+  } catch (e) {
+    hostErr = e;
+  }
+  // Also runs when the host's write failed: many-document writes can stop part-way, and only changed documents are kept.
+  try {
+    if (!failedWhy) {
+      if (kind === "insert") await afterInsert(ctx, plan, result, notSaved);
+      else if (before && before.saved.length)
+        await afterChange(ctx, kind, before);
+    }
+  } catch (e) {
+    notSaved("capture error " + ((e && e.code) || "unknown"));
+  }
+  if (hostErr) throw hostErr;
+  return result;
+}
+
+// Returns { value } when capture took over (it runs the host's write itself, or blocks it), otherwise null.
+// original = the driver's own method, so our reads and the host's write never go through the hook again.
+function maybeCapture(col, method, args, original) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked()) return null;
+  if (!kindOf(method)) return null;
+  if (store.isOwnTable(col.collectionName)) return null;
+
+  const call = parseCall(method, args);
+  const db = col.s && col.s.db;
+  const dbName = col.dbName || (db && db.databaseName) || "?";
+  const label = dbName + "." + col.collectionName;
+
+  // A write that cannot be saved: blocked until the user confirms (or runs unsaved if they already did).
+  const refuse = (why) => {
+    if (st.confirmed) {
+      st.unsaved = true; // runs without a saved snapshot, so Undo will not cover it
+      return null;
+    }
+    const p = gate.block(st, label + " " + method, why);
+    if (call.cb) {
+      p.then(null, (e) => process.nextTick(call.cb, e));
+      return { value: undefined };
+    }
+    return { value: p };
+  };
+
+  const kind = WRITE_KIND[method];
+  if (!kind) return refuse(method + " cannot be saved");
+  if (call.options.session) return refuse("inside a host transaction");
+  if (kind === "update" && call.options.upsert)
+    return refuse("upsert cannot be saved");
+  if (!mstore.hasEJSON())
+    return refuse("the driver's BSON library was not found (driver too old?)");
+  if (!db || typeof db.collection !== "function")
+    return refuse("database object not reachable");
+  if (
+    kind !== "insert" &&
+    (!call.filter ||
+      typeof call.filter !== "object" ||
+      Array.isArray(call.filter))
+  )
+    return refuse("this filter shape cannot be saved");
+  const chk = store.checkCapturable({
+    rowCount: 0,
+    primaryKeyColumns: ["_id"],
+  });
+  if (!chk.ok) return refuse(chk.reason);
+
+  undoMongo.remember(db); // Undo reuses the host's own database object
+  const ctx = {
+    col,
+    snapCol: db.collection(store.TABLE),
+    method,
+    call,
+    st,
+    label,
+    dbName,
+  };
+  const p = runCapture(ctx, () =>
+    Promise.resolve(original.apply(col, call.hostArgs)),
+  );
+  if (call.cb) {
+    p.then(
+      (r) => process.nextTick(call.cb, null, r),
+      (e) => process.nextTick(call.cb, e),
+    );
+    return { value: undefined };
+  }
+  return { value: p };
+}
+
+module.exports = { maybeCapture, HOOKED_METHODS, kindOf };