kryptheon 0.1.48 → 0.1.50

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/kryptheon.js CHANGED
@@ -49,6 +49,11 @@ const MIN_NODE = [20, 6, 0];
49
49
  const WINDOW_POLL_MS = 5000;
50
50
  const WINDOW_TIMEOUT_MS = 30000;
51
51
  const WINDOW_HARD_LIMIT_MS = 90000;
52
+ // A browser left running with no window confirmed is watched on, quietly, and
53
+ // if this long goes by from the start with still none seen, the person is told
54
+ // once what to look at. Found on Windows 10: no window for an hour, and
55
+ // nothing said after the first minute and a half.
56
+ const WINDOW_LATE_MS = 3 * 60 * 1000;
52
57
  // This was 4 seconds, kept under the poll interval so a probe never held the
53
58
  // loop past the next one. Measured since, on a Windows 11 machine: the probe
54
59
  // takes 2.5-3 seconds with nothing else running, and while the browser was
@@ -102,6 +107,8 @@ function usage() {
102
107
  console.log(' npx kryptheon code read your frontend code for text inserted as HTML');
103
108
  console.log(' npx kryptheon edge try unusual values in your recorded forms (adds test data; asks first)');
104
109
  console.log(' npx kryptheon reliability replay each flow 3 times, double-click what saves (adds test data; asks first)');
110
+ console.log(' npx kryptheon payments one test payment, its webhook sent again: given twice? (asks first)');
111
+ console.log(' ... --app <url> --port <n> --schema <name> --test-mode (database: KRYPTHEON_DATABASE_URL)');
105
112
  console.log(' npx kryptheon dashboard the page above (also: npx kryptheon, in a terminal)');
106
113
  console.log('');
107
114
  console.log(' add --quiet to check for one line when everything passes');
@@ -685,21 +692,66 @@ function whenWindowUnconfirmed(verdict, atKeyboard) {
685
692
  return atKeyboard ? 'leave' : 'stop';
686
693
  }
687
694
 
695
+ /**
696
+ * Whether this run was started from the dashboard (kryptheonChild says so).
697
+ * There is no terminal then: nobody can press Ctrl+C, and the way to end a
698
+ * run is the Stop button on the page.
699
+ */
700
+ function fromDashboardJob() {
701
+ return process.env.KRYPTHEON_DASHBOARD_JOB === '1';
702
+ }
703
+
688
704
  // Said once, while the person may still be recording, instead of taking the
689
- // browser away from them.
690
- function windowUnconfirmedLines() {
705
+ // browser away from them. From the dashboard it names Stop: found on Windows
706
+ // 10, where the page told somebody to press Ctrl+C - which the page does not
707
+ // have - while a recording with no window stayed RUNNING for an hour.
708
+ function windowUnconfirmedLines(fromDashboard) {
691
709
  return [
692
710
  '',
693
711
  ' (I could not confirm the browser window from here - that check is slow',
694
712
  ' on some machines - so I am leaving it alone. If it is on your screen,',
695
713
  ' carry on and close it when you are done. If there is no window',
696
- ' anywhere, press Ctrl+C to stop.)',
714
+ fromDashboard ? ' anywhere, press Stop on the dashboard.)' : ' anywhere, press Ctrl+C to stop.)',
697
715
  '',
698
716
  ];
699
717
  }
700
718
 
701
719
  // The probe kept failing to answer. Nothing was learned about the browser
702
720
  // either way, and saying "no window appeared" would be inventing a fact.
721
+ /**
722
+ * Said once, three minutes in, when no window has been seen - the probe did
723
+ * not answer, or answered that there is none. The browser is left running
724
+ * all the same: an unanswered probe is not proof, and someone may be using
725
+ * the window. Antivirus is named because that is what held Chrome for
726
+ * Testing on the machine where this was found.
727
+ */
728
+ function windowLateLines(platform, fromDashboard) {
729
+ const where = platform === 'win32'
730
+ ? [
731
+ ' - Open Task Manager and look for "Chrome for Testing". If it is there',
732
+ ' but nothing is on your screen, it is stuck.',
733
+ ' - Antivirus (for example Quick Heal or Avast) may be holding it. Allow',
734
+ ' the folder %LOCALAPPDATA%\\ms-playwright in your antivirus, then',
735
+ ' record again.',
736
+ ]
737
+ : [
738
+ ' - Look for "Chrome for Testing" among the programs running. If it is',
739
+ ' there but nothing is on your screen, it is stuck.',
740
+ ' - Security software may be holding it. Allow the ms-playwright folder,',
741
+ ' where the browser is kept, then record again.',
742
+ ];
743
+ return [
744
+ '',
745
+ ' No browser window could be seen, 3 minutes after it was started.',
746
+ '',
747
+ ].concat(where, [
748
+ fromDashboard ? ' - Or press Stop on the dashboard.' : ' - Or press Ctrl+C here to stop.',
749
+ '',
750
+ ' If the window is on your screen after all, carry on - nothing has been stopped.',
751
+ '',
752
+ ]);
753
+ }
754
+
703
755
  function probeUnclearLines(answered, unanswered, platform) {
704
756
  return [
705
757
  '',
@@ -738,6 +790,7 @@ function createWindowWatch(options) {
738
790
  const clock = opts.now || Date.now;
739
791
  const budgetMs = opts.budgetMs == null ? WINDOW_TIMEOUT_MS : opts.budgetMs;
740
792
  const hardLimitMs = opts.hardLimitMs == null ? WINDOW_HARD_LIMIT_MS : opts.hardLimitMs;
793
+ const lateMs = opts.lateMs == null ? WINDOW_LATE_MS : opts.lateMs;
741
794
 
742
795
  const started = clock();
743
796
  let lastTick = started;
@@ -748,6 +801,7 @@ function createWindowWatch(options) {
748
801
  let answered = 0;
749
802
  let unanswered = 0;
750
803
  let sawProcess = false;
804
+ let lateSaid = false;
751
805
 
752
806
  return {
753
807
  tick: function () {
@@ -778,6 +832,20 @@ function createWindowWatch(options) {
778
832
  seconds: Math.round((now - started) / 1000),
779
833
  };
780
834
  },
835
+ /**
836
+ * After a verdict that left the browser running with no window seen: keep
837
+ * looking, quietly. 'window' once one is seen; 'late' once, when lateMs
838
+ * have gone by since the start with none (null after that); otherwise
839
+ * null. Never a reason to stop the browser.
840
+ */
841
+ later: function () {
842
+ if (lateSaid) return null;
843
+ const seen = probe();
844
+ if (seen && seen.known && seen.windows > 0) return 'window';
845
+ if (clock() - started < lateMs) return null;
846
+ lateSaid = true;
847
+ return 'late';
848
+ },
781
849
  stats: function () {
782
850
  return { spent: spent, answered: answered, unanswered: unanswered, sawProcess: sawProcess };
783
851
  },
@@ -954,16 +1022,19 @@ function reportSecrets(replacements) {
954
1022
  // order mark that makes the first line unreadable.
955
1023
  const hasEnv = fs.existsSync(path.join(USER_DIR, '.env'));
956
1024
  const example = hasEnv ? null : secrets.writeEnvExample(USER_DIR, names);
1025
+ // Each account has its own name, so the owner's and a member's recordings
1026
+ // can both sign in (blind round 19).
1027
+ const whose = (item) => (item.account ? ' (' + String(item.field).toLowerCase() + ' of ' + item.account + ')' : '');
957
1028
  if (example) {
958
1029
  console.log(' A file called .env.example has been written here:');
959
- for (const name of names) console.log(' ' + name + '=yourpassword');
1030
+ for (const item of replacements) console.log(' ' + item.envName + '=yourpassword' + whose(item));
960
1031
  console.log('');
961
- console.log(' Put your real password in it and save it as .env, in this folder.');
1032
+ console.log(' Put the real password in it and save it as .env, in this folder.');
962
1033
  } else {
963
1034
  console.log(' Before this can be checked, put it in a file called .env next to');
964
1035
  console.log(' your tests, like this:');
965
1036
  for (const item of replacements) {
966
- console.log(' ' + item.envName + '=your ' + String(item.field).toLowerCase() + ' here');
1037
+ console.log(' ' + item.envName + '=your ' + String(item.field).toLowerCase() + ' here' + whose(item));
967
1038
  }
968
1039
  }
969
1040
  console.log('');
@@ -1654,6 +1725,8 @@ async function record(url, options) {
1654
1725
  // Someone whose window is real but undetectable can turn this off.
1655
1726
  const watchdogOff = !!process.env.KRYPTHEON_FORCE_RECORD;
1656
1727
  const watch = createWindowWatch();
1728
+ // Left running with no window seen: looking on for the three-minute note.
1729
+ let lookingLater = false;
1657
1730
  const watchdog = setInterval(() => {
1658
1731
  if (watchdogOff) {
1659
1732
  clearInterval(watchdog);
@@ -1665,15 +1738,25 @@ async function record(url, options) {
1665
1738
  clearInterval(watchdog);
1666
1739
  return;
1667
1740
  }
1741
+ if (lookingLater) {
1742
+ const later = watch.later();
1743
+ if (!later) return;
1744
+ clearInterval(watchdog);
1745
+ if (later === 'late') for (const line of windowLateLines(process.platform, fromDashboardJob())) console.log(line);
1746
+ return;
1747
+ }
1668
1748
  const outcome = watch.tick();
1669
1749
  if (!outcome) return;
1670
- clearInterval(watchdog);
1671
1750
  if (whenWindowUnconfirmed(outcome.verdict, !!process.stdin.isTTY) === 'leave') {
1672
- if (outcome.verdict !== 'window') {
1673
- for (const line of windowUnconfirmedLines()) console.log(line);
1751
+ if (outcome.verdict === 'window') {
1752
+ clearInterval(watchdog);
1753
+ return;
1674
1754
  }
1755
+ for (const line of windowUnconfirmedLines(fromDashboardJob())) console.log(line);
1756
+ lookingLater = true;
1675
1757
  return;
1676
1758
  }
1759
+ clearInterval(watchdog);
1677
1760
  stopChild();
1678
1761
  finalise(outcome.verdict, outcome).then(resolve);
1679
1762
  }, WINDOW_POLL_MS);
@@ -1686,6 +1769,15 @@ async function record(url, options) {
1686
1769
  process.once('SIGINT', onSignal);
1687
1770
  process.once('SIGTERM', onSignal);
1688
1771
  process.once('SIGHUP', onSignal);
1772
+ // Started from the dashboard, Stop on the page is this process's Ctrl+C.
1773
+ // The channel must not keep the process alive once the recording is done.
1774
+ const onMessage = (message) => {
1775
+ if (message === STOP_MESSAGE) onSignal();
1776
+ };
1777
+ if (process.channel) {
1778
+ process.on('message', onMessage);
1779
+ process.channel.unref();
1780
+ }
1689
1781
 
1690
1782
  child.on('error', () => {
1691
1783
  clearInterval(watchdog);
@@ -1697,6 +1789,7 @@ async function record(url, options) {
1697
1789
  process.removeListener('SIGINT', onSignal);
1698
1790
  process.removeListener('SIGTERM', onSignal);
1699
1791
  process.removeListener('SIGHUP', onSignal);
1792
+ process.removeListener('message', onMessage);
1700
1793
  finalise('exit').then(resolve);
1701
1794
  });
1702
1795
  });
@@ -2047,6 +2140,83 @@ async function probeCommand(check, args) {
2047
2140
  return report.flows.some((f) => f.state === 'tested') ? 0 : 2;
2048
2141
  }
2049
2142
 
2143
+ // --- payments ---------------------------------------------------------------
2144
+ //
2145
+ // One real test-mode payment, its webhook sent again: does the customer get it
2146
+ // twice? The work is in kryptheon-payments.js; what is said is in
2147
+ // kryptheon-payments-run.js. The database address is only ever read from the
2148
+ // environment, never from the command line, where it would be kept in the
2149
+ // shell's history.
2150
+
2151
+ function flagValue(args, name) {
2152
+ const at = args.indexOf(name);
2153
+ return at !== -1 && args[at + 1] && !/^--/.test(args[at + 1]) ? args[at + 1] : null;
2154
+ }
2155
+
2156
+ async function paymentsCommand(args) {
2157
+ if (!openStore()) return 1;
2158
+ const runner = require(path.join(PACKAGE_DIR, 'kryptheon-payments-run.js'));
2159
+ const port = Number(flagValue(args, '--port')) || runner.DEFAULT_PORT;
2160
+ let stopped = false;
2161
+ const onSigint = () => { stopped = true; };
2162
+ process.once('SIGINT', onSigint);
2163
+ console.log('');
2164
+ const out = await runner.run(USER_DIR, {
2165
+ app: flagValue(args, '--app') || 'http://localhost:3000',
2166
+ schema: flagValue(args, '--schema') || 'public',
2167
+ port: port,
2168
+ database: process.env.KRYPTHEON_DATABASE_URL || null,
2169
+ yes: args.includes('--yes'),
2170
+ testMode: args.includes('--test-mode'),
2171
+ ask: (question) => (process.stdin.isTTY ? askLine(' ' + question) : Promise.resolve('')),
2172
+ say: (line) => console.log(line ? ' ' + line : ''),
2173
+ stopped: () => stopped,
2174
+ });
2175
+ process.removeListener('SIGINT', onSigint);
2176
+ console.log('');
2177
+ return out.code;
2178
+ }
2179
+
2180
+ /**
2181
+ * What a replay that did not all pass is called on the page: "broke" only
2182
+ * when a flow that passed before fails now. Round 18 said "a flow broke"
2183
+ * about a recording that had never passed, while the replay said 0 broken.
2184
+ */
2185
+ function regressionSummary() {
2186
+ try {
2187
+ const dash = require(path.join(PACKAGE_DIR, 'kryptheon-dashboard.js'));
2188
+ const open = dash.buildState(USER_DIR).findings.filter((f) => f.check === 'regression');
2189
+ if (open.length && open.every((f) => f.status !== 'confirmed')) return 'a recording has never passed - see Findings (the recording or the app?)';
2190
+ } catch (err) {
2191
+ /* said the usual way */
2192
+ }
2193
+ return 'a flow broke - see Findings';
2194
+ }
2195
+
2196
+ /**
2197
+ * The payment check from the dashboard's button. The page has shown its words
2198
+ * and the person said yes there; the server checked the address is local.
2199
+ * Stop ends the wait for a payment, or the run between webhooks.
2200
+ */
2201
+ async function paymentsFromDashboard(run, say, control) {
2202
+ const runner = require(path.join(PACKAGE_DIR, 'kryptheon-payments-run.js'));
2203
+ let stopped = false;
2204
+ if (control) control.onStop(() => { stopped = true; });
2205
+ const out = await runner.run(USER_DIR, {
2206
+ app: run.app, schema: run.schema, port: runner.DEFAULT_PORT, database: run.connection,
2207
+ yes: true, testMode: run.testMode, say: say, stopped: () => stopped, stopWith: 'Stop on this page',
2208
+ });
2209
+ const report = out.report || { results: [] };
2210
+ const found = report.results.reduce((n, r) => n + r.findings.length, 0);
2211
+ const tested = report.results.filter((r) => !r.notTested.length).length;
2212
+ if (out.code === 2) {
2213
+ const why = (report.results.find((r) => r.notTested.length) || { notTested: [] }).notTested[0];
2214
+ return { ok: false, why: stopped ? 'stopped before a payment was checked' : why || 'nothing was tested - see what it printed' };
2215
+ }
2216
+ return { ok: true, summary: found ? found + (found === 1 ? ' problem found' : ' problems found') + ' - see Findings'
2217
+ : tested + (tested === 1 ? ' webhook' : ' webhooks') + ' sent again, and nothing was given twice' };
2218
+ }
2219
+
2050
2220
  // --- setup-ai ---------------------------------------------------------------
2051
2221
  //
2052
2222
  // An assistant that only reads code will happily call a change finished. These
@@ -2458,6 +2628,7 @@ async function probeRecheckCommand(target, options) {
2458
2628
  : target.kind === 'phone' ? 'replays ' + name + ' once, then once more at phone size, clicking every button with saving blocked. Two runs.'
2459
2629
  : target.kind === 'race' ? 'replays ' + name + ' once, then once more with this save sent twice at the same moment. Two runs.'
2460
2630
  : target.kind === 'shown' ? 'replays ' + name + ' three times, looking for what the save added on the page right after it. It is fixed only if it shows right away.'
2631
+ : target.kind === 'kept' ? 'replays ' + name + ' three times, opening the form again after each save and reading back what was typed. It is fixed only if the form shows it.'
2461
2632
  : 'replays ' + name + ' once, then once more with this step double-clicked. Two runs.');
2462
2633
  const confirmed = await probeConsent(what, addresses, Boolean(options && options.yes), PROBE_CHECKS[target.check].words);
2463
2634
  if (!confirmed) return 2;
@@ -2574,7 +2745,7 @@ const DASHBOARD_PORT = Number(process.env.KRYPTHEON_DASHBOARD_PORT) || 4789;
2574
2745
  * so the page can show progress instead of a spinner. Nothing is read from
2575
2746
  * the keyboard: a command started from the page has nobody at one.
2576
2747
  */
2577
- function spawnLines(file, args, options, say) {
2748
+ function spawnLines(file, args, options, say, onChild) {
2578
2749
  return new Promise((resolve) => {
2579
2750
  let child;
2580
2751
  try {
@@ -2584,6 +2755,7 @@ function spawnLines(file, args, options, say) {
2584
2755
  resolve({ code: null, why: err.message });
2585
2756
  return;
2586
2757
  }
2758
+ if (onChild) onChild(child);
2587
2759
  const pending = { out: '', err: '' };
2588
2760
  const feed = (which) => (chunk) => {
2589
2761
  pending[which] += chunk.toString();
@@ -2605,9 +2777,37 @@ function spawnLines(file, args, options, say) {
2605
2777
  });
2606
2778
  }
2607
2779
 
2608
- /** This same command, as a child, with these arguments. */
2609
- function kryptheonChild(args, say) {
2610
- return spawnLines(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js')].concat(args), {}, say);
2780
+ /**
2781
+ * This same command, as a child, with these arguments. KRYPTHEON_DASHBOARD_JOB
2782
+ * tells it that it was started from the page: nobody is at a terminal to press
2783
+ * Ctrl+C, and what it says should name the page's Stop button instead.
2784
+ *
2785
+ * With `onChild`, the child also gets a message channel, and onChild is handed
2786
+ * the child: stopChildJob() asks it over that channel to stop the way Ctrl+C
2787
+ * does. Killing it would not - on Windows a kill gives it no chance to stop
2788
+ * the browser it started, or to keep what was recorded.
2789
+ */
2790
+ function kryptheonChild(args, say, onChild) {
2791
+ const options = { env: Object.assign({}, process.env, { KRYPTHEON_DASHBOARD_JOB: '1' }) };
2792
+ if (onChild) options.stdio = ['ignore', 'pipe', 'pipe', 'ipc'];
2793
+ return spawnLines(process.execPath, [path.join(PACKAGE_DIR, 'bin', 'kryptheon.js')].concat(args), options, say, onChild);
2794
+ }
2795
+
2796
+ // What stopChildJob sends, and what record listens for.
2797
+ const STOP_MESSAGE = 'kryptheon:stop';
2798
+
2799
+ /** Asks a child started by kryptheonChild to stop as Ctrl+C would; a kill only if it cannot be asked. */
2800
+ function stopChildJob(child) {
2801
+ try {
2802
+ if (child.connected) {
2803
+ child.send(STOP_MESSAGE);
2804
+ return 'asked';
2805
+ }
2806
+ child.kill();
2807
+ return 'killed';
2808
+ } catch (err) {
2809
+ return 'gone';
2810
+ }
2611
2811
  }
2612
2812
 
2613
2813
  /**
@@ -2682,7 +2882,7 @@ function runFromDashboard(id, opened, say) {
2682
2882
  // A run that found broken flows is a run that finished; its results are
2683
2883
  // in the history the page reads next.
2684
2884
  code === 0 ? { ok: true, summary: 'every flow held' }
2685
- : code === 1 ? { ok: true, summary: 'a flow broke - see Findings' }
2885
+ : code === 1 ? { ok: true, summary: regressionSummary() }
2686
2886
  : { ok: false, why: 'the replay stopped with exit ' + code });
2687
2887
  }
2688
2888
  return { ok: false, why: '"' + id + '" cannot be run from the dashboard' };
@@ -2773,12 +2973,19 @@ function recheckFromDashboard(id, opened, say) {
2773
2973
  });
2774
2974
  }
2775
2975
 
2776
- /** Records one flow the way `npx kryptheon record <address>` does, and names what it saved. */
2976
+ /**
2977
+ * Records one flow the way `npx kryptheon record <address>` does, and names
2978
+ * what it saved. The page's Stop ends it as Ctrl+C would in a terminal: found
2979
+ * on Windows 10, where a browser that never showed its window left a
2980
+ * recording RUNNING for an hour with no way to end it from the page.
2981
+ */
2777
2982
  function recordFromDashboard(address, say, options) {
2778
2983
  const phone = Boolean(options && options.phone);
2984
+ const control = options && options.control;
2779
2985
  const before = listSpecFiles();
2780
2986
  say('A ' + (phone ? 'phone-sized ' : '') + 'browser window opens on ' + address + '. Use your app, then close that window to save.');
2781
- return kryptheonChild(['record', address].concat(phone ? ['--phone'] : []), say).then(({ code }) => {
2987
+ const onChild = control ? (child) => control.onStop(() => stopChildJob(child)) : null;
2988
+ return kryptheonChild(['record', address].concat(phone ? ['--phone'] : []), say, onChild).then(({ code }) => {
2782
2989
  const added = listSpecFiles().filter((name) => !before.includes(name));
2783
2990
  if (!added.length) return { ok: false, exit: code, why: 'no recording was saved' };
2784
2991
  return { ok: true, exit: code, recordings: added, summary: 'saved ' + added.join(', ') };
@@ -3112,6 +3319,7 @@ async function dashboardCommand() {
3112
3319
  probeRecheck: (id, say, control, confirmed) => probeRecheckFromDashboard(id, say, control, confirmed),
3113
3320
  record: (address, say, options) => recordFromDashboard(address, say, options),
3114
3321
  db: (action, connection, say) => databaseFromDashboard(action, connection, say),
3322
+ payments: (run, say, control) => paymentsFromDashboard(run, say, control),
3115
3323
  words: (connection) => nightWords(connection),
3116
3324
  chooseFolder: () => chooseFolder(),
3117
3325
  openFolder: (folder) => openFolderDashboard(folder),
@@ -3438,6 +3646,8 @@ async function main() {
3438
3646
  case 'edge':
3439
3647
  case 'reliability':
3440
3648
  return finishWith(await probeCommand(command, rest));
3649
+ case 'payments':
3650
+ return finishWith(await paymentsCommand(rest));
3441
3651
  case '-v':
3442
3652
  case '--version':
3443
3653
  case 'version':
@@ -3512,6 +3722,11 @@ module.exports = {
3512
3722
  askKey: askKey,
3513
3723
  whenWindowUnconfirmed: whenWindowUnconfirmed,
3514
3724
  windowUnconfirmedLines: windowUnconfirmedLines,
3725
+ windowLateLines: windowLateLines,
3726
+ WINDOW_LATE_MS: WINDOW_LATE_MS,
3727
+ fromDashboardJob: fromDashboardJob,
3728
+ stopChildJob: stopChildJob,
3729
+ STOP_MESSAGE: STOP_MESSAGE,
3515
3730
  WINDOW_TIMEOUT_MS: WINDOW_TIMEOUT_MS,
3516
3731
  WINDOW_HARD_LIMIT_MS: WINDOW_HARD_LIMIT_MS,
3517
3732
  WINDOW_POLL_MS: WINDOW_POLL_MS,
package/kryptheon-code.js CHANGED
@@ -34,6 +34,11 @@ const SKIP_DIRS = new Set([
34
34
  ]);
35
35
  const CODE_EXT = /\.(js|mjs|cjs|jsx|ts|tsx)$/i;
36
36
  const PAGE_EXT = /\.(html|htm|vue|svelte)$/i;
37
+ // Pages the server fills in before it sends them: EJS, Handlebars, Pug,
38
+ // Nunjucks and the rest. Not JavaScript - read for the one thing that matters
39
+ // here, a value written out without escaping. Found on blind round 19: an
40
+ // app's pages were all .ejs, none was read, and <%- c.body %> was missed.
41
+ const TEMPLATE_EXT = /\.(ejs|eta|hbs|handlebars|mustache|pug|jade|njk|nunjucks|liquid|twig|erb)$/i;
37
42
  const MAX_BYTES = 800 * 1024;
38
43
 
39
44
  // A call whose name says it makes text safe for HTML. Matched on the called
@@ -67,7 +72,7 @@ function listFiles(root) {
67
72
  const full = path.join(dir, entry.name);
68
73
  if (entry.isDirectory()) {
69
74
  if (!SKIP_DIRS.has(entry.name)) walk(full);
70
- } else if ((CODE_EXT.test(entry.name) || PAGE_EXT.test(entry.name)) && !/\.min\.js$/i.test(entry.name)) {
75
+ } else if ((CODE_EXT.test(entry.name) || PAGE_EXT.test(entry.name) || TEMPLATE_EXT.test(entry.name)) && !/\.min\.js$/i.test(entry.name)) {
71
76
  out.push(full);
72
77
  }
73
78
  }
@@ -203,6 +208,48 @@ function vHtmlIn(source) {
203
208
  return found;
204
209
  }
205
210
 
211
+ // How each kind of server template writes a value out without escaping it,
212
+ // and the way that escapes it - for the fix.
213
+ const RAW_OUTPUT = [
214
+ { ext: /\.(ejs|eta)$/i, engine: 'EJS', re: /<%-\s*([\s\S]*?)\s*[-_]?%>/g, raw: '<%- %>', escaped: '<%= %>' },
215
+ { ext: /\.(hbs|handlebars|mustache)$/i, engine: 'Handlebars', re: /\{\{\{\s*([\s\S]*?)\s*\}\}\}|\{\{&\s*([\s\S]*?)\s*\}\}/g, raw: '{{{ }}}', escaped: '{{ }}' },
216
+ { ext: /\.(pug|jade)$/i, engine: 'Pug', re: /^[ \t]*[\w.#:-]*(?:\([^)\n]*\))?!=[ \t]*(.+)$|!\{([^}\n]+)\}/gm, raw: '!= or !{ }', escaped: '= or #{ }' },
217
+ { ext: /\.(njk|nunjucks|liquid|twig)$/i, engine: 'Nunjucks', re: /\{\{\s*([^}]*?)\s*\|\s*(?:safe|raw)\b[^}]*\}\}/g, raw: '| safe', escaped: 'the value without | safe' },
218
+ { ext: /\.erb$/i, engine: 'ERB', re: /<%==\s*([\s\S]*?)\s*-?%>|<%=\s*raw[\s(]+([\s\S]*?)\)?\s*-?%>|<%=\s*([\s\S]*?)\.html_safe\s*-?%>/g, raw: '<%== %>, raw or html_safe', escaped: '<%= %>' },
219
+ ];
220
+ // What a template writes out raw on purpose: another template, a layout's
221
+ // page body, a block of a layout.
222
+ const TEMPLATE_PLUMBING = /^(include|partial|render|block|yield|defineContent|contentFor)\b|^(body|locals\.body|script|style|layout)$/;
223
+ // A field whose name says it holds what someone typed: worth more than a guess.
224
+ const TYPED_FIELD = /(^|\.)(body|content|description|desc|comment|comments|text|message|msg|note|notes|bio|about|title|name|summary|html|markdown|reply|caption|subject|label)$/i;
225
+
226
+ /**
227
+ * Values a server template writes out without escaping them: { line,
228
+ * expression, engine, raw, escaped }. A literal, a number, another template
229
+ * and anything an escaping call made safe are left out.
230
+ */
231
+ function rawOutputsIn(file, source) {
232
+ const kind = RAW_OUTPUT.find((k) => k.ext.test(file));
233
+ if (!kind) return [];
234
+ const found = [];
235
+ kind.re.lastIndex = 0;
236
+ let m;
237
+ while ((m = kind.re.exec(source))) {
238
+ const expression = String(m.slice(1).find((g) => g !== undefined) || '').trim().replace(/;$/, '').trim();
239
+ if (!expression || TEMPLATE_PLUMBING.test(expression)) continue;
240
+ if (/^(['"`])[^'"`]*\1$/.test(expression) || /^-?\d+(\.\d+)?$/.test(expression)) continue;
241
+ const call = /^([\w$.]+)\s*\(/.exec(expression);
242
+ if (call && MAKES_SAFE.test(call[1].split('.').pop())) continue;
243
+ // JSON written into a page script: its own risk, said nowhere here.
244
+ if (call && /^JSON\.stringify$/.test(call[1])) continue;
245
+ const last = (/([\w$]+)\s*$/.exec(expression) || [])[1] || '';
246
+ if (/^[\w$.]+$/.test(expression) && (NUMERIC_PROPS.test(last) || NUMERIC_NAMES.test(last) || TAGLESS_COLUMNS.has(last))) continue;
247
+ found.push({ line: source.slice(0, m.index).split('\n').length + (/^\s*\n/.test(m[0]) ? 1 : 0), expression: expression.slice(0, 120),
248
+ engine: kind.engine, raw: kind.raw, escaped: kind.escaped, typed: TYPED_FIELD.test(expression) });
249
+ }
250
+ return found;
251
+ }
252
+
206
253
  function calleeName(node) {
207
254
  if (!node) return '';
208
255
  if (node.type === 'Identifier') return node.name;
@@ -1442,6 +1489,8 @@ function importResolver(parser, root) {
1442
1489
  const MUTATORS = /^(push|pop|shift|unshift|splice|sort|reverse|fill|copyWithin|set|add|delete|clear)$/;
1443
1490
  // Calls that only read what they are given.
1444
1491
  const READS_ONLY = /^(String|Number|Boolean|JSON\.stringify|console\.\w+|Array\.isArray|Object\.(keys|values|entries|freeze|isFrozen))$/;
1492
+ // Calls that only ask whether an object has a key.
1493
+ const HAS_KEY = /(^|\.)(hasOwnProperty|propertyIsEnumerable)\.call$|^Object\.hasOwn$|^Reflect\.has$/;
1445
1494
  // Methods that only read their argument: list.concat(demo.changes) builds a
1446
1495
  // new list and leaves demo alone. push() and the like are not here - they put
1447
1496
  // the value somewhere it can be written through.
@@ -1477,6 +1526,9 @@ function writtenThrough(ref, depth) {
1477
1526
  const full = callee.type === 'MemberExpression' && callee.object.type === 'Identifier'
1478
1527
  ? callee.object.name + '.' + calleeName(callee) : calleeName(callee);
1479
1528
  if (/MemberExpression$/.test(callee.type) && READS_ARGUMENT.test(calleeName(callee))) return false;
1529
+ // Asking whether it has a key reads it (blind round 20, DECOY-05:
1530
+ // Object.prototype.hasOwnProperty.call(styles, status)).
1531
+ if (HAS_KEY.test(memberPath(callee))) return false;
1480
1532
  return !(MAKES_SAFE.test(calleeName(callee)) || READS_ONLY.test(full));
1481
1533
  }
1482
1534
  }
@@ -1739,6 +1791,54 @@ function scanProject(root, options) {
1739
1791
  }
1740
1792
  return { ran: true, filesRead: filesRead, findings: secrets.concat(findings.map(describe)), unreadable: unreadable };
1741
1793
 
1794
+ /**
1795
+ * Whether a function the app declares under `name` (in its own JavaScript,
1796
+ * where a template's helpers live - server.js) returns only text that
1797
+ * cannot carry a tag: every return judged as any value put into a page is.
1798
+ * False when it is not found, or found more than once.
1799
+ */
1800
+ function helperIsSafe(name) {
1801
+ // Kept on the function: readAll runs before any const below its call.
1802
+ const helperSafety = (helperIsSafe.cache = helperIsSafe.cache || new Map());
1803
+ if (helperSafety.has(name)) return helperSafety.get(name);
1804
+ let verdict = false;
1805
+ const declared = new RegExp('(function\\s+' + name + '\\s*\\(|(const|let|var)\\s+' + name + '\\s*=)');
1806
+ const homes = files.filter((f) => CODE_EXT.test(f)).filter((f) => {
1807
+ try {
1808
+ return fs.statSync(f).size <= MAX_BYTES && declared.test(fs.readFileSync(f, 'utf8'));
1809
+ } catch (err) {
1810
+ return false;
1811
+ }
1812
+ });
1813
+ if (homes.length === 1) {
1814
+ try {
1815
+ const code = fs.readFileSync(homes[0], 'utf8');
1816
+ const ast = parser.babelParse(code, homes[0], true);
1817
+ PROGRAM_FILE.set(ast.program, homes[0]);
1818
+ const saved = FN_PATHS;
1819
+ FN_PATHS = new WeakMap();
1820
+ let fnPath = null;
1821
+ parser.traverse(ast, {
1822
+ Function(p) {
1823
+ FN_PATHS.set(p.node, p);
1824
+ },
1825
+ Program(p) {
1826
+ fnPath = localFunction(name, p.scope);
1827
+ },
1828
+ });
1829
+ if (fnPath) {
1830
+ const returns = returnsOf(fnPath);
1831
+ verdict = returns.length > 0 && worst(returns.map((r) => classify(r.node, r.scope, code, 0))) === 'safe';
1832
+ }
1833
+ FN_PATHS = saved;
1834
+ } catch (err) {
1835
+ verdict = false;
1836
+ }
1837
+ }
1838
+ helperSafety.set(name, verdict);
1839
+ return verdict;
1840
+ }
1841
+
1742
1842
  function readAll() {
1743
1843
  for (const full of files) {
1744
1844
  let size = 0;
@@ -1755,7 +1855,19 @@ function scanProject(root, options) {
1755
1855
  const source = fs.readFileSync(full, 'utf8');
1756
1856
  filesRead++;
1757
1857
  for (const k of keys.secretsIn(rel, source, loadedBy)) secrets.push(k);
1758
- const pieces = PAGE_EXT.test(full) ? scriptsIn(source) : [{ code: source, line: 1 }];
1858
+ // A template's own scripts are read as any page's are, unless the
1859
+ // template fills them in itself - then they are not JavaScript yet.
1860
+ const pieces = TEMPLATE_EXT.test(full) ? scriptsIn(source).filter((s) => !/<%|\{\{|[#!]\{/.test(s.code))
1861
+ : PAGE_EXT.test(full) ? scriptsIn(source) : [{ code: source, line: 1 }];
1862
+ if (TEMPLATE_EXT.test(full)) {
1863
+ for (const t of rawOutputsIn(full, source)) {
1864
+ // <%- statusPill(a.status) %>: a helper of the app's own whose every
1865
+ // return is fixed markup is not a way in (blind round 20, DECOY-05).
1866
+ const call = /^([A-Za-z_$][\w$]*)\s*\(/.exec(t.expression);
1867
+ if (call && helperIsSafe(call[1])) continue;
1868
+ findings.push({ file: rel, line: t.line, sink: t.engine + ' ' + t.raw, expression: t.expression, origin: t.typed ? 'template-typed' : 'template', template: t });
1869
+ }
1870
+ }
1759
1871
  for (const piece of pieces) {
1760
1872
  try {
1761
1873
  for (const f of sinksIn(parser, piece.code, full, piece.line, resolver)) findings.push(Object.assign({ file: rel }, f));
@@ -1776,6 +1888,8 @@ const ORIGIN_WORDS = {
1776
1888
  network: 'read from a server response',
1777
1889
  error: "an error's message, which often carries text a server sent",
1778
1890
  unknown: 'from somewhere the code alone cannot pin down',
1891
+ template: 'filled in by the server, from whatever it passes to the page - often a row from the database',
1892
+ 'template-typed': 'filled in by the server from a field whose name says it holds text someone typed',
1779
1893
  };
1780
1894
 
1781
1895
  // Wrapped here rather than by whoever prints it: this is pasted into a chat
@@ -1832,9 +1946,51 @@ function describeRedirect(f) {
1832
1946
  };
1833
1947
  }
1834
1948
 
1949
+ /** A server template writing a value out unescaped, in the same shape. */
1950
+ function describeTemplate(f) {
1951
+ const t = f.template;
1952
+ const typed = f.origin === 'template-typed';
1953
+ const fixPrompt = [
1954
+ 'My app may have a security problem - please check it rather than assume it.',
1955
+ '',
1956
+ 'In ' + f.file + ' at line ' + f.line + ', the page template writes this value into the page without escaping it (' + t.engine + ' ' + t.raw + '):',
1957
+ '',
1958
+ ' ' + f.expression,
1959
+ '',
1960
+ 'The value is ' + ORIGIN_WORDS[f.origin] + '. If it can ever contain text a user or another account typed, a "<" in it ' +
1961
+ 'becomes a real tag and can run script in the page of everyone who opens it, with their session.',
1962
+ '',
1963
+ 'Fix it so the value is shown as text: write it with ' + t.escaped + ' instead of ' + t.raw + ', which escapes it. If it is ' +
1964
+ 'meant to keep some formatting, clean it on the server with a sanitizer (sanitize-html, or DOMPurify) before it is ' +
1965
+ 'passed to the template, and keep ' + t.raw + ' only for that cleaned value.',
1966
+ '',
1967
+ 'Change only how this value is written, and look for the same pattern in the other templates. Afterwards, save a value ' +
1968
+ 'with < and & in it and open the page: both must show as typed.',
1969
+ ].map((p) => (p.startsWith(' ') ? p : wrap(p, 72))).join('\n');
1970
+ return {
1971
+ kind: 'unsafe-html',
1972
+ status: 'verification required',
1973
+ evidence: 'code analysis',
1974
+ severity: typed ? 'HIGH' : 'MEDIUM',
1975
+ confidence: typed ? 'medium' : 'low',
1976
+ file: f.file,
1977
+ line: f.line,
1978
+ sink: f.sink,
1979
+ expression: f.expression,
1980
+ origin: f.origin,
1981
+ parts: [],
1982
+ via: null,
1983
+ helper: null,
1984
+ headline: 'The template ' + f.file + ':' + f.line + ' writes ' + f.expression + ' into the page without escaping it (' + t.engine + ' ' + t.raw + ')' +
1985
+ (typed ? ' - a field that holds what someone typed.' : '.'),
1986
+ fixPrompt: fixPrompt,
1987
+ };
1988
+ }
1989
+
1835
1990
  /** One finding, in the shape every Kryptheon report uses. */
1836
1991
  function describe(f) {
1837
1992
  if (f.kind === 'redirect') return describeRedirect(f);
1993
+ if (f.template) return describeTemplate(f);
1838
1994
  const severity = f.origin === 'unknown' ? 'MEDIUM' : 'HIGH';
1839
1995
  const how = f.sink === 'v-html' ? 'v-html' : f.sink;
1840
1996
  // Where the helper builds it: its own file when it is another one.