kryptheon 0.1.54 → 0.1.56

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/README.md CHANGED
@@ -244,6 +244,85 @@ is "verification required", ranked HIGH when the value comes from a server
244
244
  response or an error message, MEDIUM when the code alone cannot say. The fix
245
245
  prompt for each one names the file, line and value.
246
246
 
247
+ ## Backend map
248
+
249
+ ```
250
+ npx kryptheon map
251
+ ```
252
+
253
+ Reads your server code - never runs it, sends nothing, changes no file - and
254
+ lists every route it can read: Express (routers mounted under prefixes,
255
+ `app.route()`, route files handed the app, handlers imported from other
256
+ files), Supabase Edge Functions (`supabase/functions/<name>/index.ts`) and
257
+ Next.js (`pages/api/**`, `app/**/route.ts`, `middleware.ts` and its matcher).
258
+ For each route:
259
+
260
+ - the middleware in front of it, inherited ones included, with the file and
261
+ line each is defined and used on;
262
+ - a sign-in check, a role check and, for webhooks, a signature check - each
263
+ `guard_detected`, `not_detected` or `unknown`. `not_detected` is said only
264
+ when everything in front of the route was found and read; when the request
265
+ is handed to code that could not be followed, the answer is `unknown` and
266
+ says where it went;
267
+ - every database statement its handler makes (SQL, `sql` templates, supabase
268
+ `.from()`, prisma), with the table, the operation, and whether its rows are
269
+ limited to the signed-in person's organisation - read from the WHERE clause,
270
+ the inserted columns and where each value comes from. Row level security, a
271
+ table with no schema, or SQL built at run time make that `unknown`;
272
+ - each field it is sent, and the checks made on it before it is used.
273
+
274
+ It then lists what is worth a look - a webhook whose signature is not
275
+ checked, a write with no sign-in check, a statement on another organisation's
276
+ rows, an organisation taken from the request - each with its file and line and
277
+ a prompt for your AI tool. Everything it points at is "to check": a reading of
278
+ code proves nothing. `npx kryptheon roles` proves it on the running app.
279
+
280
+ What it cannot read is listed, with its file and line, never skipped: a path
281
+ chosen at run time, middleware from a package, a router nobody mounts, server
282
+ actions, and frameworks it does not read yet (Fastify, Koa, Hono, NestJS). The
283
+ whole map is kept as `map-last.json` beside what Kryptheon remembers of the
284
+ project; `--json` prints it. On the dashboard it is the "Backend map" check.
285
+
286
+ ## API check
287
+
288
+ ```
289
+ npx kryptheon api
290
+ npx kryptheon api --run --origin http://localhost:3000 --yes
291
+ ```
292
+
293
+ Takes every route the backend map read and tries it on your running app, with
294
+ no recordings. The first form is a dry run: it sends nothing and lists what
295
+ would be tried, as whom, and what would not be tried and why. The second sends
296
+ requests, and only to an app on this computer (localhost or 127.0.0.1) - use a
297
+ test copy, because it adds test data. It never sends a DELETE, and lists
298
+ anything it could not put back.
299
+
300
+ - **Who can sign in:** an account is used only when its email is named in your
301
+ README, permissions file or tests and its password is set as
302
+ `KRYPTHEON_PASSWORD_<NAME>` in `.env` or the environment (`jane@acme.test`
303
+ becomes `KRYPTHEON_PASSWORD_JANE_ACME`). A password is never guessed, read from
304
+ a README, printed or saved.
305
+ - **Across organizations and without a session:** each account is aimed at the
306
+ other organizations' records (found in the app's own lists), and every route
307
+ is tried with no session at all. Judged from what comes back and from what the
308
+ app holds before and after, never from a status code alone. Needs two accounts.
309
+ - **Bad values:** for each route that creates something, one field at a time -
310
+ only fields the map saw read with no check - gets a value that should be
311
+ turned away (text for a number, 3000 characters). The app's own list says
312
+ whether it was kept. A value kept is a finding; a server error is a smaller one.
313
+ - **Who may do what:** with `--roles` and your `permissions-policy.json`, each
314
+ account also tries what its role may not do. `npx kryptheon api --draft`
315
+ writes `permissions-policy.draft.json`, a guess from your code that the roles
316
+ check refuses until you edit it and remove its `draft` line.
317
+ - **Verdicts:** every item the backend map pointed at is marked `confirmed` (a
318
+ try on the running app got through), `held`, `not judged`, or `not tried` with
319
+ the reason.
320
+
321
+ A route whose body would miss a field Kryptheon never makes up a value for (a
322
+ role) is not sent. The run is kept as `api-last.json`, and on the dashboard it
323
+ is the "API" check - read there, run only from the terminal. Exit code 1 means
324
+ a problem was confirmed.
325
+
247
326
  ## Unusual inputs
248
327
 
249
328
  ```
package/bin/kryptheon.js CHANGED
@@ -31,6 +31,8 @@ const FIRST_STORE_VERSION = '0.1.20';
31
31
 
32
32
  const PACKAGE_DIR = path.join(__dirname, '..');
33
33
  const USER_DIR = process.cwd();
34
+ // The last backend map, kept with the rest of what Kryptheon remembers of this project (the dashboard reads it).
35
+ const MAP_FILE = 'map-last.json';
34
36
  const CONFIG = path.join(PACKAGE_DIR, 'playwright.config.js');
35
37
  const TESTS_DIR = path.join(USER_DIR, 'tests');
36
38
 
@@ -105,6 +107,9 @@ function usage() {
105
107
  console.log(' npx kryptheon verify after a change: what changed, what broke, what got fixed');
106
108
  console.log(' npx kryptheon recheck [id] prove a fix: run the check again, and say FIXED or not');
107
109
  console.log(' npx kryptheon code read your frontend code for text inserted as HTML');
110
+ console.log(' npx kryptheon map read your server code: every route, its sign-in and role checks, the tables it touches');
111
+ console.log(' ... --json print the whole map as JSON');
112
+ console.log(' npx kryptheon api try every mapped route on your app on this computer (a dry run unless --run --origin <url> --yes)');
108
113
  console.log(' npx kryptheon edge try unusual values in your recorded forms (adds test data; asks first)');
109
114
  console.log(' npx kryptheon reliability replay each flow 3 times, double-click what saves (adds test data; asks first)');
110
115
  console.log(' npx kryptheon roles every recorded action tried as each account, and across organizations (needs permissions-policy.json; asks first)');
@@ -2452,6 +2457,125 @@ function readCodeAndSave(opened) {
2452
2457
  return result;
2453
2458
  }
2454
2459
 
2460
+ /**
2461
+ * The backend map: reads the app's server code (never runs it) and keeps the
2462
+ * map beside what Kryptheon remembers of this project, for the dashboard.
2463
+ */
2464
+ function readMapAndSave(opened) {
2465
+ const reader = require(path.join(PACKAGE_DIR, 'kryptheon-map.js'));
2466
+ const result = reader.mapProject(USER_DIR, { packageDir: PACKAGE_DIR });
2467
+ if (!result.ran) return result;
2468
+ result.checkedAt = new Date().toISOString();
2469
+ result.toCheck = reader.toCheck(result);
2470
+ result.summary = reader.summary(result);
2471
+ try {
2472
+ fs.writeFileSync(path.join(opened.dir, MAP_FILE), JSON.stringify(result, null, 2) + String.fromCharCode(10), 'utf8');
2473
+ } catch (err) {
2474
+ result.saveError = err.message;
2475
+ }
2476
+ return result;
2477
+ }
2478
+
2479
+ function mapRead(options) {
2480
+ const here = project.inspectCodeFolder(USER_DIR);
2481
+ if (!here.ok) {
2482
+ for (const line of project.noProjectLines(here)) console.error(line);
2483
+ return 1;
2484
+ }
2485
+ const opened = openStore();
2486
+ if (!opened) return 1;
2487
+ const result = readMapAndSave(opened);
2488
+ if (!result.ran) {
2489
+ console.error('');
2490
+ console.error(' I could not read your code this time: ' + result.why + '.');
2491
+ console.error(' Nothing was mapped - this is not a pass.');
2492
+ console.error('');
2493
+ return 2;
2494
+ }
2495
+ if (options && options.json) {
2496
+ console.log(JSON.stringify(result, null, 2));
2497
+ return 0;
2498
+ }
2499
+ const reader = require(path.join(PACKAGE_DIR, 'kryptheon-map.js'));
2500
+ for (const line of reader.reportLines(result)) console.log(line);
2501
+ if (result.saveError) console.error(' (could not save this map: ' + result.saveError + ')');
2502
+ else console.log(' The whole map, with every route\'s middleware, tables and fields: ' + path.join(opened.dir, MAP_FILE));
2503
+ console.log('');
2504
+ return 0;
2505
+ }
2506
+
2507
+ // --- api: every mapped route tried on the running app -----------------------
2508
+ //
2509
+ // Default is a dry run (nothing is sent). --draft writes permissions-policy.draft.json.
2510
+ // --run --origin http://localhost:3000 --yes tries the routes on an app on this
2511
+ // computer: across organizations, without a session, bad values in unchecked
2512
+ // fields; --roles adds who-may-do-what from permissions-policy.json.
2513
+
2514
+ async function apiCommand(args) {
2515
+ const here = project.inspectCodeFolder(USER_DIR);
2516
+ if (!here.ok) {
2517
+ for (const line of project.noProjectLines(here)) console.error(line);
2518
+ return 1;
2519
+ }
2520
+ const opened = openStore();
2521
+ if (!opened) return 1;
2522
+ const api = require(path.join(PACKAGE_DIR, 'kryptheon-api.js'));
2523
+ const reader = require(path.join(PACKAGE_DIR, 'kryptheon-map.js'));
2524
+ if (args.includes('--draft')) {
2525
+ const draft = api.draftPolicy(api.planOf(USER_DIR, { packageDir: PACKAGE_DIR }));
2526
+ if (!draft.ok) {
2527
+ console.error('');
2528
+ console.error(' No draft written: ' + draft.why);
2529
+ console.error('');
2530
+ return 2;
2531
+ }
2532
+ const written = api.writeDraft(USER_DIR, draft.text);
2533
+ console.log('');
2534
+ console.log(written.ok ? ' Wrote ' + written.file + '. It is a guess from your code: edit it, remove its "draft" line, and save it as permissions-policy.json.' : ' ' + written.why);
2535
+ console.log('');
2536
+ return written.ok ? 0 : 2;
2537
+ }
2538
+ if (!args.includes('--run')) {
2539
+ for (const line of api.planLines(api.planOf(USER_DIR, { packageDir: PACKAGE_DIR }))) console.log(line);
2540
+ console.log(' To try them on your app on this computer: npx kryptheon api --run --origin http://localhost:3000 --yes');
2541
+ console.log(' Use a test copy: it adds test data and never deletes it.');
2542
+ console.log('');
2543
+ return 0;
2544
+ }
2545
+ const origin = flagValue(args, '--origin');
2546
+ if (!origin) {
2547
+ console.error('');
2548
+ console.error(' --run needs --origin, the address of your app on this computer (for example http://localhost:3000).');
2549
+ console.error('');
2550
+ return 2;
2551
+ }
2552
+ if (!args.includes('--yes')) {
2553
+ console.log('');
2554
+ console.log(' This signs in to ' + origin + ' as the accounts whose passwords are in your .env, and sends requests that must be refused');
2555
+ console.log(' (another organization\'s records, no session, values that should be turned away). It adds test data and never deletes it.');
2556
+ console.log(' Run it on a test copy only. To go ahead, add --yes.');
2557
+ console.log('');
2558
+ return 2;
2559
+ }
2560
+ let stopped = false;
2561
+ const onSigint = () => { stopped = true; };
2562
+ process.once('SIGINT', onSigint);
2563
+ const m = reader.mapProject(USER_DIR, { packageDir: PACKAGE_DIR });
2564
+ const run = await api.runApi(USER_DIR, {
2565
+ map: m, toCheck: m.ran ? reader.toCheck(m) : [], origin: origin, roles: args.includes('--roles'), packageDir: PACKAGE_DIR,
2566
+ say: (line) => console.log(' ' + line), stopped: () => stopped,
2567
+ });
2568
+ process.removeListener('SIGINT', onSigint);
2569
+ for (const line of api.apiLines(run)) console.log(line);
2570
+ if (run.ran) {
2571
+ const saved = api.saveReport(opened.dir, run);
2572
+ console.log(saved.ok ? ' Saved: ' + saved.file : ' (could not save this run: ' + saved.why + ')');
2573
+ console.log('');
2574
+ }
2575
+ if (!run.ran) return 2;
2576
+ return run.findings.some((f) => f.status === 'confirmed') ? 1 : 0;
2577
+ }
2578
+
2455
2579
  function codeRead() {
2456
2580
  const here = project.inspectCodeFolder(USER_DIR);
2457
2581
  if (!here.ok) {
@@ -2623,6 +2747,7 @@ function verify() {
2623
2747
  }
2624
2748
  },
2625
2749
  frontend: () => readCodeAndSave(opened),
2750
+ backend: () => readMapAndSave(opened),
2626
2751
  regression: () => {
2627
2752
  console.log('');
2628
2753
  console.log(' Replaying your recordings...');
@@ -2793,7 +2918,7 @@ function recheckCommand(id, options) {
2793
2918
  const probeTarget = dash.buildState(USER_DIR).findings.find((f) => f.id === String(id).trim() && PROBE_CHECKS[f.check]);
2794
2919
  if (probeTarget) return probeRecheckCommand(probeTarget, options);
2795
2920
 
2796
- const r = looker.recheck(USER_DIR, { frontend: () => readCodeAndSave(opened), regression: replayForLoop }, String(id).trim());
2921
+ const r = looker.recheck(USER_DIR, { frontend: () => readCodeAndSave(opened), backend: () => readMapAndSave(opened), regression: replayForLoop }, String(id).trim());
2797
2922
  console.log('');
2798
2923
  if (!r.found) {
2799
2924
  console.error(' There is no open finding with the id ' + id + '.');
@@ -2956,6 +3081,17 @@ function scanSummary(code, printed) {
2956
3081
  }
2957
3082
 
2958
3083
  function runFromDashboard(id, opened, say) {
3084
+ if (id === 'backend') {
3085
+ say('Reading the server code in ' + USER_DIR + ' ...');
3086
+ const result = readMapAndSave(opened);
3087
+ if (!result.ran) {
3088
+ say(result.why);
3089
+ return { ok: false, why: result.why };
3090
+ }
3091
+ const n = result.toCheck.length;
3092
+ say('Read ' + result.filesRead + (result.filesRead === 1 ? ' file: ' : ' files: ') + result.summary.routes + ' route' + (result.summary.routes === 1 ? '' : 's') + '. ' + (n ? n + ' thing' + (n === 1 ? '' : 's') + ' to check.' : 'Nothing stood out.'));
3093
+ return { ok: true, summary: result.summary.routes + ' routes, ' + (n ? n + ' to check' : 'nothing stood out') };
3094
+ }
2959
3095
  if (id === 'frontend') {
2960
3096
  say('Reading the code in ' + USER_DIR + ' ...');
2961
3097
  const result = readCodeAndSave(opened);
@@ -3450,6 +3586,7 @@ async function dashboardCommand() {
3450
3586
  const looker = require(path.join(PACKAGE_DIR, 'kryptheon-look.js'));
3451
3587
  looker.startWatch(USER_DIR, {
3452
3588
  frontend: () => readCodeAndSave(opened),
3589
+ backend: () => readMapAndSave(opened),
3453
3590
  regression: () => null,
3454
3591
  }, {
3455
3592
  onLook: (r) => {
@@ -3738,6 +3875,11 @@ async function main() {
3738
3875
  break;
3739
3876
  case 'code':
3740
3877
  return finishWith(codeRead());
3878
+ case 'map':
3879
+ case 'backend':
3880
+ return finishWith(mapRead({ json: rest.includes('--json') }));
3881
+ case 'api':
3882
+ return finishWith(await apiCommand(rest));
3741
3883
  case 'verify':
3742
3884
  return finishWith(verify());
3743
3885
  case 'recheck':