kryptheon 0.1.67 → 0.1.69

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.
@@ -53,7 +53,7 @@ const EXCERPT = 240;
53
53
  * The origin requests may go to. Only this computer, and only an origin named
54
54
  * in `allow` when one is given: anything else throws, before any request.
55
55
  */
56
- function assertLocalTarget(baseUrl, allow) {
56
+ function assertLocalTarget(baseUrl, allow, how) {
57
57
  let u;
58
58
  try {
59
59
  u = new URL(String(baseUrl));
@@ -61,7 +61,9 @@ function assertLocalTarget(baseUrl, allow) {
61
61
  throw new Error('authz: "' + baseUrl + '" is not an address');
62
62
  }
63
63
  if (!/^https?:$/.test(u.protocol)) throw new Error('authz: only http or https addresses are allowed');
64
- if (!LOCAL_HOSTS.includes(u.hostname.toLowerCase())) {
64
+ // Another computer's address (a live app) only for a read-only run: GET, and the one sign-in POST - kept in
65
+ // ctx.request below, where every request is sent. Never for a run that may write.
66
+ if (!LOCAL_HOSTS.includes(u.hostname.toLowerCase()) && !(how && how.readOnly === true)) {
65
67
  throw new Error('authz: refused ' + u.origin + ' - this only runs against localhost or 127.0.0.1');
66
68
  }
67
69
  if (allow && allow.length && !allow.includes(u.origin)) {
@@ -477,14 +479,28 @@ function storeCookies(jar, res) {
477
479
  }
478
480
 
479
481
  function makeContext(options) {
480
- const origin = assertLocalTarget(options.baseUrl, options.allowOrigins);
482
+ const origin = assertLocalTarget(options.baseUrl, options.allowOrigins, { readOnly: options.readOnly === true });
483
+ // read-only: what may still be sent besides GET and HEAD - the sign-in, as "POST /path"
484
+ const writesAllowed = new Set((options.readOnly === true ? options.allowWrites || [] : []).map(String));
481
485
  const fetchImpl = options.fetch || globalThis.fetch;
482
486
  const secrets = Object.values(options.passwords || {}).filter(Boolean);
483
487
  // ctx.limit can be raised by a check that knows how big the app is (runSteps); it never goes away.
484
- const ctx = { origin: origin, requests: 0, secrets: secrets, limit: options.maxRequests || MAX_REQUESTS };
488
+ const ctx = { origin: origin, requests: 0, secrets: secrets, limit: options.maxRequests || MAX_REQUESTS, readOnly: options.readOnly === true };
485
489
  ctx.request = async function (session, method, p, opts) {
486
490
  method = String(method).toUpperCase();
491
+ // An app that signs people in with a token (blind round 35: Authorization: Bearer <token>, no sign-in route): the
492
+ // "sign-in" sends nothing; it gives the session its token, and every request after it carries the header.
493
+ if (method === BEARER_SIGN_IN) {
494
+ if (!session.password) return { status: 0, error: 'no token for this account' };
495
+ session.bearer = String(session.password);
496
+ return { status: 200, location: '', text: '', json: { signedIn: 'with a token' } };
497
+ }
487
498
  if (method === 'DELETE') throw new Error('authz: this check never deletes anything');
499
+ if (ctx.readOnly && method !== 'GET' && method !== 'HEAD' && method !== BEARER_SIGN_IN && !writesAllowed.has(method + ' ' + String(p).split('?')[0])) {
500
+ const stop = new Error('authz: read-only - ' + method + ' ' + String(p).split('?')[0] + ' was not sent');
501
+ stop.code = READ_ONLY;
502
+ throw stop;
503
+ }
488
504
  if (String(p).startsWith('//') || /^[a-z]+:/i.test(String(p))) throw new Error('authz: refused a request to "' + p + '" - paths only, on the allowed origin');
489
505
  if (ctx.requests + 1 > ctx.limit) {
490
506
  // A stop, not a crash: the caller keeps what it found so far and says it stopped (blind round 32,
@@ -500,6 +516,7 @@ function makeContext(options) {
500
516
  const headers = { accept: 'application/json, text/html;q=0.8' };
501
517
  const cookie = cookieHeader(session.jar);
502
518
  if (cookie) headers.cookie = cookie;
519
+ if (session.bearer) headers.authorization = 'Bearer ' + session.bearer;
503
520
  for (const k of Object.keys(opts.headers || {})) if (!/^(cookie|host|content-type|content-length)$/i.test(k)) headers[k.toLowerCase()] = String(opts.headers[k]);
504
521
  let body;
505
522
  if (opts.json !== undefined) {
@@ -916,7 +933,12 @@ function reportLines(run) {
916
933
  return lines;
917
934
  }
918
935
 
936
+ const BEARER_SIGN_IN = 'BEARER';
937
+ const READ_ONLY = 'KRYPTHEON_READ_ONLY';
938
+
919
939
  module.exports = {
940
+ BEARER_SIGN_IN,
941
+ READ_ONLY,
920
942
  VERDICT: VERDICT,
921
943
  KINDS: KINDS,
922
944
  assertLocalTarget: assertLocalTarget,
@@ -1,232 +1,232 @@
1
- // Keeping a saved result tied to the recording it came from.
2
- //
3
- // A baseline used to be identified by where the recording lived and what it was
4
- // called. That is not enough. Delete the spec files with `del tests\*.spec.js` -
5
- // which is what anyone does before the tool has taught them `kryptheon remove` -
6
- // record the flow again, and the new recording is handed the same name. Same
7
- // path, same title, same key. It inherits the old recording's saved page and
8
- // fails on its very first run, against a baseline it never created and could
9
- // never have matched.
10
- //
11
- // The report that came out of that said both of these at once:
12
- //
13
- // This has not passed before.
14
- // Headings that are gone: "Transactions"
15
- //
16
- // Which cannot both be true. If it has never passed there is no baseline of its
17
- // own to have changed, so there is nothing to show a difference against.
18
- //
19
- // So a saved result now also records a fingerprint of the recording that made
20
- // it. When the recording is gone, or its steps are not the steps the baseline
21
- // was taken from, the saved result describes something that no longer exists
22
- // and is thrown away rather than compared against.
23
- //
24
- // Pure data work: no Playwright, no test runner.
25
-
26
- const fs = require('fs');
27
- const path = require('path');
28
- const replay = require('./kryptheon-replay.js');
29
-
30
- /** The spec file half of a baseline key, in one consistent shape. */
31
- function specOf(key) {
32
- return String(key || '').split(' :: ')[0].split('\\').join('/');
33
- }
34
-
35
- function titleOf(key) {
36
- const parts = String(key || '').split(' :: ');
37
- return parts.length > 1 ? parts.slice(1).join(' :: ') : '';
38
- }
39
-
40
- /** The fingerprint of the recording in a file, or null if it cannot be read. */
41
- function fingerprintOf(userDir, specPath) {
42
- let source;
43
- try {
44
- source = fs.readFileSync(path.join(userDir, specPath), 'utf8');
45
- } catch (e) {
46
- return null;
47
- }
48
- return replay.recordingId(source);
49
- }
50
-
51
- /**
52
- * What each saved result is: still current, orphaned, or stale.
53
- *
54
- * `orphan` - the recording it belongs to is not there any more.
55
- * `stale` - a recording of that name exists, but it is not the one this was
56
- * taken from. This is the case that cost twenty minutes: the file
57
- * is present, so nothing looks wrong.
58
- * `legacy` - written before fingerprints existed. There is no way to tell
59
- * whether it matches, so it is kept, and a fingerprint is written
60
- * in so the question can be answered next time. Guessing here would
61
- * mean either throwing away a good baseline or, far worse, quietly
62
- * accepting a real regression as the new normal.
63
- */
64
- function classifyBaselines(baselines, userDir) {
65
- const all = baselines || {};
66
- const verdicts = [];
67
-
68
- for (const key of Object.keys(all)) {
69
- const entry = all[key];
70
- const spec = specOf(key);
71
- if (!entry || typeof entry !== 'object') {
72
- verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
73
- continue;
74
- }
75
-
76
- let exists = false;
77
- try {
78
- exists = fs.statSync(path.join(userDir, spec)).isFile();
79
- } catch (e) {
80
- exists = false;
81
- }
82
- if (!exists) {
83
- verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
84
- continue;
85
- }
86
-
87
- const now = fingerprintOf(userDir, spec);
88
- if (!entry.recordingId) {
89
- verdicts.push({ key: key, state: 'legacy', spec: spec, title: titleOf(key), fingerprint: now });
90
- continue;
91
- }
92
- if (now && entry.recordingId !== now) {
93
- verdicts.push({ key: key, state: 'stale', spec: spec, title: titleOf(key), fingerprint: now });
94
- continue;
95
- }
96
- verdicts.push({ key: key, state: 'current', spec: spec, title: titleOf(key) });
97
- }
98
-
99
- return verdicts;
100
- }
101
-
102
- /**
103
- * The saved results with the dead ones taken out.
104
- *
105
- * Returns a new object; nothing is written here. The caller decides whether the
106
- * file is worth rewriting, so a check that changes nothing never touches it.
107
- */
108
- function pruneBaselines(baselines, userDir) {
109
- const all = baselines || {};
110
- const verdicts = classifyBaselines(all, userDir);
111
- const kept = {};
112
- const dropped = [];
113
- let stamped = 0;
114
-
115
- for (const verdict of verdicts) {
116
- if (verdict.state === 'orphan' || verdict.state === 'stale') {
117
- dropped.push(verdict);
118
- continue;
119
- }
120
- const entry = all[verdict.key];
121
- if (verdict.state === 'legacy' && verdict.fingerprint) {
122
- // Kept as it is, but tied to this recording from now on.
123
- kept[verdict.key] = Object.assign({}, entry, { recordingId: verdict.fingerprint });
124
- stamped++;
125
- continue;
126
- }
127
- kept[verdict.key] = entry;
128
- }
129
-
130
- return { baselines: kept, dropped: dropped, stamped: stamped, changed: dropped.length > 0 || stamped > 0 };
131
- }
132
-
133
- function plural(n, word) {
134
- return n + ' ' + word + (n === 1 ? '' : 's');
135
- }
136
-
137
- /**
138
- * One line about what was thrown away, said as a fact rather than a warning.
139
- *
140
- * Nothing has gone wrong when this happens - a recording was deleted or redone,
141
- * which is a normal thing to do. It is said out loud only so that a flow which
142
- * suddenly starts from scratch is not a mystery.
143
- */
144
- function pruneLines(dropped) {
145
- const list = dropped || [];
146
- if (!list.length) return [];
147
-
148
- const orphans = list.filter((d) => d.state === 'orphan');
149
- const stale = list.filter((d) => d.state === 'stale');
150
- const lines = [];
151
-
152
- if (orphans.length) {
153
- lines.push(
154
- ' ' + plural(orphans.length, 'old baseline') + ' removed - ' +
155
- (orphans.length === 1 ? 'its recording is' : 'their recordings are') + ' no longer here.',
156
- );
157
- }
158
- if (stale.length) {
159
- lines.push(
160
- ' ' + plural(stale.length, 'old baseline') + ' removed - ' +
161
- (stale.length === 1 ? 'its recording has' : 'those recordings have') +
162
- ' been recorded again since.',
163
- );
164
- }
165
- lines.push('');
166
- return lines;
167
- }
168
-
169
- /**
170
- * The last run of one recorded test, from the run history: whether it
171
- * passed, and where it broke if it did not. Null when it has never run.
172
- */
173
- function lastRunOf(historyFile, key) {
174
- let lines = [];
175
- try {
176
- lines = fs.readFileSync(historyFile, 'utf8').split('\n').filter(Boolean);
177
- } catch (e) {
178
- return null;
179
- }
180
- const spec = specOf(key);
181
- const title = titleOf(key);
182
- for (let i = lines.length - 1; i >= 0; i--) {
183
- let entry;
184
- try {
185
- entry = JSON.parse(lines[i]);
186
- } catch (e) {
187
- continue;
188
- }
189
- const test = (entry.tests || []).find((t) => t && t.title === title && specOf(t.specFile) === spec);
190
- if (test) return { status: test.status, at: entry.runAt, failure: test.failure || null };
191
- }
192
- return null;
193
- }
194
-
195
- /**
196
- * What accept says when there is nothing it can take, from the last run.
197
- *
198
- * Found on a blind test (HelixOps): a step was broken on purpose, and accept
199
- * answered "it last matched its saved result" - the opposite of what had
200
- * happened. accept only takes a run that went all the way through and ended
201
- * on a different page; a step that no longer matches is a changed flow or a
202
- * broken app, and neither is accepted.
203
- */
204
- function nothingToAcceptLines(name, last) {
205
- if (last && last.status === 'failed') {
206
- const failure = last.failure || {};
207
- const where = failure.line ? ' at line ' + failure.line + (failure.file ? ' of ' + specOf(failure.file) : '') : '';
208
- const what = failure.plainLanguage ? ' (' + String(failure.plainLanguage).replace(/\.$/, '') + ')' : '';
209
- return [
210
- '"' + name + '" has nothing to accept: its last run broke' + where + ', before the end' + what + '.',
211
- 'accept only covers a run that went all the way through and finished on a different page - ' +
212
- 'a new address or a new title.',
213
- 'A step that no longer matches cannot be accepted. If the flow changed on purpose, record it ' +
214
- 'again (npx kryptheon record). If it did not, the app broke, and npx kryptheon check says what to fix.',
215
- ];
216
- }
217
- if (last && last.status === 'passed') {
218
- return ['"' + name + '" has no new result waiting.', 'Nothing to accept - its last run matched its saved result.'];
219
- }
220
- return ['"' + name + '" has no new result waiting.', 'Nothing to accept - no run has finished on a different page.'];
221
- }
222
-
223
- module.exports = {
224
- specOf: specOf,
225
- titleOf: titleOf,
226
- fingerprintOf: fingerprintOf,
227
- classifyBaselines: classifyBaselines,
228
- pruneBaselines: pruneBaselines,
229
- pruneLines: pruneLines,
230
- lastRunOf: lastRunOf,
231
- nothingToAcceptLines: nothingToAcceptLines,
232
- };
1
+ // Keeping a saved result tied to the recording it came from.
2
+ //
3
+ // A baseline used to be identified by where the recording lived and what it was
4
+ // called. That is not enough. Delete the spec files with `del tests\*.spec.js` -
5
+ // which is what anyone does before the tool has taught them `kryptheon remove` -
6
+ // record the flow again, and the new recording is handed the same name. Same
7
+ // path, same title, same key. It inherits the old recording's saved page and
8
+ // fails on its very first run, against a baseline it never created and could
9
+ // never have matched.
10
+ //
11
+ // The report that came out of that said both of these at once:
12
+ //
13
+ // This has not passed before.
14
+ // Headings that are gone: "Transactions"
15
+ //
16
+ // Which cannot both be true. If it has never passed there is no baseline of its
17
+ // own to have changed, so there is nothing to show a difference against.
18
+ //
19
+ // So a saved result now also records a fingerprint of the recording that made
20
+ // it. When the recording is gone, or its steps are not the steps the baseline
21
+ // was taken from, the saved result describes something that no longer exists
22
+ // and is thrown away rather than compared against.
23
+ //
24
+ // Pure data work: no Playwright, no test runner.
25
+
26
+ const fs = require('fs');
27
+ const path = require('path');
28
+ const replay = require('./kryptheon-replay.js');
29
+
30
+ /** The spec file half of a baseline key, in one consistent shape. */
31
+ function specOf(key) {
32
+ return String(key || '').split(' :: ')[0].split('\\').join('/');
33
+ }
34
+
35
+ function titleOf(key) {
36
+ const parts = String(key || '').split(' :: ');
37
+ return parts.length > 1 ? parts.slice(1).join(' :: ') : '';
38
+ }
39
+
40
+ /** The fingerprint of the recording in a file, or null if it cannot be read. */
41
+ function fingerprintOf(userDir, specPath) {
42
+ let source;
43
+ try {
44
+ source = fs.readFileSync(path.join(userDir, specPath), 'utf8');
45
+ } catch (e) {
46
+ return null;
47
+ }
48
+ return replay.recordingId(source);
49
+ }
50
+
51
+ /**
52
+ * What each saved result is: still current, orphaned, or stale.
53
+ *
54
+ * `orphan` - the recording it belongs to is not there any more.
55
+ * `stale` - a recording of that name exists, but it is not the one this was
56
+ * taken from. This is the case that cost twenty minutes: the file
57
+ * is present, so nothing looks wrong.
58
+ * `legacy` - written before fingerprints existed. There is no way to tell
59
+ * whether it matches, so it is kept, and a fingerprint is written
60
+ * in so the question can be answered next time. Guessing here would
61
+ * mean either throwing away a good baseline or, far worse, quietly
62
+ * accepting a real regression as the new normal.
63
+ */
64
+ function classifyBaselines(baselines, userDir) {
65
+ const all = baselines || {};
66
+ const verdicts = [];
67
+
68
+ for (const key of Object.keys(all)) {
69
+ const entry = all[key];
70
+ const spec = specOf(key);
71
+ if (!entry || typeof entry !== 'object') {
72
+ verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
73
+ continue;
74
+ }
75
+
76
+ let exists = false;
77
+ try {
78
+ exists = fs.statSync(path.join(userDir, spec)).isFile();
79
+ } catch (e) {
80
+ exists = false;
81
+ }
82
+ if (!exists) {
83
+ verdicts.push({ key: key, state: 'orphan', spec: spec, title: titleOf(key) });
84
+ continue;
85
+ }
86
+
87
+ const now = fingerprintOf(userDir, spec);
88
+ if (!entry.recordingId) {
89
+ verdicts.push({ key: key, state: 'legacy', spec: spec, title: titleOf(key), fingerprint: now });
90
+ continue;
91
+ }
92
+ if (now && entry.recordingId !== now) {
93
+ verdicts.push({ key: key, state: 'stale', spec: spec, title: titleOf(key), fingerprint: now });
94
+ continue;
95
+ }
96
+ verdicts.push({ key: key, state: 'current', spec: spec, title: titleOf(key) });
97
+ }
98
+
99
+ return verdicts;
100
+ }
101
+
102
+ /**
103
+ * The saved results with the dead ones taken out.
104
+ *
105
+ * Returns a new object; nothing is written here. The caller decides whether the
106
+ * file is worth rewriting, so a check that changes nothing never touches it.
107
+ */
108
+ function pruneBaselines(baselines, userDir) {
109
+ const all = baselines || {};
110
+ const verdicts = classifyBaselines(all, userDir);
111
+ const kept = {};
112
+ const dropped = [];
113
+ let stamped = 0;
114
+
115
+ for (const verdict of verdicts) {
116
+ if (verdict.state === 'orphan' || verdict.state === 'stale') {
117
+ dropped.push(verdict);
118
+ continue;
119
+ }
120
+ const entry = all[verdict.key];
121
+ if (verdict.state === 'legacy' && verdict.fingerprint) {
122
+ // Kept as it is, but tied to this recording from now on.
123
+ kept[verdict.key] = Object.assign({}, entry, { recordingId: verdict.fingerprint });
124
+ stamped++;
125
+ continue;
126
+ }
127
+ kept[verdict.key] = entry;
128
+ }
129
+
130
+ return { baselines: kept, dropped: dropped, stamped: stamped, changed: dropped.length > 0 || stamped > 0 };
131
+ }
132
+
133
+ function plural(n, word) {
134
+ return n + ' ' + word + (n === 1 ? '' : 's');
135
+ }
136
+
137
+ /**
138
+ * One line about what was thrown away, said as a fact rather than a warning.
139
+ *
140
+ * Nothing has gone wrong when this happens - a recording was deleted or redone,
141
+ * which is a normal thing to do. It is said out loud only so that a flow which
142
+ * suddenly starts from scratch is not a mystery.
143
+ */
144
+ function pruneLines(dropped) {
145
+ const list = dropped || [];
146
+ if (!list.length) return [];
147
+
148
+ const orphans = list.filter((d) => d.state === 'orphan');
149
+ const stale = list.filter((d) => d.state === 'stale');
150
+ const lines = [];
151
+
152
+ if (orphans.length) {
153
+ lines.push(
154
+ ' ' + plural(orphans.length, 'old baseline') + ' removed - ' +
155
+ (orphans.length === 1 ? 'its recording is' : 'their recordings are') + ' no longer here.',
156
+ );
157
+ }
158
+ if (stale.length) {
159
+ lines.push(
160
+ ' ' + plural(stale.length, 'old baseline') + ' removed - ' +
161
+ (stale.length === 1 ? 'its recording has' : 'those recordings have') +
162
+ ' been recorded again since.',
163
+ );
164
+ }
165
+ lines.push('');
166
+ return lines;
167
+ }
168
+
169
+ /**
170
+ * The last run of one recorded test, from the run history: whether it
171
+ * passed, and where it broke if it did not. Null when it has never run.
172
+ */
173
+ function lastRunOf(historyFile, key) {
174
+ let lines = [];
175
+ try {
176
+ lines = fs.readFileSync(historyFile, 'utf8').split('\n').filter(Boolean);
177
+ } catch (e) {
178
+ return null;
179
+ }
180
+ const spec = specOf(key);
181
+ const title = titleOf(key);
182
+ for (let i = lines.length - 1; i >= 0; i--) {
183
+ let entry;
184
+ try {
185
+ entry = JSON.parse(lines[i]);
186
+ } catch (e) {
187
+ continue;
188
+ }
189
+ const test = (entry.tests || []).find((t) => t && t.title === title && specOf(t.specFile) === spec);
190
+ if (test) return { status: test.status, at: entry.runAt, failure: test.failure || null };
191
+ }
192
+ return null;
193
+ }
194
+
195
+ /**
196
+ * What accept says when there is nothing it can take, from the last run.
197
+ *
198
+ * Found on a blind test (HelixOps): a step was broken on purpose, and accept
199
+ * answered "it last matched its saved result" - the opposite of what had
200
+ * happened. accept only takes a run that went all the way through and ended
201
+ * on a different page; a step that no longer matches is a changed flow or a
202
+ * broken app, and neither is accepted.
203
+ */
204
+ function nothingToAcceptLines(name, last) {
205
+ if (last && last.status === 'failed') {
206
+ const failure = last.failure || {};
207
+ const where = failure.line ? ' at line ' + failure.line + (failure.file ? ' of ' + specOf(failure.file) : '') : '';
208
+ const what = failure.plainLanguage ? ' (' + String(failure.plainLanguage).replace(/\.$/, '') + ')' : '';
209
+ return [
210
+ '"' + name + '" has nothing to accept: its last run broke' + where + ', before the end' + what + '.',
211
+ 'accept only covers a run that went all the way through and finished on a different page - ' +
212
+ 'a new address or a new title.',
213
+ 'A step that no longer matches cannot be accepted. If the flow changed on purpose, record it ' +
214
+ 'again (npx kryptheon record). If it did not, the app broke, and npx kryptheon check says what to fix.',
215
+ ];
216
+ }
217
+ if (last && last.status === 'passed') {
218
+ return ['"' + name + '" has no new result waiting.', 'Nothing to accept - its last run matched its saved result.'];
219
+ }
220
+ return ['"' + name + '" has no new result waiting.', 'Nothing to accept - no run has finished on a different page.'];
221
+ }
222
+
223
+ module.exports = {
224
+ specOf: specOf,
225
+ titleOf: titleOf,
226
+ fingerprintOf: fingerprintOf,
227
+ classifyBaselines: classifyBaselines,
228
+ pruneBaselines: pruneBaselines,
229
+ pruneLines: pruneLines,
230
+ lastRunOf: lastRunOf,
231
+ nothingToAcceptLines: nothingToAcceptLines,
232
+ };