kryptheon 0.1.55 → 0.1.57

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.
@@ -85,6 +85,8 @@ function loadPolicy(root) {
85
85
  function checkPolicy(json) {
86
86
  const problems = [];
87
87
  if (!json || typeof json !== 'object' || Array.isArray(json)) return { ok: false, problems: ['it must be a JSON object with a "roles" section.'] };
88
+ // A draft Kryptheon wrote from the code says what the code does today, not what the owner wants.
89
+ if (json.draft !== undefined) return { ok: false, problems: ['it is still marked "draft": it lists what your code does today, not what you want. Edit each role to what you want, then delete the "draft" line.'] };
88
90
  const roles = {};
89
91
  if (!json.roles || typeof json.roles !== 'object' || Array.isArray(json.roles)) problems.push('"roles" must say, for each role, the list of permissions it has.');
90
92
  else {
@@ -106,6 +108,8 @@ function checkPolicy(json) {
106
108
 
107
109
  /** Whether `role` has `permission` ("*" and "resource.*" are allowed in the file). */
108
110
  function holds(policy, role, permission) {
111
+ // The API check's organization-only run: who may do what is not judged, every signed-in account may.
112
+ if (policy.anyRole) return true;
109
113
  const key = Object.keys(policy.roles).find((r) => r.toLowerCase() === String(role || '').toLowerCase());
110
114
  if (!key) return false;
111
115
  return policy.roles[key].some((p) => p === permission || p === '*' || (p.endsWith('.*') && permission.startsWith(p.slice(0, -1))));
@@ -437,6 +441,13 @@ function findUser(json) {
437
441
  return pools.find(looks) || null;
438
442
  }
439
443
 
444
+ /** Who the app says is signed in when it names no role: an object with an id and an email. */
445
+ function findAnyUser(json) {
446
+ const looks = (o) => o && typeof o === 'object' && !Array.isArray(o) && o.id !== undefined && typeof o.email === 'string';
447
+ const pools = [json, json && json.user, json && json.data, json && json.data && json.data.user, json && json.me, json && json.account, json && json.profile];
448
+ return pools.find(looks) || null;
449
+ }
450
+
440
451
  function orgOf(user, extra) {
441
452
  const idPath = extra && extra.identity && extra.identity.orgPath;
442
453
  const namePath = extra && extra.identity && extra.identity.orgNamePath;
@@ -509,7 +520,7 @@ async function checkAccess(input) {
509
520
  for (const p of candidates) {
510
521
  const me = await s.send('GET', p);
511
522
  if (me.status === 200 && me.json) {
512
- user = findUser(me.json);
523
+ user = findUser(me.json) || (policy.anyRole ? findAnyUser(me.json) : null);
513
524
  if (user) break;
514
525
  }
515
526
  }
@@ -517,8 +528,8 @@ async function checkAccess(input) {
517
528
  skipped.push({ what: a.email, why: 'signed in, but the app did not say who it is (looked at ' + candidates.slice(0, 3).join(', ') + '...). Name the address in ' + POLICY_FILE + ' under kryptheon.identity.path' });
518
529
  continue;
519
530
  }
520
- const roleName = typeof user.role === 'string' ? user.role : user.role.name;
521
- const known = Object.keys(policy.roles).find((r) => r.toLowerCase() === roleName.toLowerCase());
531
+ const roleName = typeof user.role === 'string' ? user.role : user.role ? user.role.name : 'signed in';
532
+ const known = policy.anyRole ? roleName : Object.keys(policy.roles).find((r) => r.toLowerCase() === roleName.toLowerCase());
522
533
  if (!known) {
523
534
  skipped.push({ what: a.email, why: 'the app says its role is "' + roleName + '", which ' + POLICY_FILE + ' does not list' });
524
535
  continue;
@@ -601,7 +612,7 @@ async function checkAccess(input) {
601
612
  for (const t of Object.keys(after)) if (before[t] !== undefined) lines.push.apply(lines, diffLines(t, before[t], after[t]));
602
613
  return lines;
603
614
  };
604
- for (const key of orgs.keys()) {
615
+ for (const key of orgs.size ? Array.from(orgs.keys()) : [null]) {
605
616
  const one = await snapshot(key);
606
617
  const two = await snapshot(key);
607
618
  for (const t of Object.keys(one)) if (JSON.stringify(one[t]) !== JSON.stringify(two[t])) {
@@ -641,12 +652,53 @@ async function checkAccess(input) {
641
652
  fieldCache.set(k, field);
642
653
  return field;
643
654
  };
655
+ // A route whose address names a record, with no list of those records but a POST at the same address: the POST is sent once
656
+ // per organization (by an account that may) and the id in its answer is the record to aim at. Test data, listed.
657
+ const seeded = new Map();
658
+ out.seeded = [];
659
+ const idIn = (json) => {
660
+ const find = (v, depth) => {
661
+ if (v == null || typeof v !== 'object' || depth > 2) return undefined;
662
+ if (!Array.isArray(v) && ['string', 'number'].includes(typeof v.id)) return v.id;
663
+ for (const k of Object.keys(v)) {
664
+ const f = find(v[k], depth + 1);
665
+ if (f !== undefined) return f;
666
+ }
667
+ return undefined;
668
+ };
669
+ return find(json, 0);
670
+ };
671
+ if (input.seed) {
672
+ for (const action of journey.actions) {
673
+ if (action.params.length !== 1) continue;
674
+ const listing = '/' + action.segs.slice(0, action.params[0].index).join('/');
675
+ if (getTemplates.has(listing) || seeded.has(listing)) continue;
676
+ const maker = journey.actions.find((a) => a.method === 'POST' && a.template === listing && !a.params.length);
677
+ if (!maker) continue;
678
+ const perm = (mapped.find((m) => m.method === 'POST' && m.template === listing) || {}).permission || null;
679
+ const made = [];
680
+ for (const org of orgs.size ? Array.from(orgs.keys()) : [null]) {
681
+ const who = accountsOf(org).find((ss) => !perm || holds(policy, ss.role, perm)) || accountsOf(org)[0];
682
+ if (!who) continue;
683
+ const body = sampleBody(maker);
684
+ const res = await who.send('POST', listing, maker.encoding === 'form' ? { form: body } : { json: body });
685
+ const id = res.status >= 200 && res.status < 300 ? idIn(res.json) : undefined;
686
+ if (id === undefined) continue;
687
+ made.push({ org: org, value: id, item: res.json, listing: listing, field: 'id' });
688
+ out.seeded.push('POST ' + listing + ' -> ' + id + (org !== null ? ' (' + (orgs.get(org) ? orgs.get(org).name : org) + ')' : '') + ': made to have a record to aim at');
689
+ }
690
+ seeded.set(listing, made);
691
+ }
692
+ }
644
693
  /** The records of one organization an action's address can be aimed at: [{ value, item }]. */
645
694
  const targetsFor = async (action, orgKey) => {
646
695
  if (!action.params.length) return [{ value: null, item: null }];
647
696
  if (action.params.length > 1) return null;
648
697
  const listing = '/' + action.segs.slice(0, action.params[0].index).join('/');
649
- if (!getTemplates.has(listing)) return null;
698
+ if (!getTemplates.has(listing)) {
699
+ const mine = (seeded.get(listing) || []).filter((r) => r.org === orgKey);
700
+ return mine.length ? mine : null;
701
+ }
650
702
  const items = await itemsOf(orgKey, listing);
651
703
  if (!items) return null;
652
704
  const field = await fieldFor(action, listing);
@@ -693,6 +745,15 @@ async function checkAccess(input) {
693
745
  }
694
746
  }
695
747
  }
748
+ // Asked for (the API check): every action once with no session at all, aimed at
749
+ // the first organization's records and judged by its lists before and after.
750
+ if (input.anonymous) {
751
+ const anon = authz.makeSession(ctx, null, '(not signed in)', null);
752
+ anon.role = 'not signed in';
753
+ anon.org = null;
754
+ const first = sessions.find((s) => s.org);
755
+ for (const action of mapped) plan.push({ action: action, actor: anon, kind: 'signin', expected: 'deny', org: first ? first.org.key : null });
756
+ }
696
757
  // Refusals first, so a control that changes things (an archive, a job) cannot make a later refusal look kept.
697
758
  const rank = (p) => (p.expected === 'deny' ? 0 : 1);
698
759
  plan.sort((a, b) => rank(a) - rank(b));
@@ -736,7 +797,8 @@ async function checkAccess(input) {
736
797
  groups.get(k).push(a);
737
798
  }
738
799
  for (const [k, list] of groups) {
739
- if (list.every((a) => !a.notTried && a.response.status === 401)) {
800
+ const signedIn = list.filter((a) => a.kind !== 'signin');
801
+ if (signedIn.length && signedIn.every((a) => !a.notTried && a.response.status === 401)) {
740
802
  out.attempts = out.attempts.filter((a) => !list.includes(a));
741
803
  skipped.push({ what: k, why: 'every account was answered 401 (not signed in): it does not take the session, probably its own key, so it was not judged' });
742
804
  }
@@ -832,7 +894,14 @@ async function tryOnce(x) {
832
894
  }
833
895
  if (/^(PATCH|PUT)$/.test(a.method) && !Object.keys(body).some((k) => nameOf(body[k]))) {
834
896
  const field = Object.keys(body).find((k) => typeof body[k] === 'string' && body[k].length > 2 && !/status|state|type|role|kind|currency|country|id$/i.test(k));
835
- if (field) body[field] = body[field] + ' kx-roles';
897
+ if (field) {
898
+ // the same value as the record already holds (a try of an earlier run, kept) would change nothing and look like a refusal
899
+ let v = body[field] + ' kx-roles';
900
+ const flat = (k) => String(k).split('_').join('').toLowerCase();
901
+ const held = target.item && typeof target.item === 'object' ? Object.keys(target.item).find((k) => flat(k) === flat(field)) : undefined;
902
+ if (held !== undefined && String(target.item[held]) === v) v = v + ' ' + Math.random().toString(36).slice(2, 5);
903
+ body[field] = v;
904
+ }
836
905
  }
837
906
  }
838
907
  const request = { method: a.method, path: pathNow };
@@ -840,8 +909,16 @@ async function tryOnce(x) {
840
909
  const requestText = pathNow + ' ' + JSON.stringify(body || {});
841
910
 
842
911
  // what the app holds now
843
- const reader = targetOrg !== null;
912
+ const reader = targetOrg !== null || p.kind === 'signin' || x.orgs.size === 0;
844
913
  const before = reader ? await x.snapshot(targetOrg) : {};
914
+ // a write to an address that is also read (POST /returns/5/notes, GET /returns/5/notes) shows there
915
+ const sameGet = reader && !isGet && a.params.length && x.getTemplates.has(a.template) ? pathNow : null;
916
+ const readSame = async () => {
917
+ const f = sameGet ? await x.readerFor(targetOrg, sameGet, null, false) : null;
918
+ return f ? stable(f.res.json) : undefined;
919
+ };
920
+ const sameBefore = await readSame();
921
+ if (sameBefore !== undefined) before[sameGet] = sameBefore;
845
922
  const known = await x.knownTo(actor);
846
923
 
847
924
  // truth: the records a read would disclose
@@ -866,6 +943,10 @@ async function tryOnce(x) {
866
943
  const ownMarked = actor.org && isGet ? ownRecords(res.json, actor.org.key) : 0;
867
944
  const found = markers.length ? authz.foundIn(res, markers).length : 0;
868
945
  const after = reader ? await x.snapshot(targetOrg) : {};
946
+ if (sameBefore !== undefined) {
947
+ const sameAfter = await readSame();
948
+ if (sameAfter !== undefined) after[sameGet] = sameAfter;
949
+ }
869
950
  const changes = x.compare(before, after);
870
951
  const changed = Object.keys(before).length ? changes.length > 0 : null;
871
952
 
@@ -893,9 +974,15 @@ async function tryOnce(x) {
893
974
  const original = target.item && /^(PATCH|PUT)$/.test(a.method) ? target.item : null;
894
975
  if (original) {
895
976
  const back = {};
896
- for (const k of Object.keys(body || {})) if (original[k] !== undefined) back[k] = original[k];
977
+ // The body says recipientName where the record says recipient_name: the same field.
978
+ const plain = (k) => String(k).replace(/[^A-Za-z0-9]/g, '').toLowerCase();
979
+ const held = new Map(Object.keys(original).map((k) => [plain(k), k]));
980
+ for (const k of Object.keys(body || {})) {
981
+ const at = original[k] !== undefined ? k : held.get(plain(k));
982
+ if (at !== undefined && original[at] !== undefined) back[k] = original[at];
983
+ }
897
984
  if (Object.keys(back).length) {
898
- const writers = x.orgs.get(targetOrg).sessions.filter((s) => holds(policy, s.role, a.permission)).concat([actor]);
985
+ const writers = (x.orgs.get(targetOrg) ? x.orgs.get(targetOrg).sessions : x.sessions).filter((s) => holds(policy, s.role, a.permission)).concat([actor]);
899
986
  for (const who of writers) {
900
987
  await who.send(a.method, pathNow, a.encoding === 'form' ? { form: back } : { json: back });
901
988
  const again = await x.snapshot(targetOrg);
@@ -0,0 +1,390 @@
1
+ // The webhook check for an app that signs its own events: no real payment needed.
2
+ //
3
+ // kryptheon-payments.js needs one real test-mode payment so a provider's own
4
+ // signed webhook can be sent again. Many apps - and every app a person builds
5
+ // to try a provider - also take events they sign themselves, with a secret in
6
+ // their .env. For those the event can be made here:
7
+ //
8
+ // 1. the app's webhook handler is read: which header holds the signature,
9
+ // how it is computed (createHmac, the algorithm, hex or base64, over the
10
+ // body), where the secret comes from (process.env.NAME) and which fields
11
+ // and event types the handler looks at. Anything it signs in a way this
12
+ // file does not know (a timestamp in front, a prefix) is said as not
13
+ // tried, never guessed;
14
+ // 2. a correctly signed event is sent first. If the app refuses even that,
15
+ // nothing else means anything and the check stops, saying so;
16
+ // 3. then, each on a record of its own, and judged from the app's own list
17
+ // of those records before and after (never from a status code alone):
18
+ // - the same event with no signature at all,
19
+ // - with a wrong signature,
20
+ // - correctly signed but for an amount that is not the record's,
21
+ // - a refund event for a record nobody had paid or approved.
22
+ //
23
+ // Promises: only an app on this computer; the secret is read from the app's
24
+ // .env, used to sign, and never printed or saved; nothing is ever deleted;
25
+ // every record an event changed is listed, since a webhook cannot be undone.
26
+
27
+ const fs = require('fs');
28
+ const path = require('path');
29
+ const crypto = require('crypto');
30
+ const secrets = require('./kryptheon-secrets.js');
31
+
32
+ const VOLATILE_KEY = /^(updated_?at|modified_?at|last_?seen|now|server_?time|timestamp|request_?id|etag|generated_?at|processed_?at)$/i;
33
+ const ALGORITHMS = /^(sha1|sha224|sha256|sha384|sha512)$/i;
34
+ const SIG_HEADER = /sig|hmac|token|secret|signature/i;
35
+ const TYPE_NAME = /^(event_?type|type|event|kind|action|topic|eventType)$/i;
36
+ const ID_NAME = /^(event_?id|eventId|id|uuid)$/i;
37
+ const AMOUNT_NAME = /amount|cents|paise|total|price/i;
38
+ const CURRENCY_NAME = /^currency$/i;
39
+ const MAX_TYPES = 3;
40
+ const MAX_TRIES = 12;
41
+
42
+ const wordsOf = (name) => String(name).replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
43
+
44
+ /** a.b.c / a['b'].c as ['a','b','c'], or null */
45
+ function chainOf(n) {
46
+ const out = [];
47
+ let c = n;
48
+ while (c && (c.type === 'MemberExpression' || c.type === 'OptionalMemberExpression')) {
49
+ if (!c.computed && c.property.type === 'Identifier') out.unshift(c.property.name);
50
+ else if (c.computed && c.property.type === 'StringLiteral') out.unshift(c.property.value);
51
+ else return null;
52
+ c = c.object;
53
+ }
54
+ if (c && c.type === 'Identifier') {
55
+ out.unshift(c.name);
56
+ return out;
57
+ }
58
+ return null;
59
+ }
60
+
61
+ /** The handler function of the route written at file:line, as { path, reqName } or null. */
62
+ function handlerAt(parser, ast, line) {
63
+ let found = null;
64
+ parser.traverse(ast, {
65
+ CallExpression(p) {
66
+ if (found) return;
67
+ const n = p.node;
68
+ if (!n.loc || n.loc.start.line !== line) return;
69
+ if (!n.callee || n.callee.type !== 'MemberExpression') return;
70
+ const verb = n.callee.property && n.callee.property.name;
71
+ if (!/^(post|put|patch|all)$/.test(verb || '')) return;
72
+ const argIndex = n.arguments.map((a) => a.type).lastIndexOf('ArrowFunctionExpression');
73
+ const fnIndex = argIndex >= 0 ? argIndex : n.arguments.map((a) => a.type).lastIndexOf('FunctionExpression');
74
+ if (fnIndex < 0) return;
75
+ found = { path: p.get('arguments.' + fnIndex), node: n.arguments[fnIndex] };
76
+ },
77
+ });
78
+ if (!found) return null;
79
+ const first = found.node.params[0];
80
+ return { path: found.path, reqName: first && first.type === 'Identifier' ? first.name : null };
81
+ }
82
+
83
+ /**
84
+ * How the handler signs: { ok, header, algorithm, encoding, secret: { env, fallback }, fields, types, why }.
85
+ * Reading code only. `fields` are the body fields the map saw the route read.
86
+ */
87
+ function readSigning(parser, root, route, fields) {
88
+ let source;
89
+ const abs = path.join(root, route.file);
90
+ try {
91
+ source = fs.readFileSync(abs, 'utf8');
92
+ } catch (err) {
93
+ return { ok: false, why: 'the file ' + route.file + ' could not be read' };
94
+ }
95
+ let ast;
96
+ try {
97
+ ast = parser.babelParse(source, abs, true);
98
+ } catch (err) {
99
+ try {
100
+ ast = parser.babelParse(source, abs, false);
101
+ } catch (err2) {
102
+ return { ok: false, why: route.file + ' could not be parsed' };
103
+ }
104
+ }
105
+ const h = handlerAt(parser, ast, route.line);
106
+ if (!h || !h.reqName) return { ok: false, why: 'the handler at ' + route.file + ':' + route.line + ' is not a function written in the route itself' };
107
+ const req = h.reqName;
108
+ const resolve = (node, depth) => {
109
+ let n = node;
110
+ for (let i = 0; i < (depth || 3); i++) {
111
+ if (n && n.type === 'Identifier') {
112
+ const b = h.path.scope.getBinding(n.name);
113
+ const init = b && b.path && b.path.node && b.path.node.type === 'VariableDeclarator' ? b.path.node.init : null;
114
+ if (!init) return n;
115
+ n = init;
116
+ } else if (n && (n.type === 'AwaitExpression' || n.type === 'TSAsExpression' || n.type === 'ParenthesizedExpression')) n = n.argument || n.expression;
117
+ else break;
118
+ }
119
+ return n;
120
+ };
121
+ let header = null;
122
+ let hmac = null;
123
+ const literals = new Set();
124
+ h.path.traverse({
125
+ CallExpression(p) {
126
+ const n = p.node;
127
+ const chain = chainOf(n.callee);
128
+ // req.get('x-sig') / req.header('x-sig')
129
+ if (chain && chain[0] === req && /^(get|header)$/.test(chain[chain.length - 1]) && n.arguments[0] && n.arguments[0].type === 'StringLiteral' && SIG_HEADER.test(n.arguments[0].value) && !header) header = n.arguments[0].value.toLowerCase();
130
+ // .digest('hex') of .update(x) of createHmac(alg, secret)
131
+ if (n.callee && n.callee.type === 'MemberExpression' && n.callee.property.name === 'digest' && n.callee.object && n.callee.object.type === 'CallExpression') {
132
+ const upd = n.callee.object;
133
+ const mk = upd.callee && upd.callee.type === 'MemberExpression' && upd.callee.property.name === 'update' ? upd.callee.object : null;
134
+ const mkName = mk && mk.type === 'CallExpression' ? (mk.callee.type === 'MemberExpression' ? mk.callee.property.name : mk.callee.name) : null;
135
+ if (mkName === 'createHmac' && !hmac) hmac = { alg: mk.arguments[0], key: mk.arguments[1], payload: upd.arguments[0], enc: n.arguments[0] };
136
+ }
137
+ },
138
+ MemberExpression(p) {
139
+ const chain = chainOf(p.node);
140
+ if (chain && chain[0] === req && chain[1] === 'headers' && chain[2] && SIG_HEADER.test(chain[2]) && !header) header = chain[2].toLowerCase();
141
+ },
142
+ BinaryExpression(p) {
143
+ const n = p.node;
144
+ if (!/^[!=]==?$/.test(n.operator)) return;
145
+ const [a, b] = [n.left, n.right];
146
+ const name = (x) => (x.type === 'Identifier' ? x.name : (chainOf(x) || []).slice(-1)[0] || '');
147
+ if (b.type === 'StringLiteral' && TYPE_NAME.test(name(a))) literals.add(b.value);
148
+ if (a.type === 'StringLiteral' && TYPE_NAME.test(name(b))) literals.add(a.value);
149
+ },
150
+ SwitchStatement(p) {
151
+ const d = p.node.discriminant;
152
+ const nm = d.type === 'Identifier' ? d.name : (chainOf(d) || []).slice(-1)[0] || '';
153
+ if (!TYPE_NAME.test(nm)) return;
154
+ for (const c of p.node.cases) if (c.test && c.test.type === 'StringLiteral') literals.add(c.test.value);
155
+ },
156
+ });
157
+ if (!header) return { ok: false, why: 'no signature header is read in the handler (looked for a header with sig, hmac or token in its name)' };
158
+ if (!hmac) return { ok: false, why: 'the handler reads ' + header + ' but does not compute an HMAC the way this check knows (createHmac(alg, secret).update(body).digest(encoding))' };
159
+ const alg = hmac.alg && hmac.alg.type === 'StringLiteral' ? hmac.alg.value.toLowerCase() : null;
160
+ const enc = hmac.enc && hmac.enc.type === 'StringLiteral' ? hmac.enc.value.toLowerCase() : null;
161
+ if (!alg || !ALGORITHMS.test(alg)) return { ok: false, why: 'the HMAC algorithm is not a plain name written in the code' };
162
+ if (enc !== 'hex' && enc !== 'base64') return { ok: false, why: 'the signature is not read out as hex or base64' };
163
+ // what is signed: JSON.stringify(req.body), or the raw body
164
+ const pay = resolve(hmac.payload);
165
+ const payChain = pay && chainOf(pay);
166
+ const stringifies = pay && pay.type === 'CallExpression' && (chainOf(pay.callee) || []).join('.') === 'JSON.stringify' && (chainOf(pay.arguments[0]) || []).join('.') === req + '.body';
167
+ const rawBody = payChain && payChain[0] === req && /^(rawBody|body)$/.test(payChain[1] || '') && payChain.length === 2;
168
+ if (!stringifies && !rawBody) return { ok: false, why: 'what is signed is more than the body (a timestamp or a prefix in front, say), which this check does not make' };
169
+ // the secret
170
+ const key = resolve(hmac.key);
171
+ let secret = null;
172
+ const envName = (n) => { const c = n && chainOf(n); return c && c[0] === 'process' && c[1] === 'env' && c[2] ? c[2] : null; };
173
+ if (key && key.type === 'LogicalExpression' && /^(\|\||\?\?)$/.test(key.operator)) {
174
+ const e = envName(key.left);
175
+ if (e) secret = { env: e, fallback: key.right.type === 'StringLiteral' ? key.right.value : null };
176
+ } else if (envName(key)) secret = { env: envName(key), fallback: null };
177
+ else if (key && key.type === 'StringLiteral') secret = { env: null, fallback: key.value };
178
+ if (!secret) return { ok: false, why: 'the secret is not process.env.NAME or a plain string in the code' };
179
+ return { ok: true, header, algorithm: alg, encoding: enc, secret, fields: (fields || []).slice(), types: Array.from(literals), signs: stringifies ? 'JSON.stringify(req.body)' : 'the raw body' };
180
+ }
181
+
182
+ /** Which body field is which, from names. { id, type, record, amount, currency, others } or why not. */
183
+ function shapeOf(fields) {
184
+ const names = fields.map((f) => f.name);
185
+ const type = names.find((n) => TYPE_NAME.test(n));
186
+ const id = names.find((n) => ID_NAME.test(n) && n !== type);
187
+ const amount = names.find((n) => AMOUNT_NAME.test(n));
188
+ const currency = names.find((n) => CURRENCY_NAME.test(n));
189
+ const record = names.find((n) => n !== id && n !== type && n !== amount && (/_?id$/i.test(n) || /ref$/i.test(n) || /Id$/.test(n)));
190
+ if (!type) return { ok: false, why: 'no field of the body names the kind of event (event_type, type, event ...)' };
191
+ if (!record) return { ok: false, why: 'no field of the body names the record the event is about (return_id, order_id ...)' };
192
+ return { ok: true, id, type, record, amount, currency };
193
+ }
194
+
195
+ /** The signature the app would accept for these exact bytes. Never printed. */
196
+ function sign(signing, secret, body) {
197
+ const mac = crypto.createHmac(signing.algorithm, secret).update(body).digest(signing.encoding);
198
+ return mac;
199
+ }
200
+
201
+ /** A signature of the right shape that is not right. */
202
+ function wrongSignature(signing, secret, body) {
203
+ const good = sign(signing, secret, body);
204
+ // flip the first character, staying inside the alphabet it is written in
205
+ const first = good[0];
206
+ const swap = signing.encoding === 'hex' ? (first === '0' ? '1' : '0') : (first === 'A' ? 'B' : 'A');
207
+ return swap + good.slice(1);
208
+ }
209
+
210
+ const stableItem = (item) => {
211
+ if (!item || typeof item !== 'object') return item;
212
+ const out = {};
213
+ for (const k of Object.keys(item).sort()) if (!VOLATILE_KEY.test(k)) out[k] = item[k];
214
+ return out;
215
+ };
216
+
217
+ const listOf = (json) => {
218
+ if (Array.isArray(json)) return json;
219
+ if (json && typeof json === 'object') for (const k of Object.keys(json)) if (Array.isArray(json[k])) return json[k];
220
+ return null;
221
+ };
222
+
223
+ /** The words of the order a status runs in: what has been paid or approved before a refund. */
224
+ const PAID = /approv|paid|captur|complet|process|settl|success|confirm/i;
225
+ const REFUNDED = /refund/i;
226
+
227
+ /**
228
+ * Tries each signed-event case on the running app. { ran, why, hooks: [...], findings, left }.
229
+ * `options`: origin, env, say, stopped, fetch, map (a map already read), packageDir.
230
+ */
231
+ async function run(root, options) {
232
+ const api = require('./kryptheon-api.js');
233
+ const authz = require('./kryptheon-authz.js');
234
+ const code = require('./kryptheon-code.js');
235
+ const mapper = require('./kryptheon-map.js');
236
+ const opts = options || {};
237
+ const say = typeof opts.say === 'function' ? opts.say : () => {};
238
+ const plan = api.planOf(root, opts);
239
+ if (!plan.ran) return { ran: false, why: plan.why };
240
+ const hooks = (plan.map.routes || []).filter((r) => r.kind === 'webhook' && !r.unmounted && r.method === 'POST' && r.path);
241
+ if (!hooks.length) return { ran: false, why: 'the map found no webhook route' };
242
+ let origin;
243
+ try {
244
+ origin = authz.assertLocalTarget(opts.origin);
245
+ } catch (err) {
246
+ return { ran: false, why: 'the app must be on this computer (localhost or 127.0.0.1): ' + (opts.origin || 'no address was given') };
247
+ }
248
+ const j = plan.journey;
249
+ if (!j.signIn) return { ran: false, why: j.signInWhy };
250
+ if (!j.accounts.usable.length) return { ran: false, why: 'no account has a password in .env, so the records an event is about cannot be read' };
251
+ const parser = code.loadParser(opts.packageDir || __dirname);
252
+ if (!parser) return { ran: false, why: 'the JavaScript parser this check uses was not found' };
253
+ const who = j.accounts.usable[0];
254
+ const appEnv = Object.assign({}, secrets.readEnvFile(secrets.envFileFor(root)), opts.env || {});
255
+ const ctx = authz.makeContext({ baseUrl: origin, allowOrigins: [origin], fetch: opts.fetch, passwords: { [who.email]: who.password }, maxRequests: 200 });
256
+ const reader = authz.makeSession(ctx, 'account', who.email, who.password);
257
+ const fields = { [j.signIn.emailField]: who.email, [j.signIn.passwordField]: who.password };
258
+ const signed = authz.replyOf(await reader.send(j.signIn.method, j.signIn.path, j.signIn.encoding === 'form' ? { form: fields } : { json: fields }));
259
+ if (signed.kind === 'refused' || signed.kind === 'server-error' || signed.kind === 'no-answer') return { ran: false, why: 'could not sign in as ' + who.email + ' (' + signed.note + ')' };
260
+ const out = { ran: true, hooks: [], findings: [], left: [] };
261
+
262
+ for (const route of hooks) {
263
+ const name = route.method + ' ' + route.path;
264
+ const hook = { route: name, from: route.file + ':' + route.line, tried: [], findings: [], notTried: null, control: null };
265
+ out.hooks.push(hook);
266
+ const bodyFields = ((route.validation && route.validation.fields) || []).filter((f) => f.from === 'body');
267
+ const signing = readSigning(parser, root, route, bodyFields);
268
+ if (!signing.ok) { hook.notTried = signing.why; continue; }
269
+ hook.signing = { header: signing.header, algorithm: signing.algorithm, encoding: signing.encoding, secretFrom: signing.secret.env ? signing.secret.env + ' in .env' : 'a string in the code', signs: signing.signs };
270
+ const secret = (signing.secret.env && appEnv[signing.secret.env]) || signing.secret.fallback;
271
+ if (!secret) { hook.notTried = 'the secret ' + signing.secret.env + ' is not in the app\'s .env, and the code has no fallback'; continue; }
272
+ // whatever the app answers is cleaned of it before anything is said
273
+ if (!ctx.secrets.includes(secret)) ctx.secrets.push(secret);
274
+ const shape = shapeOf(bodyFields);
275
+ if (!shape.ok) { hook.notTried = shape.why; continue; }
276
+ const types = signing.types.slice(0, MAX_TYPES);
277
+ if (!types.length) { hook.notTried = 'no event type is written in the handler (an if on ' + shape.type + ' or a switch), so there is nothing to send'; continue; }
278
+ // the records an event is about: the app's own list of them, as the signed-in account sees it
279
+ const resource = wordsOf(shape.record)[0];
280
+ const listRoute = (plan.map.routes || []).find((r) => r.method === 'GET' && !r.unmounted && r.path && !/[:{]/.test(r.path) && new RegExp('(^|/)' + resource + '(s|es)?$', 'i').test(r.path));
281
+ if (!listRoute) { hook.notTried = 'the app has no list of ' + resource + 's (GET /...' + resource + 's) to read the effect of an event from'; continue; }
282
+ const readList = async () => {
283
+ const res = await reader.send('GET', listRoute.path, {});
284
+ return res.status === 200 ? listOf(res.json) : null;
285
+ };
286
+ const items0 = await readList();
287
+ if (!items0 || !items0.length) { hook.notTried = 'GET ' + listRoute.path + ' answered no records to aim an event at'; continue; }
288
+ const records = items0.filter((it) => it && it.id !== undefined);
289
+ const amountKey = records[0] && Object.keys(records[0]).find((k) => AMOUNT_NAME.test(k));
290
+ const statusKey = records[0] && Object.keys(records[0]).find((k) => /^status$|^state$/i.test(k));
291
+ hook.list = listRoute.path;
292
+
293
+ const used = new Set();
294
+ const nextRecord = (want) => records.find((r) => !used.has(r.id) && (!statusKey || !REFUNDED.test(String(r[statusKey]))) && (!want || want(r)));
295
+ // a refund event is tried first on a record nobody has paid or approved: the case it should refuse
296
+ const unpaidFor = (type) => (REFUNDED.test(type) && statusKey ? (r) => !PAID.test(String(r[statusKey])) : null);
297
+ const bodyFor = (type, rec, amount) => {
298
+ const b = {};
299
+ if (shape.id) b[shape.id] = 'kx-evt-' + crypto.randomBytes(5).toString('hex');
300
+ b[shape.type] = type;
301
+ b[shape.record] = rec.id;
302
+ if (shape.amount) b[shape.amount] = amount !== undefined ? amount : amountKey ? rec[amountKey] : 1;
303
+ return b;
304
+ };
305
+ const post = async (mode, body) => {
306
+ const text = JSON.stringify(body);
307
+ const session = authz.makeSession(ctx, null, '(nobody signed in)', null);
308
+ const headers = {};
309
+ if (mode === 'signed') headers[signing.header] = sign(signing, secret, text);
310
+ if (mode === 'wrong') headers[signing.header] = wrongSignature(signing, secret, text);
311
+ return session.send('POST', route.path, { json: body, headers });
312
+ };
313
+ const attempt = async (mode, type, rec, amount, label) => {
314
+ const before = await readList();
315
+ const body = bodyFor(type, rec, amount);
316
+ used.add(rec.id);
317
+ const res = await post(mode, body);
318
+ const reply = authz.replyOf(res);
319
+ const after = await readList();
320
+ const was = before && before.find((x) => x.id === rec.id);
321
+ const now = after && after.find((x) => x.id === rec.id);
322
+ const changed = !!(was && now && JSON.stringify(stableItem(was)) !== JSON.stringify(stableItem(now)));
323
+ const took = reply.kind === 'accepted' || reply.kind === 'redirect';
324
+ const t = { mode, label: label || mode, type, record: rec.id, status: res.status, took, changed, from: was && statusKey ? was[statusKey] : null, to: now && statusKey ? now[statusKey] : null };
325
+ hook.tried.push(t);
326
+ if (changed) out.left.push(name + ' ' + (label || mode) + ' ' + type + ' for ' + resource + ' ' + rec.id + (t.from !== null ? ': ' + statusKey + ' ' + t.from + ' -> ' + t.to : ' changed it'));
327
+ else if (took) out.left.push(name + ' ' + (label || mode) + ' ' + type + ' for ' + resource + ' ' + rec.id + ' answered ' + res.status + ' (no change seen in ' + listRoute.path + '); the event id is in the app\'s webhook table');
328
+ return t;
329
+ };
330
+
331
+ // 1. a correctly signed event first: if the app refuses its own, nothing after it means anything
332
+ say('Sending a correctly signed ' + types[0] + ' to ' + name + ' first...');
333
+ const first = nextRecord(unpaidFor(types[0])) || nextRecord();
334
+ if (!first) { hook.notTried = 'no record left to aim an event at'; continue; }
335
+ const control = await attempt('signed', types[0], first, undefined, 'signed');
336
+ hook.control = control;
337
+ if (!control.took) {
338
+ hook.notTried = 'the app refused even a correctly signed event (' + control.status + '), so either the signature is made differently from how the code reads, or the event needs more than ' + Object.keys(bodyFor(types[0], first)).join(', ') + ': nothing after it would mean anything';
339
+ continue;
340
+ }
341
+ // the tries, in the order that tells the most when records run out
342
+ const cases = [];
343
+ for (const type of types) cases.push({ mode: 'none', type, label: 'unsigned' });
344
+ cases.push({ mode: 'wrong', type: types[0], label: 'wrong signature' });
345
+ for (const type of types.slice(1)) cases.push({ mode: 'signed', type, label: 'signed' });
346
+ if (shape.amount && amountKey) for (const type of types) if (!REFUNDED.test(type) && /pay|captur|charge|paid|success/i.test(type)) { cases.push({ mode: 'signed', type, label: 'signed, wrong amount', wrongAmount: true }); break; }
347
+ for (const c of cases) {
348
+ if (opts.stopped && opts.stopped()) break;
349
+ if (hook.tried.length >= MAX_TRIES) break;
350
+ const rec = (c.mode === 'signed' && nextRecord(unpaidFor(c.type))) || nextRecord();
351
+ if (!rec) break;
352
+ let amount;
353
+ if (c.wrongAmount) amount = (Number(rec[amountKey]) || 0) + 100;
354
+ await attempt(c.mode, c.type, rec, amount, c.label);
355
+ }
356
+
357
+ // judged
358
+ const at = hook.from;
359
+ const finding = (kind, severity, status, headline, proof, fix) => {
360
+ const f = { kind, where: name, from: at, status, severity, headline, proof, fixPrompt: ['Kryptheon sent my running app an event it signs itself, and it was taken when it should not have been:', '', headline, '', 'Where: ' + at, '', fix, '', 'Afterwards I will run: npx kryptheon api'].join(String.fromCharCode(10)) };
361
+ hook.findings.push(f);
362
+ out.findings.push(f);
363
+ };
364
+ const lineOf = (t) => t.label + ' ' + t.type + ' for ' + resource + ' ' + t.record + ': answered ' + t.status + (t.changed ? ', and ' + (t.from !== null ? statusKey + ' went ' + t.from + ' -> ' + t.to : 'the record changed') + ' in GET ' + listRoute.path : t.took ? ', nothing changed in GET ' + listRoute.path : ', refused');
365
+ for (const t of hook.tried) {
366
+ // the first signed event is a control for the signature, but what it did is judged like any other signed event
367
+ if (t === control && !(t.changed && REFUNDED.test(String(t.to)) && t.from !== null && !PAID.test(String(t.from)))) continue;
368
+ if (t.mode === 'none' && t.took) {
369
+ finding('webhook-unsigned', t.changed ? 'CRITICAL' : 'HIGH', t.changed ? 'confirmed' : 'verification required',
370
+ t.changed ? name + ' took ' + t.type + ' with no signature at all and changed ' + resource + ' ' + t.record + (t.from !== null ? ' (' + statusKey + ' ' + t.from + ' -> ' + t.to + ')' : '') + ': anyone who can reach it can send one.' : name + ' answered ' + t.status + ' to ' + t.type + ' with no signature, though no change was seen in ' + listRoute.path + '.',
371
+ ['With nobody signed in and no ' + signing.header + ' header: ' + lineOf(t)], 'Treat a request with no signature as invalid: answer 401 before anything is saved, the same as a wrong signature. The check that reads "if the header is there and it is wrong" lets every request without the header through.');
372
+ } else if (t.mode === 'wrong' && t.took) {
373
+ finding('webhook-forged', t.changed ? 'CRITICAL' : 'HIGH', t.changed ? 'confirmed' : 'verification required',
374
+ name + ' took ' + t.type + ' with a wrong signature' + (t.changed ? ' and changed ' + resource + ' ' + t.record : '') + '.',
375
+ ['A signature of the right length, one character wrong: ' + lineOf(t)], 'Compare the signature with a timing-safe compare (crypto.timingSafeEqual) over the exact raw body, and answer 401 when it does not match, before anything is saved.');
376
+ } else if (t.label === 'signed, wrong amount' && t.took && t.changed) {
377
+ finding('webhook-amount', 'HIGH', 'confirmed',
378
+ name + ' applied ' + t.type + ' for an amount that is not ' + resource + ' ' + t.record + '\'s: the status changed all the same.',
379
+ ['Correctly signed, with the amount 100 higher than the record\'s: ' + lineOf(t)], 'Compare the amount (and currency) in the event with the amount the ' + resource + ' was created for, and ignore or flag the event when they differ.');
380
+ } else if (t.mode === 'signed' && t.changed && REFUNDED.test(String(t.to)) && t.from !== null && !PAID.test(String(t.from))) {
381
+ finding('webhook-lifecycle', 'MEDIUM', 'verification required',
382
+ name + ' marked ' + resource + ' ' + t.record + ' as ' + t.to + ' from ' + t.from + ': a refund event for something nobody had paid or approved.',
383
+ ['Correctly signed: ' + lineOf(t)], 'Apply a refund event only to a record that was paid or approved first, in the same tenant, for no more than was paid; answer and log anything else without changing it.');
384
+ }
385
+ }
386
+ }
387
+ return out;
388
+ }
389
+
390
+ module.exports = { readSigning, shapeOf, sign, wrongSignature, run, MAX_TRIES };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kryptheon",
3
- "version": "0.1.55",
3
+ "version": "0.1.57",
4
4
  "description": "Record what you do in your app and get plain-language reports when it breaks.",
5
5
  "license": "SEE LICENSE IN LICENSE",
6
6
  "type": "commonjs",
@@ -54,7 +54,11 @@
54
54
  "kryptheon-payments.js",
55
55
  "kryptheon-payments-run.js",
56
56
  "kryptheon-authz.js",
57
- "kryptheon-roles.js"
57
+ "kryptheon-roles.js",
58
+ "kryptheon-map.js",
59
+ "kryptheon-api.js",
60
+ "kryptheon-webhook.js",
61
+ "kryptheon-csv.js"
58
62
  ],
59
63
  "engines": {
60
64
  "node": ">=20.6.0"
@@ -64,7 +68,7 @@
64
68
  "pg": "^8.23.0"
65
69
  },
66
70
  "scripts": {
67
- "check": "node kryptheon-store.check.js && node kryptheon-code.check.js && node kryptheon-constdata.check.js && node kryptheon-listitems.check.js && node kryptheon-accept.check.js && node kryptheon-keys.check.js && node kryptheon-dashboard.check.js && node kryptheon-edge.check.js && node kryptheon-reliability.check.js && node kryptheon-fresh.check.js && node kryptheon-payments-dash.check.js && node kryptheon-embedded.check.js && node kryptheon-autostart.check.js && node kryptheon-changes.check.js && node kryptheon-look.check.js && node kryptheon-verify.check.js && node kryptheon-recheck.check.js && node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-signature.number.check.js && node kryptheon-signature.rows.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-phone.check.js && node kryptheon-homedash.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-testfiles.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-browser.check.js && node kryptheon-heal.check.js && node kryptheon-load.check.js && node kryptheon-authz.check.js && node kryptheon-roles.check.js && node kryptheon-package.check.js",
71
+ "check": "node kryptheon-store.check.js && node kryptheon-code.check.js && node kryptheon-constdata.check.js && node kryptheon-listitems.check.js && node kryptheon-accept.check.js && node kryptheon-keys.check.js && node kryptheon-dashboard.check.js && node kryptheon-edge.check.js && node kryptheon-reliability.check.js && node kryptheon-fresh.check.js && node kryptheon-payments-dash.check.js && node kryptheon-embedded.check.js && node kryptheon-autostart.check.js && node kryptheon-changes.check.js && node kryptheon-look.check.js && node kryptheon-verify.check.js && node kryptheon-recheck.check.js && node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-signature.number.check.js && node kryptheon-signature.rows.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-phone.check.js && node kryptheon-homedash.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-testfiles.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-browser.check.js && node kryptheon-heal.check.js && node kryptheon-load.check.js && node kryptheon-authz.check.js && node kryptheon-roles.check.js && node kryptheon-map.check.js && node kryptheon-api.check.js && node kryptheon-webhook.check.js && node kryptheon-csv.check.js && node kryptheon-package.check.js",
68
72
  "check:store": "node kryptheon-store.check.js",
69
73
  "check:code": "node kryptheon-code.check.js",
70
74
  "check:constdata": "node kryptheon-constdata.check.js",
@@ -105,7 +109,11 @@
105
109
  "check:fresh": "node kryptheon-fresh.check.js",
106
110
  "check:authz": "node kryptheon-authz.check.js",
107
111
  "check:roles": "node kryptheon-roles.check.js",
108
- "check:roles-mutants": "node kryptheon-roles.mutants.js"
112
+ "check:roles-mutants": "node kryptheon-roles.mutants.js",
113
+ "check:map": "node kryptheon-map.check.js",
114
+ "check:api": "node kryptheon-api.check.js",
115
+ "check:webhook": "node kryptheon-webhook.check.js",
116
+ "check:csv": "node kryptheon-csv.check.js"
109
117
  },
110
118
  "keywords": [
111
119
  "playwright",