kryptheon 0.1.58 → 0.1.62

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,20 @@ 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
+ // the helper call being read now: a call found inside it is that call's child, so a secret can be followed back
168
+ // through each of them to the handler (round 28: hmac(secret, raw) -> signBody(secret, body) -> createHmac)
169
+ let reading = null;
170
+ const readFrom = (fnPath) => fnPath.traverse({
134
171
  CallExpression(p) {
135
172
  const n = p.node;
136
173
  const chain = chainOf(n.callee);
@@ -141,20 +178,45 @@ function readSigning(parser, root, route, fields) {
141
178
  const upd = n.callee.object;
142
179
  const mk = upd.callee && upd.callee.type === 'MemberExpression' && upd.callee.property.name === 'update' ? upd.callee.object : null;
143
180
  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] };
181
+ // names are resolved from where they are used: `const raw` inside a try {} is not in the function's own scope
182
+ 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 };
183
+ }
184
+ // helper(req.body, ...): a function of this file that is handed the body (round 26: processPaymentWebhook(req.body || {}, sig);
185
+ // round 23: hmac(raw), where raw = req.rawBody || Buffer.from(JSON.stringify(req.body)) is a second name for it)
186
+ if (n.callee && n.callee.type === 'Identifier') {
187
+ // handed the body, or the body's bytes: sign(raw, key) where raw = JSON.stringify(req.body || {})
188
+ const at = n.arguments.findIndex((a) => isBody(a) || isPayload(resolve(a, 3, p)));
189
+ if (at >= 0) helpers.push({ name: n.callee.name, at, scope: p.scope, callPath: p, parent: reading });
190
+ }
191
+ // ['payment.captured', 'refund.processed'].includes(payload.type), or TYPES.includes(event.type): every kind in
192
+ // the list (round 27)
193
+ if (n.callee && n.callee.type === 'MemberExpression' && !n.callee.computed && n.callee.property.name === 'includes' && n.arguments.length === 1) {
194
+ const subject = n.arguments[0];
195
+ const nm = subject.type === 'Identifier' ? subject.name : (chainOf(subject) || []).slice(-1)[0] || '';
196
+ let list = n.callee.object;
197
+ if (list.type === 'Identifier') {
198
+ const b = p.scope.getBinding(list.name);
199
+ list = b && b.path && b.path.node.type === 'VariableDeclarator' && !b.constantViolations.length ? b.path.node.init : null;
200
+ }
201
+ if (TYPE_NAME.test(nm) && list && list.type === 'ArrayExpression' && list.elements.length && list.elements.every((e) => e && e.type === 'StringLiteral')) {
202
+ for (const e of list.elements) listed.add(e.value);
203
+ typeField = typeField || nm;
204
+ }
145
205
  }
146
206
  },
147
207
  MemberExpression(p) {
148
208
  const chain = chainOf(p.node);
149
209
  if (chain && chain[0] === req && chain[1] === 'headers' && chain[2] && SIG_HEADER.test(chain[2]) && !header) header = chain[2].toLowerCase();
210
+ // payload.amount, where payload is the body or a second name for it: a field the webhook reads (round 27)
211
+ 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
212
  },
151
213
  BinaryExpression(p) {
152
214
  const n = p.node;
153
215
  if (!/^[!=]==?$/.test(n.operator)) return;
154
216
  const [a, b] = [n.left, n.right];
155
217
  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);
218
+ if (b.type === 'StringLiteral' && TYPE_NAME.test(name(a))) { literals.add(b.value); typeField = typeField || name(a); }
219
+ if (a.type === 'StringLiteral' && TYPE_NAME.test(name(b))) { literals.add(a.value); typeField = typeField || name(b); }
158
220
  },
159
221
  SwitchStatement(p) {
160
222
  const d = p.node.discriminant;
@@ -162,21 +224,77 @@ function readSigning(parser, root, route, fields) {
162
224
  if (!TYPE_NAME.test(nm)) return;
163
225
  for (const c of p.node.cases) if (c.test && c.test.type === 'StringLiteral') literals.add(c.test.value);
164
226
  },
227
+ VariableDeclarator(p) {
228
+ // const event = req.body || {} - a second name for the body (round 25)
229
+ if (p.node.id.type === 'Identifier' && p.node.init && p.node.init.type !== 'Identifier' && isBody(p.node.init)) bodyNames.add(p.node.id.name);
230
+ // const { event_id, amount } = body - the fields, when the map could not see them (they are read in a helper)
231
+ 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);
232
+ },
165
233
  });
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))' };
234
+ readFrom(h.path);
235
+ let via = null;
236
+ if (!hmac) {
237
+ for (const call of helpers) {
238
+ const b = call.scope.getBinding(call.name);
239
+ if (!b || !b.path) continue;
240
+ 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;
241
+ const param = fnPath && fnPath.node.params[call.at];
242
+ if (!param || param.type !== 'Identifier') continue;
243
+ bodyNames.add(param.name);
244
+ scopePath = fnPath;
245
+ call.fnPath = fnPath;
246
+ reading = call;
247
+ readFrom(fnPath);
248
+ reading = null;
249
+ if (hmac) {
250
+ via = call.name;
251
+ // the helper's own parameters are this call's arguments: hmac(secret, body) called as
252
+ // hmac(process.env.PAYMENT_WEBHOOK_SECRET || '', raw) signs with that secret (round 27)
253
+ hmac.via = call;
254
+ call.read = true;
255
+ break;
256
+ }
257
+ bodyNames.delete(param.name);
258
+ scopePath = h.path;
259
+ }
260
+ }
261
+ // the other functions handed the body: what they read and the kinds they branch on are the webhook's too, even
262
+ // once the HMAC is found (round 27: hmac(...) signs, applyPaymentEvent(payload) acts on payload.type)
263
+ for (const call of helpers) {
264
+ if (call.read || call.name === via) continue;
265
+ const b = call.scope.getBinding(call.name);
266
+ if (!b || !b.path) continue;
267
+ 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;
268
+ const param = fnPath && fnPath.node.params[call.at];
269
+ if (!param || param.type !== 'Identifier') continue;
270
+ call.read = true;
271
+ bodyNames.add(param.name);
272
+ readFrom(fnPath);
273
+ }
274
+ const known = new Set((fields || []).map((f) => f.name));
275
+ const allFields = (fields || []).slice().concat(destructured.filter((n) => !known.has(n) && (known.add(n), true)).map((n) => ({ name: n, from: 'body' })));
276
+ // no signature header and no HMAC anywhere in the handler: a webhook anyone can send (round 23 carrier, round 25
277
+ // inventory). Not "not tried" - its events are sent with no signature, which is the very thing to find out
278
+ 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' };
279
+ 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)' };
280
+ 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
281
  const alg = hmac.alg && hmac.alg.type === 'StringLiteral' ? hmac.alg.value.toLowerCase() : null;
169
282
  const enc = hmac.enc && hmac.enc.type === 'StringLiteral' ? hmac.enc.value.toLowerCase() : null;
170
283
  if (!alg || !ALGORITHMS.test(alg)) return { ok: false, why: 'the HMAC algorithm is not a plain name written in the code' };
171
284
  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' };
285
+ // what is signed: the bytes of the body, in any of the spellings isPayload knows
286
+ const pay = resolve(hmac.payload, 3, hmac.payloadScope);
287
+ const stringifies = pay && pay.type === 'CallExpression' && (chainOf(pay.callee) || []).join('.') === 'JSON.stringify';
288
+ 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
289
  // the secret
179
- const key = resolve(hmac.key);
290
+ let key = resolve(hmac.key, 3, hmac.keyScope);
291
+ // a parameter of the helper is the argument of its call, and that may be a parameter of the helper around it
292
+ for (let step = hmac.via; step && key && key.type === 'Identifier'; step = step.parent) {
293
+ const at = step.fnPath.node.params.findIndex((q) => q.type === 'Identifier' && q.name === key.name);
294
+ const arg = at >= 0 ? step.callPath.node.arguments[at] : null;
295
+ if (!arg) break;
296
+ key = resolve(arg, 3, step.callPath);
297
+ }
180
298
  let secret = null;
181
299
  const envName = (n) => { const c = n && chainOf(n); return c && c[0] === 'process' && c[1] === 'env' && c[2] ? c[2] : null; };
182
300
  if (key && key.type === 'LogicalExpression' && /^(\|\||\?\?)$/.test(key.operator)) {
@@ -185,17 +303,32 @@ function readSigning(parser, root, route, fields) {
185
303
  } else if (envName(key)) secret = { env: envName(key), fallback: null };
186
304
  else if (key && key.type === 'StringLiteral') secret = { env: null, fallback: key.value };
187
305
  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' };
306
+ 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
307
  }
190
308
 
191
- /** Which body field is which, from names. { id, type, record, amount, currency, others } or why not. */
192
- function shapeOf(fields) {
309
+ /**
310
+ * Which body field is which, from names. { id, type, record, amount, currency, others } or why not.
311
+ * `loose` (the run): a body with no type field, or with only an owner id (organization_id), is still a shape -
312
+ * its record then comes from the list whose items carry its fields.
313
+ */
314
+ function shapeOf(fields, opts) {
315
+ if (opts && opts.loose) {
316
+ const names = fields.map((f) => f.name);
317
+ const type = names.find((n) => TYPE_NAME.test(n));
318
+ const id = names.find((n) => ID_NAME.test(n) && n !== type);
319
+ const amount = names.find((n) => AMOUNT_NAME.test(n));
320
+ const currency = names.find((n) => CURRENCY_NAME.test(n));
321
+ 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)));
322
+ return { ok: true, id, type, record, amount, currency };
323
+ }
193
324
  const names = fields.map((f) => f.name);
194
325
  const type = names.find((n) => TYPE_NAME.test(n));
195
326
  const id = names.find((n) => ID_NAME.test(n) && n !== type);
196
327
  const amount = names.find((n) => AMOUNT_NAME.test(n));
197
328
  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)));
329
+ // org_id names whose records these are, not the record itself (round 26: org_id before delivery_id)
330
+ const recordLike = names.filter((n) => n !== id && n !== type && n !== amount && (/_?id$/i.test(n) || /ref$/i.test(n) || /Id$/.test(n)));
331
+ const record = recordLike.find((n) => !OWNER_ID.test(n)) || recordLike[0];
199
332
  if (!type) return { ok: false, why: 'no field of the body names the kind of event (event_type, type, event ...)' };
200
333
  if (!record) return { ok: false, why: 'no field of the body names the record the event is about (return_id, order_id ...)' };
201
334
  return { ok: true, id, type, record, amount, currency };
@@ -231,6 +364,8 @@ const listOf = (json) => {
231
364
 
232
365
  /** The words of the order a status runs in: what has been paid or approved before a refund. */
233
366
  const PAID = /approv|paid|captur|complet|process|settl|success|confirm/i;
367
+ // an event type no handler acts on: what an app should answer for it, signed, is "taken"; unsigned, refused
368
+ const NEUTRAL = 'kryptheon.test';
234
369
  const REFUNDED = /refund/i;
235
370
 
236
371
  /**
@@ -275,40 +410,96 @@ async function run(root, options) {
275
410
  const bodyFields = ((route.validation && route.validation.fields) || []).filter((f) => f.from === 'body');
276
411
  const signing = readSigning(parser, root, route, bodyFields);
277
412
  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; }
413
+ // open: the handler checks no signature at all, so every event is sent with none (round 23 carrier, round 25 inventory)
414
+ const open = !!signing.open;
415
+ let secret = null;
416
+ if (open) hook.signing = { open: true };
417
+ else {
418
+ 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 };
419
+ secret = (signing.secret.env && appEnv[signing.secret.env]) || signing.secret.fallback;
420
+ if (!secret) { hook.notTried = 'the secret ' + signing.secret.env + ' is not in the app\'s .env, and the code has no fallback'; continue; }
421
+ // whatever the app answers is cleaned of it before anything is said
422
+ if (!ctx.secrets.includes(secret)) ctx.secrets.push(secret);
423
+ }
424
+ const shape = shapeOf(signing.fields, { loose: true });
425
+ // a kind compared on a parsed copy of the body (round 22: event.event) is still the body's own field
426
+ if (!shape.type && signing.typeField) shape.type = signing.typeField;
285
427
  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, {});
428
+ // the records an event is about: the app's own list of them, as the signed-in account sees it -
429
+ // named by the record field (order_id: /orders), else by the webhook's own path (/webhooks/payment: /payments),
430
+ // else the list whose items carry the most of the fields the handler reads (sku, location_code: /stock)
431
+ 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));
432
+ const listFor = (word) => lists.find((r) => new RegExp('(^|/)' + word.replace(/y$/, '(y|ie)') + '(s|es)?$', 'i').test(r.path));
433
+ const recordWords = shape.record ? wordsOf(shape.record).filter((w) => w !== 'id') : [];
434
+ // a record named in two words is looked for whole first: work_order_id -> /work-orders (round 27)
435
+ const joined = recordWords.length > 1 ? [recordWords.join('[-_]?')] : [];
436
+ const words = joined.concat(recordWords, wordsOf(route.path).filter((w) => !/^(api|v\d+|webhooks?|hooks?|events?)$/.test(w)));
437
+ const found = words.find((w) => listFor(w));
438
+ let listRoute = found ? listFor(found) : null;
439
+ let resource = found ? (found.includes('[') ? recordWords.join(' ') : found) : (shape.record ? wordsOf(shape.record)[0] : 'record');
440
+ const fetchList = async (r) => {
441
+ const res = await reader.send('GET', r.path, {});
293
442
  return res.status === 200 ? listOf(res.json) : null;
294
443
  };
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);
444
+ let items0 = listRoute ? await fetchList(listRoute) : null;
445
+ if (!listRoute) {
446
+ const own = signing.fields.map((f) => f.name).filter((n) => n !== shape.id && n !== shape.type && !OWNER_ID.test(n));
447
+ let best = null;
448
+ for (const r of lists.slice(0, 8)) {
449
+ const items = await fetchList(r);
450
+ const n = items && items[0] && typeof items[0] === 'object' ? own.filter((f) => f in items[0]).length : 0;
451
+ if (n >= 2 && (!best || n > best.n)) best = { r, items, n };
452
+ }
453
+ if (best) { listRoute = best.r; items0 = best.items; resource = wordsOf(best.r.path).filter((w) => w !== 'api').slice(-1)[0].replace(/s$/, ''); }
454
+ }
455
+ // no list to read an effect from: the events are still sent, and judged by what the app answers (never confirmed)
456
+ const records = items0 && items0.length ? items0.filter((it) => it && it.id !== undefined) : [];
457
+ if (!records.length) records.push({ id: null });
458
+ const readList = async () => (listRoute ? fetchList(listRoute) : null);
298
459
  const amountKey = records[0] && Object.keys(records[0]).find((k) => AMOUNT_NAME.test(k));
299
460
  const statusKey = records[0] && Object.keys(records[0]).find((k) => /^status$|^state$/i.test(k));
300
- hook.list = listRoute.path;
461
+ hook.list = listRoute ? listRoute.path : null;
301
462
 
302
463
  const used = new Set();
303
- const nextRecord = (want) => records.find((r) => !used.has(r.id) && (!statusKey || !REFUNDED.test(String(r[statusKey]))) && (!want || want(r)));
464
+ // a fresh record first; when the list is short (two payments, say), one already used rather than no try at all
465
+ const nextRecord = (want) => records.find((r) => !used.has(r.id) && (!statusKey || !REFUNDED.test(String(r[statusKey]))) && (!want || want(r))) ||
466
+ records.find((r) => (!statusKey || !REFUNDED.test(String(r[statusKey]))) && (!want || want(r)));
304
467
  // a refund event is tried first on a record nobody has paid or approved: the case it should refuse
305
468
  const unpaidFor = (type) => (REFUNDED.test(type) && statusKey ? (r) => !PAID.test(String(r[statusKey])) : null);
469
+ // an owner id the event names that its record does not carry (round 26: org_id, not in GET /api/deliveries):
470
+ // the signed-in account's own, from its "who am I"
471
+ const owned = {};
472
+ const meRoute = (plan.map.routes || []).find((r) => r.method === 'GET' && !r.unmounted && r.path && /(^|\/)(me|whoami|session|profile|account)$/i.test(r.path));
473
+ const missing = signing.fields.filter((f) => OWNER_ID.test(f.name) && !records.some((r) => r[f.name] !== undefined && r[f.name] !== null));
474
+ if (missing.length && meRoute) {
475
+ const me = await reader.send('GET', meRoute.path, {});
476
+ const seek = (o, key, depth) => {
477
+ if (!o || typeof o !== 'object' || depth > 3) return undefined;
478
+ if (o[key] !== undefined && o[key] !== null && typeof o[key] !== 'object') return o[key];
479
+ for (const k of Object.keys(o)) { const v = seek(o[k], key, depth + 1); if (v !== undefined) return v; }
480
+ return undefined;
481
+ };
482
+ for (const f of missing) { const v = me.status === 200 ? seek(me.json, f.name, 0) : undefined; if (v !== undefined) owned[f.name] = v; }
483
+ }
306
484
  const bodyFor = (type, rec, amount) => {
307
485
  const b = {};
308
486
  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;
487
+ if (shape.type) b[shape.type] = type;
488
+ else if (type === NEUTRAL) b.event = type;
489
+ // the record's own value when its list carries the field (provider_order_id), else its id
490
+ if (shape.record && rec.id !== null) b[shape.record] = rec[shape.record] !== undefined && rec[shape.record] !== null ? rec[shape.record] : rec.id;
491
+ // a status the event sets: one another record has, so the change can be seen (round 23: carrier status)
492
+ for (const f of signing.fields) {
493
+ if (b[f.name] !== undefined || !/^(status|state)$/i.test(f.name) || rec[f.name] === undefined) continue;
494
+ const other = records.find((r) => r[f.name] !== undefined && r[f.name] !== null && r[f.name] !== rec[f.name]);
495
+ b[f.name] = other ? other[f.name] : 'kryptheon-test';
496
+ }
497
+ // every other field the handler reads that the record carries too (org_id): an event names what it is about
498
+ 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];
499
+ // a quantity the event moves by (round 25: quantity_delta): 1, so the record changes
500
+ for (const f of signing.fields) if (b[f.name] === undefined && /quantity|qty|delta/i.test(f.name)) b[f.name] = 1;
501
+ for (const k of Object.keys(owned)) if (b[k] === undefined) b[k] = owned[k];
502
+ if (shape.amount) b[shape.amount] = amount !== undefined ? amount : amountKey ? Number(rec[amountKey]) : 1;
312
503
  return b;
313
504
  };
314
505
  const post = async (mode, body) => {
@@ -328,35 +519,97 @@ async function run(root, options) {
328
519
  const after = await readList();
329
520
  const was = before && before.find((x) => x.id === rec.id);
330
521
  const now = after && after.find((x) => x.id === rec.id);
331
- const changed = !!(was && now && JSON.stringify(stableItem(was)) !== JSON.stringify(stableItem(now)));
522
+ const [sw, sn] = [stableItem(was), stableItem(now)];
523
+ const fields = was && now ? Object.keys(Object.assign({}, sw, sn)).filter((k) => JSON.stringify(sw[k]) !== JSON.stringify(sn[k])) : [];
524
+ const changed = fields.length > 0;
332
525
  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 };
526
+ 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
527
  Object.defineProperty(t, 'body', { value: body, enumerable: false }); // sent again as it was, never printed
335
528
  hook.tried.push(t);
336
529
  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');
530
+ 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
531
  return t;
339
532
  };
340
533
 
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();
534
+ // 1. a correctly signed event first: if the app refuses its own, nothing after it means anything.
535
+ // Open (no signature checked at all): the first event goes with none, and is itself the finding if it is taken.
536
+ const S = open ? 'none' : 'signed';
537
+ // With an amount to try and at most one record left that a capture could still land on, the control is a kind that
538
+ // neither captures nor refunds, so the wrong amount has somewhere to go (round 28: one payment per organization,
539
+ // and a captured control left none). With more records the order stays (round 26 refuses payment.created).
540
+ const CAPTURE = /captur|charge|paid|success/i;
541
+ const capturable = records.filter((r) => r.id !== null && (!statusKey || !(CAPTURE.test(String(r[statusKey])) || REFUNDED.test(String(r[statusKey])))));
542
+ const plain = shape.amount && amountKey && capturable.length <= 1 ? types.find((t) => !REFUNDED.test(t) && !CAPTURE.test(t)) : null;
543
+ const ctypes = types.length ? (plain ? [plain].concat(types.filter((t) => t !== plain)) : types) : [NEUTRAL];
544
+ say('Sending ' + (open ? 'an unsigned' : 'a correctly signed') + ' ' + ctypes[0] + ' to ' + name + ' first...');
545
+ const first = nextRecord(unpaidFor(ctypes[0])) || nextRecord();
344
546
  if (!first) { hook.notTried = 'no record left to aim an event at'; continue; }
345
- const control = await attempt('signed', types[0], first, undefined, 'signed');
547
+ let control = await attempt(S, ctypes[0], first, undefined, open ? 'unsigned' : 'signed');
548
+ // a refusal can be the record's state, not the signature (round 26: "captured" sent to a failed payment is 409):
549
+ // the same type at the other records, then the next type, three sends at most - a refusal changes nothing
550
+ const refusals = [control];
551
+ // a plain control refused (round 26 refuses payment.created for the record's state): the usual order then, with the
552
+ // usual three sends besides it
553
+ const order = plain && !control.took ? types : ctypes;
554
+ const budget = plain && !control.took ? 4 : 3;
555
+ for (const type of order) {
556
+ for (const rec of records) {
557
+ if (control.took || refusals.length >= budget) break;
558
+ if (refusals.some((t) => t.type === type && t.record === rec.id) || (statusKey && REFUNDED.test(String(rec[statusKey])))) continue;
559
+ control = await attempt(S, type, rec, undefined, open ? 'unsigned' : 'signed');
560
+ refusals.push(control);
561
+ }
562
+ }
563
+ // every real event refused, or none could be built (round 22: Razorpay's nested body): a signed event of a type
564
+ // no handler acts on. Taken, it shows the signature is made right - and the same event unsigned or wrongly
565
+ // signed then shows whether the app checks it before anything else (round 22 checked the length only)
566
+ if (!control.took && !open && ctypes[0] !== NEUTRAL) {
567
+ const neutral = await attempt('signed', NEUTRAL, first, undefined, 'signed');
568
+ refusals.push(neutral);
569
+ if (neutral.took) control = neutral;
570
+ }
346
571
  hook.control = control;
572
+ hook.neutral = control.type === NEUTRAL && !open;
347
573
  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';
574
+ 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
575
  continue;
350
576
  }
351
577
  // 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;
578
+ const controlRec = records.find((r) => r.id === control.record) || first;
579
+ await attempt(S, control.type, controlRec, undefined, (open ? 'sent' : 'signed') + ' again (same event)', control.body);
580
+ // 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
581
+ const fresh = () => Object.assign({}, control.body, shape.id ? { [shape.id]: 'kx-evt-' + crypto.randomBytes(5).toString('hex') } : {});
582
+ if (!open) {
583
+ await attempt('none', control.type, controlRec, undefined, 'unsigned', fresh());
584
+ await attempt('wrong', control.type, controlRec, undefined, 'wrong signature', fresh());
585
+ }
586
+ // the payment event the app took, signed, for 100 more than the record's amount - at the record that can take it
587
+ // (round 26: the next record was a failed payment, which refuses any capture for its state, not its amount)
588
+ // a capture-kind event, even when the control was another kind (round 27: payment.created took the control); at the
589
+ // control's record first, then the others, until one takes a capture at all - a refusal for its state says nothing
590
+ 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;
591
+ const payControl = !!captureType;
592
+ if (captureType) {
593
+ for (const rec of [controlRec].concat(records.filter((r) => r !== controlRec)).slice(0, 3)) {
594
+ const t = await attempt(S, captureType, rec, (Number(rec[amountKey]) || 0) + 100, 'signed, wrong amount');
595
+ if (t.took) break;
596
+ }
597
+ }
598
+ // a refund on a record that was paid: sent twice as the same event, then for more than was paid
599
+ const refundType = types.find((t) => REFUNDED.test(t)) || signing.types.find((t) => REFUNDED.test(t));
600
+ const paidRec = refundType && statusKey && records.find((r) => PAID.test(String(r[statusKey])) && !REFUNDED.test(String(r[statusKey])));
601
+ if (paidRec && shape.amount) {
602
+ const small = await attempt(S, refundType, paidRec, 1, 'signed refund');
603
+ if (small.took) await attempt(S, refundType, paidRec, 1, (open ? 'sent' : 'signed') + ' again (same event)', small.body);
604
+ const paidKey = Object.keys(paidRec).find((k) => /captur|paid/i.test(k) && AMOUNT_NAME.test(k)) || amountKey;
605
+ const paid = Number(paidRec[paidKey]) || 0;
606
+ if (paid > 0) await attempt(S, refundType, paidRec, paid * 2, 'signed, refund above what was paid');
607
+ }
354
608
  // the tries, in the order that tells the most when records run out
355
609
  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
610
  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; }
611
+ for (const type of types) cases.push({ mode: 'none', type, label: 'unsigned' });
612
+ 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
613
  for (const c of cases) {
361
614
  if (opts.stopped && opts.stopped()) break;
362
615
  if (hook.tried.length >= MAX_TRIES) break;
@@ -364,7 +617,7 @@ async function run(root, options) {
364
617
  if (!rec) break;
365
618
  let amount;
366
619
  if (c.wrongAmount) amount = (Number(rec[amountKey]) || 0) + 100;
367
- await attempt(c.mode, c.type, rec, amount, c.label);
620
+ await attempt(open ? 'none' : c.mode, c.type, rec, amount, open ? 'unsigned' : c.label);
368
621
  }
369
622
 
370
623
  // judged
@@ -374,26 +627,38 @@ async function run(root, options) {
374
627
  hook.findings.push(f);
375
628
  out.findings.push(f);
376
629
  };
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');
630
+ const seen = listRoute ? ' in GET ' + listRoute.path : ' (the app has no list to read it from)';
631
+ // a body with no type field: what was sent is "an event", not the placeholder type
632
+ const shown = (t) => (t.type === NEUTRAL && !shape.type ? 'an event' : t.type);
633
+ 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
634
  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;
635
+ // the first signed event is a control for the signature, but what it did is judged like any other signed event;
636
+ // in an open webhook the first event already went with no signature
637
+ if (t === control && t.mode !== 'none' && !(t.changed && REFUNDED.test(String(t.to)) && t.from !== null && !PAID.test(String(t.from)))) continue;
638
+ // the same event again comes first: in an open webhook it also went unsigned, but taking it twice is what it shows
639
+ if (/ again \(same event\)$/.test(t.label) && t.took && t.changed) {
640
+ finding('webhook-replay', 'HIGH', 'confirmed',
641
+ name + ' took the same ' + shown(t) + ' a second time - same event id' + (open ? '' : ', same signature') + ' - and changed ' + resource + ' ' + t.record + ' again.',
642
+ ['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.');
643
+ continue;
644
+ }
381
645
  if (t.mode === 'none' && t.took) {
382
646
  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.');
647
+ 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 + '.',
648
+ [(open ? 'With nobody signed in, and no signature - the handler reads none: ' : 'With nobody signed in and no ' + signing.header + ' header: ') + lineOf(t)],
649
+ 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
650
  } else if (t.mode === 'wrong' && t.took) {
386
651
  finding('webhook-forged', t.changed ? 'CRITICAL' : 'HIGH', t.changed ? 'confirmed' : 'verification required',
387
652
  name + ' took ' + t.type + ' with a wrong signature' + (t.changed ? ' and changed ' + resource + ' ' + t.record : '') + '.',
388
653
  ['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
654
  } else if (t.label === 'signed, wrong amount' && t.took && t.changed) {
390
655
  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.',
656
+ 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
657
  ['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.');
658
+ } else if (t.label === 'signed, refund above what was paid' && t.took && t.changed) {
659
+ finding('webhook-refund-over', 'HIGH', 'confirmed',
660
+ 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.',
661
+ ['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
662
  } else if (t.mode === 'signed' && t.label === 'signed' && t.changed && REFUNDED.test(String(t.to)) && t.from !== null && !PAID.test(String(t.from))) {
398
663
  finding('webhook-lifecycle', 'MEDIUM', 'verification required',
399
664
  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.62",
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",