kryptheon-night 0.1.3 → 0.1.5

package/README.md

@@ -76,16 +76,55 @@ attacks, this time, lost*.
 
 ## Prove the fix worked
 
-Paste the fix into Lovable or Cursor, let it deploy, then:
+Paste the fix into Lovable or Cursor, let it deploy, then run the same command
+again:
 
 ```
-npx kryptheon-night --recheck
+npx kryptheon-night
+```
+
+It compares by itself — there is no flag to remember. A problem that
+*disappeared* is not the same as a problem that was *fixed*: if a table could
+not be tested this time, or is no longer there, it says so rather than
+crediting you with a fix. Close everything, with nothing left untested, and it
+hands out a badge.
+
+## Or let it run every night, on its own
+
+You do not have to go looking for this — the command above offers it once the
+report is on the screen, and tells you if it is already running. If you would
+rather just say so:
+
+```
+npx kryptheon-night install
 ```
 
-It runs the same attacks again and compares. A problem that *disappeared* is
-not the same as a problem that was *fixed* — if a table could not be tested
-this time, or is no longer there, it says so rather than crediting you with a
-fix. Close everything, with nothing left untested, and it hands out a badge.
+This one **stays**, and it tells you so before it does anything. It puts the
+checking functions into a schema called `kryptheon`, adds `pg_cron` and
+`pg_net` if they are not already there, and schedules one job at 3am. Then
+every night it does what the command above does — copies the shape of your
+tables, attacks the copy, writes down what got through, deletes the copy.
+
+```
+npx kryptheon-night night       read back the last night it ran
+npx kryptheon-night status      is it installed, and is it running
+npx kryptheon-night uninstall   take it all out again
+```
+
+**Nothing leaves your database**, because the checking happens inside it — the
+connection string is not stored anywhere and nothing is uploaded. It is also
+much faster for the same reason: on a real project the command line took 2
+minutes 16 seconds and the nightly run took 1 second, and both found the same
+five problems.
+
+**One thing it cannot do.** Racing two requests against each other — the "can
+this exist twice" question — 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.
+
+`uninstall` removes the job, the schema, and any extension it had to add, and
+leaves alone anything that was already there.
 
 ## Three answers, three exit codes
 

package/bin/kryptheon-night.js

@@ -30,6 +30,8 @@ const recheck = require('../recheck.js');
 const intro = require('../intro.js');
 const trouble = require('../trouble.js');
 const { howToConnect } = require('../connect.js');
+const installer = require('../installer.js');
+const finding = require('../finding.js');
 
 const line = (text) => process.stdout.write(text + '\n');
 const fail = (text) => process.stderr.write(text + '\n');
@@ -39,17 +41,33 @@ function usage() {
     '',
     '  kryptheon-night - attacks a copy of your database and tells you what got in.',
     '',
-    '  Run it with nothing and it will ask you for what it needs:',
+    '  There is one command. It asks for what it needs:',
     '',
     '      npx kryptheon-night',
     '',
+    '  Run it again after you fix something and it tells you what is actually',
+    '  closed - you do not have to ask it to. It also offers to do the same',
+    '  check every night from inside your database, and says so if it already',
+    '  is. Nothing below is needed to use this.',
+    '',
+    '  For scripts, and for people who like knowing:',
+    '',
+    '      npx kryptheon-night night       read back the last night it ran',
+    '      npx kryptheon-night status      is it installed, and is it running',
+    '      npx kryptheon-night install     set the nightly run up without being asked',
+    '      npx kryptheon-night uninstall   take it all out again',
+    '',
+    '  The nightly run needs pg_cron and pg_net. Supabase has both. It cannot',
+    '  race two requests at once, so it is weaker than this command for the',
+    '  "can this exist twice" question, and its report says which columns.',
+    '',
     '  Options, none of them necessary:',
     '',
-    '      --recheck        run the same attacks again after a fix, and say',
-    '                       which problems are actually closed',
     '      --schema NAME    the part of the database your app lives in.',
     '                       Leave it out; it is "public" for almost everyone',
     '      --yes            skip the "may I?" question. For scripts only',
+    '      --recheck        nothing any more - comparing against the last run',
+    '                       happens by itself. Kept so scripts do not break',
     '      --help           this',
     '',
     '  The connection string can be put in KN_DATABASE_URL instead of being',
@@ -58,9 +76,17 @@ function usage() {
   ];
 }
 
+// The things this can be asked to do besides scan. Kept to verbs nobody
+// names a schema: `public` is the schema almost everybody has, and a bare
+// word that is not one of these is still read as a schema so that
+// `kryptheon-night public` keeps working.
+const VERBS = ['install', 'uninstall', 'status', 'night'];
+
 /** What was asked for, and what was left to the default. */
 function readArgs(argv) {
-  const asked = { schema: null, recheck: false, yes: false, help: false, unknown: [] };
+  const asked = {
+    command: 'scan', schema: null, recheck: false, yes: false, help: false, unknown: [],
+  };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--recheck') asked.recheck = true;
@@ -69,14 +95,233 @@ function readArgs(argv) {
     else if (arg === '--schema') asked.schema = argv[++i] || null;
     else if (arg.startsWith('--schema=')) asked.schema = arg.slice('--schema='.length);
     else if (arg.startsWith('-')) asked.unknown.push(arg);
-    // A bare word is the schema, so that somebody who has read the old
-    // instructions and types `kryptheon-night public` is not told off.
+    // The first bare word is a verb if it is one, and otherwise the schema -
+    // so that somebody who has read the old instructions and types
+    // `kryptheon-night public` is not told off. Anybody whose schema really
+    // is called `status` can say so with --schema.
+    else if (asked.command === 'scan' && !asked.schema && VERBS.includes(arg)) asked.command = arg;
     else if (!asked.schema) asked.schema = arg;
     else asked.unknown.push(arg);
   }
   return asked;
 }
 
+/**
+ * The three doors that are not a scan.
+ *
+ * Each returns the exit code, because anything automating this reads those
+ * and not the words: 0 for nothing got through or nothing to say, 1 for
+ * something did, 2 for could not.
+ */
+async function runVerb(command, client, target) {
+  if (command === 'status') {
+    const where = await installer.status(client, {});
+    if (!where) {
+      line('  The nightly run is not installed in this database.');
+      line('');
+      line('  npx kryptheon-night install   would set it up.');
+      line('');
+      return 0;
+    }
+    line('  Installed, and watching "' + where.source + '".');
+    line('');
+    if (where.job) {
+      line('    job        ' + where.job.jobname + '   ' + where.job.schedule +
+        (where.job.active ? '' : '   (NOT ACTIVE)'));
+    } else {
+      // The one failure that looks like success from every other angle: the
+      // schema is there, the functions are there, and nothing is running.
+      line('    job        MISSING - nothing is scheduled, so nothing runs');
+    }
+    line('    schema     ' + where.schema);
+    line('    since      ' + new Date(where.installed_at).toISOString().slice(0, 16).replace('T', ' '));
+    line('');
+    const { rows } = await client.query(
+      'SELECT count(*)::int AS n, max(ran_at) AS last FROM ' +
+        '"' + String(where.schema).split('"').join('""') + '".runs',
+    ).catch(() => ({ rows: [{ n: 0, last: null }] }));
+    line('    runs       ' + rows[0].n +
+      (rows[0].last ? '   last ' + new Date(rows[0].last).toISOString().slice(0, 16).replace('T', ' ') : ''));
+    line('');
+    return where.job ? 0 : 1;
+  }
+
+  if (command === 'install') {
+    line('  Installing ...');
+    const done = await installer.install(client, { source: target });
+    line('');
+    line('  Installed. It will run at ' + done.at + ', watching "' + done.source + '".');
+    line('');
+    if (done.made.extensions.length) {
+      line('  I had to add: ' + done.made.extensions.join(', ') + '.');
+      line('  Removing Kryptheon will take those back out again.');
+      line('');
+    }
+    line('  Tomorrow morning:  npx kryptheon-night night');
+    line('  To remove it:      npx kryptheon-night uninstall');
+    line('');
+    return 0;
+  }
+
+  if (command === 'uninstall') {
+    const was = await installer.status(client, {});
+    if (!was) {
+      line('  There is nothing installed here to remove.');
+      line('');
+      return 0;
+    }
+    const removed = await installer.uninstall(client, {});
+    line('  Removed.');
+    line('');
+    line('    the nightly job   ' + (removed.job ? 'gone' : 'there was none'));
+    line('    the schema        ' + (removed.schema ? 'gone' : 'left, it was not mine to drop'));
+    line('    extensions        ' + (removed.extensions.length
+      ? removed.extensions.join(', ') + ' - the ones I added'
+      : 'none removed; they were here before me'));
+    line('');
+    return 0;
+  }
+
+  if (command === 'night') {
+    const where = await installer.status(client, {});
+    if (!where) {
+      line('  The nightly run is not installed in this database, so there is');
+      line('  nothing to read back.');
+      line('');
+      line('  npx kryptheon-night          would scan it now.');
+      line('  npx kryptheon-night install  would set up the nightly run.');
+      line('');
+      return 2;
+    }
+    const quoted = '"' + String(where.schema).split('"').join('""') + '"';
+    const { rows } = await client.query(
+      'SELECT ran_at, source, stopped, attacks_run, findings, not_checked ' +
+        'FROM ' + quoted + '.runs ORDER BY ran_at DESC LIMIT 1',
+    );
+    if (!rows.length) {
+      // Installed and never run is not the same as run and found nothing, and
+      // saying "nothing got through" here would be the worst sentence in the
+      // product printed about a night that never happened.
+      line('  It is installed, and it has not run yet.');
+      line('');
+      line('  The first run is at ' + (where.job ? where.job.schedule : 'whenever it is scheduled') + '.');
+      line('');
+      return 0;
+    }
+    const run = rows[0];
+    line('  From the night of ' + new Date(run.ran_at).toISOString().slice(0, 16).replace('T', ' ') +
+      ', on "' + run.source + '":');
+    scanner.report({
+      stopped: run.stopped,
+      attacksRun: run.attacks_run,
+      notChecked: run.not_checked || [],
+      findings: finding.describeAll(run.findings || []),
+    });
+    return run.stopped ? 2 : (run.findings || []).length ? 1 : 0;
+  }
+
+  throw new Error('there is no command called ' + command);
+}
+
+/**
+ * After the report: say what the nightly run is doing, or offer it.
+ *
+ * Three states and each says something different. Installed and running gets
+ * one line, because it is working and nobody needs a paragraph about it.
+ * Installed with no job is the quiet failure - the schema is there, the
+ * functions are there, and nothing runs - so it says so plainly. Not
+ * installed gets the offer.
+ *
+ * Nothing here can make the scan fail. Whatever happens, the person has
+ * already been given their answer, and losing it to an error about a nightly
+ * job they never asked for would be the tool wasting the only thing it did.
+ */
+async function offerTheNight(client, target, canAsk) {
+  let where = null;
+  try {
+    where = await installer.status(client, {});
+  } catch (err) {
+    return;
+  }
+
+  if (where && where.job) {
+    line('  I am also checking this every night, at ' + where.job.schedule + '.');
+    line('  Read the last one with:  npx kryptheon-night night');
+    line('');
+    return;
+  }
+
+  if (where && !where.job) {
+    line('  The nightly check is installed here but nothing is scheduled, so it');
+    line('  is not running. Setting it up again would fix that:');
+    line('');
+    line('      npx kryptheon-night install');
+    line('');
+    return;
+  }
+
+  if (!canAsk) {
+    // Nobody to ask. Said once, quietly, rather than nagging a log file.
+    line('  This can also run every night by itself:  npx kryptheon-night install');
+    line('');
+    return;
+  }
+
+  const can = await installer.extensionState(client, 'pg_net').catch(() => ({ available: false }));
+  const cron = await installer.extensionState(client, 'pg_cron').catch(() => ({ available: false }));
+  if (!can.available || !cron.available) {
+    // Not offered where it cannot happen. An offer that fails when accepted
+    // is worse than no offer.
+    return;
+  }
+
+  line('  One more thing.');
+  line('');
+  line('  What you just read is true about your app right now. It stops being');
+  line('  true the next time anybody changes it - and that is the day nobody');
+  line('  runs this. I can do exactly the same check every night, from inside');
+  line('  your database, and have the answer waiting.');
+  line('');
+  const yes = await intro.askYesNo('  Set that up? (y/n) ');
+  if (!yes) {
+    line('');
+    line('  Fine. It is here if you change your mind:');
+    line('      npx kryptheon-night install');
+    line('');
+    return;
+  }
+
+  block(intro.installConsentLines(installer.SCHEMA, target, installer.AT));
+  const sure = await intro.askYesNo('  Go ahead? (y/n) ');
+  if (!sure) {
+    line('');
+    line('  Left alone. Nothing was installed.');
+    line('');
+    return;
+  }
+
+  try {
+    const done = await installer.install(client, { source: target });
+    line('');
+    line('  Done. It will run at ' + done.at + ', watching "' + done.source + '".');
+    if (done.made.extensions.length) {
+      line('  I added ' + done.made.extensions.join(' and ') + '; uninstall takes them back out.');
+    }
+    line('');
+    line('  Tomorrow:    npx kryptheon-night night');
+    line('  To remove:   npx kryptheon-night uninstall');
+    line('');
+  } catch (err) {
+    // The scan still stands. Say what failed and leave it at that.
+    line('');
+    line('  I could not set up the nightly run: ' + String(err.message).split('\n')[0]);
+    line('');
+    line('  The report above is still good. Nothing was left half-installed.');
+    line('');
+    await installer.uninstall(client, {}).catch(() => {});
+  }
+}
+
 /** Prints a block of plain lines with the indent the rest of the report uses. */
 function block(lines, write) {
   (write || line)('');
@@ -141,7 +386,11 @@ async function main() {
   line('');
   line('  Database: ' + trouble.withoutSecret(connection));
 
-  if (!asked.yes) {
+  // Reading does not need permission; changing does. `status` and `night` only
+  // read what is already written down, so asking would be ceremony.
+  const needsAYes = asked.command === 'scan' || asked.command === 'install';
+
+  if (needsAYes && !asked.yes) {
     if (!canAsk) {
       fail('');
       fail('  I will not connect to your database without being told yes, and');
@@ -151,7 +400,12 @@ async function main() {
       fail('');
       process.exit(2);
     }
-    block(intro.consentLines(target));
+    // Two different screens, because they promise different things. The scan's
+    // ends "I do not leave anything behind", which is true of a scan and false
+    // of an install - and this is the one screen the product cannot be loose on.
+    block(asked.command === 'install'
+      ? intro.installConsentLines(installer.SCHEMA, target, installer.AT)
+      : intro.consentLines(target));
     const yes = await intro.askYesNo('  Go ahead? (y/n) ');
     if (!yes) {
       line('');
@@ -161,17 +415,31 @@ async function main() {
     }
   }
 
+  // Compared against last time whenever there IS a last time, without being
+  // asked.
+  //
+  // `--recheck` was a flag, and a flag is a thing somebody has to know about.
+  // The person this is for fixed what the report told them to fix and typed
+  // the same command again - and got a fresh report that said the same number
+  // of problems, with no word about which of them they had just closed. The
+  // tool knew. It had the file. It waited to be asked.
+  //
+  // The flag still works, because anything scripted may be passing it, and
+  // now it changes nothing: with an earlier run here, this always compares.
   const file = path.resolve(scanner.LAST_RUN);
-  const before = asked.recheck ? scanner.loadLastRun(file) : null;
+  const before = scanner.loadLastRun(file);
   if (asked.recheck && !before) {
+    // Asked for explicitly and impossible, which is worth saying. Arriving
+    // here by accident is not: without the flag, no earlier run simply means
+    // this is the first one.
     fail('');
     fail('  There is no earlier run in this folder to compare against.');
     fail('');
-    fail('  --recheck proves a fix worked by running the same attacks again and');
+    fail('  A re-check proves a fix worked by running the same attacks again and');
     fail('  comparing. With nothing to compare against it would report every');
     fail('  problem as new, which would look like an answer and would not be one.');
     fail('');
-    fail('  Run it without --recheck first.');
+    fail('  Run it once first, and it will compare by itself from then on.');
     fail('');
     process.exit(2);
   }
@@ -191,6 +459,20 @@ async function main() {
   line('  Connected.');
   line('');
 
+  // The other three doors. Each one ends the command; only `scan` falls
+  // through to the attack below.
+  if (asked.command !== 'scan') {
+    try {
+      process.exitCode = await runVerb(asked.command, client, target);
+    } catch (err) {
+      block(trouble.explain(err, connection), fail);
+      process.exitCode = 2;
+    } finally {
+      await client.end().catch(() => {});
+    }
+    return;
+  }
+
   try {
     const result = await scanner.scan(client, target, {
       // Two requests arriving at the same instant cannot be faked down one
@@ -208,15 +490,25 @@ async function main() {
       scanner.report(result);
       scanner.saveRun(file, result);
       process.exitCode = result.stopped ? 2 : result.findings.length ? 1 : 0;
-      return;
+    } else {
+      const verdict = recheck.compare(before, result);
+      recheck.describe(verdict).forEach(line);
+      recheck.badgeLines(verdict, result.attacksRun || 0).forEach(line);
+      if (result.findings.length) scanner.report(result);
+      scanner.saveRun(file, result);
+      process.exitCode = result.stopped ? 2 : verdict.allClear ? 0 : 1;
     }
 
-    const verdict = recheck.compare(before, result);
-    recheck.describe(verdict).forEach(line);
-    recheck.badgeLines(verdict, result.attacksRun || 0).forEach(line);
-    if (result.findings.length) scanner.report(result);
-    scanner.saveRun(file, result);
-    process.exitCode = result.stopped ? 2 : verdict.allClear ? 0 : 1;
+    // And then the only other thing worth doing, offered rather than
+    // documented.
+    //
+    // `install` was a verb, and a verb is a thing somebody has to find out
+    // about. Nobody who clicked Deploy in Lovable is going to read a list of
+    // subcommands - they will run this once, get their answer, and never
+    // think about it again, which is exactly the app that is unprotected
+    // three months later. The tool already knows whether the nightly run is
+    // there. So it asks.
+    if (!result.stopped) await offerTheNight(client, target, canAsk);
   } catch (err) {
     // Anything that went wrong mid-scan. The copy has already been dropped by
     // the `finally` inside the scan itself, so there is nothing to clean up