kryptheon 0.1.58 → 0.1.61

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.
@@ -29,15 +29,18 @@ const path = require('path');
29
29
  const crypto = require('crypto');
30
30
  const secrets = require('./kryptheon-secrets.js');
31
31
 
32
- const VOLATILE_KEY = /^(updated_?at|modified_?at|last_?seen|now|server_?time|timestamp|request_?id|etag|generated_?at|processed_?at)$/i;
32
+ // a time the app stamps by itself (captured_at = NOW() each time, round 26) is not the event changing the record
33
+ const VOLATILE_NAME = /^(updated_?at|modified_?at|last_?seen|now|server_?time|timestamp|request_?id|etag|generated_?at|processed_?at)$|_at$/i;
34
+ const VOLATILE_KEY = { test: (k) => VOLATILE_NAME.test(k) || /[a-z]At$/.test(k) };
33
35
  const ALGORITHMS = /^(sha1|sha224|sha256|sha384|sha512)$/i;
34
36
  const SIG_HEADER = /sig|hmac|token|secret|signature/i;
35
37
  const TYPE_NAME = /^(event_?type|type|event|kind|action|topic|eventType)$/i;
36
38
  const ID_NAME = /^(event_?id|eventId|id|uuid)$/i;
37
39
  const AMOUNT_NAME = /amount|cents|paise|total|price/i;
38
40
  const CURRENCY_NAME = /^currency$/i;
41
+ const OWNER_ID = /^(org|organi[sz]ation|tenant|workspace|team|account|company|user|owner)_?id$/i;
39
42
  const MAX_TYPES = 3;
40
- const MAX_TRIES = 12;
43
+ const MAX_TRIES = 20;
41
44
 
42
45
  const wordsOf = (name) => String(name).replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
43
46
 
@@ -114,11 +117,34 @@ function readSigning(parser, root, route, fields) {
114
117
  const h = handlerAt(parser, ast, route.line);
115
118
  if (!h || !h.reqName) return { ok: false, why: 'the handler at ' + route.file + ':' + route.line + ' is not a function written in the route itself' };
116
119
  const req = h.reqName;
117
- const resolve = (node, depth) => {
120
+ // the names that stand for the body: req.body, and a helper's parameter it is passed in as (round 26)
121
+ const bodyNames = new Set();
122
+ const isBody = (node) => {
123
+ if (!node) return false;
124
+ if (node.type === 'LogicalExpression' && /^(\|\||\?\?)$/.test(node.operator)) return isBody(node.left) && node.right.type === 'ObjectExpression' && !node.right.properties.length;
125
+ if (node.type === 'Identifier') return bodyNames.has(node.name);
126
+ const c = chainOf(node);
127
+ return !!(c && c[0] === req && c.length === 2 && /^(rawBody|body)$/.test(c[1]));
128
+ };
129
+ // the bytes of the body, however they are spelled: JSON.stringify(body), Buffer.from(JSON.stringify(body)),
130
+ // req.rawBody || JSON.stringify(req.body || {}) (round 22, 23) - all the very text this check sends
131
+ const isPayload = (node) => {
132
+ if (!node) return false;
133
+ if (node.type === 'CallExpression') {
134
+ const callee = (chainOf(node.callee) || []).join('.');
135
+ if (callee === 'JSON.stringify' && node.arguments.length === 1) return isBody(node.arguments[0]);
136
+ if (callee === 'Buffer.from' && node.arguments.length >= 1) return isPayload(node.arguments[0]);
137
+ return false;
138
+ }
139
+ if (node.type === 'LogicalExpression' && /^(\|\||\?\?)$/.test(node.operator)) return isPayload(node.left) && isPayload(node.right);
140
+ return isBody(node);
141
+ };
142
+ let scopePath = h.path;
143
+ const resolve = (node, depth, scope) => {
118
144
  let n = node;
119
145
  for (let i = 0; i < (depth || 3); i++) {
120
- if (n && n.type === 'Identifier') {
121
- const b = h.path.scope.getBinding(n.name);
146
+ if (n && n.type === 'Identifier' && !bodyNames.has(n.name)) {
147
+ const b = (scope || scopePath).scope.getBinding(n.name);
122
148
  const init = b && b.path && b.path.node && b.path.node.type === 'VariableDeclarator' ? b.path.node.init : null;
123
149
  if (!init) return n;
124
150
  n = init;
@@ -128,9 +154,17 @@ function readSigning(parser, root, route, fields) {
128
154
  return n;
129
155
  };
130
156
  let header = null;
157
+ // the field an event's kind is compared on (event.event === 'payment.captured'), even when it is read from a parsed copy
158
+ let typeField = null;
131
159
  let hmac = null;
132
160
  const literals = new Set();
133
- h.path.traverse({
161
+ // kinds only listed as allowed ([...].includes): after the kinds the code compares and acts on, which tell more -
162
+ // the first kind sent is the control (round 26's list put payment.created first, which Wayline refuses for state)
163
+ const listed = new Set();
164
+ const kindsOf = () => Array.from(literals).concat(Array.from(listed).filter((t) => !literals.has(t)));
165
+ const destructured = [];
166
+ const helpers = [];
167
+ const readFrom = (fnPath) => fnPath.traverse({
134
168
  CallExpression(p) {
135
169
  const n = p.node;
136
170
  const chain = chainOf(n.callee);
@@ -141,20 +175,45 @@ function readSigning(parser, root, route, fields) {
141
175
  const upd = n.callee.object;
142
176
  const mk = upd.callee && upd.callee.type === 'MemberExpression' && upd.callee.property.name === 'update' ? upd.callee.object : null;
143
177
  const mkName = mk && mk.type === 'CallExpression' ? (mk.callee.type === 'MemberExpression' ? mk.callee.property.name : mk.callee.name) : null;
144
- if (mkName === 'createHmac' && !hmac) hmac = { alg: mk.arguments[0], key: mk.arguments[1], payload: upd.arguments[0], enc: n.arguments[0] };
178
+ // names are resolved from where they are used: `const raw` inside a try {} is not in the function's own scope
179
+ if (mkName === 'createHmac' && !hmac) hmac = { alg: mk.arguments[0], key: mk.arguments[1], payload: upd.arguments[0], enc: n.arguments[0], keyScope: p, payloadScope: p };
180
+ }
181
+ // helper(req.body, ...): a function of this file that is handed the body (round 26: processPaymentWebhook(req.body || {}, sig);
182
+ // round 23: hmac(raw), where raw = req.rawBody || Buffer.from(JSON.stringify(req.body)) is a second name for it)
183
+ if (n.callee && n.callee.type === 'Identifier') {
184
+ // handed the body, or the body's bytes: sign(raw, key) where raw = JSON.stringify(req.body || {})
185
+ const at = n.arguments.findIndex((a) => isBody(a) || isPayload(resolve(a, 3, p)));
186
+ if (at >= 0) helpers.push({ name: n.callee.name, at, scope: p.scope, callPath: p });
187
+ }
188
+ // ['payment.captured', 'refund.processed'].includes(payload.type), or TYPES.includes(event.type): every kind in
189
+ // the list (round 27)
190
+ if (n.callee && n.callee.type === 'MemberExpression' && !n.callee.computed && n.callee.property.name === 'includes' && n.arguments.length === 1) {
191
+ const subject = n.arguments[0];
192
+ const nm = subject.type === 'Identifier' ? subject.name : (chainOf(subject) || []).slice(-1)[0] || '';
193
+ let list = n.callee.object;
194
+ if (list.type === 'Identifier') {
195
+ const b = p.scope.getBinding(list.name);
196
+ list = b && b.path && b.path.node.type === 'VariableDeclarator' && !b.constantViolations.length ? b.path.node.init : null;
197
+ }
198
+ if (TYPE_NAME.test(nm) && list && list.type === 'ArrayExpression' && list.elements.length && list.elements.every((e) => e && e.type === 'StringLiteral')) {
199
+ for (const e of list.elements) listed.add(e.value);
200
+ typeField = typeField || nm;
201
+ }
145
202
  }
146
203
  },
147
204
  MemberExpression(p) {
148
205
  const chain = chainOf(p.node);
149
206
  if (chain && chain[0] === req && chain[1] === 'headers' && chain[2] && SIG_HEADER.test(chain[2]) && !header) header = chain[2].toLowerCase();
207
+ // payload.amount, where payload is the body or a second name for it: a field the webhook reads (round 27)
208
+ if (chain && chain.length >= 2 && bodyNames.has(chain[0]) && /^[A-Za-z_]\w*$/.test(chain[1]) && !/^(length|toString|constructor)$/.test(chain[1])) destructured.push(chain[1]);
150
209
  },
151
210
  BinaryExpression(p) {
152
211
  const n = p.node;
153
212
  if (!/^[!=]==?$/.test(n.operator)) return;
154
213
  const [a, b] = [n.left, n.right];
155
214
  const name = (x) => (x.type === 'Identifier' ? x.name : (chainOf(x) || []).slice(-1)[0] || '');
156
- if (b.type === 'StringLiteral' && TYPE_NAME.test(name(a))) literals.add(b.value);
157
- if (a.type === 'StringLiteral' && TYPE_NAME.test(name(b))) literals.add(a.value);
215
+ if (b.type === 'StringLiteral' && TYPE_NAME.test(name(a))) { literals.add(b.value); typeField = typeField || name(a); }
216
+ if (a.type === 'StringLiteral' && TYPE_NAME.test(name(b))) { literals.add(a.value); typeField = typeField || name(b); }
158
217
  },
159
218
  SwitchStatement(p) {
160
219
  const d = p.node.discriminant;
@@ -162,21 +221,72 @@ function readSigning(parser, root, route, fields) {
162
221
  if (!TYPE_NAME.test(nm)) return;
163
222
  for (const c of p.node.cases) if (c.test && c.test.type === 'StringLiteral') literals.add(c.test.value);
164
223
  },
224
+ VariableDeclarator(p) {
225
+ // const event = req.body || {} - a second name for the body (round 25)
226
+ if (p.node.id.type === 'Identifier' && p.node.init && p.node.init.type !== 'Identifier' && isBody(p.node.init)) bodyNames.add(p.node.id.name);
227
+ // const { event_id, amount } = body - the fields, when the map could not see them (they are read in a helper)
228
+ if (p.node.id.type === 'ObjectPattern' && isBody(p.node.init)) for (const prop of p.node.id.properties) if (prop.key && prop.key.type === 'Identifier') destructured.push(prop.key.name);
229
+ },
165
230
  });
166
- 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)' };
167
- 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))' };
231
+ readFrom(h.path);
232
+ let via = null;
233
+ if (!hmac) {
234
+ for (const call of helpers) {
235
+ const b = call.scope.getBinding(call.name);
236
+ if (!b || !b.path) continue;
237
+ const fnPath = b.path.node.type === 'FunctionDeclaration' ? b.path : b.path.node.type === 'VariableDeclarator' && b.path.node.init && /Function/.test(b.path.node.init.type) ? b.path.get('init') : null;
238
+ const param = fnPath && fnPath.node.params[call.at];
239
+ if (!param || param.type !== 'Identifier') continue;
240
+ bodyNames.add(param.name);
241
+ scopePath = fnPath;
242
+ readFrom(fnPath);
243
+ if (hmac) {
244
+ via = call.name;
245
+ // the helper's own parameters are this call's arguments: hmac(secret, body) called as
246
+ // hmac(process.env.PAYMENT_WEBHOOK_SECRET || '', raw) signs with that secret (round 27)
247
+ hmac.via = { fnPath, callPath: call.callPath };
248
+ call.read = true;
249
+ break;
250
+ }
251
+ bodyNames.delete(param.name);
252
+ scopePath = h.path;
253
+ }
254
+ }
255
+ // the other functions handed the body: what they read and the kinds they branch on are the webhook's too, even
256
+ // once the HMAC is found (round 27: hmac(...) signs, applyPaymentEvent(payload) acts on payload.type)
257
+ for (const call of helpers) {
258
+ if (call.read || call.name === via) continue;
259
+ const b = call.scope.getBinding(call.name);
260
+ if (!b || !b.path) continue;
261
+ const fnPath = b.path.node.type === 'FunctionDeclaration' ? b.path : b.path.node.type === 'VariableDeclarator' && b.path.node.init && /Function/.test(b.path.node.init.type) ? b.path.get('init') : null;
262
+ const param = fnPath && fnPath.node.params[call.at];
263
+ if (!param || param.type !== 'Identifier') continue;
264
+ call.read = true;
265
+ bodyNames.add(param.name);
266
+ readFrom(fnPath);
267
+ }
268
+ const known = new Set((fields || []).map((f) => f.name));
269
+ const allFields = (fields || []).slice().concat(destructured.filter((n) => !known.has(n) && (known.add(n), true)).map((n) => ({ name: n, from: 'body' })));
270
+ // no signature header and no HMAC anywhere in the handler: a webhook anyone can send (round 23 carrier, round 25
271
+ // inventory). Not "not tried" - its events are sent with no signature, which is the very thing to find out
272
+ if (!header && !hmac) return { ok: true, open: true, fields: allFields, types: kindsOf(), typeField, why: 'no signature header is read and no HMAC is made in the handler' };
273
+ if (!header) return { ok: false, why: 'the handler makes an HMAC but reads no signature header (looked for a header with sig, hmac or token in its name)' };
274
+ 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)), in itself or in a function of the same file it hands the body to' };
168
275
  const alg = hmac.alg && hmac.alg.type === 'StringLiteral' ? hmac.alg.value.toLowerCase() : null;
169
276
  const enc = hmac.enc && hmac.enc.type === 'StringLiteral' ? hmac.enc.value.toLowerCase() : null;
170
277
  if (!alg || !ALGORITHMS.test(alg)) return { ok: false, why: 'the HMAC algorithm is not a plain name written in the code' };
171
278
  if (enc !== 'hex' && enc !== 'base64') return { ok: false, why: 'the signature is not read out as hex or base64' };
172
- // what is signed: JSON.stringify(req.body), or the raw body
173
- const pay = resolve(hmac.payload);
174
- const payChain = pay && chainOf(pay);
175
- const stringifies = pay && pay.type === 'CallExpression' && (chainOf(pay.callee) || []).join('.') === 'JSON.stringify' && (chainOf(pay.arguments[0]) || []).join('.') === req + '.body';
176
- const rawBody = payChain && payChain[0] === req && /^(rawBody|body)$/.test(payChain[1] || '') && payChain.length === 2;
177
- 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' };
279
+ // what is signed: the bytes of the body, in any of the spellings isPayload knows
280
+ const pay = resolve(hmac.payload, 3, hmac.payloadScope);
281
+ const stringifies = pay && pay.type === 'CallExpression' && (chainOf(pay.callee) || []).join('.') === 'JSON.stringify';
282
+ if (!isPayload(pay)) 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' };
178
283
  // the secret
179
- const key = resolve(hmac.key);
284
+ let key = resolve(hmac.key, 3, hmac.keyScope);
285
+ if (hmac.via && key && key.type === 'Identifier') {
286
+ const at = hmac.via.fnPath.node.params.findIndex((q) => q.type === 'Identifier' && q.name === key.name);
287
+ const arg = at >= 0 ? hmac.via.callPath.node.arguments[at] : null;
288
+ if (arg) key = resolve(arg, 3, hmac.via.callPath);
289
+ }
180
290
  let secret = null;
181
291
  const envName = (n) => { const c = n && chainOf(n); return c && c[0] === 'process' && c[1] === 'env' && c[2] ? c[2] : null; };
182
292
  if (key && key.type === 'LogicalExpression' && /^(\|\||\?\?)$/.test(key.operator)) {
@@ -185,17 +295,32 @@ function readSigning(parser, root, route, fields) {
185
295
  } else if (envName(key)) secret = { env: envName(key), fallback: null };
186
296
  else if (key && key.type === 'StringLiteral') secret = { env: null, fallback: key.value };
187
297
  if (!secret) return { ok: false, why: 'the secret is not process.env.NAME or a plain string in the code' };
188
- 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' };
298
+ return { ok: true, header, algorithm: alg, encoding: enc, secret, fields: allFields, types: kindsOf(), typeField, signs: stringifies ? 'JSON.stringify(req.body)' : 'the raw body', via };
189
299
  }
190
300
 
191
- /** Which body field is which, from names. { id, type, record, amount, currency, others } or why not. */
192
- function shapeOf(fields) {
301
+ /**
302
+ * Which body field is which, from names. { id, type, record, amount, currency, others } or why not.
303
+ * `loose` (the run): a body with no type field, or with only an owner id (organization_id), is still a shape -
304
+ * its record then comes from the list whose items carry its fields.
305
+ */
306
+ function shapeOf(fields, opts) {
307
+ if (opts && opts.loose) {
308
+ const names = fields.map((f) => f.name);
309
+ const type = names.find((n) => TYPE_NAME.test(n));
310
+ const id = names.find((n) => ID_NAME.test(n) && n !== type);
311
+ const amount = names.find((n) => AMOUNT_NAME.test(n));
312
+ const currency = names.find((n) => CURRENCY_NAME.test(n));
313
+ const record = names.find((n) => n !== id && n !== type && n !== amount && !OWNER_ID.test(n) && (/_?id$/i.test(n) || /ref$/i.test(n) || /Id$/.test(n)));
314
+ return { ok: true, id, type, record, amount, currency };
315
+ }
193
316
  const names = fields.map((f) => f.name);
194
317
  const type = names.find((n) => TYPE_NAME.test(n));
195
318
  const id = names.find((n) => ID_NAME.test(n) && n !== type);
196
319
  const amount = names.find((n) => AMOUNT_NAME.test(n));
197
320
  const currency = names.find((n) => CURRENCY_NAME.test(n));
198
- const record = names.find((n) => n !== id && n !== type && n !== amount && (/_?id$/i.test(n) || /ref$/i.test(n) || /Id$/.test(n)));
321
+ // org_id names whose records these are, not the record itself (round 26: org_id before delivery_id)
322
+ const recordLike = names.filter((n) => n !== id && n !== type && n !== amount && (/_?id$/i.test(n) || /ref$/i.test(n) || /Id$/.test(n)));
323
+ const record = recordLike.find((n) => !OWNER_ID.test(n)) || recordLike[0];
199
324
  if (!type) return { ok: false, why: 'no field of the body names the kind of event (event_type, type, event ...)' };
200
325
  if (!record) return { ok: false, why: 'no field of the body names the record the event is about (return_id, order_id ...)' };
201
326
  return { ok: true, id, type, record, amount, currency };
@@ -231,6 +356,8 @@ const listOf = (json) => {
231
356
 
232
357
  /** The words of the order a status runs in: what has been paid or approved before a refund. */
233
358
  const PAID = /approv|paid|captur|complet|process|settl|success|confirm/i;
359
+ // an event type no handler acts on: what an app should answer for it, signed, is "taken"; unsigned, refused
360
+ const NEUTRAL = 'kryptheon.test';
234
361
  const REFUNDED = /refund/i;
235
362
 
236
363
  /**
@@ -275,40 +402,96 @@ async function run(root, options) {
275
402
  const bodyFields = ((route.validation && route.validation.fields) || []).filter((f) => f.from === 'body');
276
403
  const signing = readSigning(parser, root, route, bodyFields);
277
404
  if (!signing.ok) { hook.notTried = signing.why; continue; }
278
- 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 };
279
- const secret = (signing.secret.env && appEnv[signing.secret.env]) || signing.secret.fallback;
280
- if (!secret) { hook.notTried = 'the secret ' + signing.secret.env + ' is not in the app\'s .env, and the code has no fallback'; continue; }
281
- // whatever the app answers is cleaned of it before anything is said
282
- if (!ctx.secrets.includes(secret)) ctx.secrets.push(secret);
283
- const shape = shapeOf(bodyFields);
284
- if (!shape.ok) { hook.notTried = shape.why; continue; }
405
+ // open: the handler checks no signature at all, so every event is sent with none (round 23 carrier, round 25 inventory)
406
+ const open = !!signing.open;
407
+ let secret = null;
408
+ if (open) hook.signing = { open: true };
409
+ else {
410
+ 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 };
411
+ secret = (signing.secret.env && appEnv[signing.secret.env]) || signing.secret.fallback;
412
+ if (!secret) { hook.notTried = 'the secret ' + signing.secret.env + ' is not in the app\'s .env, and the code has no fallback'; continue; }
413
+ // whatever the app answers is cleaned of it before anything is said
414
+ if (!ctx.secrets.includes(secret)) ctx.secrets.push(secret);
415
+ }
416
+ const shape = shapeOf(signing.fields, { loose: true });
417
+ // a kind compared on a parsed copy of the body (round 22: event.event) is still the body's own field
418
+ if (!shape.type && signing.typeField) shape.type = signing.typeField;
285
419
  const types = signing.types.slice(0, MAX_TYPES);
286
- 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; }
287
- // the records an event is about: the app's own list of them, as the signed-in account sees it
288
- const resource = wordsOf(shape.record)[0];
289
- 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));
290
- if (!listRoute) { hook.notTried = 'the app has no list of ' + resource + 's (GET /...' + resource + 's) to read the effect of an event from'; continue; }
291
- const readList = async () => {
292
- const res = await reader.send('GET', listRoute.path, {});
420
+ // the records an event is about: the app's own list of them, as the signed-in account sees it -
421
+ // named by the record field (order_id: /orders), else by the webhook's own path (/webhooks/payment: /payments),
422
+ // else the list whose items carry the most of the fields the handler reads (sku, location_code: /stock)
423
+ const lists = (plan.map.routes || []).filter((r) => r.method === 'GET' && !r.unmounted && r.path && !/[:{*]/.test(r.path) && !/(^|\/)(me|whoami|session|profile|account|health)$/i.test(r.path));
424
+ const listFor = (word) => lists.find((r) => new RegExp('(^|/)' + word.replace(/y$/, '(y|ie)') + '(s|es)?$', 'i').test(r.path));
425
+ const recordWords = shape.record ? wordsOf(shape.record).filter((w) => w !== 'id') : [];
426
+ // a record named in two words is looked for whole first: work_order_id -> /work-orders (round 27)
427
+ const joined = recordWords.length > 1 ? [recordWords.join('[-_]?')] : [];
428
+ const words = joined.concat(recordWords, wordsOf(route.path).filter((w) => !/^(api|v\d+|webhooks?|hooks?|events?)$/.test(w)));
429
+ const found = words.find((w) => listFor(w));
430
+ let listRoute = found ? listFor(found) : null;
431
+ let resource = found ? (found.includes('[') ? recordWords.join(' ') : found) : (shape.record ? wordsOf(shape.record)[0] : 'record');
432
+ const fetchList = async (r) => {
433
+ const res = await reader.send('GET', r.path, {});
293
434
  return res.status === 200 ? listOf(res.json) : null;
294
435
  };
295
- const items0 = await readList();
296
- if (!items0 || !items0.length) { hook.notTried = 'GET ' + listRoute.path + ' answered no records to aim an event at'; continue; }
297
- const records = items0.filter((it) => it && it.id !== undefined);
436
+ let items0 = listRoute ? await fetchList(listRoute) : null;
437
+ if (!listRoute) {
438
+ const own = signing.fields.map((f) => f.name).filter((n) => n !== shape.id && n !== shape.type && !OWNER_ID.test(n));
439
+ let best = null;
440
+ for (const r of lists.slice(0, 8)) {
441
+ const items = await fetchList(r);
442
+ const n = items && items[0] && typeof items[0] === 'object' ? own.filter((f) => f in items[0]).length : 0;
443
+ if (n >= 2 && (!best || n > best.n)) best = { r, items, n };
444
+ }
445
+ if (best) { listRoute = best.r; items0 = best.items; resource = wordsOf(best.r.path).filter((w) => w !== 'api').slice(-1)[0].replace(/s$/, ''); }
446
+ }
447
+ // no list to read an effect from: the events are still sent, and judged by what the app answers (never confirmed)
448
+ const records = items0 && items0.length ? items0.filter((it) => it && it.id !== undefined) : [];
449
+ if (!records.length) records.push({ id: null });
450
+ const readList = async () => (listRoute ? fetchList(listRoute) : null);
298
451
  const amountKey = records[0] && Object.keys(records[0]).find((k) => AMOUNT_NAME.test(k));
299
452
  const statusKey = records[0] && Object.keys(records[0]).find((k) => /^status$|^state$/i.test(k));
300
- hook.list = listRoute.path;
453
+ hook.list = listRoute ? listRoute.path : null;
301
454
 
302
455
  const used = new Set();
303
- const nextRecord = (want) => records.find((r) => !used.has(r.id) && (!statusKey || !REFUNDED.test(String(r[statusKey]))) && (!want || want(r)));
456
+ // a fresh record first; when the list is short (two payments, say), one already used rather than no try at all
457
+ const nextRecord = (want) => records.find((r) => !used.has(r.id) && (!statusKey || !REFUNDED.test(String(r[statusKey]))) && (!want || want(r))) ||
458
+ records.find((r) => (!statusKey || !REFUNDED.test(String(r[statusKey]))) && (!want || want(r)));
304
459
  // a refund event is tried first on a record nobody has paid or approved: the case it should refuse
305
460
  const unpaidFor = (type) => (REFUNDED.test(type) && statusKey ? (r) => !PAID.test(String(r[statusKey])) : null);
461
+ // an owner id the event names that its record does not carry (round 26: org_id, not in GET /api/deliveries):
462
+ // the signed-in account's own, from its "who am I"
463
+ const owned = {};
464
+ const meRoute = (plan.map.routes || []).find((r) => r.method === 'GET' && !r.unmounted && r.path && /(^|\/)(me|whoami|session|profile|account)$/i.test(r.path));
465
+ const missing = signing.fields.filter((f) => OWNER_ID.test(f.name) && !records.some((r) => r[f.name] !== undefined && r[f.name] !== null));
466
+ if (missing.length && meRoute) {
467
+ const me = await reader.send('GET', meRoute.path, {});
468
+ const seek = (o, key, depth) => {
469
+ if (!o || typeof o !== 'object' || depth > 3) return undefined;
470
+ if (o[key] !== undefined && o[key] !== null && typeof o[key] !== 'object') return o[key];
471
+ for (const k of Object.keys(o)) { const v = seek(o[k], key, depth + 1); if (v !== undefined) return v; }
472
+ return undefined;
473
+ };
474
+ for (const f of missing) { const v = me.status === 200 ? seek(me.json, f.name, 0) : undefined; if (v !== undefined) owned[f.name] = v; }
475
+ }
306
476
  const bodyFor = (type, rec, amount) => {
307
477
  const b = {};
308
478
  if (shape.id) b[shape.id] = 'kx-evt-' + crypto.randomBytes(5).toString('hex');
309
- b[shape.type] = type;
310
- b[shape.record] = rec.id;
311
- if (shape.amount) b[shape.amount] = amount !== undefined ? amount : amountKey ? rec[amountKey] : 1;
479
+ if (shape.type) b[shape.type] = type;
480
+ else if (type === NEUTRAL) b.event = type;
481
+ // the record's own value when its list carries the field (provider_order_id), else its id
482
+ if (shape.record && rec.id !== null) b[shape.record] = rec[shape.record] !== undefined && rec[shape.record] !== null ? rec[shape.record] : rec.id;
483
+ // a status the event sets: one another record has, so the change can be seen (round 23: carrier status)
484
+ for (const f of signing.fields) {
485
+ if (b[f.name] !== undefined || !/^(status|state)$/i.test(f.name) || rec[f.name] === undefined) continue;
486
+ const other = records.find((r) => r[f.name] !== undefined && r[f.name] !== null && r[f.name] !== rec[f.name]);
487
+ b[f.name] = other ? other[f.name] : 'kryptheon-test';
488
+ }
489
+ // every other field the handler reads that the record carries too (org_id): an event names what it is about
490
+ for (const f of signing.fields) if (b[f.name] === undefined && f.name !== shape.amount && rec[f.name] !== undefined && rec[f.name] !== null) b[f.name] = rec[f.name];
491
+ // a quantity the event moves by (round 25: quantity_delta): 1, so the record changes
492
+ for (const f of signing.fields) if (b[f.name] === undefined && /quantity|qty|delta/i.test(f.name)) b[f.name] = 1;
493
+ for (const k of Object.keys(owned)) if (b[k] === undefined) b[k] = owned[k];
494
+ if (shape.amount) b[shape.amount] = amount !== undefined ? amount : amountKey ? Number(rec[amountKey]) : 1;
312
495
  return b;
313
496
  };
314
497
  const post = async (mode, body) => {
@@ -328,35 +511,88 @@ async function run(root, options) {
328
511
  const after = await readList();
329
512
  const was = before && before.find((x) => x.id === rec.id);
330
513
  const now = after && after.find((x) => x.id === rec.id);
331
- const changed = !!(was && now && JSON.stringify(stableItem(was)) !== JSON.stringify(stableItem(now)));
514
+ const [sw, sn] = [stableItem(was), stableItem(now)];
515
+ const fields = was && now ? Object.keys(Object.assign({}, sw, sn)).filter((k) => JSON.stringify(sw[k]) !== JSON.stringify(sn[k])) : [];
516
+ const changed = fields.length > 0;
332
517
  const took = reply.kind === 'accepted' || reply.kind === 'redirect';
333
- 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 };
518
+ const t = { mode, label: label || mode, type, record: rec.id, status: res.status, took, changed, fields, from: was && statusKey ? was[statusKey] : null, to: now && statusKey ? now[statusKey] : null };
334
519
  Object.defineProperty(t, 'body', { value: body, enumerable: false }); // sent again as it was, never printed
335
520
  hook.tried.push(t);
336
521
  if (changed) out.left.push(name + ' ' + (label || mode) + ' ' + type + ' for ' + resource + ' ' + rec.id + (t.from !== null ? ': ' + statusKey + ' ' + t.from + ' -> ' + t.to : ' changed it'));
337
- 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');
522
+ else if (took) out.left.push(name + ' ' + (label || mode) + ' ' + type + (rec.id !== null ? ' for ' + resource + ' ' + rec.id : '') + ' answered ' + res.status + (listRoute ? ' (no change seen in ' + listRoute.path + ')' : '') + '; the event id is in the app\'s webhook table');
338
523
  return t;
339
524
  };
340
525
 
341
- // 1. a correctly signed event first: if the app refuses its own, nothing after it means anything
342
- say('Sending a correctly signed ' + types[0] + ' to ' + name + ' first...');
343
- const first = nextRecord(unpaidFor(types[0])) || nextRecord();
526
+ // 1. a correctly signed event first: if the app refuses its own, nothing after it means anything.
527
+ // Open (no signature checked at all): the first event goes with none, and is itself the finding if it is taken.
528
+ const S = open ? 'none' : 'signed';
529
+ const ctypes = types.length ? types : [NEUTRAL];
530
+ say('Sending ' + (open ? 'an unsigned' : 'a correctly signed') + ' ' + ctypes[0] + ' to ' + name + ' first...');
531
+ const first = nextRecord(unpaidFor(ctypes[0])) || nextRecord();
344
532
  if (!first) { hook.notTried = 'no record left to aim an event at'; continue; }
345
- const control = await attempt('signed', types[0], first, undefined, 'signed');
533
+ let control = await attempt(S, ctypes[0], first, undefined, open ? 'unsigned' : 'signed');
534
+ // a refusal can be the record's state, not the signature (round 26: "captured" sent to a failed payment is 409):
535
+ // the same type at the other records, then the next type, three sends at most - a refusal changes nothing
536
+ const refusals = [control];
537
+ for (const type of ctypes) {
538
+ for (const rec of records) {
539
+ if (control.took || refusals.length >= 3) break;
540
+ if (refusals.some((t) => t.type === type && t.record === rec.id) || (statusKey && REFUNDED.test(String(rec[statusKey])))) continue;
541
+ control = await attempt(S, type, rec, undefined, open ? 'unsigned' : 'signed');
542
+ refusals.push(control);
543
+ }
544
+ }
545
+ // every real event refused, or none could be built (round 22: Razorpay's nested body): a signed event of a type
546
+ // no handler acts on. Taken, it shows the signature is made right - and the same event unsigned or wrongly
547
+ // signed then shows whether the app checks it before anything else (round 22 checked the length only)
548
+ if (!control.took && !open && ctypes[0] !== NEUTRAL) {
549
+ const neutral = await attempt('signed', NEUTRAL, first, undefined, 'signed');
550
+ refusals.push(neutral);
551
+ if (neutral.took) control = neutral;
552
+ }
346
553
  hook.control = control;
554
+ hook.neutral = control.type === NEUTRAL && !open;
347
555
  if (!control.took) {
348
- 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';
556
+ hook.notTried = 'the app refused even ' + (open ? 'an event sent with no signature (it may check one in a way this check cannot see)' : 'a correctly signed event') + ' (' + refusals.map((t) => t.type + (t.record !== null ? ' for ' + resource + ' ' + t.record : '') + ': ' + t.status).join('; ') + '), so either the signature is made differently from how the code reads, or the event needs more than ' + Object.keys(bodyFor(ctypes[0], first)).join(', ') + ': nothing after it would mean anything';
349
557
  continue;
350
558
  }
351
559
  // 2. the very same event again - same id, same signature - as a provider does when it is not sure it was taken
352
- const replay = await attempt('signed', types[0], first, undefined, 'signed again (same event)', control.body);
353
- void replay;
560
+ const controlRec = records.find((r) => r.id === control.record) || first;
561
+ await attempt(S, control.type, controlRec, undefined, (open ? 'sent' : 'signed') + ' again (same event)', control.body);
562
+ // the event the app just took, as a new event: with no signature, and with a wrong one - so a refusal can only be the signature
563
+ const fresh = () => Object.assign({}, control.body, shape.id ? { [shape.id]: 'kx-evt-' + crypto.randomBytes(5).toString('hex') } : {});
564
+ if (!open) {
565
+ await attempt('none', control.type, controlRec, undefined, 'unsigned', fresh());
566
+ await attempt('wrong', control.type, controlRec, undefined, 'wrong signature', fresh());
567
+ }
568
+ // the payment event the app took, signed, for 100 more than the record's amount - at the record that can take it
569
+ // (round 26: the next record was a failed payment, which refuses any capture for its state, not its amount)
570
+ // a capture-kind event, even when the control was another kind (round 27: payment.created took the control); at the
571
+ // control's record first, then the others, until one takes a capture at all - a refusal for its state says nothing
572
+ const CAPTURE = /captur|charge|paid|success/i;
573
+ const captureType = shape.amount && amountKey ? (!REFUNDED.test(control.type) && CAPTURE.test(control.type) ? control.type : signing.types.find((t) => !REFUNDED.test(t) && CAPTURE.test(t))) : null;
574
+ const payControl = !!captureType;
575
+ if (captureType) {
576
+ for (const rec of [controlRec].concat(records.filter((r) => r !== controlRec)).slice(0, 3)) {
577
+ const t = await attempt(S, captureType, rec, (Number(rec[amountKey]) || 0) + 100, 'signed, wrong amount');
578
+ if (t.took) break;
579
+ }
580
+ }
581
+ // a refund on a record that was paid: sent twice as the same event, then for more than was paid
582
+ const refundType = types.find((t) => REFUNDED.test(t)) || signing.types.find((t) => REFUNDED.test(t));
583
+ const paidRec = refundType && statusKey && records.find((r) => PAID.test(String(r[statusKey])) && !REFUNDED.test(String(r[statusKey])));
584
+ if (paidRec && shape.amount) {
585
+ const small = await attempt(S, refundType, paidRec, 1, 'signed refund');
586
+ if (small.took) await attempt(S, refundType, paidRec, 1, (open ? 'sent' : 'signed') + ' again (same event)', small.body);
587
+ const paidKey = Object.keys(paidRec).find((k) => /captur|paid/i.test(k) && AMOUNT_NAME.test(k)) || amountKey;
588
+ const paid = Number(paidRec[paidKey]) || 0;
589
+ if (paid > 0) await attempt(S, refundType, paidRec, paid * 2, 'signed, refund above what was paid');
590
+ }
354
591
  // the tries, in the order that tells the most when records run out
355
592
  const cases = [];
356
- for (const type of types) cases.push({ mode: 'none', type, label: 'unsigned' });
357
- cases.push({ mode: 'wrong', type: types[0], label: 'wrong signature' });
358
593
  for (const type of types.slice(1)) cases.push({ mode: 'signed', type, label: 'signed' });
359
- 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; }
594
+ for (const type of types) cases.push({ mode: 'none', type, label: 'unsigned' });
595
+ if (shape.amount && amountKey && !payControl) 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; }
360
596
  for (const c of cases) {
361
597
  if (opts.stopped && opts.stopped()) break;
362
598
  if (hook.tried.length >= MAX_TRIES) break;
@@ -364,7 +600,7 @@ async function run(root, options) {
364
600
  if (!rec) break;
365
601
  let amount;
366
602
  if (c.wrongAmount) amount = (Number(rec[amountKey]) || 0) + 100;
367
- await attempt(c.mode, c.type, rec, amount, c.label);
603
+ await attempt(open ? 'none' : c.mode, c.type, rec, amount, open ? 'unsigned' : c.label);
368
604
  }
369
605
 
370
606
  // judged
@@ -374,26 +610,38 @@ async function run(root, options) {
374
610
  hook.findings.push(f);
375
611
  out.findings.push(f);
376
612
  };
377
- 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');
613
+ const seen = listRoute ? ' in GET ' + listRoute.path : ' (the app has no list to read it from)';
614
+ // a body with no type field: what was sent is "an event", not the placeholder type
615
+ const shown = (t) => (t.type === NEUTRAL && !shape.type ? 'an event' : t.type);
616
+ const lineOf = (t) => t.label + ' ' + shown(t) + (t.record !== null ? ' for ' + resource + ' ' + t.record : '') + ': answered ' + t.status + (t.changed ? ', and ' + (t.from !== null && t.from !== t.to ? statusKey + ' went ' + t.from + ' -> ' + t.to : (t.fields || []).join(', ') + ' changed') + seen : t.took ? ', nothing changed' + seen : ', refused');
378
617
  for (const t of hook.tried) {
379
- // the first signed event is a control for the signature, but what it did is judged like any other signed event
380
- if (t === control && !(t.changed && REFUNDED.test(String(t.to)) && t.from !== null && !PAID.test(String(t.from)))) continue;
618
+ // the first signed event is a control for the signature, but what it did is judged like any other signed event;
619
+ // in an open webhook the first event already went with no signature
620
+ if (t === control && t.mode !== 'none' && !(t.changed && REFUNDED.test(String(t.to)) && t.from !== null && !PAID.test(String(t.from)))) continue;
621
+ // the same event again comes first: in an open webhook it also went unsigned, but taking it twice is what it shows
622
+ if (/ again \(same event\)$/.test(t.label) && t.took && t.changed) {
623
+ finding('webhook-replay', 'HIGH', 'confirmed',
624
+ name + ' took the same ' + shown(t) + ' a second time - same event id' + (open ? '' : ', same signature') + ' - and changed ' + resource + ' ' + t.record + ' again.',
625
+ ['The ' + (open ? '' : 'correctly signed ') + 'event, sent again unchanged: ' + lineOf(t)], 'Keep the id of every event you have handled, with a unique rule on it, and answer 200 without doing anything when the same id comes again. Providers resend events whenever they are not sure the first was taken.');
626
+ continue;
627
+ }
381
628
  if (t.mode === 'none' && t.took) {
382
629
  finding('webhook-unsigned', t.changed ? 'CRITICAL' : 'HIGH', t.changed ? 'confirmed' : 'verification required',
383
- 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 + '.',
384
- ['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.');
630
+ t.changed ? name + ' took ' + shown(t) + ' with no signature at all and changed ' + resource + ' ' + t.record + (t.from !== null && t.from !== t.to ? ' (' + statusKey + ' ' + t.from + ' -> ' + t.to + ')' : ' (' + t.fields.join(', ') + ')') + ': anyone who can reach it can send one.' : name + ' answered ' + t.status + ' to ' + shown(t) + ' with no signature, though no change was seen' + seen + '.',
631
+ [(open ? 'With nobody signed in, and no signature - the handler reads none: ' : 'With nobody signed in and no ' + signing.header + ' header: ') + lineOf(t)],
632
+ open ? 'This webhook checks no signature at all. Have the sender sign each event (an HMAC of the exact raw body with a shared secret, in a header) and answer 401 before anything is saved when the signature is missing or wrong, using a timing-safe compare.' : '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.');
385
633
  } else if (t.mode === 'wrong' && t.took) {
386
634
  finding('webhook-forged', t.changed ? 'CRITICAL' : 'HIGH', t.changed ? 'confirmed' : 'verification required',
387
635
  name + ' took ' + t.type + ' with a wrong signature' + (t.changed ? ' and changed ' + resource + ' ' + t.record : '') + '.',
388
636
  ['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.');
389
637
  } else if (t.label === 'signed, wrong amount' && t.took && t.changed) {
390
638
  finding('webhook-amount', 'HIGH', 'confirmed',
391
- name + ' applied ' + t.type + ' for an amount that is not ' + resource + ' ' + t.record + '\'s: the status changed all the same.',
639
+ name + ' applied ' + t.type + ' for an amount that is not ' + resource + ' ' + t.record + '\'s, and it changed all the same (' + (t.from !== t.to ? statusKey + ' ' + t.from + ' -> ' + t.to : t.fields.join(', ')) + ').',
392
640
  ['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.');
393
- } else if (t.label === 'signed again (same event)' && t.took && t.changed) {
394
- finding('webhook-replay', 'HIGH', 'confirmed',
395
- name + ' took the same ' + t.type + ' a second time - same event id, same signature - and changed ' + resource + ' ' + t.record + ' again.',
396
- ['The correctly signed event, sent again unchanged: ' + lineOf(t)], 'Keep the id of every event you have handled, with a unique rule on it, and answer 200 without doing anything when the same id comes again. Providers resend events whenever they are not sure the first was taken.');
641
+ } else if (t.label === 'signed, refund above what was paid' && t.took && t.changed) {
642
+ finding('webhook-refund-over', 'HIGH', 'confirmed',
643
+ name + ' applied a ' + t.type + ' for twice what ' + resource + ' ' + t.record + ' was paid, and the record changed: a refund larger than the payment was taken.',
644
+ ['Correctly signed, with the refund amount twice the amount paid: ' + lineOf(t)], 'Before applying a refund, add up the refunds already made for this ' + resource + ' and refuse one that would take the total above what was actually paid (captured); refuse a refund for something that was never paid at all.');
397
645
  } else if (t.mode === 'signed' && t.label === 'signed' && t.changed && REFUNDED.test(String(t.to)) && t.from !== null && !PAID.test(String(t.from))) {
398
646
  finding('webhook-lifecycle', 'MEDIUM', 'verification required',
399
647
  name + ' marked ' + resource + ' ' + t.record + ' as ' + t.to + ' from ' + t.from + ': a refund event for something nobody had paid or approved.',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "kryptheon",
3
- "version": "0.1.58",
3
+ "version": "0.1.61",
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",