kryptheon-night 0.1.3 → 0.1.5

package/installer.js

@@ -0,0 +1,224 @@
+// The second door: the engine stays put, and pg_cron calls it at night.
+//
+// Down `npx` the engine is installed into a throwaway schema, used, and
+// dropped inside one command - the connection string never leaves the
+// person's machine, but they have to run it. This door is for the thing they
+// will not do every week. The same functions are installed once, pg_cron runs
+// `nightly()` at three in the morning, and nothing about it needs a
+// credential to move anywhere, because nothing moves: the work happens where
+// the data already is.
+//
+// Everything here is written around one rule, and it is the rule fixture.js
+// learned the expensive way: **only remove what you created**. A database
+// that already had pg_cron in it before Kryptheon arrived must still have it
+// afterwards, and a customer who removes Kryptheon must not be left with a
+// nightly job nobody owns. So install writes down what it made, in a table
+// inside its own schema, and uninstall reads that list before it drops
+// anything.
+//
+// Measured on a real Supabase project before any of this was written:
+//
+//   pg_net lands in `public` - the customer's own schema - unless it is told
+//     where to go, so it is always told.
+//   cron.unschedule is overloaded on (bigint) and (name), and an uncast
+//     parameter binds to the name one and fails with "could not find valid
+//     entry for job", which reads like the job was already gone.
+
+const sqlengine = require('./sqlengine.js');
+
+// Where the engine lives when it is staying. A fixed name rather than a
+// timestamped one: the throwaway copies are named for the moment they were
+// made so an abandoned one can be aged and swept, and this is the opposite -
+// it is meant to be found again.
+const SCHEMA = 'kryptheon';
+
+// Three in the morning, in whatever the database thinks the time is. Late
+// enough to be quiet, early enough that the answer is waiting before anybody
+// looks.
+const AT = '0 3 * * *';
+
+const quote = (name) => '"' + String(name).split('"').join('""') + '"';
+
+/** Is this extension already here, and did we have to put it here? */
+async function extensionState(client, name) {
+  const { rows } = await client.query(
+    'SELECT installed_version FROM pg_available_extensions WHERE name = $1', [name],
+  );
+  if (!rows.length) return { available: false, installed: false };
+  return { available: true, installed: Boolean(rows[0].installed_version) };
+}
+
+/**
+ * Puts an extension where it belongs, and says whether it had to.
+ *
+ * `pg_net` installs into whatever the search_path says unless it is told
+ * otherwise, and on Supabase that is `public`. Watching it appear in a
+ * customer's own schema is what made this function exist rather than a line
+ * of SQL.
+ */
+async function ensureExtension(client, name, into) {
+  const state = await extensionState(client, name);
+  if (!state.available) {
+    throw new Error(
+      'this database does not offer ' + name + ', so the nightly run cannot be installed. ' +
+      'Supabase has it; a plain Postgres may not.',
+    );
+  }
+  if (state.installed) return { made: false };
+
+  const haveSchema = into
+    ? (await client.query('SELECT count(*)::int n FROM pg_namespace WHERE nspname = $1', [into])).rows[0].n > 0
+    : false;
+  await client.query('CREATE EXTENSION ' + name + (haveSchema ? ' WITH SCHEMA ' + quote(into) : ''));
+  return { made: true, into: haveSchema ? into : null };
+}
+
+/**
+ * Installs the engine, schedules the night, and writes down what it made.
+ *
+ * Safe to run twice: the engine is CREATE OR REPLACE throughout, and the job
+ * is replaced rather than added to, so an upgrade is the same operation as an
+ * install.
+ */
+async function install(client, options) {
+  const opts = options || {};
+  const schema = opts.schema || SCHEMA;
+  const source = opts.source || 'public';
+  const at = opts.at || AT;
+  const made = { extensions: [], schema: false, jobid: null };
+
+  // pg_net first: it is the one that lands in the wrong place if nobody
+  // says where, and it is easier to take back out before anything depends
+  // on it.
+  const net = await ensureExtension(client, 'pg_net', 'extensions');
+  if (net.made) made.extensions.push('pg_net');
+
+  const cron = await ensureExtension(client, 'pg_cron', null);
+  if (cron.made) made.extensions.push('pg_cron');
+
+  const existed = (await client.query(
+    'SELECT count(*)::int n FROM pg_namespace WHERE nspname = $1', [schema],
+  )).rows[0].n > 0;
+  made.schema = !existed;
+
+  await sqlengine.install(client, schema);
+
+  // What this install created, kept where uninstall can find it and nowhere
+  // else. In the schema it is about to drop, on purpose: if the schema is
+  // gone, so is everything this list describes.
+  await client.query(
+    'CREATE TABLE IF NOT EXISTS ' + quote(schema) + '.installed (' +
+      'id integer PRIMARY KEY DEFAULT 1, ' +
+      'installed_at timestamptz NOT NULL DEFAULT now(), ' +
+      'source text NOT NULL, ' +
+      'made_extensions text[] NOT NULL DEFAULT \'{}\', ' +
+      'made_schema boolean NOT NULL DEFAULT false, ' +
+      'jobid bigint, ' +
+      'CONSTRAINT only_one CHECK (id = 1))',
+  );
+
+  // Replaced rather than added to. cron.schedule with a name that already
+  // exists updates it, but an install that ran twice under two names would
+  // attack the same app twice a night for ever.
+  const { rows } = await client.query(
+    'SELECT cron.schedule($1, $2, $3) AS jobid',
+    ['kryptheon_nightly', at, 'SELECT ' + quote(schema) + '.nightly(' + literal(source) + ')'],
+  );
+  made.jobid = rows[0].jobid;
+
+  await client.query(
+    'INSERT INTO ' + quote(schema) + '.installed (id, source, made_extensions, made_schema, jobid) ' +
+      'VALUES (1, $1, $2, $3, $4) ' +
+      'ON CONFLICT (id) DO UPDATE SET source = EXCLUDED.source, jobid = EXCLUDED.jobid, ' +
+      'made_extensions = ' + quote(schema) + '.installed.made_extensions || EXCLUDED.made_extensions, ' +
+      'installed_at = now()',
+    [source, made.extensions, made.schema, made.jobid],
+  );
+
+  return { schema: schema, source: source, at: at, jobid: made.jobid, made: made };
+}
+
+/** A string, quoted the way Postgres wants it inside another statement. */
+function literal(text) {
+  return "'" + String(text).split("'").join("''") + "'";
+}
+
+/** What is installed, or null. */
+async function status(client, options) {
+  const schema = (options || {}).schema || SCHEMA;
+  const here = (await client.query(
+    'SELECT count(*)::int n FROM pg_namespace WHERE nspname = $1', [schema],
+  )).rows[0].n > 0;
+  if (!here) return null;
+
+  const { rows } = await client.query(
+    'SELECT source, installed_at, jobid, made_extensions, made_schema FROM ' +
+      quote(schema) + '.installed WHERE id = 1',
+  ).catch(() => ({ rows: [] }));
+  if (!rows.length) return { schema: schema, source: null, jobid: null, unrecorded: true };
+
+  const job = await client.query(
+    'SELECT jobname, schedule, active FROM cron.job WHERE jobid = $1', [rows[0].jobid],
+  ).catch(() => ({ rows: [] }));
+
+  return Object.assign({ schema: schema }, rows[0], { job: job.rows[0] || null });
+}
+
+/**
+ * Takes it all away, and only what was put here.
+ *
+ * The order matters. The job goes first, because a job whose function has
+ * been dropped runs every night and fails every night, and pg_cron keeps
+ * every one of those failures in a log nobody reads.
+ */
+async function uninstall(client, options) {
+  const schema = (options || {}).schema || SCHEMA;
+  const removed = { job: false, schema: false, extensions: [] };
+
+  const was = await status(client, { schema: schema });
+  if (!was) return removed;
+
+  if (was.jobid) {
+    // Cast on purpose. cron.unschedule is overloaded on (bigint) and (name),
+    // and a parameter sent as text binds to the name overload and goes
+    // looking for a job CALLED '1'. It fails with "could not find valid entry
+    // for job", which reads exactly like the job having already gone - so the
+    // uninstall would have reported success and left the job running.
+    await client.query('SELECT cron.unschedule($1::bigint)', [was.jobid]).catch(() => {});
+    const left = await client.query(
+      'SELECT count(*)::int n FROM cron.job WHERE jobid = $1', [was.jobid],
+    ).catch(() => ({ rows: [{ n: 0 }] }));
+    if (left.rows[0].n) {
+      throw new Error('the nightly job ' + was.jobid + ' is still scheduled, so nothing else was removed');
+    }
+    removed.job = true;
+  }
+
+  if (was.made_schema !== false) {
+    await client.query('DROP SCHEMA IF EXISTS ' + quote(schema) + ' CASCADE');
+    removed.schema = true;
+  } else {
+    // The schema was somebody else's before we arrived. Take the engine's own
+    // things out of it and leave the schema itself where it was.
+    await sqlengine.uninstall(client, schema).catch(() => {});
+  }
+
+  // Extensions last, and only ours. A database that had pg_cron before
+  // Kryptheon arrived must still have it afterwards - and dropping pg_cron
+  // would take every other job in it with it.
+  for (const ext of was.made_extensions || []) {
+    await client.query('DROP EXTENSION IF EXISTS ' + ext).catch(() => {});
+    removed.extensions.push(ext);
+  }
+
+  return removed;
+}
+
+module.exports = {
+  SCHEMA: SCHEMA,
+  AT: AT,
+  install: install,
+  uninstall: uninstall,
+  status: status,
+  extensionState: extensionState,
+};

package/intro.js

@@ -98,6 +98,57 @@ function consentLines(target) {
   ];
 }
 
+/**
+ * What staying costs, said before anything is left behind.
+ *
+ * The scan's consent screen above ends "I do not leave anything behind", and
+ * that is true of a scan and false of an install. Reusing it here would be
+ * the product lying on the one screen it exists to be honest on, so this is
+ * its own text and says the opposite plainly, first.
+ *
+ * Everything that gets left is named, because "it installs a few things" is
+ * the sentence somebody agrees to and then finds a `cron` schema they did not
+ * recognise. And the way out is on the screen where they say yes, not in a
+ * README they will not read again.
+ */
+function installConsentLines(schema, source, at) {
+  return [
+    'This one stays. Everything else this tool does is temporary; this is not.',
+    '',
+    'What I will leave in your database:',
+    '',
+    '  - A schema called "' + schema + '", holding the functions that do the',
+    '    checking. No data of yours goes in it.',
+    '',
+    '  - Two Postgres extensions, if they are not already there: pg_cron, which',
+    '    runs things on a schedule, and pg_net. Supabase provides both.',
+    '',
+    '  - One scheduled job, named kryptheon_nightly, set to ' + at + '.',
+    '',
+    'What it will do, every night:',
+    '',
+    '  - Exactly what the scan does now - copy the shape of your "' + source + '"',
+    '    tables into a temporary space, put two made-up people in it, attack',
+    '    that, write down what got through, and delete the copy.',
+    '',
+    '  - It still never reads your real data, and still sends nothing anywhere.',
+    '    Nothing leaves your database, because the checking happens inside it.',
+    '',
+    'One thing it cannot do:',
+    '',
+    '  - It cannot race two requests against each other, which is how the',
+    '    "can this exist twice" question is answered. That needs two',
+    '    connections at the same instant, and nothing living inside a database',
+    '    has them. The nightly report names every column it could not race.',
+    '    Running the command by hand still tests them properly.',
+    '',
+    'To take it all away again:  npx kryptheon-night uninstall',
+    '',
+    'That removes the job, the schema, and any extension I had to add - and',
+    'leaves alone anything that was already here.',
+  ];
+}
+
 /** Asks a question and hands back what was typed. */
 function ask(question) {
   return new Promise((resolve) => {
@@ -191,6 +242,7 @@ async function askForConnection(say) {
 module.exports = {
   whereToFindIt: whereToFindIt,
   consentLines: consentLines,
+  installConsentLines: installConsentLines,
   ask: ask,
   askSecret: askSecret,
   askYesNo: askYesNo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon-night",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Attacks a copy of your Supabase database and tells you in plain English what got in.",
   "license": "MIT",
   "type": "commonjs",
@@ -20,13 +20,16 @@
     "intro.js",
     "trouble.js",
     "connect.js",
-    "README.md"
+    "README.md",
+    "installer.js",
+    "sqlengine.js",
+    "engine.sql"
   ],
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "check": "node package.check.js && node trouble.check.js && node intro.check.js && node finding.check.js && node recheck.check.js && node untouched.check.js && node blocked.check.js && node orphans.check.js && node guests.check.js && node usable.check.js && node twin.check.js && node external.check.js && node schema.check.js && node collision.check.js && node tamper.check.js && node orphan.check.js && node shapes.check.js && node verdicts.check.js && node loop.check.js",
+    "check": "node package.check.js && node trouble.check.js && node intro.check.js && node finding.check.js && node recheck.check.js && node untouched.check.js && node blocked.check.js && node orphans.check.js && node guests.check.js && node usable.check.js && node twin.check.js && node engines.check.js && node external.check.js && node schema.check.js && node collision.check.js && node tamper.check.js && node orphan.check.js && node shapes.check.js && node verdicts.check.js && node loop.check.js",
     "check:dry": "node package.check.js && node trouble.check.js && node intro.check.js && node finding.check.js && node recheck.check.js",
     "check:package": "node package.check.js",
     "check:trouble": "node trouble.check.js",
@@ -52,7 +55,9 @@
     "check:interruption": "node orphan.check.js",
     "probe:orphan": "node probe-orphan.js",
     "check:twin": "node twin.check.js",
-    "prepublishOnly": "node package.check.js"
+    "prepublishOnly": "node package.check.js",
+    "check:engines": "node engines.check.js",
+    "check:installer": "node installer.check.js"
   },
   "keywords": [
     "supabase",

package/scan.js

@@ -112,6 +112,35 @@ function suggest(schemas) {
     worth.map((entry) => entry.schema + ' (' + entry.tables + ')').join(', ');
 }
 
+/**
+ * The engine, as six operations, so the scan does not know which one it has.
+ *
+ * `scan.js` named `schema.js`, `attack.js`, `tamper.js` and `orphan.js`
+ * directly, which meant the SQL engine could only ever be reached by the twin
+ * check. Two engines and one of them never on the real path is how the unused
+ * one rots however good the comparison is.
+ *
+ * Deliberately not included: the collision race. It needs two requests in
+ * flight at once, which needs two connections, and no credential ever moves
+ * into the database - so the SQL engine cannot have it and says so. The scan
+ * keeps racing for real down `openSession` whichever engine it is given, and
+ * the report says what could not be raced when there is no second connection.
+ * That is the one place the two doors are honestly not the same, and it is
+ * named rather than papered over.
+ */
+function nodeEngine() {
+  return {
+    name: 'node',
+    readSchema: (client, target) => schema.readSchema(client, target),
+    writeSchema: (client, plan, into) => schema.writeSchema(client, plan, into),
+    seed: (client, into, tables) => attack.seed(client, into, tables),
+    impersonate: (client, into, tables) => attack.impersonate(client, into, tables),
+    tamper: (client, into, tables, seeded, policies) =>
+      tamper.tamper(client, into, tables, seeded, policies),
+    orphan: (client, into, tables, seeded) => orphan.orphan(client, into, tables, seeded),
+  };
+}
+
 /**
  * Runs the whole thing and hands back what got through.
  *
@@ -122,6 +151,8 @@ async function scan(client, sourceSchema, options) {
   const opts = options || {};
   const copyName = 'kn_' + Date.now().toString(36);
   const say = opts.quiet ? () => {} : line;
+  // Whichever engine the caller handed over, or the one built in.
+  const engine = opts.engine || nodeEngine();
 
   // Anything an earlier run could not clean up after itself. The copy is
   // dropped in a `finally`, but a `finally` needs a connection: when the link
@@ -147,7 +178,7 @@ async function scan(client, sourceSchema, options) {
   }
 
   say('  Reading the shape of ' + sourceSchema + ' ...');
-  const plan = await schema.readSchema(client, sourceSchema);
+  const plan = await engine.readSchema(client, sourceSchema);
 
   if (!plan.tables.length) {
     // Nothing wrong with the database, but nothing was tested either, and
@@ -171,8 +202,8 @@ async function scan(client, sourceSchema, options) {
   say('  ' + plan.tables.length + ' tables, ' + plan.policies.length + ' rules. Building a copy ...');
 
   try {
-    await schema.writeSchema(client, plan, copyName);
-    const copyPlan = await schema.readSchema(client, copyName);
+    await engine.writeSchema(client, plan, copyName);
+    const copyPlan = await engine.readSchema(client, copyName);
 
     // The copy has to be the app, or nothing that follows means anything.
     const differences = schema.diffSchemas(plan, copyPlan);
@@ -192,7 +223,7 @@ async function scan(client, sourceSchema, options) {
     // from every attack, and a table nobody attacks has nothing to report.
     const standIns = new Set((plan.external || []).map((entry) => entry.stub));
     const theirs = copyPlan.tables.filter((table) => !standIns.has(table.name));
-    const sown = await attack.seed(client, copyName, theirs);
+    const sown = await engine.seed(client, copyName, theirs);
 
     // Views are read but never seeded: they have no rows of their own, they
     // show the rows of the tables underneath. That is exactly why they matter
@@ -206,7 +237,7 @@ async function scan(client, sourceSchema, options) {
       rlsEnabled: false,
       isView: true,
     }));
-    const impersonation = await attack.impersonate(client, copyName, theirs.concat(views));
+    const impersonation = await engine.impersonate(client, copyName, theirs.concat(views));
 
     // Every attack genuinely run, named the way a finding is named. The
     // re-check needs this: a finding that disappears because its attack never
@@ -246,7 +277,7 @@ async function scan(client, sourceSchema, options) {
     // The copy's own policies, not the app's - they are the same rules, and
     // the copy is what was actually attacked. The report needs them to say
     // which rule let a write through rather than assuming one.
-    const writes = await tamper.tamper(client, copyName, theirs, sown.seeded, copyPlan.policies);
+    const writes = await engine.tamper(client, copyName, theirs, sown.seeded, copyPlan.policies);
     for (const key of writes.completed) attempted.push(key);
     for (const stuck of writes.blocked) {
       notChecked.push({ table: stuck.table, key: stuck.key, why: stuck.why });
@@ -254,7 +285,7 @@ async function scan(client, sourceSchema, options) {
 
     // Can a half-finished write survive? Rolled back like the writes above.
     say('  Looking for rows that could point at nothing ...');
-    const stranded = await orphan.orphan(client, copyName, theirs, sown.seeded);
+    const stranded = await engine.orphan(client, copyName, theirs, sown.seeded);
     for (const key of stranded.completed) attempted.push(key);
     for (const missed of stranded.notTried) {
       notChecked.push({

package/sqlengine.js

@@ -0,0 +1,200 @@
+// Reaching the SQL engine from Node.
+//
+// engine.sql holds the work. This is only the door: put the functions
+// somewhere, call them, take them away again.
+//
+// Two doors lead to the same engine, and this is the one the command line
+// uses. The other is the installer, where the same functions stay put and
+// pg_cron calls them nightly - so anything that happens here must be a thing
+// the scheduler could do too. No cleverness in Node that the database cannot
+// do on its own, or the two doors stop leading to the same place.
+
+const fs = require('fs');
+const path = require('path');
+
+// The token engine.sql carries wherever its own schema name belongs. A token
+// rather than the word "kryptheon" so that replacing it cannot quietly hit a
+// comment or a string that happened to say the same thing.
+const PLACEHOLDER = '__KN__';
+
+/** The engine, with its functions addressed to one schema. */
+function engineFor(target) {
+  const source = fs.readFileSync(path.join(__dirname, 'engine.sql'), 'utf8');
+  if (!source.includes(PLACEHOLDER)) {
+    throw new Error('engine.sql has no ' + PLACEHOLDER + ' in it, so it cannot be addressed anywhere');
+  }
+  return source.split(PLACEHOLDER).join(quote(target));
+}
+
+function quote(name) {
+  return '"' + String(name).split('"').join('""') + '"';
+}
+
+/**
+ * Puts the engine somewhere it can be called from.
+ *
+ * `CREATE OR REPLACE` throughout, so installing twice is not an error and an
+ * upgrade is the same operation as an install.
+ */
+async function install(client, target) {
+  await client.query(engineFor(target));
+  return target;
+}
+
+/** Takes it away again, functions and all. */
+async function uninstall(client, target) {
+  await client.query('DROP SCHEMA IF EXISTS ' + quote(target) + ' CASCADE');
+}
+
+/** What the engine says the shape of an app is. */
+async function readSchema(client, target, source) {
+  const { rows } = await client.query('SELECT ' + quote(target) + '.read_schema($1) AS shape', [source]);
+  return rows[0].shape;
+}
+
+/**
+ * What the engine would run to rebuild one schema as another.
+ *
+ * Handed back without running any of it, so the guard can look at every
+ * statement before one of them touches the database - and so a check can read
+ * what would have happened without anything happening.
+ */
+async function copyStatements(client, target, plan, into) {
+  const { rows } = await client.query(
+    'SELECT ' + quote(target) + '.copy_statements($1::jsonb, $2) AS statements',
+    [JSON.stringify(plan), into],
+  );
+  return rows[0].statements;
+}
+
+/** Builds the copy, and hands back every statement it ran. */
+async function writeSchema(client, target, plan, into) {
+  const { rows } = await client.query(
+    'SELECT ' + quote(target) + '.write_schema($1::jsonb, $2) AS statements',
+    [JSON.stringify(plan), into],
+  );
+  return rows[0].statements;
+}
+
+/*
+ * The attacks.
+ *
+ * Thin on purpose: each one hands the engine the same arguments its Node twin
+ * takes and gives back the same shape, so a caller can be pointed at either
+ * without knowing which it has. `twin.check.js` has been calling these through
+ * raw SQL since they were written; they are functions here so that `scan.js`
+ * can reach them too, which is what makes the two doors one engine rather than
+ * one on paper.
+ */
+
+/** Puts two fake people in the copy, and says what it could not seed. */
+async function seed(client, target, into, tables) {
+  const { rows } = await client.query(
+    'SELECT ' + quote(target) + '.seed($1, $2::jsonb) AS answer',
+    [into, JSON.stringify(tables)],
+  );
+  return rows[0].answer;
+}
+
+/** Can the wrong person read this? */
+async function impersonate(client, target, into, tables) {
+  const { rows } = await client.query(
+    'SELECT ' + quote(target) + '.impersonate($1, $2::jsonb) AS answer',
+    [into, JSON.stringify(tables)],
+  );
+  return rows[0].answer;
+}
+
+/** Can a stranger change it? Every write rolled back inside the engine. */
+async function tamper(client, target, into, tables, seeded, policies) {
+  const { rows } = await client.query(
+    'SELECT ' + quote(target) + '.tamper($1, $2::jsonb, $3::jsonb, $4::jsonb) AS answer',
+    [into, JSON.stringify(tables), JSON.stringify(seeded), JSON.stringify(policies || [])],
+  );
+  return rows[0].answer;
+}
+
+/** Can a half-finished row survive? */
+async function orphan(client, target, into, tables, seeded) {
+  const { rows } = await client.query(
+    'SELECT ' + quote(target) + '.orphan($1, $2::jsonb, $3::jsonb) AS answer',
+    [into, JSON.stringify(tables), JSON.stringify(seeded)],
+  );
+  return rows[0].answer;
+}
+
+/**
+ * Can the same thing exist twice?
+ *
+ * Inside the database this one cannot actually race anything - two requests at
+ * the same instant need two connections, and no credential ever moves - so it
+ * comes back with every column it would have tried in `notTried`, with the
+ * reason. That is deliberate and is the honest answer: reporting nothing at
+ * all would read as safety.
+ */
+async function collide(client, target, into, tables, indexes) {
+  const { rows } = await client.query(
+    'SELECT ' + quote(target) + '.collide($1, $2::jsonb, $3::jsonb) AS answer',
+    [into, JSON.stringify(tables), JSON.stringify(indexes)],
+  );
+  return rows[0].answer;
+}
+
+/**
+ * The same six operations `scan.js` asks of an engine, done in SQL.
+ *
+ * Handed an engine schema that is already installed, because installing and
+ * removing it is the caller's business - `withEngine` below - and a scan
+ * should not have to know that this engine needs putting somewhere first.
+ *
+ * `collide` is not among them. The scan races two real requests down two real
+ * connections, which is something no engine living inside the database can do;
+ * that is measured and written up in STATE.md, and the report names what it
+ * could not race rather than leaving it out.
+ */
+function adapterFor(target) {
+  return {
+    name: 'sql',
+    readSchema: (client, source) => readSchema(client, target, source),
+    writeSchema: (client, plan, into) => writeSchema(client, target, plan, into),
+    seed: (client, into, tables) => seed(client, target, into, tables),
+    impersonate: (client, into, tables) => impersonate(client, target, into, tables),
+    tamper: (client, into, tables, sown, policies) =>
+      tamper(client, target, into, tables, sown, policies),
+    orphan: (client, into, tables, sown) => orphan(client, target, into, tables, sown),
+  };
+}
+
+/**
+ * Installs the engine, does something with it, and takes it away.
+ *
+ * The schema is named for the moment it was made, the same as the copy is, so
+ * that one abandoned by a dropped connection can be recognised and swept later
+ * rather than sitting there for ever.
+ */
+async function withEngine(client, work) {
+  const target = 'kn_engine_' + Date.now().toString(36);
+  await install(client, target);
+  try {
+    return await work(target);
+  } finally {
+    await uninstall(client, target).catch(() => {});
+  }
+}
+
+module.exports = {
+  PLACEHOLDER: PLACEHOLDER,
+  engineFor: engineFor,
+  install: install,
+  uninstall: uninstall,
+  readSchema: readSchema,
+  copyStatements: copyStatements,
+  writeSchema: writeSchema,
+  seed: seed,
+  impersonate: impersonate,
+  tamper: tamper,
+  orphan: orphan,
+  collide: collide,
+  adapterFor: adapterFor,
+  withEngine: withEngine,
+};