botversion-sdk 2.2.3 → 2.3.0

package/undo/lib/setup-check.js

@@ -0,0 +1,294 @@
+// lib/setup-check.js
+"use strict";
+// SETUP CHECK (Phase 1) - optional, run by the HOST in their own terminal:
+//   npx botversion-undo-exp setup [ENV_VAR_NAME]
+// Checks that the snapshot table exists and is writable. Postgres only, needs the host's own `pg` driver.
+// The connection string is read from a hidden prompt (or a named environment variable), kept only in memory,
+// never printed, logged, stored or sent anywhere. The only network call is to the host's own database.
+
+const readline = require("readline");
+const crypto = require("crypto");
+const log = require("./log");
+const { findHostRoot } = require("./scanner");
+
+const TABLE = "botversion_undo_snapshots";
+const COLUMNS = [
+  "id",
+  "action_id",
+  "seq",
+  "table_name",
+  "operation",
+  "primary_key",
+  "before_data",
+  "after_data",
+  "is_linked",
+  "requester_hash",
+  "status",
+  "created_at",
+  "expires_at",
+];
+
+// Reads one line without showing what is typed (so the URL is not visible on screen or in shell history).
+function askHidden(question) {
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    const stdin = process.stdin;
+    if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+      const rl = readline.createInterface({ input: stdin });
+      rl.once("line", (line) => {
+        rl.close();
+        resolve(line);
+      });
+      rl.once("close", () => resolve(""));
+      return;
+    }
+    let value = "";
+    const finish = () => {
+      stdin.removeListener("data", onData);
+      stdin.setRawMode(false);
+      stdin.pause();
+      process.stdout.write("\n");
+    };
+    const onData = (chunk) => {
+      for (const ch of String(chunk)) {
+        if (ch === "\r" || ch === "\n") {
+          finish();
+          resolve(value);
+          return;
+        }
+        if (ch === "\u0003") {
+          finish();
+          process.exit(130);
+        }
+        if (ch === "\u007f" || ch === "\b") {
+          value = value.slice(0, -1);
+          continue;
+        }
+        if (ch >= " ") value += ch;
+      }
+    };
+    stdin.setEncoding("utf8");
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  });
+}
+
+// Host name only (never the user, password or database name).
+function hostOf(url) {
+  try {
+    return new URL(url).hostname || "unknown";
+  } catch (_) {
+    return "unknown";
+  }
+}
+
+async function run() {
+  const say = (line) => log.info(line);
+  say("-".repeat(64));
+  say(
+    "UNDO SETUP CHECK - run by you, in your terminal. Nothing is sent anywhere except to your own database.",
+  );
+
+  // 1. The host's own pg driver.
+  let Client;
+  try {
+    const resolved = require.resolve("pg", {
+      paths: [findHostRoot(), process.cwd()],
+    });
+    Client = require(resolved).Client;
+  } catch (_) {
+    say(
+      'This check needs the "pg" (Postgres) driver in your project, and it was not found.',
+    );
+    say(
+      "Projects that use only Prisma (no pg) cannot run this check yet. Skipping it never breaks anything:",
+    );
+    say(
+      'if the table is missing, Undo switches itself off for that action and asks "Are you sure?" instead.',
+    );
+    say("-".repeat(64));
+    process.exitCode = 1;
+    return;
+  }
+
+  // 2. The connection string: a named environment variable, or a hidden prompt.
+  const varName = process.argv[3];
+  let url = "";
+  if (varName) {
+    url = process.env[varName] || "";
+    if (!url) {
+      say(
+        `The environment variable "${varName}" is empty or not set in this terminal.`,
+      );
+      say(
+        "Run the command again without a name to paste the URL into a hidden prompt instead.",
+      );
+      say("-".repeat(64));
+      process.exitCode = 1;
+      return;
+    }
+    say(
+      `Using the environment variable ${varName} (its value is never printed).`,
+    );
+  } else {
+    url = await askHidden(
+      "Paste your database URL and press Enter (nothing is shown, saved or sent): ",
+    );
+  }
+  url = String(url)
+    .trim()
+    .replace(/^["']|["']$/g, "");
+
+  // Anything that could appear in an error message is scrubbed of the URL and its password.
+  const secrets = [url];
+  try {
+    const u = new URL(url);
+    if (u.password) secrets.push(u.password, decodeURIComponent(u.password));
+  } catch (_) {
+    /* ignore */
+  }
+  const scrub = (text) => {
+    let t = String(text || "");
+    for (const s of secrets)
+      if (s && s.length >= 3) t = t.split(s).join("[hidden]");
+    return t.slice(0, 200);
+  };
+
+  if (!/^postgres(ql)?:\/\//i.test(url)) {
+    say(
+      "That does not look like a Postgres URL (it should start with postgres:// or postgresql://). Nothing was checked.",
+    );
+    say("-".repeat(64));
+    process.exitCode = 1;
+    return;
+  }
+
+  say(`Checking the database on host: ${hostOf(url)}`);
+
+  let client;
+  try {
+    client = new Client({
+      connectionString: url,
+      connectionTimeoutMillis: 10000,
+      query_timeout: 15000,
+    });
+  } catch (_) {
+    say("Could not read that URL. Nothing was checked.");
+    say("-".repeat(64));
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    await client.connect();
+
+    // 3. Does the table exist, with every column?
+    const found = await client.query("SELECT to_regclass($1::text) AS t", [
+      TABLE,
+    ]);
+    if (!found.rows[0].t) {
+      say(
+        `Undo setup NOT done: the table "${TABLE}" does not exist in this database.`,
+      );
+      say(
+        "Run the snapshot table command (from the dashboard, the guide, or the SDK startup message), then run this check again.",
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const cols = await client.query(
+      "SELECT a.attname AS name FROM pg_attribute a WHERE a.attrelid = to_regclass($1::text) AND a.attnum > 0 AND NOT a.attisdropped",
+      [TABLE],
+    );
+    const have = new Set(cols.rows.map((r) => r.name));
+    const missing = COLUMNS.filter((c) => !have.has(c));
+    if (missing.length) {
+      say(
+        `Undo setup NOT done: the table exists but these columns are missing: ${missing.join(", ")}`,
+      );
+      say("Create the table again with the exact snapshot table command.");
+      process.exitCode = 1;
+      return;
+    }
+
+    // 4. Write one test row, read it back, delete it. All in one transaction: a failure leaves nothing behind.
+    const id = crypto.randomUUID();
+    await client.query("BEGIN");
+    try {
+      await client.query(
+        `INSERT INTO ${TABLE} (id, action_id, seq, table_name, operation, primary_key, expires_at) VALUES ($1, 'botversion-setup-check', 0, 'setup-check', 'insert', 'setup-check', now())`,
+        [id],
+      );
+      const back = await client.query(`SELECT id FROM ${TABLE} WHERE id = $1`, [
+        id,
+      ]);
+      if (back.rowCount !== 1)
+        throw new Error("the test row was saved but could not be read back");
+      await client.query(
+        `UPDATE ${TABLE} SET after_data = 'setup-check' WHERE id = $1`,
+        [id],
+      );
+      await client.query(`DELETE FROM ${TABLE} WHERE id = $1`, [id]);
+      await client.query("COMMIT");
+    } catch (e) {
+      try {
+        await client.query("ROLLBACK");
+      } catch (_) {
+        /* ignore */
+      }
+      throw e;
+    }
+
+    say(
+      `Undo setup OK: the table exists, has every column, and this login can write to it (host: ${hostOf(url)}).`,
+    );
+    say("Limits of this check:");
+    say(
+      "  - It checked only the database you pasted. Run it once for each environment (test, production).",
+    );
+    say(
+      "  - A production database behind a firewall may not be reachable from this computer.",
+    );
+    say(
+      "  - It proves THIS login works, not necessarily the login your app uses.",
+    );
+    say(
+      '  - It needs the "pg" driver, so Prisma-only projects cannot run it yet.',
+    );
+  } catch (e) {
+    const code = e && e.code;
+    const reason = scrub(e && e.message);
+    if (code === "42501") {
+      say(
+        "Undo setup NOT done: this login is not allowed to write to the snapshot table. Grant it INSERT, SELECT, UPDATE and DELETE on that table.",
+      );
+    } else if (code === "28P01" || code === "28000") {
+      say("Could not log in: the user or password was refused.");
+    } else if (
+      code === "ENOTFOUND" ||
+      code === "ECONNREFUSED" ||
+      code === "ETIMEDOUT"
+    ) {
+      say(
+        "Could not reach the database. Check the host, the port, your network and any firewall.",
+      );
+    } else if (/ssl/i.test(reason)) {
+      say(
+        "The database connection failed on SSL. If your database requires SSL, add ?sslmode=require to the URL; if it does not allow SSL, add ?sslmode=disable.",
+      );
+    } else {
+      say("Undo setup NOT done: " + reason);
+    }
+    process.exitCode = 1;
+  } finally {
+    try {
+      await client.end();
+    } catch (_) {
+      /* ignore */
+    }
+    say("-".repeat(64));
+  }
+}
+
+module.exports = { run };

package/undo/lib/snapshot-crypto.js

@@ -0,0 +1,96 @@
+// lib/snapshot-crypto.js
+"use strict";
+// SNAPSHOT ENCRYPTION (Phase 2)
+// Encrypts the rows saved in the snapshot table with AES-256-GCM.
+// The key is derived from the host's BotVersion API key (a different key from the one that signs action ids).
+// The API key itself is never kept, logged or sent. This file never prints anything.
+
+const crypto = require("crypto");
+
+const PREFIX = "v1:";
+let key = null;
+
+// Derives the encryption key. No usable API key = no key = nothing can be saved.
+function setApiKey(apiKey) {
+  try {
+    key =
+      typeof apiKey === "string" && apiKey.trim()
+        ? crypto
+            .createHmac("sha256", apiKey)
+            .update("botversion-snapshot-encryption-v1")
+            .digest()
+        : null;
+  } catch (_) {
+    key = null;
+  }
+}
+
+function hasKey() {
+  return !!key;
+}
+
+// Row -> JSON text, keeping types plain JSON cannot hold (dates, binary data, big numbers).
+function serialize(value) {
+  return JSON.stringify(value, function (k, v) {
+    // JSON.stringify converts dates and buffers before this function sees them, so the original is read back.
+    const raw = this[k];
+    if (raw instanceof Date) {
+      return {
+        $bv: "date",
+        v: isNaN(raw.getTime()) ? null : raw.toISOString(),
+      };
+    }
+    if (Buffer.isBuffer(raw))
+      return { $bv: "buffer", v: raw.toString("base64") };
+    if (typeof raw === "bigint") return { $bv: "bigint", v: raw.toString() };
+    return v;
+  });
+}
+
+function deserialize(text) {
+  return JSON.parse(text, function (k, v) {
+    if (v && typeof v === "object" && typeof v.$bv === "string") {
+      if (v.$bv === "date") return v.v === null ? new Date(NaN) : new Date(v.v);
+      if (v.$bv === "buffer") return Buffer.from(v.v, "base64");
+      if (v.$bv === "bigint") return BigInt(v.v);
+    }
+    return v;
+  });
+}
+
+// value (any row or key object) -> "v1:" + base64url(iv + tag + encrypted text)
+function encrypt(value) {
+  if (!key) throw new Error("no encryption key");
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  const data = Buffer.concat([
+    cipher.update(serialize(value), "utf8"),
+    cipher.final(),
+  ]);
+  return (
+    PREFIX +
+    Buffer.concat([iv, cipher.getAuthTag(), data]).toString("base64url")
+  );
+}
+
+// Throws if the text was changed, or was encrypted with another key.
+function decrypt(text) {
+  if (!key) throw new Error("no encryption key");
+  if (typeof text !== "string" || !text.startsWith(PREFIX))
+    throw new Error("not an encrypted snapshot value");
+  const buf = Buffer.from(text.slice(PREFIX.length), "base64url");
+  if (buf.length < 29) throw new Error("encrypted value is too short");
+  const decipher = crypto.createDecipheriv(
+    "aes-256-gcm",
+    key,
+    buf.subarray(0, 12),
+  );
+  decipher.setAuthTag(buf.subarray(12, 28));
+  const plain = Buffer.concat([
+    decipher.update(buf.subarray(28)),
+    decipher.final(),
+  ]);
+  return deserialize(plain.toString("utf8"));
+}
+
+module.exports = { setApiKey, hasKey, encrypt, decrypt };

package/undo/lib/snapshot-sql.js

@@ -0,0 +1,180 @@
+// lib/snapshot-sql.js
+"use strict";
+// Builds the plain-language "create this table" message for the host.
+// The table is the same for every host; only the SQL dialect changes.
+
+const SQL = {
+  postgres: `CREATE TABLE botversion_undo_snapshots (
+  id            UUID PRIMARY KEY,
+  action_id     TEXT        NOT NULL,
+  seq           INTEGER     NOT NULL,
+  table_name    TEXT        NOT NULL,
+  operation     TEXT        NOT NULL,
+  primary_key   TEXT        NOT NULL,
+  before_data   TEXT,
+  after_data    TEXT,
+  is_linked     BOOLEAN     NOT NULL DEFAULT FALSE,
+  requester_hash TEXT,
+  status        TEXT        NOT NULL DEFAULT 'captured',
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  expires_at    TIMESTAMPTZ NOT NULL
+);
+CREATE INDEX botversion_undo_snapshots_action ON botversion_undo_snapshots (action_id);
+CREATE INDEX botversion_undo_snapshots_expiry ON botversion_undo_snapshots (expires_at);`,
+
+  mysql: `CREATE TABLE botversion_undo_snapshots (
+  id            CHAR(36)     NOT NULL PRIMARY KEY,
+  action_id     VARCHAR(64)  NOT NULL,
+  seq           INT          NOT NULL,
+  table_name    VARCHAR(255) NOT NULL,
+  operation     VARCHAR(16)  NOT NULL,
+  primary_key   TEXT         NOT NULL,
+  before_data   LONGTEXT     NULL,
+  after_data    LONGTEXT     NULL,
+  is_linked     TINYINT(1)   NOT NULL DEFAULT 0,
+  requester_hash VARCHAR(64) NULL,
+  status        VARCHAR(16)  NOT NULL DEFAULT 'captured',
+  created_at    DATETIME(3)  NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  expires_at    DATETIME(3)  NOT NULL,
+  INDEX botversion_undo_snapshots_action (action_id),
+  INDEX botversion_undo_snapshots_expiry (expires_at)
+);`,
+
+  sqlite: `CREATE TABLE botversion_undo_snapshots (
+  id            TEXT PRIMARY KEY,
+  action_id     TEXT    NOT NULL,
+  seq           INTEGER NOT NULL,
+  table_name    TEXT    NOT NULL,
+  operation     TEXT    NOT NULL,
+  primary_key   TEXT    NOT NULL,
+  before_data   TEXT,
+  after_data    TEXT,
+  is_linked     INTEGER NOT NULL DEFAULT 0,
+  requester_hash TEXT,
+  status        TEXT    NOT NULL DEFAULT 'captured',
+  created_at    TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+  expires_at    TEXT    NOT NULL
+);
+CREATE INDEX botversion_undo_snapshots_action ON botversion_undo_snapshots (action_id);
+CREATE INDEX botversion_undo_snapshots_expiry ON botversion_undo_snapshots (expires_at);`,
+
+  sqlserver: `CREATE TABLE botversion_undo_snapshots (
+  id            UNIQUEIDENTIFIER NOT NULL PRIMARY KEY,
+  action_id     NVARCHAR(64)     NOT NULL,
+  seq           INT              NOT NULL,
+  table_name    NVARCHAR(255)    NOT NULL,
+  operation     NVARCHAR(16)     NOT NULL,
+  primary_key   NVARCHAR(MAX)    NOT NULL,
+  before_data   NVARCHAR(MAX)    NULL,
+  after_data    NVARCHAR(MAX)    NULL,
+  is_linked     BIT              NOT NULL DEFAULT 0,
+  requester_hash NVARCHAR(64)    NULL,
+  status        NVARCHAR(16)     NOT NULL DEFAULT 'captured',
+  created_at    DATETIME2        NOT NULL DEFAULT SYSUTCDATETIME(),
+  expires_at    DATETIME2        NOT NULL
+);
+CREATE INDEX botversion_undo_snapshots_action ON botversion_undo_snapshots (action_id);
+CREATE INDEX botversion_undo_snapshots_expiry ON botversion_undo_snapshots (expires_at);`,
+};
+
+// Prisma model equivalent of the same table, per database. Used for hosts that manage their database with Prisma.
+const PRISMA_ATTRS = {
+  postgres: { id: "@db.Uuid", ts: "@db.Timestamptz(6)" },
+  mysql: {
+    id: "@db.Char(36)",
+    s64: "@db.VarChar(64)",
+    s255: "@db.VarChar(255)",
+    s16: "@db.VarChar(16)",
+    text: "@db.Text",
+    long: "@db.LongText",
+    ts: "@db.DateTime(3)",
+  },
+  sqlite: {},
+  sqlserver: {
+    id: "@db.UniqueIdentifier",
+    s64: "@db.NVarChar(64)",
+    s255: "@db.NVarChar(255)",
+    s16: "@db.NVarChar(16)",
+    text: "@db.NVarChar(Max)",
+    long: "@db.NVarChar(Max)",
+    ts: "@db.DateTime2",
+  },
+};
+
+function buildPrismaModel(dialect) {
+  const a = PRISMA_ATTRS[dialect] || PRISMA_ATTRS.postgres;
+  const x = (k) => (a[k] ? " " + a[k] : "");
+  return [
+    "model BotversionUndoSnapshot {",
+    `  id            String    @id${x("id")}`,
+    `  actionId      String    @map("action_id")${x("s64")}`,
+    "  seq           Int",
+    `  tableName     String    @map("table_name")${x("s255")}`,
+    `  operation     String${x("s16")}`,
+    `  primaryKey    String    @map("primary_key")${x("text")}`,
+    `  beforeData    String?   @map("before_data")${x("long")}`,
+    `  afterData     String?   @map("after_data")${x("long")}`,
+    '  isLinked      Boolean   @default(false) @map("is_linked")',
+    `  requesterHash String?   @map("requester_hash")${x("s64")}`,
+    `  status        String    @default("captured")${x("s16")}`,
+    `  createdAt     DateTime  @default(now()) @map("created_at")${x("ts")}`,
+    `  expiresAt     DateTime  @map("expires_at")${x("ts")}`,
+    "",
+    '  @@index([actionId], map: "botversion_undo_snapshots_action")',
+    '  @@index([expiresAt], map: "botversion_undo_snapshots_expiry")',
+    '  @@map("botversion_undo_snapshots")',
+    "}",
+  ];
+}
+
+function buildSnapshotTableMessage(st, hasPrisma) {
+  const lines = [];
+  lines.push(
+    "UNDO SNAPSHOT TABLE (not created by this package - you add it yourself, once):",
+  );
+
+  if (st && st.dialect === "mongodb") {
+    lines.push(`Database detected: ${st.label} (from ${st.source}).`);
+    lines.push(
+      'MongoDB needs nothing created: the collection "botversion_undo_snapshots" is created automatically in your database the first time an AI write is saved. The login your app uses must be allowed to insert, find, update and delete in it.',
+    );
+    return lines;
+  }
+
+  const known = st && SQL[st.dialect];
+  const dialect = known ? st.dialect : "postgres";
+
+  if (known) {
+    lines.push(`Database detected: ${st.label} (from ${st.source}).`);
+  } else {
+    lines.push("Could not tell which database this project uses.");
+    lines.push("EXAMPLE ONLY (Postgres style). Adjust to your own database.");
+  }
+  lines.push("");
+
+  if (hasPrisma) {
+    // Prisma hosts add a model and migrate, so Prisma knows about the table and reports no drift.
+    lines.push(
+      "Prisma project: add this model to your schema.prisma, then run your normal migration:",
+    );
+    lines.push("");
+    buildPrismaModel(dialect).forEach((l) => lines.push(l));
+    lines.push("");
+    lines.push(
+      "  Development: npx prisma migrate dev --name add_botversion_undo_snapshots",
+    );
+    lines.push("  Production:  npx prisma migrate deploy");
+  } else {
+    lines.push("Run this in that database:");
+    lines.push("");
+    SQL[dialect].split("\n").forEach((l) => lines.push(l));
+  }
+
+  lines.push("");
+  lines.push(
+    'Keep the table name exactly "botversion_undo_snapshots" (the model above already maps to it).',
+  );
+  return lines;
+}
+
+module.exports = { buildSnapshotTableMessage };